logo IPR declaration
FIDO Web Pay - Crypto
Table of Contents
1 Introduction
2 Relationship to Existing Standards
3 Terminology
4 User Authorization
    4.1 Create Authorization Data (AD)
    4.2 Create Signed Authorization Data (SAD)
    4.3 Signature Algorithms
5 Encrypted User Authorization (ESAD)
    5.1 Encryption Object
    5.2 Encryption Process
    5.3 Content Encryption Algorithms
    5.4 Key Algorithms
    5.5 Key Encryption Algorithms
    5.6 Key Derivation Function
6 User Authorization Decoding and Verification
    6.1 Decrypt Authorization (ESAD)
    6.2 Decode Signed Authorization Data (SAD)
    6.3 Validate Signature
7 Sample Keys
    7.1 Signature Key
    7.2 Encryption Key
Document History
Authors
Trademarks
1. Introduction
This document describes the cryptographic constructs used in FIDO Web Paylink (FWP) Assertions.
To make the descriptions more accessible, the samples in the core document are used for illustrating the different processing steps. The samples depend on the keys provided in the Sample Keys section.
2. Relationship to Existing Standards
Since the user authorization component of FWP Assertionslink is based on CBOR [RFC8949link], one might assume that the cryptography would be based on COSE [RFC8152link]. However, this is only partially true because FIDO signatures (Web Authenticationlink) are incompatible with COSE. In addition, FWP authorization signatures build on deterministic CBOR as outlined in RFC8949, section 4.2.1.
3. Terminology
Throughout this document CBOR primitives are expressed in CDDL [RFC8610link] notation.
Items in red refer to attributes associated with the selected Payment Credentiallink.
4. User Authorization
Unlike Web Authenticationlink, FWP builds on an authorization concept derived from EMV®. That is, user authorizations are created entirely locally in the FWP client. Compatible FIDO authenticators MUST therefore be "client side" only.
The following subsections describe the steps required for creating the user authorization component of FWP Assertionslink.
4.1. Create Authorization Data (AD)
Before requesting the user to authorize ("sign"), the FWP client creates data to related to the payment request (aka "dynamic linking") like in the sample from the main document:
{
  1: {
    1: "Space Shop",
    2: "7040566321",
    3: "435.00",
    4: "EUR"
  },
  2: "spaceshop.com",
  3: "FR7630002111110020050014382",
  4: "https://banknet2.org",
  5: "0057162932",
  6: "additional stuff...",
  7: {
    1: {
      3: "Android",
      4: "12.0"
    },
    2: {
      3: "Chrome",
      4: "108"
    }
  },
  8: [40.74844, -73.984559],
  9: "2023-02-16T10:14:07+01:00",
  / signature /
  -1: {
    / signatureAlgorithm = ES256 /
    1: -7,
    / publicKey /
    2: {
      / kty = EC /
      1: 2,
      / crv = P-256 /
      -1: 1,
      / x /
      -2: h'e812b1a6dcbc708f9ec43cc2921fa0a14e9d5eadcc6dc63471dd4b680c6236b5',
      / y /
      -3: h'9826dcbd4ce6e388f72edd9be413f2425a10f75b5fd83d95fa0cde53159a51d8'
    }
  }
}
This object is referred to as Authorization Data (AD)link.
Since this section is about cryptographic constructs, only the data in the signature map (label -1) is elaborated on here.
Definition:
NameLabelTypeDescription
signatureAlgorithm 1 int FIDO signatureAlgorithm associated with the selected Payment Credentiallink. The value to use is the "Identifier" specified in the Signature Algorithms table.
publicKey 2 map FIDO publicKey descriptor associated with the selected Payment Credentiallink. The key descriptor MUST only contain the core public key data. This item MUST be COSE compliant as well as be compatible with the signatureAlgorithm.
authenticatorData 3 bstr FIDO assertion data attribute. See also Web Authenticationlink.
signatureValue 4 bstr FIDO assertion signature. See also Web Authenticationlink.
As can be seen in the listing, the signatureAlgorithm and publicKey attributes are already featured in the signature map. This is because they are static and can thus be included in the data to be signed, potentially making the signature scheme more resistant to tampering.
The sample AD should read as follows when expressed in hexadecimal encoding:
aa01a4016a53706163652053686f70026a3730343035363633323103663433352e30300463455552026d737061636573686f702e636f6d03781b465237363330303032313131313130303230303530303134333832047468747470733a2f2f62616e6b6e6574322e6f7267056a3030353731363239333206736164646974696f6e616c2073747566662e2e2e07a201a20367416e64726f6964046431322e3002a203664368726f6d6504633130380882fb40445fcce1c58256fbc0527f0303c07ee1097819323032332d30322d31365431303a31343a30372b30313a303020a2012602a401022001215820e812b1a6dcbc708f9ec43cc2921fa0a14e9d5eadcc6dc63471dd4b680c6236b52258209826dcbd4ce6e388f72edd9be413f2425a10f75b5fd83d95fa0cde53159a51d8
4.2. Create Signed Authorization Data (SAD)
Using the result of the previous step (but using binary encoding), as the sole data input to the FIDO signature process, the user should at this stage be asked to authorize a payment request using the key (authenticator) pointed out by the credentialId of the selected Payment Credentiallink.
For a detailed description of how FIDO signatures are created, turn to Web Authenticationlink. Note that AD is signed after hashing, making clientDataHash the actual data to be signed:
signature
The SHA256 hash of the sample AD should read as follows if encoded in hexadecimal:
d1f6eba26d2a7308eecdcd2a215460d5ac50a395de72ca2f5c4343622e8acf23
After adding the asserted FIDO authenticatorData and signatureValue attributes to the signature map of AD, the resulting sample should read as follows:
{
  1: {
    1: "Space Shop",
    2: "7040566321",
    3: "435.00",
    4: "EUR"
  },
  2: "spaceshop.com",
  3: "FR7630002111110020050014382",
  4: "https://banknet2.org",
  5: "0057162932",
  6: "additional stuff...",
  7: {
    1: {
      3: "Android",
      4: "12.0"
    },
    2: {
      3: "Chrome",
      4: "108"
    }
  },
  8: [40.74844, -73.984559],
  9: "2023-02-16T10:14:07+01:00",
  / signature /
  -1: {
    / signatureAlgorithm = ES256 /
    1: -7,
    / publicKey /
    2: {
      / kty = EC /
      1: 2,
      / crv = P-256 /
      -1: 1,
      / x /
      -2: h'e812b1a6dcbc708f9ec43cc2921fa0a14e9d5eadcc6dc63471dd4b680c6236b5',
      / y /
      -3: h'9826dcbd4ce6e388f72edd9be413f2425a10f75b5fd83d95fa0cde53159a51d8'
    },
    / authenticatorData /
    3: h'412e175a0f0bdc06dabf0b1db79b97541c08dbacee7e31c97a553588ee922ea70500000017',
    / signatureValue /
    4: h'304402204fbd186e8eac7d7dbb915a7a443b0939af77de5e35cf87831663ae3a8bfc1d940220201d0c51ff9b683648a626cbe0bbb69fed29ce854aea65763e0e33edf2af9e09'
  }
}
This object is subsequently referred to as Signed Authorization Data (SAD).
The sample SAD object should read as follows if encoded in hexadecimal:
aa01a4016a53706163652053686f70026a3730343035363633323103663433352e30300463455552026d737061636573686f702e636f6d03781b465237363330303032313131313130303230303530303134333832047468747470733a2f2f62616e6b6e6574322e6f7267056a3030353731363239333206736164646974696f6e616c2073747566662e2e2e07a201a20367416e64726f6964046431322e3002a203664368726f6d6504633130380882fb40445fcce1c58256fbc0527f0303c07ee1097819323032332d30322d31365431303a31343a30372b30313a303020a4012602a401022001215820e812b1a6dcbc708f9ec43cc2921fa0a14e9d5eadcc6dc63471dd4b680c6236b52258209826dcbd4ce6e388f72edd9be413f2425a10f75b5fd83d95fa0cde53159a51d8035825412e175a0f0bdc06dabf0b1db79b97541c08dbacee7e31c97a553588ee922ea70500000017045846304402204fbd186e8eac7d7dbb915a7a443b0939af77de5e35cf87831663ae3a8bfc1d940220201d0c51ff9b683648a626cbe0bbb69fed29ce854aea65763e0e33edf2af9e09
After the Signed Authorization Data (SAD) has been created, it MUST be encrypted as described in Encrypted User Authorization (ESAD).
4.3. Signature Algorithms
FIDO currently supports the following COSE signature algorithms:
NameIdentifierNotes
ES256 -7 ECDSA signatures differs in encoding from COSE. See Web Authenticationlink.
ED25519 -8 This identifier is strictly put not COSE compliant.
RS256 -257
5. Encrypted User Authorization (ESAD)
For privacy and security reasons the user authorization component of FWP Assertionslink MUST be encrypted.
The listing below shows a sample of an encrypted SAD object:
/ COTX wrapper /
1010(["https://fido-web-pay.github.io/ns/p1", {
  / algorithm = A256GCM /
  1: 3,
  / keyEncryption /
  2: {
    / algorithm = ECDH-ES+A256KW /
    1: -31,
    / keyId /
    3: "x25519:2022:1",
    / ephemeralKey /
    7: {
      / kty = OKP /
      1: 1,
      / crv = X25519 /
      -1: 4,
      / x /
      -2: h'034e9273d9d55c3df0fb366fc33425648d8150de504c1b3499e0a7dac91a2c17'
    },
    / cipherText /
    10: h'2fd62268299b5e2fe57bafd5762a8eff3a8b9991facbec2d36093cdacb23ed5dff5750ca3bd5d7fc'
  },
  / tag /
  8: h'c20ab16145f1e5349c1d85fab4caf0a3',
  / iv /
  9: h'57e7341b3b1379d8765ae613',
  / cipherText /
  10: h'204e5f5b4ad63d013ac875d160ffc4f762b75153fb8b30a9d9ecefaf23a30898cd68ac104edfdf854e060d906f1229f739b37e52dffed874a07df3fd661c061d6d7b4d561afe9fc31f14ffbb15a5d62debe1f5cb54a851fdc4b54a83d6f8e64a5a5b0c445960992af964126c17aa5591d747b9e74a40c5ea2d6c2a5f387401c63685bb1cc2a7a331b9b44505622e27a7c29314dedaacc8d3f425b48010d97115f7672dc1ad89a6b01b3d6f0427333d1abf0667feb54c42383ceb4a8883a24b93b4b7921649d05435fb62d4d4aafcb4ce93238d3538fc8821bf6a71bc906173152f933b359ccf9a546ad840510baebdecb6ee15fddc4348b8ef8d80cb36f8410a94784e22542208bfbf6cab1989f23d34be75ccc38a29502bf0e952174ab823df6728c39315c2acf3be75fb8a072a048c08e1efec35ee5158cf828f2b8b8a9e304824ff5dc7c9139af3667165ebc5dca0cfc20baa9e2e45fa65aad54ae026e7b463ec8f974dbe37e90217f6abe223c598c334e9aaa98647ee485eb65f271a7386db71c13843b7570ee211a5b055ee83e9ab9068536ae0b698821bad1a79de35'
}])
The resulting object is referred to as Encrypted Signed Authorization Data (ESAD).
The sample ESAD object should read as follows if encoded in hexadecimal:
d903f282782468747470733a2f2f6669646f2d7765622d7061792e6769746875622e696f2f6e732f7031a5010302a401381e036d7832353531393a323032323a3107a301012004215820034e9273d9d55c3df0fb366fc33425648d8150de504c1b3499e0a7dac91a2c170a58282fd62268299b5e2fe57bafd5762a8eff3a8b9991facbec2d36093cdacb23ed5dff5750ca3bd5d7fc0850c20ab16145f1e5349c1d85fab4caf0a3094c57e7341b3b1379d8765ae6130a59019f204e5f5b4ad63d013ac875d160ffc4f762b75153fb8b30a9d9ecefaf23a30898cd68ac104edfdf854e060d906f1229f739b37e52dffed874a07df3fd661c061d6d7b4d561afe9fc31f14ffbb15a5d62debe1f5cb54a851fdc4b54a83d6f8e64a5a5b0c445960992af964126c17aa5591d747b9e74a40c5ea2d6c2a5f387401c63685bb1cc2a7a331b9b44505622e27a7c29314dedaacc8d3f425b48010d97115f7672dc1ad89a6b01b3d6f0427333d1abf0667feb54c42383ceb4a8883a24b93b4b7921649d05435fb62d4d4aafcb4ce93238d3538fc8821bf6a71bc906173152f933b359ccf9a546ad840510baebdecb6ee15fddc4348b8ef8d80cb36f8410a94784e22542208bfbf6cab1989f23d34be75ccc38a29502bf0e952174ab823df6728c39315c2acf3be75fb8a072a048c08e1efec35ee5158cf828f2b8b8a9e304824ff5dc7c9139af3667165ebc5dca0cfc20baa9e2e45fa65aad54ae026e7b463ec8f974dbe37e90217f6abe223c598c334e9aaa98647ee485eb65f271a7386db71c13843b7570ee211a5b055ee83e9ab9068536ae0b698821bad1a79de35
The following subsections describe the encryption scheme in detail.
5.1. Encryption Object
The encryption scheme is based on an ECDH profile derived from CBOR Encryption Format (CEF)link.
To identify the ESAD object profile, as well as the encrypted SAD object, a common COTXlink tag with the value "https://fido-web-pay.github.io/ns/p1" is wrapping the encryption attributes.
ESAD objects are packaged as follows:
FWP Encryption Layout Main Map (Content Encryption) Sub Map (Key Encryption) algorithm (1) keyEncryption (2) tag (8) iv (9) cipherText (10) algorithm (1) keyId (3) publicKey (4) ephemeralKey (7) cipherText (10)
Numbers in parentheses represent the CBOR map key (label) associated with the symbolic name. The attributes in the dashed boxes are optional, depending on key encryption algorithm and encryption key reference method.
Main map definition:
NameLabelTypeDescription
algorithm 1 int Symmetric key algorithm used for encrypting the actual content. The value to use is the "Identifier" specified in the Content Encryption Algorithms table.
keyEncryption 2 map Holds the Sub map.
tag 8 bstr Algorithm specific authentication data.
iv 9 bstr Algorithm specific initialization vector.
cipherText 10 bstr Encrypted content.
Sub map definition:
NameLabelTypeDescription
algorithm 1 int Key encryption algorithm. The value to use is the "Identifier" specified in the Key Encryption Algorithms table.
keyId 3 "Any" Optional: To facilitate a streamlined decryption process, the encryption object MUST include a reference to the encryption key. This reference is either provided through a keyId or through the publicKey itself. That is, both attributes MUST NOT be present in an FWP compliant encryption object.
Note that the this specification does not define any specific keyId syntax. The sample uses a tstr but it could equally well be a hash of the publicKey featured in a bstr.
publicKey 4 map Optional: Public key in COSE format. See keyId.
Note that a publicKey attribute MUST only contain the core public key data.
ephemeralKey 7 map Ephemeral public key in COSE format.
Note that a publicKey attribute MUST only contain the core public key data.
cipherText 10 bstr Optional: Encrypted key for key-wrapping ECDH algorithms.
5.2. Encryption Process
To encrypt a SAD object, the following steps MUST be performed:
  1. Retrieve the keyEncryptionAlgorithm, contentEncryptionAlgorithm, and encryptionKey attributes of the selected Payment Credentiallink. The compatibility of these attributes with respect to this specification, as well as with the client implementation, is assumed to have been verified during credential enrollment.
  2. Create an empty CBOR Sub map object.
  3. Copy the keyEncryptionAlgorithm to the algorithm label.
  4. If the encryptionKeyId of the selected Payment Credentiallink is defined, copy the value to the keyId label, else copy the encryptionKey to the publicKey label.
  5. Creating a key for encrypting the content (SAD) requires the following steps:
  6. Create an empty CBOR Main map object.
  7. Copy the contentEncryptionAlgorithm to the algorithm label.
  8. Copy the previously created CBOR Sub map object to the keyEncryption label.
  9. Wrap the current Main map object in a COTX tag and assign the serialized result to an AAD (Additional Authenticated Data) variable.
  10. Generate an IV (Initialization Vector) compliant with the contentEncryptionAlgorithm. See Content Encryption Algorithms.
  11. Encrypt the SAD object as follows
    cipherText, tag = encrypt(contentEncryptionAlgorithm,
                              contentEncryptionKey,
                              SAD,
                              AAD,
                              IV)
    here using an hypothetical encryption method returning both the resulting cipherText and a tag value.
  12. Copy the cipherText, tag, and IV values to the cipherText, tag, and iv labels respectively.
