Struct jsonwebtokens::Algorithm

pub struct Algorithm { /* private fields */ }

A cryptographic function for signing or verifying a token signature

An Algorithm encapsulates one function for signing or verifying tokens. A key or secret only needs to be decoded once so it can be reused cheaply while signing or verifying tokens. The decoded key or secret and AlgorithmID are immutable after construction to avoid the chance of being coerced into using the wrong algorithm to sign or verify a token at runtime.

Optionally a kid Key ID can be assigned to an Algorithm to add a strict check that a token’s header must include the same kid value. This is useful when using an Algorithm to represent a single key within a JWKS key set, for example.

Implementations

impl Algorithm

pub fn id(&self) -> AlgorithmID

Returns the AlgorithmID that was used to construct the Algorithm

Examples found in repository

src/raw.rs (line 212)

pub fn verify_signature_only(
    header: &serde_json::value::Value,
    message: impl AsRef<str>,
    signature: impl AsRef<str>,
    algorithm: &Algorithm,
) -> Result<(), Error> {
    match header.get("alg") {
        Some(serde_json::value::Value::String(alg)) => {
            let alg = AlgorithmID::from_str(alg)?;

            if alg != algorithm.id() {
                return Err(Error::AlgorithmMismatch());
            }

            // An Algorithm may relate to a specific 'kid' which we verify...
            let kid = match header.get("kid") {
                Some(serde_json::value::Value::String(k)) => Some(k.as_ref()),
                Some(_) => {
                    return Err(Error::MalformedToken(ErrorDetails::new(
                        "Non-string 'kid' found",
                    )))
                }
                None => None,
            };

            algorithm.verify(kid, message, signature)?;
        }
        _ => return Err(Error::AlgorithmMismatch()),
    }

    Ok(())
}

pub fn name(&self) -> &'static str

Returns the algorithm name as standardized in RFC 7518

Examples found in repository

src/crypto/algorithm.rs (line 125)

    fn from(alg: Algorithm) -> Self {
        alg.name()
    }

pub fn set_kid(&mut self, kid: impl Into<String>)

Optionally if a kid is associated with an algorithm there will be an extra verification that a token’s kid matches the one associated with the Algorithm

pub fn kid(&self) -> Option<&str>

Returns a reference to any associated kid set via set_kid()

pub fn new_unsecured() -> Result<Self, Error>

Constructs a NOP algorithm for use with unsecured (unsigned) tokens

pub fn new_hmac(
    id: AlgorithmID,
    secret: impl Into<Vec<u8>>
) -> Result<Self, Error>

Constructs a symmetric HMAC algorithm based on a given secret

This algorithm may be used for signing and/or verifying signatures

pub fn new_hmac_b64(
    id: AlgorithmID,
    secret: impl AsRef<str>
) -> Result<Self, Error>

Constructs a symmetric HMAC algorithm based on a given base64 secret

This is a convenience api in case the secret you’re using is base64 encoded

This algorithm may be used for signing and/or verifying signatures

pub fn new_ecdsa_pem_signer(id: AlgorithmID, key: &[u8]) -> Result<Self, Error>

Constructs an ECDSA algorithm based on a PEM format private key

This algorithm may only be used for signing tokens

pub fn new_ecdsa_pem_verifier(id: AlgorithmID, key: &[u8]) -> Result<Self, Error>

Constructs an ECDSA algorithm based on a PEM format public key

This algorithm may only be used for verifying tokens

pub fn new_rsa_pem_signer(id: AlgorithmID, key: &[u8]) -> Result<Self, Error>

Constructs an RSA algorithm based on a PEM format private key

This algorithm may only be used for signing tokens

pub fn new_rsa_pem_verifier(id: AlgorithmID, key: &[u8]) -> Result<Self, Error>

Constructs an RSA algorithm based on a PEM format public key

This algorithm may only be used for verifying tokens

pub fn new_rsa_n_e_b64_verifier(
    id: AlgorithmID,
    n_b64: &str,
    e_b64: &str
) -> Result<Self, Error>

Constructs an RSA algorithm based on modulus (n) and exponent (e) components

In some situations (such as JWKS key sets), a public RSA key may be described in terms of (base64 encoded) modulus and exponent values.

This algorithm may only be used for verifying tokens

pub fn verify(
    &self,
    kid: Option<&str>,
    message: impl AsRef<str>,
    signature: impl AsRef<str>
) -> Result<(), Error>

Lower-level api that can be used to verify a signature for a given message

Examples found in repository

src/raw.rs (line 227)

pub fn verify_signature_only(
    header: &serde_json::value::Value,
    message: impl AsRef<str>,
    signature: impl AsRef<str>,
    algorithm: &Algorithm,
) -> Result<(), Error> {
    match header.get("alg") {
        Some(serde_json::value::Value::String(alg)) => {
            let alg = AlgorithmID::from_str(alg)?;

            if alg != algorithm.id() {
                return Err(Error::AlgorithmMismatch());
            }

            // An Algorithm may relate to a specific 'kid' which we verify...
            let kid = match header.get("kid") {
                Some(serde_json::value::Value::String(k)) => Some(k.as_ref()),
                Some(_) => {
                    return Err(Error::MalformedToken(ErrorDetails::new(
                        "Non-string 'kid' found",
                    )))
                }
                None => None,
            };

            algorithm.verify(kid, message, signature)?;
        }
        _ => return Err(Error::AlgorithmMismatch()),
    }

    Ok(())
}

pub fn sign(&self, message: &str) -> Result<String, Error>

Lower-level api that can be used to calculate a signature for a message

Examples found in repository

src/encode.rs (line 47)

pub fn encode<H: Serialize, C: Serialize>(
    header: &H,
    claims: &C,
    algorithm: &Algorithm,
) -> Result<String, Error> {
    let encoded_header = b64_encode_part(&header)?;
    let encoded_claims = b64_encode_part(&claims)?;
    let message = [encoded_header.as_ref(), encoded_claims.as_ref()].join(".");
    let signature = algorithm.sign(&message)?;
    Ok([message, signature].join("."))
}

Trait Implementations

impl Debug for Algorithm

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<Algorithm> for &'static str

fn from(alg: Algorithm) -> Self

Converts to this type from the input type.