Remote WSCD Registration¶

This flow describes the Remote WSCD registration process as part of the broader wallet activation as introduced here.

Design Decisions¶

In the Remote WSCD Registration process, the Wallet Instance (WI) establishes a two-factor authentication based on a hardware-bound key pair and a PIN. The Remote WSCD responds with a Remote WSCD account identifier and stores it alongside the corresponding public keys in its database.

The Wallet Instance begins the Remote WSCD Registration by requesting a challenge from the Remote WSCD, this challenge protects the process against replay attacks. The Wallet Instance generates a hardware-bound key pair on the mobile device and transmits the public key to the Remote WSCD. This key acts as a possession factor for two-factor authentication.

For the second authentication factor, the Wallet Instance asks the user for an initial RWSCD-PIN. As the PIN management on most mobile devices is not able to achieve LoA high, the RWSCD-PIN and its retry counter are managed on the Remote WSCD. As the Remote WSCD must not know the RWSCD-PIN itself, a cryptographic key is derived from the PIN. Neither the RWSCD-PIN nor the PIN-derived key are stored persistently on the Wallet Instance. More details can be found in the document Cryptography

The Remote WSCD does not need to store any session data or state related to a specific Wallet Instance during the registration process. Instead, the process relies on cryptographically signed ("self-contained") challenges to verify the authenticity of the Wallet Instance.

ToDo¶

update design considerations text to include mdvm token
add chapter about wallet lifecycle
add rate limiting/replay attack detection based on rwscd_auth_challenge

Data Flow¶

This section describes the data flow of the Remote WSCD Registration in a sequence diagram and a more detailed table. Artifacts in italics are further explained in the data register chapter

Sequence Diagram¶

Detailed Description¶

No	Description
001 - 003	The WI requests a challenge from the RWSCD challenge endpoint using an HTTP POST request, the request is unauthenticated. The RWSCD generates a JSON structure containing a random nonce and a timestamp of the current time and MACs it using a symmetric key (rwscd_mac_symk) as a JSON Web Token (JWT), the resulting structure is the rwscd_auth_challenge. The MDVM responds to the WI with the rwscd_auth_challenge in the HTTP payload. The WI uses the challenge as a transparent string and does not evaluate the JWT claims. The RWSCD does not store the challenge after creation, thus the operation is stateless.
004 - 005	The WI requests a RWSCD-PIN (user_rwscd_pin) from the user. The WI validates that the entered user_rwscd_pin matches the PIN security requirements. In particular, it matches the PIN input against a denylist of trivial, repetitive patterns.
006	The WI generates a cryptographic, random salt (wi_rwscd_pin_salt), that will be used for the key derivation of the RWSCD-PIN. The salt expands the low-entropy Wallet PIN into a high-entropy cryptographic key. The salt must have sufficiently secure randomness and at least 128 bits of length. The salt is stored encrypted for the long-term, as it is required to regenerate the knowledge authentication factor together with the PIN.
007	The WI derives the cryptographic key pair (wi_rwscd_pin_prvk and wi_rwscd_pin_pubk) which is used as the knowledge factor of the two-factor authentication to the RWSCD for subsequent requests. The WI must use HKDF to derive wi_rwscd_pin_prvk from user_rwscd_pin and wi_rwscd_pin_salt, see PIN derivation. This key pair is never stored in the WI, but must be deleted after its intended usage, see PIN caching for details. The user_rwscd_pin must be deleted from memory as soon as the wi_rwscd_pin_prvk is derived.
008	The WI computes a proof of possession by signing the rwscd_auth_challenge for freshness and to enable replay protection and both public keys wi_mdvm_auth_pubk and wi_rwscd_pin_pubk once with the wi_mdvm_auth_prvk from the MDVM token (the actual possession factor) and once with the wi_rwscd_pin_prvk (the knowledge factor). The payload and both signatures are encoded as a JSON Web Signature (JWS) in JSON Serialization. The resulting structure is called wi_rwscd_register_pop. The proof of possession cross-signs each public key to bind both authentication factors together.
009	The WI requests the RWSCD to perform the registration and sends the proof of possession for the two-factor authentication (wi_rwscd_register_pop) und the MDVM token mdvm_token that was issued during wallet activation. If the mdvm_token is not up-to-date, the WI may fetch a fresh one from the MDVM endpoint using the renewal flow for either Android or iOS. The request is unauthenticated (as RWSCD does not know the WI yet at registration).
010	The RWSCD verifies the self-contained rwscd_auth_challenge using its symmetric key (rwscd_mac_symk) and validating that the timestamp is within a valid time interval of 0 minute to +5 minutes.
011 - 013	The RWSCD verifies the received mdvm_token with mdvm_attestation_pubk for authenticity and integrity and checks that it is still valid. The RWSCD has a trusted, out-of-band mechanism towards the MDVM to fetch the valid mdvm_attestation_pubk. The RWSCD verifies the received proof of possession for the WI's possession factor (wi_rwscd_register_pop) using the included wi_mdvm_auth_pubk from the mdvm_token. Lastly, the RWSCD verifies that the used key wi_mdvm_auth_pubk is the same in wi_rwscd_register_pop and mdvm_token.
014	The RWSCD verifies the knowledge factor of the proof of possession (wi_rwscd_register_pop) by verifying the second signature using the included wi_rwscd_pin_pubk.
015	The RWSCD optionally initializes and sets up the account with the HSM.
016	The RWSCD generates a unique Remote WSCD account identifier rwscd_account_id and stores the combination of rwscd_account_id, wi_mdvm_auth_pubk, wi_rwscd_pin_pubk, and an initial retry counter for the PIN in its database to register the new account.
017	The RWSCD responds with the generated Remote WSCD account identifier rwscd_account_id to the WI.
018	The WI stores the received Remote WSCD account identifier rwscd_account_id.

