# `Attesto.X509`
[🔗](https://github.com/XukuLLC/attesto/blob/v2.28.0/lib/attesto/x509.ex#L1)

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](https://www.ietf.org/archive/id/draft-ietf-oauth-sd-jwt-vc-08.html#section-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](https://www.ietf.org/archive/id/draft-ietf-oauth-sd-jwt-vc-13.html#section-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](https://openid.net/specs/openid4vc-high-assurance-interoperability-profile-1_0-final.html#section-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](https://www.ietf.org/archive/id/draft-ietf-oauth-sd-jwt-vc-26.html#section-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.

# `option`

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

# `verified`

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

# `verify_error`

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

# `decode_x5c`

```elixir
@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?`

```elixir
@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`

```elixir
@spec max_cert_bytes() :: pos_integer()
```

Maximum accepted DER certificate size in bytes.

# `max_chain_length`

```elixir
@spec max_chain_length() :: pos_integer()
```

Maximum accepted X.509 certificate chain length.

# `max_trust_anchors`

```elixir
@spec max_trust_anchors() :: pos_integer()
```

Maximum accepted number of trust anchors in a verification call.

# `valid_trust_anchors?`

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

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

# `verify`

```elixir
@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`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
