Ring

https://docs.rs/ring/0.17.14/
Admin
Ring is a cryptographic library for Rust providing AEAD encryption, key agreement, digital...
Tokens:463,652
Snippets:3,091
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### RSA Signing and Verification Example

Source: https://docs.rs/ring/0.17.14/src/ring/signature.rs.html?search=std%3A%3Avec

Demonstrates the process of signing a message with an RSA key pair and verifying the resulting signature. This example includes custom error handling and a file reading utility for loading keys.

```rust
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 {
#  #[cfg(feature = "std")]
   IO(std::io::Error),
   BadPrivateKey,
   OOM,
   BadSignature,
}

# #[cfg(feature = "std")]
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)
}
#
# #[cfg(not(feature = "std"))]
# fn sign_and_verify_rsa(_private_key_path: &std::path::Path,
#                        _public_key_path: &std::path::Path)
#                        -> Result<(), ()> {
#     Ok(())
# }
#
# fn main() {
#     let private_key_path =
#         std::path::Path::new("src/rsa/signature_rsa_example_private_key.der");
#     let public_key_path =
#         std::path::Path::new("src/rsa/signature_rsa_example_public_key.der");
#     sign_and_verify_rsa(&private_key_path, &public_key_path).unwrap()
# }
```

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

### Verify password login example

Source: https://docs.rs/ring/0.17.14/src/ring/pbkdf2.rs.html

An example showing a successful password verification attempt.

```rust
    // An attempt to log in with the right password succeeds.
    assert!(db.verify_password("alice", "@74d7]404j|W}6u").is_ok());
}
```

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

### PBKDF2 Password Verification Example

Source: https://docs.rs/ring/0.17.14/src/ring/pbkdf2.rs.html?search=

An example of verifying a password using the PBKDF2 implementation.

```rust
// An attempt to log in with the right password succeeds.
assert!(db.verify_password("alice", "@74d7]404j|W}6u").is_ok());
}
```

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

### Password Database Example

Source: https://docs.rs/ring/0.17.14/ring/pbkdf2/index.html?search=

Demonstrates how to implement a password storage and verification system using PBKDF2. It highlights the importance of using a user-specific and database-unique salt to protect against attacks.

```rust
use ring::{digest, pbkdf2};
use std::{collections::HashMap, num::NonZeroU32};

static PBKDF2_ALG: pbkdf2::Algorithm = pbkdf2::PBKDF2_HMAC_SHA256;
const CREDENTIAL_LEN: usize = digest::SHA256_OUTPUT_LEN;
pub type Credential = [u8; CREDENTIAL_LEN];

enum Error {
    WrongUsernameOrPassword
}

struct PasswordDatabase {
    pbkdf2_iterations: NonZeroU32,
    db_salt_component: [u8; 16],

    // Normally this would be a persistent database.
    storage: HashMap<String, Credential>,
}

impl PasswordDatabase {
    pub fn store_password(&mut self, username: &str, password: &str) {
        let salt = self.salt(username);
        let mut to_store: Credential = [0u8; CREDENTIAL_LEN];
        pbkdf2::derive(PBKDF2_ALG, self.pbkdf2_iterations, &salt,
                       password.as_bytes(), &mut to_store);
        self.storage.insert(String::from(username), to_store);
    }

    pub fn verify_password(&self, username: &str, attempted_password: &str)
                           -> Result<(), Error> {
        match self.storage.get(username) {
           Some(actual_password) => {
               let salt = self.salt(username);
               pbkdf2::verify(PBKDF2_ALG, self.pbkdf2_iterations, &salt,
                              attempted_password.as_bytes(),
                              actual_password)
                    .map_err(|_| Error::WrongUsernameOrPassword)
           },

           None => Err(Error::WrongUsernameOrPassword)
        }
    }

    // The salt should have a user-specific component so that an attacker
    // cannot crack one password for multiple users in the database. It
    // should have a database-unique component so that an attacker cannot
    // crack the same user's password across databases in the unfortunate
    // but common case that the user has used the same password for
    // multiple systems.
    fn salt(&self, username: &str) -> Vec<u8> {
        let mut salt = Vec::with_capacity(self.db_salt_component.len() +
                                          username.as_bytes().len());
        salt.extend(self.db_salt_component.as_ref());
        salt.extend(username.as_bytes());
        salt
    }
}

fn main() {
    // Normally these parameters would be loaded from a configuration file.
    let mut db = PasswordDatabase {
        pbkdf2_iterations: NonZeroU32::new(100_000).unwrap(),
        db_salt_component: [
            // This value was generated from a secure PRNG.
            0xd6, 0x26, 0x98, 0xda, 0xf4, 0xdc, 0x50, 0x52,
            0x24, 0xf2, 0x27, 0xd1, 0xfe, 0x39, 0x01, 0x8a
        ],
        storage: HashMap::new(),
    };

    db.store_password("alice", "@74d7]404j|W}6u");

    // An attempt to log in with the wrong password fails.
    assert!(db.verify_password("alice", "wrong password").is_err());

    // Normally there should be an expoentially-increasing delay between
    // attempts to further protect against online attacks.

    // An attempt to log in with the right password succeeds.
    assert!(db.verify_password("alice", "@74d7]404j|W}6u").is_ok());
}
```

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