The wrapped CBOR Main map object represents an ESAD object according to this specification.
5.3. Content Encryption Algorithms
Compliant FWP implementations MUST as a minimum support the following COSE content encryption algorithms:
NameIdentifierKeyTagIV
A128GCM 1 16 16 12
A192GCM 2 24 16 12
A256GCM 3 32 16 12
The length of the "Key", "Tag", and "IV" attributes are in bytes.
5.4. Key Algorithms
Compliant FWP implementations MUST as a minimum support P-256 and X25519 keys.
5.5. Key Encryption Algorithms
Compliant FWP implementations MUST as a minimum support the following COSE key encryption algorithms:
NameIdentifierDerived Key
ECDH-ES -25 Defined by the content encryption algorithm. See Content Encryption Algorithms.
ECDH-ES+A128KW -29 16
ECDH-ES+A192KW -30 24
ECDH-ES+A256KW -31 32
The length of the "Derived Key" attribute is in bytes.
5.6. Key Derivation Function
Note that the ECDH algorithms MUST use a Key Derivation Function (KDF) according to HKDF [RFC5869link], profiled as follows:
6. User Authorization Decoding and Verification
The following sections describe the steps needed for decoding the user authorization part (ESAD) of FWP Assertionslink, as well as verifying that it is technically correct from a cryptographic point of view. As outlined in the core document, several other checks MUST also be performed before an associated payment request can be considered as trusted.
Missing, erroneous, or extraneous data MUST cause the verification process to terminate with an appropriate error indication.
6.1. Decrypt Authorization (ESAD)
Decode the ESAD binary using a suitable CBOR parser.
Perform the following steps to decrypt the ESAD object:
  1. Retrieve the private encryption key associated with the encryptionKeyId or the publicKey in the Sub map, depending on which of the attributes that are defined (which in most cases is known in advance since the issuer and relying party usually is the same entity).
  2. Fetch the ECDH algorithm to use from the algorithm attribute in the Sub map.
  3. Perform an ECDH key agreement operation including KDF with the retrieved private key and the ephemeralKey attribute in the Sub map.
  4. For key wrapping ECDH algorithms, use the result of the ECDH operation to unwrap a contentEncryptionKey (specified by the cipherText attribute in the Sub map), while ECDH-ES returns the contentEncryptionKey directly. See Key Encryption Algorithms.
  5. Fetch the contentEncryptionAlgorithm specified by the algorithm attribute in the Main map. See Content Encryption Algorithms.
  6. Fetch and remove the tag, iv, and cipherText attributes in the Main map.
  7. Serialize the remaining CBOR object and assign the result to an AAD (Additional Authenticated Data) variable.
  8. Decrypt the ESAD object as follows
    plainText = decrypt(contentEncryptionAlgorithm,
                        contentEncryptionKey,
                        AAD,
                        iv,
                        tag,
                        cipherText)
    here using an hypothetical decryption method.
