### Complete Workflow Example

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/paserk.md

An end-to-end example demonstrating key generation, serialization to PASERK, and deserialization.

```APIDOC
## Complete Workflow Example

```rust
use pasetors::keys::{Generate, AsymmetricKeyPair};
use pasetors::paserk::{FormatAsPaserk, Id};
use pasetors::version4::V4;
use core::convert::TryFrom;

// Generate a keypair
let kp = AsymmetricKeyPair::<V4>::generate()?;

// Serialize secret key to PASERK
let mut secret_paserk = String::new();
kp.secret.fmt(&mut secret_paserk)?;
println!("Secret: {}", secret_paserk);

// Serialize public key to PASERK
let mut public_paserk = String::new();
kp.public.fmt(&mut public_paserk)?;
println!("Public: {}", public_paserk);

// Create key ID
let id = Id::from(&kp.public);
let mut id_paserk = String::new();
id.fmt(&mut id_paserk)?;
println!("Key ID: {}", id_paserk);

// Later, deserialize from PASERK
let restored_secret = pasetors::keys::AsymmetricSecretKey::<V4>::try_from(secret_paserk.as_str())?;
let restored_public = pasetors::keys::AsymmetricPublicKey::<V4>::try_from(public_paserk.as_str())?;

// Verify they're the same
assert_eq!(restored_secret, kp.secret);
assert_eq!(restored_public, kp.public);

# Ok::<(), Box<dyn std::error::Error>>(())
```
```

--------------------------------

### Public PASETO Token Example

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/token.md

Example of a public PASETO token, which includes a footer.

```text
v4.public.eyJ...ew.eyJr...g
```

--------------------------------

### Example Rust Code Block in Documentation

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/INDEX.md

This shows the standard format for Rust code examples within the pasetors documentation. The line starting with '#' is for testing and is not rendered.

```rust
use pasetors::example::{Type, function};

// Example code here
# Ok::<(), pasetors::errors::Error>(())
```

--------------------------------

### Local PASETO Token Example

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/token.md

Example of a local PASETO token, which does not include a footer.

```text
v4.local.AAAA...bbbb
```

--------------------------------

### Footer::new

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/footer.md

Creates a new `Footer` instance with default limits. This is the starting point for building a footer.

```APIDOC
## Footer::new

### Description
Creates a new `Footer` instance with default limits.

### Method
`new()`

### Returns
`Footer` - New footer instance

### Example
```rust
use pasetors::footer::Footer;

let footer = Footer::new();
# Ok::<(), pasetors::errors::Error>(())
```
```

--------------------------------

### Usage Example: Footer with Token Signing

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/footer.md

Demonstrates how to create and populate a footer with additional claims, and then use it when signing a token with public key cryptography.

```rust
use pasetors::footer::Footer;
use pasetors::claims::Claims;
use pasetors::public;
use pasetors::keys::{Generate, AsymmetricKeyPair};
use pasetors::version4::V4;

// Create and populate a footer
let mut footer = Footer::new();
footer.add_additional("request_id", "req123")?;
footer.add_additional("user_context", "admin")?;

// Use with public token signing
let kp = AsymmetricKeyPair::<V4>::generate()?;
let mut claims = Claims::new()?;
claims.add_additional("user", "alice")?;

let token = public::sign(&kp.secret, &claims, Some(&footer), None)?;
# Ok::<(), pasetors::errors::Error>(())
```

--------------------------------

### PASETO Token Format Example

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/token.md

Illustrates the standard PASETO token format, which includes version, purpose, payload, and an optional footer.

```text
<version>.<purpose>.<payload>[.<footer>]
```

--------------------------------

### PASERK Format Examples

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/paserk.md

Illustrates the structure of PASERK strings with different versions and key types.

```plaintext
k4.local.xxxxxxxxxxxxx...

```

```plaintext
k4.secret.yyyyyyyyyyyyy...

```

```plaintext
k4.public.zzzzzzzzzzzzz...

```

```plaintext
k4.pid.wwwwwwwwwwww...

```

--------------------------------

### Complete PASERK Workflow Example

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/paserk.md

Demonstrates the full lifecycle of generating an asymmetric keypair, serializing both secret and public keys to PASERK format, creating a PASERK ID, and then deserializing the keys back from their PASERK representations. Verifies that the deserialized keys match the original ones.

```rust
use pasetors::keys::{Generate, AsymmetricKeyPair};
use pasetors::paserk::{FormatAsPaserk, Id};
use pasetors::version4::V4;
use core::convert::TryFrom;

// Generate a keypair
let kp = AsymmetricKeyPair::<V4>::generate()?;

// Serialize secret key to PASERK
let mut secret_paserk = String::new();
kp.secret.fmt(&mut secret_paserk)?;
println!("Secret: {}", secret_paserk);

// Serialize public key to PASERK
let mut public_paserk = String::new();
kp.public.fmt(&mut public_paserk)?;
println!("Public: {}", public_paserk);

// Create key ID
let id = Id::from(&kp.public);
let mut id_paserk = String::new();
id.fmt(&mut id_paserk)?;
println!("Key ID: {}", id_paserk);

// Later, deserialize from PASERK
let restored_secret = pasetors::keys::AsymmetricSecretKey::<V4>::try_from(secret_paserk.as_str())?;
let restored_public = pasetors::keys::AsymmetricPublicKey::<V4>::try_from(public_paserk.as_str())?;

// Verify they're the same
assert_eq!(restored_secret, kp.secret);
assert_eq!(restored_public, kp.public);

# Ok::<(), Box<dyn std::error::Error>>(())
```

