AWS LC RS

https://docs.rs/aws-lc-rs/latest/
Admin
AWS LC RS is a ring-compatible cryptographic library that provides FIPS-validated cryptography using...
Tokens:576,114
Snippets:4,750
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### RSA Signature Example

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/signature.rs.html

Example of reading RSA keys from files and performing a sign and verify operation.

```rust
    let mut file = std::fs::File::open(path).map_err(|e| MyError::IO(e))?;
    let mut contents: Vec<u8> = Vec::new();
    file.read_to_end(&mut contents)
        .map_err(|e| MyError::IO(e))?;
    Ok(contents)
}

fn main() {
#   if !cfg!(target_arch = "wasm32") {
    let private_key_path =
        std::path::Path::new("tests/data/signature_rsa_example_private_key.der");
    let public_key_path =
        std::path::Path::new("tests/data/signature_rsa_example_public_key.der");
    sign_and_verify_rsa(&private_key_path, &public_key_path).unwrap()
#   }
}
```

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

### PQDSA Deterministic Seed Test Setup

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/pqdsa/key_pair.rs.html?search=u32+-%3E+bool

Partial test setup for deterministic key generation from a seed.

```rust
    #[test]
    fn test_from_seed_deterministic() {
        for &alg in TEST_ALGORITHMS {
            let seed = [42u8; 32];
```

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

### Nonce Unit Test

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/aead/nonce.rs.html?search=u32+-%3E+bool

Example demonstrating the creation of a Nonce from a byte array.

```rust
#[test]
fn test_nonce_from_byte_array() {
    use crate::aead::nonce::IV_LEN;
    use crate::aead::Nonce;
    let iv: [u8; IV_LEN] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16];
    let nonce = Nonce::from(&iv);

    assert_eq!(&[1u8, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12], nonce.as_ref());
}
```

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

### PqdsaKeyPair Seed and Roundtrip Testing

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/pqdsa/key_pair.rs.html?search=

Examples demonstrating key generation from seeds, PKCS#8 roundtrips, and raw private key handling.

```rust
let kp1 = PqdsaKeyPair::from_seed(alg, &seed).unwrap();
let kp2 = PqdsaKeyPair::from_seed(alg, &seed).unwrap();
assert_eq!(kp1.public_key().as_ref(), kp2.public_key().as_ref());
```

```rust
use crate::error::KeyRejected;
for &alg in TEST_ALGORITHMS {
    assert_eq!(
        PqdsaKeyPair::from_seed(alg, &[0u8; 31]).err(),
        Some(KeyRejected::too_small())
    );
    assert_eq!(
        PqdsaKeyPair::from_seed(alg, &[0u8; 33]).err(),
        Some(KeyRejected::too_large())
    );
    assert_eq!(
        PqdsaKeyPair::from_seed(alg, &[]).err(),
        Some(KeyRejected::too_small())
    );
}
```

```rust
for &alg in TEST_ALGORITHMS {
    let kp1 = PqdsaKeyPair::from_seed(alg, &[1u8; 32]).unwrap();
    let kp2 = PqdsaKeyPair::from_seed(alg, &[2u8; 32]).unwrap();
    assert_ne!(kp1.public_key().as_ref(), kp2.public_key().as_ref());
}
```

```rust
use crate::encoding::AsRawBytes;
for &alg in TEST_ALGORITHMS {
    let seed = [55u8; 32];
    let kp = PqdsaKeyPair::from_seed(alg, &seed).unwrap();
    let raw_bytes = kp.private_key().as_raw_bytes().unwrap();
    let kp2 = PqdsaKeyPair::from_raw_private_key(alg, raw_bytes.as_ref()).unwrap();
    assert_eq!(kp.public_key().as_ref(), kp2.public_key().as_ref());
}
```

```rust
for &alg in TEST_ALGORITHMS {
    let seed = [77u8; 32];
    let kp = PqdsaKeyPair::from_seed(alg, &seed).unwrap();
    let pkcs8 = kp.to_pkcs8().unwrap();
    let kp2 = PqdsaKeyPair::from_pkcs8(alg, pkcs8.as_ref()).unwrap();
    assert_eq!(kp.public_key().as_ref(), kp2.public_key().as_ref());
}
```

```rust
let seed = [42u8; 32];
let kp_44 = PqdsaKeyPair::from_seed(&ML_DSA_44_SIGNING, &seed).unwrap();
let kp_65 = PqdsaKeyPair::from_seed(&ML_DSA_65_SIGNING, &seed).unwrap();
let kp_87 = PqdsaKeyPair::from_seed(&ML_DSA_87_SIGNING, &seed).unwrap();
assert_ne!(
    kp_44.public_key().as_ref().len(),
    kp_65.public_key().as_ref().len()
);
assert_ne!(
    kp_65.public_key().as_ref().len(),
    kp_87.public_key().as_ref().len()
);
```

```rust
for &alg in TEST_ALGORITHMS {
    assert!(PqdsaKeyPair::from_raw_private_key(alg, &[7u8; 32]).is_err());
}
```

