Skip to content

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.

Issuance of a Refresh Token used as a Seed Credential

[Sequence Diagram] Issuance of a Refresh Token used as a Seed Credential

User Journey: PID Issuance - Issuer Signed - Cloud

PID Issuance of the Refresh Token over OpenID4VCIPID Issuance of the Refresh Token over OpenID4VCIPID HolderUser.s EUDI Wallet BackendUser.s EUDI Wallet Instance .eID-Client.PID ProviderPID HolderPIN: (user_pin)PID HolderPIN: (user_pin)User's EUDI Wallet BackendLong-term Key: (wb_device_pub,wb_device_priv)User's EUDI Wallet BackendLong-term Key: (wb_device_pub,wb_device_priv)User's EUDI Wallet Instance (eID-Client)Device Key: (device_pub,device_priv)Wallet Attestation bound towb_device_pubPIN Salt:pin_saltUser's EUDI Wallet Instance (eID-Client)Device Key: (device_pub,device_priv)Wallet Attestation bound towb_device_pubPIN Salt:pin_saltPID Provider(eService+eID Server)Long-term Key: (pp_pub,pp_priv)eID data encryption Key: (pp_data)PID Provider(eService+eID Server)Long-term Key: (pp_pub,pp_priv)eID data encryption Key: (pp_data)(001)open wallet, unlock walletScreen: launch_walletScreen: unlock_wallet(002)request issuance of PIDScreen: credential_catalogPID Issuer and EUDI Wallet have inherenttrust relationship, metadata may bepre-configured or retrieved(003)[TLS] HTTP POST</session_endpoint>pid_issuer_session_id(004)generate and storepid_issuer_session_id(005)[TLS] HTTP 200<pid_issuer_session_id>Screen: consent_add_credentialcheck pin(006)[TLS] HTTP POST</session_endpoint>wallet_backend_session_id(007)generate and storewallet_backend_session_id(008)[TLS] HTTP 200<wallet_backend_session_id>(009)enter Wallet PINScreen: wallet_pin(010)derive key pair(pin_derived_eph_pub,pin_derived_eph_priv) fromKDF(Wallet PIN,encrypt_AES(pin_salt, WalletPIN))(011)generate PoP for pin derivedephemeral key -sign(wallet_backend_session_id| device_pub)pin_derived_eph_priv(012)generate PoP for wallet app'skey -sign(wallet_backend_session_id|pin_derived_eph_pub)device_privproof must be built from both the device keyand the key derived from the user PIN, mightrequire new proof typeRemote HSM(013)prepare wallet attestation POPwith audience, expiration timeand pid_issuer_session_id(014)hash wallet attestation PoP(015)[TLS] HTTP POST <UUID,issuer_ID, PoP for pin derivedephemeral key, PoP for walletapp's key, hash of walletattestation PoP>(016)load instance information forUUIDInstance Information: retry counter,pin_derived_eph_pub, device_pub, securityrelevant device attributes(017)check user pin retryrequest would be refused in case of lockedpin(018)check security of deviceagainst VulnerabilityManagement informationPIN will not be validated if device is known tobe insecure(019)check signaturesuser pin retry counter would be increased incase of failed pin signature check, user pinwould be locked after threshold is exeeded(020)sign hash of wallet attestationPoP with wb_device_priv(021)[TLS] HTTP 200 <send signedhash of wallet attestation PoP,wallet_backend_session_id>(022)assemble wallet attestationPoP(023)[TLS] HTTP POST PAR (PKCEcode_challenge, WalletAttestation + PoP, client_id)(024)verify wallet attestation & PoPcheck Wallet Provider solutionstatus on trust list(025)[TLS] HTTP 200 request_uriAttestation guarantees with high certaintythat Wallet is trustworthy and notmanipulated(026)[TLS] HTTP GET <OpenID4VCIAuthorizationRequest(request_uri)>Screen: eid_startRead eID or Smart eID acc. to BSI TR-03130(027)[TLS] HTTP 200 starting theeID Process(028)eID Process(029)<eID-PIN>Screen: eid_pin(030)eID Process(031)[TLS] HTTP GET finishing theeID process with refreshUrlScreen: eid_nfc_data(032)[TLS] HTTP 302 <OpenID4VCIAuthorizationResponse(authorizationcode)>Generate initial DPoP nonce(033)generate placeholder DPoPproof with generic (notHSM-bound) key pair(034)[TLS] HTTP POST <TokenRequest(DPoP Header withplaceholder proof,authorization code, PKCEcode_verifier)>(035)generate and storedpop_nonce(036)[TLS] HTTP 400 <Bad Request(DPoP nonce Header withdpop_nonce, error:"use_dpop_nonce")>The Wallet should check at this point,whether the Token Endpoint delivered theexpected error and nonce. If not, this needsto be handled (retry or abort gracefully).(037)store dpop_nonceRemote HSM(038)prepare DPoP-proof JWT forHSM bound key incl.dpop_nonce(039)hash(DPoP-proof JWT for HSMbound key)(040)[TLS] HTTP POST <hash ofPoP,wallet_backend_session_id>(041)checkwallet_backend_session_id(042)sign hash of PoP withwb_dpop_priv (associated withUUID & Issuer_ID)(043)[TLS] HTTP 200 <signed hashof proof>(044)assemble DPoP-proof JWT forHSM bound key with signature(045)[TLS] HTTP POST <TokenRequest(DPoP Header withproof JWT incl. wb_dpop_puband key attestation,authorization code, PKCEcode_verifier)>(046)lookup authorization code verify PKCE challenge verify DPoP proof verify key attestation forDPoP proof(047)create refresh token bound towb_dpop_priv in JWT formatwith eID data symmetricallyencrypted with pp_data andits expiration date and sign the refresh tokenJWT with pp_priv(048)generate and storedpop_nonce(049)generate Token Responsewith access and refresh tokenDPoP bound to wb_dpop_privand fresh dpop_nonce(050)[TLS] HTTP 200 <TokenResponse(DPoP nonce headerwith dpop_nonce, DPoP-boundaccess_token, DPoP-boundrefresh_token)>The access token and the refresh token areboth bound to the same key.(051)store DPoP bound access andrefresh token(052)store dpop_nonceScreen: successScreen: home

