Remote WSCA Operations¶

This flow describes various operations provided by the Remote WSCA, 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¶

The RWSCA enables authenticated Wallet Instances to perform secure cryptographic operations on the Remote WSCD (RWSCD). The Remote WSCA (RWSCA) uses two-factor authentication to ensure integrity and authenticity of the requests sent by the Wallet Instance (WI):

The possession factor is based on a hardware-bound key pair from the Hardware-backed Key Store (HKS) of the WI, that is attested by the Mobile Device Vulnerability Management (MDVM). The MDVM issues MDVM tokens that attest to the general security posture of the mobile device. The RWSCA leverages the MDVM tokens to get assurance into the possession factor wi_mdvm_auth_prvk.
The knowledge factor is based on a user-provided 6-digit RWSCA-PIN. The WI uses a locally stored salt to derive a private key, that is used to prove the knowledge factor towards the RWSCA. Neither the RWSCA-PIN nor the PIN-derived key are stored persistently on the Wallet Instance. The RWSCA issues a backend-controlled short-lived PIN session token, to enable caching of the user authentication. As secure PIN management on most mobile devices is challenging, the RWSCA-PIN-derived public key and its retry counter are managed on the Remote WSCA.

The RWSCA provides self-contained, short-lived challenges for replay protection. The WI uses the private keys in a challenge-response pattern to prove the two-factor authentication and sign operation requests towards the RWSCA. Every request is signed by the possession-factor itself, the RWSCA does not use session keys to reduce state for improved scalability.

During the Wallet activation, the WI requests the account creation operation and the RWSCA stores the WI's possession factor in its account database. During the initial PID issuance, the user chooses the RWSCA-PIN, the WI requests the Initialize PIN and Start PIN session operation and the RWSCA sets the knowledge factor. In subsequent user authentications, the WI uses the Start PIN session operation to prove the knowledge factor. In both cases, the RWSCA responds with a PIN session token, that acts as a short-lived session token to cache the successful user authentication with the RWSCA-PIN. During PID issuance or PID presentation, the WI requests Create Key or Sign Data operations, to perform cryptographic operations on the RWSCD and the RWSCA forwards key-related operations to the Remote WSCD after successful authentication of the WI and the user. An overview of supported operations is given in Authenticated Remote WSCA Operations.

The RWSCA queries the RWSCD (HSM) using PKCS#11 requests to create keys and sign data. The WSCD does not store user specific private keys (e.g. rwscd_rt_prvk and rwscd_pid_device_prvk) in its internal storage, as the volume of expected keys will exceed its capacity. Instead, they are securely exported in protected form immediately after generation.

In the key creation process, the WSCA queries the WSCD to generate private keys and export them as wrapped keys (rwscd_wrapped_key) within its secure boundary, which are encrypted and authenticated with the WSCD's master key and only usable from within the WSCD. The WSCA itself binds the wrapped keys to the WI's account id (rwsca_account_id) after successful two-factor authentication by using authenticated encryption to export the authenticated wrapped key (rwsca_bound_wrapped_key) to the WI.

In the signing process, the WI authenticates towards the WSCA with two-factor authentication and provides the authenticated wrapped key (rwsca_bound_wrapped_key). The WSCA verifies the binding of the authenticated wrapped key (rwsca_bound_wrapped_key) to the WI's account (rwsca_account_id) and only then forwards the signing operation to the WSCD using the wrapped key. The WSCD decrypts and verifies the wrapped key within its secure boundary, uses the resulting unwrapped private key to perform the signing operation, and returns the generated signature to the WSCA, which then forwards it to the WI.

Authenticated Remote WSCA Operations¶

The RWSCA offers various operations that are each handled by dedicated endpoints. The "Create Key" and "Sign Data" operations fulfill the definition of "wallet cryptographic operations" as defined by CIR (EU) 2024/2979. The Delete Key operation is not part of the Remote WSCA, as the WI itself can delete rwsca_bound_wrapped_key to enforce key deletion. The operations have different authentication requirements, as listed in table below:

Operation	Authentication	Description
Create Account	possession factor	Create an account for a Wallet Instance by establishing a possession factor for authentication.
Initialize PIN and Start Session	possession factor + RWSCA-PIN	Initializes a PIN-derived public key as a knowledge factor.
Start PIN Session	possession factor + RWSCA-PIN	Proof the knowledge factor using the RWSCA-PIN to receive a PIN session token for two-factor authentication enabled operations.
Create Keys	possession factor	Create one or more cryptographic keys in the HSM and optionally a WTE, e.g. for PID device binding keys or for refresh token keys.
Sign Data	possession factor + PIN Session Token	Sign data using a wrapped cryptographic key that is decrypted within the HSM, e.g. for creating proof of possessions for PID presentation or refresh token usage. This operation requires a PIN session token obtained from the Start PIN Session operation.
Delete Account	possession factor	Delete all data that is stored or related to a wallet instance.

Data Flow¶

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

Create Account¶

In the Create Account operation, the WI provides the MDVM token to authenticate and provide the attested public key as the possession factor for the new account at the RWSCA. This operation is only performed once during wallet activation.

The following table describes the steps of the sequence diagram in more detail:

No	Description
001	The WI determines if its most recent mdvm_token is still valid. 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.
002 - 004	The WI requests a challenge from the RWSCA challenge endpoint, the request is unauthenticated. The RWSCA generates a JSON structure containing a random nonce and a timestamp of the current time and MACs it using a symmetric key (rwsca_mac_symk) as a JSON Web Token (JWT), the resulting structure is the rwsca_auth_challenge. The RWSCA responds to the WI with the rwsca_auth_challenge in the HTTP payload. The WI uses the challenge as an opaque string and does not evaluate the JWT claims. The RWSCA does not store the challenge after creation, thus the operation is stateless.
005	The WI computes a proof of possession by signing the rwsca_auth_challenge for freshness and to enable replay protection and the mdvm_token to provide the possession factor and proof of device authenticity and integrity. The WI signs the proof of possession with the wi_mdvm_auth_prvk. The resulting structure is called wi_rwsca_auth_pop.
006	The WI requests the RWSCA to perform the registration and sends the wi_rwsca_auth_pop to the RWSCA's registration endpoint. The request is unauthenticated (as RWSCA does not know the WI yet at registration).
007	The RWSCA verifies the self-contained rwsca_auth_challenge using its rwsca_mac_symk and validating that the timestamp is within a valid time interval of 0 minute to +5 minutes.
008 - 009	The RWSCA verifies the received mdvm_token with mdvm_attestation_pubk for authenticity and integrity and checks that it is still valid. The RWSCA has a trusted, out-of-band mechanism towards the MDVM to fetch the valid mdvm_attestation_pubk. The RWSCA verifies the received proof of possession for the WI's possession factor (wi_rwsca_auth_pop) using the included wi_mdvm_auth_pubk from the mdvm_token.
010	The RWSCA generates a unique account identifier rwsca_account_id and stores the combination of rwsca_account_id and wi_mdvm_auth_pubk in its database to register the new account. The RWSCA is aware that no knowledge factor has been established at this point and the account is unable to use operations that require two-factor-authentication until the RWSCA-PIN is initialized using the Initialize PIN and Start PIN Session operation.
011	The RWSCA responds with the generated account identifier rwsca_account_id to the WI.
012	The WI stores the received account identifier rwsca_account_id.

Initialize PIN and Start PIN Session endpoints¶

The sequence diagram contains two flows marked as alternatives when they diverge:

1) In the Initialize PIN and Start Session operation, the WI initializes the PIN as a knowledge factor for an existing account. The green section describes steps that are only relevant for this flow. 2) In the Start PIN Session operation the WI performs the user authentication by proving the PIN for it's account. The pink section describes steps that are only relevant for this flow.

The following table describes the steps of the sequence diagram in more detail:

No	Description
001	The WI determines if its most recent mdvm_token is still valid. 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.
002 - 004	The WI requests a challenge from the RWSCA challenge endpoint, the request is unauthenticated. The RWSCA generates a JSON structure containing a random nonce and a timestamp of the current time and MACs it using a symmetric key (rwsca_mac_symk) as a JSON Web Token (JWT), the resulting structure is the rwsca_auth_challenge. The RWSCA responds to the WI with the rwsca_auth_challenge in the HTTP payload. The WI uses the challenge as an opaque string and does not evaluate the JWT claims. The RWSCA does not store the challenge after creation, thus the operation is stateless.
005	The WI requests a RWSCA-PIN (user_rwsca_pin) from the user. The WI validates that the entered user_rwsca_pin matches the PIN security requirements. In particular, it matches the PIN input against a blocklist of trivial, repetitive patterns.
006	Step 006 only occurs in the Initialize PIN and Start Session operation The WI generates a cryptographic, random salt (wi_rwsca_pin_salt), that will be used for the key derivation of the RWSCA-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_rwsca_pin_prvk and wi_rwsca_pin_pubk) which is used as the knowledge factor of the two-factor authentication to the RWSCA for subsequent requests. The WI must use HKDF to derive wi_rwsca_pin_prvk from user_rwsca_pin and wi_rwsca_pin_salt, see PIN derivation. This key pair is never stored in the WI, but must be deleted after its intended usage, see PIN Key Derivation for details. The user_rwsca_pin must be deleted from memory as soon as the wi_rwsca_pin_prvk is derived.
008 - 010	The WI computes a proof of possession by signing the rwsca_account_id for identification, the rwsca_auth_challenge for freshness and to enable replay protection and the mdvm_token to provide the possession factor and proof of device authenticity and integrity. *If the Initialize PIN and Start Session operation is performed the WI additionally adds the derived wi_rwsca_pin_pubk* to the request parameters in Step 008*. The WI signs the proof of possession with the wi_mdvm_auth_prvk* from the MDVM token (the actual possession factor) and with the wi_rwsca_pin_prvk (the knowledge factor). The resulting structure is called wi_rwsca_auth_pop. The proof of possession cross-signs both public keys to bind the authentication factors together. The wi_rwsca_pin_prvk must be deleted from memory as soon as the wi_rwsca_auth_pop is signed.
011	The WI requests the RWSCA to perform the initialize or proof the RWSCA-PIN and sends the wi_rwsca_auth_pop to the RWSCA's Initialize PIN and Start Session/Start PIN Session endpoint. The request is authenticated.
012	The RWSCA verifies the self-contained rwsca_auth_challenge using its rwsca_mac_symk and validating that the timestamp is within a valid time interval of 0 minute to +5 minutes.
013	Step 013 only occurs in the Initialize PIN and Start Session operation The RWSCA fetches the public key for the possession factor wi_mdvm_auth_pubk from the database using the provided account identifier rwsca_account_id included in wi_rwsca_auth_pop.
014	Step 014 only occurs in the Start PIN Session operation The RWSCA fetches the public keys for the possession factor wi_mdvm_auth_pubk and the knowledge factor wi_rwsca_pin_pubk from the database using the provided account identifier rwsca_account_id included in wi_rwsca_auth_pop.
015 - 017	The RWSCA validates the security posture of the WI by verifying the mdvm_token with mdvm_attestation_pubk and checks that it is still valid. The RWSCA has a trusted, out-of-band mechanism towards the MDVM to fetch the valid mdvm_attestation_pubk. The RWSCA verifies the first signature of the received proof of possession (wi_rwsca_auth_pop) for the WI's possession factor using wi_mdvm_auth_pubk from the mdvm_token. Lastly, the RWSCA verifies that the used key wi_mdvm_auth_pubk is the same in wi_rwsca_auth_pop and in the database. This verification must be performed before the PIN validation to prevent denial of service or malicious locking for specific accounts.
018 - 019	Step 018 - 019 only occur in the Initialize PIN and Start Session operation The RWSCA verifies the knowledge factor of the proof of possession (wi_rwsca_auth_pop) by verifying the second signature using the included wi_rwsca_pin_pubk. The RWSCA updates the account belonging to rwsca_account_id authenticated by the possession factor with the wi_rwsca_pin_pubk and an initial retry counter for the PIN in its database to initialize the knowledge factor.
020 - 022	Step 020 - 022 only occur in the Start PIN Session operation The RWSCA fetches the retry counter rwsca_pin_retry_counter from the database using the provided account identifier rwsca_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 rwsca_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 PIN Retry Counter section for details. The RWSCA then verifies the second signature of the proof of possession wi_rwsca_auth_pop using the public key wi_rwsca_pin_pubk from the database. If the verification is successful, the rwsca_pin_retry_counter must be reset to the initial value (maximum retries).
023 - 024	The RWSCA generates a PIN session token rwsca_pin_session_token using rwsca_pin_symk and returns it to the WI.

