Skip to content

PID Issuance

This flow describes the PID issuance process as introduced here and here in the blueprint.

ToDo

  • separate WTEs for mdoc and SD-JWT credentials

Data Flow

This section describes the data flow of the PID issuance in a sequence diagram and a more detailed table. Artifacts in italics are further explained in the data register of the decomposition chapter.

Sequence Diagram

The sequence diagram contains two flows marked as alternatives when they diverge: 1) The initial issuance of a refresh token and PID credentials, where the user authenticates with the eID Card. The yellow section describes steps that are only relevant for this flow. 2) The re-issuance of the PID credentials, where the authentication uses the refresh tokens. The blue section describes steps that are only relevant for this flow.

PID IssuancePID Issuance greensequence numbers for AusweisApp SDKsolid line arrows represent technical functionality, dotted line arrows represent non-technical/user functionalityUserWallet Provider Backend .WB.Remote WSCD .RWSCD.Wallet Instance . App .WI.PID Provider .PP.rwscdUserUserWallet Provider Backend (WB)Wallet Provider Backend (WB)Remote WSCD (RWSCD)Remote WSCD (RWSCD)Wallet Instance / App (WI)Wallet Instance / App (WI)PID Provider (PP)PID Provider (PP)rwscdrwscd(001)open wallet(002)user authenticationalt[Initial issuance](003)request issuance of PID(004)[TLS] fetch PID Issuermetadata pp_meta_data(005)[TLS] authenticate towardsWallet Provider Backend andreceive fresh walletattestation wb_wia(006)[TLS] HTTP POST <challengeendpoint> request for clientattestation challenge(007)generate randompp_wia_pop_nonce(008)[TLS] HTTP 200<pp_wia_pop_nonce>(009)generate wallet attestationPoP wi_wia_pop usingaudience andpp_wia_pop_nonce(010)generatewi_pkce_code_verifier andwi_pkce_code_challenge(011)[TLS] HTTP POST <PushedAuthorizationRequest(wb_client_id,wi_pkce_code_challenge,wb_wia, wi_wia_pop)>(012)verify wb_wia and wi_wia_pop,validate wb_client_id against atrust list, create issuancesession and eID Serversession based on es_tc_tokenand wi_pkce_code_challenge,generate pp_par_request_uripointing to es_tc_token(013)[TLS] HTTP 200pp_par_request_uri(014)[TLS] HTTP GET<AuthorizationRequest(pp_par_request_uri)>(015)[TLS] HTTP 200 starting theeID Process (es_tc_tokencontaining pp_refresh_url)(016)eID Process(017)present eID Card and enteruser_eid_pin(018)eID Process(019)[TLS] HTTP GET<pp_refresh_url>, finishingthe eID process by redirectingto the refresh URL(020)fetch es_eid_data from eIDServer session to issuancesession(021)[TLS] HTTP 302<AuthorizationResponse(pp_authorization_code)>[Re-issuance](022): re-issuance is triggeredautomatically by the walletinstance or manually by theuser(023)generate fake DPoP proof withlocal key wi_fake_dpop(024)[TLS] HTTP POST <TokenRequest(wi_fake_dpop,pp_authorization_code,wi_pkce_code_verifier)>(025)generate randompp_rt_dpop_nonce(026)[TLS] HTTP 400 <Token ErrorResponse(pp_rt_dpop_nonce)>(027)[TLS] perform Remote WSCDregistration to setup accountwith user_rwscd_pin if this isthe very first issuancerequiring Remote WSCD(028)enter user_rwscd_pinalt[Initial issuance](029)[TLS] request Remote WSCDCreate Key operation forrefresh token(030)create (rwscd_rt_pubk,rwscd_rt_prvk) within KMS andrelated Wallet Trust Evidencerwscd_rt_wte usingpp_rt_dpop_nonce and signedby rwscd_wte_auth_prvk(031)[TLS] respond Create Keyoperation <rwscd_rt_pubk,rwscd_key_id, rwscd_rt_wte>(032)prepare DPoP proofwi_rt_dpop for rwscd_rt_prvkand pp_rt_dpop_nonce(033)[TLS] request Remote WSCDSign operation <hashedpayload of wi_rt_dpop> forrwscd_key_id(034)sign (hashed payload ofwi_rt_dpop, rwscd_rt_prvk)(035)[TLS] respond Sign operation<signature of wi_rt_dpop(036)assemble wi_rt_dpop frompayload and signaturealt[Initial issuance](037)[TLS] HTTP POST <TokenRequest(pp_authorization_code,wi_pkce_code_verifier,wi_rt_dpop, rwscd_rt_wte)>(038)validate authorization codeverify PKCE challengegenerate pp_access_tokenand pp_refresh_token boundto rwscd_rt_pubk(039)[TLS] HTTP 200 <TokenResponse(pp_access_token,pp_refresh_token)>[Re-issuance](040)[TLS] authenticate towardsWallet Provider Backend andreceive fresh walletattestation wb_wia(041)[TLS] HTTP OPTIONS <PARendpoint> request for nonce(042)generate randompp_wia_pop_nonce(043)[TLS] HTTP 200<pp_wia_pop_nonce>(044)generate wallet attestationPoP wi_wia_pop usingaudience andpp_wia_pop_nonce(045)[TLS] HTTP POST <TokenRequest(pp_refresh_token,wi_rt_dpop, wb_wia,wi_wia_pop)>(046)validate refresh token,verifywallet attestation wb_wia andwi_wia_pop, validate against atrust list, generatepp_access_token bound torwscd_rt_pubk(047)[TLS] HTTP 200 <TokenResponse(pp_access_token)>(048)[TLS] HTTP POST <NonceRequest()>(049)create random pp_c_nonceand pp_rt_dpop_nonce(050)[TLS] HTTP 200 <NonceResponse(pp_c_nonce,pp_rt_dpop_nonce)>(051)[TLS] request Remote WSCDCreate Key operation fordevice binding key pairs(052)create(rwscd_pid_device_pubk[],rwscd_pid_device_prvk[])within KMS and related WalletTrust Evidencerwscd_pid_device_wte usingpp_c_nonce and signed byrwscd_wte_auth_prvk(053)[TLS] respond Create Keyoperation<rwscd_pid_device_pubk[],rwscd_key_id[],rwscd_pid_device_wte>(054)prepare access token DPoPproof wi_rt_dpop forrwscd_rt_prvk andpp_rt_dpop_nonce(055)[TLS] request Remote WSCDSign operation <hashedpayload of wi_rt_dpop> forrwscd_key_id(056)sign (hashed payload ofwi_rt_dpop, rwscd_rt_prvk)(057)[TLS] respond Sign operation<signature of wi_rt_dpop(058)assemble wi_rt_dpop frompayload and signature(059)[TLS] HTTP POST <CredentialRequest(pp_access_token,wi_rt_dpop,wi_device_key_pubk[],rwscd_pid_device_wte)>(060)validate access token, verifyWallet Trust evidence andvalidate against a trust list(061)create PIDs in mdocpp_pid_credential[] withes_eid_data, bound torwscd_pid_device_pubk[] andsigned with pp_pid_auth_prvk(062)[TLS] HTTP 200 <CredentialResponse(pp_pid_credential[])>(063)[TLS] HTTP POST <CredentialRequest(pp_access_token,wi_rt_dpop,wi_device_key_pubk[],rwscd_pid_device_wte)>(064)validate access token, verifyWallet Trust evidence andvalidate against a trust list(065)create PIDs in SD-JWT VCpp_pid_credential withes_eid_data, bound torwscd_pid_device_pubk[] andsigned with pp_pid_auth_prvk(066)[TLS] HTTP 200 <CredentialResponse(pp_pid_credential[])>(067)store pp_pid_credential[],pp_refresh_token andassociated rwscd_key_ids