### PKCS1 Padding Instances

Source: https://docs.rs/ring/0.17.14/src/ring/rsa/padding/pkcs1.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Examples of PKCS1 padding instances defined using the rsa_pkcs1_padding macro.

```rust
rsa_pkcs1_padding!(
    pub(in super::super) RSA_PKCS1_SHA1_FOR_LEGACY_USE_ONLY,
    &digest::SHA1_FOR_LEGACY_USE_ONLY,
    &SHA1_PKCS1_DIGESTINFO_PREFIX,
    "PKCS#1 1.5 padding using SHA-1 for RSA signatures."
);

rsa_pkcs1_padding!(
    pub RSA_PKCS1_SHA256,
    &digest::SHA256,
    &SHA256_PKCS1_DIGESTINFO_PREFIX,
    "PKCS#1 1.5 padding using SHA-256 for RSA signatures."
);

rsa_pkcs1_padding!(
    pub RSA_PKCS1_SHA384,
    &digest::SHA384,
    &SHA384_PKCS1_DIGESTINFO_PREFIX,
    "PKCS#1 1.5 padding using SHA-384 for RSA signatures."
);
```

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

### Multi-step Digest Calculation

Source: https://docs.rs/ring/0.17.14/ring/digest/struct.Context.html

Example showing how to use Context for multi-part digest updates compared to a one-shot digest.

```rust
use ring::digest;

let one_shot = digest::digest(&digest::SHA384, b"hello, world");

let mut ctx = digest::Context::new(&digest::SHA384);
ctx.update(b"hello");
ctx.update(b", ");
ctx.update(b"world");
let multi_part = ctx.finish();

assert_eq!(&one_shot.as_ref(), &multi_part.as_ref());
```

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

### RSA Signing and Verification Example

Source: https://docs.rs/ring/0.17.14/src/ring/signature.rs.html?search=u32+-%3E+bool

Demonstrates the full workflow of signing a message with an RSA key pair and verifying the resulting signature using an unparsed public key.

```rust
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)
}
```

```rust
#[derive(Debug)]
enum MyError {
#  #[cfg(feature = "std")]
   IO(std::io::Error),
   BadPrivateKey,
   OOM,
   BadSignature,
}
```

```rust
# #[cfg(feature = "std")]
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)
}
```

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

### Point double test setup

Source: https://docs.rs/ring/0.17.14/src/ring/ec/suite_b/ops.rs.html?search=

Initializes the P-256 point doubling test with the required external C function.

```rust
#[test]
fn p256_point_double_test() {
    prefixed_extern! {
        fn p256_point_double(
            r: *mut Limb,   // [p256::COMMON_OPS.num_limbs*3]
            a: *const Limb, // [p256::COMMON_OPS.num_limbs*3]
        );
    }
    point_double_test(

```

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

### OpeningKey::new

Source: https://docs.rs/ring/0.17.14/ring/aead/chacha20_poly1305_openssh/struct.OpeningKey.html

Constructs a new OpeningKey instance from 64 bytes of key material.

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

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

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

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

### Test elem_reduced_once

Source: https://docs.rs/ring/0.17.14/src/ring/arithmetic/bigint.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example of a test function using test_vector_file to verify the elem_reduced_once operation.

```rust
    #[test]
    fn test_elem_reduced_once() {
        let cpu_features = cpu::features();
        test::run(
            test_vector_file!("bigint_elem_reduced_once_tests.txt"),
            |section, test_case| {
                assert_eq!(section, "");

                struct M {}
                struct O {}
                let m = consume_modulus::<M>(test_case, "m");
                let m = m.modulus(cpu_features);
                let a = consume_elem_unchecked::<O>(test_case, "a", m.limbs().len());
                let expected_result = consume_elem::<M>(test_case, "r", &m);
                let other_modulus_len_bits = m.len_bits();

                let actual_result =
                    elem_reduced_once(m.alloc_zero(), &a, &m, other_modulus_len_bits);
                assert_elem_eq(&actual_result, &expected_result);

                Ok(())
            },
        )
    }
```

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

### Test elem_reduced

Source: https://docs.rs/ring/0.17.14/src/ring/arithmetic/bigint.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example of a test function using test_vector_file to verify the elem_reduced operation.

