Digital Credentials Harmonized Presentation - Editor's Copy

5.1. Request Structure

The top-level CredentialRequest contains:¶

The RequestPayload contains:¶

5.2. Scenario Sets

A ScenarioSet represents an overarching purpose or business context (e.g., "Age Verification", "Identity Check"). It references the credential definitions via CredentialRef and defines the valid combinations a wallet can use to satisfy the scenario. ScenarioSets are carried as a map in RequestPayload, keyed directly by ScenarioRef, so the scenario_ref field is the map key rather than an item inside the structure.¶

• A CredentialCombination is an array of CredentialRef values - all referenced credentials must be presented (logical AND).¶
• The wallet need only satisfy one combination per ScenarioSet (logical OR across combinations).¶

5.3. Credential Queries

A CredentialQuery defines the exact credential requirements for a single credential type.¶

5.4. Data Elements & Logic

ElementLogic  = [ + OrGroup ]   ; Level 1 — AND: ALL OrGroups must be satisfied
OrGroup       = [ + AndGroup ]  ; Level 2 — OR:  AT LEAST ONE AndGroup must be satisfied
AndGroup      = [ + ElementRef ] ; Level 3 — AND: ALL referenced elements must be provided

6.1. Multi-Key Routing

The request defines a primary encryption_context and optionally additional contexts in additional_encryption_contexts, keyed by integer. Each CredentialQuery may carry an optional encryption_ref pointing to one of the additional contexts by integer key. If encryption_ref is absent the credential uses the primary encryption_context. If encryption_context is also absent (BLE/NFC session encryption), the credential is unencrypted at the application layer. This allows a wallet to encrypt an "Identity" credential for one backend and a "Payment" credential for a different backend within the same response payload.¶

6.2. EncryptionContext

6.3. Algorithm

For non-post-quantum-cryptography (non-PQC) operations, HPKE is mandated, potentially based on draft-ietf-cose-hpke.¶

8.1. ReaderTransactionTranscript

8.2. WalletTransactionTranscript

The wallet determines the applicable value from CredentialQuery.encryption_ref: if present, it is copied directly into this field; if absent, the field is omitted (indicating the main encryption_context is used or no application-layer encryption applies).¶

8.3. Channel Binding

ChannelBinding is a CBOR map capturing the engagement and transmission channel used to initiate the session. The fields present depend on the transport. At most one engagement field and at most one transmission field will be present for any given session.¶

8.4. Use in Protocol Operations

9.1. Envelope Structure

An Envelope contains a credential pool and a scenario map:¶

The CredentialRef keys in the pool are the same integers used in the request's CredentialQueries map, so the verifier can directly correlate a returned credential to the query that requested it without any additional mapping.¶

Each CredentialItem:¶

9.2. Credential Data Types

The type and encoding of data are defined by the credential format definition for the credential format identified by format, see Credential Formats.¶

10.1. Requirements on Credential Format Definitions

A credential format definition shall specify:¶

1. the value of the credential format identifier (credential_format);¶
2. the content of the credential type field (credential_type);¶
3. the meaning of the path element of a DataElementDef, and how it relates to specific fields in the credential and in the response;¶
4. how value matching (value_match) works;¶
5. how the issuer identifier request (issuer_identifiers) applies;¶
6. any format-specific extensions (format_extensions), for example cryptographic algorithm values;¶
7. how the cryptographic binding parameter request (support_no_cryptographic_binding) applies;¶
8. the structure of the credential data (data) returned in the response for this format;¶
9. what the transaction data request (credential_auth_data) means for this format;¶
10. how the transaction transcript is included in the response.¶

A credential format definition extends the $formatExtensions and $CredentialData CDDL sockets defined in CDDL Definitions with the types it defines for format_extensions and data.¶

11.1. Request CDDL

; ==========================================
; TOP-LEVEL REQUEST
; ==========================================

CredentialRequest = {
  payload:        1 => bstr,      ; CBOR-encoded RequestPayload
  ? reader_auth:  2 => COSE_Sign, ; Optional reader authentication (detached payload)
  * int => any                    ; RFU extensions
}

