Attesto.X509 (Attesto v2.28.0)

Copy Markdown View Source

Bounded X.509 certificate path validation and SD-JWT VC issuer binding.

verify/2 accepts a leaf-first DER certificate chain and explicit DER trust anchors in :trusted_certificates. It validates the complete path with OTP's PKIX implementation, then applies an optional :certificate_trust callback for additional host policy. The callback cannot replace path validation. Returns the verified leaf public JWK and authority key identifiers from the validated chain, and the selected DER :trust_anchor. Hosts still own ecosystem policy and revocation checking.

:purpose defaults to :generic. The :mdoc_issuer purpose recognizes a critical mdoc document-signer extended key usage on the leaf certificate. It does not accept that extension on a CA or bypass any path-validation error.

PSS-specific SubjectPublicKeyInfo keys are rejected throughout the selected path, including its trust anchor, until complete PSS parameter propagation is supported. rsaEncryption parameters must be NULL; absent parameters are accepted for interoperability. Other parameter values fail closed.

:haip defaults to false. With true, a self-signed leaf or any supplied trust anchor in the chain is refused. Both the chain and anchor list contain 1..8 certificates, each at most 65,536 DER bytes. No certificates, revocation information, or issuer metadata are fetched. OTP uses the system clock for certificate validity; credential :now options do not change that clock.

SD-JWT VC issuer binding

matches_issuer?/2 checks an already validated leaf against an HTTPS iss. URI SAN entries take precedence: if any exist, one must equal the complete issuer string. Only when none exist may a dNSName SAN equal its host, ignoring ASCII case. No wildcard, common-name, IP-address, IDNA, percent-decoding, or trailing-dot equivalence is applied. A matching URI wins even if a DNS SAN differs; a conflicting URI cannot be rescued by a matching DNS SAN.

This precedence is an explicit conservative policy, not a rule established by the specifications below:

  • SD-JWT VC draft -08 §3.5 says "iss value matches a uniformResourceIdentifier SAN entry" and also permits matching the issuer's domain against a dNSName SAN. It specifies no precedence between the alternatives.
  • SD-JWT VC draft -13 §3.5 requires the leaf key from x5c and "validates the X.509 certificate chain accordingly". It identifies the issuer by the certificate subject and does not retain the earlier SAN matching rule.
  • HAIP 1.0 §6.1.1 states "The X.509 certificate of the trust anchor MUST NOT be included" in the SD-JWT VC x5c header. It also prohibits a self-signed signing certificate. HAIP §9.4 references SD-JWT VC draft -13.
  • SD-JWT VC draft -26 §2.5 states "An iss claim, if present, is not authenticated by this mechanism". It permits recipients to require a binding according to their policy.

Selecting :trusted_certificates in Attesto.SdJwtVc.verify/3 opts into path validation and this issuer binding policy. It requires iss even in certificate identity mode. That opt-in path defaults to haip: true; this module's standalone verify/2 retains haip: false. Host authorization and revocation remain the caller's responsibility.

Summary

Functions

Decode a leaf-first JOSE x5c list using standard base64 (not base64url).

Match a validated leaf DER certificate to an HTTPS issuer identifier.

Maximum accepted DER certificate size in bytes.

Maximum accepted X.509 certificate chain length.

Maximum accepted number of trust anchors in a verification call.

Return true when anchors is a non-empty bounded list of valid DER certificate binaries.

Validate a leaf-first DER chain against explicit DER trust anchors.

Derive an OID4VP x509_hash:<base64url-sha256> client identifier from a leaf DER certificate.

Types

option()

@type option() ::
  {:trusted_certificates, [binary()]}
  | {:certificate_trust, ([binary()] -> :ok | {:error, term()})}
  | {:purpose, :generic | :mdoc_issuer}
  | {:haip, boolean()}

verified()

@type verified() :: %{
  public_key: map(),
  authority_key_identifiers: [String.t()],
  trust_anchor: binary()
}

verify_error()

@type verify_error() :: :untrusted_certificate | :invalid_certificate

Functions

decode_x5c(chain)

@spec decode_x5c(term()) :: {:ok, [binary()]} | {:error, :invalid_certificate}

Decode a leaf-first JOSE x5c list using standard base64 (not base64url).

Enforces the chain and certificate size bounds; does not establish trust.

matches_issuer?(leaf, issuer)

@spec matches_issuer?(binary(), String.t()) :: boolean()

Match a validated leaf DER certificate to an HTTPS issuer identifier.

Returns false for a mismatch, absent names, or malformed input. This function only checks names: first validate the chain with verify/2. See the module documentation for URI precedence and specification versions.

max_cert_bytes()

@spec max_cert_bytes() :: pos_integer()

Maximum accepted DER certificate size in bytes.

max_chain_length()

@spec max_chain_length() :: pos_integer()

Maximum accepted X.509 certificate chain length.

max_trust_anchors()

@spec max_trust_anchors() :: pos_integer()

Maximum accepted number of trust anchors in a verification call.

valid_trust_anchors?(anchors)

@spec valid_trust_anchors?(term()) :: boolean()

Return true when anchors is a non-empty bounded list of valid DER certificate binaries.

verify(chain, opts)

@spec verify([binary()], [option()]) :: {:ok, verified()} | {:error, verify_error()}

Validate a leaf-first DER chain against explicit DER trust anchors.

Options are :trusted_certificates (required), :certificate_trust (an optional function receiving the DER chain and returning :ok to allow it), :purpose (:generic or :mdoc_issuer), and :haip (default false). Path validation and signing-key checks precede the callback. A rejection is :untrusted_certificate; malformed inputs or raised/thrown failures may return :invalid_certificate. No unverified key is returned.

x509_hash_client_id(leaf)

@spec x509_hash_client_id(binary()) ::
  {:ok, String.t()} | {:error, :invalid_certificate}

Derive an OID4VP x509_hash:<base64url-sha256> client identifier from a leaf DER certificate.