--------------------------------

### Handle Key Error

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/errors.md

Demonstrates handling `Error::Key` when key validation fails, for example, due to incorrect byte length or unparseable key material. This example specifically shows a V4 key size mismatch.

```rust
use pasetors::keys::{AsymmetricSecretKey, SymmetricKey};
use pasetors::version4::V4;
use pasetors::errors::Error;

let invalid_key_bytes = vec![0u8; 16]; // Wrong length for V4 (needs 32)
match SymmetricKey::<V4>::from(&invalid_key_bytes) {
    Err(Error::Key) => eprintln!("Key size invalid for V4"),
    Err(e) => eprintln!("Other error: {:?}", e),
    Ok(key) => println!("Key created"),
}
```

--------------------------------

### Create and Verify a Public PASETO Token

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/README.md

Demonstrates the process of generating a keypair, creating claims, signing a token, and then verifying it with claims validation. This example uses the high-level API for PASETO Version 4.

```rust
use pasetors::public;
use pasetors::claims::{Claims, ClaimsValidationRules};
use pasetors::keys::{Generate, AsymmetricKeyPair};
use pasetors::token::{Public, UntrustedToken};
use pasetors::version4::V4;
use core::convert::TryFrom;

// 1. Generate keypair
let kp = AsymmetricKeyPair::<V4>::generate()?;

// 2. Create claims
let mut claims = Claims::new()?;
claims.issuer("https://auth.example.com")?;
claims.subject("user123")?;
claims.add_additional("role", "admin")?;

// 3. Sign to create token
let token = public::sign(&kp.secret, &claims, None, None)?;
println!("Token: {}", token);

// ---

// Later, verify

// 4. Parse untrusted token
let untrusted = UntrustedToken::<Public, V4>::try_from(token.as_str())?;

// 5. Create validation rules
let mut rules = ClaimsValidationRules::new();
rules.validate_issuer_with("https://auth.example.com");
rules.validate_subject_with("user123");

// 6. Verify token and validate claims
let trusted = public::verify(&kp.public, &untrusted, &rules, None, None)?;

// 7. Access verified claims
if let Some(claims) = trusted.payload_claims() {
    println!("User role: {:?}", claims.get_claim("role"));
}
# Ok::<(), pasetors::errors::Error>(())

```

--------------------------------

### Rust Example: Validating Claims with Issuer Rule

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/claims.md

Demonstrates how to create claims, set an issuer validation rule, and then validate the claims against these rules. Ensure the `pasetors::claims` and `pasetors::errors` modules are in scope.

```rust
use pasetors::claims::{Claims, ClaimsValidationRules};

let mut claims = Claims::new()?;
claims.issuer("example.com")?;

let mut rules = ClaimsValidationRules::new();
rules.validate_issuer_with("example.com");

rules.validate_claims(&claims)?;
# Ok::<(), pasetors::errors::Error>(())
```

--------------------------------

### Error Pattern Matching Example

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/errors.md

Demonstrates how to use pattern matching to handle different types of Pasetors errors, including general validation errors and specific claim validation errors like expiration.

```rust
use pasetors::errors::{Error, ClaimValidationError};

match some_operation() {
    Err(Error::TokenValidation) => { /* handle tampered token */ },
    Err(Error::ClaimValidation(ClaimValidationError::Exp)) => { /* handle expiration */ },
    Err(Error::ClaimValidation(_)) => { /* handle other validation errors */ },
    Err(e) => { /* handle all other errors */ },
    Ok(result) => { /* success */ },
}
```

--------------------------------

### Handle EmptyPayload Error When Creating a Token

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/errors.md

This example illustrates handling an `EmptyPayload` error, which occurs when attempting to create a PASETO token with an empty payload. The PASETO specification mandates non-empty payloads for security reasons.

```rust
use pasetors::public;
use pasetors::claims::Claims;
use pasetors::keys::{Generate, AsymmetricKeyPair};
use pasetors::version4::V4;
use pasetors::errors::Error;

let kp = AsymmetricKeyPair::<V4>::generate()?;
let empty_claims = Claims::new()?;
// ... if somehow serialized to empty string ...

match public::sign(&kp.secret, &empty_claims, None, None) {
    Err(Error::EmptyPayload) => eprintln!("Cannot create token with empty payload"),
    Err(e) => eprintln!("Other error: {:?}", e),
    Ok(token) => println!("Token created"),
}
```

--------------------------------

### Get Verified Footer Bytes

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/token.md

Retrieves the verified footer of a trusted token as a byte slice. The footer is empty if no footer was included during token creation.

```rust
use pasetors::token::TrustedToken;

let footer_bytes = trusted_token.footer();
if !footer_bytes.is_empty() {
    let footer_json = std::str::from_utf8(footer_bytes)?;
}
# Ok::<(), Box<dyn std::error::Error>>(())
```

--------------------------------

### Get Asymmetric Key as Bytes

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/keys.md

Retrieve the raw byte representation of an asymmetric key. This is useful for serialization or when needing to pass the key as bytes to other functions.

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

--------------------------------

### Handle ClaimValidation Errors During Token Verification

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/errors.md