```rust
for &alg in TEST_ALGORITHMS {
    let kp = PqdsaKeyPair::from_seed(alg, &[3u8; 32]).unwrap();
    let pkcs8 = kp.to_pkcs8().unwrap();
    let raw_expanded = kp.private_key().as_raw_bytes().unwrap();
    assert!(
        pkcs8.as_ref().len() < raw_expanded.as_ref().len(),
        "seed-form pkcs8 ({}) should be smaller than expanded key ({})",
        pkcs8.as_ref().len(),
        raw_expanded.as_ref().len(),
    );
    assert!(
        pkcs8.as_ref().len() < 128,
        "seed-form pkcs8 should be compact, got {}",
        pkcs8.as_ref().len(),
    );
}
```

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

### Example Test Data File Format

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/test.rs.html

A sample input file format for the testing framework, demonstrating comments and key-value pairs for HMAC test cases.

```text
# This is a comment.

HMAC = SHA1
Input = "My test data"
Key = ""
Output = 61afdecb95429ef494d61fdee15990cabf0826fc

HMAC = SHA256
Input = "Sample message for keylen<blocklen"
Key = 000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F
Output = A28CF43130EE696A98F14A37678B56BCFCBDD9E5CF69717FECF5480F0EBDF790
```

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

### ML-DSA Signing and Verification

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/unstable/signature.rs.html?search=std%3A%3Avec

Example demonstrating how to generate a key pair, sign a message, and verify the signature using the ML-DSA-44 algorithm.

```APIDOC
## ML-DSA Signing and Verification

### Description
This example shows the workflow for using the unstable PQDSA APIs to sign a message and verify it using the ML-DSA-44 algorithm.

### Usage
```rust
use aws_lc_rs::encoding::AsDer;
use aws_lc_rs::signature::{KeyPair, UnparsedPublicKey};
use aws_lc_rs::unstable::signature::{PqdsaKeyPair, ML_DSA_44_SIGNING, ML_DSA_44};

// 1. Generate a key pair
let signing_alg = &ML_DSA_44_SIGNING;
let key_pair = PqdsaKeyPair::generate(signing_alg)?;

// 2. Sign a message
const MESSAGE: &'static [u8] = b"hello, world";
let mut signature = vec![0; signing_alg.signature_len()];
let signature_len = key_pair.sign(MESSAGE, &mut signature)?;

// 3. Verify the signature
let public_key_bytes = key_pair.public_key().as_der()?;
let public_key = UnparsedPublicKey::new(&ML_DSA_44, public_key_bytes.as_ref());
assert!(public_key.verify(MESSAGE, &signature).is_ok());
```
```

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

### HKDF Key Derivation Example

Source: https://docs.rs/aws-lc-rs/latest/aws_lc_rs/hkdf/index.html

Demonstrates extracting a pseudo-random key from input material and expanding it into HMAC and AEAD keys.

```rust
use aws_lc_rs::{aead, hkdf, hmac, rand};

// Generate a (non-secret) salt value
let mut salt_bytes = [0u8; 32];
rand::fill(&mut salt_bytes).unwrap();

// Extract pseudo-random key from secret keying materials
let salt = hkdf::Salt::new(hkdf::HKDF_SHA256, &salt_bytes);
let pseudo_random_key = salt.extract(b"secret input keying material");

// Derive HMAC key
let hmac_key_material = pseudo_random_key
    .expand(
        &[b"hmac contextual info"],
        hkdf::HKDF_SHA256.hmac_algorithm(),
    )
    .unwrap();
let hmac_key = hmac::Key::from(hmac_key_material);

// Derive UnboundKey for AES-128-GCM
let aes_keying_material = pseudo_random_key
    .expand(&[b"aes contextual info"], &aead::AES_128_GCM)
    .unwrap();
let aead_unbound_key = aead::UnboundKey::from(aes_keying_material);
```

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

### KEM Usage Example

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/kem.rs.html?search=

Demonstrates the full lifecycle of a KEM operation using ML-KEM-512, including key generation, encapsulation, and decapsulation.

```APIDOC
## KEM Operation Workflow

### Description
This example demonstrates how to perform a key exchange using the ML-KEM-512 algorithm. It covers generating a decapsulation key, deriving an encapsulation key, encapsulating a secret, and decapsulating the resulting ciphertext.

### Usage
```rust
use aws_lc_rs::{
    kem::{Ciphertext, DecapsulationKey, EncapsulationKey},
    kem::{ML_KEM_512}
};

// Alice generates their (private) decapsulation key.
let decapsulation_key = DecapsulationKey::generate(&ML_KEM_512)?;

// Alice computes the (public) encapsulation key.
let encapsulation_key = decapsulation_key.encapsulation_key()?;
let encapsulation_key_bytes = encapsulation_key.key_bytes()?;

// Bob constructs the (public) encapsulation key from the key bytes provided by Alice.
let retrieved_encapsulation_key = EncapsulationKey::new(&ML_KEM_512, encapsulation_key_bytes.as_ref())?;

// Bob executes the encapsulation algorithm to produce their copy of the secret, and associated ciphertext.
let (ciphertext, bob_secret) = retrieved_encapsulation_key.encapsulate()?;

// Alice runs decapsulation to derive their copy of the secret.
let alice_secret = decapsulation_key.decapsulate(Ciphertext::from(ciphertext.as_ref()))?;

// Alice and Bob have now arrived to the same secret
assert_eq!(alice_secret.as_ref(), bob_secret.as_ref());
```
```

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

