WebAuthn pubKeyCredParams & credentialPublicKey: CBOR & COSE

1. Introduction: pubKeyCredParams & credentialPublicKey

2. What is Public-Key Cryptography?

    2.1 How Does Public-Key Cryptography Work?

    2.2 Common Types of Public-Key Cryptography Algorithms

    2.3 Increasing Adoption of ECC-based Public Cryptography

3. WebAuthn: How is Public-Key Cryptography Used within Passkeys?

4. How to Choose Correct pubKeyCredParams Settings?

    4.1 Which COSE Algorithms are Relevant for WebAuthn?

    4.2 Defining pubKeyCredParams-Array in pubKeyCredParams

5. How to Extract the Public Key from attestationObject?

    5.1 Overview: What is the attestationObject?

      5.2 What is Concise Binary Object Representation (CBOR)?

      5.3 What is COSE Key Format?

      5.4 Decoding and Parsing the attestationObject

6. Recommendation

7. Conclusion

In digital security, passkeys are the new passwordless standard. At the heart of passkeys lies public-key cryptography, utilized within the WebAuthn protocol on which passkeys are based. Understanding how public-key cryptography is used in WebAuthn, particularly in creating, extracting, managing and storing passkeys, is crucial when designing or using passkey authentication. The public key is stored on the server of the relying party (RP), which is the backend of the website that wants to authenticate a user via passkeys, and the private key is securely stored in a Hardware Security Module depending on the operating system Secure Enclave (iOS), TEE (Android) or a TPM (Windows).

In this blog post, we will go quickly over the basics of public-key cryptography used in passkeys. The following questions should be answered by the end of the blog post:

• Which encryption algorithms are supported in WebAuthn
• How do pubKeyCredParams work when creating a key pair?
• How do credentialPublicKey work when extracting the created public keys?

To understand how public-key cryptography works within WebAuthn, we will take a quick look into how it works in general and what the common types of algorithms are.

Public-key cryptography, also known as asymmetric cryptography, stands in contrast to symmetric cryptography where the same key is used for both encryption and decryption. Asymmetric cryptography employs two distinct keys – a public key, which can be shared openly, and a private key, which is kept secret by the owner.

Taken from: https://en.wikipedia.org/wiki/Public-key_cryptography

This method enables not only the encryption of data to secure its confidentiality but also allows to sign messages. Signing verifies the sender's identity and ensures that the message has not been tampered with, thereby confirming its authenticity and integrity.

Subscribe to our Passkeys Substack for the latest news, insights and strategies.

Subscribe

Here's an overview of some common types of algorithms used in public key cryptography:

The mathematical foundation of elliptic curve cryptography (ECC), including ECDSA and EdDSA, involves the properties of elliptic curves which we will not cover in this article. But it is obvious from the table above, that there are advantages that drive their adoption. We will go through the most important ones in the next section.

Become part of our Passkeys Community for updates and support.

Join

Elliptic curve cryptography has been widely adopted for mobile devices as they benefit from the smaller key sizes, which brings the following advantages:

• Reduced Storage Requirements: ECC’s smaller keys require less storage space compared to traditional cryptographic methods like RSA. This is especially beneficial for devices with limited memory resources, allowing for more efficient use of space. The following table shows an approximation of comparable security levels and the actual sizes of the keys used. The security level is measured in bits and usually corresponds to a symmetric key cipher of that size:

The term security level in this context refers to the strength of the cryptographic system, specifically the level of difficulty for an attacker to defeat the security measures. It is generally measured in bits and represents the amount of work (the number of operations) that would be required to break the encryption or forge a signature. With increasing security level, the size advantages become obvious up to key ratio sizes of 1:30.

• Enhanced Performance: The smaller keys enable faster cryptographic operations, which is crucial for devices with lower processing power. This results in quicker encryption and decryption activities, boosting the overall performance and responsiveness of mobile applications. Depending on the type of benchmarks the speed ups range from 10-40x in execution. Here is an example of benchmark data that AWS conducted when implementing ECDSA for Cloudfront in 2018:

• Improved Battery Efficiency: With more efficient processing from smaller keys, ECC operations can consume less power. This conservation of energy is vital for mobile devices, where preserving battery life is a constant challenge.

These factors make ECC particularly suitable for mobile environments, where the optimization of storage, processing speed, and power consumption is essential. As a result, ECC is increasingly favored in mobile computing for its ability to provide robust security without compromising device performance. Nevertheless, up to today a lot of older versions of widespread protocols like TLS (used for HTTPS, FTPS or SMTPS), SSH or IPsec exist that still support RSA but have started to offer ECC-based variants to clients that support them.

The WebAuthn standard is not an encryption standard, but rather a security protocol that provides strong, public-key-based authentication for web applications, enabling users to log in using biometrics, mobile devices, or hardware security keys (e.g. YubiKeys) instead of passwords. Therefore, WebAuthn is intentionally agnostic which underlying which public-key based cryptography is actually used, let’s take a look how this is accomplished.

The WebAuthn security protocol facilitates the cryptographic secure authentication between the User and the Relying Party. In technical terms this means that the Relying Party (a website that wants to use passkeys with its users) needs to exchange keys over the browser with the user and his authenticator which then stores the private key in the specific hardware security module (HSM).

For sign-up / registration of passkeys, there are three important steps:

• (1) The Relying Party signals supported encryption algorithms: The relying party signals supported encryption algorithms via PublicKeyCredentialCreationOptions.pubKeyCredParams together with the other PublicKeyCredentialCreationOptions.
• (2) The Authenticator of the user creates the key-pair: The authenticator checks the pubKeyCredParams list for encryption algorithms that it supports and creates a key-pair alongside with a unique Credential ID. It stores the private key within the HSM and then returns the public-key and the used encryption-algorithm to the browser. Then, the browser sends a POST request to the Relying Party backend with the attestationObject in the “authData” section. In case there is no match of the supported encryption algorithms, the create ceremony will fail.
• (3) The Relying Party extracts the public-key and stores it: The relying party receives the attestationObject from the browser. It parses the authData.credentialPublicKey section and extracts the public-key. Together with the public-key also information about the used encryption algorithm and the Credential ID is sent back to the relying party.

For subsequent login / authentication with passkeys, the following steps are necessary (details simplified):

• (1) The Relying Party presents a challenge: The relying party generates a random challenge and provides it to the authenticator for signature.
• (2) The Authenticator of the user signs the challenge: The Authenticator signs the challenge with the key that matches the authentication request and returns it with the Credential ID to the Relying Party.
• (3) The Relying Party validates the signature: The Relying Party receives the information and looks up the public key associated with the Credential ID used. It then cryptographically validates the signature using the encryption/signature algorithm agreed upon during the registration of the passkeys.

By looking at both cases, we can see that only for sign-up / registration of passkeys public-key and encryption algorithm information are transported between the actors.

For subsequent login / authentication events with passkeys, only the challenge and the signature are part of the transmitted data.

The WebAuthn standard uses the IANA COSE Algorithm IDs to identify the encryption algorithms used. The COSE Algorithm IDs are both used for signaling the supported algorithms in pubKeyCredParams and to transmit the actually created key-pair type in credentialPublicKey. We will focus on their implementation in the next two sections.

The COSE Algorithms list of IANA includes over 75 algorithms that could theoretically be used with the WebAuthn Standard. Most of the algorithms with negative ID are asymmetric public-key and most of the positive symmetric, but this is rather a convention as there are exceptions to that

As we have pointed out before, the encryption algorithm needs to be supported by the Authenticator and the Relying Party backend in order be used in the WebAuthn ceremony. As most relying parties use existing WebAuthn libraries that have access to a wide range of encryption algorithms, it is more important to look at which algorithms are supported by which authenticators:

(*) = Small portion of security keys (e.g. Yubikeys 5+, Solokey or Nitrokey)
Excerpt from IANA Table: See full list here

As you can see from this table, to support all important authenticators RS256 and ES256 are sufficient. There are some parts of the community that recommend integrating also EdDSA to further improve security. On the other side, the Credential IDs that also need to be stored seem to be significantly longer for EdDSA keys. As of today, the W3C Editor’s draft on the upcoming Level 3 WebAuthn Standard suggest all three algorithms.

Configuring the supported encryption algorithms for the passkey creation is done via the PublicKeyCredentialCreationOptions:

const publicKeyCredentialCreationOptions = {
  challenge: "*",
  rp: {
    name: "Corbado",
    id: "corbado.com",
  },
  user: {
    id: "user-X",
    name: "user@corbado.com",
    displayName: "Corbado Name",
  },
  pubKeyCredParams: [
    {
      alg: -8,
      type: "public-key"
    },
    {
      alg: -7,
      type: "public-key"
    },
    {
      alg: -257,
      type: "public-key"
    },
  ],
  authenticatorSelection: {
    authenticatorAttachment: "platform",
    requireResidentKey: true,
  }
};
 
const credential = await navigator.credentials.create({
  publicKey: publicKeyCredentialCreationOptions
});

The example shows how the algorithms are specified within: pubKeyCredParams by alg for the ID and adding public-key as type of the algorithm. In line 29/30, the PublicKeyCredentialCreationOptions are passed to the authenticator via the WebAuthn API of the browser. Removing support for ES256 or RS256 will produce errors and is strictly not recommended.

As a working example, we will run the following PublicKeyCredentialCreationOptions on a Mac in the Passkeys Debugger.

{
    "rp": {
        "id": "www.passkeys-debugger.io",
        "name": "Relying Party Name"
    },
    "challenge": "AAABeB78HrIemh1jTdJICr_3QG_RMOhp",
    "pubKeyCredParams": [
        {
            "type": "public-key",
            "alg": -8
        },
        {
            "type": "public-key",
            "alg": -7
        },
        {
            "type": "public-key",
            "alg": -257
        }
    ],
    "excludeCredentials": [],
    "timeout": 120000,
    "authenticatorSelection": {
        "residentKey": "required",
        "requireResidentKey": true,
        "userVerification": "required",
        "authenticatorAttachment": "platform"
    },
    "hints": [],
    "attestation": "direct",
    "user": {
        "name": "User-2024-08-19",
        "displayName": "User-2024-08-19",
        "id": "LlakhOS2vobxxwdkInYP-277Atf0S5OsJax_uBCNNINk"
    }
}

The response produced by the authenticator is sent to the relying party (as attestation) and looks like:

{
    "id": "aWMmE4BE9ZzvRKd9rQhdy6ubrlB3COrTRFQANe6ydHg",
    "rawId": "aWMmE4BE9ZzvRKd9rQhdy6ubrlB3COrTRFQANe6ydHg",
    "type": "public-key",
    "response": {
        "attestationObject": "o2NmbXRmcGFja2VkZ2F0dFN0bXSiY2FsZyZjc2lnWEcwRQIhAIvVNCTlYXX7WKOfeto7WyBQE6uvXpvnNy22kqrMxs_QAiAmanFqalrvD_1fe0Cb2f60ljth4nngckkKJ8JPtqZiO2hhdXRoRGF0YVikt8DGRTBfls-BhOH2QC404lvdhe_t2_NkvM0nQWEEADdFAAAAAK3OAAI1vMYKZIsLJfHwVQMAIGljJhOARPWc70Snfa0IXcurm65Qdwjq00RUADXusnR4pQECAyYgASFYIDP4onRKVHXlhwbmWF4V6jmfsuVuSXchGm6xoceSBGtjIlgg3bxZIbKyE7qPczMZmS0jCGBf9cgajs77EZL-gNAjO0c",
        "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiQUFBQmVCNzhIckllbWgxalRkSklDcl8zUUdfUk1PaHAiLCJvcmlnaW4iOiJodHRwczovL29wb3Rvbm5pZWUuZ2l0aHViLmlvIiwiY3Jvc3NPcmlnaW4iOmZhbHNlfQ",
        "transports": [
            "internal"
        ],
        "publicKeyAlgorithm": -7
    },
    "authenticatorAttachment": "platform",
    "clientExtensionResults": {}
}