```rust
    #[test]
    fn test_elem_reduced() {
        let cpu_features = cpu::features();
        test::run(
            test_vector_file!("bigint_elem_reduced_tests.txt"),
            |section, test_case| {
                assert_eq!(section, "");

                struct M {}

                let m_ = consume_modulus::<M>(test_case, "M");
                let m = m_.modulus(cpu_features);
                let expected_result = consume_elem(test_case, "R", &m);
                let a =
                    consume_elem_unchecked::<M>(test_case, "A", expected_result.limbs.len() * 2);
                let other_modulus_len_bits = m_.len_bits();

                let actual_result = elem_reduced(m.alloc_zero(), &a, &m, other_modulus_len_bits);
                let oneRR = One::newRR(m.alloc_zero(), &m);
                let actual_result = elem_mul(oneRR.as_ref(), actual_result, &m);
                assert_elem_eq(&actual_result, &expected_result);

                Ok(())
            },
        )
    }
```

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

### OpeningKey::new

Source: https://docs.rs/ring/0.17.14/ring/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]) -> Self

### 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.
```

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

### Test elem_squared

Source: https://docs.rs/ring/0.17.14/src/ring/arithmetic/bigint.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example of a test function using test_vector_file to verify the elem_squared operation.

```rust
    #[test]
    fn test_elem_squared() {
        let cpu_features = cpu::features();
        test::run(
            test_vector_file!("bigint_elem_squared_tests.txt"),
            |section, test_case| {
                assert_eq!(section, "");

                let m = consume_modulus::<M>(test_case, "M");
                let m = m.modulus(cpu_features);
                let expected_result = consume_elem(test_case, "ModSquare", &m);
                let a = consume_elem(test_case, "A", &m);

                let a = into_encoded(m.alloc_zero(), a, &m);
                let actual_result = elem_squared(a, &m);
                let actual_result = actual_result.into_unencoded(&m);
                assert_elem_eq(&actual_result, &expected_result);

                Ok(())
            },
        )
    }
```

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

### OpeningKey::new constructor

Source: https://docs.rs/ring/0.17.14/ring/aead/chacha20_poly1305_openssh/struct.OpeningKey.html?search=

Constructs a new OpeningKey from 64 bytes of key material.

```rust
pub fn new(key_material: &[u8; 64]) -> Self
```

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

### Test runner syntax error handling

Source: https://docs.rs/ring/0.17.14/src/ring/testutil.rs.html

Example of testing for syntax errors in test vector files.

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

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

### OpeningKey::new

Source: https://docs.rs/ring/0.17.14/ring/aead/struct.OpeningKey.html?search=

Constructs a new OpeningKey instance from an UnboundKey and a NonceSequence.

```APIDOC
## fn new(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 for the key.
```

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

### Example Failing Test Case

Source: https://docs.rs/ring/0.17.14/src/ring/testutil.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
```

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

### Signing and verifying with RSA (PKCS#1 1.5 padding)

Source: https://docs.rs/ring/0.17.14/ring/signature/index.html

Demonstrates signing a message with RSA PKCS#1 v1.5 padding and SHA256, and verifying the signature.

```rust
use ring::{rand, rsa, signature};

fn sign_and_verify_rsa(private_key_path: &std::path::Path,
                       public_key_path: &std::path::Path)
                       -> Result<(), MyError> {
// Create an RSA keypair 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 = rsa::KeyPair::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)
}
```

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

### PrivatePrime construction

Source: https://docs.rs/ring/0.17.14/src/ring/rsa/keypair.rs.html

Logic for initializing a private prime component, including bit length validation and modulus setup.

```rust
struct PrivatePrime<M> {
    modulus: bigint::OwnedModulus<M>,
    oneRR: bigint::One<M, RR>,
}

impl<M> PrivatePrime<M> {
    fn new(
        p: untrusted::Input,
        n_bits: BitLength,
        cpu_features: cpu::Features,
    ) -> Result<Self, KeyRejected> {
        let p = bigint::OwnedModulusValue::from_be_bytes(p)?;

        // 5.c / 5.g:
        //
        // TODO: First, stop if `p < (√2) * 2**((nBits/2) - 1)`.
        // TODO: First, stop if `q < (√2) * 2**((nBits/2) - 1)`.
        //
        // Second, stop if `p > 2**(nBits/2) - 1`.
        // Second, stop if `q > 2**(nBits/2) - 1`.
        if p.len_bits() != n_bits.half_rounded_up() {
            return Err(KeyRejected::inconsistent_components());
        }

        if p.len_bits().as_bits() % 512 != 0 {
            return Err(KeyRejected::private_modulus_len_not_multiple_of_512_bits());
        }

        // TODO: Step 5.d: Verify GCD(p - 1, e) == 1.
        // TODO: Step 5.h: Verify GCD(q - 1, e) == 1.

        // Steps 5.e and 5.f are omitted as explained above.
        let p = bigint::OwnedModulus::from(p);
        let pm = p.modulus(cpu_features);
        let oneRR = bigint::One::newRR(pm.alloc_zero(), &pm);

        Ok(Self { modulus: p, oneRR })
    }
}
```

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

