examples

Examples

Runnable demonstrations of the public rscrypto API. Each example is small enough to read end-to-end and feature-gated to the smallest set that compiles.

Getting Started

If you've never used rscrypto, run basic first. It tours the main API patterns across the primitive families. After that, pick the example that matches what you're trying to do.

If you are replacing an existing crate, start with the matching guide in docs/migration/ and then use these examples to confirm the new API shape.

All examples

basic: API tour across every family

cargo run --example basic --features full,getrandom

Walks through checksums (Crc32C), digests (Sha256, Blake3), MACs (HmacSha256), KDFs (HkdfSha256), XOFs (Shake256, Blake3), fast hashes (Xxh3, RapidHash), AEAD (ChaCha20Poly1305 with a fresh random nonce), hex formatting, secret-key Debug masking, byte-array round-trips through from_bytes / to_bytes / as_bytes, and the std::io::{Read, Write} adapters for streaming digests and checksums. Every section asserts that one-shot equals streaming. That is the API contract every primitive in rscrypto follows.

password_hashing: Argon2id and scrypt with bounded-policy verify

cargo run --example password_hashing --features password-hashing,getrandom

Hashes a password with both Argon2id and scrypt, encodes the result as a PHC string, then verifies it through bounded verify_string. The default verify policy caps the cost parameters the verifier will accept, blocking attacker-supplied high-cost PHC strings. Prints both PHC encodings to stdout so you can inspect the format.

aead_seal_open: ChaCha20-Poly1305 seal/open

cargo run --example aead_seal_open --features chacha20poly1305,getrandom

Generates a ChaCha20-Poly1305 key, seals a short payload with associated data and a fresh random nonce, then opens it back to the original plaintext. This is the smallest AEAD example for the common "encrypt then authenticate" workflow.

signatures: Ed25519 and ECDSA P-256 signing

cargo run --example signatures --features ed25519,ecdsa-p256,getrandom

Generates Ed25519 and ECDSA P-256 keypairs, signs one message with each, and verifies both signatures through the public-key API. Use this when choosing between deterministic Ed25519 and randomized ECDSA protocol surfaces.

rsa_pss_verify: RSA-PSS fixture verification

cargo run --example rsa_pss_verify --features rsa

Loads a checked-in RSA-3072 SubjectPublicKeyInfo fixture and verifies a PSS/SHA-256 signature over a fixed message. This keeps the example deterministic and focused on the verification path used by certificate, package, and protocol integrations.

mlkem_encapsulation: ML-KEM-768 key encapsulation

cargo run --example mlkem_encapsulation --features ml-kem,getrandom

Generates an ML-KEM-768 keypair, encapsulates a shared secret to the public key, decapsulates with the private key, and asserts both sides derived the same bytes. This is the minimal KEM workflow for hybrid key-establishment prototypes.

parallel: CRC chunk combining for large inputs

cargo run --example parallel --features checksums

Shows how rscrypto combines CRC states: given crc(A) and crc(B), you can compute crc(A || B) without ever holding both chunks together. The example checks a two-way split, a multi-part loop, and scoped-thread chunk processing against sequential references. Uses Crc32 and Crc64 (XZ polynomial). The pattern applies to any Checksum type that implements ChecksumCombine.

introspect: Runtime dispatch inspection

cargo run --example introspect --features checksums,hashes,aead,diag

Prints the platform's detected CPU capabilities and reports which kernel the dispatcher selected for representative checksums, hashes, fast hashes, and AEAD backends at useful buffer sizes. Use this when you want to confirm hardware acceleration kicked in on a new platform, or when you're investigating a performance surprise. Requires the diag feature; introspection is opt-in to keep the default binary small.

Pattern reference

To do this	See
Hash data (one-shot or streaming)	basic (digest section)
Compute and verify a MAC	basic (auth section)
Encrypt and decrypt with AEAD	aead_seal_open, basic (AEAD section)
Sign and verify messages	signatures, rsa_pss_verify
Encapsulate and decapsulate a KEM shared secret	mlkem_encapsulation
Hash a password and verify safely	password_hashing
Process a large file in parallel	parallel
Confirm hardware acceleration is active	introspect
Stream a digest through std::io::Read	basic (I/O adapters section)

Beyond examples

• Full API reference: docs.rs/rscrypto
• Algorithm inventory and feature flags: README.md
• Migration guides from RustCrypto, blake3, CRC crates, AEADs, signatures, and password hashing: docs/migration/
• Security posture and constant-time boundaries: README.md#security, docs/constant-time.md