[Step-by-Step Description] Issuance of a Refresh Token used as a Seed Credential

  1. The user opens and unlocks the Wallet
  2. The user browses through the pre-configured credential catalog and chooses to request a PID
  3. The Wallet requests a fresh pid_issuer_session_id from the PID Provider
  4. The PID Provider generates a fresh pid_issuer_session_id linked to the issuance session
  5. The PID Provider returns the pid_issuer_session_id to the Wallet
  6. The Wallet obtains fresh wallet_backend_session_id from the Wallet Backend's session endpoint.
  7. part of an above module
  8. part of an above module
  9. The User enters the Wallet PIN
  10. The Wallet proves possession of the Wallet PIN
    • See "Wallet proving possession of the PIN" module for a detailed description of the steps
  11. part of an above module
  12. part of an above module
  13. The Wallet prepares a Wallet Attestation PoP; containing
    • audience
    • expiration time
    • pid_issuer_session_id
  14. The Wallet hashes the prepared Wallet Attestation PoP
  15. The Wallet sends a request to the Wallet Backend; containing
    • UUID & Issuer_ID
    • PoP for pin_derived_eph_priv
    • PoP for device_priv
    • Hash of the Wallet Attestation PoP
  16. The Wallet Backend checks Wallet Instance.
  17. part of an above module
  18. part of an above module
  19. The Wallet Backend validates the PoP for pin_derived_eph_pub and device_pub
  20. The Wallet Backend signs the hash of Wallet Attestation PoP with wb_device_priv
  21. The Wallet Backend returns the request to the Wallet; containing:
    • signed hash of Wallet Attestation PoP
  22. The Wallet assembles the Wallet Attestation PoP using the signature received in a previous step
  23. 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
    • a wallet attestation and proof of possession
  24. 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
  25. The PID Provider returns a request_uri that is bound to the Pushed Authorization Request
  26. The Wallet sends the Authorization Request; containing the PAR request_uri
  27. The PID Provider responds with the first step to start the eID process with the Wallet, e.g. the tcToken, to authenticate the user.
  28. Further communication is exchanged to perform the eID process
  29. The user provides the eID PIN to the Wallet.
  30. Further communication is exchanged to perform the eID process
  31. 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.
  32. The PID Provider responds to the Wallet with an Authorization Response; containing the authorization code.
  33. 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.
  34. The Wallet sends a Token Request to the PID Provider; containing the placeholder DPoP proof.
  35. The PID Provider generates and stores a dpop_nonce.
  36. 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.
  37. The Wallet extracts and stores the dpop_nonce.
  38. The Wallet now prepares the actual DPoP-proof JWT for the HSM-bound wb_dpop_pub including the dpop_nonce and iat.
  39. The Wallet hashes the DPoP proof.
  40. The Wallet sends a request to the Wallet Backend to sign the hash of the DPoP-proof for the HSM bound key; containing
    • hash of the PoP for the HSM bound key
    • wallet_backend_session_id
  41. The Wallet Backend validates the wallet_backend_session_id and loads session context
  42. 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
  43. The Wallet Backend returns the signed hash of the PoP for the HSM bound key to the Wallet.
  44. The Wallet assembles the DPoP-proof for the HSM bound key using the signature received in a previous step
  45. 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
    • key attestation for wb_dpop_pub
  46. The PID Provider matches the code, verifies the PKCE code_verifier to the previously received code_challenge and verifies the DPoP proof.
  47. 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
    • the expiration date of the refresh token
  48. The PID Provider generates and stores a fresh dpop_nonce.
  49. The PID Provider generates a Token Response; containing
    • DPoP-bound access token (bound to wb_dpop_priv)
    • DPoP-bound refresh token (bound to wb_dpop_priv)
    • a c_nonce
    • a fresh dpop_nonce in the DPoP nonce header
  50. The PID Provider sends the Token Response to the Wallet
  51. The Wallet stores the access and the refresh token.
  52. The wallet stores the dpop_nonce.