This example demonstrates how to catch `ClaimValidation` errors, which indicate that a registered claim validation rule has failed during token verification. It shows specific handling for expiration (`Exp`) and issuer (`Iss`) validation failures.

```rust
use pasetors::public;
use pasetors::claims::{ClaimsValidationRules, ClaimValidationError};
use pasetors::token::{Public, UntrustedToken};
use pasetors::version4::V4;
use core::convert::TryFrom;
use pasetors::errors::Error;

let untrusted = UntrustedToken::<Public, V4>::try_from(token_str)?;

match public::verify(&public_key, &untrusted, &rules, None, None) {
    Err(Error::ClaimValidation(ClaimValidationError::Exp)) => {
        eprintln!("Token has expired");
    },
    Err(Error::ClaimValidation(ClaimValidationError::Iss)) => {
        eprintln!("Token issuer doesn't match");
    },
    Err(e) => eprintln!("Other error: {:?}", e),
    Ok(trusted) => println!("Token verified"),
}
```

--------------------------------

### Get Verified Payload String

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/token.md

Retrieves the verified payload of a trusted token as a UTF-8 string. This payload can then be parsed, for example, into JSON.

```rust
use pasetors::token::TrustedToken;
use serde_json::json;

let payload = trusted_token.payload();
let json: serde_json::Value = serde_json::from_str(payload).unwrap();
```

--------------------------------

### Create and Decrypt a Local PASETO Token

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/README.md

Demonstrates generating a symmetric key, creating claims, encrypting them into a local token, and later decrypting and validating the token.

```rust
use pasetors::local;
use pasetors::claims::{Claims, ClaimsValidationRules};
use pasetors::keys::{Generate, SymmetricKey};
use pasetors::token::{Local, UntrustedToken};
use pasetors::version4::V4;
use core::convert::TryFrom;

// 1. Generate shared secret key
let sk = SymmetricKey::<V4>::generate()?;

// 2. Create claims
let mut claims = Claims::new()?;
claims.add_additional("session_id", "sess_abc123")?;
claims.add_additional("user_id", "user123")?;

// 3. Encrypt to create token
let token = local::encrypt(&sk, &claims, None, None)?;

// --- Later, decrypt ---

// 4. Parse untrusted token
let untrusted = UntrustedToken::<Local, V4>::try_from(token.as_str())?;

// 5. Decrypt and validate claims
let rules = ClaimsValidationRules::new();
let trusted = local::decrypt(&sk, &untrusted, &rules, None, None)?;

// 6. Access decrypted claims
if let Some(claims) = trusted.payload_claims() {
    println!("Session: {:?}", claims.get_claim("session_id"));
}
# Ok::<(), pasetors::errors::Error>(())
```

--------------------------------

### AsymmetricSecretKey::as_bytes

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/keys.md

Get the AsymmetricSecretKey as a byte slice.

```APIDOC
## AsymmetricSecretKey::as_bytes

### Description
Get the key as a byte slice.

### Returns
`&[u8]` - Key bytes

### Example
```rust
use pasetors::keys::{Generate, AsymmetricKeyPair};
use pasetors::version4::V4;

let kp = AsymmetricKeyPair::<V4>::generate()?;
let secret_bytes = kp.secret.as_bytes().to_vec();
let secret = pasetors::keys::AsymmetricSecretKey::<V4>::from(&secret_bytes)?;
# Ok::<(), pasetors::errors::Error>(())
```
```

--------------------------------

### SymmetricKey::as_bytes

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/keys.md

Get the SymmetricKey as a byte slice.

```APIDOC
## SymmetricKey::as_bytes

### Description
Get the key as a byte slice.

### Returns
`&[u8]` - Key bytes

### Example
```rust
use pasetors::keys::{Generate, SymmetricKey};
use pasetors::version4::V4;

let key = SymmetricKey::<V4>::generate()?;
let bytes = key.as_bytes();
assert_eq!(bytes.len(), 32);
# Ok::<(), pasetors::errors::Error>(())
```
```

--------------------------------

### Create New Footer Instance

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/footer.md

Use this method to initialize a new Footer object with default configuration for key limits and length.

```rust
use pasetors::footer::Footer;

let footer = Footer::new();
# Ok::<(), pasetors::errors::Error>(())
```

--------------------------------

### Get Claim Value

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/claims.md

Retrieves the value of a claim by its name. Returns Some(value) if the claim is found, or None if it does not exist.

```rust
use pasetors::claims::Claims;

let claims = Claims::new()?;
if let Some(exp) = claims.get_claim("exp") {
    println!("Expiration: {:?}", exp);
}
# Ok::<(), pasetors::errors::Error>(())
```

--------------------------------

### Serialize Keys to PASERK Format

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/README.md

Shows how to generate asymmetric key pairs and symmetric keys, then serialize them into the PASERK format for storage or transmission. Also demonstrates parsing them back.