### Counter32 Nonce Sequence Tests

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/aead/nonce_sequence/counter32.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Examples demonstrating the initialization, advancement, and limit enforcement of the Counter32 nonce sequence.

```rust
        let nonce = cns.advance().unwrap();
        let nonce = nonce.as_ref();
        assert_eq!(2, cns.generated());
        assert_eq!(9, cns.counter());
        assert_eq!(
            [0xA1, 0xB2, 0xC3, 0xD4, 0xA2, 0xB3, 0xC4, 0xD5],
            cns.identifier()
        );
        assert_eq!(
            nonce,
            &[0xA1, 0xB2, 0xC3, 0xD4, 0xA2, 0xB3, 0xC4, 0xD5, 0, 0, 0, 8]
        );
    }

    #[test]
    fn test_counter32() {
        let mut cns = Counter32Builder::new().counter(0x_4CB0_16EA_u32).build();
        let nonce = cns.advance().unwrap();
        let nonce = nonce.as_ref();
        assert_eq!(nonce, &[0, 0, 0, 0, 0, 0, 0, 0, 0x4C, 0xB0, 0x16, 0xEA]);
        let nonce = cns.advance().unwrap();
        let nonce = nonce.as_ref();
        assert_eq!(nonce, &[0, 0, 0, 0, 0, 0, 0, 0, 0x4C, 0xB0, 0x16, 0xEB]);
    }

    #[test]
    fn test_counter32_int_id() {
        let mut cns = Counter32Builder::new()
            .counter(0x_6A_u32)
            .identifier(0x_7B_u64.to_be_bytes())
            .build();
        let nonce = cns.advance().unwrap();
        let nonce = nonce.as_ref();
        assert_eq!(nonce, &[0, 0, 0, 0, 0, 0, 0, 0x7B, 0, 0, 0, 0x6A]);
        let nonce = cns.advance().unwrap();
        let nonce = nonce.as_ref();
        assert_eq!(nonce, &[0, 0, 0, 0, 0, 0, 0, 0x7B, 0, 0, 0, 0x6B]);
    }

    #[test]
    fn test_counter32_limit() {
        let mut cns = Counter32Builder::new().limit(1).build();
        assert_eq!(1, cns.limit());
        assert_eq!(0, cns.generated());
        let _nonce = cns.advance().unwrap();
        assert_eq!(1, cns.generated());
        assert!(cns.advance().is_err());
    }
}
```

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

### Parsing and Verifying RSA Public Key

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/rsa/key.rs.html?search=u32+-%3E+bool

Example of converting raw RSA components into a ParsedPublicKey to verify a signature.

```rust
use aws_lc_rs::signature::{self, RsaPublicKeyComponents};

# fn main() -> Result<(), Box<dyn std::error::Error>> {
# fn modulus_bytes() -> &'static [u8] { &[] }
# fn exponent_bytes() -> &'static [u8] { &[] }
# fn signature_bytes() -> &'static [u8] { &[] }
// Public key components (big-endian, no leading zeros) received
// out-of-band from a peer.
let components = RsaPublicKeyComponents {
    n: modulus_bytes(),
    e: exponent_bytes(),
};
let parsed =
    components.to_parsed_public_key(&signature::RSA_PKCS1_2048_8192_SHA256)?;
parsed.verify_sig(b"hello, world", signature_bytes())?;
# Ok(()) }
```

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

### KEM Usage Example

Source: https://docs.rs/aws-lc-rs/latest/aws_lc_rs/kem/index.html

Demonstrates the workflow for generating a decapsulation key, deriving an encapsulation key, encapsulating a secret, and decapsulating it to arrive at a shared secret.

```APIDOC
## KEM Workflow

### Description
This example shows how to perform a key exchange using the ML-KEM-512 algorithm. Alice generates a key pair, Bob uses the public encapsulation key to encapsulate a secret, and Alice decapsulates the resulting ciphertext to recover the shared secret.

### Usage
1. Generate `DecapsulationKey` using `DecapsulationKey::generate(&ML_KEM_512)`.
2. Derive `EncapsulationKey` from the decapsulation key.
3. Bob uses `EncapsulationKey::new` and `encapsulate()` to produce a `Ciphertext` and a `SharedSecret`.
4. Alice uses `DecapsulationKey::decapsulate` with the `Ciphertext` to recover the `SharedSecret`.
```

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

### HKDF Key Derivation Example

Source: https://docs.rs/aws-lc-rs/latest/aws_lc_rs/hkdf/index.html?search=

Demonstrates how to use the hkdf module to extract a pseudorandom key from secret material and expand it into keys for HMAC and AEAD operations.

```APIDOC
## Rust SDK Usage: HKDF Key Derivation

### Description
This example shows the standard workflow for HKDF: creating a salt, extracting a pseudorandom key (PRK) from secret input, and expanding that PRK into specific keying material for cryptographic primitives.

### Code Example
```rust
use aws_lc_rs::{aead, hkdf, hmac, rand};

// Generate a (non-secret) salt value
let mut salt_bytes = [0u8; 32];
rand::fill(&mut salt_bytes).unwrap();

// Extract pseudo-random key from secret keying materials
let salt = hkdf::Salt::new(hkdf::HKDF_SHA256, &salt_bytes);
let pseudo_random_key = salt.extract(b"secret input keying material");

