Struct Header

pub struct Header {
    pub protected: HeaderMap,
    pub unprotected: HeaderMap,
}

Header for a Common Access Token.

The header contains metadata about the token, such as the algorithm used for signing and the key identifier. It is divided into two parts:

• Protected Header: Contains parameters that are integrity-protected and included in the signature input. This typically includes the algorithm.

• Unprotected Header: Contains parameters that are not integrity-protected and can be modified without invalidating the signature. This might include non-critical metadata.

Examples

Creating a header with algorithm and key identifier:

use common_access_token::{Algorithm, Header, KeyId};

let header = Header::new()
    .with_algorithm(Algorithm::HmacSha256)
    .with_protected_key_id(KeyId::string("my-key-2023"));

assert_eq!(header.algorithm(), Some(Algorithm::HmacSha256));

Fields

protected: HeaderMap

Protected header parameters (must be integrity protected)

unprotected: HeaderMap

Unprotected header parameters

Implementations

impl Header

pub fn new() -> Self

Creates a new empty header with no parameters.

Example

use common_access_token::Header;

let header = Header::new();
assert!(header.protected.is_empty());
assert!(header.unprotected.is_empty());

pub fn with_algorithm(self, alg: Algorithm) -> Self

Sets the algorithm in the protected header.

The algorithm is always placed in the protected header because it is a critical parameter that must be integrity-protected.

Example

use common_access_token::{Algorithm, Header};

let header = Header::new().with_algorithm(Algorithm::HmacSha256);
assert_eq!(header.algorithm(), Some(Algorithm::HmacSha256));

pub fn with_protected_key_id(self, kid: KeyId) -> Self

Sets the key identifier in the protected header.

The key identifier in the protected header is integrity-protected and cannot be modified without invalidating the signature.

Example

use common_access_token::{Header, KeyId};

let header = Header::new().with_protected_key_id(KeyId::string("my-key-2023"));
if let Some(KeyId::String(kid)) = header.key_id() {
    assert_eq!(kid, "my-key-2023");
}

pub fn with_unprotected_key_id(self, kid: KeyId) -> Self

Sets the key identifier in the unprotected header.

The key identifier in the unprotected header is not integrity-protected and can be modified without invalidating the signature.

Example

use common_access_token::{Header, KeyId};

let header = Header::new().with_unprotected_key_id(KeyId::string("my-key-2023"));
if let Some(KeyId::String(kid)) = header.key_id() {
    assert_eq!(kid, "my-key-2023");
}

pub fn algorithm(&self) -> Option<Algorithm>

Gets the algorithm from the protected header.

Returns None if the algorithm is not present or is not a valid algorithm.

Example

use common_access_token::{Algorithm, Header};

let header = Header::new().with_algorithm(Algorithm::HmacSha256);
assert_eq!(header.algorithm(), Some(Algorithm::HmacSha256));

let empty_header = Header::new();
assert_eq!(empty_header.algorithm(), None);

pub fn key_id(&self) -> Option<KeyId>

Gets the key identifier from the protected or unprotected header.

This method first checks the protected header, and if the key identifier is not found there, it checks the unprotected header.

Returns None if the key identifier is not present in either header.

Example

use common_access_token::{Header, KeyId};

let header = Header::new().with_protected_key_id(KeyId::string("my-key-2023"));
if let Some(KeyId::String(kid)) = header.key_id() {
    assert_eq!(kid, "my-key-2023");
}

let empty_header = Header::new();
assert_eq!(empty_header.key_id(), None);

Examples found in repository

examples/basic_usage.rs (line 159)

fn verify_token(token_bytes: &[u8], key: &[u8], expected_token_type: &str) {
    // Decode the token
    let token = match common_access_token::Token::from_bytes(token_bytes) {
        Ok(token) => token,
        Err(err) => {
            println!("Failed to decode {} token: {}", expected_token_type, err);
            return;
        }
    };

    // Verify the signature
    if let Err(err) = token.verify(key) {
        println!(
            "Failed to verify {} token signature: {}",
            expected_token_type, err
        );
        return;
    }

    // Verify the claims
    let options = VerificationOptions::new()
        .verify_exp(true)
        .verify_nbf(true)
        .expected_issuer("example-issuer")
        .expected_audience("example-audience");

    if let Err(err) = token.verify_claims(&options) {
        println!(
            "Failed to verify {} token claims: {}",
            expected_token_type, err
        );
        return;
    }

    // Get the key ID
    let kid = token.header.key_id().expect("No key ID in token");
    let kid_str = match &kid {
        KeyId::Binary(data) => format!("Binary key ID: {:?}", data),
        KeyId::String(data) => format!("String key ID: {}", data),
    };

    println!(
        "Successfully verified {} token ({})",
        expected_token_type, kid_str
    );

    // Print some claims
    if let Some(iss) = &token.claims.registered.iss {
        println!("  Issuer: {}", iss);
    }
    if let Some(sub) = &token.claims.registered.sub {
        println!("  Subject: {}", sub);
    }
    if let Some(exp) = token.claims.registered.exp {
        println!(
            "  Expires at: {} (in {} seconds)",
            exp,
            exp - current_timestamp()
        );
    }
}

Trait Implementations

impl Clone for Header

fn clone(&self) -> Header

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Header

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

Formats the value using the given formatter.

impl Default for Header

fn default() -> Header

Returns the “default value” for a type.