### Open operation entry point

Source: https://docs.rs/ring/0.17.14/src/ring/aead/aes_gcm.rs.html?search=

Dispatches the open operation to the appropriate hardware-accelerated or fallback implementation based on the target architecture.

```rust
#[inline(never)]
pub(super) fn open(
    Key(key): &Key,
    nonce: Nonce,
    aad: Aad<&[u8]>,
    in_out_slice: &mut [u8],
    src: RangeFrom<usize>,
) -> Result<Tag, error::Unspecified> {
    let mut ctr = Counter::one(nonce);
    let tag_iv = ctr.increment();

    match key {
        #[cfg(all(target_arch = "aarch64", target_endian = "little"))]
        DynKey::AesHwClMul(c) => {
            open_whole_partial(c, aad, in_out_slice, src, ctr, tag_iv, aarch64::open_whole)
        }

        #[cfg(target_arch = "x86_64")]
        DynKey::VAesClMulAvx2(c) => open_whole_partial(
            c,
            aad,
            in_out_slice,
            src,
            ctr,
            tag_iv,
            vaesclmulavx2::open_whole_vaes_clmul_avx2,
        ),

        #[cfg(target_arch = "x86_64")]
        DynKey::AesHwClMulAvxMovbe(Combo { aes_key, gcm_key }) => {
            aeshwclmulmovbe::open(aes_key, gcm_key, ctr, tag_iv, aad, in_out_slice, src)
        }

        #[cfg(any(target_arch = "x86_64", target_arch = "x86"))]
        DynKey::AesHwClMul(c) => open_strided(c, aad, in_out_slice, src, ctr, tag_iv),

        #[cfg(any(
            all(target_arch = "aarch64", target_endian = "little"),
            all(target_arch = "arm", target_endian = "little"),
            target_arch = "x86_64",
            target_arch = "x86"
        ))]
        DynKey::Simd(c) => open_strided(c, aad, in_out_slice, src, ctr, tag_iv),

        DynKey::Fallback(c) => open_strided(c, aad, in_out_slice, src, ctr, tag_iv),
    }
}
```

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

### CPU Feature Configuration

Source: https://docs.rs/ring/0.17.14/src/ring/aead/chacha20_poly1305/integrated.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Conditional compilation setup for required and optional CPU features based on the target architecture.

```rust
cfg_if! {
    if #[cfg(all(target_arch = "aarch64", target_endian = "little"))] {
        use crate::cpu::arm::Neon;
        type RequiredCpuFeatures = Neon;
        type OptionalCpuFeatures = ();
    } else {
        use crate::cpu::intel::{Avx2, Bmi2, Sse41};
        type RequiredCpuFeatures = Sse41;
        type OptionalCpuFeatures = (Avx2, Bmi2);
    }
}
```

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

### Read Tag and Get Value

Source: https://docs.rs/ring/0.17.14/src/ring/io/der.rs.html

Reads a DER-encoded tag and its length, returning the tag byte and the inner input slice.

```rust
pub fn read_tag_and_get_value<'a>(
    input: &mut untrusted::Reader<'a>,
) -> Result<(u8, untrusted::Input<'a>), error::Unspecified> {
    let tag = input.read_byte()?;
    if (tag & 0x1F) == 0x1F {
        return Err(error::Unspecified); // High tag number form is not allowed.
    }

    // If the high order bit of the first byte is set to zero then the length
    // is encoded in the seven remaining bits of that byte. Otherwise, those
    // seven bits represent the number of bytes used to encode the length.
    let length = match input.read_byte()? {
        n if (n & 0x80) == 0 => usize::from(n),
        0x81 => {
            let second_byte = input.read_byte()?;
            if second_byte < 128 {
                return Err(error::Unspecified); // Not the canonical encoding.
            }
            usize::from(second_byte)
        }
        0x82 => {
            let second_byte = usize::from(input.read_byte()?);
            let third_byte = usize::from(input.read_byte()?);
            let combined = (second_byte << 8) | third_byte;
            if combined < 256 {
                return Err(error::Unspecified); // Not the canonical encoding.
            }
            combined
        }
        _ => {
            return Err(error::Unspecified); // We don't support longer lengths.
        }
    };

    let inner = input.read_bytes(length)?;
    Ok((tag, inner))
}
```

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

