Ecosystem Architecture

Person Identification Data (PID)

Runtime Views

Basic Idea

In this flow, long-lived, digitally signed PID credentials in ISO mdoc and IETF SD-JWT VC formats are issued to the Wallet Instance utilizing the OpenID4VCI protocol. During the issuance, the user is authenticated using the eID card, so when these PID credentials are presented to the Relying Parties over OpenID4VP protocol, there is no need for the user to use physical eID card. This flow trusts using Wallet Backend to manage keys on behalf of the Wallet Instance, under the assumption that keys managed on the mobile device cannot be secured in a way that is appropriate for Level of Assurance High (unlike Option C).

To improve user experience and prevent the users from tapping an eID card every time a batch of Credentials needs to be refreshed and tapping an eID card as many times as there are Credentials in a batch, a concept of Seed Credential is introduced. A Seed Credential is used to acquire a set of single-use Batch Credentials from the Provider. The Wallet can then present these Batch Credentials to the Relying Parties. The user only needs to present the physical ID card once - to acquire the Seed Credential - instead of every presentation.

Such Seed Credential is issued by a PID Provider to the Wallet as a signed DPoP-bound refresh token and can be stored for a longer period. The key from the wallet backend, that the refresh token is bound to, is stored and managed by an HSM in the wallet backend (WSCD) instead of the wallet device itself.

Wallet Attestation PoP and DPoP Proof are bound to the keys managed by a wallet backend, but since they contain session specific information (audience and a nonce/session id) that should be known only to the wallet instance from a privacy perspective, to generate a signature, the wallet instance sends only a ready-to-be-signed hash to the wallet backend. Wallet Attestation PoP and DPoP Proof require key attestation for the keys that they are bound to.

Cryptographic Keys

Prefixes

Prefix	Meaning
wb_	Wallet Backend
pp_	PID Provider

Prefix	Meaning
rp_	Relying Party
device_	Wallet Instance

Long-Term keys

Key	Meaning
$device\_pub, device\_priv$	Wallet Instance generates locally managed key pair which is used to bind the PIN proof to the device.
$pin\_salt$	Wallet Instance generates AES key which is used to derive the pin_derived_eph_priv used as PoP of Wallet PIN.
$wb\_attestation\_pub_wa, wb\_attestation\_priv_wa$ $wb\_attestation\_pub_kbp, wb\_attestation\_priv_kbp$ $wb\_attestation\_pub_ks, wb\_attestation\_priv_ks$ $wb\_attestation\_pub_kd, wb\_attestation\_priv_kd$	Wallet Backend has key pairs with postfixes which are each used: - to sign wallet instance's wallet attestations: _wa - to sign key attestation for the key that a PID is bound to: _kbp - to sign key attestation for the key that a seed credential is bound to: _ks - to sign key attestation for the key that a DPoP Proof is bound to: _kd.
$wb\_device\_pub, wb\_device\_priv$	Wallet Backend generates the key pair which is used to sign proof of possession of wallet attestation.
$wb\_dpop\_pub, wb\_dpop\_priv$	Wallet Backend generates the HSM bound key pair which is used to generate DPoP proof (a key to which refresh token used as a seed credential is bound to).
$pp\_pub, pp\_priv$	PID Provider has the HSM bound long-term key pair to sign over the issued Credential and to sign over the Refresh Token JWT.
$pp\_data$	PID Provider has this symmetric long-term key which is used to encrypt eID data inside the refresh token.
$rp\_pub, rp\_priv$	Relying Party has this long-term key pair which is used to sign over the authorization request, authenticating its contents.

Note (not normative for Wallet implementations)

The following sequence diagrams include, among other things, user interactions with the Wallet. These interactions are not normative; only the depicted data flows are normative.

Issuance of a Refresh Token used as a Seed Credential

Sequence Diagram

-> Visual Example of the User Journey: PID Issuance - Issuer Signed - Cloud

Step-by-Step Description