// Derive HMAC key
let hmac_key_material = pseudo_random_key
    .expand(
        &[b"hmac contextual info"],
        hkdf::HKDF_SHA256.hmac_algorithm(),
    )
    .unwrap();
let hmac_key = hmac::Key::from(hmac_key_material);

// Derive UnboundKey for AES-128-GCM
let aes_keying_material = pseudo_random_key
    .expand(&[b"aes contextual info"], &aead::AES_128_GCM)
    .unwrap();
let aead_unbound_key = aead::UnboundKey::from(aes_keying_material);
```
```

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

### OpeningKey::new

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/aead/chacha20_poly1305_openssh.rs.html?search=u32+-%3E+bool

Constructs a new OpeningKey instance.

```APIDOC
## OpeningKey::new(key_material: &[u8; KEY_LEN]) -> OpeningKey

### Description
Constructs a new `OpeningKey` for authenticating and decrypting SSH packets.

### Parameters
- **key_material** (&[u8; KEY_LEN]) - Required - The key material used to derive the internal keys.
```

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

### Counter32Builder::counter

Source: https://docs.rs/aws-lc-rs/latest/aws_lc_rs/aead/nonce_sequence/struct.Counter32Builder.html?search=

Sets the starting counter value.

```APIDOC
## pub fn counter(self, counter: u32) -> Counter32Builder

### Description
Sets the starting counter value for the `Counter32`.

### Parameters
- **counter** (u32) - The initial counter value.
```

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

### OpeningKey::new

Source: https://docs.rs/aws-lc-rs/latest/aws_lc_rs/aead/chacha20_poly1305_openssh/struct.OpeningKey.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Constructs a new OpeningKey instance using the provided 64-byte key material.

```APIDOC
## pub fn new(key_material: &[u8; 64]) -> OpeningKey

### Description
Constructs a new `OpeningKey` from the provided 64-byte key material.

### Parameters
- **key_material** (&[u8; 64]) - Required - The 64-byte key material used to initialize the opening key.
```

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

### CMAC Key Initialization and Signing

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/cmac.rs.html?search=

Demonstrates creating keys for different algorithms and signing data.

```rust
#[test]
    fn cmac_key_new_test() {
        // Test Key::new with explicit key values
        let key_128 = [0u8; 16];
        let key_192 = [0u8; 24];
        let key_256 = [0u8; 32];
        let key_3des = [0u8; 24];

        let k1 = Key::new(AES_128, &key_128).unwrap();
        let k2 = Key::new(AES_192, &key_192).unwrap();
        let k3 = Key::new(AES_256, &key_256).unwrap();
        let k4 = Key::new(DES_EDE3_FOR_LEGACY_USE_ONLY, &key_3des).unwrap();

        let data = b"test message";

        // All should produce valid tags
        let _ = sign(&k1, data).unwrap();
        let _ = sign(&k2, data).unwrap();
        let _ = sign(&k3, data).unwrap();
        let _ = sign(&k4, data).unwrap();
    }
```

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

### Get Signing Algorithm

Source: https://docs.rs/aws-lc-rs/latest/aws_lc_rs/signature/struct.EcdsaKeyPair.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves the algorithm used to create the key pair.

```rust
pub fn algorithm(&self) -> &'static EcdsaSigningAlgorithm
```

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

### Using the multi-part API

Source: https://docs.rs/aws-lc-rs/latest/aws_lc_rs/cmac/index.html?search=

Demonstrates signing fragmented data using the Context API and verifying the result.

```rust
use aws_lc_rs::{cmac, rand};

let parts = ["hello", ", ", "world"];

// The sender generates a secure key value and signs the message with it.
// Note that in a real protocol, a key agreement protocol would be used to
// derive `key_value`.
let rng = rand::SystemRandom::new();
let key_value: [u8; 32] = rand::generate(&rng)?.expose();

let s_key = cmac::Key::new(cmac::AES_256, key_value.as_ref())?;
let mut s_ctx = cmac::Context::with_key(&s_key);
for part in &parts {
    s_ctx.update(part.as_bytes())?;
}
let tag = s_ctx.sign()?;

// The receiver (somehow!) knows the key value, and uses it to verify the
// integrity of the message.
let v_key = cmac::Key::new(cmac::AES_256, key_value.as_ref())?;
let mut msg = Vec::<u8>::new();
for part in &parts {
    msg.extend(part.as_bytes());
}
cmac::verify(&v_key, &msg.as_ref(), tag.as_ref())?;
```

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

### Streaming Cipher Test Invocation

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/cipher/streaming.rs.html

Example usage of the streaming_cipher_kat macro to test AES-128-CTR.

```rust
streaming_cipher_kat!(
        test_iv_aes_128_ctr_16_bytes,
        &AES_128,
        OperatingMode::CTR,
        "000102030405060708090a0b0c0d0e0f",
        "00000000000000000000000000000000",
        "00112233445566778899aabbccddeeff",
        "c6b01904c3da3df5e7d62bd96d153686",
        2,
        9
    );
```

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

### Initialize and Dump Errors

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/lib.rs.html

Demonstrates the initialization of the library and the unsafe dumping of internal errors.

```rust
#[test]
    fn test_init() {
        init();
    }

    #[test]
    fn test_dump() {
        unsafe {
            dump_error();
        }
    }
```

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

