oxicrypto-adapter-aws-lc — aws-lc-rs backend for OxiCrypto

oxicrypto-adapter-aws-lc implements the core OxiCrypto traits (Aead, Hash, Signer, Verifier from oxicrypto-core) on top of aws-lc-rs, the FIPS-validated cryptographic library maintained by AWS. It lets an application that is already written against the OxiCrypto trait surface swap selected primitives for the hardware-accelerated, FIPS-mode aws-lc-rs implementations without changing call sites.

Not Pure Rust. aws-lc-rs wraps the AWS-LC C library (a BoringSSL/OpenSSL derivative) and pulls in a C toolchain (or a prebuilt binary) at build time. This adapter is therefore C/FFI-backed, in deliberate contrast to the default Pure-Rust OxiCrypto stack. It is opt-in and non-default: the crate exposes no types unless the aws-lc feature is enabled, and the parent oxicrypto facade only re-exports it under oxicrypto::aws_lc when built with features = ["aws-lc"]. Use it when FIPS 140 validation or AWS-LC parity is a hard requirement; otherwise prefer the Pure-Rust crates.

Installation

[dependencies]
# Types are only compiled in when the `aws-lc` feature is on.
oxicrypto-adapter-aws-lc = { version = "0.1.0", features = ["aws-lc"] }

Or, more commonly, enable it transitively through the facade:

[dependencies]
oxicrypto = { version = "0.1.0", features = ["aws-lc"] }

A C compiler / build environment compatible with aws-lc-rs is required at build time. See the aws-lc-rs requirements for platform details.

Quick Start

# #[cfg(feature = "aws-lc")]
# {
use oxicrypto_adapter_aws_lc::aead::AwsLcAead;
use oxicrypto_core::Aead;

let cipher = AwsLcAead::aes256_gcm();
let key = vec![0x42u8; cipher.key_len()];   // 32 bytes
let nonce = vec![0x11u8; cipher.nonce_len()]; // 12 bytes
let aad = b"associated data";
let plaintext = b"secret payload";

// ct buffer must hold plaintext + tag_len() bytes.
let mut ct = vec![0u8; plaintext.len() + cipher.tag_len()];
let written = cipher.seal(&key, &nonce, aad, plaintext, &mut ct)?;

let mut recovered = vec![0u8; plaintext.len()];
cipher.open(&key, &nonce, aad, &ct[..written], &mut recovered)?;
assert_eq!(&recovered, plaintext);
# }
# Ok::<(), oxicrypto_core::CryptoError>(())

Signing with the aws-lc-rs Ed25519 backend:

# #[cfg(feature = "aws-lc")]
# {
use oxicrypto_adapter_aws_lc::sign::{AwsLcEd25519Signer, AwsLcEd25519Verifier};
use oxicrypto_core::{Signer, Verifier};

let signer = AwsLcEd25519Signer;
let seed = [0x5au8; 32];          // 32-byte Ed25519 seed
let msg = b"message to sign";
let mut sig = [0u8; 64];
signer.sign(&seed, msg, &mut sig)?;

// (public key derived out-of-band, e.g. via aws-lc-rs Ed25519KeyPair)
# }
# Ok::<(), oxicrypto_core::CryptoError>(())

API Overview

All items below are compiled only when the aws-lc feature is enabled.

aead module

The Aead impl provides name(), key_len(), nonce_len(), tag_len(), seal(...), and open(...) (plus the *_to_vec default helpers from the trait). nonce_len() is 12 and tag_len() is 16 for every variant.

hash module

Each is a unit struct (Debug + Default + Clone + Copy) exposing the Hash trait methods name(), output_len(), hash() (and the hash_to_vec default helper).

sign module

All four are unit structs (Debug + Default + Clone + Copy).

Feature Flags

Error variants

This adapter returns the shared oxicrypto_core::CryptoError. The variants it actually produces are:

Cross-references

• oxicrypto-core — the Aead, Hash, Signer, Verifier, and CryptoError definitions this adapter implements.
• oxicrypto — Pure-Rust facade; re-exports this adapter at oxicrypto::aws_lc under the aws-lc feature.
• oxicrypto-aead / oxicrypto-hash / oxicrypto-sig — the Pure-Rust counterparts these primitives can substitute for.
• oxicrypto-adapter-pkcs11 — the other opt-in, non-Pure-Rust adapter (HSM via PKCS#11).
• oxicrypto-bench — benchmarks that compare OxiCrypto against aws-lc-rs and ring.

License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)