pasetors

https://docs.rs/pasetors/0.8.0/pasetors/
Admin
pasetors is a Rust implementation of Platform-Agnostic Security Tokens (PASETO) and PASERK key...
Tokens:10,620
Snippets:127
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Creating and verifying public tokens

Source: https://docs.rs/pasetors/0.8.0/pasetors/index.html

Demonstrates signing and verifying public tokens using asymmetric keys and automatic claim validation.

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

// Setup the default claims, which include `iat` and `nbf` as the current time and `exp` of one hour.
// Add a custom `data` claim as well.
let mut claims = Claims::new()?;
claims.add_additional("data", "A public, signed message")?;

// Generate the keys and sign the claims.
let kp = AsymmetricKeyPair::<V4>::generate()?;
let pub_token = public::sign(&kp.secret, &claims, None, Some(b"implicit assertion"))?;

// Decide how we want to validate the claims after verifying the token itself.
// The default verifies the `nbf`, `iat` and `exp` claims. `nbf` and `iat` are always
// expected to be present.
// NOTE: Custom claims, defined through `add_additional()`, are not validated. This must be done
// manually.
let validation_rules = ClaimsValidationRules::new();
let untrusted_token = UntrustedToken::<Public, V4>::try_from(&pub_token)?;
let trusted_token = public::verify(&kp.public, &untrusted_token, &validation_rules, None, Some(b"implicit assertion"))?;
assert_eq!(&claims, trusted_token.payload_claims().unwrap());

let claims = trusted_token.payload_claims().unwrap();

println!("{:?}", claims.get_claim("data"));
println!("{:?}", claims.get_claim("iat"));
```

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

### TryFrom<&str> for AsymmetricPublicKey<V>

Source: https://docs.rs/pasetors/0.8.0/pasetors/keys/struct.AsymmetricPublicKey.html

Converts a string representation into an AsymmetricPublicKey for a specific version (V2, V3, or V4). This requires the 'paserk' crate feature.

```APIDOC
## fn try_from(value: &str) -> Result<Self, Self::Error>

### Description
Performs the conversion from a string slice into an AsymmetricPublicKey instance. This method is available for versions V2, V3, and V4 when the 'paserk' feature is enabled.

### Parameters
- **value** (&str) - Required - The string representation of the public key.

### Returns
- **Result<Self, Self::Error>** - Returns the parsed AsymmetricPublicKey or an Error if the conversion fails.
```

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

### pub fn from(bytes: &[u8]) -> Result<Self, Error>

Source: https://docs.rs/pasetors/0.8.0/pasetors/keys/struct.AsymmetricPublicKey.html

Creates a new AsymmetricPublicKey instance from a provided byte slice.

```APIDOC
## pub fn from(bytes: &[u8]) -> Result<Self, Error>

### Description
Creates an `AsymmetricPublicKey` from a raw byte slice.

### Parameters
- **bytes** (&[u8]) - Required - The byte representation of the public key.

### Returns
- **Result<Self, Error>** - Returns the initialized public key or an error if the bytes are invalid.
```

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

### Creating and verifying local tokens

Source: https://docs.rs/pasetors/0.8.0/pasetors/index.html

Demonstrates encrypting and decrypting local tokens using symmetric keys and automatic claim validation.

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

// Setup the default claims, which include `iat` and `nbf` as the current time and `exp` of one hour.
// Add a custom `data` claim as well.
let mut claims = Claims::new()?;
claims.add_additional("data", "A secret, encrypted message")?;

// Generate the key and encrypt the claims.
let sk = SymmetricKey::<V4>::generate()?;
let token = local::encrypt(&sk, &claims, None, Some(b"implicit assertion"))?;

// Decide how we want to validate the claims after verifying the token itself.
// The default verifies the `nbf`, `iat` and `exp` claims. `nbf` and `iat` are always
// expected to be present.
// NOTE: Custom claims, defined through `add_additional()`, are not validated. This must be done
// manually.
let validation_rules = ClaimsValidationRules::new();
let untrusted_token = UntrustedToken::<Local, V4>::try_from(&token)?;
let trusted_token = local::decrypt(&sk, &untrusted_token, &validation_rules, None, Some(b"implicit assertion"))?;
assert_eq!(&claims, trusted_token.payload_claims().unwrap());

let claims = trusted_token.payload_claims().unwrap();

println!("{:?}", claims.get_claim("data"));
println!("{:?}", claims.get_claim("iat"));
```

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