Detailed Description

No Description
001 The user opens/launches the Wallet Instance (App).
002 The wallet instance checks whether a platform authenticator is set up for the mobile device to protect it from unauthorised use. If no platform authenticator is set up, the user is asked to first set up a platform authenticator for the mobile device.
003 Steps 003-021 only occur in the initial issuance.
The User explicitly requests a new PID, either because this is the very first PID issuance after installation of the WI or the previous PID and it's refresh token (pp_refresh_token) is expired and the user is required to go through a issuance with user authentication based on the eID Card.
004 The Wallet Instance fetches OpenID4VCI Credential Issuer and Authorization Server metadata from the PID Provider to obtain relevant configuration parameters needed for the issuance. The WI and PP are always communcicating via TLS and start a TLS session here. The WI and PP may have an inherent trust relationship and metadata may be pre-configured in the WI.
005 The WI fetches a Wallet Instance Attestation from its Wallet Provider Backend as described in the WIA issuance flow. This step may also happen before the issuance process and the WI has some WIAs cached.
006 - 008 The Wallet Instance requests a challenge from the PID Provider (PP) for the generation of the Wallet Instance Attestation PoP. The challenge guarantees freshness of the presentation to the PP. The process is described in detail in the challenge retrieval section of Attestation-Based Client Authentication.
009 The WI generates a proof of possession wi_wia_pop for the Wallet Instance Attestation wb_wia, as detailed in the section Wallet Instance Attestation below.
010 The WI generates a PKCE Verifier wi_pkce_code_verifier as a random string and a matching PKCE Challenge wi_pkce_code_challenge as the SHA-256 hash of the wi_pkce_code_verifier. Proof Key for Code Exchange (PKCE) ensures the binding between the Authorization Request and the Token Request.
011 The WI sends a Pushed Authorization Request (PAR) as defined in OpenID4VP to the PP to start the OpenID4VCI issuance flow, it contains:
  • the OAuth Client identifier wb_client_id as an identifier for the Wallet Solution (pre-configured by the Wallet app)
  • the Wallet Attestation wb_wia and its corresponding Proof of Possession wi_wia_pop
  • the PKCE Challenge wi_pkce_code_challenge
