Skip to content

Note: this flow is currently not being actively maintained.

PID Option B: Authenticated Channel with eID Card (B) with mDoc, ISO REST API

Basic Idea

Presentation of PID and QEAAs (EAAs) reusing the entire System for German eID or Smart-eID for PID. The protocol is based on ISO standards ISO 18013-5/-7 and ISO 23220 and has two options for QEAA handling:

  1. get PID and QEAA in one shot (request/response)
  2. get PID and QEAA independent of each other (multiple requests/responses)

Cryptographic Formats

Long-Term keys:

  • PID Provider has long-term key pair \((pp\_pub, pp\_priv)\) that can be verified using \(x5chain\)
  • RP has long-term key pair \((rp\_pub, rp\_priv)\)

Transaction-specific keys:

  • RP contribution to HMAC key: RP generates ephemeral key pair \((rp\_eph\_pub, rp\_eph\_priv)\)
  • PID Provider contribution to HMAC key: PID provider generates ephemeral device key pair \((dev\_eph\_pub, dev\_eph\_priv)\) for each request

Artifacts:

  • \(issuerAuth := \text{sign}(dev\_eph\_pub, x5chain)_{pp\_priv}\)
  • \(hmac\_key := \text{ecdh}(rp\_eph\_pub, dev\_eph\_priv)\)
  • \(deviceAuth := \text{hmac}(\mathit{eID\_data}, \mathit{SessionTranscript})_{hmac\_key}\)

Sequence Diagram

User Journey: PID Presentation - Authenticated Channel - eID Card