### AEAD Decryption and Verification

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/aead/tls.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example of opening a cipher text and verifying the resulting plaintext.

```rust
opening_key
    .open_within(
        Nonce::try_assume_unique_for_key(nonce_bytes).unwrap(),
        Aad::empty(),
        &mut offset_cipher_text,
        4..)
    .unwrap();
assert_eq!(plaintext, offset_cipher_text[..plaintext.len()]);
```

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

### Using the multi-part API

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/cmac.rs.html

Demonstrates using the Context API to sign data provided in multiple parts.

```rust
use aws_lc_rs::{cmac, rand};

let parts = ["hello", ", ", "world"];

// The sender generates a secure key value and signs the message with it.
// Note that in a real protocol, a key agreement protocol would be used to
// derive `key_value`.
let rng = rand::SystemRandom::new();
let key_value: [u8; 32] = rand::generate(&rng)?.expose();

let s_key = cmac::Key::new(cmac::AES_256, key_value.as_ref())?;
let mut s_ctx = cmac::Context::with_key(&s_key);
for part in &parts {
    s_ctx.update(part.as_bytes())?;
}
let tag = s_ctx.sign()?;

// The receiver (somehow!) knows the key value, and uses it to verify the
// integrity of the message.
let v_key = cmac::Key::new(cmac::AES_256, key_value.as_ref())?;
let mut msg = Vec::<u8>::new();
for part in &parts {
    msg.extend(part.as_bytes());
}
cmac::verify(&v_key, &msg.as_ref(), tag.as_ref())?;

# Ok::<(), aws_lc_rs::error::Unspecified>(())
```

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

### StreamingEncryptingKey Initialization Logic

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/cipher/streaming.rs.html?search=

Constructor logic for StreamingEncryptingKey, including algorithm validation and context setup.

```rust
impl StreamingEncryptingKey {
    #[allow(clippy::needless_pass_by_value)]
    fn new(
        key: UnboundCipherKey,
        mode: OperatingMode,
        context: EncryptionContext,
    ) -> Result<Self, Unspecified> {
        let algorithm = key.algorithm();
        if !algorithm.supports_mode(mode) {
            return Err(Unspecified);
        }
        // The streaming path passes raw key bytes to the EVP API rather than
        // going through `SymmetricCipherKey` construction.  Validate
        // algorithm-specific key constraints (e.g. DES weak-key / K1!=K2
        // checks) that would otherwise be missed.
        key.validate_key_material()?;
        let mut cipher_ctx = LcPtr::new(unsafe { EVP_CIPHER_CTX_new() })?;
        let cipher = mode.evp_cipher(key.algorithm);
        let key_bytes = key.key_bytes.as_ref();
        if key_bytes.len()
            != <usize>::try_from(unsafe { EVP_CIPHER_key_length(cipher.as_const_ptr()) }).unwrap()
        {
            return Err(Unspecified);
        }

        match &context {
            ctx @ EncryptionContext::Iv128(..) => {
                let iv = <&[u8]>::try_from(ctx)?;
                debug_assert_eq!(
                    iv.len(),
                    <usize>::try_from(unsafe { EVP_CIPHER_iv_length(cipher.as_const_ptr()) })
```

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

### Sealed Trait Pattern

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/lib.rs.html?search=u32+-%3E+bool

Example of using a sealed trait to restrict implementation to internal modules.