```rust
use pasetors::keys::{Generate, AsymmetricKeyPair, SymmetricKey};
use pasetors::paserk::{FormatAsPaserk, Id};
use pasetors::version4::V4;
use core::convert::TryFrom;

// Generate keys
let kp = AsymmetricKeyPair::<V4>::generate()?;
let sk = SymmetricKey::<V4>::generate()?;

// Serialize to PASERK
let mut secret_paserk = String::new();
kp.secret.fmt(&mut secret_paserk)?;

let mut public_paserk = String::new();
kp.public.fmt(&mut public_paserk)?;

let mut local_paserk = String::new();
sk.fmt(&mut local_paserk)?;

// Create and serialize key ID
let id = Id::from(&kp.public);
let mut id_paserk = String::new();
id.fmt(&mut id_paserk)?;

println!("Secret: {}", secret_paserk);   // k4.secret.xxx...
println!("Public: {}", public_paserk);   // k4.public.yyy...
println!("Local: {}", local_paserk);     // k4.local.zzz...
println!("ID: {}", id_paserk);           // k4.pid.www...

// Parse back from PASERK
let restored_secret = pasetors::keys::AsymmetricSecretKey::<V4>::try_from(secret_paserk.as_str())?;
let restored_public = pasetors::keys::AsymmetricPublicKey::<V4>::try_from(public_paserk.as_str())?;
let restored_local = SymmetricKey::<V4>::try_from(local_paserk.as_str())?;

# Ok::<(), Box<dyn std::error::Error>>(())
```

--------------------------------

### Get Symmetric Key Bytes

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/keys.md

Retrieves the raw byte representation of a symmetric key. The key is automatically zeroed when dropped.

```rust
use pasetors::keys::{Generate, SymmetricKey};
use pasetors::version4::V4;

let key = SymmetricKey::<V4>::generate()?;
let bytes = key.as_bytes();
assert_eq!(bytes.len(), 32);
# Ok::<(), pasetors::errors::Error>(())
```

--------------------------------

### Rust Function Signature: validate_token_identifier_with

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/claims.md

Sets the expected token identifier for validation. This function is part of the claims validation setup.

```rust
pub fn validate_token_identifier_with(&mut self, valid_token_identifier: &str)
```

--------------------------------

### Get Token Header

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/token.md

Retrieves the header part of a trusted token as a string slice. The header typically indicates the token version and type.

```rust
use pasetors::token::TrustedToken;

let header = trusted_token.header();
assert!(header.starts_with("v4."));
```

--------------------------------

### Symmetric Key Parsing

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/paserk.md

Demonstrates how to parse symmetric keys from their PASERK string representation into usable key objects.

```APIDOC
### Symmetric Keys

#### Parsing

```rust
use pasetors::keys::SymmetricKey;
use pasetors::version4::V4;
use core::convert::TryFrom;

let paserk_str = "k4.local.xxx...";
let key = SymmetricKey::<V4>::try_from(paserk_str)?;
# Ok::<(), pasetors::errors::Error>(())
```
```

--------------------------------

### Public Token Workflow

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/public_local.md

Demonstrates the full lifecycle of a public token: generating an asymmetric key pair, signing claims, creating an untrusted token, and then verifying and validating it. Suitable for scenarios where tokens need to be verified by multiple parties without sharing secret keys.

```rust
use pasetors::public;
use pasetors::claims::{Claims, ClaimsValidationRules};
use pasetors::keys::{Generate, AsymmetricKeyPair};
use pasetors::token::{Public, UntrustedToken};
use pasetors::version4::V4;
use core::convert::TryFrom;

// Generate keypair
let kp = AsymmetricKeyPair::<V4>::generate()?;

// Create claims
let mut claims = Claims::new()?;
claims.issuer("https://example.com")?;
claims.subject("user123")?;
claims.add_additional("email", "user@example.com")?;

// Create token
let token = public::sign(&kp.secret, &claims, None, None)?;
println!("Created token: {}", token);

// Parse untrusted token
let untrusted = UntrustedToken::<Public, V4>::try_from(token.as_str())?;

// Verify and validate
let mut rules = ClaimsValidationRules::new();
rules.validate_issuer_with("https://example.com");
rules.validate_subject_with("user123");

let trusted = public::verify(&kp.public, &untrusted, &rules, None, None)?;

// Access validated claims
if let Some(claims) = trusted.payload_claims() {
    println!("Email: {:?}", claims.get_claim("email"));
}
# Ok::<(), pasetors::errors::Error>(())
```

--------------------------------

### Get Untrusted Footer Bytes

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/token.md

Retrieves the raw bytes of the untrusted footer from a token. This is useful for inspecting footer data before cryptographic verification.

```rust
use pasetors::token::{Public, UntrustedToken};
use pasetors::version4::V4;
use core::convert::TryFrom;

let token = "v4.public.payload.footer";
let untrusted = UntrustedToken::<Public, V4>::try_from(token)?;
let footer = untrusted.untrusted_footer();
// footer can be inspected before verification
# Ok::<(), pasetors::errors::Error>(())
```

--------------------------------

### Get Implicit Assertion Bytes

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/token.md

Retrieves the implicit assertion bytes used during token creation. This will be empty if `None` was used or if the token was created with V2.

```rust
pub fn implicit_assert(&self) -> &[u8]
```

--------------------------------

### Generate, Encrypt, Decrypt, and Verify Local PASETO Token

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/public_local.md

This snippet demonstrates the complete local token workflow. It includes generating a symmetric key, creating claims with additional data, encrypting the token, and then decrypting and verifying it with validation rules. Use this for secure local communication where a shared secret is feasible.