Create Key, Sign Data and Delete Account endpoints¶

The sequence diagram contains three flows marked as alternatives when they diverge:

1) In the Create Key operation, the WI requests creation a cryptographic key by the RWSCA. The yellow section describes steps that are only relevant for this flow. 2) In the Sign Data operation, the WI requests to sign a data hash for a given key by the RWSCA. The pink section describes steps that are only relevant for this flow. 3) In the Delete Account operation, the WI requests to delete all of it's data by the RWSCA. The grey section describes steps that are only relevant for this flow.

The following table describes the steps of the sequence diagram in more detail:

No	Description
001	The WI determines if its most recent mdvm_token is still valid. 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.
002 - 004	The WI requests a challenge from the RWSCA challenge endpoint using an HTTP POST request, the request is unauthenticated. The RWSCA generates a JSON structure containing a random nonce and a timestamp of the current time and MACs it using a symmetric key (rwsca_mac_symk) as a JSON Web Token (JWT), the resulting structure is the rwsca_auth_challenge. The RWSCA responds to the WI with the rwsca_auth_challenge in the HTTP payload. The WI uses the challenge as an opaque string and does not evaluate the JWT claims. The RWSCA does not store the challenge after creation, thus the operation is stateless.
005 - 007	The WI sets parameters (wi_rwsca_operation_params) depending on the operation: Create Key operation: the WI provides the number of keys, the algorithm (e.g. elliptic curve) and the Issuer-provided nonce //pp_c_nonce//. As the only supported algorithm in the beginning is ES256, the algorithm parameter may be omitted or ignored. Sign Data operation: the WI provides the rwsca_bound_wrapped_key containing the key to sign with, the hash to be signed wi_key_binding_data_hash and a PIN session token rwsca_pin_session_token, that was freshly received from proving the knowledge factor at the Start PIN Session endpoint Delete account operation: no additional parameters required
008	The WI computes a proof of possession by signing the rwsca_account_id for identification of the user, rwsca_auth_challenge for freshness and to enable replay protection, the mdvm_token to prove device authenticity and integrity and the additional operation-specific parameters wi_rwsca_operation_params. The WI signs the proof of possession with the wi_mdvm_auth_prvk. The resulting structure is called wi_rwsca_auth_pop.
009	The WI requests the RWSCA to create keys/sign data/delete the account and sends the wi_rwsca_auth_pop to the RWSCA's respective endpoint. The request is authenticated.
010	The RWSCA verifies the self-contained rwsca_auth_challenge using its rwsca_mac_symk and validating that the timestamp is within a valid time interval of 0 minute to +5 minutes.
011	The RWSCA fetches the public key for the possession factor wi_mdvm_auth_pubk from the database using the provided account identifier rwsca_account_id included in wi_rwsca_auth_pop.
012 - 014	The RWSCA validates the security posture of the WI by verifying the mdvm_token with mdvm_attestation_pubk and checks that it is still valid. The RWSCA has a trusted, out-of-band mechanism towards the MDVM to fetch the valid mdvm_attestation_pubk. The RWSCA verifies the first signature of the received proof of possession (wi_rwsca_auth_pop) for the WI's possession factor using wi_mdvm_auth_pubk from the mdvm_token. Lastly, the RWSCA verifies that the used key wi_mdvm_auth_pubk is the same in wi_rwsca_auth_pop and in the database. This verification must be 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.
015 - 018	Steps 015 - 020 only occur in the Create Key operation The RWSCA performs the following operations for the number of keys requested by the WI in wi_rwsca_operation_params: The RWSCA requests the RWSCD to generate a cryptographic key pair (e.g. rwscd_pid_device_prvk) for the algorithm requested by WI using PKCS#11 function C_GenerateKeyPair. The plaintext private key is never exposed outside the RWSCD. The RWSCA requests the RWSCD to encrypt the private key within the secure boundaries of the HSM using the RWSCD's internal master key rwscd_master_key using PKCS#11 function C_WrapKey, the resulting rwscd_wrapped_key is returned to the RWSCA. This procedure ensures that the private key never exists in plaintext outside the secure hardware boundary of the RWSCD. The RWSCA requests the RWSCD to delete the private key within the secure boundaries of the HSM using PKCS#11 function C_DestroyObject. This ensures that the internal storage of the HSM does not fill up. The WSCA cryptographically binds the wrapped private key rwscd_wrapped_key to the authenticated rwsca_account_id by concatenating and encrypting both values using its own symmetric key rwsca_aead_symk with authenticated encryption (AEAD). The resulting structure is called rwsca_bound_wrapped_key. Each key requested by the WI is individually wrapped by the RWSCD and RWSCA.
019	The RWSCA creates a Wallet Trust Evidence by signing the batch of generated public keys (e.g. rwscd_pid_device_pubk) and the Issuer-provided pp_c_nonce using it's signing key rwscd_wte_auth_prvk inside the RWSCD using PKCS#11 function C_SignInit and C_Sign. As the rwscd_wte_auth_prvk is a long-term key stored in the HSM, it does not need to be imported or destroyed. The resulting rwscd_pid_device_wte assures the Issuer that the corresponding private keys (e.g. rwscd_pid_device_prvk) were generated in the secure hardware boundary of the RWSCD. The Issuer later fetches the rwscd_wte_auth_pubk from a trust list to verify the rwscd_pid_device_wte.
020	Steps 015 - 020 only occur in the Create Key operation The RWSCA responds with the return value of operation containing: the batch of individually wrapped keys rwsca_bound_wrapped_key the batch of corresponding public keys for each wrapped key the Wallet Trust Evidence rwscd_pid_device_wte for the whole batch of public keys
021	Steps 021 - 027 only occur in the Sign Data operation The RWSCA validates the rwsca_pin_session_token using its symmetric key (rwsca_pin_symk). It confirms that the session is still within its validity period (check expiry_time) and that the rwsca_account_id embedded in the token matches the authenticated request.
022 - 023	The RWSCA performs an AEAD decryption on the outer wrapping rwsca_bound_wrapped_key using rwsca_aead_symk. This step retrieves the rwscd_wrapped_key and cryptographically verifies that this specific key is bound to the rwsca_account_id. The RWSCA then verifies that the rwsca_account_id matches to the authenticated request from wi_rwsca_auth_pop.
024 - 027	Steps 021 - 027 only occur in the Sign Data operation The RWSCA performs the following operations to generate the signature: The RWSCA requests the RWSCD to unwrap the wrapped key rwscd_wrapped_key within the secure boundaries of the HSM using the RWSCD's internal master key rwscd_master_key using PKCS#11 function C_UnwrapKey The RWSCA requests the RWSCD to initialize the signature process for the unwrapped key (e.g. rwscd_pid_device_prvk) using PKCS#11 function C_InitSign The RWSCA requests the RWSCD to perform the signature process for the unwrapped key (e.g. rwscd_pid_device_prvk) by providing the data hash (wi_key_binding_data_hash) using PKCS#11 function C_Sign, which returns the signature rwscd_key_binding_signature back to the RWSCA The RWSCA requests the RWSCD to delete the private key within the secure boundaries of the HSM using PKCS#11 function C_DestroyObject. This ensures that the internal storage of the HSM does not fill up. The RWSCA forwards the signature to the WI.
028 - 029	Steps 028 - 039 only occur in the Delete Account operation The RWSCA deletes all data from the WSCA account database corresponding to the rwsca_account_id. It then confirms the successful deletion to the WI. This operation may be triggered by the WI and enables GDPR rights of the user.

