Crate ssi_jws

Expand description

JSON Web Signature (JWS) implementation following RFC 7515 and RFC 7797 (Unencoded Payload Option).

§Usage

The entry point to store and verify JWS is the &Jws type, borrowing the JWS, just like a &str borrows a text string. The JwsBuf type is the owned version of this type, owning the JWS, just like a String owns a text string.

§Decoding & Verification

Use JwsSlice::verify to decode a JWS.

use serde_json::json;
use ssi_jwk::JWK;
use ssi_jws::Jws;

let jws = Jws::new(b"eyJhbGciOiJFUzI1NiJ9.cGF5bG9hZA.LW6XkHmgfNnb2CA-2qdeMVGpekAoxRNsAHoeLpnton3QMaQ3dMj-5G9SlP8dHj7cHf2HtRPdy6-9LbxYKvumKw").unwrap();

let jwk: JWK = json!({
    "kty": "EC",
    "use": "sig",
    "crv": "P-256",
    "x": "dxdB360AJqJFYhdctoKZD_a_P6vLGAxtEVaCLnyraXQ",
    "y": "iH6o0l5AECsfRuEw2Eghbrp-6Fob3j98-1Cbe1YOmwM",
    "alg": "ES256"
}).try_into().unwrap();

assert!(jws.verify(&jwk).await.unwrap().is_ok());

Internally JwsSlice::verify uses JwsSlice::decode to decode the JWS, then DecodedJws::verify to validate the signature.

let decoded_jws = jws.to_decoded().unwrap();
let verifiable_jws = decoded_jws.into_verifiable().await.unwrap();
assert_eq!(verifiable_jws.verify(&jwk).await.unwrap().is_ok());

You can use this method to decode the payload before the verification (using DecodedJws::try_map for instance) so it can be verified along the signature.

§Signature

Use the JwsPayload::sign method to sign a payload into a compact JWS.

use serde_json::json;
use ssi_jwk::JWK;
use ssi_jws::JwsPayload;

let jwk: JWK = json!({
    "kty": "EC",
    "d": "3KSLs0_obYeQXfEI9I3BBH5y7aOm028bEx3rW6i5UN4",
    "use": "sig",
    "crv": "P-256",
    "x": "dxdB360AJqJFYhdctoKZD_a_P6vLGAxtEVaCLnyraXQ",
    "y": "iH6o0l5AECsfRuEw2Eghbrp-6Fob3j98-1Cbe1YOmwM",
    "alg": "ES256"
}).try_into().unwrap();

let jwt = "payload".sign(&jwk).await.unwrap();
assert_eq!(jwt, "eyJhbGciOiJFUzI1NiJ9.cGF5bG9hZA.LW6XkHmgfNnb2CA-2qdeMVGpekAoxRNsAHoeLpnton3QMaQ3dMj-5G9SlP8dHj7cHf2HtRPdy6-9LbxYKvumKw")

§URL safety and JWS types

RFC 7515 originally defines JWS as URL safe strings due to the payload being base64 URL-safe encoded. However, RFC 7797 introduces a b64 header option that makes this encoding optional. If set to false, the JWS may not be URL-safe. In fact it may not be UTF-8 encoded at all.

To deal with these different encoding expectations this library provides three families of types for representing JWS:

Jws and JwsBuf: This is the most common type family that follows RFC 7515 to the letter, expecting an URL-safe JWS. It is still possible to use the b64 header to embed unencoded payloads but those payloads must use URL-safe base64 bytes/characters.
JwsStr and JwsString: This family relaxes the URL-safe payload constraint. Unencoded payloads may use bytes outside of the URL-safe base64 alphabet, but they must be valid UTF-8 strings. This guarantees that the overall JWS is a valid UTF-8 string, even if it is not URL-safe.
JwsSlice and JwsVec: This family does not imposes any constraint on unencoded payloads. There is no guaranty that the overall JWS will be an UTF-8 string.

Re-exports§

pub use error::Error;

Modules§

error

Macros§

jws: Creates a new static URL-safe JWS reference from a string literal.

Structs§

DecodedJws: Decoded JWS.
DecodedSigningBytes: JWS decoded signing bytes.
Header: JOSE Header.
InvalidJws
JwkWithAlgorithm
Jws: Borrowed URL-safe JWS.
JwsBuf: Owned URL-safe JWS.
JwsParts: Decoded JWS parts.
JwsSignature
JwsSignerInfo
JwsSlice: Borrowed JWS without any encoding guaranties.
JwsStr: Borrowed UTF-8 encoded JWS.
JwsString: Owned UTF-8 encoded JWS.
JwsVec: Owned JWS without any encoding guaranties.

Enums§

Base64DecodeError: Errors that can occur while decoding.
DecodeError
InvalidHeader

Traits§

JwsPayload: JWS payload type.
JwsSigner: JWS Signer.
ValidateJwsHeader

Functions§

complete_sign_unencoded_payload
decode_jws_parts: Decode JWS parts (JOSE header, payload, and signature) into useful values. The payload argument is bytes since it may be unencoded if the b64:false header parameter is used; otherwise it must be a base64url-encoded string. Header and signature are always expected to be base64url-encoded. “crit” (critical) header parameters are checked and disallowed if unrecognized/unsupported.
decode_unverified
decode_verify
detached_recover: Recover a JWK from a JWS and payload, if the algorithm supports that (such as ES256K-R).
detached_recover_legacy_keccak_es256kr
detached_sign_unencoded_payload
detached_verify: Verify a JWS with detached payload. Returns the JWS header on success.
encode_sign
encode_sign_custom_header
encode_unsigned
prepare_detached_unencoded_payload
recover: Recover a key from a signature and message, if the algorithm supports this. (e.g. ES256K-R)
sign_bytes
sign_bytes_b64
split_detached_jws
split_jws
verify_bytes
verify_bytes_warnable

Type Aliases§

VerificationWarnings

Crate ssi_jwsCopy item path