0083 XLS-83d: Passkey Signature Support

[intelliot]

Title:       0083 XLS-83d: Passkey Signature Support
Revision:    2 (2024-11-20)
Type:        draft
Authors:     Elliot Lee
             Javi Romero
Affiliation: Ripple

Proposes adding passkey (WebAuthn) support into the XRP Ledger protocol for enhanced security and user experience.

Abstract

This proposal introduces passkey support to the XRP Ledger by adding the ability to verify signatures created as part of a WebAuthn authentication flow. By allowing users to utilize passkeys for transaction authorization, the XRP Ledger can enhance security, improve user experience, and encourage wider adoption through the use of phishing-resistant authentication.

Motivation

As the XRP Ledger continues to grow, there is a need to improve security and user experience for account access and transaction authorization. Traditional key generation and management can be complex and insecure for end-users, leading to potential loss of funds due to mishandling of secret keys or falling victim to phishing attacks. By integrating passkey support using WebAuthn standards, users can leverage device-bound or syncable credentials (passkeys) for secure, convenient, and phishing-resistant authentication.

Specification

This specification focuses on the ability to handle the signature structure and data fields required by passkey authentication. A separate spec, XLS-84d: Support for ES256 on the P-256 curve in Passkey Signatures, covers cryptographic algorithm support.

Overview

This specification proposes the addition of passkey support to the XRP Ledger by:

• Introducing a new signature type to support passkey-based transaction signing.
• Defining how passkey credentials are registered and managed within the ledger.
• Modifying transaction validation to verify signatures created using passkeys.
• Extending support to multi-signature transactions by enabling the addition of passkeys to signer lists.
• Ensuring compatibility with existing accounts and transactions.

Simplified Passkey Signature Implementation

Rationale

Unlike most WebAuthn use cases, the XRP Ledger is a public, permissionless blockchain where security relies on cryptographic signatures proving that a transaction is authorized. To securely integrate passkey (WebAuthn) support into the XRP Ledger, it's essential to align with the WebAuthn specification. This requires including necessary data structures—AuthenticatorData, ClientDataJSON, and PasskeyID—in transactions. These components ensure that signatures produced by passkeys can be properly verified, maintaining the security and integrity of the ledger.

Transaction Format Modifications

Transactions signed using a passkey MUST include the following fields:

• SigningPubKey: The public key associated with the passkey credential.
• PasskeySignature: An object containing the signature and related data necessary for verification.
• TxnSignature: This field MUST be set to an empty string or omitted when using PasskeySignature.

New Field: PasskeySignature

The PasskeySignature field is an object containing the following subfields:

Field Name	Required?	JSON Type	Internal Type
PasskeyID	✔️	string	Blob
AuthenticatorData	✔️	string	Blob
ClientDataJSON	✔️	string	Blob
Signature	✔️	string	Blob
Algorithm	Optional (include if necessary)	number	Int32

• PasskeyID: The identifier of the credential used for signing, as provided by the authenticator.
• AuthenticatorData: The raw bytes of the authenticator data returned during the signing process. It contains information from the authenticator about processing a credential creation or authentication request.
• ClientDataJSON: The JSON-serialized client data used during the signing process.
• Signature: The digital signature produced by the authenticator. The signature signs authenticatorData + SHA256(clientDataJSON). The authenticatorData contains a "counter" that increases each time the credential key is used to authenticate.
• Algorithm: An integer indicating the cryptographic algorithm used by the credential, specified using COSE algorithm identifiers per the WebAuthn specification.

Transaction Fields Summary

Field Name	Required?	JSON Type	Internal Type
TransactionType	✔️	string	UInt16
Account	✔️	string	AccountID
SigningPubKey	✔️	string	Blob
PasskeySignature	✔️	object	Object
TxnSignature	Must be empty or omitted when PasskeySignature is present	string	VariableLength
Sequence	✔️	number	UInt32
Fee	✔️	string	Amount
...	...	...	...

Passkey Registration and Management

New Ledger Entry: PasskeyList