```rust
use pasetors::local;
use pasetors::claims::{Claims, ClaimsValidationRules};
use pasetors::keys::{Generate, SymmetricKey};
use pasetors::token::{Local, UntrustedToken};
use pasetors::version4::V4;
use core::convert::TryFrom;

// Generate symmetric key
let sk = SymmetricKey::<V4>::generate()?;

// Create claims
let mut claims = Claims::new()?;
claims.add_additional("session_id", "sess_abc123")?;
claims.add_additional("user_role", "admin")?;

// Create token
let token = local::encrypt(&sk, &claims, None, None)?;
println!("Created token: {}", token);

// Later, decrypt and verify
let untrusted = UntrustedToken::<Local, V4>::try_from(token.as_str())?;

let rules = ClaimsValidationRules::new();
let trusted = local::decrypt(&sk, &untrusted, &rules, None, None)?;

// Access decrypted claims
if let Some(claims) = trusted.payload_claims() {
    if let Some(session_id) = claims.get_claim("session_id") {
        println!("Session: {}", session_id);
    }
}
# Ok::<(), pasetors::errors::Error>(())
```

--------------------------------

### AsymmetricPublicKey::from

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/keys.md

Creates an AsymmetricPublicKey from a byte slice. The byte slice must be of a specific length depending on the key version (32 bytes for V2/V4, 49 bytes for V3).

```APIDOC
## AsymmetricPublicKey::from(bytes)

### Description
Creates an `AsymmetricPublicKey` from raw bytes.

### Method
`from`

### Parameters
#### Path Parameters
- **bytes** (`&[u8]`) - Required - Raw key bytes (32 bytes for V2/V4, 49 bytes for V3)

### Response
#### Success Response
- **Self** (`AsymmetricPublicKey<V>`) - The created public key.

#### Errors
- **Key** - Condition: bytes length doesn't match version.

### Example
```rust
use pasetors::keys::{AsymmetricPublicKey};
use pasetors::version4::V4;

// Assuming pub_bytes is a Vec<u8> containing the public key bytes
// let pub_bytes = kp.public.as_bytes().to_vec();
// let public = pasetors::keys::AsymmetricPublicKey::<V4>::from(&pub_bytes)?;
```
```

--------------------------------

### Get Payload Claims from Trusted Token

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/token.md

Retrieves the validated claims parsed from the payload of a trusted token. This is only available when the `std` feature is enabled. Returns `None` if claims were not parsed or validated.

```rust
use pasetors::public;
use pasetors::claims::{Claims, ClaimsValidationRules};
use pasetors::token::UntrustedToken;

let validation_rules = ClaimsValidationRules::new();
let trusted = public::verify(&public_key, &untrusted, &validation_rules, None, None)?;

if let Some(claims) = trusted.payload_claims() {
    if let Some(iss) = claims.get_claim("iss") {
        println!("Issuer: {}", iss);
    }
}
# Ok::<(), pasetors::errors::Error>(())
```

--------------------------------

### Asymmetric Public Key Parsing

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/paserk.md

Illustrates parsing asymmetric public keys from their PASERK string representation.

```APIDOC
### Public Keys (Asymmetric)

#### Parsing

```rust
use pasetors::keys::AsymmetricPublicKey;
use pasetors::version4::V4;
use core::convert::TryFrom;

let paserk_str = "k4.public.xxx...";
let key = AsymmetricPublicKey::<V4>::try_from(paserk_str)?;
# Ok::<(), pasetors::errors::Error>(())
```
```

--------------------------------

### Get Untrusted Message Bytes

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/token.md

Retrieves the raw, unverified message bytes from an `UntrustedToken`. For Local tokens, this includes nonce, ciphertext, and tag; for Public tokens, it includes the payload and signature.

```rust
use pasetors::token::{Public, UntrustedToken};
use pasetors::version4::V4;
use core::convert::TryFrom;

let token = "v4.public.eyJkYXRhIjoidGhpcyBpcyBhIHNpZ25lZCBtZXNzYWdlIn19...";
let untrusted = UntrustedToken::<Public, V4>::try_from(token)?;
let msg = untrusted.untrusted_message();
println!("Message length: {}", msg.len());
# Ok::<(), pasetors::errors::Error>(())
```

--------------------------------

### Get Untrusted Payload Bytes

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/token.md

Retrieves only the untrusted payload bytes from an `UntrustedToken`, excluding the signature or authentication tag. For Local tokens, this is the encrypted payload; for Public tokens, it's the plaintext payload.

```rust
pub fn untrusted_payload(&self) -> &[u8]

```

--------------------------------

### Minimal no_std Pasetors Configuration

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/README.md

Configure the Pasetors crate with minimal features for a no_std environment, enabling only PASETO Version 4.

```toml
pasetors = { version = "0.7", default-features = false, features = ["v4"] }
```

--------------------------------

### Handle Public Key Conversion Errors

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/errors.md

Use this snippet when there's a failure in converting between compressed and uncompressed public key formats, or if the public key bytes are invalid for the operation.

```rust
use pasetors::errors::Error;

match some_key_conversion() {
    Err(Error::PublicKeyConversion) => eprintln!("Cannot convert public key format"),
    Err(e) => eprintln!("Other error: {:?}", e),
    Ok(result) => println!("Conversion successful"),
}
```

--------------------------------

### public::sign()

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/public_local.md

Creates a public PASETO token by signing claims with a secret key. Supports optional footer and implicit assertions.

