Issue and verify ISO 18013-5 mdoc credentials and OID4VP mdoc presentations.
Issuance builds the MobileSecurityObject (MSO), binds the holder's device
key, and signs issuer authentication with ES256 COSE_Sign1. verify/3
checks issuer signatures, item digests, and validity for a bare
IssuerSigned structure. The document type is bound ONLY when
:expected_doc_type is supplied — without it, any doc type from a trusted
issuer is accepted, so a caller that needs a specific doc type (e.g. a DCQL
mso_mdoc query) MUST pass it. Attesto.VpToken threads this via its
:query_constraints for the OID4VP path.
verify_device_response/4 additionally verifies an OID4VP presentation: a
full ISO 18013-5 DeviceResponse whose DeviceSigned.deviceAuth is an
ES256 COSE_Sign1 (detached payload) over DeviceAuthentication = ["DeviceAuthentication", SessionTranscript, DocType, DeviceNameSpacesBytes], where SessionTranscript's Handover is OID4VP's
OpenID4VPHandover by default, or OpenID4VPDCAPIHandover when
:dc_api_origin is supplied. COSE_Mac0 device authentication is not
supported. Device signatures and device keys remain ES256/P-256 only.
## Handover and issuer algorithms
OpenID4VP 1.0 §B.2.6.2
says of the origin: "It MUST NOT be prefixed with origin:." The DC API
transcript hashes CBOR [origin, nonce, jwkThumbprint], using a byte-string
SHA-256 JWK thumbprint for encrypted responses and null otherwise.
§2 defines web origins as scheme, host and non-default port; platform
application URIs are also permitted. Supply the exact platform origin,
without a path or trailing slash for web origins. No normalization occurs.
§B.2.6.1 continues to govern the default redirect transcript.
ISO/IEC TS 18013-7:2025 §6.4.3.1, Table 1 distinguishes "OID4VP" (Annex B) from "Digital credentials API retrieval" (Annex C). This module implements the OpenID4VP 1.0 handover, not the separate ISO Annex C protocol; ISO §2 references OpenID4VP draft 18.
ISO/IEC 18013-5:2021 §9.1.2.4 requires readers to "support all of these signature algorithms and curves". It permits ES256/P-256, ES384/P-384 and ES512/P-521 for issuerAuth. §9.1.3.6 applies these pairings to device signatures too; §9.1.5.2, Table 22 also requires EdDSA and brainpool support from readers. Those additional curves are unimplemented, so this is a subset of ISO reader functionality. §9.1.5.1 defines the underlying session transcript.
HAIP 1.0 §7
specifies ES256 "at a minimum", allowing ecosystem cryptographic suites.
It does not prohibit ES384 or ES512 issuer signatures. Its
§5.2
says the verifier "MUST use the Response Mode dc_api.jwt"; unencrypted DC API verification
here does not satisfy that flow profile. :haip controls certificate
policy only, not transport compliance.
Issuer verification accepts ES256 by default for compatibility. Opt into
accepted_algs: ["ES256", "ES384", "ES512"] on verify/3,
verify_device_response/4, or Attesto.VpToken.verify/2. A supported COSE
algorithm paired with the wrong EC curve returns :algorithm_key_mismatch,
including under certificate trust. See Attesto.Cose for RFC 9053 details.
peek_doc_type/1 reads an unverified docType out of a DeviceResponse
for issuer-key resolution ahead of verification; see Attesto.VpToken.
## Certificate trust
With :trusted_certificates, issuer authentication validates the leaf-first
x5chain in issuerAuth's unprotected header (COSE label 33), then uses only
that leaf's public key. The following text informs this path:
- ISO/IEC 18013-5:2021 §9.1.2.4
places the MSO signing certificate in
x5chainas an "unprotected header element". §9.3.3 requires "RFC 5280, section 6.1 basic path validation"; §9.3.1 steps 1–2 use the validated certificate key for issuerAuth. Annex B.1.1 puts the document signer first and excludes the IACA root. - HAIP 1.0 §3.4
leaves "authorization of an Issuer to issue certain types of credentials"
outside its scope. Its §6.1.1 issuer-key rules explicitly concern SD-JWT
VC. Attesto also defaults mdoc to
haip: true, refusing a self-signed leaf or an embedded configured anchor.haip: falsedisables these two restrictions while retaining path validation.
There is no docType-to-certificate-name binding in these provisions.
§9.3.1 step 4 binds the MSO's docType to the presented document's docType,
which verify_device_response/4 checks. Requested types are constrained
separately by :expected_doc_type or Attesto.VpToken's DCQL checks.
Trust in a certificate does not itself establish authorization for every
document type; hosts supply their ecosystem's authorization policy.
This path uses Attesto.X509 with purpose: :mdoc_issuer, recognizing the
critical document-signer extended key usage. It does not implement every
ISO certificate-profile rule: IACA country/state matching, revocation,
and the MSO signing-time check against certificate validity remain outside
this path. Hosts can add certificate policy via :certificate_trust.
No certificate or revocation data is fetched.
Credential status references are fetched and enforced by default through
Attesto.StatusList.fetch/3 and its bounded verified-token cache. Explicit
resolve_status: false is for offline inspection; it must not be used to
decide whether a credential is acceptable. A custom resolver can replace
the transport while retaining signature and status enforcement.
Summary
Types
What the issuer authorized the device key to sign, from the MSO's
deviceKeyInfo.keyAuthorizations (ISO/IEC 18013-5 §9.1.2.4): whole
namespaces, and individual data elements by namespace. Both are empty when
the MSO carries no authorization.
Functions
Decode an IssuerSigned mdoc supplied as base64url or raw CBOR bytes, enforcing core's 262144-byte decoded CBOR limit.
The ISO/IEC 18013-5 DeviceAuthenticationBytes that a Wallet signs as the
detached payload of DeviceSigned.deviceAuth.deviceSignature, and that
verify_device_response/4 checks the signature against:
#6.24(bstr .cbor ["DeviceAuthentication", SessionTranscript, DocType, DeviceNameSpacesBytes]), CBOR-encoded.
Extract the x5chain (COSE unprotected header label 33) DER certificate list
from an IssuerSigned mdoc binary, decoded IssuerSigned map, or issuerAuth list.
Issue a base64url-encoded ISO 18013-5 IssuerSigned structure.
Maximum accepted decoded CBOR size in bytes of an mdoc payload.
Peek an OID4VP DeviceResponse's first document docType, supplied as
base64url or raw CBOR bytes, without verifying any signature.
Read an IssuerSigned mdoc's unverified status reference. This only detects whether revocation checking is required; callers must verify the credential before fetching any URI from this result.
The OID4VP 1.0 SessionTranscript for an mso_mdoc presentation in the
redirect flow ("Handover and SessionTranscript Definitions"):
[null, null, ["OpenID4VPHandover", SHA-256(OpenID4VPHandoverInfo)]], where
OpenID4VPHandoverInfo is [client_id, nonce, jwkThumbprint, response_uri].
Verify an IssuerSigned mdoc supplied as base64url or raw CBOR bytes.
Verify an OID4VP mdoc presentation: a full ISO 18013-5 DeviceResponse
supplied as base64url or raw CBOR bytes.
Types
@type key_authorizations() :: %{ name_spaces: [String.t()], data_elements: %{required(String.t()) => [String.t()]} }
What the issuer authorized the device key to sign, from the MSO's
deviceKeyInfo.keyAuthorizations (ISO/IEC 18013-5 §9.1.2.4): whole
namespaces, and individual data elements by namespace. Both are empty when
the MSO carries no authorization.
@type verify_error() :: :algorithm_key_mismatch | :credential_revoked | :digest_mismatch | :expired | :invalid_cose | :invalid_identifier_list | :invalid_key | :invalid_mdoc | :invalid_signature | {:credential_status, non_neg_integer()} | :credential_suspended | :invalid_status_list | :invalid_status_list_signature | :invalid_status_list_token | :invalid_status_reference | :not_yet_valid | :status_index_out_of_range | :status_list_uri_mismatch | :unauthorized_device_element | :unexpected_doc_type | :unsupported_algorithm | Attesto.X509.verify_error() | term()
Functions
Decode an IssuerSigned mdoc supplied as base64url or raw CBOR bytes, enforcing core's 262144-byte decoded CBOR limit.
The ISO/IEC 18013-5 DeviceAuthenticationBytes that a Wallet signs as the
detached payload of DeviceSigned.deviceAuth.deviceSignature, and that
verify_device_response/4 checks the signature against:
#6.24(bstr .cbor ["DeviceAuthentication", SessionTranscript, DocType, DeviceNameSpacesBytes]), CBOR-encoded.
session_transcript is the data item returned by session_transcript/1.
device_namespaces is the DeviceNameSpacesBytes data item exactly as it
appears in DeviceSigned.nameSpaces: a tag-24 %CBOR.Tag{} wrapping the
encoded DeviceNameSpaces map.
@spec extract_x5chain(binary() | map() | list()) :: {:ok, [binary()]} | {:error, :invalid_certificate}
Extract the x5chain (COSE unprotected header label 33) DER certificate list
from an IssuerSigned mdoc binary, decoded IssuerSigned map, or issuerAuth list.
Issue a base64url-encoded ISO 18013-5 IssuerSigned structure.
Required options are :doc_type, :namespaces, :device_key,
:issuer_pem, and :validity. :x5chain optionally carries a list of
issuer-certificate DER binaries in the COSE unprotected header.
Validity must satisfy signed <= valid_from < valid_until.
:key_authorizations optionally states what the device key may sign as
device-signed data elements (ISO/IEC 18013-5 §9.1.2.4): a keyword list or
map with :name_spaces (a list of namespaces authorized in full) and/or
:data_elements (a map from namespace to a list of element identifiers).
It must authorize something, and a namespace authorized in full must not
also appear under :data_elements. Without it the device key may sign no
data elements, and a verifier refuses a presentation that carries any.
@spec max_cbor_bytes() :: pos_integer()
Maximum accepted decoded CBOR size in bytes of an mdoc payload.
Peek an OID4VP DeviceResponse's first document docType, supplied as
base64url or raw CBOR bytes, without verifying any signature.
Mirrors Attesto.JWS.peek_json peeking an SD-JWT's unverified iss:
the result is UNVERIFIED input and exists only to select candidate issuer
keys ahead of verification (e.g. for Attesto.VpToken's :resolve_issuer
callback). It MUST NOT be used to make a network request — the presenter
controls this value.
Read an IssuerSigned mdoc's unverified status reference. This only detects whether revocation checking is required; callers must verify the credential before fetching any URI from this result.
The OID4VP 1.0 SessionTranscript for an mso_mdoc presentation in the
redirect flow ("Handover and SessionTranscript Definitions"):
[null, null, ["OpenID4VPHandover", SHA-256(OpenID4VPHandoverInfo)]], where
OpenID4VPHandoverInfo is [client_id, nonce, jwkThumbprint, response_uri].
context takes :client_id, :nonce, and :response_uri (non-empty
strings). For the direct_post.jwt Response Mode it also takes the
Verifier's public :response_encryption_jwk, whose JWK SHA-256 thumbprint
becomes jwkThumbprint; without it jwkThumbprint is null.
Supplying :dc_api_origin explicitly selects §B.2.6.2's DC API flow:
the handover identifier is "OpenID4VPDCAPIHandover" and its hashed info
is [origin, nonce, jwkThumbprint]. The origin must be an exact serialized
HTTP(S) origin or a platform application URI, without an origin: prefix.
Web origins cannot contain a path, query, fragment, credentials, or an
explicit default port. The optional key represents dc_api.jwt; its
absence represents dc_api. Both transcript builders are pure functions.
Returns the CBOR data item to pass to device_authentication_bytes/3. A
Wallet signs over it and verify_device_response/4 rebuilds it from the
same request values, so both sides derive identical bytes. Errors are
:invalid_context for a missing or empty value and :invalid_key for a
response-encryption key whose thumbprint cannot be computed.
@spec verify(binary(), JOSE.JWK.t() | map() | String.t() | nil, keyword()) :: {:ok, verified()} | {:error, verify_error()}
Verify an IssuerSigned mdoc supplied as base64url or raw CBOR bytes.
trusted is the issuer's public JWK or PEM. Set :expected_doc_type to
bind verification to a requested credential type. A :now option may be
supplied as Unix seconds or a DateTime for deterministic clock checks.
:accepted_algs defaults to ["ES256"]; it can also include "ES384"
and "ES512". An empty list denies all issuer algorithms. This option
does not change device authentication or issuance.
With :trusted_certificates (DER trust anchors), trusted may be nil
and is ignored. The issuerAuth unprotected header's x5chain (label 33)
must contain a DER byte string or a non-empty array of DER byte strings,
leaf first. Attesto.X509.verify/2 validates it with purpose: :mdoc_issuer
before the signature is checked with the leaf key alone. Missing or
malformed chains return :invalid_certificate; path and policy errors
propagate from Attesto.X509. There is no fallback to trusted.
:haip defaults to true; :certificate_trust optionally adds host policy.
Certificate validity uses the system clock, independently of :now.
@spec verify_device_response( binary(), keyword(), JOSE.JWK.t() | map() | String.t() | nil, keyword() ) :: {:ok, [verified_presentation()]} | {:error, verify_error()}
Verify an OID4VP mdoc presentation: a full ISO 18013-5 DeviceResponse
supplied as base64url or raw CBOR bytes.
context supplies the OID4VP request values needed to reconstruct the
OpenID4VPHandover and SessionTranscript: :client_id, :nonce, and
:response_uri are required. :response_encryption_jwk is the
Verifier's public response-encryption key (present only for the
direct_post.jwt Response Mode) and is folded in as the handover's JWK
thumbprint; omit it for unencrypted direct_post.
Supplying :dc_api_origin instead selects the DC API flow. Only that
origin and :nonce are required; :client_id and :response_uri do not
enter this transcript. Include :response_encryption_jwk for dc_api.jwt
and omit it for dc_api. See session_transcript/1.
trusted and opts verify each document's IssuerSigned structure
exactly as in verify/3 (:expected_doc_type and :now included).
Each document's DeviceSigned.deviceAuth is additionally verified as an
ES256 COSE_Sign1 with a detached payload, signed by the device key
bound in that document's MSO.
Device-signed data elements (DeviceSigned.nameSpaces) are returned in
device_namespaces, apart from the issuer-signed namespaces: the holder's
device asserts them, the issuer does not. Each one must be authorized by
the MSO's keyAuthorizations, by its namespace in full or by name (ISO/IEC
18013-5 §9.1.3.4); otherwise the result is
{:error, :unauthorized_device_element}. An MSO with no
keyAuthorizations authorizes none.
Returns one verified result per document in the DeviceResponse.