Remote WSCD Operations¶

This flow describes various operations provided by the Remote WSCD, that are required for both issuance and presentation of credentials. Some of this functionality is reflected in the issuance and presentation flows of the blueprint, but not as cleanly separated as in this document. Furthermore, this page includes additional functionality not reflected in the blueprint.

Design Decisions¶

In the Remote WSCD Operation process, the WI uses the established two-factor authentication from the registration process to request a certain operation from the Remote WSCD. The Remote WSCD forwards key-related operations to the Remote KMS Provider and forwards the results to the WI.

The WI begins the Remote WSCD Operation by requesting a challenge from the Remote WSCD, this challenge protects the process against replay attacks. The WI creates an operation request and authenticates the request as a JSON Web Signature (JWS) in JSON serialization using two signatures, one for each authentication factor. It sends the authenticated request alongside the account identifier to the Remote WSCD.

The Remote WSCD verifies the authenticated request using the data corresponding to the account identifier. The validation sequence begins by verifying the challenge for replay detection, continues with the possession factor and concludes with the PIN, to avoid any denial attacks potentially blocking user accounts. The PIN verification and its retry counter are managed by the Remote WSCD. After verifying the authenticity of the operation request, the Remote WSCD forwards key-related operations to the Remote KMS Provider or handles any user management operations itself. An overview of supported operations is given in , the detailed API will be published at a later stage.

ToDo¶

integrate mobile device vulnerability management
add rate limiting/replay attack detection based on rwscd_auth_challenge and rwscd_account_id

Data Flow¶

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

Sequence Diagram¶

Detailed Description¶

No	Description
001	The WI requests the RWSCD to generate a challenge (rwscd_auth_challenge). The request is unauthenticated and state-less.
002	The RWSCD generates a structure containing a random nonce and 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 called the challenge (rwscd_auth_challenge). The key and nonce must have sufficient security properties, information on algorithms and key lengths can be found in the cryptography chapter.
003	The RWSCD responds with the challenge (rwscd_auth_challenge) to the WI. The WI uses the challenge as a transparent string and not evaluate the JWT claims.
004	The WI generates the operation (wi_rwscd_operation_request) that shall be performed by the Remote WSCD. The supported operations are specified in the operations section.
005	The WI requests the RWSCD PIN (user_rwscd_pin) from the user.
006	The WI receives the RWSCD PIN (user_rwscd_pin) entered by the user.
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 authorize the operation to the RWSCD. 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 payload of rwscd_auth_challenge for replay protection, both public keys of the authentication factors wi_rwscd_pin_pubk and the requested operation wi_rwscd_operation with: the possession factor wi_rwscd_auth_prvk the knowledge factor wi_rwscd_pin_prvk using ECDSA and encoding it as a JSON Web Signature (JWS) in JSON Serialization. The resulting structure is called wi_rwscd_auth_pop. The proof of possession is signing the public keys and the wi_rwscd_operation_request to bind both authentication factors and the requested operation together.
009	The WI requests the RWSCD to perform the operation, it sends rwscd_account_id for identification, the proof of possession (wi_rwscd_auth_pop) for the two-factor authentication including the requested operation wi_rwscd_operation_request to be performed. The request is authenticated and state-less.
010	The RWSCD verifies the rwscd_auth_challenge included in the wi_rwscd_auth_pop by verifying the MAC using rwscd_mac_symk and validating that the timestamp is within a valid time interval of 0 minute to +5 minutes. This step ensures replay protection beyond the valid time interval of the challenge.
011	The RWSCD fetches the public keys for the possession factor wi_rwscd_auth_pubk and the knowledge factor wi_rwscd_pin_pubk from the database using the provided account identifier rwscd_account_id.
012	The RWSCD verifies the first signature of the proof of possession wi_rwscd_auth_pop using the wi_rwscd_auth_pubk. This verification is performed before the PIN validation to prevent denial of service or malicious locking for specific accounts. The database lookup is not subject to prevention of distributed denial of service attacks, as these attacks need to be mitigated further up in the infrastructure layer.
013	The RWSCD fetches the retry counter rwscd_pin_retry_counter from the database using the provided account identifier rwscd_account_id, validate that the retry counter has not exceeded retry limit and decreases the retry counter. All the operations related to the PIN retry counter must happen in a single database transaction, i.e. the operation must fail if the rwscd_pin_retry_counter is already at 0 and it must be prevented that multiple concurrent requests allow to circumvent these checks for more tries than intended, see cryptography chapter for details.
014	The RWSCD verifies the second signature of the proof of possession wi_rwscd_auth_pop using the public key wi_rwscd_pin_pubk from the database. If the verification is successful, the rwscd_pin_retry_counter must be reset to the initial value (maximum retries).
015	The RWSCD requests cryptographic operation to the Remote KMS Provider based on the wi_rwscd_operation_request as described in the operations section. Some operations may not involve the Remote KMS Provider, e.g. changing the RWSCD PIN.
016	The RWSCD responds with the return value of operation (rwscd_operation_result).

