10.1.4.2.3. Wallet Unit Attestation Issuance

This section describes how the Wallet Provider issues a Wallet Unit Attestations.

The figure illustrates the Sequence Diagram for Wallet Unit Attestations acquisition.

Fig. 10.5 Sequence Diagram for Wallet Unit Attestations acquisition.

Step 1: The User initiates a new operation that necessitates the acquisition of a Wallet Unit Attestation.

Steps 2-3: The Wallet Instance MUST:

  1. Verify the existence of Cryptographic Hardware Keys. If none exist, Wallet Instance re-initialization is required (WP_140a).

  2. Generate one or batch of asymmetric credential key pair(s) to be attested in Wallet Unit Attestation (key_pub_1, key_priv_1, ..., key_pub_n, key_priv_n).

  3. Verify the Wallet Provider's federation membership and retrieve its metadata (WP_023).

Steps 4-6 (Nonce Retrieval): The Wallet Instance requests a nonce value from the Wallet Solution Nonce Endpoint of the Wallet Provider Backend (WP_140b). The nonce is required to be unpredictable and serves as the main defense against replay attacks.

The nonce MUST ensure single-use within a predetermined time frame.

Upon a successful request, the Wallet Provider generates and returns the nonce value to the Wallet Instance.

Step 7: The Wallet Instance performs the following actions (WP_140c):

  • Creates client_data, a JSON object that includes the nonce and a jwk_thumbprints field containing a JSON array of the JWK thumbprints corresponding to the public keys (key_pub_1,...,key_pub_n) .

  • Computes client_data_hash by applying the SHA256 algorithm to the client_data.

Below is a non-normative example of the client_data JSON object.

{
  "nonce": "i4ThI2Jhbu81i8mqyWEuDG5t",
  "jwk_thumbprints": ["vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c"]
}

Steps 8-11: The Wallet Instance:

  • produces an hardware_signature value by signing the client_data_hash with the Wallet Hardware's private key, serving as a proof of possession for the Cryptographic Hardware Keys (WP_140d).

  • requests the Device Integrity Service to create an integrity_assertion value linked to the client_data_hash.

  • receives a signed integrity_assertion value for Wallet Instance from the Device Integrity Service, authenticated by the OEM (WP_140e).

Note

integrity_assertion is a custom payload generated by Device Integrity Service, signed by device OEM and encoded in base64 to have uniformity between different devices.

Note

In the case of Android OS, the flow continues based on Steps 12-15, otherwise for the case of iOS, the flow continues based on Steps 16-19.

Steps 12-15: The Wallet Instance:

  • requests the Key Attestation API to create an key_attestation value for each client_data_hash per each key_pub.

  • receives a signed key_attestation value from the Key Attestation API, authenticated by the OEM.

  • generate keys_to_attest value by signing the key_attestation using the private key of the initially generated credential key pair (priv_key).

Steps 16-19: The Wallet Instance:

  • requests the Device Integrity Service to create an integrity_assertion value for each client_data_hash per each key_pub.

  • receives a signed integrity_assertion value from the Device Integrity Service, authenticated by the OEM.

  • generate keys_to_attest value by signing the integrity_assertion that is obtained for the Wallet Unit Attestation using the private key of the initially generated credential key pair (priv_key).

Steps 20-21 (Wallet Unit Attestation Issuance Request): The Wallet Instance:

  • Constructs the Wallet Unit Attestation Request in the form of a JWT. This JWT includes the integrity_assertion, keys_to_attest, hardware_signature, nonce, hardware_key_tag, cnf, platform, wallet_solution_id, wallet_solution_version and other configuration related parameters (see Table of the Wallet Unit Attestation Request Body) and is signed using the private key that it is public key illustrated in the request through cnf (first element of keys_to_attest) (WP_140–141).

  • Submits the Wallet Unit Attestation Request to the Wallet Unit Attestation Issuance Endpoint of the Wallet Provider Backend.

Note

keys_to_attest contains a key_attestation object in case of Android and integrity_assertion in case of iOS.

The Wallet Instance MUST send the signed Wallet Unit Attestation Request JWT as an assertion parameter in the body of an HTTP request to the Wallet Provider's Wallet Unit Attestation Issuance Endpoint (WP_142).

Steps 22-27: The Wallet Provider Backend evaluates the Wallet unit Attestation Request and MUST perform the following checks (WP_143):

  1. The request MUST include all required HTTP header parameters as defined in Wallet Unit Attestation Issuance Request (WP_143a).

  2. The signature of the Wallet Unit Attestation Request MUST be valid and verifiable using the provided jwk (WP_143b).

  3. The nonce value MUST have been generated by the Wallet Provider and not previously used (WP_143c).

  4. A valid and currently registered Wallet Instance associated with the provided hardware_key_tag MUST exist (WP_143d).

  5. The signature of the keys_to_attest parameter Must be first validated using the provided jwk and its value (key_attestation in case of Android or integrity_assertion in case of iOS) MUST be validated according to the device manufacturer's guidelines.

  6. The client_data MUST be reconstructed using the nonce and their respective thumbprint JWKs [key_pub_1,...,key_pub_n]. The hardware_signature parameter value is then validated using the registered Cryptographic Hardware Key's public key associated with the Wallet Instance (WP_143e).

  7. The integrity_assertion MUST be validated according to the device manufacturer's guidelines. The specific checks performed by the Wallet Provider are detailed in the operating system manufacturer's documentation (WP_143f).

  8. The device in use MUST be free of known security flaws and meet the minimum security requirements defined by the Wallet Provider.

  9. The URL in the iss parameter MUST match the Wallet Provider's URL identifier (WP_143g).

Upon successful completion of all checks, the Wallet Provider issues a Wallet Unit Attestation valid for at least one month.

Step 28 (Wallet Unit Attestation Issuance Response): Upon successful completion, the Wallet Provider MUST return a confirmation response using status code 200 and Content-Type application/json, containing the Wallet Unit Attestations signed by the Wallet Provider in the JWT format. The Wallet Instance will then perform security and integrity verification of the Wallet Unit Attestations received in addition to trust verification of its Issuer (WP_030–031).

Below is a non-normative example of the response.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "wallet_unit_attestation": "omppc3N1ZXJBdXRohEOhASaiBE...dElEAnFlbGVtZW50SWRl"
}