8.2.2. Proximity Flow¶
This section describes how a Relying Party Instance requests the presentation of an mdoc-CBOR Credential to a Wallet Instance as specified in the ISO 18013-5 Specification.
The high-level presentation phase is structured into three broad sub-phases as depicted in the following figure:
The sub-phases are described below:
1. Device Engagement: This subphase begins when the User is prompted to disclose specific attributes from the mdoc(s). The objective of this subphase is to establish a secure communication channel between the Wallet Instance and the Relying Party Instance, so that the mdoc requests and responses can be exchanged during the communication subphase. The messages exchanged in this subphase are transmitted through short-range technologies to limit the possibility of interception and eavesdropping. Device Engagement data may be transferred using either QR code or NFC technologies.
2. Session Establishment: During the session establishment phase, the Relying Party Instance sets up a secure connection. All data transmitted over this connection is encrypted using a session key, which is known to both the Wallet Instance and the Relying Party Instance at this stage. The established session MAY be later terminated based on the conditions as detailed in [ISO18013-5 #12.2.4].
3. Communication - Device Retrieval: The Relying Party Instance encrypts the mdoc request with the appropriate session key and sends it to the Wallet Instance together with its public key in a session establishment message. The Wallet Instance uses the data from the session establishment message to derive the session key and then to decrypt the mdoc request. During the communication subphase, the Relying Party Instance has the option to request information from the Wallet Instance using mdoc requests and responses. The primary mode of communication is the secure channel established during the session setup. The Wallet Instance encrypts the mdoc response using the session key and transmits it to the mobile Relying Party Instance via a session data message.
Relying Party and Wallet Instances registered in the IT-Wallet ecosystem MUST support at least the following flows:
Supervised Device Retrieval flow where a human Relying Party is overseeing the verification process in person, or unsupervised flow where verification might happen through automated systems without human oversight (WP_095).
Relying Party Instance Authentication following the mechanisms defined in the ISO18013-5 for the reader authentication (WP_098).
Domestic Document Type and Namespaces defined in this technical specification in addition to those already defined in the ISO18013-5 for the mDL (see mdoc-CBOR Credential Format for more details) (WP_099).
Wallet Instance validation through the Wallet Attestation.
The following table shows the supported Device Engagement technologies (WP_097), specifying which are mandatory.
Transmission technology |
ISO 18013-5 |
ISO 18013-5 |
IT Wallet |
IT Wallet |
|---|---|---|---|---|
Wallet Instance |
RP Instance |
Wallet Instance |
RP Instance |
|
QR code |
Ca |
M |
MUST |
C – MUST if the device is equipped with a camera or QR code reader and BLE. |
NFC |
Ca |
M |
RECOMMENDED |
C – MUST if the device is equipped with an NFC reader. |
Key: C = Conditional | M = Mandatory | aSupport for at least one of these methods is mandatory (WP_097a)
The following table shows the supported Device Retrieval technologies, specifying which are mandatory.
Transmission technology |
ISO 18013-5 |
ISO 18013-5 |
IT Wallet |
IT Wallet |
|---|---|---|---|---|
Wallet Instance |
RP Instance |
Wallet Instance |
RP Instance |
|
BLE |
Ca |
M |
MUST |
C – MUST if the device is equipped with a camera or QR code reader and BLE. |
NFC |
Ca |
M |
RECOMMENDED |
C – MUST if the device is equipped with an NFC reader. |
Key: C = Conditional | M = Mandatory | aSupport for at least one of these methods is mandatory (WP_096b)
Note
From the second edition, version 3, ISO18013-5 does not define or support Server Retrieval as a transport option. Only proximity retrieval methods (NFC, BLE, and optionally Wi-Fi Aware) are specified (WP_096). Therefore, Server Retrieval is not considered in this flow (WP_096a and PPR-023).
The following figure illustrates the low-level flow compliant with ISO 18013-5 for proximity flow.
Step 1: The User opens the Wallet Instance initiating the process.
Step 2: The User authenticates itself to the Wallet Instance. This can be done by the Wallet Instance or a Wallet Secure Cryptographic Application (WSCA). It is a prerequisite for accessing sensitive data and presenting attributes (WP_100).
Step 3: The User selects the proximity presentation functionality.
Step 4: [Optional] If the initial authentication in Step 2 was not done through WSCA, a separate authentication via WSCA MAY be required (WP_100).
Step 5: The Wallet Instance generates a new ephemeral Elliptic Curve key pair for secure communication (WP_101). The public key (EDeviceKey.Pub) will be exchanged with the Relying Party Instance to derive a shared session key, which is then used for session encryption. This is part of the device engagement process.
Box A
The Wallet Instance and Relying Party Instance exchange Device Engagement data via QR code or via NFC Connection Handover (WP_097).
Refer to:
Sec 8.2.2.1 for
DeviceEngagementover QR codeSec 8.2.2.2 for
DeviceEngagementover NFC
Step 6: The Relying Party Instance generates its ephemeral key pair (EReaderKey.Priv, EReaderKey.Pub). The private key (EReaderKey.Priv) MUST be kept secret, and the public key (EReaderKey.Pub) MUST be used in establishing the session.
Step 7: The Wallet Instance and Relying Party Instance independently MUST derive the session keys using their private ephemeral key and the other party's public ephemeral key through a key agreement protocol. This ensures session encryption. In this particular step, the Relying Party Instance MUST compute its session key (PPR-002 and WP_104).
Step 8: The Relying Party Instance MUST prepare a SessionEstablishment message. This message MUST be signed by the Relying Party Instance (mdoc reader authentication as specified in [ISO18013-5 #12.5]) and encrypted using the session keys derived in the previous step. The SessionEstablishment message MUST include the EReaderKey.Pub and a request for specific attribute(s) (PPR-002).
Below is a non-normative example using the diagnostic notation of a CBOR-encoded SessionEstablishment message that contains an mdoc request for a Wallet Attestation along with an mDL Digital Credential.
{
"version": "1.0", % Version
"docRequests":
[
{
"itemsRequest":
24(<< % Embedded CBOR data item
{
"docType": "org.iso.18013.5.1.mDL",
"nameSpaces":
{
"org.iso.18013.5.1":
{
"family_name": true,
"document_number": true,
"driving_privileges": true,
"issue_date": true,
"expiry_date": true,
"portrait": false
}
}
}
>>)
},
{
"itemsRequest":
24(<< % Embedded CBOR data item
{
"docType": "it.wallet.trust-registry.WalletAttestation",
}
>>)
}
],
"readerAuthAll":
[
h'a10126', % COSE_Sign1 authentication header
{
33: h'308201253081cda00302010202012a300a06082a8648ce3d0403023020311e301c06035504030c15536f6d652052656164657220417574686f72697479301e170d3233313132343130323832325a170d3238313132323130323832325a301a3118301606035504030c0f536f6d6520526561646572204b65793059301306072a8648ce3d020106082a8648ce3d03010703420004aa1092fb59e26ddd182cfdbc85f1aa8217a4f0fae6a6a5536b57c5ef7be2fb6d0dfd319839e6c24d087cd26499ec4f87c8c766200ba4c6218c74de50cd1243b'
},
null, % No additional reader authentication
h'58a0d421a7e53b7db0412a196fea50ca6d4c8a530a47dd84d88588ab145374bd0ab2a724cf2ed2facf32c7184591c5969efd53f5aba63194105440bc1904e1b9' % Reader authentication signature
]
}
Box B
The Relying Party Instance MUST transmit the encrypted and signed SessionEstablishment message to the Wallet Instance over an NFC or a BLE secure connection that was established based on the Device Engagement information.
Refer to:
Sec 8.2.2.3 for
SessionEstablishmentover BLE, andSec 8.2.2.5 for
SessionEstablishmentover NFC
Step 9: The Wallet Instance MUST compute the session key, as described in Step 7.
Step 10: Upon receiving the SessionEstablishment message, the Wallet Instance MUST decrypt it using the shared session key and MUST verify the Relying Party Instance's signature (mdoc reader authentication as specified in [ISO18013-5 #12.5]) to ensure its authenticity (PPR-002 and WP_105–106).
Step 11: The Wallet Instance MUST decrypt the attribute request and MUST prompt the User for their consent to release the requested attributes (WP_107). It MUST also display the contents of the Relying Party's Registration Certificate to ensure transparency about the requested attributes and its registered purpose (WP_107b).
Step 12: The User reviews the request and the Relying Party's registration information and then approves the presentation of the requested attributes.
Box C
After receiving User approval, the Wallet Instance MUST retrieve the requested mdoc Digital Credentials (PPR-006 and WP_108). It then MUST prepare a SessionData message containing these Digital Credentials, and it MUST sign the required authentication data (as part of the mdoc authentication process, as specified in [ISO18013-5 #12.4]) as per (WP_109–110). It MUST encrypt it using the established session keys before transmitting it to the Relying Party Instance over the secure channel (WP_111). The signing ensures device binding and data integrity. The mdoc response MUST be encoded in CBOR, with its structure outlined in [ISO18013-5 #10.3] (PPR-029, PPR-030, and WP_112).
Refer to (WP_112a–112b):
Sec 8.2.2.4 for
SessionDataover BLE, andSec 8.2.2.5 for
SessionDataover NFC
Below is a non-normative example using the diagnostic notation of a CBOR-encoded SessionData that contains the mdoc response of a Wallet Attestation and an mDL Digital Credential.
{
"version": "1.0",
"documents":
[
{
"docType": "org.iso.18013.5.1.mDL",
"issuerSigned":
{
"nameSpaces":
{
"org.iso.18013.5.1":
[
24(<<
{
"digestID": 0,
"random": h'790401ed5d0822d1aced942e4b0c41f754eee67b89c5ee3b8fd2c97491a96406',
"elementIdentifier": "family_name",
"elementValue": "Rossi"
}
>>),
24(<<
{
"digestID": 3,
"random": h'0c8f68d1ec3aa445ef68aa10b7a5875fa18ca222a821e23890a227cdc7d25e8f',
"elementIdentifier": "issue_date",
"elementValue": 1004(2025-03-27)
}
>>),
24(<<
{
"digestID": 4,
"random": h'0a9ed0d4937673152e52fb3fac0722baf4252e0d0c9869919e3339670203178e',
"elementIdentifier": "expiry_date",
"elementValue": 1004(2030-03-27)
}
>>),
24(<<
{
"digestID": 8,
"random": h'88e94c0365c611b523518d9a1b179ae52e242383576249f4965c40c6c97cf214',
"elementIdentifier": "document_number",
"elementValue": "XX1234567"
}
>>),
24(<<
{
"digestID": 9,
"random": h'944758b43602b01ad68911b062349845492c04c6a78129bcf8cb5fb1396af2fc',
"elementIdentifier": "portrait",
"elementValue": h'ffd8ffe000104a46494600010101009000900000ffdb004300130d0e110e0c
13110f11151413171d301f1d1a1a1d3a2a2c2330453d4947443d43414c566d5d4c51685241435f82
606871757b7c7b4a5c869085778f6d787b76ffdb0043011415151d191d381f1f38764f434f767676
76767676767676767676767676767676767676767676767676767676767676767676767676767676
76767676767676ffc00011080018006403012200021101031101ffc4001b00000301000301000000
000000000000000005060401020307ffc40032100001030303020502030900000000000001020304
0005110612211331141551617122410781a1163542527391b2c1f1ffc40015010101000000000000
00000000000000000001ffc4001a110101010003010000000000000000000000014111213161ffda
000c03010002110311003f00a5bbde22da2329c7d692bc7d0d03f52cfb0ff75e7a7ef3e7709723a1
d0dae146ddfbb3c039ce07ad2bd47a7e32dbb8dd1d52d6ef4b284f64a480067dfb51f87ffb95ff00
eb9ff14d215de66af089ce44b7dbde9cb6890a2838eddf18078f7add62d411ef4db9b10a65d6b95a
147381ea0d495b933275fe6bba75c114104a8ba410413e983dff004f5af5d34b4b4cde632d0bf1fd
1592bdd91c6411f3934c2fa6af6b54975d106dcf4a65ae56e856001ebc03c7ce29dd9eef1ef10fc4
47dc9da76ad2aee93537a1ba7e4f70dd8eff0057c6dffb5e1a19854a83758e54528750946ec67048
50cd037bceb08b6d7d2cc76d3317fc7b5cc04fb6707269c5c6e0c5b60ae549242123b0e493f602a0
75559e359970d98db89525456b51c951c8afa13ea8e98e3c596836783d5c63f5a61a99fdb7290875
db4be88ab384bbbbbfc7183fdeaa633e8951db7da396dc48524fb1a8bd611a5aa2a2432f30ab420a
7a6d3240c718cf031fa9ef4c9ad550205aa02951df4a1d6c8421b015b769db8c9229837ea2be8b1b
0d39d0eba9c51484efdb8c0efd8d258daf3c449699f2edbd4584e7af9c64e3f96b9beb28d4ac4093
1e6478c8e76a24a825449501d867d2b1dcdebae99b9c752ae4ecd6dde4a179c1c1e460938f9149ef
655e515c03919a289cb3dca278fb7bf177f4faa829dd8ce3f2ac9a7ecde490971fafd7dce15eed9b
71c018c64fa514514b24e8e4f8c5c9b75c1e82579dc1233dfec08238f6add62d391acc1c5256a79e
706d52d431c7a0145140b9fd149eb3a60dc5e88cbbc2da092411e9dc71f39a7766b447b344e847dc
ac9dcb5abba8d145061d43a6fcf1e65cf15d0e90231d3dd9cfe62995c6dcc5ca12a2c904a15f71dd
27d451453e09d1a21450961cbb3ea8a956433b781f1ce33dfed54f0e2b50a2b71d84ed6db18028a2
8175f74fc6bda105c529a791c25c4f3c7a11f71586268f4a66b726e33de9ea6f1b52b181c760724e
47b514520a5a28a283ffd9'
}
>>),
24(<<
{
"digestID": 10,
"random": h'577e4822125f55fe923117aba01fdaefcc67d4aea80018fc22efa8d48e17982f',
"elementIdentifier": "driving_privileges",
"elementValue": [
{
"vehicle_category_code": "A",
"issue_date": 1004("2020-09-17"),
"expiry_date": 1004("2031-06-10")
}
]
}
>>)
]
},
"issuerAuth":
[
<< {1: -7} >>,
{
33: h'30820208308201afa00302010202142eb39c647c81836bcf79fa9cd0b201ec0bf52307300a0
6082a8648ce3d0403023064310b30090603550406130255533113301106035504080c0a43616c6966
6f726e69613116301406035504070c0d53616e204672616e636973636f31133011060355040a0c0a4
d7920436f6d70616e793113301106035504030c0a6d79736974652e636f6d301e170d323530333237
3135353532305a170d3235303430363135353532305a3064310b30090603550406130255533113301
106035504080c0a43616c69666f726e69613116301406035504070c0d53616e204672616e63697363
6f31133011060355040a0c0a4d7920436f6d70616e793113301106035504030c0a6d79736974652e6
36f6d3059301306072a8648ce3d020106082a8648ce3d03010703420004f33da72d0dd0009b62221b
0e839099b12dab5e01021124ebf9060422e648f3c3ec6614a86da1e91e552b2ae35e04d3058ae82b5
c65a7f1f26800cb4499652a09a33f303d303b0603551d1104343032863068747470733a2f2f637265
64656e7469616c2d6973737565722e6f6964632d66656465726174696f6e2e6f6e6c696e65300a060
82a8648ce3d040302034700304402204d1f0819971652b79ebe4825547de3d5554d2f41410225e6b1
3dab949cda125e022079ba71b823619e49719dce5daa565bf745d3d97e2b87c7f7d6a626f981e653ed'
},
<<
24(<<
{
"version": "1.0",
"digestAlgorithm": "SHA-256",
"docType": "org.iso.18013.5.1.mDL",
"valueDigests": {
"org.iso.18013.5.1":
{
0: h'f46b65d5060ad060ab9be62ff22ea8633437619ebdc7fa81f2d151159e92bffe',
1: h'e506545f6a6fd5d982670b4d62fc2b0688dc8f26754e7b0c574d63f5d72a85ac',
2: h'cfcf96fa12d100eeed5f00183d3b6a0888baa47eae85b5b95037eca7bbc0d07e',
3: h'8b0772252b0e06b611676b6b3402eb33bf866eb145e49f4d5f23215e6a047772',
4: h'14135c96693e2ab08d956876ee491357d906a6dd125557196dfb9811ba54aa8d',
5: h'86dcbd99233fbb84a9a2dce3a864a425e6e809300067a4475e3ea2a4d233dc74',
6: h'2e9512d35ea225e69e7b2180ecc1678dcc3e77a16e36427e64b4f0e2861b4d3a',
7: h'4efe55c36f6249d23c473a125afc5181aa30633936494781554971b72ff13700',
8: h'cc44a4f9983c5b0b1efc0e82e2867c8d5bbdf89c34bff16a1953c923bb4e4b3e',
9: h'775eb2af0aa55f2071d62662b35c99698ae3bc0e2c4af5724ff88476cddd152f',
10: h'915d0ad53dd23dace34968c263d307c04701a9bb9dc9865af91dc409786fd833',
11: h'47d89ff4fb513044e6f2394236755ac0abf3e4f4a46f40454a458a59f8b7a6fb'
},
"org.iso.18013.5.1.IT": {
12: h'd665c50c4364c7cbf4ab9461b9bbb228f37ad278b9fb61283550951624d4d9ae',
13: h'dc9d032a64866e33d06f48a882989b5747da3638f0d216a2275191ed3395fdec'
}
},
"deviceKeyInfo": {
"deviceKey": {
1: 2,
-1: 1,
-2: h'f96b29873b61f05403e2963a7ecbc799c9aab28d8a6629e5848cfdef85442866',
-3: h'a9fef033a900c63e3894d8deb805a2a1fb55ef0d2b88e3c0d3336408186485ef'
}
},
"validityInfo": {
"signed": 0("2025-03-27T00:00:00Z"),
"validFrom": 0("2025-03-27T00:00:00Z"),
"validUntil": 0("2026-03-27T00:00:00Z")
},
"status": {
"status_list": {
"idx": 1340,
"uri": "https://statusprovider.example.org/statuslists/1"
}
}
}
>>)
>>,
h'd09f9acdf7a6be5e4aeb405bfb3b297b1b8003bcf52558a2f39fc6e5cffed40f18f49d2cc0e72a2a5645
8d8aade591dee8d6540e639bca637f94bd9fa56f345c'
]
},
"deviceSigned":
{
"nameSpaces": 24(<< {} >>),
"deviceAuth":
{
"deviceSignature":
[
<< {1: -7} >>,
{},
null,
h'E99521A85AD75943BF5AEAE68943BF5AE249943BF5AE943BF5AE43BF5AEDE99521A85AD75943BF5AEAE
68943BF5AE249943BF5AE943BF5AE43BF5AED'
]
}
}
},
{
"docType": "it.wallet.trust-registry.WalletAttestation",
"issuerSigned": {
"nameSpaces": {
"it.wallet.trust-registry.WalletAttestation": [
24(<<
{
"digestID": 0,
"elementIdentifier": "aal",
"elementValue": "https://wallet-provider.example.org/LoA/basic",
"random": h'bbc6b4df4282424ed5753b4218863923ab3256cb831822601d95a5806e2bd114'
}
>>),
24(<<
{
"digestID": 1,
"elementIdentifier": "sub",
"elementValue": "ec#1",
"random": h'0117942b3ecdad65f226a668466fa175b72563a392598ad18fa6d359ea9b1b2d'
}
>>),
24(<<
{
"digestID": 2,
"elementIdentifier": "wallet_link",
"elementValue": "https://wallet-provider.example.org",
"random": h'dc9d032a64866e33d06f48a882989b5747da3638f0d216a2275191ed3395fdec'
}
>>),
24(<<
{
"digestID": 3,
"elementIdentifier": "wallet_name",
"elementValue": "Wallet name",
"random": h'd665c50c4364c7cbf4ab9461b9bbb228f37ad278b9fb61283550951624d4d9ae'
}
>>)
]
},
"issuerAuth": [
<< {1: -7} >>,
{
33: h'825903B0...'
},
<<
24(<<
{
"version": "1.0",
"digestAlgorithm": "SHA-256",
"valueDigests": {
"org.iso.18013.5.1.IT": {
0: h'2f89a12f690fe570b9b18d96acd231a70b5cb97cef5edad81973b99eeb145c2f',
1: h'7541a38f61d686f72ca8fb9da87a3db9fc65d28caa4e0973b0a3d66181ff7997',
2: h'7049c3bfcd96d62833f2fdb892b12cb6fd983b4c3bf40b0c39cb233bfeb5b75f',
3: h'ce566344e76ff543c5084e7618bdb54223ff2750dbcb4a3c7c35fd56a47a1024'
}
},
"deviceKeyInfo": {
"deviceKey": {
-1: 1,
2: "ec#1",
1: 2,
-2: h'09a9028deb030705de45e4702d1ce6860e94c0e29f334359a476078c2d22b9c5',
-3: h'6b972cd32c19cd5e8c19e051f1e207cabb3c2a802abf40ee5baaaa4a464508c3'
}
},
"docType": "org.iso.18013.5.1.IT.WalletAttestation",
"validityInfo": {
"signed": 0("2025-06-27T07:40:21Z"),
"validFrom": 0("2025-06-27T07:40:21Z"),
"validUntil": 0("2025-06-27T08:40:21Z")
}
}
>>)
>>
h'97f223fd4c9c462454e4123df916dd0d672af14608727ce38470b8bd74fb496e11462113f0005d3e97bf6115074712991e1720eb085292edd894a116a305310c'
]
},
"deviceSigned":
{
"nameSpaces": 24(<< {} >>),
"deviceAuth":
{
"deviceSignature":
[
<< {1: -7} >>,
{},
null,
h'E99521A85AD75943BF5AEAE68943BF5AE249943BF5AE943BF5AE43BF5AEDE99521A85AD75943
BF5AEAE68943BF5AE249943BF5AE943BF5AE43BF5AED'
]
}
}
}
],
"status": 0
}
Step 13: The Relying Party Instance receives the SessionData, then it MUST decrypt it, and it MUST verify the Wallet Instance's signature to ensure the data's integrity and that it originates from the expected device (device binding). It also MUST check the validity of the mdoc, including its Issuer's signature. In case of long-lived Digital Credentials, it SHOULD also check the revocation status using the TOKEN-STATUS-LIST.
Step 14: Once the data exchange is complete, either party can terminate the session. The session can be terminated by sending the status code for session termination in a SessionData message; this can be sent together with an mdoc request or response [ISO18013-5 #12.2.4] (WP_113c). If BLE is used, this can involve sending a status code for session termination or the “End” command. In this scenario, the GATT Client (Relying Party Instance) MUST unsubscribe from characteristics and disconnect from the GATT server (Wallet Instance) (PPR-007, WP_113b, and WP_114).
Final Consideration: The presentation flow focused on the technical data exchange in proximity settings. It is crucial to recognise that supervised proximity flows involving a human verifier play a vital role in many use cases (e.g., age verification at a store, identity check by law enforcement). The human element adds a layer of identity verification through visual inspection and comparison, contributing to User Binding and overall authentication assurance aspects not fully captured in a purely technical presentation flow.
Note
During proximity presentation the Wallet Instance might not be able to fetch a fresh Wallet Attestation, in this case, the Wallet Instance SHOULD send the latest version of the Wallet Attestation (WP_108a). It is left up to the Relying Party to determine whether a presentation with a valid but expired Wallet Attestation is valid or not.
8.2.2.1. DeviceEngagement over QR Code¶
The following figure illustrates the low-level flow compliant with ISO 18013-5 for DeviceEngagement over QR Code corresponding to Box A in Figure Low-Level Presentation Flow in proximity..
Fig. 8.15 Device Engagement over QR Code.¶
Step 1: The Wallet Instance presents a QR Code to the Relying Party Instance. The QR code SHALL contain a URI with “mdoc:” as scheme and the DeviceEngagement structure specified in Section 9.1 encoded using base64url-without-padding, according to RFC 4648, as path (WP_102a).
8.2.2.1.1. Non-Normative Example with BLE as Data Retrieval¶
Below is a non-normative example using the diagnostic notation of a CBOR-encoded DeviceEngagement that utilizes QR for Device Engagement and Bluetooth Low Energy (BLE) for data retrieval.
{ 0: "1.1", % Version (Updated to 1.1 because Capabilities and OriginInfos are present) 1: % Security [ 1, % defines the cipher suite , which contains only EC curves 24(<< % embedded CBOR data item { 1: 2, % kty:EC2 (Elliptic curves with x and y coordinate pairs) -1: 1, % crv:p256 -2:h'5A88D182BCE5F42EFA59943F33359D2E8A968FF289D93E5FA444B624343167FE', % x-coordinate -3:h'B16E8CF858DDC7690407BA61D4C338237A8CFCF3DE6AA672FC60A557AA32FC67' % y-coordinate } >>) ], 2: % DeviceRetrievalMethods (Device engagement using QR code with BLE for retrieval) [ [ 2, % BLE 1, % Version { % BLE options 0: false, % no support for mdoc peripheral server mode 1: true, % support for mdoc central client mode 11: h'45EFEF742B2C4837A9A3B0E1D05A6917' % UUID of mdoc client central mode } ] ], 5: % OriginInfos (Required because Capabilities is present) [], 6: % Capabilities (Defines supported features) { 2: false, % HandoverSessionEstablishmentSupport (Supports negotiated handover) 3: true % ReaderAuthAllSupport (Supports reader authentication) } }
8.2.2.1.2. Non-Normative Example with NFC as Data Retrieval¶
Below is a non-normative example using the diagnostic notation of a CBOR-encoded DeviceEngagement that utilizes QR for Device Engagement and NFC for data retrieval.
{ 0: "1.1", % Version (Updated to 1.1 because Capabilities and OriginInfos are present) 1: % Security [ 1, % defines the cipher suite , which contains only EC curves 24(<< % embedded CBOR data item { 1: 2, % kty:EC2 (Elliptic curves with x and y coordinate pairs) -1: 1, % crv:p256 -2:h'5A88D182BCE5F42EFA59943F33359D2E8A968FF289D93E5FA444B624343167FE', % x-coordinate -3:h'B16E8CF858DDC7690407BA61D4C338237A8CFCF3DE6AA672FC60A557AA32FC67' % y-coordinate } >>) ], 2: % DeviceRetrievalMethods (Device engagement using QR code with BLE for retrieval) [ [ 1, % NFC 1, % Version { % NFC options 0: uint, % Maximum length of command data field 1: uint, % Maximum length of response data field } ] ], 5: % OriginInfos (Required because Capabilities is present) [], 6: % Capabilities (Defines supported features) { 2: false, % HandoverSessionEstablishmentSupport (Supports negotiated handover) 3: true % ReaderAuthAllSupport (Supports reader authentication) } }
Step 2: The Relying Party uses its Relying Party Instance to scan the QR code and retrieve the DeviceEngagement data from the mdoc. It MUST select one of the transmission technologies from the ones provided in the DeviceEngagement structure.
8.2.2.2. DeviceEngagement over NFC¶
The following figure illustrates the low-level flow compliant with ISO 18013-5 for DeviceEngagement over NFC corresponding to Box A in Figure Low-Level Presentation Flow in proximity. (WP_103).
Fig. 8.16 Device Engagement over NFC.¶
DeviceEngagement over NFC is based on the NFC Forum Connection Handover Technical Specification, Version 1.5. Only Reader/ Writer mode using a Type 4 Tag is supported. The Connection Handover protocol is always initiated by the Relying Party Instance, which makes the role of Handover Requester. The Wallet Instance acts as the NFC Tag Device and the Relying Party Instance as the NFC Reader Device. The Wallet Instance SHALL use either Static Handover or Negotiated Handover:
- Static Handover: The Relying Party Instance retrieves a Handover Select message directly from the Wallet Instance's Type 4 Tag. This message contains at least one Alternative Carrier Record, each indicating a retrieval method supported by the Wallet Instance (WP_103a). The Relying Party Instance MUST select one of these transmission technologies. (see Step 1)
- Negotiated Handover: The Wallet Instance includes the service urn:nfc:sn:handover in a Service Parameter Record of the initial NDEF (NFC Data Exchange Format) message (WP_103b). Upon selecting this service, the Relying Party Instance sends a Handover Request with an Alternative Carrier Record for each carrier it supports. The Wallet Instance replies with a Handover Select message containing exactly one selected carrier. (See Step 2-4)
Step 1: The Relying Party Instance reads the Wallet’s NFC Type 4 Tag to obtain a Handover Select message, which includes: - Alternative Carrier Record is an NDEF record inside a Handover Select or Handover Request message. It points to one possible communication technology (called a “carrier”), such as NFC or BLE. It tells the reader about the supported carrier and a pointer (Auxiliary Data Reference) to more detailed information. The Alternative Carrier Record for the NFC device retrieval transmission technology shall reference the Carrier Configuration Record with the ID reference “nfc”. - Carrier Configuration Record provides the technical parameters needed actually to use that carrier. For NFC device retrieval transmission technology, it SHALL have the type “iso.org:18013:nfc” and the ID reference “nfc”. The binary content of the Carrier Configuration Record SHALL be encoded according to Table 1 of [ISO18013-5 #9.2.2] (WP_103d).
For example:
For NFC, this defines maximum APDU (Application Protocol Data Unit) command/response lengths;
For BLE, it defines the Wallet Instance service UUID, characteristic UUIDs, MTU (Maximum Transmission Unit) size, and optional connection parameters;
If early SessionEstablishment is supported, it also lists the TNEP (Tag NDEF Exchange Protocol) service name used to send the SessionEstablishment message during handover.
Note
For the NFC device retrieval transmission technology, the contents of the Alternative Carrier Record and Carrier Configuration Record(s) SHALL comply with [ISO18013-5 #9.2.2]. For the BLE device retrieval transmission technology, the contents of the Alternative Carrier Record and Carrier Configuration Record(s) shall comply with [ISO18013-5 #11.1.2].
Auxiliary Data Record MUST carry the DeviceEngagement structure from the Wallet Instance to the Relying Party Instance as part of the auxiliary NDEF record in the Handover Select message. This record has the type
iso.org:18013:deviceengagement, the ID reference “mdoc”, and uses the NFC forum external type format (0x04). For each Alternative Carrier record, the Auxiliary Data Reference MUST point to the NDEF record containing theDeviceEngagementStructure (WP_103e).
Step 2: The Relying Party Instance reads the Wallet Instance's Initial NDEF (NFC Data Exchange Format) message, which contains a service parameter record for urn:nfc:sn:handover, indicating the Wallet supports Negotiated Handover.
Step 3: The Relying Party Instance sends a Handover Request to the Wallet Instance listing the supported carriers.
Step 4: The Wallet Instance returns Handover Select constructed in response to the received Handover Request message. The contents of the Handover Select message is the same as Step 1 (WP_103f).
Note
Use of Negotiated Handover for Device Engagement allows negotiation of transfer methods. For BLE, it additionally allows negotiation of keys used by the transmission layer. This provides improved user experience and enhances the security of data transmission [ISO18013-5 #9.2.1].
Note
Proceed only if the DeviceEngagement Capabilities include HandoverSessionEstablishmentSupport set to true (WP_103c). Otherwise, skip the early SessionEstablishment. The early SessionEstablishment is sent via a dedicated TNEP service; the same SessionEstablishment SHALL also be sent again during data retrieval and MUST match. If it does not match, the Wallet Instance terminates (WP_103g). If the early SessionEstablishment fails to send, proceed as normal (WP_103h).
Step 5: [Optional] Relying Party Instance opens the TNEP service named [urn:placeholder] with the Wallet Instance during the negotiated handover to deliver the early SessionEstablishment message.
Step 6: Relying Party Instance sends SessionEstablishment (e.g., EReaderKey + encrypted DeviceRequest). Wallet Instance processes it; data retrieval has not started yet.
Step 7: Relying Party Instance closes the TNEP service.
Note
If an optional SessionEstablishment message is sent during Negotiated Handover (Step 5), the Wallet Instance MUST verify that it matches the SessionEstablishment message received during Device Retrieval (using BLE or NFC secure channel). This verification is required to ensure a correct Session Binding.
8.2.2.2.1. Non-Normative Example¶
- Below is a non-normative example of a
DeviceEngagementstructure for Data Retrieval over BLE and NFC. { 0: "1.1", % Version (Updated to 1.1 because Capabilities and OriginInfos are present) 1: % Security [ 1, % defines the cipher suite , which contains only EC curves 24(<< % embedded CBOR data item { 1: 2, % kty:EC2 (Elliptic curves with x and y coordinate pairs) -1: 1, % crv:p256 -2:h'5A88D182BCE5F42EFA59943F33359D2E8A968FF289D93E5FA444B624343167FE', % x-coordinate -3:h'B16E8CF858DDC7690407BA61D4C338237A8CFCF3DE6AA672FC60A557AA32FC67' % y-coordinate } >>) ], 2: % DeviceRetrievalMethods (Absent when using NFC for device engagement) [], 5: % OriginInfos (Required because Capabilities is present) [], 6: % Capabilities (Defines supported features) { 2: true, % HandoverSessionEstablishmentSupport (Supports negotiated handover) 3: true % ReaderAuthAllSupport (Supports reader authentication) } }
8.2.2.3. SessionEstablishment over BLE¶
The following figure illustrates the low-level flow compliant with ISO18013-5 for SessionEstablishment over BLE corresponding to Boxes B in Figure 8.10.
Fig. 8.17 Session Establishment over BLE.¶
Step 1: The Wallet Instance and Relying Party Instance establish a secure BLE connection [ISO18013-5 #11.1]. The Relying Party Instance (central) connects to the Wallet Instance (peripheral) using the Wallet Instance service UUID provided by DeviceEngagement, then discovers services/characteristics, and enables notifications as needed (WP_112c).
Step 2-5: [Optional] Wallet Instance initiates verification by preparing to check the Relying Party’s identity via the Ident characteristic, that is a BLE GATT characteristic that carries an identifier value as described in [ISO18013-5 #11.1.3.2]. The Wallet Instance derives the expected Ident value and reads the Relying Party's Ident characteristic, comparing it to the expected Ident, and terminating the BLE connection if a mismatch may occur .
Note
The purpose of the Ident characteristic is only to verify whether the Wallet Instance is connected to the correct Relying Party Instance before starting data retrieval. If the Wallet Instance is connected to the wrong Relying Party Instance, session establishment will fail. Connecting and disconnecting to a Relying Party Instance takes a relatively large amount of time; therefore, it is faster to implement methods to identify the correct Relying Party Instance [ISO18013-5 #11.1.3.1] (WP_112d).
Step 6: Relying Party Instance sends the encrypted SessionEstablishment message (includes EReaderKey and encrypted DeviceRequest) over the established BLE connection.
Step 7-8: [Optional] If the Wallet Unit receives the SessionEstablishment message during Negotiated Handover, the Wallet Unit MUST verify if this SessionEstablishment message matches the SessionEstablishment message received during the data retrieval phase (i.e., Step 6). In the event of a mismatch, the Wallet Unit shall terminate the BLE connection [ISO18013-5 #9.2.3].
8.2.2.4. SessionData over BLE¶
The following figure illustrates the low-level flow compliant with ISO18013-5 for SessionData over BLE corresponding to Boxes C in Figure 8.10.
Fig. 8.18 Session Data over BLE.¶
Step 1: The Wallet Instance sends the final APDU containing either the last block DeviceResponse (with requested attributes) or a status code, after which the session may end or continue with a new request.
8.2.2.5. SessionEstablishment over NFC¶
Note
If Device Engagement is initiated via a QR code, the Relying Party Instance has no standardised way to signal its intent to use NFC for subsequent data transfer. This could lead to a poor user experience, as the User might not be aware that they need to use NFC. This issue is avoided when NFC is used for the Device Engagement, as it implicitly establishes the data transfer method [ISO18013-5 #8.2.5].
Note
Due to the limited data transfer rate of NFC, if a large amount of data is required for a transaction, it may be neither practical nor reasonable for a User to keep the device within the RF range of the Relying Party Instance for the duration of the transaction. Furthermore, loss of signal when a device leaves the RF field necessitates re-initiating the transaction. This can only be avoided if all necessary User interactions with the Wallet Instance are performed while the device remains in the field, or if no User interaction is required during the active transmission phase [ISO18013-5 #8.2.5].
The following figure illustrates the low-level flow compliant with ISO18013-5 for SessionEstablishment over NFC corresponding to Box B in Figure 8.10.
Fig. 8.19 Session Establishment over NFC.¶
8.2.2.5.1. Definitions (Acronyms and Commands)¶
Acronym/Command |
Description |
|---|---|
PICC |
Proximity Integrated Circuit Card, implemented by Wallet Units acting as a NFC tag. |
PCD |
Proximity Coupling Device, impletented by Relying Party instances using APDU exchanges. |
AID |
Application Identifier, unique ID used in SELECT APDU command to engage the Wallet Instance. |
APDU |
Application Protocol Data Unit, a standard message format for communication between Relying Party Instance (PCD) and Wallet (PICC) consists of Command APDUs (e.g., SELECT, ENVELOPE, GET RESPONSE) from the reader and Response APDUs from the wallet, which include data exhange and end exchange using status words (SW1/SW2). |
SELECT APDU |
Command that opens the Wallet Instance by AID. Response includes File Control Information (FCI) and Status Word (SW1/SW2). |
ENVELOPE APDU |
Command that carries session messages (e.g., |
GET RESPONSE APDU |
Command that retrieves additional response data when the Wallet signals "more data" is available (SW1=61). |
SW1/SW2 |
SW1/SW2 (Status Words) — Two-byte status code at the end of every response. Common values: 90 00 = success, 61 XX = more data, 6A 82 = file/application not found. |
Step 1: The Relying Party Instance (PCD) sends a SELECT APDU command with the Application Identifier (AID: A0 00 00 02 48 04 00) to engage the Wallet Instance.
Step 2: The Wallet Instance (PICC) responds with File Control Information (FCI) and status words (SW1/SW2), either confirming success (90 00) or indicating that more data (61 XX) (WP_112e).
Step 3: The Relying Party Instance sends an ENVELOPE APDU carrying the SessionEstablishment message, which contains the encrypted DeviceRequest and its ephemeral public key for session setup.
Step 4: The Wallet Instance processes SessionEstablishment and returns an APDU response with SW1/SW2 (OK or more data to fetch), confirming the start of secure session context (WP_112f).
Step 5-6: [Optional] The Wallet Instance receives the SessionEstablishment message during Negotiated Handover, the Wallet Instance SHALL verify that this SessionEstablishment message matches the same message received during the data retrieval phase (i.e., Step 3-4). In the event of a mismatch, the Wallet Instance SHALL terminate the NFC connection [ISO18013-5 #9.2.3].
8.2.2.6. SessionData over NFC¶
The following figure illustrates the low-level flow compliant with ISO18013-5 for SessionData over NFC corresponding to Box C in Figure 8.10.
Fig. 8.20 Session Data over NFC.¶
Step 1-2: As long as the Wallet Instance signals that more data is available (61 XX), the Relying Party Instance issues GET RESPONSE APDUs to request the next block. The Wallet Instance returns encrypted SessionData fragments until all data is delivered.
Step 3: The Wallet Instance sends the final APDU containing either the last block DeviceResponse (with requested attributes) or a status code, after which the session may end or continue with a new request.
8.2.2.7. Device Engagement¶
The Device Engagement structure MUST be CBOR encoded and have at least the following components (PPR-001, PPR-021, PPR-022, and WP_102):
Component |
Description |
|---|---|
Version |
(tstr). Version of the Device Engagement structure. |
Security |
(array). Contains two mandatory values:
|
DeviceRetrievalMode-BLEOptions |
(map). Provides options for the BLE connection, such as Peripheral Server or Central Client mode, and the device UUID. See Table 2 of ISO18013-5 for the detailed mapping. If the Wallet Instance indicates during Device Engagement that it supports both modes, the Relying Party Instance SHOULD select the mdoc central client mode [ISO18013-5 #11.1.3.1]. Only present when performing Device Engagement using the QR code. Absent when using NFC to perform Device Engagement. |
DeviceRetrievalMode-NFCOptions |
(map). Provides options for NFC connections, including the supported role (PICC or PCD) and maximum PDU command/response sizes. See Table 2 of ISO18013-5 for the detailed mapping. In case NFC is used for Device Retrieval, the Wallet Instance SHALL support PICC mode and the Relying Party Instance SHALL support PCD mode [ISO18013-5 #11.2]. Only present when performing Device Engagement using the QR code. Absent when using NFC to perform Device Engagement. |
Capabilities |
(map). Declares optional capabilities supported by the mdoc, that are:
|
OriginInfos |
(array). Describes the interface used to receive and deliver the engagement structure. OriginInfos MAY be an empty array. |
8.2.2.7.1. mdoc Request¶
The messages in the mdoc Request MUST be encoded using CBOR. The resulting CBOR byte string for the mdoc Request MUST be encrypted with the Session Key obtained after the Device Engagement phase and MUST be transmitted using the BLE or NFC protocol (PPR-026, PPR-027, PPR-028).
Each mdoc Request MUST be compliant with the following structure, and MUST include the following components, unless otherwise specified:
Component |
Description |
|---|---|
version |
(tstr). Version of the mdoc Request structure. Enables compatibility management across different versions or implementation profiles. |
docRequests |
(array). Each entry is a DocRequest containing:
|
readerAuthAll |
(COSE_Sign1, CONDITIONAL). Used to authenticate the Relying Party once for all DocRequest`s. The signature is computed over `ReaderAuthenticationAll data, as defined in [ISO18013-5 #12.5]. This component MUST be present only if ReaderAuthAllSupport is set to true in the DeviceEngagement structure, and individual readerAuth fields are not used (PPR-025). |
Note
Requesting the Wallet Attestation
The Relying Party requesting a Wallet Attestation MUST add an object in the docRequest array having the docType set to {Trust Anchor reverse domain}.{WalletAttestation} as described in Digital Credentials Catalogue Structure. The Relying Party MUST NOT include the nameSpaces parameter in the request (PPR-010).
8.2.2.7.2. mdoc Response¶
The messages in the mdoc Response MUST be encoded using CBOR and MUST be encrypted with the Session Key obtained after the Device Engagement phase (PPR-029, PPR-030).
Each mdoc Response MUST be compliant with the following structure, and MUST include the following components, unless otherwise specified:
Component |
Description |
|---|---|
version |
(tstr). Version of the mdoc Response structure. Enables tracking changes and maintaining compatibility across versions of the standard or implementation profiles. |
documents |
(array of Documents, OPTIONAL). CBOR-encoded collection of documents returned in response to the request. Each document includes issuerSigned and deviceSigned components, and follows the structure defined in [ISO18013-5 #10.3.3]. |
documentErrors |
(map, OPTIONAL). A map of error codes for unreturned documents, as defined in [ISO18013-5 #10.3.6]. Each key is a docType, and each value is an ErrorCode (int) indicating the reason why the document was not returned. |
status |
(uint). Status code indicating the outcome of the request. For example, "status": 0 means successful processing. For details, see Table 3 (ResponseStatus) of [ISO18013-5 #10.3.5]. |
Each document in documents MUST be compliant with the following structure, and it MUST include the following components, unless otherwise specified (PPR-029):
Component |
Description |
|---|---|
docType |
(tstr). Document type identifier. For example, for an mDL, the value MUST be |
issuerSigned |
(bstr). Contains the IssuerNameSpaces structure, which includes data elements signed by the Issuer, and the issuerAuth structure, which ensures their authenticity and integrity using the Mobile Security Object (MSO). See mdoc-CBOR Credential Format. |
deviceSigned |
(bstr). Contains the DeviceNameSpaces structure (data elements signed by the Wallet Instance), and the deviceAuth structure, which includes the authentication data signed by the Wallet Instance. See the table below for details. |
errors |
(map, OPTIONAL). A map of error codes for each unreturned data element grouped by namespace. Each key represents a namespace, and each value is a map of data element identifiers to corresponding error codes. See [ISO18013-5 #10.3.6] for details on the errors structure. |
A deviceSigned data structure MUST be compliant with the following structure (WP_111a), and MUST include the following components:
Component |
Description |
|---|---|
nameSpaces |
(bstr). Contains the DeviceNameSpaces structure. It MAY be an empty structure. DeviceNameSpaces maps namespace identifiers to a set of data elements signed by the Wallet Instance. Each namespace contains one or more DeviceSignedItem, where each item includes:
|
deviceAuth |
(COSE_Sign1). Contains the DeviceAuth structure, which MUST include the deviceSignature for the Wallet Instance authentication. The signature is computed over the DeviceAuthentication data, which binds the returned elements to the session and the request. See [ISO18013-5 #12.4] for details on the authentication structure. |
Note
Presenting the Wallet Attestation
The Wallet Instance MUST include the Wallet Attestation if requested by the Relying Party in the mdoc request. The Wallet Instance SHOULD include all available disclosures for the Wallet Attestation and MUST include the claim aal as a disclosure (WP_108b). Moreover, during presentaion, the Wallet Instance MUST NOT request user's consent to the disclosure of the Wallet Attestation attributes which are technical data not transparent to the user (WP_107a).
8.2.2.7.3. Session Termination¶
The session MUST be terminated if at least one of the following conditions occur (PPR-007 and WP_113–113a):
After a time-out of no activity of receiving or sending session establishment or session data messages occurs. The time-out for no activity implemented by the Wallet Instance and the Relying Party Instance SHOULD be no less than 300 seconds;
When the Wallet Instance does not accept any more requests;
When the Relying Party Instance does not send any further requests.
If the Wallet Instance and the Relying Party Instance do not send or receive any further requests, the session termination MUST be initiated as follows (PPR-007 and WP_113):
Send the status code for session termination, or
Dispatch the "End" command as outlined in [ISO18013-5 #11.1.3.3].
When a session is terminated, the Wallet Instance and the Relying Party Instance MUST perform at least the following actions (WP_114):
Destruction of session keys and related ephemeral key material;
Closure of the communication channel used for data retrieval.
Note
See mdoc-CBOR Credential Format for the meaning of CBOR type acronyms.