Issuance of a Batch of PIDs

[Sequence Diagram] Issuance of a Batch of PIDs

PID Batch Credential Issuance over OpenID4VCIPID Batch Credential Issuance over OpenID4VCIPID HolderUser.s EUDI Wallet BackendUser.s EUDI Wallet Instance .eID-Client.PID ProviderPID HolderPIN: (user_pin)PID HolderPIN: (user_pin)User's EUDI Wallet BackendLong-term Key: (wb_attestation_pub,wb_attestation_priv)Long-term Key: (wb_device_pub,wb_device_priv)User's EUDI Wallet BackendLong-term Key: (wb_attestation_pub,wb_attestation_priv)Long-term Key: (wb_device_pub,wb_device_priv)User's EUDI Wallet Instance (eID-Client)Device Key: (device_pub,device_priv)Wallet Attestation bound towb_device_pubPIN Salt:pin_saltUser's EUDI Wallet Instance (eID-Client)Device Key: (device_pub,device_priv)Wallet Attestation bound towb_device_pubPIN Salt:pin_saltPID Provider(eService+eID Server)Long-term Key: (pp_pub,pp_priv)eID data encryption Key: (pp_data)PID Provider(eService+eID Server)Long-term Key: (pp_pub,pp_priv)eID data encryption Key: (pp_data)(001)open wallet, unlock walletScreen: launch_walletScreen: unlock_wallet(002)request issuance of PID BatchCredentialscheck pin and generate batch keys(003)[TLS] HTTP POST</session_endpoint>pid_issuer_session_id(004)generate and storepid_issuer_session_id(005)[TLS] HTTP 200<pid_issuer_session_id>(006)[TLS] HTTP POST</session_endpoint>wallet_backend_session_id(007)generate and storewallet_backend_session_id(008)[TLS] HTTP 200<wallet_backend_session_id>(009)enter Wallet PINScreen: wallet_pin(010)derive key pair(pin_derived_eph_pub,pin_derived_eph_priv) fromKDF(Wallet PIN,encrypt_AES(pin_salt, WalletPIN))(011)generate PoP for pin derivedephemeral key -sign(wallet_backend_session_id| device_pub)pin_derived_eph_priv(012)generate PoP for wallet app'skey -sign(wallet_backend_session_id|pin_derived_eph_pub)device_privproof must be built from both the device keyand the key derived from the user PIN, mightrequire new proof type(013)[TLS] HTTP POST<CredentialRequest(UUID,issuer_ID, PoP for pin derivedephemeral key, PoP for walletapp's key)>(014)load instance information forUUIDInstance Information: retry counter,pin_derived_eph_pub, device_pub, securityrelevant device attributes(015)check user pin retryrequest would be refused in case of lockedpin(016)check security of deviceagainst VulnerabilityManagement informationPIN will not be validated if device is known tobe insecure(017)check signaturesuser pin retry counter would be increased incase of failed pin signature check, user pinwould be locked after threshold is exeeded(018)generate cryptographic seed(c_seed) for batch credentialsand associate with issuer_ID(019)derive X key pairs (incl. keyIDs) (keyIDx,(batch_kb_X_pub,batch_kb_X_priv))deterministically from c_seed(020)assembleCloudWalletBatchKey claimwith X tuples (keyIDx,batch_kb_X_pub) and signwith wb_attestation_priv(021)[TLS] HTTP 200 <signedCloudWalletBatchKey,wallet_backend_session_id>Remote HSM(022)generate wallet attestationPOP with audience, expirationtime, CloudWalletBatchKeyand pid_issuer_session_id(023)hash wallet attestation PoP(024)[TLS] HTTP POST <hash ofwallet attestation PoP,wallet_backend_session_id>(025)validatewallet_backend_session_idand load session context(026)sign hash of wallet attestationPoP with wb_device_priv(027)[TLS] HTTP 200 <signature forhash of wallet attestationPoP>(028)assemble wallet attestationPoP with signaturePID batch issuancealt[Noorstale DPoP nonce](029)generate placeholder DPoPproof with generic (notHSM-bound) keypair(030)[TLS] HTTP POST <TokenRequest(DPoP Header withplaceholder proof,authorization code, PKCEcode_verifier)>(031)generate and storedpop_nonce(032)[TLS] HTTP 400 <Bad Request(DPoP nonce Header withdpop_nonce, error:"use_dpop_nonce")>(033)store dpop_nonceRemote HSM(034)prepare DPoP-proof JWT forHSM bound key incl.dpop_nonce(035)hash(DPoP-proof JWT for HSMbound key)(036)[TLS] HTTP POST <hash ofPoP,wallet_backend_session_id>(037)checkwallet_backend_session_id(038)sign hash of PoP withwb_dpop_priv (associated withUUID & Issuer_ID)(039)[TLS] HTTP 200 <signed hashof proof>(040)assemble DPoP-proof JWT forHSM bound key with signature(041)[TLS] HTTP POST <TokenRequest(wallet attestationand wallet attestation PoP, DPoP-proof JWT overwb_dpop_pub, grant_type=refresh_token,DPoP bound refresh token)>wallet attestation Header includes Walletattestation and PoP. DPoP Header includesDPoP proof JWT. refresh_token contains theeID data encrypted with pp_pub(042)verify wallet attestation & PoPcheck Wallet Provider solutionstatus on trust list(043)verify the validity of therefresh token (incl.DPoP-binding)(044)decrypt refresh tokencontents with pp_data andstore user data in session(045)generate and storedpop_nonce(046)generate Token Responsewith DPoP-boundaccess_token(047)[TLS] HTTP 200 <TokenResponse(DPoP nonce headerwith dpop_nonce, DPop boundaccess_token, c_nonce)>(048)prepare X batch credentialkey PoPs (incl. audience,batch_kb_X_pub, c_nonce)and hash them(049)[TLS] HTTP POST<BatchSigningRequest(Xhashed PoPs,wallet_backend_session_id)>(050)validatewallet_backend_session_idand load session context(051)sign hashed PoPs X withbatch_kb_X_priv(052)[TLS] HTTP 200 <X signedhashed PoPs>(053)assemble XCredentialRequests withsigned batch credential keyPoPsRemote HSM(054)prepare DPoP-proof JWT forHSM bound key incl.dpop_nonce(055)hash(DPoP-proof JWT for HSMbound key)(056)[TLS] HTTP POST <hash ofPoP,wallet_backend_session_id>(057)checkwallet_backend_session_id(058)sign hash of PoP withwb_device_priv (associatedwith UUID & Issuer_ID)(059)[TLS] HTTP 200 <signed hashof proof>(060)assemble DPoP-proof JWT forHSM bound key with signature(061)generate credential responseencryption key pair(cre_eph_pub, cre_eph_priv)(062)createcredential_response_encryptionobject with jwk containingcre_eph_pub(063)[TLS] HTTP POST <BatchCredential Request (DPoPHeader with proof, XCredentialRequests,credential_response_encryptionobject, DPoP-boundaccess_token)>(064)validate DPoP-boundaccess_token and checksignatures of theCredentialRequest proofsensure that the batch_kb_X_pub from theCredentialRequests match to the public keysin the CloudWalletBatchKey claim from thewallet attestation PoPalt[ISO mdoc](065)create mdoc with eID dataand batch_kb_X_pub, signedby pp_priv, and matchingNameSpaceBytes(066)generate encrypted credentialresponse JWT using the valuesreceived in thecredential_response_encryptionobject(067)generate and storedpop_nonce(068)[TLS] HTTP 200 <BatchCredential Response(DPoPnonce Header withdpop_nonce, JWT(mdoc))>[SD-JWT VC](069)create SD-JWT VC with eIDdata and batch_kb_X_pub,signed by pp_priv, andmatching Disclosures(070)generate encrypted credentialresponse JWT using the valuesreceived in thecredential_response_encryptionobject(071)generate and storedpop_nonce(072)[TLS] HTTP 200 <BatchCredential Response(DPoPnonce Header withdpop_nonce, JWT(SD-JWT VC,Disclosures))>(073)decrypt batch credentialresponse JWT and retrieve PID(074)match keyIDx fromCloudWalletBatchKey claim toSD-JWT/mdoc Credentials bytheir respective public key(batch_kb_X_pub) and storeas tuple inBatchCredentialStore withissuer_ID(075)store dpop_nonce