### Serialize keys to PASERK in Rust

Source: https://docs.rs/pasetors/0.8.0/pasetors/index.html

Demonstrates generating a symmetric key and converting it to and from the PASERK format.

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

// Generate the key and serialize to and from PASERK.
let sk = SymmetricKey::<V4>::generate()?;
let mut paserk = String::new();
sk.fmt(&mut paserk).unwrap();
let sk = SymmetricKey::<V4>::try_from(paserk.as_str())?;
```

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

### Manage footers with registered and custom claims in Rust

Source: https://docs.rs/pasetors/0.8.0/pasetors/index.html

Shows how to include a key ID in a footer and retrieve it from a verified token.

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

// Generate the key used to later sign a token.
let kp = AsymmetricKeyPair::<V4>::generate()?;
// Serialize the public key to PASERK "pid".
let mut pid = Id::from(&kp.public);
// Add the "pid" to the "kid" claim of a footer.
let mut footer = Footer::new();
footer.key_id(&pid);
footer.add_additional("custom_footer_claim", "custom_value")?;

let mut claims = Claims::new()?;
let pub_token = public::sign(&kp.secret, &claims, Some(&footer), Some(b"implicit assertion"))?;

// If we receive a token that needs to be verified, we can still try to parse a Footer from it
// as long one was used during creation, if we don't know it beforehand.
let validation_rules = ClaimsValidationRules::new();
let untrusted_token = UntrustedToken::<Public, V4>::try_from(&pub_token)?;
let trusted_token = public::verify(&kp.public, &untrusted_token, &validation_rules, None, Some(b"implicit assertion"))?;
let trusted_footer = Footer::try_from(&trusted_token)?;

let mut kid = String::new();
pid.fmt(&mut kid).unwrap();
assert_eq!(trusted_footer.get_claim("kid").unwrap().as_str().unwrap(), kid);
```

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

### encrypt

Source: https://docs.rs/pasetors/0.8.0/pasetors/local/index.html

Creates a local PASETO token using version 4.

```APIDOC
## encrypt

### Description
Create a local token using the latest PASETO version (v4).
```

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

### encrypt

Source: https://docs.rs/pasetors/0.8.0/pasetors/local/fn.encrypt.html

Creates a local token using the latest PASETO version (v4).

```APIDOC
## Function: encrypt

### Description
Create a local token using the latest PASETO version (v4).

### Signature
`pub fn encrypt(secret_key: &SymmetricKey<V4>, message: &Claims, footer: Option<&Footer>, implicit_assert: Option<&[u8]>) -> Result<String, Error>`

### Parameters
- **secret_key** (&SymmetricKey<V4>) - Required - The symmetric key used for encryption.
- **message** (&Claims) - Required - The claims to be included in the token.
- **footer** (Option<&Footer>) - Optional - An optional footer for the token.
- **implicit_assert** (Option<&[u8]>) - Optional - Optional implicit assertions.

### Returns
- **Result<String, Error>** - Returns the encrypted token string on success, or an Error on failure.
```

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

### sign

Source: https://docs.rs/pasetors/0.8.0/pasetors/public/index.html

Creates a public token using the latest PASETO version (v4).

```APIDOC
## sign

### Description
Create a public token using the latest PASETO version (v4).
```

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

### Set and validate registered claims in Rust

Source: https://docs.rs/pasetors/0.8.0/pasetors/index.html

Demonstrates setting standard claims like issuer, subject, and expiration, and configuring validation rules to verify them.

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

// `iat`, `nbf` and `exp` have been set automatically, but could also be overridden.
let mut claims = Claims::new()?;
claims.issuer("paragonie.com")?;
claims.subject("test")?;
claims.audience("pie-hosted.com")?;
claims.expiration("2039-01-01T00:00:00+00:00")?;
claims.not_before("2038-04-01T00:00:00+00:00")?;
claims.issued_at("2038-03-17T00:00:00+00:00")?;
claims.token_identifier("87IFSGFgPNtQNNuw0AtuLttPYFfYwOkjhqdWcLoYQHvL")?;

