Enum KeyId 

pub enum KeyId {
    Binary(Vec<u8>),
    String(String),
}

Key identifier that can be either a binary or string value.

The key identifier (kid) is used to indicate which key was used to secure the token. This allows the recipient to select the appropriate key for verification without having to try each key.

Examples

Creating a string key identifier:

use common_access_token::KeyId;

let string_kid = KeyId::string("my-key-2023");

Creating a binary key identifier:

use common_access_token::KeyId;

let binary_kid = KeyId::binary(vec![0x01, 0x02, 0x03, 0x04]);

Variants

Binary(Vec<u8>)

Binary key identifier (for binary key identifiers like UUIDs or hashes)

String(String)

String key identifier (for human-readable key identifiers)

Implementations

impl KeyId

pub fn binary<T: Into<Vec<u8>>>(data: T) -> Self

Create a new binary key identifier

Examples found in repository

examples/basic_usage.rs (line 73)

fn create_token_with_binary_kid(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();
    let binary_kid = vec![0x01, 0x02, 0x03, 0x04, 0x05];

    // Create a token with binary key ID
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::binary(binary_kid))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now),
        )
        .sign(key)
        .expect("Failed to sign token")
}

pub fn string<T: Into<String>>(data: T) -> Self

Create a new string key identifier

Examples found in repository

examples/basic_usage.rs (line 47)

fn create_token_with_string_kid(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a token with string key ID
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("string-key-example"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now)
                .with_cti(b"token-id-1234".to_vec()),
        )
        .custom_string(100, "custom-string-value")
        .custom_binary(101, b"custom-binary-value".to_vec())
        .custom_int(102, 12345)
        .sign(key)
        .expect("Failed to sign token")
}

/// Create a token with a binary key ID
fn create_token_with_binary_kid(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();
    let binary_kid = vec![0x01, 0x02, 0x03, 0x04, 0x05];

    // Create a token with binary key ID
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::binary(binary_kid))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now),
        )
        .sign(key)
        .expect("Failed to sign token")
}

/// Create a token with a nested map claim
fn create_token_with_nested_map(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a nested map for the token
    let mut nested_map = BTreeMap::new();
    nested_map.insert(1, CborValue::Text("nested-text-value".to_string()));
    nested_map.insert(2, CborValue::Integer(42));
    nested_map.insert(3, CborValue::Bytes(vec![1, 2, 3, 4, 5]));

    // Create a second level nested map
    let mut second_level_map = BTreeMap::new();
    second_level_map.insert(1, CborValue::Text("second-level-text".to_string()));
    second_level_map.insert(2, CborValue::Integer(99));

    // Add the second level map to the first level
    nested_map.insert(4, CborValue::Map(second_level_map));

    // Create a token with a nested map claim
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("nested-map-example"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now),
        )
        .custom_map(200, nested_map)
        .sign(key)
        .expect("Failed to sign token")
}

examples/cat_specific_claims.rs (line 68)

fn create_token_with_cat_claims(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a CATU claim (Common Access Token URI)
    let mut catu_components = BTreeMap::new();

    // Restrict to https scheme
    catu_components.insert(uri_components::SCHEME, catu::exact_match("https"));

    // Restrict to example.com host
    catu_components.insert(uri_components::HOST, catu::suffix_match(".example.com"));

    // Restrict to paths starting with /content
    catu_components.insert(uri_components::PATH, catu::prefix_match("/content"));

    // Restrict to .m3u8 files
    catu_components.insert(uri_components::EXTENSION, catu::exact_match(".m3u8"));

    // Create a CATM claim (Common Access Token Methods)
    let allowed_methods = vec!["GET", "HEAD"];

    // Create a CATR claim (Common Access Token Renewal)
    let renewal_params = catr::automatic_renewal(3600, Some((now + 3000) as i64));

    // Build the token with CAT-specific claims
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("example-key-id"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now)
                .with_cti(b"token-id-1234".to_vec()),
        )
        // Add CAT-specific claims
        .custom_cbor(cat_keys::CATU, catu::create(catu_components))
        .custom_cbor(cat_keys::CATR, catr::create(renewal_params))
        .custom_cbor(cat_keys::CATREPLAY, catreplay::prohibited())
        .custom_int(cat_keys::CATV, 1) // Version 1
        .custom_array(cat_keys::CATM, catm::create(allowed_methods))
        .sign(key)
        .expect("Failed to sign token")
}