No	Description
001	The user opens and unlocks the Wallet.
002	The user browses through the pre-configured credential catalogue and chooses to request a PID.
003	The Wallet requests a fresh pid_issuer_session_id from the PID Provider.
004	The PID Provider generates a fresh pid_issuer_session_id linked to the issuance session.
005	The PID Provider returns the pid_issuer_session_id to the Wallet.
006	The Wallet obtains fresh wallet_backend_session_id from the Wallet Backend's session endpoint.
007	Part of the above-mentioned module.
008	Part of the above-mentioned module.
009	The User enters the Wallet PIN.
010	The Wallet proves possession of the Wallet PIN {See "Wallet proving possession of the PIN" module for a detailed description of the steps).
011	Part of the above-mentioned module.
012	Part of the above-mentioned module.
013	The Wallet prepares a Wallet Attestation PoP containing audience, expiration time and pid_issuer_session_id
014	The Wallet hashes the prepared Wallet Attestation PoP.
015	The Wallet sends a request to the Wallet Backend containing UUID & Issuer_ID, PoP for pin_derived_eph_priv, PoP for device_priv and hash of the Wallet Attestation PoP
016	The Wallet Backend checks Wallet Instance.
017	Part of the above-mentioned module.
018	Part of the above-mentioned module.
019	The Wallet Backend validates the PoP for pin_derived_eph_pub and device_pub.
020	The Wallet Backend signs the hash of Wallet Attestation PoP with wb_device_priv.
021	The Wallet Backend returns the request to the Wallet containing signed hash of Wallet Attestation PoP.
022	The Wallet assembles the Wallet Attestation PoP using the signature received in a previous step.
023	The Wallet sends the Pushed Authorization Request to the PID Provider, containing the Wallet Provider's client_id, authorization_details for PID, a PKCE code_challenge and a wallet attestation and proof of possession.
024	The PID Provider verifies the wallet attestation and its proof of possession and validates the certification status of the Wallet Solution on a trust list.
025	The PID Provider returns a request_uri that is bound to the Pushed Authorization Request.
026	The Wallet sends the Authorization Request; containing the PAR request_uri.
027	The PID Provider responds with the first step to start the eID process with the Wallet, e.g. the tcToken, to authenticate the user.
028	Further communication is exchanged to perform the eID process.
029	The user provides the eID PIN to the Wallet.
030	Further communication is exchanged to perform the eID process.
031	The eID process is finished and as a final step the Wallet sends a request to the PID Provider calling the refreshURL. From now on Wallet and PID Provider are using the TLS-PSK channel generated by the eID flow.
032	The PID Provider responds to the Wallet with an Authorization Response containing the authorization code.
033	The Wallet generates (and stores) a placeholder DPoP proof with a generic (not HSM-bound) keypair to trigger an error response from the Token endpoint necessary to retrieve the dpop_nonce.
034	The Wallet sends a Token Request to the PID Provider; containing the placeholder DPoP proof.
035	The PID Provider generates and stores a dpop_nonce.
036	The PID Provider responds with the expected error "use_dpop_nonce" containing the dpop_nonce to be used from now in the DPoP nonce header.
037	The Wallet extracts and stores the dpop_nonce.
038	The Wallet now prepares the actual DPoP-proof JWT for the HSM-bound wb_dpop_pub including the dpop_nonce and iat.
039	The Wallet hashes the DPoP proof.
040	The Wallet sends a request to the Wallet Backend to sign the hash of the DPoP-proof for the HSM bound key containing the hash of the PoP for the HSM bound key and the wallet_backend_session_id.
041	The Wallet Backend validates the wallet_backend_session_id and loads session context.
042	The Wallet Backend signs the hash of the PoP for the HSM bound key with wb_dpop_priv (associated with UUID & Issuer_ID) from the HSM.
043	The Wallet Backend returns the signed hash of the PoP for the HSM bound key to the Wallet.
044	The Wallet assembles the DPoP-proof for the HSM bound key using the signature received in a previous step.
045	The Wallet sends a Token Request to the PID Provider containing a DPoP Header with the DPoP-proof JWT incl. wb_dpop_pub, the authorization code from Authorization Response, the PKCE code_verifier matching the code_challenge from Authorization Request and the.key attestation for wb_dpop_pub.
046	The PID Provider matches the code, verifies the PKCE code_verifier to the previously received code_challenge and verifies the DPoP proof.
047	The PID Provider then generates an access token and a refresh token bound to the DPoP key wb_dpop_priv in JWT format, signed with pp_priv containing the eID data encrypted with pp_data and the expiration date of the refresh token.
048	The PID Provider generates and stores a fresh dpop_nonce.
049	The PID Provider generates a Token Response containing the DPoP-bound access token (bound to wb_dpop_priv), the DPoP-bound refresh token (bound to wb_dpop_priv), a c_nonce and a fresh dpop_nonce in the DPoP nonce header.
050	The PID Provider sends the Token Response to the Wallet.
051	The Wallet stores the access and the refresh token.
052	The wallet stores the dpop_nonce.