The wb_client_id should match to the subject of wb_wia.
012 The PP verifies the Wallet Instance Attestation (wb_wia) and its Proof-of-Possession (wi_wia_pop) and validates the wb_client_id using a trusted list of authorized wallet solutions. PP generates an issuance session to store the wi_pkce_code_challenge and starts a session with the eID Server coupled to the issuance session based on es_tc_token as described in BSI TR-03124-1. PP generates a pp_par_request_uri that points to es_tc_token.
013 The PP responds with the pp_par_request_uri that points to es_tc_token.
014 The WI sends an Authorization Request by calling pp_par_request_uri to fetch es_tc_token.
015 The PP response with (a URL to) es_tc_token. The es_tc_token contains all information required to establish a trustworthy channel ("tc") between the WI as eID Client and the eID-Server for reading the eID Card. es_tc_token contains es_refresh_url, which points to the eID Server session coupled with the issuance session for the final redirect to the PP.
016 The ES (eID Server), the WI (eID Client) and the eID Card communicate through the protocols defined by BSI TR-03127 and TR-03110. The eID Client side is implemented using the AusweisApp SDK using the integrated flow.
017 The user presents its eID card to the WI by using NFC and enters it's eID Card PIN (user_eid_pin) to authorize the PP to read the data. The user may either present a "Personalausweis" (nPA) as a German citizen or an "Elektronischer Aufenthaltstitel" (eAT) as a citizen with non-EU nationality.
018 See 016. As part of the user authentication process using the eID Card, es_eid_data is read from the eID Card and stored in the eID session on the eID Server.
019 After the eID data groups have been read by the ES, the final step of the eID Client on the WI is to call an HTTP GET to the pp_refresh_url.
020 The PP fetches es_eid_data from the eID Server using the established session from the tcToken and stores it temporarily with this issuance session.
021 Steps 003-021 only occur in the initial issuance.
The PP returns the Authorization Response, which contains the authorization code (pp_authorization_code). This Authorization Response in the context of OpenID4VCI is not to be confused with the OpenID4VP Authorization Response.
022 Step 022 only occurs in the re-issuance with refresh token.
The WI starts the re-issuance flow either because the user's previously issued PID credentials are expired or used up (as they are one-time use). This may be explicitly requested by the user itself (e.g. after being notified by the WI) or the WI may trigger itself, e.g. after previous PID presentation through the user. The user presence is required for re-issuance as both the refresh token keys and PID device binding keys require authentication towards the Remote WSCD with the RWSCD-PIN.
023 - 026 To sender-constrain the access token, the WI sends a Token Request with a DPoP Proof generated by a local key to the PP. The PP generates a random DPoP nonce (pp_rt_dpop_nonce) and responds with an HTTP 400 error containing pp_rt_dpop_nonce because the Token Request did not yet contain a DPoP nonce. Unfortunately, the DPoP protocol does not allow any other mechanism to fetch a nonce other than through an error.
027 The WI checks if it has already set-up an account at the Remote WSCD. If this PID issuance is the very first process requiring the Remote WSCD, then the WI performs the Remote WSCD registration and let's the user set-up his RWSCD PIN (user_rwscd_pin). The lifecycle, retry counter, caching policy and other details about the RWSCD PIN are described in the Cryptography chapter.
028 The WI prompts the user to enter its RWSCD-PIN to authorize all operations with the Remote WSCD required for the issuance process.
029 - 031 Steps 029-031 only occur in the initial issuance.
The WI requests the Remote WSCD Create Key operation authenticating with two factor authentication that was established during Remote WSCD registration. The Remote WSCD generates the key pair (rwscd_rt_prvk, rwscd_rt_pubk) and a Wallet Trust Evidence (rwscd_rt_wte) attesting the key and responds to the WI with the public key rwscd_rt_pubk and the corresponding rwscd_rt_wte. The key to secure refresh tokens is created within the RWSCD instead of the WI, as the refresh token is authorizing issuance of the PID credentials and therefore requires high assurances that may not be met by WI. The Wallet Trust Evidence is ensuring that the key originates from the Remote WSCD's HSM and meets requirements to a certain attack potential resistance. The Remote WSCD uses rwscd_wte_auth_prvk to sign the WTE and issues the WTE on behalf of the Wallet Provider, such that rwscd_wte_auth_pubk is published on a trust list. The PID Provider can verify the authenticity of the WTE using rwscd_wte_auth_pubk from a trust list.
032 The WI prepares the payload of the DPoP proof used for securely binding of the refresh token and the access token to the RWSCD (wi_rt_dpop). The DPoP Proof contains it's public key rwscd_rt_pubk, the pp_rt_dpop_nonce and the hashed payload as part of an ECDSA signature.
033 - 035 The WI requests the Remote WSCD Sign operation authenticating with two factor authentication that was established during Remote WSCD registration to sign the hashed payload for wi_rt_dpop with rwscd_rt_prvk using ECDSA. The authentication of the WI ensures that only the associated account rwscd_account_id has access to the private key rwscd_rt_prvk. The RWSCD then signs the hash ( without knowing the payload) of wi_rt_dpop using rwscd_rt_prvk and responds the signature to the WI.
036 The WI assembles wi_rt_dpop from the payload generated by WI and the signature generated by the RWSCD.
037 Steps 037-039 only occur in the initial issuance.
The WI sends a Token Request to exchange the authorization code for an access/refresh token, it contains:
  • the authorization code (pp_authorization_code) binding it to the issuance session
  • the PKCE Code Verifier (wi_pkce_code_verifier) to proof that the Token Request and the Pushed Authorization Request originate from the same client
  • the DPoP Proof header (wi_rt_dpop) including the WTE (rwscd_rt_wte) to provide a secure key for access/refresh token binding