let mut validation_rules = ClaimsValidationRules::new();
validation_rules.validate_issuer_with("paragonie.com");
validation_rules.validate_subject_with("test");
validation_rules.validate_audience_with("pie-hosted.com");
validation_rules.validate_token_identifier_with("87IFSGFgPNtQNNuw0AtuLttPYFfYwOkjhqdWcLoYQHvL");

// The token has been set to be issued in the future and not valid yet, so validation fails.
assert!(validation_rules.validate_claims(&claims).is_err());
```

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

### LocalToken::encrypt

Source: https://docs.rs/pasetors/0.8.0/pasetors/version2/struct.LocalToken.html

Creates a new PASETO v2 local token.

```APIDOC
## pub fn encrypt(secret_key: &SymmetricKey<V2>, message: &[u8], footer: Option<&[u8]>) -> Result<String, Error>

### Description
Creates a local token using the provided symmetric key, message, and optional footer.

### Parameters
- **secret_key** (&SymmetricKey<V2>) - Required - The symmetric key used for encryption.
- **message** (&[u8]) - Required - The message to be encrypted.
- **footer** (Option<&[u8]>) - Optional - An optional footer to include in the token.
```

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

### pub fn sign

Source: https://docs.rs/pasetors/0.8.0/pasetors/public/fn.sign.html

Creates a public token using the latest PASETO version (v4).

```APIDOC
## pub fn sign

### Description
Create a public token using the latest PASETO version (v4).

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

### Requirements
Available on crate features `std` and `v4` only.
```

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

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

Source: https://docs.rs/pasetors/0.8.0/pasetors/keys/struct.AsymmetricPublicKey.html

Retrieves the underlying byte representation of the public key.

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

### Description
Returns the public key as a byte-slice.

### Returns
- **&[u8]** - The byte slice representation of the key.
```

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

### PublicToken::verify

Source: https://docs.rs/pasetors/0.8.0/pasetors/version3/struct.PublicToken.html

Verifies a PASETO v3 public token using the provided public key and optional footer and implicit assertion.

```APIDOC
## PublicToken::verify

### Description
Verify a public token. The public_key must be in big-endian. If footer is provided, it will be validated and compared to the known value.

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

### Parameters
- **public_key** (&AsymmetricPublicKey<V3>) - Required - The asymmetric public key (must be big-endian).
- **token** (&UntrustedToken<Public, V3>) - Required - The untrusted token to verify.
- **footer** (Option<&[u8]>) - Optional - An optional footer to validate against.
- **implicit_assert** (Option<&[u8]>) - Optional - An optional implicit assertion.

### Returns
- **Result<TrustedToken, Error>** - Returns a TrustedToken on success, or an error.
```

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

### Footer methods

Source: https://docs.rs/pasetors/0.8.0/pasetors/footer/struct.Footer.html

Methods for creating, modifying, and parsing footer claims.

```rust
pub fn new() -> Self
pub fn max_keys(&mut self, max_keys: usize)
pub fn max_len(&mut self, max_len: usize)
pub fn add_additional(&mut self, claim: &str, value: &str) -> Result<(), Error>
pub fn contains_claim(&self, claim: &str) -> bool
pub fn get_claim(&self, claim: &str) -> Option<&Value>
pub fn key_id(&mut self, id: &Id)
pub fn parse_bytes(&mut self, bytes: &[u8]) -> Result<(), Error>
pub fn parse_string(&mut self, string: &str) -> Result<(), Error>
pub fn to_string(&self) -> Result<String, Error>
```

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

### Footer constants

Source: https://docs.rs/pasetors/0.8.0/pasetors/footer/struct.Footer.html

Configuration constants defining limits for footer validation.

```rust
pub const REGISTERED_CLAIMS: [&'static str; 2]
pub const DISALLOWED_FOOTER: [&'static str; 8]
pub const DEFAULT_MAX_KEYS: usize = 512
pub const DEFAULT_MAX_LEN: usize = 8192
pub const MAX_RECURSION_DEPTH: usize = 128
```

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

### AsymmetricSecretKey::from

Source: https://docs.rs/pasetors/0.8.0/pasetors/keys/struct.AsymmetricSecretKey.html

Creates a new AsymmetricSecretKey instance from a provided byte slice.

```APIDOC
## pub fn from(bytes: &[u8]) -> Result<Self, Error>

### Description
Creates a `AsymmetricSecretKey` from the provided `bytes`. Note that for versions V2 or V4, the function will panic if an all-zero secret seed is provided.

### Parameters
- **bytes** (&[u8]) - Required - The byte slice containing the secret key data.

### Returns
- **Result<Self, Error>** - Returns the initialized AsymmetricSecretKey or an Error if the input is invalid.
```

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