Issuance of a Batch of PIDs

Sequence Diagram

Step-by-Step Description

No	Description
001	The user opens and unlocks the Wallet.
002	The Wallet requests issuance of PID Batch Credentials.
003	The Wallet requests fresh wallet_backend_session_id.
004	The Wallet Backend generates and links it to the session.
005	The Wallet Backend returns the wallet_backend_session_id to the Wallet.
006	The Wallet requests a fresh pid_issuer_session_id from the Wallet Backend
007	The Wallet Backend generates a fresh wallet_backend_session_id linked to the session.
008	The Wallet Backend returns the pid_issuer_session_id to the Wallet.
009	The user enters the Wallet PIN.
010	The Wallet proves possession of the Wallet PIN. See "Wallet proving possession of the PIN" module for a detailed description of the steps.
011	Part of the above-mentioned module.
012	Part of the above-mentioned module.
013	The Wallet sends a Credential Request to the Wallet Backend containing the UUID & the Issuer_ID, the PoP for pin_derived_eph_priv and the PoP for device_priv.
014	The Wallet Backend checks Wallet Instance. See Issuance of Wallet Instance Attestation (WIA)¶ for a detailed description of the steps.
015	Part of the above-mentioned module.
016	Part of the above-mentioned module.
017	The Wallet Backend validates the PoP for pin_derived_eph_pub and device_pub.
018	The Wallet Backend generates a cryptographic seed (c_seed) for the batch credential keys and associates it with Issuer_ID. Each batch of credentials uses it's own c_seed, previous c_seeds are discarded when a new batch of credentials for a specific Issuer are requested.
019	The Wallet Backend deterministically derives the required number of key pairs incl. key IDs from c_seed. A mechanism for key derivation will be defined later.
020	The Wallet Backend assembles a claim called CloudWalletBatchKey containing the public part of the just generated key pairs and the respective key IDs and signs the claim with wb_attestation_priv.
021	The Wallet Backend returns the request to the Wallet; containing the signed CloudWalletBatchKey.
022	The Wallet prepares a Wallet Attestation PoP containing the audience, the signed CloudWalletBatchKey claim and the pid_issuer_session_id.
023	The Wallet hashes the Wallet Attestation PoP.
024	The Wallet sends a signing request to the Wallet Backend containing the hash of the Wallet Attestation PoP and the wallet_backend_session_id.
025	The Wallet Backend validates the wallet_backend_session_id and loads the session context.
026	The Wallet Backend signs the hash of the Wallet Attestation PoP with the respective wb_device_priv.
027	The Wallet Backend returns the request to the Wallet incl. the signed hash of the Wallet Attestation PoP.
028	The Wallet assembles the Wallet Attestation PoP using the signature received in a previous step.
029	The Wallet generates (and stores) a placeholder DPoP proof with a generic (not HSM-bound) keypair to trigger an error response from the Token endpoint necessary to retrieve the dpop_nonce.
030	The Wallet sends a Token Request to the PID Provider; containing the placeholder DPoP proof.
031	The PID Provider generates and stores a dpop_nonce.
032	The PID Provider responds with the expected error "use_dpop_nonce" containing the dpop_nonce to be used from now in the DPoP nonce header.
033	The Wallet extracts and stores the dpop_nonce.
034	The Wallet prepares the DPoP-proof JWT for the HSM-bound wb_attestation_pub including the dpop_nonce and iat.
035	The Wallet hashes the DPoP proof.
036	The Wallet sends a request to the Wallet Backend to sign the hash of the DPoP-proof for the HSM bound key containing a hash of the PoP for the HSM bound key.
037	The Wallet Backend validates the wallet_backend_session_id and loads the session context.
038	The Wallet Backend signs the hash of the PoP for the HSM bound key with wb_device_priv (associated with UUID & Issuer_ID) from the HSM.
039	The Wallet Backend returns the signed hash of the PoP for the HSM bound key to the Wallet.
040	The Wallet assembles the DPoP-proof for the HSM bound key using the signature received in a previous step.
041	The Wallet sends a Token Request to the PID Provider containing the Wallet Attestation + PoP in the wallet attestation Header, the DPoP-proof JWT over wb_attestation_pub, the grant_type "refresh_token" and the DPoP-bound refresh token.
042	The PID Provider verifies the wallet attestation and its proof of possession and validates the certification status of the Wallet Solution on a trust list.
043	The PID Provider verifies the validity of the refresh token (incl. DPoP-binding).
044	The PID Provider decrypts the refresh token contents with //pp_data// and stores the users identity attributes in the session.
045	The PID Provider generates and stores a dpop_nonce.
046	The PID Provider generates a Token Response with a DPop bound access token.
047	The PID Provider returns a Token Response to the Wallet containing the DPoP bound access_token, the c_nonce and a fresh dpop_nonce in the DPoP nonce header.
048	The Wallet prepares the required number of PoP (incl. audience and respective public key) for the batch credential keys and hashes them.
049	The Wallet sends a BatchSigningRequest to the Wallet Backend containing the required number of hashed batch credential key PoPs and the wallet_backend_session_id.
050	The Wallet Backend validates the wallet_backend_session_id and loads the session context.
051	The Wallet Backend signs the hashed batch credential key PoPs with the respective batch_kb_X_priv.
052	The Wallet Backend returns the request to the Wallet incl. the signed hashes of the batch credential key PoPs.
053	The Wallet assembles the required amount of CredentialRequests containing the signed batch credential key PoPs.
054	The Wallet prepares the DPoP-proof JWT for the HSM-bound //dev// key including the dpop_nonce and iat.
055	The Wallet hashes the DPoP proof.
056	The Wallet sends a request to the Wallet Backend to sign the hash of the DPoP-proof for the HSM bound key containing a hash of the PoP for the HSM bound key and the wallet_backend_session_id.
057	The Wallet Backend validates the wallet_backend_session_id and loads the session context.
058	The Wallet Backend signs the hash of the PoP for the HSM bound key with wb_dpop_priv (associated with UUID & Issuer_ID) from the HSM.
059	The Wallet Backend returns the signed hash of the PoP for the HSM bound key to the Wallet.
060	The Wallet assembles the DPoP-proof for the HSM bound key using the signature received in a previous step.
061	The Wallet generates a new ephemeral keypair (cre_eph_pub, cre_eph_priv).
062	The Wallet creates the credential_response_encryption JSON object containing a jwk containing the cre_eph_pub, the JWE alg parameter and the JWE enc parameter.
063	The Wallet sends a BatchCredentialRequest to the PID Provider containing the DPoP proof JWT, the required amount of CredentialRequests, the credential_response_encryption object and the DPoP bound access_token.
064	The PID Provider validates the DPoP bound access_token and checks the signatures of the CredentialRequests. The PID Provider has to ensure that the batch_kb_X_pub from the CredentialRequests match to the public keys in the CloudWalletBatchKey claim from the Wallet Attestation PoP.
065	(mdoc) The PID Provider creates the mdoc containing the issuerAuth with the batch_kb_X_pub as deviceKey and hashes of the eID data, the eID data as NameSpaceBytes and the status management information.
066	(mdoc) The PID Provider creates an encrypted JWT (JWE) using the values received in the credential_response_encryption object and adds (among others) the PID credential to the payload.
067	The PID Provider generates and stores a fresh dpop_nonce.
068	(mdoc) The PID Provider sends the Credential Response JWT containing the required amount of PID credentials as mdoc.
069	(SD-JWT) The PID Provider creates SD-JWT VC containing the SD-JWT with the batch_kb_X_pub as confirmation claim and hashes of the eID data, the eID data as Disclosures and the status management information.
070	(SD-JWT) The PID Provider creates an encrypted JWT (JWE) using the values received in the credential_response_encryption object and adds (among others) the PID credential to the payload.
071	The PID Provider generates and stores a fresh dpop_nonce.
072	(SD-JWT) The PID Provider sends the Credential Response JWT containing the required amount of PID credentials as SD-JWT VC.
073	The Wallet decrypts the Credential Response JWT using the cre_eph_priv.
074	The Wallet matches the key IDs (from the CloudWalletBatchKey claim) to the public keys in the Credential Response by their respective public keys and stores them as tuple in a BatchCredentialStore with the issuer_ID.
075	The Wallet extracts and stores the dpop_nonce.