### ChaCha20-Poly1305 Initialization

Source: https://docs.rs/ring/0.17.14/src/ring/aead/algorithm.rs.html?search=std%3A%3Avec

Initializes the ChaCha20-Poly1305 key context.

```rust
fn chacha20_poly1305_init(
    key: &[u8],
    _cpu_features: cpu::Features,
) -> Result<KeyInner, error::Unspecified> {
    let key: [u8; chacha20_poly1305::KEY_LEN] = key.try_into()?;
    Ok(KeyInner::ChaCha20Poly1305(chacha20_poly1305::Key::new(key)))
}
```

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

### Expect Tag and Get Value

Source: https://docs.rs/ring/0.17.14/src/ring/io/der.rs.html

Validates that the next element in the reader matches the expected tag and returns its inner content.

```rust
pub fn expect_tag_and_get_value<'a>(
    input: &mut untrusted::Reader<'a>,
    tag: Tag,
) -> Result<untrusted::Input<'a>, error::Unspecified> {
    let (actual_tag, inner) = read_tag_and_get_value(input)?;
    if usize::from(tag) != usize::from(actual_tag) {
        return Err(error::Unspecified);
    }
    Ok(inner)
}
```

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

### Feature Flag Initialization and Detection

Source: https://docs.rs/ring/0.17.14/src/ring/cpu/intel.rs.html

Manages the initialization of CPU features using OPENSSL_cpuid_setup and provides access to detected features.

```rust
pub(in super::super) fn get_or_init() -> cpu::Features {
        // SAFETY: `OPENSSL_cpuid_setup` must be called only in
        // `INIT.call_once()` below.
        prefixed_extern! {
            fn OPENSSL_cpuid_setup(out: &mut [u32; 4]);
        }

        let _: NonZeroUsize = FEATURES.get_or_init(|| {
            let mut cpuid = [0; 4];
            // SAFETY: We assume that it is safe to execute CPUID and XGETBV.
            unsafe {
                OPENSSL_cpuid_setup(&mut cpuid);
            }
            let detected = super::cpuid_to_caps_and_set_c_flags(&cpuid);
            let merged = CAPS_STATIC | detected;

            let merged = usize_from_u32(merged) | (1 << (super::Shift::Initialized as u32));
            NonZeroUsize::new(merged).unwrap() // Can't fail because we just set a bit.
        });

        // SAFETY: We initialized the CPU features as required.
        // `INIT.call_once` has `happens-before` semantics.
        unsafe { cpu::Features::new_after_feature_flags_written_and_synced_unchecked() }
    }

    pub(in super::super) fn get(_cpu_features: cpu::Features) -> u32 {
        // SAFETY: Since only `get_or_init()` could have created
        // `_cpu_features`, and it only does so after `FEATURES.get_or_init()`,
        // we know we are reading from `FEATURES` after initializing it.
        //
        // Also, 0 means "no features detected" to users, which is designed to
        // be a safe configuration.
        let features = FEATURES.get().map(NonZeroUsize::get).unwrap_or(0);

        // The truncation is lossless, as we set the value with a u32.
        #[allow(clippy::cast_possible_truncation)]
        let features = features as u32;

        features
    }

    static FEATURES: race::OnceNonZeroUsize = race::OnceNonZeroUsize::new();
```

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

### Implement From for Unspecified

Source: https://docs.rs/ring/0.17.14/ring/error/struct.Unspecified.html?search=u32+-%3E+bool

Example showing how to implement From<ring::error::Unspecified> to map crypto errors to a custom application error type.

```rust
use ring::rand::{self, SecureRandom};

enum Error {
    CryptoError,

    IOError(std::io::Error),
    // [...]
}

impl From<ring::error::Unspecified> for Error {
    fn from(_: ring::error::Unspecified) -> Self { Error::CryptoError }
}

fn eight_random_bytes() -> Result<[u8; 8], Error> {
    let rng = rand::SystemRandom::new();
    let mut bytes = [0; 8];

    // The `From<ring::error::Unspecified>` implementation above makes this
    // equivalent to
    // `rng.fill(&mut bytes).map_err(|_| Error::CryptoError)?`.
    rng.fill(&mut bytes)?;

    Ok(bytes)
}

assert!(eight_random_bytes().is_ok());
```

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

### UnparsedPublicKey::new

Source: https://docs.rs/ring/0.17.14/ring/agreement/struct.UnparsedPublicKey.html?search=u32+-%3E+bool

Constructs a new UnparsedPublicKey instance.

```APIDOC
### pub fn new(algorithm: &'static Algorithm, bytes: B) -> Self

Constructs a new `UnparsedPublicKey`.
```

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

### Overlapping struct definition and implementation

Source: https://docs.rs/ring/0.17.14/src/ring/aead/overlapping/base.rs.html?search=u32+-%3E+bool