UserUserBrowser App(same device)Browser App(same device)Relying PartyLong-term Key: (rp_pub,rp_priv)for Reader Authentication:Relying PartyLong-term Key: (rp_pub,rp_priv)for Reader Authentication:User's EUDI Wallet Instance(eID-Client)User's EUDI Wallet Instance(eID-Client)PID Provider(eService+eID Server)Long-term Key: (pp_pub,pp_priv)for mDoc Authentication (ECDH for HMAC):PID Provider(eService+eID Server)Long-term Key: (pp_pub,pp_priv)for mDoc Authentication (ECDH for HMAC):(001)browseto applicationScreen: same_device_relying_party_startstart session acc. to ISO/IEC 23220-4 and ISO/IEC 18013-7(002)[TLS] HTTP GET <rp-website>(003)create ISO-RestAPI-sessionIDand ReaderEngagementReaderEngagement contains:- ephemeral session keys forsession encryption Reader.EDeviceKey.pub- referrer url incl. sessionID, e.g.,https://relying-party-service.de/{uuid}/- OriginInfo (004)[TLS] HTTP 200params("HTML with link tomdoc://base64(ReaderEngagement)")(005)mdoc://params("/base64(ReaderEngagement)")Screen: launch_wallet(006)user consent (unlock wallet)Screen: unlock_wallet(007)generate ephemeral SessionKeyscreate Device Engagement(008)[TLS] HTTP POSTparams("MessageData")MessageData contains- deviceEngagementBytes with- RetrievalMethod == RestAPI- ephemeral session keyWallet.EDeviceKey.pub- MacKeySupport := TRUE- MacKeyCurves := []- OriginInfo.ReferrerURL :=https://relying-party-service.de/{uuid}/- OriginInfo.BaseURL :=https://relying-party-service.de(009)validateOriginInfo.ReferrerURL andOriginInfo.BaseURL withOriginIfo fromReaderEngagementrecognize MiTM attack(010)calculate mdoc_request forPID and mDLmdoc_request containsephemeral MacKeys Reader.MacKey.pub ifDeviceEngagement requests Mac supportReaderAuthentication  :_= COSE_Sign1 withdetached  ReaderAuthenticationBytes (incl.SessionTranscript)(011)perform key agreement(Wallet.EDeviceKey.pub *EReaderKey.priv) and HKDFfor S.key(012)SessionData := enc(S.key,mdoc_request)(013)[TLS] HTTP 200params("SesssionData")(014)perform key agreement(EDeviceKey.priv *Reader.EReaderKey.pub)S.key(015)mdoc_request := dec(S.key,SesssionData)(016)calculate SessionTranscript(017)validate ReaderAuthenticationSignature over detachedReaderAuthenticationBytes (incl.SessionTranscript)ReaderAuthenticationBytes needs to berebuilt for validation on Device sideScreen: consent_present_credential(018)[TLS] HTTP GET /tcTokenparams("Reader.MacKey.pub,SessionTranscript")Security risk: No PoP for MacKey used here;can an attacker forward a MacKey from adifferent session to the PID Provider?Screen: eid_startRead eID or Smart eID acc. to BSI TR-03130(019)tlspsk() eID Processonly the required PID attributes arerequestedScreen: eid_pinScreen: eid_nfc_data(020)store eID dataPrepare response for PID acc. ISO 18013-7 and ISO 23220-4 in mdoc format (REST-API)(021)generate MDoc-DeviceKey-Pair and create MSO withMDoc.EDeviceKey.pub but w/odata itemsthe Device Key pair shall be generated withinan HSM and will be referenced by theSessionID(022)perform key agreement(Reader.MacKey.pub *MDoc.EDeviceKey.priv) andHKDF for HMAC(023)calculate HMAC forDeviceAuth(024)create mDoc-Response fromPID incl. DeviceAuthuser data is not signed, but HMACd(025)[TLS] HTTP GET /pidtrust relation between wallet andPID-Provider needs to be defined,options are reuse existing TLS-PSK channelfor mutual authenticationor  mTLS(026)[TLS] HTTP 200params("mdoc-response")optional: get QEAA(027)SessionData := enc(S.key,mdoc-response)(028)[TLS] HTTP POSTparams("SessionData")(029)perform key agreement(Reader.MacKey.pub *MDoc.EDeviceKey.priv) andHKDF for HMAC(030)mdoc _response := dec(S.key,SessionData)(031)verify HMAC for DeviveAuth inmdoc _responserequest addtional mDoc from wallet(032)SessionData := enc(S.key,mdoc-request)reuse S.key from step 011(033)[TLS] HTTP 200params("SessionData")(034)SessionData := enc(S.key,mdoc-request)Question: This step should probably besomething else?reuse S.key from step 011(035)[TLS]  HTTP POSTparams("SessionData")(036)SessionData := enc(S.key,mdoc-response)reuse S.key from step 014(037)[TLS]  HTTP 200TLS session from step 002 needs to bematched with ISO REST session (long polling,web sockets or similar).Security risk: No protection against relayingrequests yet (binding to browser session).Screen: success_redirectScreen: same_device_relying_party_identified

Step-by-Step Description