### PublicToken::verify

Source: https://docs.rs/pasetors/0.8.0/pasetors/version2/struct.PublicToken.html

Verifies a PASETO v2 public token using an asymmetric public key.

```APIDOC
## fn verify(public_key: &AsymmetricPublicKey<V2>, token: &UntrustedToken<Public, V2>, footer: Option<&[u8]>) -> Result<TrustedToken, Error>

### Description
Verifies a public token. If a footer is provided, it is validated and compared against the known value.

### Parameters
- **public_key** (&AsymmetricPublicKey<V2>) - Required - The public key used for verification.
- **token** (&UntrustedToken<Public, V2>) - Required - The token to verify.
- **footer** (Option<&[u8]>) - Optional - An optional footer to validate against the token.

### Returns
- **Result<TrustedToken, Error>** - Returns a TrustedToken on successful verification, or an error.
```

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

### LocalToken::encrypt

Source: https://docs.rs/pasetors/0.8.0/pasetors/version4/struct.LocalToken.html

Creates a new PASETO v4 local token using a symmetric key, message, optional footer, and optional implicit assertion.

```APIDOC
## pub fn encrypt(secret_key: &SymmetricKey<V4>, message: &[u8], footer: Option<&[u8]>, implicit_assert: Option<&[u8]>) -> Result<String, Error>

### Description
Encrypts a message into a PASETO v4 local token string.

### Parameters
- **secret_key** (&SymmetricKey<V4>) - Required - The symmetric key used for encryption.
- **message** (&[u8]) - Required - The plaintext message to encrypt.
- **footer** (Option<&[u8]>) - Optional - An optional footer to include in the token.
- **implicit_assert** (Option<&[u8]>) - Optional - An optional implicit assertion for the token.

### Returns
- **Result<String, Error>** - Returns the encrypted token string on success, or an error.
```

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

### verify

Source: https://docs.rs/pasetors/0.8.0/pasetors/public/index.html

Verifies a public token using the latest PASETO version (v4) and validates claims.

```APIDOC
## verify

### Description
Verify a public token using the latest PASETO version (v4). If verification passes, validate the claims according to the `validation_rules`.
```

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

### PublicToken::verify

Source: https://docs.rs/pasetors/0.8.0/pasetors/version4/struct.PublicToken.html

Verifies a PASETO v4 public token using an asymmetric public key.

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

### Description
Verifies a public token. If a footer is provided, it is validated and compared against the known value.

### Parameters
- **public_key** (&AsymmetricPublicKey<V4>) - Required - The public key used for verification.
- **token** (&UntrustedToken<Public, V4>) - Required - The token to verify.
- **footer** (Option<&[u8]>) - Optional - The expected footer to validate against.
- **implicit_assert** (Option<&[u8]>) - Optional - The implicit assertion to validate against.

### Returns
- **Result<TrustedToken, Error>** - Returns a TrustedToken on success, or an error if verification fails.
```

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

### pub fn verify

Source: https://docs.rs/pasetors/0.8.0/pasetors/public/fn.verify.html

Verifies a public token using the latest PASETO version (v4) and validates claims against provided rules.

```APIDOC
## pub fn verify

### Description
Verify a public token using the latest PASETO version (v4). If verification passes, validate the claims according to the `validation_rules`.

### Signature
```rust
pub fn verify(
    public_key: &AsymmetricPublicKey<V4>,
    token: &UntrustedToken<Public, V4>,
    validation_rules: &ClaimsValidationRules,
    footer: Option<&Footer>,
    implicit_assert: Option<&[u8]>
) -> Result<TrustedToken, Error>
```

### Parameters
- **public_key** (&AsymmetricPublicKey<V4>) - Required - The public key used for verification.
- **token** (&UntrustedToken<Public, V4>) - Required - The untrusted PASETO token to verify.
- **validation_rules** (&ClaimsValidationRules) - Required - Rules to validate the claims within the token.
- **footer** (Option<&Footer>) - Optional - An optional footer to verify.
- **implicit_assert** (Option<&[u8]>) - Optional - An optional implicit assertion byte slice.