The PasskeyList ledger entry represents a list of registered passkey credentials associated with an account.

Fields

Field Name	Required?	JSON Type	Internal Type
LedgerEntryType	✔️	string	UInt16
Account	✔️	string	AccountID
Passkeys	✔️	array	Array

Passkeys Array Elements

Each element in the Passkeys array represents a registered passkey credential:

Field Name	Required?	JSON Type	Internal Type
PasskeyID	✔️	string	Blob
PublicKey	✔️	string	Blob
SignCount	✔️	number	UInt32
Algorithm	✔️	number	Int32

• Algorithm: An integer indicating the cryptographic algorithm used by the credential, specified using COSE algorithm identifiers per the WebAuthn specification.

New Transaction Type: SetPasskeyList

The SetPasskeyList transaction allows an account owner to add or remove passkey credentials from their PasskeyList.

Fields

Field Name	Required?	JSON Type	Internal Type
TransactionType	✔️	string	UInt16
Account	✔️	string	AccountID
PasskeyActions	✔️	array	Array
Fee	✔️	string	Amount
Sequence	✔️	number	UInt32
SigningPubKey	✔️	string	Blob
TxnSignature	✔️	string	Blob

PasskeyActions Array Elements

Each element specifies an action to add or remove a passkey credential:

Field Name	Required?	JSON Type	Internal Type
Action	✔️	string	UInt8
PasskeyID	✔️	string	Blob
PublicKey	Required if Action is "add"	string	Blob
SignCount	Required if Action is "add"	number	UInt32
Algorithm	Required if Action is "add"	number	Int32

• Action: MUST be either "add" or "remove".

Account Deletion

The PasskeyList object is a deletion blocker. An account cannot be deleted if it has a PasskeyList associated with it. To delete the account, the PasskeyList must first be removed by removing all passkey credentials using the SetPasskeyList transaction.

Processing Rules

• When Action is "add", the transaction MUST add the provided passkey credential to the account's PasskeyList.
• When Action is "remove", the transaction MUST remove the specified credential from the PasskeyList.
• The SetPasskeyList transaction MUST be signed using the account's master key or an existing authorized signer.

Transaction Signing with Passkeys

Modifications to Transaction Validation

When a transaction containing a PasskeySignature is submitted, the server MUST perform the following steps:

1. Credential Lookup: Verify that the PasskeyID in PasskeySignature corresponds to a registered credential in the account's PasskeyList.

2. Extract Algorithm: Retrieve the Algorithm associated with the PasskeyID from the PasskeyList.

3. Reconstruct Client Data Hash: Compute the SHA-256 hash of the ClientDataJSON.

4. Construct Signed Data: Concatenate AuthenticatorData and the ClientDataHash.

5. Verify Signature.

   • Signature Verification: Use the selected algorithm to verify the Signature over the concatenated signed data (AuthenticatorData || SHA-256(ClientDataJSON)) using the PublicKey.

   • Failure Handling: If the algorithm is unsupported or the verification fails, the transaction MUST fail with a temBAD_SIGNATURE error.

6. Validate Challenge: Ensure that the challenge in the ClientDataJSON matches the expected value (the SHA-256 hash of the serialized transaction blob, excluding the TxnSignature and PasskeySignature fields).

7. Prevent Replay Attacks: Compare the SignCount from AuthenticatorData with the stored SignCount for the credential. The SignCount MUST be greater than the stored value. Update the stored SignCount with the new value.

8. Validate Origin (Optional): Servers MAY verify that the origin in ClientDataJSON matches an expected value to enhance security.

Signature Verification Process

The verification MUST follow the WebAuthn Level 2 specification for verifying an authentication assertion. The transaction hash is used as the challenge in the ClientDataJSON, binding the signature to the specific transaction.

Transaction Signing Process

1. Transaction Preparation: The client prepares the transaction as usual, excluding the TxnSignature field.

2. Generate Challenge: Compute the SHA-256 hash of the serialized transaction blob (excluding the TxnSignature and PasskeySignature fields) to be used as the challenge in the WebAuthn authentication flow.

