Algorithms

WebAuthn Algorithms

The cryptographic algorithm used to generate a public keypair during a FIDO2/WebAuthn registration is determined by the capabilities of the FIDO2 Authenticator and the preferences of the Relying Party (RP). The allowed algorithms are defined in the pubKeyCredParams section.

The COSE Algorithms registry contains definitions of all possible algorithms that can be used. This is enforced due to some transports, such as Bluetooth or NFC, having restrictions in data bandwidth that make transmission of JSON files problematic. To avoid this issue, FIDO2 interactions must be capable of being translated to the CBOR format, including the algorithms utilized.

The RP will further narrow down the supported algorithms, depending on which are supported on the FIDO2 server. For example, in Yubico’s python-fido2 server, the supported algorithms include ES256, RS256, PS256, and EdDSA. At registration, the supported algorithms for the public key (pubKeyCredParams) must be presented as either a JSON or CBOR format.

Sample JSON pubKeyCredParams:

{
// This Relying Party will accept either an ES256 or RS256 credential, but
  // prefers an ES256 credential.
  pubKeyCredParams: [
    {
      type: "public-key",
      alg: -7 // "ES256" as registered in the IANA COSE Algorithms registry
    },
    {
      type: "public-key",
      alg: -257 // Value registered by this specification for "RS256"
    }
  ],
}

Sample CBOR pubKeyCredParams:

{
82                                              # array(2)
    a2                                          # map(2)
        63                                      # text(3)
            616c67                              # "alg"
        26                                      # -7 (ES256)
        64                                      # text(4)
            74797065                            # "type"
        6a                                      # text(10)
            7075626C69632D6B6579                # "public-key"
    a2                                          # map(2)
        63                                      # text(3)
            616c67                              # "alg"
        390100                                  # -257 (RS256)
        64                                      # text(4)
            74797065                            # "type"
        6a                                      # text(10)
            7075626C69632D6B6579                # "public-key"
}

The order in which the algorithms are listed by the RP will define the priority of the algorithm to be used.

The authenticator will also have a subset of algorithms it supports for generating a public keypair. When generating a new public keypair during registration, the authenticator does not offer a prioritization of algorithms to be used; the algorithm with the highest priority set by the RP will be selected. The CTAP2 command, authenticatorGetInfo, can be used to list the algorithms supported on an authenticator, should more information be required. YubiKeys currently support RS256 (Firmware 5.1.X and below only), EdDSA, ES256, and Ed25519 (Firmware 5.2.X and above only).

If the pubKeyCredParams parameter does not contain a valid COSEAlgorithmIdentifier value that is supported by the authenticator, the registration event will fail with the error code CTAP2_ERR_UNSUPPORTED_ALGORITHM.

When defining the supported algorithms and prioritizing them, we recommend supporting at minimum ES256 and RS256. ES256 is supported on the vast majority of FIDO2 Authenticator devices, like the YubiKey, while most platform-based FIDO2 Authenticators include support for RS256.

Next: Platform vs Cross-Platform