### Returns
- **Result<TrustedToken, Error>** - Returns a `TrustedToken` if verification and validation succeed, otherwise returns an `Error`.
```

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

### public::verify

Source: https://docs.rs/pasetors/0.8.0/pasetors/all.html

Verifies a public PASETO token.

```APIDOC
## public::verify

### Description
Verifies the signature of a public PASETO token using an asymmetric public key.

### Signature
`pub fn verify<K: AsRef<AsymmetricPublicKey>>(key: &K, token: &str, footer: Option<&Footer>) -> Result<Vec<u8>, Error>`
```

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

### UncompressedPublicKey Definition

Source: https://docs.rs/pasetors/0.8.0/pasetors/version3/struct.UncompressedPublicKey.html

The structure definition for UncompressedPublicKey.

```rust
pub struct UncompressedPublicKey(/* private fields */);
```

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

### Verify Public Token

Source: https://docs.rs/pasetors/0.8.0/pasetors/version3/struct.PublicToken.html

Verifies a public token using an asymmetric public key. The public key must be in big-endian format.

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

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

### Sign Public Token

Source: https://docs.rs/pasetors/0.8.0/pasetors/version3/struct.PublicToken.html

Creates a public token using an asymmetric secret key. The secret key must be in big-endian format.

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

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

### PublicToken Header Constant

Source: https://docs.rs/pasetors/0.8.0/pasetors/version3/struct.PublicToken.html

The header and purpose string for v3 public tokens.

```rust
pub const HEADER: &'static str = "v3.public."
```

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

### PublicToken::sign

Source: https://docs.rs/pasetors/0.8.0/pasetors/version3/struct.PublicToken.html

Creates a new PASETO v3 public token using the provided secret key, message, and optional footer and implicit assertion.

```APIDOC
## PublicToken::sign

### Description
Creates a public token. The secret_key must be in big-endian.

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

### Parameters
- **secret_key** (&AsymmetricSecretKey<V3>) - Required - The asymmetric secret key (must be big-endian).
- **message** (&[u8]) - Required - The message to sign.
- **footer** (Option<&[u8]>) - Optional - An optional footer for the token.
- **implicit_assert** (Option<&[u8]>) - Optional - An optional implicit assertion.

### Returns
- **Result<String, Error>** - Returns the signed token string on success, or an error.
```

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

### PublicToken::sign

Source: https://docs.rs/pasetors/0.8.0/pasetors/version2/struct.PublicToken.html

Creates a new PASETO v2 public token using an asymmetric secret key.

```APIDOC
## fn sign(secret_key: &AsymmetricSecretKey<V2>, message: &[u8], footer: Option<&[u8]>) -> Result<String, Error>

### Description
Creates a public token using the provided asymmetric secret key, message, and optional footer.

### Parameters
- **secret_key** (&AsymmetricSecretKey<V2>) - Required - The secret key used for signing.
- **message** (&[u8]) - Required - The message to be signed.
- **footer** (Option<&[u8]>) - Optional - An optional footer to include in the token.

### Returns
- **Result<String, Error>** - Returns the signed token string on success, or an error.
```

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

### PublicToken::sign

Source: https://docs.rs/pasetors/0.8.0/pasetors/version4/struct.PublicToken.html

Creates a new PASETO v4 public token using an asymmetric secret key.

```APIDOC
## fn sign(secret_key: &AsymmetricSecretKey<V4>, message: &[u8], footer: Option<&[u8]>, implicit_assert: Option<&[u8]>) -> Result<String, Error>

### Description
Creates a public token using the provided secret key, message, and optional footer and implicit assertion.

### Parameters
- **secret_key** (&AsymmetricSecretKey<V4>) - Required - The secret key used for signing.
- **message** (&[u8]) - Required - The message to be signed.
- **footer** (Option<&[u8]>) - Optional - An optional footer to include in the token.
- **implicit_assert** (Option<&[u8]>) - Optional - An optional implicit assertion for the token.

### Returns
- **Result<String, Error>** - Returns the signed token string on success, or an error.
```

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

### local::encrypt

Source: https://docs.rs/pasetors/0.8.0/pasetors/all.html

Encrypts data into a local PASETO token.

```APIDOC
## local::encrypt

### Description
Encrypts a payload into a local PASETO token using a symmetric key.

