Attesto.Key (Attesto v2.28.0)

Copy Markdown View Source

Pure helpers for working with signing material as PEM strings.

An RSA private key already contains its public half, so there is never a separately stored public PEM to drift out of sync. public_pem/1 derives the public key from a private PEM, giving exactly one source of truth: the verification key always matches the signing key. This closes a real failure mode where a tracked public PEM and a regenerated private key silently mismatch and every verification fails.

kid/1 is the RFC 7638 JWK thumbprint of a key's public half. It is stable for a given key and changes iff the key changes, so rotating to a new key yields a distinct kid automatically - no separate identifier to assign or track.

Summary

Functions

Default minimum accepted RSA modulus bit length.

Import one PEM key without matching exception messages.

Parse a PEM (private or public) into a JOSE.JWK.

The RFC 7638 SHA-256 JWK thumbprint (kid) of the public half of the key in pem. Accepts a private or public PEM; both yield the same thumbprint because it is computed over the public members only.

Return the public JWK field map for a single JOSE.JWK struct or single JWK map.

Derive the public key, in conventional SPKI (-----BEGIN PUBLIC KEY-----) PEM form, from a private RSA key PEM.

Parse a private PEM, JWK map, or JOSE.JWK for signing.

Whether jwk_map is a single JWK rather than a JWK Set.

Check whether key selection requires a protected-header kid.

Validate and parse an untrusted JWK for signature verification.

Types

verification_jwk_error()

@type verification_jwk_error() ::
  :private_material
  | :invalid_use
  | :alg_mismatch
  | :incompatible_key
  | :weak_key
  | :oversized_key
  | :malformed_jwk

Functions

default_minimum_rsa_bits()

@spec default_minimum_rsa_bits() :: pos_integer()

Default minimum accepted RSA modulus bit length.

import_pem(pem)

@spec import_pem(term()) ::
  {:ok, JOSE.JWK.t()} | {:error, :malformed_key | :unsupported_key}

Import one PEM key without matching exception messages.

Returns {:ok, jwk}, {:error, :malformed_key} for empty, malformed, multi-entry or non-binary input, or {:error, :unsupported_key} for a parseable key whose type or curve is unsupported. Neither error includes key material. Accepts public and private keys, as jwk/1 does.

jwk(pem)

@spec jwk(String.t()) :: JOSE.JWK.t()

Parse a PEM (private or public) into a JOSE.JWK.

Raises ArgumentError if pem does not contain exactly one parseable key. JOSE.JWK.from_pem/1 returns [] for input with no key entry and a list for a multi-key PEM; left unguarded, thumbprint/1 of those returns [] rather than a string, which would silently poison kid/1 and verification-key selection. Failing loudly here surfaces a malformed keystore PEM as a configuration error instead of a request-time mystery.

Also raises if the key type/curve is not supported by Attesto's asymmetric signing algorithms. Algorithms are derived from trusted key metadata, not from a presented token header.

kid(pem)

@spec kid(String.t()) :: String.t()

The RFC 7638 SHA-256 JWK thumbprint (kid) of the public half of the key in pem. Accepts a private or public PEM; both yield the same thumbprint because it is computed over the public members only.

public_map(jwk)

@spec public_map(JOSE.JWK.t() | map()) :: map()

Return the public JWK field map for a single JOSE.JWK struct or single JWK map.

When deriving from private material, omit its key_ops: private signing permissions do not describe the public half's verification permissions. Public-only inputs retain their key_ops, so this is not a way to relax a verification key's declared usage. Raises ArgumentError for JWK Set inputs or non-JWK values.

public_pem(pem)

@spec public_pem(String.t()) :: String.t()

Derive the public key, in conventional SPKI (-----BEGIN PUBLIC KEY-----) PEM form, from a private RSA key PEM.

Accepts the PKCS#1 (RSA PRIVATE KEY) and PKCS#8 (PRIVATE KEY) forms. Raises ArgumentError - signing material is operator-provided, so a misconfiguration is a deploy-time failure that should be loud rather than silently verifying against garbage - if pem contains no key entry, contains more than one, contains a non-RSA key, or is public-only. EC/OKP deployments should publish JWKS instead.

signing_jwk(jwk)

@spec signing_jwk(String.t() | map() | JOSE.JWK.t()) :: JOSE.JWK.t()

Parse a private PEM, JWK map, or JOSE.JWK for signing.

A JWK's use must be absent or "sig"; key_ops must be absent or a list of strings containing "sign". Public material and JWK Sets are refused with ArgumentError. public_map/1 derives verification material without carrying the private key's operations.

Unlike jwk/1, this rejects public-only PEMs: they are valid verification material, but cannot sign tokens.

single_jwk_map?(jwk_map)

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

Whether jwk_map is a single JWK rather than a JWK Set.

A JWK has a string kty member (RFC 7517 §4.1) and no keys member. JOSE parses a map that has both as the outer key with the inner keys attached, and a map that has only keys as a set, so a caller that expects one key must refuse both before parsing.

validate_kid(keys, kid, opts \\ [])

@spec validate_kid(list(), term(), keyword()) :: :ok | {:error, :missing_kid}

Check whether key selection requires a protected-header kid.

:require_kid is false by default, true to require it for every token, or :multiple to require it when the original key set contains more than one entry. Count entries before filtering by algorithm, usage, or strength; even duplicate entries count. Pass the complete list of keys before candidate filtering. A required identifier must be a non-empty string.

verification_jwk(jwk_map, opts)

@spec verification_jwk(
  map(),
  keyword()
) :: {:ok, JOSE.JWK.t()} | {:error, verification_jwk_error()}

Validate and parse an untrusted JWK for signature verification.

The raw map is checked before parsing so private members and contradictory RFC 7517 metadata cannot be normalized away by the JOSE library. By default, private material is rejected and RSA verification keys must be at least 2048 bits.

:alg is required and is compared with a JWK's optional alg member. :require_public? defaults to true, and :minimum_rsa_bits defaults to 2048.

The requested algorithm is checked against the parsed key type and curve before the key reaches a signature verifier, including explicit Edwards and ES256K identifiers.