RequestPayload = {
  ScenarioSets:                     1 => { + ScenarioRef => ScenarioSet },
  CredentialQueries:                2 => { + CredentialRef => CredentialQuery },
  ? encryption_context:             3 => EncryptionContext,
  ? additional_encryption_contexts: 4 => { + int => EncryptionContext },
  * int => any                      ; RFU extensions
}

ScenarioRef   = int
CredentialRef = int

; ==========================================
; ENCRYPTION PARAMETERS
; ==========================================

EncryptionContext = {
  key:        1 => COSE_Key,
  nonce:      2 => bstr,
  algorithms: 3 => [ + int ],     ; COSE algorithm identifiers (e.g. HPKE ciphersuites)
  * int / tstr => any             ; RFU / application-specific extensions
}

; ==========================================
; SCENARIO SETS
; ==========================================

ScenarioSet = {
  mandatory:    1 => bool,
  combinations: 2 => [ + CredentialCombination ],
  purpose_id:   3 => [ controlled_id: tstr, + int ],
  ? extensions: 4 => { * int / tstr => any }, ; int = RFU, tstr = application-specific
  * int => any                    ; RFU extensions
}

CredentialCombination = [ + CredentialRef ]

; ==========================================
; CREDENTIAL QUERIES & EXTENSIONS
; ==========================================

CredentialQuery = {
  credential_format:    1 => tstr,
  credential_type:      2 => tstr,
  elements_dict:        3 => { + ElementRef => DataElementDef },
  requested_elements:   4 => ElementLogic,
  ? general_extensions: 5 => generalExtensions,
  ? format_extensions:  6 => $formatExtensions, ; Socket, see below
  ? encryption_ref:     7 => int,   ; Key into additional_encryption_contexts; absent = use main
  * int => any                      ; RFU extensions
}

generalExtensions = {
  ? issuer_identifiers:               1 => IssuerIdentifiers,
  ? allow_multiple:                   2 => bool,
  ? credential_auth_data:             3 => { + int / tstr => any },
  ? support_no_cryptographic_binding: 4 => bool,
  * int / tstr => any             ; int = RFU, tstr = application-specific
}

; $formatExtensions is a socket (RFC 8610, Section 3.9): each credential
; format definition adds its own extensions structure to it, e.g.
;   $formatExtensions /= mdocExtensions

IssuerIdentifiers = {
  ? x509_ref: 1 => [ + bstr ],
  * int / tstr => [ + any ]       ; int = RFU, tstr = application-specific
}

; ==========================================
; DATA ELEMENTS & LOGIC
; ==========================================

ElementRef = int

DataElementDef = {
  path:               1 => [ + tstr ],
  ? value_match:      2 => any,
  intent_to_retain:   3 => bool,
  * int => any                    ; RFU extensions
}

; Conjunctive Normal Form (CNF): AND of OR of AND
ElementLogic = [ + OrGroup ]    ; Level 1 (AND): All OrGroups must be satisfied
OrGroup      = [ + AndGroup ]   ; Level 2 (OR):  At least one AndGroup must be satisfied
AndGroup     = [ + ElementRef ] ; Level 3 (AND): All referenced elements must be provided

11.2. Response CDDL

; ==========================================
; PRIMITIVE TYPE ALIASES
; ==========================================

; full-date is defined in RFC 8943 as CBOR tag 1004 applied to a text string (tstr).
full-date = #6.1004(tstr)

; ==========================================
; TOP-LEVEL RESPONSE
; ==========================================

CredentialResponse = {
  ? unencrypted:  1 => Envelope,
  ? encrypted:    2 => [ + COSE_Encrypt ], ; Each item decrypts to bytes .cbor Envelope
  * int => any                             ; RFU extensions
}

; Both unencrypted and encrypted envelopes share the same structure.
; Each envelope is self-contained: credentials that must appear in multiple
; envelopes are duplicated; no cross-envelope references are permitted.
Envelope = {
  credentials:    1 => { + CredentialRef => CredentialItem },
  scenarios:      2 => { + ScenarioRef   => [ + CredentialRef ] },
  * int => any                             ; RFU extensions
}