The Overlapping struct maintains an invariant that the source range start is within the bounds of the input/output slice.

```rust
pub struct Overlapping<'o, T> {
    // Invariant: self.src.start <= in_out.len().
    in_out: &'o mut [T],
    src: RangeFrom<usize>,
}

impl<'o, T> From<&'o mut [T]> for Overlapping<'o, T> {
    fn from(in_out: &'o mut [T]) -> Self {
        Self { in_out, src: 0.. }
    }
}

impl<'o, T> Overlapping<'o, T> {
    pub fn new(in_out: &'o mut [T], src: RangeFrom<usize>) -> Result<Self, IndexError> {
        match in_out.get(src.clone()) {
            Some(_) => Ok(Self { in_out, src }),
            None => Err(IndexError::new(src.start)),
        }
    }

    #[cfg(any(
        all(target_arch = "arm", target_endian = "little"),
        target_arch = "x86"
    ))]
    pub fn copy_within(self) -> &'o mut [T]
    where
        T: Copy,
    {
        if self.src.start == 0 {
            self.in_out
        } else {
            let len = self.len();
            self.in_out.copy_within(self.src, 0);
            &mut self.in_out[..len]
        }
    }

    #[cfg(any(
        all(target_arch = "arm", target_endian = "little"),
        target_arch = "x86"
    ))]
    pub fn into_slice_src_mut(self) -> (&'o mut [T], RangeFrom<usize>) {
        (self.in_out, self.src)
    }

    pub fn into_unwritten_output(self) -> &'o mut [T] {
        let len = self.len();
        self.in_out.get_mut(..len).unwrap_or_else(|| {
            // The invariant ensures this succeeds.
            unreachable!()
        })
    }
}
```

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

### DynKey Initialization Logic

Source: https://docs.rs/ring/0.17.14/src/ring/aead/aes_gcm.rs.html?search=

Implements the logic to select the appropriate AES-GCM implementation based on available CPU features.

```rust
impl DynKey {
    fn new(key: aes::KeyBytes, cpu: cpu::Features) -> Result<Self, error::Unspecified> {
        let cpu = cpu.values();

        #[cfg(target_arch = "x86_64")]
        if let Some((aes, gcm)) = cpu.get_feature() {
            // 14.3.1 Detection of VEX-Encoded AES and VPCLMULQDQ
            let aes_key = aes::hw::Key::new(key, aes, cpu.get_feature())?;
            let gcm_key_value = derive_gcm_key_value(&aes_key);
            let combo = if let Some(cpu) = cpu.get_feature() {
                let gcm_key = gcm::vclmulavx2::Key::new(gcm_key_value, cpu);
                Self::VAesClMulAvx2(Combo { aes_key, gcm_key })
            } else if let Some(cpu) = cpu.get_feature() {
                let gcm_key = gcm::clmulavxmovbe::Key::new(gcm_key_value, cpu);
                Self::AesHwClMulAvxMovbe(Combo { aes_key, gcm_key })
            } else {
                let gcm_key = gcm::clmul::Key::new(gcm_key_value, gcm);
                Self::AesHwClMul(Combo { aes_key, gcm_key })
            };
            return Ok(combo);
        }

        // x86_64 is handled above.
        #[cfg(any(
            all(target_arch = "aarch64", target_endian = "little"),
            target_arch = "x86"
        ))]
        if let (Some(aes), Some(gcm)) = (cpu.get_feature(), cpu.get_feature()) {
            let aes_key = aes::hw::Key::new(key, aes, cpu.get_feature())?;
            let gcm_key_value = derive_gcm_key_value(&aes_key);
            let gcm_key = gcm::clmul::Key::new(gcm_key_value, gcm);
            return Ok(Self::AesHwClMul(Combo { aes_key, gcm_key }));
        }

        #[cfg(any(
            all(target_arch = "aarch64", target_endian = "little"),
            all(target_arch = "arm", target_endian = "little")
        ))]
        if let Some(cpu) = cpu.get_feature() {
            return Self::new_neon(key, cpu);
        }

        #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
        if let Some(cpu) = cpu.get_feature() {
            return Self::new_ssse3(key, cpu);
        }

        let _ = cpu;
        Self::new_fallback(key)
    }
```

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

### Test runner success and failure cases

Source: https://docs.rs/ring/0.17.14/src/ring/testutil.rs.html

Examples of using the test runner to process test vectors, including handling successful execution, expected errors, and panics.

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

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

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

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

### SealingKey::new

Source: https://docs.rs/ring/0.17.14/ring/aead/chacha20_poly1305_openssh/struct.SealingKey.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

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

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

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