If all steps succeed, the resulting plain text is assumed to be a SAD object.
6.2. Decode Signed Authorization Data (SAD)
Decode the SAD binary using a suitable CBOR parser.
Fetch and remove the FIDO attributes authenticatorData and signatureValue from the decoded object which now effectively is an AD object.
6.3. Validate Signature
The signature is validated by applying the attributes received in the signature map to a suitable signature validation API like:
// Hypothetical signature validation method
validate(signatureAlgorithm,
         publicKey,
         // Signed data
         authenticatorData || SHA256(AD),
         signatureValue)
Although the FIDO signature scheme is unique, signatures can be validated by any cryptographic API supporting the signature algorithm in question.
7. Sample Keys
7.1. Signature Key
The following key (here expressed as a JWK [RFC7517link]), was used for the signature part of the SAD sample:
{
  "kty": "EC",
  "crv": "P-256",
  "x": "6BKxpty8cI-exDzCkh-goU6dXq3MbcY0cd1LaAxiNrU",
  "y": "mCbcvUzm44j3Lt2b5BPyQloQ91tf2D2V-gzeUxWaUdg",
  "d": "6XxMFXhcYT5QN9w5TIg2aSKsbcj-pj4BnZkK7ZOt4B8"
}
Note that ES256 signatures usually depend on a random factor as well, making each signature unique. Verification should still work as long as the signature key and data to be signed remain constant.
7.2. Encryption Key
The following key (here expressed as a JWK [RFC7517link]), was used for the encryption part of the ESAD sample:
{
  "kty": "OKP",
  "crv": "X25519",
  "x": "6ZoM7yBYlJYNmxwFl4UT3MtCoTv7ztUjpRuKEXrV8Aw",
  "d": "cxfl86EVmcqrR07mWENCf1F_5Ni5mt1ViGyERB6Q1vA"
}
Note that the ESAD sample uses a keyId for identifying the encryption key.
Document History
DateVersionComment
2021-07-26 0.1Initial publishing.
2021-08-23 0.11Added CTAP2 suggestion.
2021-09-30 0.12Made keyId generic.
2022-02-02 0.13Main document update forced test data update.
2022-06-17 0.14CBOR primitives expressed in CDDL notation.
2022-08-18 0.15CTAP2 signature scheme.
2022-12-19 0.16Set signature key to -1.
2023-01-07 0.17Added COTX wrapper to ESAD.
Authors
The FWP specification is currently authored by Anders Rundgren (anders.rundgren.net@gmail.com) on GitHub (https://github.com/fido-web-pay/specificationlink).
Trademarks
FIDO is a registered trademark of the FIDO alliance.
EMV is a registered trademark of EMVCo.
 
This specification represents an independent effort, not associated with the FIDO alliance or EMVCo.