[Step-by-Step Description] Issuance of a Batch of PIDs

  1. The user opens and unlocks the Wallet.
  2. The Wallet requests issuance of PID Batch Credentials.
  3. The Wallet requests fresh wallet_backend_session_id
  4. The Wallet Backend generates and links it to the session
  5. The Wallet Backend returns the wallet_backend_session_id to the Wallet
  6. The Wallet requests a fresh pid_issuer_session_id from the Wallet Backend
  7. The Wallet Backend generates a fresh wallet_backend_session_id linked to the session
  8. The Wallet Backend returns the pid_issuer_session_id to the Wallet
  9. The user enters the Wallet PIN.
  10. The Wallet proves possession of the Wallet PIN
    • See "Wallet proving possession of the PIN" module for a detailed description of the steps
  11. part of an above module
  12. part of an above module
  13. 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
  14. The Wallet Backend checks Wallet Instance.
  15. part of an above module
  16. part of an above module
  17. The Wallet Backend validates the PoP for pin_derived_eph_pub and device_pub.
  18. 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
  19. 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
  20. 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.
  21. The Wallet Backend returns the request to the Wallet; containing
    • the signed CloudWalletBatchKey
  22. The Wallet prepares a Wallet Attestation PoP containing
    • the audience,
    • the signed CloudWalletBatchKey claim and
    • the pid_issuer_session_id.
  23. The Wallet hashes the Wallet Attestation PoP.
  24. The Wallet sends a signing request to the Wallet Backend containing
    • hash of the Wallet Attestation PoP
    • wallet_backend_session_id
  25. The Wallet Backend validates the wallet_backend_session_id and loads the session context.
  26. The Wallet Backend signs the hash of the Wallet Attestation PoP with the respective wb_device_priv.
  27. The Wallet Backend returns the request to the Wallet incl. the signed hash of the Wallet Attestation PoP.
  28. The Wallet assembles the Wallet Attestation PoP using the signature received in a previous step.
  29. 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.
  30. The Wallet sends a Token Request to the PID Provider; containing the placeholder DPoP proof.
  31. The PID Provider generates and stores a dpop_nonce.
  32. 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.
  33. The Wallet extracts and stores the dpop_nonce.
  34. The Wallet prepares the DPoP-proof JWT for the HSM-bound wb_attestation_pub including the dpop_nonce and iat.
  35. The Wallet hashes the DPoP proof.
  36. 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
  37. The Wallet Backend validates the wallet_backend_session_id and loads the session context.
  38. 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.
  39. The Wallet Backend returns the signed hash of the PoP for the HSM bound key to the Wallet.
  40. The Wallet assembles the DPoP-proof for the HSM bound key using the signature received in a previous step.
  41. 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",
    • the DPoP-bound refresh token
  42. 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
  43. The PID Provider verifies the validity of the refresh token (incl. DPoP-binding).
  44. The PID Provider decrypts the refresh token contents with //pp_data// and stores the users identity attributes in the session.
  45. The PID Provider generates and stores a dpop_nonce.
  46. The PID Provider generates a Token Response with a DPop bound access token.
  47. The PID Provider returns a Token Response to the Wallet containing
    • the DPoP bound access_token and
    • the c_nonce
    • a fresh dpop_nonce in the DPoP nonce header.
  48. The Wallet prepares the required number of PoP (incl. audience and respective public key) for the batch credential keys and hashes them.
  49. 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.
  50. The Wallet Backend validates the wallet_backend_session_id and loads the session context.
  51. The Wallet Backend signs the hashed batch credential key PoPs with the respective batch_kb_X_priv.
  52. The Wallet Backend returns the request to the Wallet incl. the signed hashes of the batch credential key PoPs.
  53. The Wallet assembles the required amount of CredentialRequests containing the signed batch credential key PoPs.
  54. The Wallet prepares the DPoP-proof JWT for the HSM-bound //dev// key including the dpop_nonce and iat.
  55. The Wallet hashes the DPoP proof.
  56. 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.
  57. The Wallet Backend validates the wallet_backend_session_id and loads the session context.
  58. 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.
  59. The Wallet Backend returns the signed hash of the PoP for the HSM bound key to the Wallet.
  60. The Wallet assembles the DPoP-proof for the HSM bound key using the signature received in a previous step.
  61. The Wallet generates a new ephemeral keypair (cre_eph_pub, cre_eph_priv).
  62. The Wallet creates the credential_response_encryption JSON object containing the following information:
    • a jwk containing the cre_eph_pub
    • the JWE alg parameter
    • the JWE enc parameter
  63. The Wallet sends a BatchCredentialRequest to the PID Provider containing
    • DPoP proof JWT
    • required amount of CredentialRequests
    • credential_response_encryption object
    • DPoP bound access_token
  64. 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.
  65. (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
  66. (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.
  67. The PID Provider generates and stores a fresh dpop_nonce.
  68. (mdoc) The PID Provider sends the Credential Response JWT containing
    • the required amount of PID credentials as mdoc.
  69. (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
  70. (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.
  71. The PID Provider generates and stores a fresh dpop_nonce.
  72. (SD-JWT) The PID Provider sends the Credential Response JWT containing
    • the required amount of PID credentials as SD-JWT VC.
  73. The Wallet decrypts the Credential Response JWT using the cre_eph_priv.
  74. 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.
  75. The Wallet extracts and stores the dpop_nonce.

Credential Presentation

[Sequence Diagram] Credential Presentation

User Journey: PID Presentation - Issuer Signed - Cloud

PID presentation over OpenID4VPPID presentation over OpenID4VPPID HolderBrowser AppRelying PartyUser.s EUDI Wallet Instance .eID-Client.User.s EUDI Wallet BackendPID HolderPIN: (user_pin)PID HolderPIN: (user_pin)Browser App(same device)Browser App(same device)Relying PartyLong-term Key: (rp_pub,rp_priv)Relying PartyLong-term Key: (rp_pub,rp_priv)User's EUDI Wallet Instance (eID-Client)Device Key: (device_pub,device_priv)Wallet Attestation bound towb_device_pubPIN Salt:pin_saltUser's EUDI Wallet Instance (eID-Client)Device Key: (device_pub,device_priv)Wallet Attestation bound towb_device_pubPIN Salt:pin_saltUser's EUDI Wallet BackendLong-term Key: (wb_attestation_pub,wb_attestation_priv)Long-term Key: (wb_device_pub,wb_device_priv)User's EUDI Wallet BackendLong-term Key: (wb_attestation_pub,wb_attestation_priv)Long-term Key: (wb_device_pub,wb_device_priv)(001)browse to applicationScreen: same_device_relying_party_start(002)[TLS] HTTP GET <rp-website>(003)generate ephemeral key pair(rp_eph_pub, rp_eph_priv)(004)create OpenID4VPAuthorization Request, sign with rp_priv, store under <request_uri>Authorization Request includes:- presentation_definition- purpose- state- nonce- rp_eph_pub- response_uri(005)generate new browser sessionsessionId and bind theauthorization request to it(006)[TLS] HTTP 200 HTMLcontaining wallet-linkopenid4vp://authorize?")client_id=..&request_uri=<request_uri>Set-Cookie: sid=sessionId(007)action to start flow/launchwallet(008)launch with wallet-linkopenid4vp://Potential security risk: Wallet app may bespoofed by malicious appScreen: launch_wallet(009)unlock walletmay be moved to later point in flow orremoved, see notes.Screen: unlock_wallet(010)[TLS] HTTP GET<request_uri>Potential privacy risk: RP learns existance ofwallet app and potentially identifyinginformation (e.g., headers)(011)[TLS] HTTP 200 <JWT-SecuredAuthorization Request>(012)validate AuthorizationRequest JWT using rp_pub(013)user consent to present PID toRelying Party for givenpurposeScreen: consent_present_credential(014)pick batch credential tuple(Credential, keyIDx) frombatch credential storealt[ISO mdoc](015)prepare mdoc presentationaccording to<presentation_definition> byremoving unnecessaryNameSpaceBytes(016)calculate SessionTranscript(mDocGeneratedNonce,client_id, responseUri, nonce)and generate deviceAuthpayload and hash[SD-JWT VC](017)prepare SD-JWT presentationaccording to<presentation_definition> byremoving unnecessaryDisclosures(018)generate KB-JWT payload(nonce, audience, hash ofSD-JWT and disclosures) andhashcheck pin & sign in remote HSM(019)[TLS] HTTP POST</session_endpoint>wallet_backend_session_id(020)generate and storewallet_backend_session_id(021)[TLS] HTTP 200<wallet_backend_session_id>(022)input Wallet PINScreen: wallet_pin(023)generate key pair(pin_derived_eph_pub,pin_derived_eph_priv) fromKDF(Wallet PIN,encrypt_AES(pin_salt, WalletPIN))(024)generate PoP for pin derivedephemeral key -sign(wallet_backend_session_id| device_pub)pin_derived_eph_priv(025)generate PoP for wallet app'skey -sign(wallet_backend_session_id|pin_derived_eph_pub)device_priv(026)[TLS] HTTP POST <UUID,issuer_ID, PoP for pin derivedephemeral key, PoP for walletapp's key, hash ofKB-JWT/deviceAuth , keyIDx>(027)load instance information forUUIDInstance Information: retry counter,pin_derived_eph_pub, device_pub, securityrelevant device attributes(028)check user pin retryrequest would be refused in case of lockedpin(029)check security of deviceagainst VulnerabilityManagement informationPIN will not be validated if device is known tobe insecure(030)check signaturesuser pin retry counter would be increased incase of failed pin signature check, user pinwould be locked after threshold is exeeded(031)identify c_seed with issuer_IDand load(032)deterministically regenerate(batch_kb_X_pub,batch_kb_X_priv) from c_seedand keyIDx(033)sign hash ofKB-JWT/deviceAuth hash withbatch_kb_X_priv(034)[TLS] HTTP 200 <signedKB-JWT/deviceAuth hash>alt[ISO mdoc](035)assemble deviceAuth andbuild presentation withissuerSigned anddeviceSigned(deviceAuth)[SD-JWT VC](036)assemble KB-JWT and buildpresentation with SD-JWT,selected Disclosures andKB-JWT(037)create vp_token andpresentation_definition(038)add optionally otherpresentations according tothe presentation_definition(039)delete used batch credentialand matching keyIDx(040)[TLS] HTTP POST<AuthorizationResponse(presentation_submission,vp_token, state)>(041)look up state in existingsessionscreate & store response_codefor session(042)[TLS] HTTP 200 <redirect_uriincl. response_code>(043)launch browser with<redirect_uri withresponse_code>Screen: success_redirect(044)[TLS] HTTP GET <redirect_uriwith response_code>Cookie: sid=sessionId(045)look up session with sessionIdand match response_codealt[ISO mdoc](046)verify contents of<vp_token>:- verify mdoc issuerAuth PID- verify deviceAuth withbatch_kb_X_pub fromissuerAuth- calculate and validatecorrect SessionTranscript[SD-JWT VC](047)verify contents of<vp_token>:- verify SD-JWT PID- verify KB-JWT withbatch_kb_X_pub from SD-JWT- validate nonce and audiencefrom KB-JWT(048)[TLS] HTTP 200 <HTML withcontinued UX flow>Screen: same_device_relying_party_identified

[Step-by-Step Description] Credential Presentation

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.

  1. The user browses to Relying Party (RP) website
  2. Browser app on the user's device opens the RP website
  3. RP generates an ephemeral key pair (e.g., rp_eph_pub, rp_eph_priv)
  4. RP generates an OpenID4VP Authorization Request and stores it under a request_uri (e.g., https://rp.example.com/oidc/request/1234);
  5. The request is bound to the user's browser session
  6. It is signed using a key bound to the RP's metadata that can be retrieved using the RP's client_id
  7. It contains the ephemeral key for response encryption
  8. It contains RP's nonce and state
  9. It contains the RP's response_uri endpoint for sending the Authorization Response over POST
  10. RP generates a new browser session and binds the generated Authorization Request to it
  11. 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); a cookie with the browser sessionId is set
  12. The user clicks on the link
  13. The RP website navigates to the custom scheme link to launch the Wallet
  14. The user unlocks the Wallet (see notes below)
  15. The Wallet sends a GET request to the RP's Authorization Request endpoint (e.g., https://rp.example.com/oidc/request/1234)
  16. The Wallet retrieves the Authorization Request from the RP website
  17. 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.
  18. The Wallet displays information about the identity of the Relying Party and the purpose, the user gives consent to present the PID.
  19. The Wallet picks a batch credential tuple (Credential incl. possible disclosures, keyID) from the batch credential store
  20. (mdoc) The Wallet prepares an mdoc presentation according to the presentation_definition by removing NameSpaceBytes of not disclosed attributes.
  21. (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.
  22. (SD-JWT) The Wallet generates an SD-JWT VC presentation according to the presentation_definition by removing Disclosures of not disclosed attributes.
  23. (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.
  24. The Wallet requests a fresh wallet_backend_session_id from the Wallet Backend
  25. The Wallet Backend generates a fresh wallet_backend_session_id linked to the session
  26. The Wallet Backend returns the wallet_backend_session_id to the Wallet
  27. The User enters the Wallet PIN
  28. The Wallet proves possession of the Wallet PIN
    • See "Wallet proving possession of the PIN" module for a detailed description of the steps
  29. The Wallet signs over the wallet_backend_session_id and the device-bound public key device_pub using the key pin_derived_eph_priv
  30. 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
  31. The Wallet sends a signing request to the Wallet Backend; containing
    • UUID & issuer_ID
    • PoP for pin_derived_eph_priv
    • PoP for device_priv
    • hash of KB-JWT/deviceAuth
    • keyID (of the respective key that should be used to sign)
  32. The Wallet Backend checks Wallet Instance.
  33. part of an above module
  34. part of an above module
  35. The Wallet Backend validates the PoP for pin_derived_eph_pub and device_pub
  36. The Wallet Backend loads the c_seed associated with the issuer_ID
  37. 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
  38. The Wallet Backend signs the hash of KB-JWT/deviceAuth with the respective batch_kb_X_priv
  39. The Wallet Backend returns the signed hashes of KB-JWT/deviceAuth to the Wallet
  40. (mdoc) The Wallet assembles the deviceAuth from header, payload and signature and builds the presentation from deviceAuth and issuerSigned
  41. (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
  42. The Wallet creates a VP token and a presentation submission from the received credential.
  43. Optional: The Wallet can add further presentations
  44. The Wallet deletes the used batch credential tuple (credential, keyID)
  45. The Wallet sends the VP token and presentation submission to the RP (encrypted to the RP's public key rp_eph_pub).
  46. The RP finds a session with the state and generates a response_code for this session
  47. The RP returns the redirect_uri with the response_code to the Wallet
  48. The Wallet launches the browser with the redirect_uri and response_code.
  49. The browser sends the redirect_uri and response code to the RP, attaching the browser sessionId as a cookie.
  50. The RP looks up whether there exists a session with the sessionId from the cookie and a matching response_code
  51. (mdoc) The RP verifies the PID in the VP token and verifies the SessionTranscript calculated from nonce, mDocGeneratedNonce, client_id, response_uri.
  52. (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
  53. The RP considers the user to be identified in the session context and continues the UX flow.