Skip to content

Commit

Permalink
Add nonce endpoint reference
Browse files Browse the repository at this point in the history
  • Loading branch information
grausof committed Mar 18, 2024
1 parent 36ca2d9 commit 83acccc
Showing 1 changed file with 8 additions and 6 deletions.
14 changes: 8 additions & 6 deletions docs/en/wallet-attestation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,7 @@ Wallet Instance initialization and registration
**Federation Check:** The Wallet Instance needs to check if the Wallet Provider is part of the Federation, obtaining its protocol specific Metadata. A non-normative example of a response from the endpoint **.well-known/openid-federation** with the **Entity Configuration** and the **Metadata** of the Wallet Provider is represented within the section `Wallet Provider metadata`_.

**Steps 3-5:**: The Wallet Instance sends a request to the Wallet Provider Backend and receives a one-time ``challenge``. This "challenge" is a ``nonce``, which must be unpredictable to serve as the main defense against replay attacks. The backend must generate the ``nonce`` value in a manner that ensures it is single-use and valid only within a specific time frame.
This endpoint in inspired by `OAuth 2.0 Nonce Endpoint`_.


.. code-block:: http
Expand All @@ -91,7 +92,7 @@ Wallet Instance initialization and registration

1. It MUST ensure that Wallet Hardware Keys do not already exist, if they exist and the Wallet is in the initialization phase they must be deleted.
2. It MUST generate a pair of asymmetric EC keys (Wallet Hardware Keys) via a local WSCD.
3. It SHOULD obtain a unique identifier (Wallet Hardware Key Tag) for the generated Wallet Hardware Keys from the operating system. If the operating system permits specifying a tag during the creation of keys, then a random string for the Wallet Hardware Key Tag must be selected. This random value MUST be collision-resistant and unpredictable to ensure security. To achieve this, consider using a cryptographic hash function or a secure random number generator provided by the operating system or a reputable cryptographic library.
3. It SHOULD obtain a unique identifier (Wallet Hardware Key Tag) for the generated Wallet Hardware Keys from the operating system. If the operating system permits specifying a tag during the creation of keys, then a random string for the Wallet Hardware Key Tag must be selected. This random value MUST be collision-resistant and unpredictable to ensure security. To achieve this, consider using a cryptographic hash function or a secure random number generator provided by the operating system or a reputable cryptographic library.
4. If the previous points are satisfied, It MUST store the Wallet Hardware Key Tag in a local storage.

.. note::
Expand All @@ -103,8 +104,8 @@ Wallet Instance initialization and registration

.. note::

**Device Integrity Service:** In this section the Device Integrity Service is considered as it is provided by device manufacturers. This service allows the verification of a key being securely stored within the device's hardware through a signed document (attestation). Additionally, it offers the verifiable proof that a specific app instance (Wallet Instance) is authentic, unaltered, and in its original state using a specialized signed document (assertion) made for this scope.
**Device Integrity Service:** In this section the Device Integrity Service is considered as it is provided by device manufacturers. This service allows the verification of a key being securely stored within the device's hardware through a signed document (attestation). Additionally, it offers the verifiable proof that a specific app instance (Wallet Instance) is authentic, unaltered, and in its original state using a specialized signed document (assertion) made for this scope.

The service also incorporates details in both the attestation and the assertion, such as the device type, model, app version, operating system version, bootloader status, and other relevant information to assess the device has not been compromised. For Android the service used is `Key Attestation`_ in addition to `Play Integrity API`_, while for iOS the `DeviceCheck`_ service.

**Step 8**: The Device Integrity Service performs the following actions:
Expand Down Expand Up @@ -159,7 +160,7 @@ If any errors occur during the Wallet Instance registration, the Wallet Provider


Wallet Attestation Issuance
~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~

This section describes the Wallet Attestation format and how the Wallet Provider issues it.

Expand Down Expand Up @@ -222,8 +223,8 @@ Below a non-normative example of the ``client_data``.
.. 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.

**Steps 11-12**: The Wallet Instance:
* generate the Wallet Attestation Request as a JWT containing ``integrity_assertion``, ``hardware_signature``, ``challenge``, ``wallet_hardware_key_tag``, ``public_jwk`` signed with the private key associated with the public key of the ephemeral key pair generated initially.
* send the Wallet Attestation Request to Wallet Provider backend via token endpoint.
* Constructs the Wallet Attestation Request in the form of a JWT. This JWT includes the ``integrity_assertion``, ``hardware_signature``, ``challenge``, ``wallet_hardware_key_tag``, and ``public_jwk``, and is signed using the private key from the initially generated ephemeral key pair.
* Submits the Wallet Attestation Request to the Wallet Provider's backend through the token endpoint.

Below an non-normative example of the Wallet Attestation Request JWT without encoding and signature applied:

Expand Down Expand Up @@ -509,4 +510,5 @@ The body of the Wallet Attestation JWT MUST contain:
.. _Key Attestation: https://developer.android.com/privacy-and-security/security-key-attestation
.. _Play Integrity API: https://developer.android.com/google/play/integrity?hl=it
.. _DeviceCheck: https://developer.apple.com/documentation/devicecheck
.. _OAuth 2.0 Nonce Endpoint: https://datatracker.ietf.org/doc/draft-demarco-oauth-nonce-endpoint/

0 comments on commit 83acccc

Please sign in to comment.