CredentialItem = {
  format:         1 => tstr,
  data:           2 => $CredentialData,      ; Socket, see below
  * int => any                             ; RFU extensions
}

; ==========================================
; FORMAT-SPECIFIC DATA
; $CredentialData is a socket (RFC 8610, Section 3.9): each credential
; format definition adds the type of its credential data to it, e.g.
;   $CredentialData /= Document
; ==========================================

External type references: COSE_Sign, COSE_Key, COSE_Encrypt - defined in RFC 9052 (COSE); COSE_X509 - defined in RFC 9360; full-date - defined in RFC 8943 (CBOR Tags for Date).¶

11.3. Transaction Transcript CDDL

; ==========================================
; TRANSACTION TRANSCRIPTS
; Deterministic CBOR encoding (RFC 8949 §4.2) is REQUIRED for all transcript values.
; ==========================================

; Used by the verifier: for reader authentication and as info parameter for response encryption.
ReaderTransactionTranscript = {
  request_hash:    1 => bstr,          ; SHA-256 of CBOR-encoded RequestPayload bytes
  channel_binding: 2 => ChannelBinding,
  * int / tstr => any                  ; RFU / application-specific extensions
}

; Used by the wallet: for credential authentication (as defined by the credential format definition) and response encryption.
; Includes the encryption_ref from the CredentialQuery for the credential being presented.
WalletTransactionTranscript = {
  request_hash:         1 => bstr,          ; Same value as in ReaderTransactionTranscript
  channel_binding:      2 => ChannelBinding,
  ? encryption_context: 3 => int,           ; The encryption_ref from CredentialQuery;
                                            ; absent when no application-layer encryption is used
  * int / tstr => any                       ; RFU / application-specific extensions
}

; ==========================================
; CHANNEL BINDING
; At most one engagement field and at most one transmission field are present per session.
; ==========================================