```rust
//
// Usage:
// ```
// use crate::sealed;
//
// pub trait MyType: sealed::Sealed {
//     // [...]
// }
```

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

### Test Ed25519 Generation and Signing

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/ed25519.rs.html

Example test cases for generating keys and verifying signatures.

```rust
#[test]
    fn test_generate() {
        const MESSAGE: &[u8] = b"test message";
        let key_pair = Ed25519KeyPair::generate().unwrap();
        let public_key = key_pair.public_key();
        let signature = key_pair.sign(MESSAGE);
        let unparsed_public_key = UnparsedPublicKey::new(&ED25519, public_key.as_ref());
        unparsed_public_key
            .verify(MESSAGE, signature.as_ref())
            .unwrap();
    }

    #[test]
    fn test_generate_pkcs8() {
        let rng = SystemRandom::new();
        let document = Ed25519KeyPair::generate_pkcs8(&rng).unwrap();
```

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

### Sign and verify with RSA (PKCS#1 1.5)

Source: https://docs.rs/aws-lc-rs/latest/aws_lc_rs/signature/index.html?search=u32+-%3E+bool

Demonstrates loading an RSA key pair from DER files, signing a message with SHA256, and verifying the signature.

```rust
use aws_lc_rs::{rand, signature};

fn sign_and_verify_rsa(
    private_key_path: &std::path::Path,
    public_key_path: &std::path::Path,
) -> Result<(), MyError> {
    // Create an `RsaKeyPair` from the DER-encoded bytes. This example uses
    // a 2048-bit key, but larger keys are also supported.
    let private_key_der = read_file(private_key_path)?;
    let key_pair = signature::RsaKeyPair::from_der(&private_key_der)
        .map_err(|_| MyError::BadPrivateKey)?;

    // Sign the message "hello, world", using PKCS#1 v1.5 padding and the
    // SHA256 digest algorithm.
    const MESSAGE: &'static [u8] = b"hello, world";
    let rng = rand::SystemRandom::new();
    let mut signature = vec![0; key_pair.public_modulus_len()];
    key_pair
        .sign(&signature::RSA_PKCS1_SHA256, &rng, MESSAGE, &mut signature)
        .map_err(|_| MyError::OOM)?;

    // Verify the signature.
    let public_key = signature::UnparsedPublicKey::new(
        &signature::RSA_PKCS1_2048_8192_SHA256,
        read_file(public_key_path)?,
    );
    public_key
        .verify(MESSAGE, &signature)
        .map_err(|_| MyError::BadSignature)
}

#[derive(Debug)]
enum MyError {
    IO(std::io::Error),
    BadPrivateKey,
    OOM,
    BadSignature,
}

fn read_file(path: &std::path::Path) -> Result<Vec<u8>, MyError> {
    use std::io::Read;

    let mut file = std::fs::File::open(path).map_err(|e| MyError::IO(e))?;
    let mut contents: Vec<u8> = Vec::new();
    file.read_to_end(&mut contents)
        .map_err(|e| MyError::IO(e))?;
    Ok(contents)
}

fn main() {
    let private_key_path =
        std::path::Path::new("tests/data/signature_rsa_example_private_key.der");
    let public_key_path =
        std::path::Path::new("tests/data/signature_rsa_example_public_key.der");
    sign_and_verify_rsa(&private_key_path, &public_key_path).unwrap()
}
```

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

### Verifying RSA Signatures with PublicKeyComponents

Source: https://docs.rs/aws-lc-rs/latest/aws_lc_rs/rsa/struct.PublicKeyComponents.html

Demonstrates how to initialize PublicKeyComponents with raw bytes and use them to verify a signature.

```rust
use aws_lc_rs::signature::{self, RsaPublicKeyComponents};

// Public key components (big-endian, no leading zeros) received
// out-of-band from a peer.
let components = RsaPublicKeyComponents {
    n: modulus_bytes(),
    e: exponent_bytes(),
};
let parsed =
    components.to_parsed_public_key(&signature::RSA_PKCS1_2048_8192_SHA256)?;
parsed.verify_sig(b"hello, world", signature_bytes())?;
```

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

### AES-128 CTR Test Entry

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/cipher.rs.html?search=std%3A%3Avec

Example of a specific test case for AES-128 in CTR mode.

```rust
    #[test]
    fn test_aes_128_ctr() {
        let key = from_hex("000102030405060708090a0b0c0d0e0f").unwrap();
```

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

### Counter32 Test Case

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/aead/nonce_sequence/counter32.rs.html

Example test case demonstrating the usage of Counter32Builder and nonce advancement.

```rust
127mod tests {
128    use crate::aead::nonce_sequence::Counter32Builder;
129    use crate::aead::NonceSequence;
130
131    #[test]
132    fn test_counter32_identifier() {
133        let mut cns = Counter32Builder::default()
134            .identifier([0xA1, 0xB2, 0xC3, 0xD4, 0xA2, 0xB3, 0xC4, 0xD5])
135            .counter(7)
136            .build();
137        assert_eq!(0, cns.generated());
138        let nonce = cns.advance().unwrap();
139        let nonce = nonce.as_ref();
140        assert_eq!(8, cns.counter());
141        assert_eq!(
142            [0xA1, 0xB2, 0xC3, 0xD4, 0xA2, 0xB3, 0xC4, 0xD5],
143            cns.identifier()
144        );
145        assert_eq!(u32::MAX, cns.limit());
146        assert_eq!(1, cns.generated());
147        assert_eq!(
148            nonce,
149            &[0xA1, 0xB2, 0xC3, 0xD4, 0xA2, 0xB3, 0xC4, 0xD5, 0, 0, 0, 7]
150        );
151    }
152}
```

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

### Initialize CMAC Keys

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/cmac.rs.html

Demonstrates creating CMAC keys for various algorithms including AES and 3DES, and handling key length validation.

```rust
#[test]
    fn cmac_key_new_test() {
        // Test Key::new with explicit key values
        let key_128 = [0u8; 16];
        let key_192 = [0u8; 24];
        let key_256 = [0u8; 32];
        let key_3des = [0u8; 24];

        let k1 = Key::new(AES_128, &key_128).unwrap();
        let k2 = Key::new(AES_192, &key_192).unwrap();
        let k3 = Key::new(AES_256, &key_256).unwrap();
        let k4 = Key::new(DES_EDE3_FOR_LEGACY_USE_ONLY, &key_3des).unwrap();

        let data = b"test message";

        // All should produce valid tags
        let _ = sign(&k1, data).unwrap();
        let _ = sign(&k2, data).unwrap();
        let _ = sign(&k3, data).unwrap();
        let _ = sign(&k4, data).unwrap();
    }
```

```rust
#[test]
    fn cmac_key_new_wrong_length_test() {
        let key_256 = [0u8; 32];
        // Wrong key length should return error
        assert!(Key::new(AES_128, &key_256).is_err());
    }
```

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

### Get EC Group from NID

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/ec.rs.html

Retrieves an EC_GROUP pointer based on the provided curve NID.

```rust
#[inline]
#[allow(non_upper_case_globals)]
pub(crate) fn ec_group_from_nid(nid: i32) -> Result<ConstPointer<'static, EC_GROUP>, Unspecified> {
    Ok(unsafe {
        ConstPointer::new_static(match nid {
            NID_secp224r1 => EC_group_p224(),
            NID_X9_62_prime256v1 => EC_group_p256(),
            NID_secp384r1 => EC_group_p384(),
            NID_secp521r1 => EC_group_p521(),
            NID_secp256k1 => EC_group_secp256k1(),
            _ => {
                // OPENSSL_PUT_ERROR(EC, EC_R_UNKNOWN_GROUP);
                null()
            }
        })?
    })
}
```

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

### ECB-PKCS7 Streaming Cipher Test Setup

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/cipher/streaming.rs.html

Initializes the test environment for the ECB-PKCS7 streaming cipher mode.

```rust
#[test]
    fn test_step_ecb_pkcs7_less_safe() {
        let random = SystemRandom::new();
        let mut key = [0u8; AES_256_KEY_LEN];
        random.fill(&mut key).unwrap();

        let encrypting_key_creator = || {
            let key = UnboundCipherKey::new(&AES_256, &key.clone()).unwrap();
            StreamingEncryptingKey::ecb_pkcs7(key).unwrap()
        };
        let decrypting_key_creator = |decryption_ctx: DecryptionContext| {
            let key = UnboundCipherKey::new(&AES_256, &key.clone()).unwrap();
            StreamingDecryptingKey::ecb_pkcs7(key, decryption_ctx).unwrap()
        };
```

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

### OpeningKey::new

Source: https://docs.rs/aws-lc-rs/latest/aws_lc_rs/aead/struct.OpeningKey.html

Constructs a new OpeningKey instance from an UnboundKey and a nonce sequence.

```APIDOC
## fn new<N: NonceSequence>(key: UnboundKey, nonce_sequence: N) -> Self

### Description
Constructs a new key from the given `UnboundKey` and `NonceSequence`.

### Parameters
- **key** (UnboundKey) - The unbound key to be used for decryption.
- **nonce_sequence** (N) - The sequence of nonces to be used with the key.
```

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

### Test Assertion Example

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/test.rs.html?search=

Verifies that a hex string matches the expected uppercase conversion of a byte array.

```rust
664        assert_eq!(hex.to_ascii_uppercase(), to_hex_upper(bytes));
665    }
666}
```

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

### Example Failing Test Case

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/test.rs.html

A sample test case that would trigger a failure in the testing framework.

```text
Curve = P-256
a = 2b11cb945c8cf152ffa4c9c2b1c965b019b35d0b7626919ef0ae6cb9d232f8af
b = 18905f76a53755c679fb732b7762251075ba95fc5fedb60179e730d418a9143c
r = 18905f76a53755c679fb732b7762251075ba95fc5fedb60179e730d418a9143c
```

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

### AEAD Sealing and Opening with Nonce Sequence

Source: https://docs.rs/aws-lc-rs/latest/aws_lc_rs/aead/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates how to initialize an UnboundKey, construct a SealingKey or OpeningKey with a Counter64Builder nonce sequence, and perform in-place encryption and decryption.

```APIDOC
## AEAD Sealing and Opening

