Cryptography¶
Description of the cryptographic methods for achieving the security objectives, in particular the key management and the configuration of the cryptographic methods.
ToDo¶
- add chapter for communication channels and TLS (including details of TLS pinning)
- replace PIN caching with session management operated by RWSCD
- add chapter for Wallet Unit Attestations which documents the cryptographic primitives for ensuring security of a Wallet Unit (WI, WSCA, WSCD)
- add lifetimes of keys and artifacts of authentication means
- add chapter crypto agility
Identification Means, Authentication Means, and 2FA¶
Electronic identification means is defined by eIDAS Regulation (EU) No 2024/1183 as “a material and/or immaterial unit containing person identification data and which is used for authentication for an online service or, where appropriate, for an offline service”. The identification means consists of a refresh token which contains the identity attributes in an PP-encrypted and PP-authenticated form, and several PID credentials which contain the identity attributes in a PP-authenticated form. The refresh token and PID credentials are each bound to an authentication means via a public/private key pair (rwscd_rt_pubk / rwscd_rt_prvk, rwscd_pid_device_pubk / rwscd_pid_device_prvk). Authenticity of the PID credentials is ensured via signing by the PP (pp_pid_auth_prvk). Authenticity of the refresh token is ensured via a method up to the PP.
The authentication means consists of the public/private key pairs (rwscd_rt_pubk / rwscd_rt_prvk, rwscd_pid_device_pubk / rwscd_pid_device_privk) managed in a RWSCD and a 2FA that authenticates the user to their corresponding user account in the RWSCD and is used to unlock the creation of public/private key pairs for the user or unlock signing operations with the public/private key pairs for the user.
The 2FA consists of a possession factor in the form of a public/private key pair in a hardware-backed key store (wi_rwscd_auth_pubk/ wi_rwscd_auth_prvk) in the user's smartphone and a knowledge factor (user_rwscd_pin) that is entered via the WI and is used to derive a public/private key pair (wi_rwscd_pin_pubk/ wi_rwscd_pin_privk) at runtime. The possession of both private keys is evaluated in the RWSCD (which is part of the WP) using proof of possessions.
The following picture illustrates the relations between the various entities and their keys and artifacts:
Primitives¶
| Name | Type | Scheme | Lenght (bits) | Generation | Storage | Exchange | Destruction | Usage |
|---|---|---|---|---|---|---|---|---|
| rwscd_account_id | UUID_v4 | RFC9562 | 128 | RWSCD | WI / RWSCD DB | TLS | unlimited, destruction when WI is deleted | account identifier for a RWSCD user account |
| rwscd_rt_prvk | asymmetric | ECDSA | 256 | HSM | HSM encrypted in DB of KMS | - | lifetime t.b.d. | sign PoP of Refresh Token |
| rwscd_rt_pubk | asymmetric | ECDSA | 256 | HSM | PP authenticated in Refresh Token | TLS | lifetime t.b.d. | verify PoP of Refresh Token |
| rwscd_pid_device_prvk | asymmetric | ECDSA | 256 | HSM | HSM encrypted in DB of KMS | - | lifetime t.b.d., destruction after one usage | sign PoP of a single PID Credential |
| rwscd_pid_device_pubk | asymmetric | ECDSA | 256 | HSM | PP authenticated in PID Credential | TLS | lifetime t.b.d. | verify PoP of a single PID Credential |
| wi_rwscd_auth_prvk | asymmetric | ECDSA | 256 | HKS | HKS | - | lifetime t.b.d. | sign PoP of possession factor of 2FA |
| wi_rwscd_auth_pubk | asymmetric | ECDSA | 256 | HKS | HKS / RWSCD DB | TLS | lifetime t.b.d. | verify PoP of possession factor of 2FA |
| wi_rwscd_pin_prvk | asymmetric | ECDSA | 256 | WI | cashed in WI for short time | - | lifetime t.b.d. | sign PoP of knowledge factor of 2FA |
| wi_rwscd_pin_pubk | asymmetric | ECDSA | 256 | WI | RWSCD DB | TLS | lifetime t.b.d | verify PoP of knowledge factor of 2FA |
| wi_rwscd_pin_salt | symmetric | AES | 128 | WI | WI | - | lifetime t.b.d | used as salt for derivation of wi_rwscd_pin key pair from rwscd_PIN |
RWSCD PIN¶
The RWSCD PIN (user_rwscd_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 WSCD, as described in
Key Derivation¶
The asymmetric key pair (wi_rwscd_pin_prvk, wi_rwscd_pin_pubk) as the knowledge factor is derived anew each time the RWSCD PIN (user_rwscd_pin) is entered in the following way:
- The user_rwscd_pin is entered into the WI by the user via the system input of the mobile device's operating system.
- The PIN (user_rwscd_pin) and a salt (wi_rwscd_pin_salt, stored in the app context) are input into a HKDF function to derive the ECDSA private key wi_rwscd_pin_prvk.
- The RWSCD PIN is deleted from memory.
- Derive the public key wi_rwscd_pin_pubk from the private key wi_rwscd_pin_prvk using platform-provided cryptography libraries.
The wi_rwscd_pin_prvk may cached for short time, see section Caching
Retry Counter¶
The retry counter for the RWSCD PIN is managed on the Remote WSCD with the following configuration:
- retry limit for the RWSCD PIN is 10, which implies that the authentication means will be blocked after 10 failed attempts.
- the retry counter increases without delay for the first three attempts. After that, an exponential back-off is applied on every subsequent failed attempt:
- 0 to 3: no delay
- 4: 1 minute
- 5: 5 minutes
- 6: 15 minutes
- 7: 1 hour
- 8: 3 hours
- 9: 8 hours
- 10: blocked
- the retry counter is reset after a successful PIN verification
- the retry counter is securely stored in the RWSCD backend
- 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.
Caching¶
The Remote WSCD does not create any session token after using its API, instead every request is authenticated with the two-factor-authentication, which is usually fine as most transactions performed by the wallet only require a single interaction with the Remote WSCD. However, certain transactions may require multiple interactions with the Remote WSCD API. To enable multiple operations with the Remote WSCD and to require the user to enter his RWSCD PIN only once for every transaction, the derived RWSCD PIN key wi_rwscd_pin_priv may be cached on the client side (wallet).
The WI MUST clear the RWSCD PIN cache by deleting the derived RWSCD PIN key (wi_rwscd_pin_priv) on the following situations: 1. if a transaction is successfully completed 2. if a non-recoverable error occurs during the transaction 3. 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) 4. if the cache is older than 5 minutes (if the RWSCD PIN is required after the 5 minutes, the wallet app should show the UI and ask the user again to enter the RWSCD PIN)
The last option to delete the cache after 5 minutes acts as a last resort/watch dog. If the RWSCD PIN cache is deleted by other means, the 5 minute timer should be canceled.
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)
ECDSA¶
For the used cryptographic ECDSA algorithms and curves, see Cryptographic algorithms in the Blueprint for the EUDI Wallet Ecosystem in Germany.