Crate common_access_token

Common Access Token (CAT) for Rust

A Rust implementation of the Common Access Token (CAT) specification with HMAC signatures.

Overview

Common Access Token (CAT) is a token format designed for authorization and authentication in distributed systems, particularly for media and content delivery applications. It is based on the CBOR Web Token (CWT) format defined in RFC 8392 and uses COSE (CBOR Object Signing and Encryption) for cryptographic operations.

CAT tokens are compact, secure, and designed to be efficiently processed in resource-constrained environments. They can be used for various purposes such as:

• Authentication and authorization for content access
• Secure communication between services
• Session management
• Delegation of permissions

Features

This library provides:

• Generation of CAT tokens with HMAC signatures (HS256)
• Validation of CAT tokens
• Support for standard CWT claims (issuer, subject, audience, expiration, etc.)
• Support for CAT-specific claims (version, renewal, usage, data, authorization)
• Interoperability with other CAT implementations like node-cat

Architecture

The library is organized into several modules:

• cat: Core functionality for token generation and validation
• claims: Implementation of CWT and CAT-specific claims
• cose: CBOR Object Signing and Encryption implementation
• error: Error types and handling
• util: Utility functions for encoding, decoding, and time operations

Usage Examples

Token Generation

use common_access_token::{Cat, CatGenerateOptions, CatOptions, CatValidationType, Claims};
use std::collections::HashMap;

// Create a key for token signing
let key = hex::decode("403697de87af64611c1d32a05dab0fe1fcb715a86ab435f1ec99192d79569388").unwrap();
let mut keys = HashMap::new();
keys.insert("Symmetric256".to_string(), key);

// Create CAT options
let cat_options = CatOptions {
    keys,
    expect_cwt_tag: true,
};

// Create a CAT instance
let cat = Cat::new(cat_options);

// Create claims
let mut claims = Claims::new();
claims.set_issuer("example");
claims.set_subject("user123");
claims.set_audience("service");
claims.set_expiration(std::time::SystemTime::now()
    .duration_since(std::time::UNIX_EPOCH).unwrap()
    .as_secs() as i64 + 3600); // 1 hour from now

// Generate token
let token = cat.generate(claims, &CatGenerateOptions {
    validation_type: CatValidationType::Mac,
    alg: "HS256".to_string(),
    kid: "Symmetric256".to_string(),
    generate_cwt_id: true,
}).unwrap();

Token Validation

use common_access_token::{Cat, CatGenerateOptions, CatOptions, CatValidationOptions, CatValidationType, Claims};
use std::collections::HashMap;

// First generate a token to validate
let key = hex::decode("403697de87af64611c1d32a05dab0fe1fcb715a86ab435f1ec99192d79569388").unwrap();
let mut keys = HashMap::new();
keys.insert("Symmetric256".to_string(), key.clone());

// Create a CAT instance
let cat = Cat::new(CatOptions {
    keys,
    expect_cwt_tag: true,
});

// Create claims
let mut claims = Claims::new();
claims.set_issuer("example");
claims.set_subject("user123");

// Generate a token
let token = cat.generate(claims, &CatGenerateOptions {
    validation_type: CatValidationType::Mac,
    alg: "HS256".to_string(),
    kid: "Symmetric256".to_string(),
    generate_cwt_id: true,
}).unwrap();

// Now validate the token
let validation_options = CatValidationOptions {
    issuer: "example".to_string(),
    audience: None,
};

match cat.validate(&token, CatValidationType::Mac, &validation_options) {
    Ok(claims) => {
        println!("Token is valid!");
        println!("Subject: {:?}", claims.get_subject());
    }
    Err(err) => {
        eprintln!("Token validation failed: {}", err);
    }
}

References

• CBOR Web Token (CWT) - RFC 8392
• CBOR Object Signing and Encryption (COSE) - RFC 8152
• node-cat Implementation

Re-exports

pub use cat::Cat;

pub use cat::CatGenerateOptions;

pub use cat::CatOptions;

pub use cat::CatValidationOptions;

pub use cat::CatValidationType;

pub use claims::ClaimValue;

pub use claims::Claims;

pub use error::Error;

Modules

cat

claims

cose

error

util