ChannelBinding = {
  ; --- Engagement fields (keys 1–9) ---
  ; Capture how the credential request was initiated.
  ? qr_device_engagement:              1 => bstr,  ; 18013-5 QR:              CBOR-encoded DeviceEngagement
  ? reverse_qr_device_engagement:      2 => bstr,  ; 18013-5 Reverse QR:      CBOR-encoded DeviceEngagement
  ? nfc_static_handover_engagement:    3 => bstr,  ; 18013-5 NFC static:      CBOR-encoded DeviceEngagement
  ? nfc_negotiated_handover_engagement: 4 => bstr, ; 18013-5 NFC negotiated:  CBOR-encoded DeviceEngagement
  ? oidc4vp_request_uri:               5 => tstr,  ; OID4VP:                  request_uri from the authorisation request
  ? oidc4vp_client_id:                 6 => tstr,  ; OID4VP:                  client_id from the authorisation request
  ? dc_api_origin:                     7 => tstr,  ; DC API:                  web origin (scheme://host[:port])

  ; --- Transmission fields (keys 10–19) ---
  ; Capture the data-transport channel over which the presentation is performed.
  ? ble_uuid:                 10 => bstr,           ; 18013-5 BLE (UUID):      EReaderKey bytes
  ? ble_l2cap:                11 => {               ; 18013-5 BLE L2CAP:       EReaderKey + PSM
                                   uuid: 1 => bstr, ;   Reader ephemeral public key
                                   psm:  2 => uint  ;   L2CAP Protocol/Service Multiplexer value
                                 },
  ? nfc_static_handover:      12 => bstr,           ; 18013-5 NFC static:      CBOR-encoded NFCHandover
  ? nfc_negotiated_handover:  13 => bstr,           ; 18013-5 NFC negotiated:  CBOR-encoded NFCHandover
  ? nfcv2:                    14 => bstr,           ; NFC v2:                  NFC v2 transmission data
  ? wifi_aware:               15 => bstr,           ; 18013-5 WiFi Aware:      engagement data

  * int / tstr => any                               ; RFU / application-specific extensions
}

A.1. Credential Format Identifier

The credential_format value for mdocs is mso_mdoc. The format field of a CredentialItem carrying an mdoc has the same value.¶

A.2. Credential Type

credential_type contains the mdoc DocType (e.g., org.iso.18013.5.1.mDL). A CredentialQuery with this value matches mdocs whose docType is identical to the requested value, compared as text strings; the comparison is case-sensitive.¶

A.3. Path

The path of a DataElementDef has exactly two elements: the NameSpace and the DataElementIdentifier of the requested data element, in that order, e.g., ["org.iso.18013.5.1", "family_name"]. In the response, the requested data element is returned under that namespace in the Document, either as an IssuerSignedItem in IssuerNameSpaces or in DeviceSignedItems in DeviceNameSpaces, as defined in ISO/IEC 18013-5. Which of the two is used is determined by the mdoc, subject to the KeyAuthorizations granted by the issuing authority in the MSO; the verifier validates this as part of mdoc authentication, as defined in ISO/IEC 18013-5.¶

; An mdoc DataElementDef.path is [ NameSpace, DataElementIdentifier ]
NameSpace             = tstr   ; as defined in ISO/IEC 18013-5
DataElementIdentifier = tstr   ; as defined in ISO/IEC 18013-5

A.4. Value Matching

To be completed; tracked in issue #9.¶

A.5. Issuer Identifiers

An mdoc satisfies the issuer_identifiers request if one of the values in x509_ref is equal to the KeyIdentifier of the AuthorityKeyIdentifier extension of one of the certificates in the x5chain element of the IssuerAuth header of the mdoc.¶

Note: The IACA root certificate is not included in the x5chain. A verifier that includes the subject key identifier of the certificate it uses to verify mdocs from a particular issuer (e.g., the IACA certificate) will match the authority key identifier of one of the certificates in the x5chain.¶

Editor's note: This is the same rule as the IssuerIdentifiers structure being defined in the second edition of ISO/IEC 18013-5.¶

A.6. Format-Specific Extensions

For mdocs, format_extensions contains an mdocExtensions map, which extends the $formatExtensions socket:¶

Note: A verifier that has no constraint on one of the two algorithm classes should include the field with a permissive list of acceptable values rather than omitting it.¶

$formatExtensions /= mdocExtensions

mdocExtensions = {
  ? issuer_alg_values: 1 => [ + int ],   ; COSE algorithm identifiers
  ? device_alg_values: 2 => [ + int ],   ; COSE algorithm identifiers
  * int / tstr => any             ; int = RFU, tstr = application-specific
}

A.7. Cryptographic Binding

Cryptographic binding for mdocs is mdoc authentication: the DeviceAuth structure in DeviceSigned, produced with the device key in the DeviceKeyInfo structure of the MSO, as defined in ISO/IEC 18013-5.¶

An mdoc whose MSO does not contain a DeviceKeyInfo structure is a non-key-bound mdoc: its Document contains no DeviceSigned structure and mdoc authentication does not apply to it. support_no_cryptographic_binding corresponds to the nonKeyBoundSupported element of DocRequestInfo in ISO/IEC 18013-5. If support_no_cryptographic_binding is true, the wallet may return a non-key-bound mdoc; otherwise, the wallet shall not return a non-key-bound mdoc.¶

Editor's note: Non-key-bound mdocs are introduced by the second edition of ISO/IEC 18013-5. The text above and the note below follow the changes proposed for its DIS ballot and are to be checked against the published text; tracked in issue #56.¶

Note: ISO/IEC 18013-5 requires an mDL (org.iso.18013.5.1.mDL) to always be key-bound; non-key-bound mdocs are only possible for other document types.¶

A.8. Response Structure

A CredentialItem carrying an mdoc has format set to mso_mdoc and data set to a Document: a byte string containing the CBOR-encoded ISO/IEC 18013-5 Document structure (docType, issuerSigned, deviceSigned unless the mdoc is non-key-bound, and, if applicable, errors) for the presented mdoc. Document extends the $CredentialData socket.¶

$CredentialData /= Document

Document = bstr   ; CBOR-encoded ISO/IEC 18013-5 Document structure

A.9. Transaction Data

To be completed; tracked in issue #4.¶

A.10. Transaction Transcript

The WalletTransactionTranscript for the credential (see Transaction Transcript) is bound into mdoc authentication: it is embedded in the SessionTranscript that forms part of the DeviceAuthentication structure that is signed or MACed to produce DeviceAuth.¶

The exact derivation of the SessionTranscript from the WalletTransactionTranscript is to be completed; tracked in issue #10.¶

B.1. Credential Format Identifier

The credential_format value for SD-JWT VCs is dc+sd-jwt. The format field of a CredentialItem carrying an SD-JWT VC has the same value.¶

B.2. Credential Type

credential_type contains the value of the vct claim of the SD-JWT VC. A CredentialQuery with this value matches SD-JWT VCs whose vct claim is identical to the requested value, compared as text strings; the comparison is case-sensitive.¶

Editor's note: Whether a CredentialQuery also matches SD-JWT VCs whose type inherits from the requested vct (as OpenID4VP permits for vct_values, following the inheritance logic of SD-JWT VC) has not been decided; tracked in issue #53.¶

B.3. Path

The path of a DataElementDef is the sequence of JSON object keys leading from the root of the SD-JWT VC payload (after all Disclosures have been processed) to the requested claim; each element of the path selects the member with that name one level deeper, e.g., ["address", "street_address"]. In the response, the requested claim is returned by including the Disclosures needed to reveal it, together with those of any selectively disclosable parent objects.¶

Editor's note: path is typed as [ + tstr ], so it cannot currently address individual array elements (the DCQL claims path pointer in OpenID4VP uses null and non-negative integers for this). Whether that is needed is tracked in issue #52.¶

B.4. Value Matching

To be completed; tracked in issue #9.¶

B.5. Issuer Identifiers

When the Issuer-signed JWT carries an x5c header, the SD-JWT VC satisfies the issuer_identifiers request if one of the values in x509_ref is equal to the KeyIdentifier of the AuthorityKeyIdentifier extension of one of the certificates in that x5c header.¶

Editor's note: SD-JWT VC issuers can also be identified without X.509 certificates, through the iss claim (an HTTPS URL resolved via JWT VC Issuer Metadata) or a DID. issuer_identifiers currently only defines x509_ref; how such issuers are requested is to be completed.¶

B.6. Format-Specific Extensions

For SD-JWT VCs, format_extensions contains an sdjwtExtensions map, which extends the $formatExtensions socket:¶

$formatExtensions /= sdjwtExtensions

sdjwtExtensions = {
  ? sd-jwt_alg_values: 1 => [ + tstr ],  ; JWS "alg" values
  ? kb-jwt_alg_values: 2 => [ + tstr ],  ; JWS "alg" values
  * int / tstr => any             ; int = RFU, tstr = application-specific
}

B.7. Cryptographic Binding

Cryptographic binding for SD-JWT VCs is Key Binding: a KB-JWT signed with the key in the cnf claim of the SD-JWT VC, as defined in SD-JWT.¶

If support_no_cryptographic_binding is true, the wallet may return an SD-JWT VC that has no cnf claim, presented without a KB-JWT; otherwise, the wallet shall not return such an SD-JWT VC. An SD-JWT VC that has a cnf claim shall always be presented with a KB-JWT.¶

B.8. Response Structure

A CredentialItem carrying an SD-JWT VC has format set to dc+sd-jwt and data set to SdJwtData: a text string containing the SD-JWT presentation in its compact serialization, <Issuer-signed JWT>~<Disclosure 1>~...~<Disclosure N>~<KB-JWT>. When no KB-JWT is included, the presentation ends with the trailing ~, as defined in SD-JWT. SdJwtData extends the $CredentialData socket.¶

$CredentialData /= SdJwtData

SdJwtData = tstr   ; SD-JWT presentation, compact serialization

B.9. Transaction Data

To be completed; tracked in issue #4.¶

B.10. Transaction Transcript

The SHA-256 hash of the CBOR-encoded WalletTransactionTranscript for the credential (see Transaction Transcript) is used as the value of the nonce claim in the KB-JWT.¶

Editor's note: The string encoding of the hash in the nonce claim (e.g., base64url) and the value of the KB-JWT aud claim are not yet specified; tracked in issue #10.¶