Credential Presentation

Sequence Diagram

-> Visual Example of the User Journey: PID Presentation - Issuer Signed - Cloud

Step-by-Step Description

Note: While certain assumptions about session management of the Relaying Party are made here, the concrete implementation is considered out of scope for this document. The usual security considerations for web session management apply.

No	Description
001	The user browses to Relying Party (RP) website.
002	Browser app on the user's device opens the RP website.
003	RP generates an ephemeral key pair (e.g., rp_eph_pub, rp_eph_priv).
004	RP generates an OpenID4VP Authorization Request and stores it under a request_uri (e.g., https://rp.example.com/oidc/request/1234). The request is bound to the user's browser session, it is signed using a key bound to the RP's metadata that can be retrieved using the RP's client_id. It contains the ephemeral key for response encryption. It contains RP's nonce and state. It contains the RP's response_uri endpoint for sending the Authorization Response over POST.
005	RP generates a new browser session and binds the generated Authorization Request to it.
006	RP returns a HTML page to the browser containing a link to the Wallet (e.g., openid4vp://authorize?client_id=..&request_uri=https://rp.example.com/oidc/request/1234) and a cookie with the browser sessionId is set.
007	The user clicks on the link.
008	The RP website navigates to the custom scheme link to launch the Wallet.
009	The user unlocks the Wallet (see notes below).
010	The Wallet sends a GET request to the RP's Authorization Request endpoint (e.g., https://rp.example.com/oidc/request/1234).
011	The Wallet retrieves the Authorization Request from the RP website.
012	The Wallet validates the Authorization Request using the RP's public key. Was the signature valid and the key bound to the RP's metadata? Security: This ensures that the Authorization Request was not tampered with; it does not ensure that the party that sent the Authorization Request is the RP.
013	The Wallet displays information about the identity of the Relying Party and the purpose, the user gives consent to present the PID.
014	The Wallet picks a batch credential tuple (Credential incl. possible disclosures, keyID) from the batch credential store.
015	(mdoc) The Wallet prepares an mdoc presentation according to the presentation_definition by removing NameSpaceBytes of not disclosed attributes.
016	(mdoc) The Wallet calculates the SessionTranscript according to ISO 18013-7 Annex B.4.4 from mDocGeneratedNonce, client_id, responseUri, nonce and generates the deviceAuthentication structure from SessionTranscript and NameSpaceBytes for signing and hashes the deviceAuthentication structure.
017	(SD-JWT) The Wallet generates an SD-JWT VC presentation according to the presentation_definition by removing Disclosures of not disclosed attributes.
018	(SD-JWT) The Wallet creates the header and payload for the KB-JWT from audience, nonce, hash of issuer-signed JWT and Disclosures for signing and hashes the payload.
019	The Wallet requests a fresh wallet_backend_session_id from the Wallet Backend.
020	The Wallet Backend generates a fresh wallet_backend_session_id linked to the session.
021	The Wallet Backend returns the wallet_backend_session_id to the Wallet.
022	The User enters the Wallet PIN.
023	The Wallet proves possession of the Wallet PIN. See "Wallet proving possession of the PIN" module for a detailed description of the steps.
024	The Wallet signs over the wallet_backend_session_id and the device-bound public key device_pub using the key pin_derived_eph_priv.
025	The Wallet signs over the wallet_backend_session_id and the Wallet PIN derived public key pin_derived_eph_pub using the key device_priv.
026	The Wallet sends a signing request to the Wallet Backend containing UUID & issuer_ID, PoP for pin_derived_eph_priv, PoP for device_priv, the hash of KB-JWT/deviceAuth and keyID (of the respective key that should be used to sign).
027	The Wallet Backend checks Wallet Instance. See Issuance of Wallet Instance Attestation (WIA) for a detailed description of the steps.
028	Part of the above-mentioned module.
029	Part of the above-mentioned module.
030	The Wallet Backend validates the PoP for pin_derived_eph_pub and device_pub.
031	The Wallet Backend loads the c_seed associated with the issuer_ID.
032	The Wallet Backend deterministically regenerates (batch_kb_X_pub, batch_kb_X_priv) from c_seed and keyIDx - A mechanism for key derivation will be defined later.
033	The Wallet Backend signs the hash of KB-JWT/deviceAuth with the respective batch_kb_X_priv.
034	The Wallet Backend returns the signed hashes of KB-JWT/deviceAuth to the Wallet.
035	(mdoc) The Wallet assembles the deviceAuth from header, payload and signature and builds the presentation from deviceAuth and issuerSigned.
036	(SD-JWT) The Wallet assembles the KB-JWT from header, payload and signature and builds the SD-JWT VC presentation from issuer-signed JWT, Disclosures and KB-JWT.
037	The Wallet creates a VP token and a presentation submission from the received credential.
038	Optional: The Wallet can add further presentations.
039	The Wallet deletes the used batch credential tuple (credential, keyID).
040	The Wallet sends the VP token and presentation submission to the RP (encrypted to the RP's public key rp_eph_pub).
041	The RP finds a session with the state and generates a response_code for this session.
042	The RP returns the redirect_uri with the response_code to the Wallet.
043	The Wallet launches the browser with the redirect_uri and response_code.
044	The browser sends the redirect_uri and response code to the RP, attaching the browser sessionId as a cookie.
045	The RP looks up whether there exists a session with the sessionId from the cookie and a matching response_code.
046	(mdoc) The RP verifies the PID in the VP token and verifies the SessionTranscript calculated from nonce, mDocGeneratedNonce, client_id, response_uri.
047	(SD-JWT) The RP verifies the SD-JWT PID in the VP token, verifies the KB-JWT using the batch_kb_X_pub in the SD-JWT, and verifies the nonce and audience in the KB-JWT.
048	The RP considers the user to be identified in the session context and continues the UX flow.

Wallet proving possession of the PIN

Generation of a Proof of Knowledge of the Wallet PIN

A PIN-derived ephemeral public key that is needed to validate the signature on this JWT must be included in the jwk header parameter. There must be a JWT header parameter typ with the value being pin_derived_eph_pub_pop. The JWT payload must contain an aud claim whose value is equal to the Wallet backend's Identifier. wallet_backend_session_id must be included in a wallet_backend_session_id parameter.

Below is a non-normative example of a JWT generated as a PoP for pin derived ephemeral key:

{
  "alg": "...",
  "typ": "pin_derived_eph_key_pop",
  "jwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "bPP7f...gW_ao",
    "y": "38_Lg...VUCfW"
  }
}.
{
  "wallet_backend_session_id": "123456",
  "aud": "https://pid-issuer.example.com",
  "device_key": {
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "...",
      "y": "..."
    }
  }
}.[signature by the pin derived ephemeral pub key]

The jwk claim contains the public key of a PIN-derived ephemeral key pair.