Receive credential information from a GOV.UK Wallet holder’s device
When you establish your sharing session, GOV.UK Wallet will ask the user for consent to share their credential information. If the user agrees, GOV.UK Wallet will send a DeviceResponse message through your secure session. This message is a Concise Binary Object Representation (CBOR) encrypted with ECDH. You must decrypt it with the same symmetric key you used to encrypt your DeviceRequest message.
The GOV.UK Wallet DeviceResponse structure will contain:
| Element | Description | Data type |
|---|---|---|
version |
The version of the DeviceResponse structure. Set to "1.0". |
str |
documents |
An array containing signed digital documents. | [Document]+ |
Understand the elements in a device response structure
Documents shared in GOV.UK Wallet’s DeviceResponse structure will contain:
| Element | Description | Data type |
|---|---|---|
docType |
The standardised identifier for the document type. | DocType |
issuerSigned |
A CBOR map containing mdoc nameSpaces and IssuerAuth. |
{nameSpaces: {str, arr},issuerAuth: arr }
|
deviceSigned |
A CBOR map containing the deviceSignature. |
{nameSpaces: {str, arr},deviceAuth: map }
|
errors |
An optional CBOR map containing namespace identifiers and error codes. |
errors: {tstr, uint} |
This is an example DeviceResponse CBOR for an mDL docType:
DeviceResponse
├── version : tstr
├── ? documents : [Document]+
│ └── Document
│ ├── docType : "org.iso.18013.5.1.mDL"
│ ├── issuerSigned
│ │ ├── {NAMESPACES}
│ │ └── issuerAuth : {ISSUER_AUTH}
│ └── ? errors
│ └── {ERRORS}
Example issuer signed CBOR
The issuerSigned structure contains nameSpaces taken from the credential stored in the GOV.UK Wallet. These are set by the credential issuer and represent the fields present on the physical document.
You can use the elementIdentifier and elementValue in each NameSpace in your verification process.
IssuerAuth is a COSE_Sign1 object, containing cryptographic information used when verifying each NameSpace.
This is an example issuerSigned CBOR, containing an mDL age_over_25 element:
├── issuerSigned
│ │ ├── ? nameSpaces : NameSpace => [IssuerSignedItemBytes]+
│ │ │ └── IssuerSignedItemBytes = #6.24(bstr .cbor IssuerSignedItem)
│ │ │ └── "org.iso.18013.5.1"
│ │ │ ├── digestID : 0
│ │ │ ├── random : h'8798645B20EA200E19FFABAC92624BEE6AEC63
│ │ │ ├── elementIdentifier : age_over_25
│ │ │ └── elementValue : false
│ │ └── issuerAuth : [
; COSE_Sign1 - copied from initial mdoc issuance
]
There is more guidance on the credentials available in GOV.UK Wallet.
Example device signed CBOR
The deviceSigned structure contains a deviceAuth CBOR map that lets you verify ownership of the credential being shared. The deviceAuth holds deviceSignature, which is signed with the private key that matches the public key present in the Mobile Security Object (MSO).
You must verify the deviceAuth to confirm that the credential is being presented from the same device it was issued to. If you can not verify the deviceAuth, you must not rely on the data in the credential and must discard it. There is more guidance on validating the MSO in the ISO/IEC 18013-5 specification.
GOV.UK Wallet’s deviceSigned structure also contains an empty nameSpaces array. GOV.UK Wallet will only share issuer signed credentials.
This is an example deviceSigned CBOR:
├── deviceSigned
│ │ ├── nameSpaces : DeviceNameSpacesBytes => [Device] # Empty CBOR map
│ │ └── deviceAuth
│ │ ├── deviceSignature : DeviceSignature
Example device response CBOR diagnostic
The example below shows a GOV.UK Wallet mDL DeviceResponse. In this example the holder has consented to share their:
- family name
- confirmation of age over 18
{
"version": "1.0",
"documents": [
{
"docType": "org.iso.18013.5.1.mDL",
"issuerSigned": {
"nameSpaces": {
"org.iso.18013.5.1" : [
24(<<
{
"digestID": 0
"random": h'8798....'
"elementIdentifier": "family_name"
"elementValue": "Johnson"
}
>>),
24(<<
{
"digestID": 0
"random": h'87986....'
"elementIdentifier": "age_over_18"
"elementValue": "true"
}
>>)
],
}
"issuerAuth": [
COSE_Sign1(....
]
},
"deviceSigned": {
"nameSpaces": [ ],
"deviceAuth": {
"deviceSignature": [
COSE_Sign1(....
]
}
}
}
],
"status": 0
}