User browses to Relying Party (RP) website

  1. open the Browser app
  2. request RP website within the Browser app
  3. RP generates an ephemeral session key pair and a ReaderEngagement structure according to ISO 18013-7 annex A.1
  4. ReaderEngagement contains:
  5. the public ephemeral session key
  6. an OriginInfo structure with a referrer-url incl. a REST-API sessionID, e.g., https://rp.example.com/mdoc-reader/1234
  7. RP returns a HTML page to the browser containing a link to the wallet app (e.g., mdoc://enc(base64,ReaderEngagement))
  8. The user clicks on the link and the wallet will be launched
  9. The wallet app retrieves the Authorization Request from the RP website (e.g., https://rp.example.com/mdoc-reader/1234) and the public ephemeral session key
  10. The user might be asked for consent to unlock the wallet (needs to be discussed!)
  11. RP generates an ephemeral session key pair and a DeviceEngagement structure according to ISO 18013-7 annex A.2
  12. DeviceEngagement indicates support of Mac keys for mDoc authentication
  13. DeviceEngagement contains an OriginIfo structure. This value shall not be determined using data from the ReaderEngagement structure.
  14. Wallet sends a CBOR encoded message data structure via HTTPS POST to the RP containing the DeviceEngagement structure
  15. RP validates OriginInfo from DeviceEngagement with provided ReaderEngagement from step 2
  16. RP calculates mDoc-request
    • just for PID or PID and QEAA (e.g., mDL)
    • mDoc-request contains items to request, public Reader Mac-key and ReaderAuthentication
  17. RP performs ECDH key agreement and calculates the symmetric session key S.key
  18. RP encrypts the mDoc-request with S.key
  19. RP returns the mDoc-request to the wallet
  20. wallet performs ECDH key agreement and calculates the symmetric session key S.key
  21. wallet decrypts mDoc-request with S.key
  22. wallet calculates SessionTranscript acc ISO 18013-7 A.8
  23. wallet performs Reader Authentication
  24. wallet starts eID-process if mdoc-request contains PID request
  25. wallet performs eID process acc. TR 03124
  26. PID-Provider stores eID data temporarily
  27. PID-Provider generates mDoc authentication key pair and creates an MSO structure, this might also be done for one time, e.g., during service startup
  28. optional: perform reading of additional QEAA's or EAA's by ruse of existing TLS-PSK channel
  29. PID-Provider performs ECDH and HKDF for HMAC key
  30. PID-Provider calculates HMAC for Device Authentication using the SessionTranscript
  31. PID-Provider calculates mDoc-response
    • for PID and QEAA, if optional step 22. has been performed
    • just for PID, if optional step 22. has been omitted
  32. wallet encrypts mDoc-response using session key S.key
  33. wallet posts the mDoc-response to the RP
  34. RP decrypts mDoc-response using S.key
  35. RP performs ECDH and HKDF for HMAC key
  36. RP verifies mDoc authentication
  37. optional: RP calculates an additional mDoc-request
  38. optional: RP returns additional mDoc-request to the wallet
  39. optional: Wallet encrypts mdoc-response
  40. wallet posts mdoc-response to RP
  41. RP ends the session

Implementation Considerations

TBD

Usability Considerations

The user expects a simple and intuitive user interface with the same or similar user experience as for other security-critical applications such as banking apps. That means, that the entire session will be performed within the same instance of a browser window or tab. This applies in particular for the same-device flow as well as for the cross-device flow. For both flows, the user starts the session by requesting the website in step 002 and expects to get the result in the same browser window or tab. Step 005 might be a deep link within a website behind a button for the same device flow or a qr-code with identical information mdoc://enc(base64,ReaderEngagement) for the cross-device flow. At the end of the session the content of the browser window or tab from step 004 needs to be updated. To achieve this, at least 2 options are available:

  1. using long polling
  2. using websockets with notifications

The cross-device flow is mandatory for EUID wallet according to document "EUDIW Design Guide_Data Sharing Scenarios-v1.00_clean.doc".

  • Unlock wallet (Step 006) should probably be moved to a later point in the flow, ideally just before using the credential.

Security Considerations

SessionTranscript: "Device Retrieval" with remote CA keys is defined by the ISO standards 18013-7 and 23220-4. The SessionTranscript is used within the authentication structure for the reader mDoc-request (ReaderAuthentication) and the authentication structure for the mDoc-response structure (DeviceAuthentication). The aim is the cryptographical binding of the data exchange protocol (request/response) with the underlying transport protocol REST-API. The SessionTranscript shall be created independently on each site of the communication channel.

  • The SessionTranscript structure contains a ReaderEngagementHashBytes structure calculated using SHA256( ReaderEngagementBytes ) where ReaderEngagement contains the ephemeral RP public key (EReaderKeyBytes) and the URI of the RP website(TestApiOptions).
  • The hashing of ReaderEngagementBytes prevents the leakage of session information from the Relying Party to the PID-Provider, for privacy reasons.

Cross-device Flow is mandatory for the EUID wallet. The proposed user flow as discussed in Usability Considerations (above) does not solve the problem of session hijacking by an attacker. Compared to the user experience to banking apps in combination with banking services, the RP does not know the wallet.

Proof of Possession (PoP) requires a kind of key attestation, which is not yet defined.

Privacy Considerations

  • Selective Disclosure is achieved by ensuring that the credential contains only those data items (claims) that are requested by the RP. The list of requested claims is part of the request to the PID Provider.