examples/cat_validation.rs (line 72)

fn create_token_with_cat_claims(key: &[u8], now: i64) -> common_access_token::Token {
    println!("Creating token with CAT-specific claims...");

    // 1. Create a CATU claim (Common Access Token URI)
    let mut catu_components = BTreeMap::new();

    // Restrict to https scheme
    catu_components.insert(uri_components::SCHEME, catu::exact_match("https"));

    // Restrict to example.com host
    catu_components.insert(uri_components::HOST, catu::suffix_match(".example.com"));

    // Restrict to paths starting with /api
    catu_components.insert(uri_components::PATH, catu::prefix_match("/api"));

    // Restrict to .json extension
    catu_components.insert(uri_components::EXTENSION, catu::exact_match(".json"));

    println!("  Added CATU claim with URI restrictions");

    // 2. Create a CATM claim (Common Access Token Methods)
    let allowed_methods = vec!["GET", "HEAD", "OPTIONS"];
    println!("  Added CATM claim allowing methods: {:?}", allowed_methods);

    // 3. Create a CATR claim (Common Access Token Renewal)
    let renewal_params = catr::automatic_renewal(3600, Some(now + 3000));
    println!("  Added CATR claim with automatic renewal");

    // 4. Create a CATREPLAY claim (prohibit token replay)
    println!("  Added CATREPLAY claim prohibiting token replay");

    // Build the token with all CAT-specific claims
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("example-key-id"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now as u64 + 3600) // 1 hour from now
                .with_not_before(now as u64)
                .with_issued_at(now as u64)
                .with_cti(b"token-id-1234".to_vec()),
        )
        // Add CAT-specific claims
        .custom_cbor(cat_keys::CATU, catu::create(catu_components))
        .custom_cbor(cat_keys::CATR, catr::create(renewal_params))
        .custom_cbor(cat_keys::CATREPLAY, catreplay::prohibited())
        .custom_array(cat_keys::CATM, catm::create(allowed_methods))
        .sign(key)
        .expect("Failed to sign token")
}

examples/extended_cat_claims.rs (line 30)