### Description
This operation uses an UnboundKey and a Counter64Builder nonce sequence to create a SealingKey for encryption or an OpeningKey for decryption. The process involves providing AAD (Additional Authenticated Data) and modifying a buffer in-place.

### Usage
1. Initialize `UnboundKey` with an algorithm (e.g., `AES_128_GCM`) and key bytes.
2. Create a `nonce_sequence` using `Counter64Builder`.
3. Instantiate `SealingKey` or `OpeningKey`.
4. Call `seal_in_place_append_tag` or `open_in_place` with AAD and the data buffer.
```

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

### Sealed Trait Pattern

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/lib.rs.html

Example usage of the internal sealed trait pattern for library-only trait implementation.

```rust
use crate::sealed;

pub trait MyType: sealed::Sealed {
    // [...]
}
```

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

### PqdsaKeyPair Serialization Roundtrips

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/pqdsa/key_pair.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates roundtrip serialization using raw private keys and PKCS#8 formats.

```rust
use crate::encoding::AsRawBytes;
for &alg in TEST_ALGORITHMS {
    let seed = [55u8; 32];
    let kp = PqdsaKeyPair::from_seed(alg, &seed).unwrap();
    let raw_bytes = kp.private_key().as_raw_bytes().unwrap();
    let kp2 = PqdsaKeyPair::from_raw_private_key(alg, raw_bytes.as_ref()).unwrap();
    assert_eq!(kp.public_key().as_ref(), kp2.public_key().as_ref());
}
```

```rust
for &alg in TEST_ALGORITHMS {
    let seed = [77u8; 32];
    let kp = PqdsaKeyPair::from_seed(alg, &seed).unwrap();
    let pkcs8 = kp.to_pkcs8().unwrap();
    let kp2 = PqdsaKeyPair::from_pkcs8(alg, pkcs8.as_ref()).unwrap();
    assert_eq!(kp.public_key().as_ref(), kp2.public_key().as_ref());
}
```

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

### Run tests with MemorySanitizer

Source: https://docs.rs/aws-lc-rs/latest/aws_lc_rs/index.html?search=

Example command for running tests with MSAN instrumentation using the nightly toolchain.

```bash
rustup component add rust-src --toolchain nightly
AWS_LC_SYS_SANITIZER=msan RUSTFLAGS="-Zsanitizer=memory -Zsanitizer-memory-track-origins" \
    cargo +nightly test -Zbuild-std --target x86_64-unknown-linux-gnu