```APIDOC
## sign()

### Description
Create a public token by signing claims with a secret key.

### Method
`sign`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| secret_key | `&AsymmetricSecretKey<V4>` | Yes | — | Secret key for signing |
| message | `&Claims` | Yes | — | Claims to sign |
| footer | `Option<&Footer>` | No | None | Optional footer |
| implicit_assert | `Option<&[u8]>` | No | None | Optional implicit assertion |

### Returns
`Result<String, Error>` - Token string or error

### Errors
| Error | Condition |
|-------|-----------|
| `EmptyPayload` | Claims serializes to empty payload |
| `Key` | Secret key is invalid |
| `Signing` | Signature generation failed |
| Other | Claims or footer serialization fails |

### Example
```rust
use pasetors::public;
use pasetors::claims::Claims;
use pasetors::keys::{Generate, AsymmetricKeyPair};
use pasetors::version4::V4;

let kp = AsymmetricKeyPair::<V4>::generate()?;
let mut claims = Claims::new()?;
claims.add_additional("user_id", "12345")?;

let token = public::sign(&kp.secret, &claims, None, None)?;
println!("Token: {}", token);
# Ok::<(), pasetors::errors::Error>(())
```
```

--------------------------------

### SymmetricKey::from

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/keys.md

Create a SymmetricKey from raw bytes. The byte slice must have the correct length for the version.

```APIDOC
## SymmetricKey::from

### Description
Create a `SymmetricKey` from raw bytes. The byte slice must have the correct length for the version.

### Parameters
#### Path Parameters
- **bytes** (`&[u8]`) - Required - Raw key bytes (32 bytes for V2/V4)

### Returns
`Result<SymmetricKey<V>, Error>` - Key or error if invalid

### Errors
| Error | Condition |
|---|---|
| `Key` | bytes length doesn't match version requirements |

### Example
```rust
use pasetors::keys::SymmetricKey;
use pasetors::version4::V4;

let key_bytes = vec![0u8; 32];
let key = SymmetricKey::<V4>::from(&key_bytes)?;
# Ok::<(), pasetors::errors::Error>(())
```
```

--------------------------------

### Add a Footer to a PASETO Token

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/README.md

Demonstrates how to add authenticated but unencrypted metadata (a footer) to a PASETO token during the signing process.

```rust
use pasetors::public;
use pasetors::claims::Claims;
use pasetors::footer::Footer;
use pasetors::keys::{Generate, AsymmetricKeyPair};
use pasetors::version4::V4;

let kp = AsymmetricKeyPair::<V4>::generate()?;
let mut claims = Claims::new()?;

// Create footer
let mut footer = Footer::new();
footer.add_additional("request_id", "req123")?;
footer.add_additional("environment", "production")?;

// Sign with footer
let token = public::sign(&kp.secret, &claims, Some(&footer), None)?;

# Ok::<(), pasetors::errors::Error>(())
```

--------------------------------

### Id fmt(write)

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/paserk.md

Demonstrates formatting a PASERK ID into its string representation.

```APIDOC
#### fmt(write)

```rust
fn fmt(&self, write: &mut dyn Write) -> core::fmt::Result
```

##### Description

Format the ID as a PASERK string and write to the provided writer.

##### Example

```rust
use pasetors::keys::{Generate, AsymmetricKeyPair};
use pasetors::paserk::{Id, FormatAsPaserk};
use pasetors::version4::V4;

let kp = AsymmetricKeyPair::<V4>::generate()?;
let id = Id::from(&kp.public);

let mut paserk_id = String::new();
id.fmt(&mut paserk_id)?;
println!("Key ID: {}", paserk_id);
# Ok::<(), pasetors::errors::Error>(())
```
```

--------------------------------

### encrypt()

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/public_local.md

Creates a local token by encrypting and authenticating claims with a symmetric key. This function is used to generate secure tokens for local communication.

```APIDOC
## encrypt()

### Description
Create a local token by encrypting and authenticating claims with a symmetric key.

### Method
encrypt

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **secret_key** (`&SymmetricKey<V4>`) - Required - Symmetric key for encryption
- **message** (`&Claims`) - Required - Claims to encrypt
- **footer** (`Option<&Footer>`) - Optional - Optional footer
- **implicit_assert** (`Option<&[u8]>`) - Optional - Optional implicit assertion

### Request Example
```rust
use pasetors::local;
use pasetors::claims::Claims;
use pasetors::keys::{Generate, SymmetricKey};
use pasetors::version4::V4;

let sk = SymmetricKey::<V4>::generate()?;
let mut claims = Claims::new()?;
claims.add_additional("session_id", "sess123")?;

let token = local::encrypt(&sk, &claims, None, None)?;
println!("Token: {}", token);
# Ok::<(), pasetors::errors::Error>(())
```

### Response
#### Success Response (200)
- **String** - Token string

#### Response Example
```json
{
  "example": "v4.local.AAAa..."
}
```

### Errors
- **EmptyPayload**: Claims serializes to empty payload
- **Key**: Secret key is invalid
- **Encryption**: Encryption or authentication failed
- **Other**: Claims or footer serialization fails
```

--------------------------------

### All Features Enabled Pasetors Configuration

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/README.md

Enable all available features for the Pasetors crate, including standard library support, all PASETO versions, PASERK, and serialization.

```toml
pasetors = { version = "0.7", features = ["std", "v2", "v3", "v4", "paserk", "serde"] }
```