038 The PP validates the authorization code (pp_authorization_code) and fetches the associated eID data (es_eid_data), it further validates that the PKCE Code Verifier provided in the Token Request matches with the Code Challenge provided during Pushed Authorization Request and validates the provided DPoP Proof for correctness. It then generates an access token (pp_access_token), that shall be used for immediate issuance of PID credentials and a refresh token (pp_refresh_token), that may be used for re-issuance of PID credentials later. Both refresh token and access token are bound to the key (rwscd_rt_pubk) contained in the DPoP Proof (wi_rt_dpop). It is up to the PP implementation, but it is recommended to store the eID Data within the refresh token (and optionally within the access token as well), so that the PP does not need to store this data itself. In that case, the refresh token would be securely signed/MACed for integrity and authenticity, and optionally encrypted for confidentiality. The format of the refresh token is not a subject to standardization, as the producer and consumer of it is the PP.
039 Steps 037-039 only occur in the initial issuance.
The PP responds with the Token Response to the WI, containing the access token (pp_access_token) and the refresh token (pp_refresh_token). The WI must store a mapping between pp_refresh_token and the corresponding public key wi_rt_dpop, as the refresh token is opaque to the WI.
040 - 044 Steps 040-047 only occur in the re-issuance with refresh token.
See 005 - 009.
045 The WI sends a Token Request to exchange the refresh token for an access token, it contains:
  • the refresh token (pp_refresh_token)
  • the DPoP Proof header (wi_rt_dpop) to provide a proof of possession for the refresh token binding
  • the Wallet Attestation wb_wia and its corresponding Proof of Possession wi_wia_pop
  • the PKCE Challenge wi_pkce_code_challenge
