Request credential information from a GOV.UK Wallet holder’s device
GOV.UK Wallet lets your verification process receive credential information when a user agrees to share it. GOV.UK Wallet shares credential information over a Bluetooth Low Energy (BLE) connection using the Generic Attribute Profile (GATT) protocol.
To retrieve credential information from GOV.UK Wallet you must have this capability. There is more guidance on the in-person sharing flow.
Connect to a credential holder’s device
When sharing credential details, GOV.UK Wallet will make the holder’s device discoverable for you to connect. This is known as taking the Peripheral (server) role. GOV.UK Wallet sets this role in the RetrievalOptions when you first read the holder’s QR code. You must take the Central (client) role and request to connect to the holder’s device.
Sending and receiving messages via Bluetooth
When a holder’s device takes the peripheral role, GOV.UK Wallet will create a GATT service with the following characteristics:
| Name | UUID | Properties |
|---|---|---|
State |
00000001-A123-48CE-896B-4C76973373E6 | Notify, Write Without Response |
Client2Server |
00000002-A123-48CE-896B-4C76973373E6 | Write Without Response |
Server2Client |
00000003-A123-48CE-896B-4C76973373E6 | Notify |
You can find the UUIDs of these characteristics in the ISO/IEC 18013-5 standard.
Once you have connected to a holder’s device, you can ask GOV.UK Wallet to share encrypted credential information.
Connecting in the central role
When connected in the central role, you can:
- set the
Statecharacteristic to0x01to indicate you are ready to receive messages - send a message to the holder’s device using the
Client2Servercharacteristic to begin session establishment
The maximum length of a message is 512 bytes. You must divide any messages larger than this into parts.
Connecting in the peripheral role
When connected in the peripheral role, GOV.UK Wallet will send DeviceResponse messages to your verification device using the Server2Client characteristic.
Once GOV.UK Wallet and your verification device have confirmed the secure session, you will be able to retrieve encrypted credential information. You can use this information in your verification service.
You may receive divided messages that need to be reassembled. This is likely when you request photos from a user’s credential.
Cancelling a sharing session
The central device or the peripheral device can cancel a sharing session. If your verification service needs to cancel a session, you must set the State characteristic to 0x02. Your verification process must listen for any messages which change the State value because the holder’s device can also update this characteristic.
Sending a session establishment message
When your connection is ready, you will be able to send a message to request encrypted credential information from GOV.UK Wallet. This must be a SessionEstablishment structure in the form of a Concise Binary Object Representation (CBOR). The CBOR will contain your:
- encrypted device request
- ephemeral public key used only for this session
Device request structure
The DeviceRequest structure you include in your SessionEstablishment.data element tells GOV.UK Wallet which attributes you wish to use in your verification process.
You must encrypt your DeviceRequest using a symmetric key. You must use this same key to decrypt the DeviceResponse message you receive from the holder.
Below is an example CBOR diagnostic requesting mandatory elements from an mDL:
{
"version": "1.1",
"docRequests": [
{
"itemsRequest": 24(<<
{
"docType": "org.iso.18013.5.1.mDL",
"nameSpaces": {
"org.iso.18013.5.1": {
"portrait": true,
"given_name": true,
"age_over_21": false,
"family_name": true
}
}
}
>>)
}
]
}
There is guidance on the credentials that are available in GOV.UK Wallet.
Public key
You must derive a symmetric key to encrypt the session and your DeviceRequest. There is detailed guidance on how to derive a symmetric key in Section 9.1.1.5 (Cryptographic operations) of the ISO/IEC 18013-5 specification.
You must use ECDH to derive a symmetric key (shared secret) from:
- the holder’s public key that you received when you scanned their QR code
- your private key
The key you create must match the encryption type of the public key you received from the holder. This will be either Curve P-256 or Curve P-384.
You should only use your key for a single presentation session, and only store it in temporary memory.
Example session establishment structure
Below is an example SessionEstablishment CBOR containing the elements GOV.UK Wallet needs to begin sharing:
SessionEstablishment
├── eReaderKey : #6.24(bstr .cbor EDeviceKey)
└── data : bstr ; Encrypted device request
Below is an example of the SessionEstablishment as a CBOR diagnostic:
{
"eReaderKey": 24(h'A420010102215820FF7E64F18B0352E789....B')
"data": h'41ed0d148104f57dab1a8dc9485f5662ae76.....ff'
}
Understand the session transcript
During session establishment, the peripheral and central devices will create a session transcript in the form of a SessionTranscript structure. This transcript is used when generating a unique key for the sharing session, which helps to prevent a sharing session from being altered or reused.
The SessionTranscript will contain:
| Element | Description | Data type |
|---|---|---|
DeviceEngagementBytes |
DeviceEngagement structure in the format of a base64 URL encoded CBOR. |
bstr |
EReaderKeyBytes |
SessionEstablishment eReaderKey in the format of a base64 URL encoded CBOR. |
bstr |
Handover |
GOV.UK Wallet uses a QR code for handover, and will set this element to null. |
null |
Below is an example of a SessionTranscript CBOR:
SessionTranscript = [
├── DeviceEngagementBytes : #6.24(bstr .cbor DeviceEngagement)
├── EReaderKeyBytes : #6.24(bstr .cbor EReaderKeyBytes)
└── Handover : QRHandover
└── null
Handling device request errors
If you can not establish a connection to a holder’s device, you must terminate the session. Before you terminate the session, you should send a SessionData message containing the appropriate status code.
GOV.UK Wallet will expect one of the following status codes:
| Status code | Description |
|---|---|
| 10 | There was an error encrypting the device request. |
| 11 | There was an error decoding the GOV.UK Wallet QR code. |
| 20 | Non-specific error or session termination. |
This is an example of a SessionData message:
SessionData = {
? "status": uint ; status code from table above
}