--------------------------------

### Sign Public Token (V3)

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/versions.md

Creates a signed Version 3 public token. Requires an asymmetric secret key, message, and optional footer or implicit assertion.

```rust
pub fn sign(
    secret_key: &AsymmetricSecretKey<V3>,
    message: &[u8],
    footer: Option<&[u8]>,
    implicit_assert: Option<&[u8]>,
) -> Result<String, Error>
```

--------------------------------

### Create New Claims Instance

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/claims.md

Instantiate a new Claims object with default expiration settings (iat, nbf, exp). Use when a token needs to expire automatically.

```rust
use pasetors::claims::Claims;

let claims = Claims::new()?;
// claims now has iat, nbf, and exp set automatically
# Ok::<(), pasetors::errors::Error>(())
```

--------------------------------

### Create Non-Expiring PASETO Tokens

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/README.md

Demonstrates how to create a PASETO token that does not expire by removing the 'expiration' (exp) claim and configuring validation rules to allow it.

```rust
use pasetors::claims::{Claims, ClaimsValidationRules};

// Create non-expiring token
let mut claims = Claims::new()?;
claims.non_expiring();  // Remove exp claim

// Validation must allow non-expiring
let mut rules = ClaimsValidationRules::new();
rules.allow_non_expiring();

rules.validate_claims(&claims)?;

# Ok::<(), pasetors::errors::Error>(())
```

--------------------------------

### Encrypt Local Token (V4)

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/versions.md

Creates an encrypted and authenticated Version 4 local token. Requires a symmetric key, message, and optional footer or implicit assertion.

```rust
use pasetors::version4::{V4, LocalToken};
use pasetors::keys::{Generate, SymmetricKey};

let sk = SymmetricKey::<V4>::generate()?;
let message = b"Secret message";
let token = LocalToken::encrypt(&sk, message, None, None)?;
println!("Token: {}", token);
# Ok::<(), pasetors::errors::Error>(())
```

--------------------------------

### Verify Public Token (V3)

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/versions.md

Verifies a signed Version 3 public token. Requires an asymmetric public key, the token, and optional footer or implicit assertion for validation.

```rust
pub fn verify(
    public_key: &AsymmetricPublicKey<V3>,
    token: &UntrustedToken<Public, V3>,
    footer: Option<&[u8]>,
    implicit_assert: Option<&[u8]>,
) -> Result<TrustedToken, Error>
```

--------------------------------

### Error Conversion from TryFromIntError

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/errors.md

Illustrates the automatic conversion of `core::num::TryFromIntError` to `pasetors::errors::Error::LossyConversion`.

```rust
impl From<core::num::TryFromIntError> for Error {
    fn from(_: core::num::TryFromIntError) -> Self {
        Error::LossyConversion
    }
}
```

--------------------------------

### Create AsymmetricPublicKey from Bytes

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/keys.md

Use this function to create an AsymmetricPublicKey from raw byte slices. Ensure the byte length matches the expected version (32 bytes for V2/V4, 49 bytes for V3).

```rust
use pasetors::keys::{Generate, AsymmetricKeyPair};
use pasetors::version4::V4;

let kp = AsymmetricKeyPair::<V4>::generate()?;
let pub_bytes = kp.public.as_bytes().to_vec();
let public = pasetors::keys::AsymmetricPublicKey::<V4>::from(&pub_bytes)?;
# Ok::<(), pasetors::errors::Error>(())
```

--------------------------------

### public::verify()

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/public_local.md

Verifies a public PASETO token and validates its claims against provided rules. Supports optional footer and implicit assertions.

```APIDOC
## verify()

### Description
Verify a public token and validate its claims.

### Method
`verify`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| public_key | `&AsymmetricPublicKey<V4>` | Yes | — | Public key for verification |
| token | `&UntrustedToken<Public, V4>` | Yes | — | Token to verify |
| validation_rules | `&ClaimsValidationRules` | Yes | — | Claims validation rules |
| footer | `Option<&Footer>` | No | None | Expected footer (validated if provided) |
| implicit_assert | `Option<&[u8]>` | No | None | Implicit assertion (validated if provided) |

### Returns
`Result<TrustedToken, Error>` - Verified token with validated claims or error

### Errors
| Error | Condition |
|-------|-----------|
| `TokenValidation` | Signature verification failed |
| `ClaimValidation(...)` | Claims validation failed |
| Other | Footer parsing or validation fails |

### Note
Claims validation is automatic using the provided validation rules.

### Example
```rust
use pasetors::public;
use pasetors::claims::ClaimsValidationRules;
use pasetors::token::{Public, UntrustedToken};
use pasetors::version4::V4;
use core::convert::TryFrom;

let token_str = "v4.public.eyJ...";
let untrusted = UntrustedToken::<Public, V4>::try_from(token_str)?;

let mut validation_rules = ClaimsValidationRules::new();
validation_rules.validate_issuer_with("example.com");

let trusted = public::verify(&public_key, &untrusted, &validation_rules, None, None)?;
println!("Claims: {:?}", trusted.payload_claims());
# Ok::<(), pasetors::errors::Error>(())
```
```

--------------------------------

### Create Claims from String

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/claims.md

Create `Claims` from a JSON string. The string must be valid JSON and adhere to claim format rules.

```rust
pub fn from_string(string: &str) -> Result<Self, Error>
```

--------------------------------