### Signature
`pub fn encrypt<K: AsRef<SymmetricKey>>(key: &K, payload: &[u8], footer: Option<&Footer>) -> Result<String, Error>`
```

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

### public::sign

Source: https://docs.rs/pasetors/0.8.0/pasetors/all.html

Signs a payload to create a public PASETO token.

```APIDOC
## public::sign

### Description
Signs a payload using an asymmetric secret key to produce a public PASETO token.

### Signature
`pub fn sign<K: AsRef<AsymmetricSecretKey>>(key: &K, payload: &[u8], footer: Option<&Footer>) -> Result<String, Error>`
```

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

### LocalToken::decrypt

Source: https://docs.rs/pasetors/0.8.0/pasetors/version2/struct.LocalToken.html

Verifies and decrypts a PASETO v2 local token.

```APIDOC
## pub fn decrypt(secret_key: &SymmetricKey<V2>, token: &UntrustedToken<Local, V2>, footer: Option<&[u8]>) -> Result<TrustedToken, Error>

### Description
Verifies and decrypts a local token. If a footer is provided, it is validated and compared against the token's footer.

### Parameters
- **secret_key** (&SymmetricKey<V2>) - Required - The symmetric key used for decryption.
- **token** (&UntrustedToken<Local, V2>) - Required - The untrusted token to decrypt.
- **footer** (Option<&[u8]>) - Optional - An optional footer to validate against the token.
```

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

### SymmetricKey Struct Definition

Source: https://docs.rs/pasetors/0.8.0/pasetors/keys/struct.SymmetricKey.html

The core structure definition for SymmetricKey.

```rust
pub struct SymmetricKey<V> { /* private fields */ }
```

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

### decrypt

Source: https://docs.rs/pasetors/0.8.0/pasetors/local/index.html

Verifies a local PASETO token using version 4 and validates claims.

```APIDOC
## decrypt

### Description
Verify a local token using the latest PASETO version (v4). If verification passes, validate the claims according to the `validation_rules`.
```

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

### PublicToken Struct Definition

Source: https://docs.rs/pasetors/0.8.0/pasetors/version3/struct.PublicToken.html

The base structure for PASETO v3 public tokens.

```rust
pub struct PublicToken;
```

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

### local::decrypt

Source: https://docs.rs/pasetors/0.8.0/pasetors/all.html

Decrypts a local PASETO token.

```APIDOC
## local::decrypt

### Description
Decrypts a local PASETO token using a symmetric key.

### Signature
`pub fn decrypt<K: AsRef<SymmetricKey>>(key: &K, token: &str, footer: Option<&Footer>) -> Result<Vec<u8>, Error>`
```

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

### Encrypt function signature

Source: https://docs.rs/pasetors/0.8.0/pasetors/local/fn.encrypt.html

The function signature for creating a local token using PASETO v4. Requires the std and v4 crate features.

```rust
pub fn encrypt(
    secret_key: &SymmetricKey<V4>,
    message: &Claims,
    footer: Option<&Footer>,
    implicit_assert: Option<&[u8]>,
) -> Result<String, Error>
```

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

### LocalToken::decrypt

Source: https://docs.rs/pasetors/0.8.0/pasetors/version4/struct.LocalToken.html

Verifies and decrypts a PASETO v4 local token, optionally validating against a provided footer and implicit assertion.

```APIDOC
## pub fn decrypt(secret_key: &SymmetricKey<V4>, token: &UntrustedToken<Local, V4>, footer: Option<&[u8]>, implicit_assert: Option<&[u8]>) -> Result<TrustedToken, Error>

### Description
Decrypts and verifies the integrity of a PASETO v4 local token. If a footer is provided, it is validated against the token's footer.

### Parameters
- **secret_key** (&SymmetricKey<V4>) - Required - The symmetric key used for decryption.
- **token** (&UntrustedToken<Local, V4>) - Required - The token to decrypt.
- **footer** (Option<&[u8]>) - Optional - The expected footer to validate against.
- **implicit_assert** (Option<&[u8]>) - Optional - The implicit assertion used during token creation.

