Module jose 

JSON Object Signing and Encryption: keys, algorithms, signature verification and the compact JWS serialization.

This is the crate’s signature layer. Everything above it (DID documents, credentials) carries a Jwk and a JwsAlgorithm and hands signing input to a JwsVerifier or a Signer:

• Jwk is a JSON Web Key (RFC 7517), kept as the JSON it arrived as, with RFC 7638 thumbprints, raw public key accessors for Ed25519, X25519, P-256 and secp256k1, and conversion to and from a Multikey string (Jwk::from_multikey, Jwk::to_multikey).
• JwsAlgorithm names the asymmetric algorithms this crate speaks and converts to and from jsonwebtoken::Algorithm.
• JwsVerifier verifies a signature over a signing input; DefaultVerifier does so with RustCrypto. ECDSA signatures are the raw r || s form JWS uses, never DER. An ES256 signature verifies with s and n - s alike, so identify a token by its claims, not its bytes (see DefaultVerifier).
• CompactJws decodes a compact serialization without verifying it; encode_compact produces one with any Signer, which is async because private keys live in key stores and HSMs.
• ecdsa_signature_from_der and normalize_ecdsa_signature turn what an HSM or a cloud KMS returns for an ECDSA key into the JWS form: raw r || s, with a secp256k1 s in the lower half of the group order.
• JwtClaims is a JWT claims set (RFC 7519): the registered claims as fields, aud as a OneOrMany, times as NumericDate seconds, every other claim kept in order. CompactJws::claims reads a payload as one, unverified; JwtValidator of resolver validates one, its signer’s key resolved by a KeyResolver.

JWE is out of scope.

Cargo features

• secp256k1 (default): ES256K and secp256k1 keys, via k256.
• rsa: RS256 and PS256, via rsa, with keys of at least 2048 bits (RFC 7518 §3.3, §3.5).

Structs

CompactJws

A decoded compact JWS: BASE64URL(header) || '.' || BASE64URL(payload) || '.' || BASE64URL(signature).

DefaultVerifier

A JwsVerifier over RustCrypto: ed25519-dalek for EdDSA, p256 for ES256, k256 for ES256K (feature secp256k1) and rsa for RS256 and PS256 (feature rsa).

Jwk

A JSON Web Key (RFC 7517).

JwsHeader

The JOSE header of a JWS (RFC 7515 §4).

JwtClaims

A JWT claims set: the registered claims of RFC 7519 §4.1 as fields, every other claim (vc, vp, nonce, cnf, …) in additional.

SignError

An error from a Signer.

UnknownAlgorithm

An algorithm name that is not a JwsAlgorithm.

Enums

EcdsaSignatureError

Why an ECDSA signature cannot be put in its JWS form; see ecdsa_signature_from_der and normalize_ecdsa_signature.

JwkError

Why a Jwk cannot be built, or cannot be used the way it was asked to.

JwsAlgorithm

A JWS digital signature algorithm (RFC 7518 §3.1, RFC 8037 §3.1, RFC 8812 §3.2).

JwsError

Why a compact JWS could not be decoded or produced.

KeyCodec

The multicodec codes of the public key types this crate reads from and writes to a Multikey.

KeyType

The kind of key behind a Jwk, as a key store or HSM names it.

OneOrMany

A value that is either one T or a list of them, serialized without the list when single.

VerificationError

Why a JWS signature did not verify.

Traits

JwsVerifier

Verifies JWS signatures.

Signer

Produces JWS signatures.

Functions

ecdsa_signature_from_der

A DER ECDSA-Sig-Value (RFC 3279 §2.2.3) as the JWS signature for alg (RFC 7518 §3.4): r || s, each left-padded to the curve’s size, with s normalized to the lower half of the group order for ES256K.

encode_compact

Encodes payload under header as a compact JWS signed by signer.

normalize_ecdsa_signature

A raw r || s signature for alg, with s normalized to the lower half of the group order for ES256K. ES256 and ES384 signatures are returned unchanged once their length is checked: DefaultVerifier accepts either s for ES256.