### Set Not Before Claim

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/claims.md

Sets the 'nbf' (not before) registered claim. Must be an ISO 8601 datetime string. Errors if the format is invalid.

```rust
pub fn not_before(&mut self, nbf: &str) -> Result<(), Error>
```

--------------------------------

### Parse AsymmetricPublicKey from PASERK

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/paserk.md

Parses an AsymmetricPublicKey from a PASERK formatted string. The input string must be a valid PASERK public key format (e.g., k4.public.xxx...).

```rust
use pasetors::keys::AsymmetricPublicKey;
use pasetors::version4::V4;
use core::convert::TryFrom;

let paserk_str = "k4.public.xxx...";
let key = AsymmetricPublicKey::<V4>::try_from(paserk_str)?;
# Ok::<(), pasetors::errors::Error>(())
```

--------------------------------

### verify() - V3 PublicToken

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/versions.md

Verifies a signed Version 3 public token. This function requires a public key, the token to verify, and optional footer and implicit assertion.

```APIDOC
## verify() V3 PublicToken

### Description
Verify a signed Version 3 token.

### Method
verify

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **public_key** (`&AsymmetricPublicKey<V3>`) - Required - Public key for verification
- **token** (`&UntrustedToken<Public, V3>`) - Required - Token to verify
- **footer** (`Option<&[u8]>`) - Optional - Expected footer (optional validation)
- **implicit_assert** (`Option<&[u8]>`) - Optional - Expected implicit assertion (optional validation)

### Request Example
```rust
// Example for verify() would go here if provided in source
```

### Response
#### Success Response (200)
- **TrustedToken** - Verified token

#### Response Example
```json
{
  "payload": "<verified_payload>"
}
```

### Errors
None explicitly listed in source for this snippet, but general errors may apply.
```

--------------------------------

### Asymmetric Secret Key Parsing

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/paserk.md

Shows how to parse asymmetric secret keys from their PASERK string representation.

```APIDOC
### Secret Keys (Asymmetric)

#### Parsing

```rust
use pasetors::keys::AsymmetricSecretKey;
use pasetors::version4::V4;
use core::convert::TryFrom;

let paserk_str = "k4.secret.xxx...";
let key = AsymmetricSecretKey::<V4>::try_from(paserk_str)?;
# Ok::<(), pasetors::errors::Error>(())
```
```

--------------------------------

### AsymmetricSecretKey::from

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/keys.md

Create an AsymmetricSecretKey from raw bytes. The byte slice must have the correct length and format for the version.

```APIDOC
## AsymmetricSecretKey::from

### Description
Create an `AsymmetricSecretKey` from raw bytes. The byte slice must have the correct length and format for the version.

### Parameters
#### Path Parameters
- **bytes** (`&[u8]`) - Required - Raw key bytes (64 bytes for V2/V4, 48 bytes for V3)

### Returns
`Result<AsymmetricSecretKey<V>, Error>` - Key or error if invalid

### Errors
| Error | Condition |
|---|---|
| `Key` | bytes length doesn't match version or key validation failed |

### Panics
- For V2/V4: Panics if an all-zero seed is used

### Example
```rust
use pasetors::keys::{Generate, AsymmetricKeyPair};
use pasetors::version4::V4;

let kp = AsymmetricKeyPair::<V4>::generate()?;
let secret_bytes = kp.secret.as_bytes().to_vec();
let secret = pasetors::keys::AsymmetricSecretKey::<V4>::from(&secret_bytes)?;
# Ok::<(), pasetors::errors::Error>(())
```
```

--------------------------------

### TryFrom<&TrustedToken> for Footer

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/token.md

Parses a `Footer` object from the footer field of a verified `TrustedToken`. This conversion is available when the `std` feature is enabled.

```APIDOC
## TryFrom<&TrustedToken> for Footer

### Description
Parse a `Footer` from a verified token's footer field.

### Errors
- `FooterParsing`: Footer is empty or not valid JSON

### Example
```rust
use pasetors::token::{TrustedToken, UntrustedToken, Public};
use pasetors::footer::Footer;
use pasetors::version4::V4;
use core::convert::TryFrom;

let trusted: TrustedToken = /* verified token */;
let footer = Footer::try_from(&trusted)?;
if let Some(kid) = footer.get_claim("kid") {
    println!("Key ID: {}", kid);
}
```
```

--------------------------------

### Claims::new()

Source: https://github.com/brycx/pasetors/blob/master/_autodocs/api-reference/claims.md

Creates a new Claims instance with default expiration settings. The `iat` (issued at) and `nbf` (not before) claims are set to the current UTC time, and the `exp` (expiration time) claim is set to one hour from the current time.

```APIDOC
## Claims::new()

### Description
Creates a new `Claims` instance with default expiration settings. The `iat` (issued at) and `nbf` (not before) claims are set to the current UTC time, and the `exp` (expiration time) claim is set to one hour from the current time.

### Method
`pub fn new() -> Result<Self, Error>`

### Parameters
None

### Returns
`Result<Claims, Error>` - A new claims instance or an error if time addition would overflow.

### Errors
- `InvalidClaim`: If adding the current time with one hour would overflow.

### Example
```rust
use pasetors::claims::Claims;

let claims = Claims::new()?;
// claims now has iat, nbf, and exp set automatically
# Ok::<(), pasetors::errors::Error>(())
```
```