3. Invoke WebAuthn API: Use the WebAuthn API (navigator.credentials.get) with appropriate parameters, including the challenge, to obtain an assertion (AuthenticatorAssertionResponse).

4. Construct PasskeySignature: Extract the AuthenticatorData, ClientDataJSON, Signature, and PasskeyID from the assertion and include them in the PasskeySignature field. Include the Algorithm if necessary.

5. Submit Transaction: Send the transaction with the PasskeySignature field to the XRP Ledger.

Supporting Passkey Signatures in Multi-Signature Transactions

Modifying the Signers.Signer Object

To support passkey signatures in multi-signature transactions, the Signers.Signer object is modified to include the PasskeySignature field, allowing signers to provide a passkey signature instead of a traditional TxnSignature.

Updated Signers.Signer Fields:

Field Name	Required?	JSON Type	Internal Type	Description
Account	✔️	string	AccountID	The address of the signing account.
SigningPubKey	✔️	string	Blob	The public key associated with the credential used for signing.
TxnSignature	Required if PasskeySignature is omitted	string	Blob	The signature of the transaction using traditional cryptographic methods.
PasskeySignature	Required if TxnSignature is omitted	object	Object	Contains the signature and related data necessary for verification when using passkey signatures.

Note: Exactly one of TxnSignature or PasskeySignature MUST be present in each Signer object.

Multi-Signature Transaction Signing Process with Passkeys

1. Transaction Preparation:

   • Prepare the transaction with the Signers array containing one or more Signer objects.
   • Each Signer object represents a signer that contributes a signature to the transaction.

2. Signing with Passkeys:

   • For signers using passkeys, follow the same steps as for individual transactions, using the transaction blob prepared for multi-signature signing.
   • Include the PasskeySignature field within the Signer object instead of TxnSignature.

3. Signing with Traditional Signatures:

   • For signers using traditional methods, include the TxnSignature field within the Signer object.

4. Combined Signature List:

   • The Signers array may contain a mix of signers using TxnSignature and signers using PasskeySignature.

Modifications to Transaction Validation for Multi-Signature Transactions

When validating a multi-signature transaction that includes passkey signatures, the server MUST perform the following steps for each Signer in the Signers array:

1. Verify Signer Structure:

   • Ensure that exactly one of TxnSignature or PasskeySignature is present.

2. Signature Verification:

   • If TxnSignature is present:
     • Verify the signature as per existing multi-signature validation rules.
   • If PasskeySignature is present:
     • Perform passkey signature verification using the transaction blob prepared for multi-signature signing.

3. Check Signing Permissions:

   • Ensure that the signer is authorized according to the SignerList associated with the account.

Passkey Signature Verification Steps in Multi-Signature Context

For each Signer using a passkey signature:

1. Credential Lookup:

   • Verify that the PasskeyID corresponds to a registered credential in the account's PasskeyList.

2. Extract Algorithm:

   • Retrieve the Algorithm associated with the PasskeyID from the PasskeyList.

3. Compute Client Data Hash:

   • Compute the SHA-256 hash of the ClientDataJSON.

4. Construct Signed Data:

   • Concatenate AuthenticatorData and the ClientDataHash.

5. Verify Signature:

   • Use the appropriate algorithm to verify the Signature over the concatenated signed data using the PublicKey.

6. Validate Challenge:

   • Ensure the challenge in ClientDataJSON matches the hash of the multi-signature transaction blob.

7. Prevent Replay Attacks:

   • Verify that the SignCount from AuthenticatorData is greater than the stored SignCount and update it.

8. Check Signing Permissions:

   • Confirm that the signer is listed in the SignerList and contributes towards the quorum.

Example Signers Array with Passkey Signatures

"Signers": [
  {
    "Signer": {
      "Account": "rSigner1Address",
      "SigningPubKey": "publicKey1",
      "PasskeySignature": {
        "PasskeyID": "credentialID1",
        "AuthenticatorData": "authData1",
        "ClientDataJSON": "clientDataJSON1",
        "Signature": "signature1",
        "Algorithm": -7
      }
    }
  },
  {
    "Signer": {
      "Account": "rSigner2Address",
      "SigningPubKey": "publicKey2",
      "TxnSignature": "signature2"
    }
  }
]