### Returns
- **Result<TrustedToken, Error>** - Returns a TrustedToken on success, or an error if decryption or validation fails.
```

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

### Footer struct definition

Source: https://docs.rs/pasetors/0.8.0/pasetors/footer/struct.Footer.html

The primary structure for managing footer claims.

```rust
pub struct Footer { /* private fields */ }
```

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

### sign function signature

Source: https://docs.rs/pasetors/0.8.0/pasetors/public/fn.sign.html

The function signature for creating a v4 PASETO token. Requires the std and v4 crate features.

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

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

### AsymmetricSecretKey::as_bytes

Source: https://docs.rs/pasetors/0.8.0/pasetors/keys/struct.AsymmetricSecretKey.html

Retrieves the byte representation of the AsymmetricSecretKey.

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

### Description
Returns the underlying data of the AsymmetricSecretKey as a byte-slice.

### Returns
- **&[u8]** - A reference to the byte slice representing the key.
```

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

### Create non-expiring tokens in Rust

Source: https://docs.rs/pasetors/0.8.0/pasetors/index.html

Configures claims to be non-expiring and updates validation rules to permit them.

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

// Non-expiring tokens
let mut claims = Claims::new()?;
claims.add_additional("data", "A public, signed message")?;
claims.non_expiring();
// Now claims can be validated as non-expiring when we define the validation rule as:
let mut validation_rules = ClaimsValidationRules::new();
validation_rules.allow_non_expiring();
```

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

### Encrypt a local token

Source: https://docs.rs/pasetors/0.8.0/pasetors/version4/struct.LocalToken.html

Encrypts a message into a local token using a symmetric key.

```rust
pub fn encrypt( secret_key: &SymmetricKey<V4>, message: &[u8], footer: Option<&[u8]>, implicit_assert: Option<&[u8]>, ) -> Result<String, Error>
```

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

### Define LocalToken HEADER constant

Source: https://docs.rs/pasetors/0.8.0/pasetors/version4/struct.LocalToken.html

The constant representing the header and purpose for v4 local tokens.

```rust
pub const HEADER: &'static str = "v4.local."
```

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

### Define the FormatAsPaserk trait

Source: https://docs.rs/pasetors/0.8.0/pasetors/paserk/trait.FormatAsPaserk.html

The trait requires implementing the fmt method to write the PASERK representation to a provided writer.

```rust
pub trait FormatAsPaserk {
    // Required method
    fn fmt(&self, write: &mut dyn Write) -> Result;
}
```

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

### Define LocalToken struct

Source: https://docs.rs/pasetors/0.8.0/pasetors/version4/struct.LocalToken.html

The definition of the LocalToken struct.

```rust
pub struct LocalToken;
```

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

### AsymmetricKeyPair Struct Definition

Source: https://docs.rs/pasetors/0.8.0/pasetors/keys/struct.AsymmetricKeyPair.html

The core structure definition for holding public and secret asymmetric keys.

```rust
pub struct AsymmetricKeyPair<V> {
    pub public: AsymmetricPublicKey<V>,
    pub secret: AsymmetricSecretKey<V>,
}
```

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

### Re-export Local and Public Token Types

Source: https://docs.rs/pasetors/0.8.0/pasetors/index.html

Exposes the Local and Public token types from the token module for direct access.

```rust
pub use token::Local;
```

```rust
pub use token::Public;
```

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

### Decrypt a local token

Source: https://docs.rs/pasetors/0.8.0/pasetors/version4/struct.LocalToken.html

Verifies and decrypts a local token, optionally validating the footer.

```rust
pub fn decrypt( secret_key: &SymmetricKey<V4>, token: &UntrustedToken<Local, V4>, footer: Option<&[u8]>, implicit_assert: Option<&[u8]>, ) -> Result<TrustedToken, Error>
```

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

### TrustedToken Struct Definition

Source: https://docs.rs/pasetors/0.8.0/pasetors/token/struct.TrustedToken.html

The internal structure definition for TrustedToken.

```rust
pub struct TrustedToken { /* private fields */ }
```

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

### Decrypt function signature for PASETO v4

Source: https://docs.rs/pasetors/0.8.0/pasetors/local/fn.decrypt.html

This function requires the std and v4 crate features to be enabled. It validates claims based on the provided validation rules.

```rust
pub fn decrypt(
    secret_key: &SymmetricKey<V4>,
    token: &UntrustedToken<Local, V4>,
    validation_rules: &ClaimsValidationRules,
    footer: Option<&Footer>,
    implicit_assert: Option<&[u8]>,
) -> Result<TrustedToken, Error>
```

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

### Define V2 Struct

Source: https://docs.rs/pasetors/0.8.0/pasetors/version2/struct.V2.html

The V2 struct definition used for version 2 PASETO operations.

```rust
pub struct V2;
```

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

### Define V4 struct

Source: https://docs.rs/pasetors/0.8.0/pasetors/version4/struct.V4.html

The primary definition of the V4 struct used for version 4 PASETO operations.

```rust
pub struct V4;
```

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

### ClaimsValidationRules API

Source: https://docs.rs/pasetors/0.8.0/pasetors/claims/struct.ClaimsValidationRules.html

Methods for configuring and executing validation rules on a set of claims.

```APIDOC
## ClaimsValidationRules