### Parameters
- **key_material** (&[u8; 64]) - Required - The 64-byte key material used for initialization.
```

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

### SealingKey::new

Source: https://docs.rs/ring/0.17.14/ring/aead/chacha20_poly1305_openssh/struct.SealingKey.html?search=

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

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

### Description
Constructs a new `SealingKey` using the provided 64-byte key material.

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

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

### Initialize NEON-accelerated AES-GCM key

Source: https://docs.rs/ring/0.17.14/src/ring/aead/aes_gcm.rs.html?search=u32+-%3E+bool

Initializes a key using NEON instructions for ARM architectures.

```rust
    #[cfg_attr(target_arch = "aarch64", inline(never))]
    fn new_neon(key: aes::KeyBytes, cpu: cpu::arm::Neon) -> Result<Self, error::Unspecified> {
        let aes_key = aes::vp::Key::new(key, cpu)?;
        let gcm_key_value = derive_gcm_key_value(&aes_key);
        let gcm_key = gcm::neon::Key::new(gcm_key_value, cpu);
        Ok(Self::Simd(Combo { aes_key, gcm_key }))
    }
```

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

### Parse test case attributes

Source: https://docs.rs/ring/0.17.14/src/ring/testutil.rs.html

Parses a test case from an iterator of lines, extracting key-value pairs separated by ' = '. It ignores comments starting with '#' and handles section headers.

```rust
fn parse_test_case(
    current_section: &mut String,
    lines: &mut dyn Iterator<Item = &str>,
) -> Option<TestCase> {
    let mut attributes = Vec::new();

    let mut is_first_line = true;
    loop {
        let line = lines.next();

        #[cfg(feature = "test_logging")]
        if let Some(text) = &line {
            std::println!("Line: {}", text);
        }

        match line {
            // If we get to EOF when we're not in the middle of a test case,
            // then we're done.
            None if is_first_line => {
                return None;
            }

            // End of the file on a non-empty test cases ends the test case.
            None => {
                return Some(TestCase { attributes });
            }

            // A blank line ends a test case if the test case isn't empty.
            Some("") => {
                if !is_first_line {
                    return Some(TestCase { attributes });
                }
                // Ignore leading blank lines.
            }

            // Comments start with '#'; ignore them.
            Some(line) if line.starts_with('#') => (),

            Some(line) if line.starts_with('[') => {
                assert!(is_first_line);
                assert!(line.ends_with(']'));
                current_section.truncate(0);
                current_section.push_str(line);
                let _ = current_section.pop();
                let _ = current_section.remove(0);
            }

            Some(line) => {
                is_first_line = false;

                let parts: Vec<&str> = line.splitn(2, " = ").collect();
                if parts.len() != 2 {
                    panic!("Syntax error: Expected Key = Value.");
                };

                let key = parts[0].trim();
                let value = parts[1].trim();

                // Don't allow the value to be omitted. An empty value can be
                // represented as an empty quoted string.
                assert_ne!(value.len(), 0);

                // Checking is_none() ensures we don't accept duplicate keys.
                attributes.push((String::from(key), String::from(value), false));
            }
        }
    }
}
```

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

### Initialize SIMD and Fallback Keys

Source: https://docs.rs/ring/0.17.14/src/ring/aead/aes_gcm.rs.html

Functions to initialize AES-GCM keys for different architectures including NEON, SSSE3, and fallback implementations.

```rust
    #[cfg_attr(target_arch = "aarch64", inline(never))]
    fn new_neon(key: aes::KeyBytes, cpu: cpu::arm::Neon) -> Result<Self, error::Unspecified> {
        let aes_key = aes::vp::Key::new(key, cpu)?;
        let gcm_key_value = derive_gcm_key_value(&aes_key);
        let gcm_key = gcm::neon::Key::new(gcm_key_value, cpu);
        Ok(Self::Simd(Combo { aes_key, gcm_key }))
    }
```

```rust
    #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
    #[inline(never)]
    fn new_ssse3(
        key: aes::KeyBytes,
        cpu: aes::vp::RequiredCpuFeatures,
    ) -> Result<Self, error::Unspecified> {
        let aes_key = aes::vp::Key::new(key, cpu)?;
        let gcm_key_value = derive_gcm_key_value(&aes_key);
        let gcm_key = gcm::fallback::Key::new(gcm_key_value);
        Ok(Self::Simd(Combo { aes_key, gcm_key }))
    }
```

```rust
    #[cfg_attr(
        any(
            all(target_arch = "aarch64", target_endian = "little"),
            all(target_arch = "arm", target_endian = "little"),
            target_arch = "x86",
            target_arch = "x86_64",
        ),
        inline(never)
    )]
    fn new_fallback(key: aes::KeyBytes) -> Result<Self, error::Unspecified> {
        let aes_key = aes::fallback::Key::new(key)?;
        let gcm_key_value = derive_gcm_key_value(&aes_key);
        let gcm_key = gcm::fallback::Key::new(gcm_key_value);
        Ok(Self::Fallback(Combo { aes_key, gcm_key }))
    }