Remote WSCD Challenge JWT¶

Defined in Remote WSCD Registration

Proof of possession JWS in JSON Serialization¶

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

The wi_rwscd_auth_pop contains: - JOSE Header typ as recommended by JWT BCP - JOSE Header alg indicating ECDSA NIST P-256 - JWT Claim aud referencing the URL of the Remote WSCD - JWT Claim rwscd_auth_challenge containing the serialized rwscd_auth_challenge - JWT Claim wi_rwscd_op_id identifying the wi_rwscd_operation_request - additional JWT claims needed for wi_rwscd_operation_request arguments

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.

Below is a non-normative example of a wi_rwscd_auth_pop:

Protected headers:

{
  "typ": "wi-rwscd-register-pop+jose+json",
  "alg": "ES256"
}

Payload:

{
  "aud": "https://wallet-provider-backend.eudi-wallet.de",
  "rwscd_auth_challenge": "eyJ0eXAiOiJyd3NjZC1hdXRoLWNoYWxsZW5nZStqd3QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MzgzMTQ4NzYsIm5vbmNlIjoiMGRmOGQ2OTMtODUzOS00NGRkLThjMjItMTk1NDYyODZiNjQ4IiwiaWF0IjoxNzM4MzExMjc2fQ.RIcCxQglW04Z8Tw0xH1erUx2Qbbppgv-0P-84Qh3MiE",
  "rwscd_op_id": "SIGN",
  "rwscd_key_id": "3e8ba9be-78d9-4ed3-996a-a9d4d72ce414", 
  "wi_rwscd_digest_hash": "0fafdefcad0023807f98aad159f42eba57279517444f5e0f138299cce367362f"
}

Signed by wi_rwscd_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"
    }
  ]
}

Wallet Trust Evidence¶

The WTE (rwscd_rt_wte or rwscd_pid_device_wte) is a signed attestation made by the Remote WSCD that attest the validity of the cryptographic keys it manages. The Wallet Trust Evidenence (WTE) is then used by the Wallet Instance towards Issuers. The WTE reuses the key attesattion as described in OpenID4VCI Annex D.

It's JWT Header contains: - alg: A digital signature algorithm identifier that signed the key attestation - typ: key-attestation+jwt - x5c: The X.509 Certificate chain of the Remote WSCD using rwscd_wte_auth_prvk / rwscd_wte_auth_pubk

It's JWT payload contains: - iat: Integer for the time at which the key attestation was issued using the syntax defined in [RFC7519]. - exp: Integer for the time at which the key attestation and the key it is attesting expire, using the syntax defined in [RFC7519]. - attested_keys: Array containing the created keys rwscd_pid_device_pubk[] - key_storage: Array containing the value iso_18045_high if our Remote WSCD meets the assurance level. - user_authentication: Array containing the value iso_18045_high if our Remote WSCD meets the assurance level. - nonce: an optional nonce provided by the Issuer as c_nonce from the Nonce Endpoint and send by the Wallet to the Remote WSCD through the Secure Area interface - status: not used yet until we implement revocation chaining

Below is a non-normative example of a rwscd_rt_wte or rwscd_pid_device_wte: { "typ": "key-attestation+jwt", "alg": "ES256", "x5c": ["MIIDQjCCA..."] } . { "iss": "https://remote-wscd.com", "iat": 1516247022, "exp": 1541493724, "key_storage": [ "iso_18045_high" ], "user_authentication": [ "iso_18045_high" ], "nonce": "wKI4LT17ac15ES9bw8ac4", "attested_keys": [ { "kty": "EC", "crv": "P-256", "x": "TCAER19Zvu3OHF4j4W4vfSVoHIP1ILilDls7vCeGemc", "y": "ZxjiWWbZMQGHVWKVQ4hbSIirsVfuecCE6t4jT9F2HZQ" }, { "kty": "EC", "crv": "P-256", "x": "18wHLeIgW9wVN6VD1Txgpqy2LszYkMf6J8njVAibvhM", "y": "-V4dS4UaLMgP_4fY4j8ir7cl1TXlFdAgcx55o7TkcSA" } ] }

Authenticated Remote WSCD Operations¶

This section describes the operations (wi_rwscd_operation_request and rwscd_operation_result), supported by the Remote WSCD. All operations are synchronous, stateless and require user authentication.

Operation	Description
Create Keys	Create one or more cryptographic keys in the KMS and optionally a WTE, e.g. for PID device binding keys or for refresh token keys.
Sign Data	Sign data with a cryptographic key stored in the KMS, e.g. for creating proof of possessions for PID presentation or refresh token usage.
Delete Keys	Delete one or more keys in the KMS, e.g. after presentation of a single-use credential.
Change PIN	Change the RWSCD PIN used as the knowledge factor for authentication.
Delete Account	Delete all data that is stored or related to a wallet instance, including all keys stored in the KMS.
Supported Algorithms	Provide a list of all supported cryptographic algorithms, user for negotiation with PID and EAA Providers.