The refresh token is recommended to contain the es_eid_data, so that the PID Provider does not need to store them.
046 The PP validates the refresh token (pp_authorization_code) and fetches the associated eID data (pp_refresh_token) using the associated DPoP Proof header (wi_rt_dpop). Furthermore, the PP verifies the wallet attestation and it's PoP and validates it against a trust list of authorized Wallet Solutions. It then generates an access token (pp_access_token), that shall be used for immediate issuance of PID credentials. The access token is bound again to the same key (rwscd_rt_pubk) of the DPoP Proof (wi_rt_dpop). The eID Data necessary for the PID credential issuance is recommended to be contained in the refresh token itself, so that the PP does not need to store this data itself. The PP must verify the integrity and authenticity of the refresh token and optionally decrypt it. The format of the refresh token is not a subject to standardization, as the producer and consumer of it is the PP, see 037.
047 Steps 040-047 only occur in the re-issuance with refresh token.
The PP responds with the Token Response to the WI, containing the access token (pp_access_token).
048 The WI sends a Nonce Request to the Credential Issuer's Nonce Endpoint to obtain an OpenID4VCI c_nonce and DPoP nonce.
049 The PP is generating two random nonces:
  • pp_c_nonce: The c_nonce is used to validate the freshness of device binding proofs and key attestations provided by WI at the Credential Endpoint
  • pp_rt_dpop_nonce: The DPoP nonce is used to validate the freshness of the DPoP proofs provided by WI at the Credential Endpoint. As the Authorization Server and Credential Issuer may be separate entities, we cannot rely on the pp_rt_dpop_nonce received from the Token Endpoint.