Remote WSCD Challenge JWT¶

The rwscd_auth_challenge encapsulates a verifiable challenge, that is generated and verified by the Remote WSCD. As the producer and consumer is the Remote WSCD, a MAC key rwscd_mac_symk is used for efficiency.

The rwscd_auth_challenge contains:

JOSE Header typ: as recommended by JWT BCP
JOSE Header alg: indicating HMAC-SHA256 as MAC algorithm
JWT Claim nonce: containing at least 128 bits of random
JWT Claim iat current time, indicating the issuance date

Below is a non-normative example of a rwscd_auth_challenge:

Header

{
  "typ": "wi-rwscd-auth-pop+jwt",
  "alg": "HS256"
}

Payload

{
  "nonce": "564edacb-ad81-420c-a74e-6cfbaa713d48",
  "iat": 1726214250
}

Signed by rwscd_mac_symk

Proof of possession JWS in JSON Serialization¶

The wi_rwscd_register_pop is a dual-authentication factor of the Wallet App, that creates a proof of the wi_mdvm_auth_prvk and the wi_rwscd_pin_prvk over the rwscd_auth_challenge.

The wi_rwscd_register_pop contains:

JOSE Header typ as recommended by JWT BCP
JOSE Header alg indicating ECDSA NIST P-256
JOSE Header wi_rwscd_pin_pubk containing the serialized wi_rwscd_pin_pubk
JWT Claim rwscd_auth_challenge containing the serialized rwscd_auth_challenge
JWT Claim aud referencing the URL of the Remote WSCD

Note: There is no jti parameter for potential enhanced replay protection, as we can reuse the rwscd_auth_challenge for this purpose. There is also no iat or exp parameter, because the rwscd_auth_challenge already includes a trusted timestamp. There is also no iat or exp parameter, which is added by the WI, because the rwscd_auth_challenge already includes a trusted timestamp.

Below is a non-normative example of a wi_rwscd_register_pop:

Protected headers:

{
  "typ": "wi-rwscd-register-pop+jose+json",
  "alg": "ES256",
  "wi_rwscd_pin_pubk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "mT3LI0y2LBP1mxbkHQhVrdi633qQEUJCyib1ot62flI",
    "y": "mVNKt_c8BV1vTK20ParZL5uQzDfPo_ZZXa5udKVsGao"
  }
}

Payload:

{
  "rwscd_auth_challenge": "eyJ0eXAiOiJyd3NjZC1hdXRoLWNoYWxsZW5nZStqd3QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MzgzMTQ4NzYsIm5vbmNlIjoiMGRmOGQ2OTMtODUzOS00NGRkLThjMjItMTk1NDYyODZiNjQ4IiwiaWF0IjoxNzM4MzExMjc2fQ.RIcCxQglW04Z8Tw0xH1erUx2Qbbppgv-0P-84Qh3MiE",
  "aud": "https://wallet-provider-backend.eudi-wallet.de"
}

Signed by wi_mdvm_auth_prvk and wi_rwscd_pin_prvk

Complete JWS example:

{
  "payload"    : "SGVsbG8sIHdvcmxkIQ",
  "signatures" : [
    {
      "protected" : "eyJraWQiOiIxIiwiYWxnIjoiUlMyNTYifQ",
      "signature" : "XAwNAgj-Dw5CBeWG4_6LwQyJrQaAGVJmtqkl21QcIxedNV8Ft0he02eU8Ih60jjNe5FbQxrgfA84JA0isb7NkdczEW_kfX9Fknh-tdypyymrPTsP9bhLKUYfQ7nglWgVf1tukFqkAVZOLdfV7ri9we_bqZblM0pD5ysbu6hjhkLbXSSe_ZD0QfKmJFDaIHWBlB2Z0BeqSmyGQTbO6ZpmxXzICz0ANqTsCrJe6TU2CE6i1mDm0arL12VdcqO9JjD7iQkWppfD3kmRCGsSk3jdJpyWUDCYSKlPVaJJElaffwYjIBevCgfMHFO8ALwpUJc_cFcwBsyalo25JzUSzBNaXg"
    },
    {
      "protected" : "eyJraWQiOiIyIiwiYWxnIjoiRVMyNTYifQ",
      "signature" : "ckfVpM4ECSrhDGitxe5smT-z65t3C238JyrHkJw3kiOAunPTRYzHD50wzvNGXG45nUlwl7Ybg8GPlOCNyJeonw"
    }
  ]
}