Error Handling

• Invalid Signer Structure:

  • If both TxnSignature and PasskeySignature are present, or if neither is present, the transaction MUST fail with a temMALFORMED error.

• Signature Verification Failure:

  • If a passkey signature fails verification, the transaction MUST fail with a temBAD_SIGNATURE error.

• Unauthorized Signer:

  • If a signer is not authorized according to the SignerList, the transaction MUST fail with a tefBAD_AUTH_MASTER error.

Modifications to RPC Methods

Modifying the account_objects RPC Request

To allow clients to retrieve passkey-related ledger objects, the account_objects RPC request is modified to include a passkey option in the type field.

Updated account_objects Request Fields

Field Name	Required?	JSON Type	Description
account	✔️	string	The unique identifier of the account.
type	Optional (defaults to returning all object types)	string	Filters the results to include only objects of the specified type. Possible values include passkey.

Example Request

{
  "method": "account_objects",
  "params": [
    {
      "account": "rExampleAccountAddress",
      "type": "passkey",
      "ledger_index": "validated"
    }
  ]
}

Response Modification

When the type field is set to passkey, the response MUST include only PasskeyList ledger objects associated with the specified account.

Example Response

{
  "result": {
    "account": "rExampleAccountAddress",
    "account_objects": [
      {
        "LedgerEntryType": "PasskeyList",
        "Account": "rExampleAccountAddress",
        "Passkeys": [
          {
            "PasskeyID": "credentialID1",
            "PublicKey": "publicKey1",
            "SignCount": 123,
            "Algorithm": -7
          },
          {
            "PasskeyID": "credentialID2",
            "PublicKey": "publicKey2",
            "SignCount": 456,
            "Algorithm": -8
          }
        ],
        "index": "ledgerObjectIndex"
      }
    ],
    "ledger_hash": "ledgerHash",
    "ledger_index": 12345678,
    "validated": true
  }
}

Account Setup for Passkey Authentication

• Credential Registration: Accounts MUST initialize their PasskeyList using the SetPasskeyList transaction, adding desired passkey credentials along with their corresponding Algorithm (COSE algorithm identifier).

• Authorization: The initial SetPasskeyList transaction MUST be authorized using existing account credentials (e.g., master key or regular key).

• Multiple Credentials: Accounts MAY register multiple passkey credentials, potentially using different algorithms, to allow for backup devices or multiple users.

• Algorithm Consistency: It is important that the Algorithm provided during registration matches the algorithm used by the authenticator for that credential. This ensures correct verification during transaction signing.

Error Handling

• Unregistered Credential: If the PasskeyID is not found in the PasskeyList, the transaction MUST fail with a tecNO_PERMISSION error.

• Invalid Signature: If the signature verification fails, the transaction MUST fail with a temINVALID_SIGNATURE error.

• Unsupported Algorithm: If the Algorithm is not supported by the verifier, the transaction MUST fail with a temBAD_SIGNATURE error.

• Algorithm Mismatch: If the algorithm used in the signature does not match the Algorithm specified in the PasskeyList, the transaction MUST fail with a temBAD_SIGNATURE error.

• Invalid Challenge: If the challenge in the ClientDataJSON does not match the expected value (transaction hash), the transaction MUST fail with a temBAD_SIGNATURE error.

Compliance with WebAuthn Specification

• Algorithm Specification: By using COSE algorithm identifiers for the Algorithm field, the XRPL implementation aligns with the WebAuthn specification.

• Consistency in Verification: This ensures that the verification process can accurately select and apply the correct cryptographic algorithm, as the authenticator and the verifier agree on the algorithm used.

• Reference: See the WebAuthn Level 2 Specification, Sections 5.10.3 (PublicKeyCredentialParameters) and 6.2 (Generating an Authentication Assertion), for details on how algorithms are specified and used.