In the next session, we will see how the public keys and the used encryption algorithm can be extracted from the response.

First of all, we need to examine how the actual attestationObject is constructed, because as we see above it is not transported in JSON to the Relying Party.

The attestationObject plays an important role in the WebAuthn registration process, serving as a container for the attestation statement provided by the authenticator. This object provides a lot of information necessary for the Relying Party (RP) to verify the origin and integrity of the newly created public key credential.

At its core, the attestationObject is a complex structure. It is mostly encoded in CBOR (Concise Binary Object Representation) format, which then at the end is encoded with Base64URL encoding. It encapsulates the authenticator data along with an attestation statement that verifies the information's authenticity. Because passkeys are created with attestation “none” and therefore do not carry an attestation statement, we will not cover this in this article. As a side note: We wrote mostly CBOR because there are also non-standard CBOR prefixes involved due to the variable lengths that are needed for the optional extensions. We will not dive deeper into that, a discussion about the complexities can be found here.

Taken from the WebAuthn specification

Within the authenticator data (authData), the newly generated public key, alongside user’s credential ID, are securely stored and can be retrieved by the relying party. As developers must approach the task of extracting the public key from the attestationObject in any WebAuthn-based system, understanding its architecture is important.

CBOR (Concise Binary Object Representation) is a data format designed to encode data in a compact, efficient, and extensible manner. It is binary, which makes it smaller and faster to parse than its text-based role-model JSON. The following example illustrates how JSON and CBOR are different (Text vs. Binary):

