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.
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
Functions
@spec default_minimum_rsa_bits() :: pos_integer()
Default minimum accepted RSA modulus bit length.
@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.
@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.
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.
@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.
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.
@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.
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.
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.
@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.