RWSCD setup¶

The core of the RWSCD is a Hardware Security Module (HSM), that is used to generate private keys and sign data. The private keys generated in the RWSCD are:

rwscd_rt_prvk (used by the WI in PID issuance)
rwscd_pid_device_prvk (used by the WI in PID issuance and PID presentation)
rwscd_wte_auth_prvk (used by the RWSCA to sign the Wallet Trust Evidence)

Additionally the HSM generates one symmetric key:

rwscd_master_key (used by the RWSCD for key wrapping according to PKCS#11)

More details on the key of the RWSCD and how they fit into the security concept can be found in the cryptography chapter.

The RWSCA and RWSCD use mutual TLS to encrypt and authenticate their communication. Additionally, the PKCS#11 C_Login operation is used to authenticate to a specific HSM partition. The RWSCA client uses PKCS#11 as the API to send requests to the RWSCD.

RWSCA Account database¶

The RWSCA account database stores the necessary information for each Wallet Instance's account:

rwsca_account_id
wi_mdvm_auth_pubk
wi_rwsca_pin_pubk
rwsca_pin_retry_counter

Access to the database is secured by mutual TLS to encrypt and authenticate communication to the WSCA.

RWSCA bound wrapped key¶

The key wrapping of the RWSCA uses JSON Web Encryption (JWE). The rwsca_bound_wrapped_key is using JWE Compact Serialization and contains:

the JWE Protected Header
- JOSE Header typ containing a type value (as recommended by JWT BCP)
- JOSE Header alg indicating direct encryption (symmetric encryption only without encrypting the Content Key to a recipient)
- JOSE Header enc indicating AES-256-GCM
- JOSE Header kid containing a key identifier for rwsca_aead_symk (to allow key rotation)
the empty JWE Encrypted (because we use direct encryption)
the JWE Initialization Vector (this one must be randomized)
the JWE Ciphertext, where the corresponding cleartext is a JSON structure containing:
- iss containing the Issuer URN
- rwsca_account_id containing the rwsca_account_id
- rwscd_wrapped_key containing the base64 encoded rwscd_wrapped_key
the JWE Authentication Tag ensuring the integrity

Below is a non-normative example of a rwsca_bound_wrapped_key:

Protected headers:

{
  "typ": "rwsca_bound_wrapped_key",
  "alg": "dir",
  "enc": "A256GCM",
  "kid": 1
}

Plaintext:

{
  "iss": "german-national-wallet:wallet-backend:sandbox",
  "rwsca_account_id": "d25d00ab-552b-46fc-ae19-98f440f25064",
  "rwscd_wrapped_key": "0Fo6u2feZ11Pd_BmdZMyM72YAeTN35mdDuwkrLDD0cs_Dh6RQEfJRN8QBtjpEqRdceonGwhOcj9JhYnVrCOn6M2TNsjSdQhA1CCykfwtp8TBsjxMB2D7c-XnlBhTZvOHSfUMpw1wX5-3YnavMRlINy57zCf_u7p7yA-LpqY86S1P2Sciacj6fRlk1dhb2DCQUvBpNVk5u3l-aO33GLUf3_pkPP1oCEZ5ROyK6xl6N22cdqP8jY3_1VS5xRqlpheqJI0MslwewmM"
}

Encrypted and authenticated by rwsca_aead_symk

RWSCA PIN¶

The RWSCA PIN (user_rwsca_pin) has the following properties:

it contains exactly 6 digits (0 to 9)
easily guessable PINs are prevented
it has a retry counter managed by the Remote WSCA, as described in PIN Retry Counter

PIN Key Derivation¶

The asymmetric key pair (wi_rwsca_pin_prvk, wi_rwsca_pin_pubk) as the knowledge factor is derived anew each time the RWSCA PIN (user_rwsca_pin) is entered in the following way:

The user_rwsca_pin is entered into the WI by the user via the system input of the mobile device's operating system.
The PIN (user_rwsca_pin) and a salt (wi_rwsca_pin_salt, stored in the app context) are input into a HKDF function to derive the ECDSA private key wi_rwsca_pin_prvk.
The RWSCA PIN is deleted from memory.
Derive the public key wi_rwsca_pin_pubk from the private key wi_rwsca_pin_prvk using platform-provided cryptography libraries.

The private key wi_rwsca_pin_prvk must be deleted as soon as the request for Start PIN Session is signed.

PIN Retry Counter¶

The retry counter for the RWSCA PIN is managed on the Remote WSCA with the following configuration:

The RWSCA PIN authentication mechanism allows a maximum of 10 consecutive PIN verification attempts. Upon the 10^th failed attempt, the authentication means becomes permanently blocked.
the retry counter increases without delay for the first four attempts. After that, an exponential back-off is applied on every subsequent failed attempt:
- 1 to 3: no delay
- 4: 1 minute
- 5: 5 minutes
- 6: 15 minutes
- 7: 1 hour
- 8: 3 hours
- 9: 8 hours
- 10: after this attempt the PIN must be permanently blocked
the retry counter is reset after a successful PIN verification
the retry counter is securely stored by the RWSCA
the PIN verification logic including the look-up and update of the retry counter MUST be implemented as an atomic transaction to prevent race conditions from multiple parallel attempts.

PIN Session Token¶

The WI proves it's RWSCA-PIN towards the RWSCA's Start PIN Session endpoint and in return receives a session token rwsca_pin_session_token. The session token is a self-contained assertion by the RWSCA, that it proved the knowledge factor of the WI. It is bound to a rwsca_account_id and additionally contains an expiry time.

The rwsca_pin_session_token contains:

JOSE Header typ as recommended by JWT BCP
JOSE Header alg indicating HMAC-256
JOSE Header kid: A key identifier for rwsca_pin_symk
JWT Claim iss containing the Issuer URN
JWT Claim exp containing the expiry time of the PIN session
JWT Claim rwsca_account_id containing the rwsca_account_id

Below is a non-normative example of a rwsca_pin_session_token:

Protected headers:

{
  "typ": "rwsca-pin-session-token",
  "alg": "HS256",
  "kid": 1
}

Payload:

{
  "iss": "german-national-wallet:wallet-backend:sandbox",
  "exp": 1726214250,
  "rwsca_account_id": "d25d00ab-552b-46fc-ae19-98f440f25064"
}

Signed by rwsca_pin_symk

The WI MUST delete the rwsca_pin_session_token on the following situations:

if a transaction is successfully completed
if a non-recoverable error occurs during the transaction
if the wallet app is closed or killed by either the user or the operating system (this does not include the user opening other apps and the wallet app going into the background)

The RWSCA should encode the expiry time, such that *rwsca_pin_session_token*s are invalidated after 5 minutes.

The following transactions are defined for the wallet app:

regular issuance flow, e.g. initial PID issuance
regular presentation flow, e.g. PID presentation
presentation flow followed by a re-issuance (details tbd)
presentation during issuance (details tbd)

Remote WSCA Challenge JWT¶

The rwsca_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 rwsca_mac_symk is used for efficiency.

The rwsca_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 rwsca_auth_challenge:

Header

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

Payload

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

Signed by rwsca_mac_symk

Proof of possessions¶

The wi_rwsca_auth_pop is a proof of possession encoded as an HTTP Message Signature. The signature includes the HTTP path all assets mentioned in the sequence diagrams (e.g. rwsca_auth_challenge, rwsca_account_id, ...), signed as either a JSON structure in the HTTP body or in HTTP header. Additionally, the HTTP scheme and path is signed by HTTP Message Signature, which serves as an identifier for the Remote WSCA operations.

The proof of possession also serves to assert the possession factor using the wi_mdvm_auth_prvk and optionally the knowledge factor using wi_rwsca_pin_prvk. Two-factor authentication is realized by multi-signing the same payload with both keys.

Additional details on proof of possessions using HTTP Message signatures, will be added in a dedicated section.

Wallet Trust Evidence¶

The WTE (rwsca_rt_wte or rwsca_pid_device_wte) is a signed attestation made by the Remote WSCA that attest the validity of the cryptographic keys it manages. The Wallet Trust Evidence (WTE) is then used by the Wallet Instance towards Issuers. The WTE reuses the key attestation 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 WSCA 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 WSCA 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 WSCA through the Secure Area interface
status: not used yet until we implement revocation chaining

Below is a non-normative example of a rwsca_rt_wte or rwsca_pid_device_wte:

Headers:

{
  "typ": "key-attestation+jwt",
  "alg": "ES256",
  "x5c": ["MIIDQjCCA..."]
}

Payload

{
  "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"
    }
  ]
}

Signed by rwscd_wte_auth_prvk