Attesto.SdJwtVc (Attesto v2.28.0)

Copy Markdown View Source

SD-JWT-based Verifiable Digital Credentials (SD-JWT VC), draft-ietf-oauth-sd-jwt-vc-26.

The IETF profile of Attesto.SdJwt used by the EUDI wallet stack (and its High-Assurance Interoperability Profile, HAIP): an SD-JWT whose Issuer-signed JWT carries a credential type (vct), an issuer (iss), an optional holder key binding (cnf), an optional Token Status List reference (status), and the usual temporal claims, typed dc+sd-jwt in the JOSE typ header (legacy vc+sd-jwt is neither emitted nor accepted).

This module adds the VC-specific claim rules on top of the base SD-JWT mechanism; the selective-disclosure machinery, recursive verification, and Key Binding JWT handling all come from Attesto.SdJwt.

  • issue/2 — assemble and sign an SD-JWT VC: sets iss/vct/iat (and optional exp/nbf/cnf/status/sub), makes the chosen credential claims selectively disclosable, and stamps JOSE typ ("dc+sd-jwt").
  • verify/3 — verify the issuer signature (typed dc+sd-jwt / application/dc+sd-jwt), reconstruct the disclosed claims, and enforce the VC claim rules: iss and vct non-empty by default, exp (if present) not passed, nbf (if present) reached. Holder binding is a separate step - pass the returned cnf key to Attesto.SdJwt.verify_key_binding/3 with the presentation's nonce/audience. Explicit certificate identity mode permits an omitted iss after the caller establishes certificate trust. Alternatively, :trusted_certificates opts into core path validation and SAN binding to a required iss.

Conn-free and fail-closed, like the rest of attesto core. 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

Functions

Issue an SD-JWT VC.

Verify an SD-JWT VC presentation and reconstruct the disclosed claims.

Types

verified()

@type verified() :: %{
  claims: map(),
  vct: String.t(),
  iss: String.t() | nil,
  cnf: map() | nil,
  key_binding_jwt: String.t() | nil,
  issuer_jwt: String.t(),
  disclosures: [String.t()]
}

verify_error()

@type verify_error() ::
  Attesto.SdJwt.verify_error()
  | :missing_iss
  | :invalid_issuer_identity
  | :disclosed_registered_claim
  | :missing_vct
  | :expired
  | :not_yet_valid
  | :invalid_cnf
  | {:credential_status, non_neg_integer()}
  | :credential_suspended
  | :credential_revoked
  | :invalid_status_reference
  | :invalid_status_list
  | :invalid_status_list_signature
  | :invalid_status_list_token
  | :status_list_uri_mismatch
  | :status_index_out_of_range
  | Attesto.X509.verify_error()
  | :certificate_issuer_mismatch
  | term()

Functions

issue(required, opts \\ [])

@spec issue(keyword(), keyword()) :: String.t()

Issue an SD-JWT VC.

Required options:

  • :iss - the issuer identifier (its .well-known/jwt-vc-issuer or DID).
  • :vct - the verifiable credential type (a collision-resistant string/URI).
  • :pem - the issuer signing key (PEM).

Optional:

  • :claims - the credential subject claims (a map). Defaults to %{}.
  • :disclosable - which of those claim names to make selectively disclosable. Defaults to all of :claims. Registered claims (iss/vct/cnf/status/iat/exp/nbf/sub) are never made disclosable even if listed here - they always remain visible, so a holder cannot strip holder-binding (cnf) or a status reference.
  • :cnf - the holder key-binding confirmation (RFC 7800), e.g. %{"jwk" => holder_public_jwk}. Included for later Key Binding.
  • :status - a Token Status List reference map, typically built with Attesto.StatusList.reference/2. Always visible when present.
  • :iat / :exp / :nbf / :sub - standard claims (unix seconds / string).
  • :now - clock reference for a defaulted :iat.
  • :kid - JOSE kid header. :sd_alg - SD hashing algorithm.
  • :typ - the SD-JWT VC media type stamped in the JOSE typ header; must be "dc+sd-jwt" (draft-ietf-oauth-sd-jwt-vc-26). Defaults to "dc+sd-jwt".
  • :x5c - the issuer X.509 certificate chain (RFC 7515 §4.1.6): a non-empty list of base64 DER certificate strings, stamped in the JOSE x5c header so a verifier can bind the credential to a trusted issuer certificate (HAIP). Omitted when nil.

Returns the SD-JWT VC Issuance string (no Key Binding JWT).

verify(combined, jwks, opts \\ [])

@spec verify(String.t(), map() | [map()] | list() | nil, keyword()) ::
  {:ok, verified()} | {:error, verify_error()}

Verify an SD-JWT VC presentation and reconstruct the disclosed claims.

jwks is the issuer's JWK Set (or nil with :trusted_certificates). Options are passed through to Attesto.SdJwt.verify/3 (e.g. :accepted_algs), plus:

  • :now / :max_age_seconds - clock reference for the temporal checks.
  • :issuer_identity - defaults to :claim, requiring a nonempty iss. Set :certificate only after validating the issuer's certificate chain and supplying its verified leaf public key as jwks. This mode permits an omitted iss when the signed header contains x5c, as in the SD-JWT VC profile referenced by HAIP. A present malformed iss still fails. Without :trusted_certificates, the caller establishes certificate trust; an x5c header alone is never a trust decision.
  • :trusted_certificates - opt into X.509 key resolution with a nonempty list of DER trust anchors. The protected x5c chain is validated with Attesto.X509.verify/2; its leaf public key replaces jwks for signature verification. A required, signed iss must then pass Attesto.X509.matches_issuer?/2, including URI SAN precedence. This is the stricter binding policy documented there, not a requirement of all SD-JWT VC revisions. Empty or invalid anchors fail without falling back to jwks. This option also requires iss in :certificate identity mode.
  • :haip - with :trusted_certificates, defaults to true: refuse a self-signed leaf or an embedded configured trust anchor (HAIP §6.1.1). Set false for generic X.509 chain handling. The certificate purpose is always :generic for SD-JWT VC, regardless of any :purpose option.
  • :certificate_trust - with :trusted_certificates, an optional additional chain policy callback as in Attesto.X509.verify/2. It cannot bypass path validation, signature verification, or issuer binding. :now affects credential claims only; OTP uses system time for certificate validity.

Returns {:ok, %{claims:, vct:, iss:, cnf:, key_binding_jwt:, ...}}. Holder binding is NOT checked here - if cnf is present and the presentation carries a Key Binding JWT, pass both to Attesto.SdJwt.verify_key_binding/3 with the verifier's expected nonce/audience.

A presentation is rejected if a supplied disclosure reconstructs one of the registered claims that must have remained visible. A digest does not reveal the name of an omitted disclosure, so a nonconforming issuer-hidden optional claim that the holder omits is indistinguishable from an absent optional claim. Verifiers must therefore trust the issuer to follow the profile's registered-claim visibility rule.