Handling Different Cryptographic Algorithms

Please see: XLS-84d: Support for ES256 on the P-256 curve in Passkey Signatures

[ximinez]

1. Could this be used for hardware FIDO2 keys like Yubikeys?
2. Signer lists are not deletion blockers. I don't think it makes sense for a Passkey List to be a deletion blocker. Consider the case where an account's master key is compromised, but it has a Passkey List, so the user simply disables the master key, and everything is fine. To then later delete the account, the user would have to add some other signing method (like a regular key or signer list), then delete the Passkey List, then delete the account. Seems like a lot of unnecessary work when the Passkey List is sufficient to sign for other transaction types.
   1. The correct link for the list of account deletion requirements is https://xrpl.org/docs/concepts/accounts/deleting-accounts#requirements

[sappenin]

Could this be used for hardware FIDO2 keys like Yubikeys?

This post make it sound like the answer is "yes":

"YubiKeys have had the ability to create these passwordless enabled FIDO2 credentials (passkeys) since the YubiKey 5 Series became available in mid-2018. Currently, YubiKeys can store a maximum of 25 passkeys. We are evaluating increasing this in the future because of the likely increase in fully passwordless experiences across the web that require them."

[elmurci]

1. Could this be used for hardware FIDO2 keys like Yubikeys?

2. Signer lists are not deletion blockers. I don't think it makes sense for a Passkey List to be a deletion blocker. Consider the case where an account's master key is compromised, but it has a Passkey List, so the user simply disables the master key, and everything is fine. To then later delete the account, the user would have to add some other signing method (like a regular key or signer list), then delete the Passkey List, then delete the account. Seems like a lot of unnecessary work when the Passkey List is sufficient to sign for other transaction types.

   1. The correct link for the list of account deletion requirements is https://xrpl.org/docs/concepts/accounts/deleting-accounts#requirements

1. Yes

[ximinez]

This post make it sound like the answer is "yes":

Nice!

[mvadari]

CredentialID is already used to refer to XLS-70 credentials (and it's also rather confusing). So that name should change.

[intelliot]

The name comes from the W3C spec: https://www.w3.org/TR/webauthn-3/#credential-id

How about PasskeyID?

[mvadari]

Sure

[dangell7]

I'm curious how this makes it more convenient for users if they still have to store a private key?

I'm also curious as to the term unphishable and how it applies here. My keypair, while it could sign other things doesnt really work anywhere else. So is this really a selling point? I do see the idea that they are device specific but also see passkey "syncing" so I'm a bit confused.

I'm also extremely concerned with the idea that some are suggesting sharing the keystore between devices. Wow.

How is this different or more secure then just storing the private key in the hardware keystore on the mobile device and accessing through biometrics?

[elmurci]

The idea is to propose an alternative signing method that could be more convenient in some use cases.
While Passkeys might not be suitable for every use, they can improve user experience and, thus, help adoption.

We are not saying Passkeys are more secure than storing the private key in the hardware keystore on the mobile device and accessing it through biometrics. They are an alternative secure method.

[sappenin]

I'm also extremely concerned with the idea that some are suggesting sharing the keystore between devices. Wow.

Referencing the article I shared above, Passkeys have two flavors (at least): "hardware-bound" and "copyable." Hardware bound passkeys never leave the device they live in (Yubikeys seem to work this way).

The "copyable" variant might feel risky, but in practice these can be robustly secured. In the Apple ecosystem, for example, using iCloud credentials and bound-devices in your iCloud account provides a range of increasingly sophisticated account protection (Your iCloud account itself can also ultimately be protected using 2FA hardware devices like a Yubikey to prevent login without that hardware device). Likewise for Google accounts. Apple and Google also enable encryption features using keys rooted in hardware that Apple/Google never possess, such that Apple/Google can't access encrypted data stored on your device.

From that perspective, I would imagine Passkeys as being approximately as protected as a person's iCloud or Google account (and that's up to each account holder). Either of these two systems can be quite robustly secured.