```

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

### Example Test Vector File Format

Source: https://docs.rs/ring/0.17.14/src/ring/testutil.rs.html

Input files for the testing framework use key-value pairs separated by blank lines. Bytes can be represented as quoted strings or hex sequences.

```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
```

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

### Initialize SSSE3-accelerated AES-GCM key

Source: https://docs.rs/ring/0.17.14/src/ring/aead/aes_gcm.rs.html?search=u32+-%3E+bool

Initializes a key using SSSE3 instructions for x86 architectures.

```rust
    #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
    #[inline(never)]
    fn new_ssse3(
        key: aes::KeyBytes,
        cpu: aes::vp::RequiredCpuFeatures,
    ) -> Result<Self, error::Unspecified> {
        let aes_key = aes::vp::Key::new(key, cpu)?;
        let gcm_key_value = derive_gcm_key_value(&aes_key);
        let gcm_key = gcm::fallback::Key::new(gcm_key_value);
        Ok(Self::Simd(Combo { aes_key, gcm_key }))
    }
```

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

### Feature Flag Initialization

Source: https://docs.rs/ring/0.17.14/src/ring/cpu/intel.rs.html?search=std%3A%3Avec

Handles the dynamic detection of CPU features using OPENSSL_cpuid_setup and manages the initialization state.

```rust
pub(in super::super) fn get_or_init() -> cpu::Features {
        // SAFETY: `OPENSSL_cpuid_setup` must be called only in
        // `INIT.call_once()` below.
        prefixed_extern! {
            fn OPENSSL_cpuid_setup(out: &mut [u32; 4]);
        }

        let _: NonZeroUsize = FEATURES.get_or_init(|| {
            let mut cpuid = [0; 4];
            // SAFETY: We assume that it is safe to execute CPUID and XGETBV.
            unsafe {
                OPENSSL_cpuid_setup(&mut cpuid);
            }
            let detected = super::cpuid_to_caps_and_set_c_flags(&cpuid);
            let merged = CAPS_STATIC | detected;

            let merged = usize_from_u32(merged) | (1 << (super::Shift::Initialized as u32));
            NonZeroUsize::new(merged).unwrap() // Can't fail because we just set a bit.
        });

        // SAFETY: We initialized the CPU features as required.
        // `INIT.call_once` has `happens-before` semantics.
        unsafe { cpu::Features::new_after_feature_flags_written_and_synced_unchecked() }
    }
```

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

### Initialize AES-GCM Keys

Source: https://docs.rs/ring/0.17.14/src/ring/aead/aes_gcm.rs.html?search=

Functions for initializing AES-GCM keys using NEON, SSSE3, or fallback implementations based on target architecture.

```rust
    all(target_arch = "aarch64", target_endian = "little"),
        all(target_arch = "arm", target_endian = "little")
    ))]
    #[cfg_attr(target_arch = "aarch64", inline(never))]
    fn new_neon(key: aes::KeyBytes, cpu: cpu::arm::Neon) -> Result<Self, error::Unspecified> {
        let aes_key = aes::vp::Key::new(key, cpu)?;
        let gcm_key_value = derive_gcm_key_value(&aes_key);
        let gcm_key = gcm::neon::Key::new(gcm_key_value, cpu);
        Ok(Self::Simd(Combo { aes_key, gcm_key }))
    }

    #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
    #[inline(never)]
    fn new_ssse3(
        key: aes::KeyBytes,
        cpu: aes::vp::RequiredCpuFeatures,
    ) -> Result<Self, error::Unspecified> {
        let aes_key = aes::vp::Key::new(key, cpu)?;
        let gcm_key_value = derive_gcm_key_value(&aes_key);
        let gcm_key = gcm::fallback::Key::new(gcm_key_value);
        Ok(Self::Simd(Combo { aes_key, gcm_key }))
    }

    #[cfg_attr(
        any(
            all(target_arch = "aarch64", target_endian = "little"),
            all(target_arch = "arm", target_endian = "little"),
            target_arch = "x86",
            target_arch = "x86_64",
        ),
        inline(never)
    )]
    fn new_fallback(key: aes::KeyBytes) -> Result<Self, error::Unspecified> {
        let aes_key = aes::fallback::Key::new(key)?;
        let gcm_key_value = derive_gcm_key_value(&aes_key);
        let gcm_key = gcm::fallback::Key::new(gcm_key_value);
        Ok(Self::Fallback(Combo { aes_key, gcm_key }))
    }
}
```
Tokens:
Raw