Bold is Name. Italic is Corbado. (more information can be found on https://cbor.io/)

In the context of WebAuthn, CBOR is used for several reasons:

• Link to FIDO2 / CTAP: As CBOR is used in the underlying standards streamlining the parsing and processing of data is achieved, as both WebAuthn and CTAP utilize the same compact encoding scheme.
• Compactness: CBOR’s efficient encoding makes it an excellent choice for web traffic where minimizing data size can significantly impact performance, particularly over mobile networks or in environments where bandwidth is a constraint.
• Flexibility: CBOR supports a variety of data types and structures, including arrays, maps, text strings, byte strings, and tags for extendibility. This makes it versatile enough to handle the different data types and complex structures needed for WebAuthn’s operations.
• Extensibility: The format is designed to be extendable, which means new features can be added to WebAuthn without breaking compatibility with existing implementations.

The use of CBOR is especially fitting for encoding the public keys and the attestationObject because it needs to handle the different formats and lengths we discussed above. For instance, an RSA key would have different attributes and sizes compared to an ECDSA key. Within the attestationObject, public keys are stored in COSE Key format, which is based on CBOR.

A COSE Key structure is built on a CBOR map object. It defines a structured way for key representation, encompassing various key types and their corresponding parameters, such as the RSA modulus and exponent, or the elliptic curve public key coordinates. This standardized format allows keys to be serialized and deserialized in a consistent manner, irrespective of their underlying cryptographic algorithm, in addition to the encryption algorithm ID we have discussed above.

By leveraging CBOR and the COSE Key format, WebAuthn can facilitate a wide range of cryptographic operations while ensuring the payload remains as small as possible, and remain adaptable for future updates in cryptographic technology. This choice aligns with the goals of WebAuthn to provide a secure, efficient, and forward-compatible protocol for web authentication.

When it comes to decoding the attestationObject within WebAuthn, developers are faced with an important decision: develop a custom solution or leverage an established library. The complexity and critical nature of this process cannot be overstated. Manual implementation of Base64URL and CBOR decoding, while technically feasible, introduces the risk of subtle errors that can compromise the integrity of the authentication process.

To ensure the cryptographic verification of the signature, as well as the accuracy of all other validation steps, it is strongly advised to utilize a well-tested and widely adopted WebAuthn library. Such libraries are built with encryption expertise to handle the details of decoding and validating the attestationObject, including:

• Parsing the CBOR format correctly to extract the attestation statement and authenticator data.
• Interpreting the COSE Key format to retrieve the public key.
• Performing cryptographic checks to validate the signature according to the WebAuthn standard.

By relying on a reputable library, developers not only save time and resources but also gain peace of mind. The public key, once extracted and verified through these reliable tools, can then be safely stored in the database, ready to be used for secure authentication sessions. This approach ensures adherence to the protocol’s specifications and maintains the security posture expected in WebAuthn implementations. For simplicity, we will use the SimpleWebauthn Debugger which returns a completely decoded version with CBOR fields being converted into exploded JSON:

{
  "id": "aWMmE4BE9ZzvRKd9rQhdy6ubrlB3COrTRFQANe6ydHg",
  "rawId": "aWMmE4BE9ZzvRKd9rQhdy6ubrlB3COrTRFQANe6ydHg",
  "type": "public-key",
  "response": {
    "attestationObject": {
      "fmt": "packed",
      "attStmt": {
        "alg": "ES256 (-7)",
        "sig": "MEUCIQCL1TQk5WF1-1ijn3raO1sgUBOrr16b5zcttpKqzMbP0AIgJmpxampa7w_9X3tAm9n-tJY7YeJ54HJJCifCT7amYjs"
      },
      "authData": {
        "rpIdHash": "t8DGRTBfls-BhOH2QC404lvdhe_t2_NkvM0nQWEEADc",
        "flags": {
          "userPresent": true,
          "userVerified": true,
          "backupEligible": false,
          "backupStatus": false,
          "attestedData": true,
          "extensionData": false
        },
        "counter": 0,
        "aaguid": "adce0002-35bc-c60a-648b-0b25f1f05503",
        "credentialID": "aWMmE4BE9ZzvRKd9rQhdy6ubrlB3COrTRFQANe6ydHg",
        "credentialPublicKey": "pQECAyYgASFYIDP4onRKVHXlhwbmWF4V6jmfsuVuSXchGm6xoceSBGtjIlgg3bxZIbKyE7qPczMZmS0jCGBf9cgajs77EZL-gNAjO0c",
        "parsedCredentialPublicKey": {
          "keyType": "EC2 (2)",
          "algorithm": "ES256 (-7)",
          "curve": 1,
          "x": "M_iidEpUdeWHBuZYXhXqOZ-y5W5JdyEabrGhx5IEa2M",
          "y": "3bxZIbKyE7qPczMZmS0jCGBf9cgajs77EZL-gNAjO0c"
        }
      }
    },
    "clientDataJSON": {
      "type": "webauthn.create",
      "challenge": "AAABeB78HrIemh1jTdJICr_3QG_RMOhp",
      "origin": "https://opotonniee.github.io",
      "crossOrigin": false
    },
    "transports": [
      "internal"
    ],
    "publicKeyAlgorithm": -7
  },
  "authenticatorAttachment": "platform",
  "clientExtensionResults": {}
}
 

The SimpleWebAuthn library is used to decode the complete attestationObject. As we can see, all information is now readable. All cryptographic information are part of credentialPublicKey which is part of the authData-part. which the library has exploded into the parsedCredentialPublicKey statement. In the specification, there are several examples how COSE Key Format looks like.

{
  "parsedCredentialPublicKey": {
    "keyType": "EC2 (2)",
    "algorithm": "ES256 (-7)",
    "curve": 1,
    "x": "M_iidEpUdeWHBuZYXhXqOZ-y5W5JdyEabrGhx5IEa2M",
    "y": "3bxZIbKyE7qPczMZmS0jCGBf9cgajs77EZL-gNAjO0c"
  }
}

This output showcases all the cryptographic elements of the credentialPublicKey neatly parsed into human-readable form. This particular instance reveals an EC2 key for the ES256 algorithm, as indicated by the algorithm parameter and the presence of x and y coordinates.

In contrast the output of a Windows 10 system looks as follows:

{
  "parsedCredentialPublicKey": {
    "keyType": "RSA (3)",
    "algorithm": "RS256 (-257)",
    "modulus": "mzRVwAL6jbccWT4NQ3rQWEYLkTKkEBeHPPUn0CXT8VwvvGE_IaXDeP9ZzcA7WoX3z6E0l_L-XZmRuKc9cO7BkiYyz3jOg_pNFTz5Ap9a1f_9H0m4mpL-30WHQZi1skB5f6zt8sO8q7rBYH0mRmH8LdCrhJRhVjB_UxbcAbYlpV98M5g-5OBs_boNXtMhMoyp-IOeGChp07wwSLVOH3hKMoxlU27hZ3QvK2LRWosNKhXSHcU9IOC0XOyhlZ5rtPX2ae3KsSE1H2rEJVcMaVMRAg8yx2SRM98pDvf829smrnJPdMBojKftne2j8o84i_xyDJ_jARlyVj0kxR37u0AVQQ",
    "exponent": 65537
  }
}

Here, the algorithm ID is -257, corresponding to RS256, and we can discern that the attributes characterizing this public key diverge significantly from those of an ECDSA key. The COSE Key format allows for specifying unique attributes per type:

Also, the RSA modulus is substantially longer than the elliptic curve coordinates used in the ES256 key, underscoring our previous discussion regarding the differences in key sizes and the inherent requirements of different cryptographic algorithms.

After going through the basics of public-key cryptography and understanding how it is incorporated into the WebAuthn / FIDO2 standard, we have two major recommendations for relying parties:

• Select the right encryption algorithms: In the implementation of WebAuthn, it's important to use the correct algorithms for maximum compatibility. Based on current recommendations a combination of RS256, ES256, and EdDSA is advisable. RS256 and ES256 stand out due to their wide support, and the inclusion of EdDSA may enhance security where possible.
• Use well-tested WebAuthn libraries to extract public-key: Once you've decided on the algorithms, the next step is to integrate a well-tested WebAuthn library. Such a library can competently handle the complexities of parsing * attestationObject*. After the library has extracted the public keys and its associated data it can be safely stored in the database. The format used by the library typically ensures that the key is stored in a way that can be accurately read and utilized for future authentication purposes.

It's crucial not to reinvent the wheel: leverage the collective knowledge embedded within established libraries. Custom implementation risks introducing errors and security flaws that could undermine the authentication's effectiveness and the system's overall security.

In this blog post, we have investigated the basics of public-key cryptography to answer the initial three core questions:

1. Supported Encryption Algorithms in WebAuthn: WebAuthn is designed to be flexible and supports a wide range of encryption algorithms, prominently including RSA (RS256), ECDSA (ES256), and EdDSA. This adaptability allows it to integrate seamlessly with various authenticators and platforms, ensuring broad compatibility.
2. Functionality of pubKeyCredParams in Key Pair Creation: The pubKeyCredParams play an important role in the registration phase of the WebAuthn process by specifying which cryptographic algorithms the relying party supports. This ensures that the key pairs created are compatible with both the user's authenticator and the relying party's requirements.
3. Functionality of credentialPublicKey and Extracting Public Keys: The credentialPublicKey is used to extract public keys from the attestationObject provided by authenticators.

Besides, we have highlighted the WebAuthn protocol's independence from specific encryption algorithms, which significantly enhances its flexibility and future-proofing against emerging cryptographic methods. We hope this article also helps other developers when debugging and understanding concepts / issues related to public-key cryptography in WebAuthn.