But I agree with @elmurci -- this proposal is meant to provide convenience while trying to come very close to the security properties of a purely hardware-based system (though it seems Passkeys can equal those systems when a passkey is stored in a hardware bound device like a Ledger or Yubikey).

How is this different or more secure then just storing the private key in the hardware keystore on the mobile device and accessing through biometrics?

The primary benefit I can see is that using passkeys means that application developers never have access (in application code or otherwise) to private-key material that can be used for signing.

In theory, the non-Passkey/manual alternative you reference in your question should also have this property (because keys live in an OS-managed keystore, and app developers don't have direct access to private key material). In reality, however, many device-based secure enclaves (i.e., on a phone or laptop) don't support Ed25519 or Secp256k1 signing operations. For example, Apple's Secure Enclaves only support P-256 signing operations, which means mobile apps have to fallback to an app-managed encrypted vault strategy where the device's secure enclave stores an encryption key that is used to decrypt an app-controlled "vault" of secret data. Unfortunately, this means that for (hopefully brief) periods of time, XRPL private-key material (normally stored encrypted in the "vault") is in the hands of the application, which means an app developer could be malicious with that private key material.

Putting this another way, using Passkeys allow a user to guarantee (at the OS level) that even the app developer can't get access to the Passkey for signing transactions. That seems like a nice benefit.

I suppose one other advantage of Passkeys is that they enable the decoupling of the signing flow from the app in a manner that is becoming standardized across OS and browser boundaries (whereas "just use secure element directly" is going to be a unique flow for each device/OS). This means OS vendors can iterate and improve upon Passkey management and signing UI/UX/security without app developers needing to do anything (e.g., allow a user to use hardware bound passkeys without the app actually knowing about it or needing to change).

[sappenin]

I'm also curious as to the term unphishable and how it applies here.

If we're merely talking about Passkeys vs. regular XRPL private/public-keys, I don't think there's much of a difference when it comes to "phishability" because a Passkey is -- at its core -- basically just a private/public key pair.

IMO, the real benefit protecting users against phishing comes from the protocol wrapped around the key-pair (colloquially called Passkeys) in a browser or app context. Passkeys offer the ability for a particular private key to be bound to a particular device and simultaneously limited to use only on a particular domain. For an interesting example of this, see Coinbase's Smart Wallet. That app always only allows Passkeys generated on-device while interacting with keys.coinbase.com to be used for signing, and this can all be enforced this by relying upon standards built into the browser/OS or otherwise via Passkeys standardization.

[mvadari]

• Why have an "Action" field in SetPasskeyList instead of just making an empty PublicKey string be the differentiator between adding an removing, like in the Price Oracle spec?
• Why a single object with a list of passkeys instead of a separate object for each supported passkey?
  • Also, why support multiple passkeys? Should it perhaps be more like RegularKey where you only get one?
• nit: should be PasskeyListSet, not SetPasskeyList, since the standard form of transactions is NounVerb (yes, there are exceptions, but they're old, and we should follow the norm).
• Credentials and CredentialID are SFields already used by XLS-70 (and would also be confusing due to that spec), so those should be renamed.
• Why is SignCount needed when that's already the purpose of Sequence?
  • Regardless, I don't see why it's needed in the SetPasskeyList transaction, when it's just a counter used by the ledger object.
• In the "Modifications to Transaction Validation" section, step 3 says you take the SHA-256 of the JSON, and step 6 says you take the SHA-256 of the serialized blob. Which is it?
  • Also, why is the hash needed? Can you not sign the full blob, like you do with other existing signing mechanisms?

[ximinez]

• Also, why support multiple passkeys? Should it perhaps be more like RegularKey where you only get one?

One user may create passkeys on multiple devices. I think every service I've seen that uses passkeys supports multiples. From Github's page about Passkeys:

Authenticators come in many forms, such as an iPhone or Android device, Windows Hello, a FIDO2 hardware security key, or a password manager.

[tequdev]

We can only disable the master key if RegulayKey or Multisig (SignerList) is set, but will PasskeyList be added to these?

[intelliot]

Good point. Yes, I think that would make sense.