### new()
Creates a new `ClaimsValidationRules` instance with default validation for `iat`, `nbf`, and `exp` enabled.

### disable_valid_at()
Disables the validation of `iat` and `nbf` claims.

### allow_non_expiring()
Configures the validator to allow tokens that do not contain an `exp` claim.

### validate_issuer_with(valid_issuer: &str)
Sets the expected issuer claim value for validation.

### validate_subject_with(valid_subject: &str)
Sets the expected subject claim value for validation.

### validate_audience_with(valid_audience: &str)
Sets the expected audience claim value for validation.

### validate_token_identifier_with(valid_token_identifier: &str)
Sets the expected token identifier (jti) claim value for validation.

### validate_claims(claims: &Claims) -> Result<(), Error>
Validates the provided `Claims` object against the configured rules. Returns an error if any validation rule is violated.
```

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

### Generate Trait Definition

Source: https://docs.rs/pasetors/0.8.0/pasetors/keys/trait.Generate.html

The core trait definition requiring a generate method that returns a Result containing the generated type or an Error.

```rust
pub trait Generate<T, V: Version> {
    // Required method
    fn generate() -> Result<T, Error>;
}
```

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

### AsymmetricSecretKey Struct Definition

Source: https://docs.rs/pasetors/0.8.0/pasetors/keys/struct.AsymmetricSecretKey.html

The internal structure of AsymmetricSecretKey is private and parameterized by a version V.

```rust
pub struct AsymmetricSecretKey<V> { /* private fields */ }
```

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

### Define ClaimsValidationRules structure

Source: https://docs.rs/pasetors/0.8.0/pasetors/claims/struct.ClaimsValidationRules.html

The definition of the ClaimsValidationRules struct.

```rust
pub struct ClaimsValidationRules { /* private fields */ }
```

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

### ClaimValidationError Enum Definition

Source: https://docs.rs/pasetors/0.8.0/pasetors/errors/enum.ClaimValidationError.html

The definition of the ClaimValidationError enum, listing all available error variants for claim validation.

```rust
pub enum ClaimValidationError {
Show 20 variants    Aud,
    Exp,
    Iat,
    Iss,
    Jti,
    Nbf,
    Sub,
    NoAud,
    NoExp,
    NoIat,
    NoIss,
    NoJti,
    NoNbf,
    NoSub,
    NoStrExp,
    NoStrIat,
    NoStrNbf,
    ParseExp,
    ParseIat,
    ParseNbf,
}
```

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

### Define Error Enum

Source: https://docs.rs/pasetors/0.8.0/pasetors/errors/enum.Error.html

The Error enum contains variants for various failure states encountered during token processing.

```rust
pub enum Error {
Show 18 variants    TokenFormat,
    Base64,
    TokenValidation,
    Key,
    Encryption,
    Csprng,
    LossyConversion,
    EmptyPayload,
    InvalidClaim,
    ClaimValidation(ClaimValidationError),
    ClaimInvalidUtf8,
    ClaimInvalidJson,
    PaserkParsing,
    Signing,
    PublicKeyConversion,
    KeyGeneration,
    PayloadInvalidUtf8,
    FooterParsing,
}
```

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

### Disable iat and nbf validation in Rust

Source: https://docs.rs/pasetors/0.8.0/pasetors/index.html

Disables the automatic validation of issued-at and not-before claims within the validation rules.

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

// Standard claims with default `iat`, `nbf` and `exp` present
let claims = Claims::new()?;
// Skipping validation of `iat` and `nbf` claims (still checking expiry unless specifically disabled as above),
// that _may_ be present in payload claims:
let mut validation_rules = ClaimsValidationRules::new();
validation_rules.disable_valid_at();
```
Tokens:
Raw