Attesto.Mdoc (Attesto v2.28.0)

Copy Markdown View Source

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 x5chain as 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: false disables 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

key_authorizations()

@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.

validity()

@type validity() :: %{
  signed: integer(),
  valid_from: integer(),
  valid_until: integer()
}

verified()

@type verified() :: %{
  :doc_type => String.t(),
  :namespaces => %{required(String.t()) => %{required(String.t()) => term()}},
  :device_key => map(),
  :key_authorizations => key_authorizations(),
  :validity => validity(),
  optional(:status) => map()
}

verified_presentation()

@type verified_presentation() :: %{
  :doc_type => String.t(),
  :namespaces => %{required(String.t()) => %{required(String.t()) => term()}},
  :device_namespaces => %{
    required(String.t()) => %{required(String.t()) => term()}
  },
  :validity => validity(),
  optional(:status) => map()
}

verify_error()

@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_issuer_signed(input)

@spec decode_issuer_signed(binary()) :: {:ok, map()} | {:error, :invalid_mdoc}

Decode an IssuerSigned mdoc supplied as base64url or raw CBOR bytes, enforcing core's 262144-byte decoded CBOR limit.

device_authentication_bytes(session_transcript, doc_type, device_namespaces)

@spec device_authentication_bytes(list(), String.t(), struct()) :: binary()

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.

extract_x5chain(input)

@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(opts)

@spec issue(keyword()) :: {:ok, String.t()} | {:error, :invalid_options}

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.

max_cbor_bytes()

@spec max_cbor_bytes() :: pos_integer()

Maximum accepted decoded CBOR size in bytes of an mdoc payload.

peek_doc_type(device_response)

@spec peek_doc_type(binary()) :: {:ok, String.t()} | {:error, :invalid_mdoc}

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.

peek_status(input)

@spec peek_status(binary()) :: {:ok, map() | nil} | {:error, :invalid_mdoc}

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.

session_transcript(context)

@spec session_transcript(keyword()) ::
  {:ok, list()} | {:error, :invalid_context | :invalid_key}

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.

verify(input, trusted, opts \\ [])

@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.

verify_device_response(device_response, context, trusted, opts \\ [])

@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.