```

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

### Test Runner Utilities

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/test.rs.html

Examples of using the test runner to handle test files, expected errors, and panics.

```rust
#[test]
    fn one_ok() {
        test::run(test_file!("test/test_1_tests.txt"), |_, test_case| {
            test_case.consume_string("Key");
            Ok(())
        });
    }
```

```rust
#[test]
    #[should_panic(expected = "Test failed.")]
    fn one_err() {
        test::run(test_file!("test/test_1_tests.txt"), |_, test_case| {
            test_case.consume_string("Key");
            Err(error::Unspecified)
        });
    }
```

```rust
#[test]
    #[should_panic(expected = "Oh noes!")]
    fn one_panics() {
        test::run(test_file!("test/test_1_tests.txt"), |_, test_case| {
            test_case.consume_string("Key");
            panic!("Oh noes!");
        });
    }
```

```rust
#[test]
    #[should_panic(expected = "Test failed.")]
    fn first_err() {
        err_one(0);
    }

    #[test]
    #[should_panic(expected = "Test failed.")]
    fn middle_err() {
        err_one(1);
    }

    #[test]
    #[should_panic(expected = "Test failed.")]
    fn last_err() {
        err_one(2);
    }

    fn err_one(test_to_fail: usize) {
        let mut n = 0;
        test::run(test_file!("test/test_3_tests.txt"), |_, test_case| {
            test_case.consume_string("Key");
            let result = if n == test_to_fail {
                Err(error::Unspecified)
            } else {
                Ok(())
            };
            n += 1;
            result
        });
    }
```

```rust
#[test]
    #[should_panic(expected = "Oh Noes!")]
    fn first_panic() {
        panic_one(0);
    }

    #[test]
    #[should_panic(expected = "Oh Noes!")]
    fn middle_panic() {
        panic_one(1);
    }

    #[test]
    #[should_panic(expected = "Oh Noes!")]
    fn last_panic() {
        panic_one(2);
    }

    fn panic_one(test_to_fail: usize) {
        let mut n = 0;
        test::run(test_file!("test/test_3_tests.txt"), |_, test_case| {
            test_case.consume_string("Key");
            assert_ne!(n, test_to_fail, "Oh Noes!");
            n += 1;
            Ok(())
        });
    }
```

```rust
#[test]
    #[should_panic(expected = "Syntax error: Expected Key = Value.")]
    fn syntax_error() {
        test::run(test_file!("test/test_1_syntax_error_tests.txt"), |_, _| {
            Ok(())
        });
    }
```

```rust
#[test]
    fn test_to_hex_upper() {
        let hex = "abcdef0123";
        let bytes = from_dirty_hex(hex);
```

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

### Example Failure Output

Source: https://docs.rs/aws-lc-rs/latest/src/aws_lc_rs/test.rs.html

The output format displayed by the framework when a test case fails, including backtrace information.

```text
src/example_tests.txt: Test panicked.
Curve = P-256
a = 2b11cb945c8cf152ffa4c9c2b1c965b019b35d0b7626919ef0ae6cb9d232f8af
b = 18905f76a53755c679fb732b7762251075ba95fc5fedb60179e730d418a9143c
r = 18905f76a53755c679fb732b7762251075ba95fc5fedb60179e730d418a9143c
thread 'example_test' panicked at 'Test failed.', src\test.rs:206
stack backtrace:
   0:     0x7ff654a05c7c - std::rt::lang_start::h61f4934e780b4dfc
   1:     0x7ff654a04f32 - std::rt::lang_start::h61f4934e780b4dfc
   2:     0x7ff6549f505d - std::panicking::rust_panic_with_hook::hfe203e3083c2b544
   3:     0x7ff654a0825b - rust_begin_unwind
   4:     0x7ff6549f63af - std::panicking::begin_panic_fmt::h484cd47786497f03
   5:     0x7ff654a07e9b - rust_begin_unwind
   6:     0x7ff654a0ae95 - core::panicking::panic_fmt::h257ceb0aa351d801
   7:     0x7ff654a0b190 - core::panicking::panic::h4bb1497076d04ab9
   8:     0x7ff65496dc41 - from_file<closure>
                        at C:\Users\Example\example\<core macros>:4
   9:     0x7ff65496d49c - example_test
                        at C:\Users\Example\example\src\example.rs:652
  10:     0x7ff6549d192a - test::stats::Summary::new::ha139494ed2e4e01f
  11:     0x7ff6549d51a2 - test::stats::Summary::new::ha139494ed2e4e01f
  12:     0x7ff654a0a911 - _rust_maybe_catch_panic
  13:     0x7ff6549d56dd - test::stats::Summary::new::ha139494ed2e4e01f
  14:     0x7ff654a03783 - std::sys::thread::Thread::new::h2b08da6cd2517f79
  15:     0x7ff968518101 - BaseThreadInitThunk
```
Tokens:
Raw