fn main() {
    let key = b"my-secret-key-for-hmac-sha256";
    let now = current_timestamp();

    println!("=== Extended CAT Claims Example ===\n");

    // Example 1: Token with probability of rejection (CATPOR)
    println!("1. Creating token with CATPOR (25% rejection probability)");
    let token_with_catpor = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-1"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATPOR, catpor::create(25))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATPOR: 25% rejection probability\n");

    // Example 2: Token with network IP restrictions (CATNIP)
    println!("2. Creating token with CATNIP (IP restrictions)");
    let token_with_catnip = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-2"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_array(
            cat_keys::CATNIP,
            catnip::create(vec!["192.168.1.0/24", "10.0.0.0/8"]),
        )
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATNIP: 192.168.1.0/24, 10.0.0.0/8\n");

    // Example 3: Token with ALPN restrictions (CATALPN)
    println!("3. Creating token with CATALPN (HTTP/2 only)");
    let token_with_catalpn = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-3"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_array(cat_keys::CATALPN, catalpn::http2_only())
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATALPN: h2 only\n");

    // Example 4: Token with HTTP header requirements (CATH)
    println!("4. Creating token with CATH (custom headers)");
    let mut headers = BTreeMap::new();
    headers.insert("X-API-Key", "secret-api-key");
    headers.insert("X-Client-Version", "1.0");

    let token_with_cath = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-4"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATH, cath::create(headers))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATH: X-API-Key, X-Client-Version\n");

    // Example 5: Token with geographic restrictions (CATGEO*)
    println!("5. Creating token with geographic restrictions");
    let token_with_geo = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-5"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        // Country restriction
        .custom_array(cat_keys::CATGEOISO3166, catgeoiso3166::create(vec!["US"]))
        // Coordinate restriction (New York City with 5km radius)
        .custom_cbor(
            cat_keys::CATGEOCOORD,
            catgeocoord::with_radius(40.7128, -74.0060, 5000),
        )
        // Altitude restriction (0-1000 meters)
        .custom_cbor(cat_keys::CATGEOALT, catgeoalt::range(0, 1000))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATGEOISO3166: US");
    println!("   ✓ Token created with CATGEOCOORD: NYC (40.7128, -74.0060) ±5km");
    println!("   ✓ Token created with CATGEOALT: 0-1000m\n");

    // Example 6: Token with TLS public key pinning (CATTPK)
    println!("6. Creating token with CATTPK (TLS key pinning)");
    // In a real scenario, this would be the SHA-256 hash of a certificate's public key
    let public_key_hash = vec![
        0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd,
        0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab,
        0xcd, 0xef,
    ];

    let token_with_cattpk = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-6"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATTPK, cattpk::create(public_key_hash.clone()))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATTPK: public key hash (32 bytes)\n");

    // Example 7: Token with DPoP settings (CATDPOP)
    println!("7. Creating token with CATDPOP (DPoP required)");
    let token_with_catdpop = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-7"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATDPOP, catdpop::required())
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATDPOP: DPoP required\n");

    // Example 8: Token with conditional logic (CATIF/CATIFDATA)
    println!("8. Creating token with CATIF and CATIFDATA");
    let mut condition = BTreeMap::new();
    condition.insert(0, common_access_token::CborValue::Text("role".to_string()));
    condition.insert(
        1,
        common_access_token::CborValue::Text("equals".to_string()),
    );
    condition.insert(2, common_access_token::CborValue::Text("admin".to_string()));

    let mut if_data = BTreeMap::new();
    if_data.insert(0, common_access_token::CborValue::Text("role".to_string()));
    if_data.insert(1, common_access_token::CborValue::Text("admin".to_string()));

    let token_with_catif = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-8"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATIF, catif::create(condition))
        .custom_cbor(cat_keys::CATIFDATA, catifdata::create(if_data))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATIF: conditional logic");
    println!("   ✓ Token created with CATIFDATA: role=admin\n");

    // Example 9: Comprehensive token with multiple CAT claims
    println!("9. Creating comprehensive token with multiple CAT claims");
    let comprehensive_token = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("comprehensive-key"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("secure-service")
                .with_subject("user-12345")
                .with_audience("api.example.com")
                .with_expiration(now + 7200),
        )
        .custom_cbor(cat_keys::CATV, catv::with_version(1))
        .custom_cbor(cat_keys::CATPOR, catpor::create(10))
        .custom_array(cat_keys::CATNIP, catnip::single("203.0.113.0/24"))
        .custom_array(cat_keys::CATALPN, catalpn::create(vec!["h2", "http/1.1"]))
        .custom_array(cat_keys::CATGEOISO3166, catgeoiso3166::create(vec!["US"]))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Comprehensive token created with:");
    println!("     - CATV: version 1");
    println!("     - CATPOR: 10% rejection probability");
    println!("     - CATNIP: 203.0.113.0/24");
    println!("     - CATALPN: h2, http/1.1");
    println!("     - CATGEOISO3166: US");

    // Verify all tokens can be encoded
    println!("\n=== Verification ===");
    let tokens = vec![
        ("CATPOR", &token_with_catpor),
        ("CATNIP", &token_with_catnip),
        ("CATALPN", &token_with_catalpn),
        ("CATH", &token_with_cath),
        ("CATGEO*", &token_with_geo),
        ("CATTPK", &token_with_cattpk),
        ("CATDPOP", &token_with_catdpop),
        ("CATIF", &token_with_catif),
        ("Comprehensive", &comprehensive_token),
    ];

    for (name, token) in tokens {
        let token_bytes = token.to_bytes().expect("Failed to encode token");
        println!("✓ {} token encoded ({} bytes)", name, token_bytes.len());
    }

    println!("\n=== All Extended CAT Claims Examples Completed Successfully ===");
}

pub fn as_bytes(&self) -> &[u8]

Get the key identifier as bytes

Trait Implementations

impl Clone for KeyId

fn clone(&self) -> KeyId

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for KeyId

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

Formats the value using the given formatter.

impl PartialEq for KeyId

fn eq(&self, other: &KeyId) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for KeyId

impl StructuralPartialEq for KeyId