Both nonces are not necessarily bound to the issuance session on the PP side, but may be self-contained nonces with a limited lifetime, to increase scalability. The main purpose of the nonces is to guarantee freshness of cryptographic proofs.
050 The PP responds with a Nonce Response containing pp_c_nonce and pp_rt_dpop_nonce. Both nonces may have the same value, but they need to be listed independently to fulfill the issuance protocol.
051 - 053 The WI requests the Remote WSCD Create Key operation to generate the PID device binding keys and a Wallet Trust Evidence. The request is authenticated with two factor authentication that was established during Remote WSCD registration. The Remote WSCD generates the key pairs (rwscd_pid_device_prvk[], rwscd_pid_device_pubk[]) and responds to the WI with the public keys (rwscd_pid_device_pubk[]), the correspponding key ids for the public keys (rwscd_key_id[]) and a Wallet Trust Evidence (rwscd_pid_device_wte) attesting that the private keys (rwscd_pid_device_prvk[]) are managed in the Remote WSCD. The Remote WSCD uses rwscd_wte_auth_prvk to sign the WTE (rwscd_pid_device_wte) and issues the WTE on behalf of the Wallet Provider, such that rwscd_wte_auth_pubk is published on a trust list. The PID Provider can verify the authenticity of the WTE using rwscd_wte_auth_pubk from the trust list.
054 - 058 See 032 - 036.
059 The WI sends a Credential Request to exchange the access token for PID credentials, it contains:
  • the access token (pp_access_token) as the authorization for the issuance session
  • the DPoP Proof header (wi_rt_dpop) to provide a secure key for access token binding
  • the device binding public keys (wi_device_key_pubk[]) and the Wallet Trust Evidence (rwscd_pid_device_wte) to proof the authenticity and attack potential resistance of the device keys.
060 The PP verifies the access token (pp_access_token) and its corresponding DPoP Proof header (wi_rt_dpop). Furthermore it verifies the Wallet Trust Evidence (rwscd_pid_device_wte) of the device binding keys and checks it against a trust list to ensure that the cryptographic keys meet the requirements.
061 The PP generates and signs PID credentials in ISO 18013-5 format (pp_pid_credential[]) for each of the device binding keys wi_device_key_pubk[] provided in the request. The eID data is taken from the issuance session or from the refresh token. The PID credentials are signed with PP's highly secure signing key pp_pid_auth_prvk.
062 The PP responds with a Credential Response containing the PID credentials (pp_pid_credential[]).
063 - 066 See 059 - 062, except for using SD-JWT VC as PID credential format.
067 The WI stores the PID credentials, the refresh token and the associated keys for future use.

Wallet Instance Attestation

For the issuance of a PID, the Wallet Instance must authenticate itself to the PID Issuer using attestation-based client authentication to ensure that only authorized and legitimate Wallets can request PID data. To determine that this authentication mechanism is required, the Wallet Instance evaluates the PID Issuer metadata, specifically the token_endpoint_auth_methods_supported parameter which should contain the value attest_jwt_client_auth.

According to this client authentication method, a Wallet Instance Attestation (WIA) consists of two parts: - a Client Attestation JWT - a Client Attestation PoP JWT

For the Client Attestation JWT we use the wallet attestation issued by the wallet backend.

For the Client Attestation PoP JWT, the Wallet Instance generates the JWT using the key from the Client Attestation JWT. It contains: - iss: client_id value that matches sub of Client Attestation JWT - iat: current time - exp: current time + 5 minutes - aud: the URL of the PID Issuer Authorization Server - jti: use a UUIDv4 - nonce: use the session_id of the PID Issuer Session Endpoint

Wallet Trust Evidence

For the issuance of a PID, the Wallet Instance must authenticate the keys used for device binding of PID credentials, refresh tokens and access tokens to ensure that key management meets the PID issuer's requirement for Level of Assurance High. This is done using key attestations as described within OpenID4VCI Annex D.

To determine that this mechanism is required, the Wallet Instance evaluates the PID Issuer metadata, specifically the key_attestations_required parameter within the proof_types_supported parameter which should contain an object with the values iso_18045_high.

For the Wallet Trust Evidence, we use the key attestation issued by the Remote WSCD.