Crate kychacha_crypto 

Features

Name	Default?	What does it do?
mlkem512	x	Select Ml-Kem security level to 512 (private key size)
mlkem768	✅	Select Ml-Kem security level to 768 (private key size)
mlkem1024	x	Select Ml-Kem security level to 1024 (private key size)
small-buffer	x	Use a 4 KB buffer for encryption and decryption (files < 1 MB), for environments with very restricted amount of ram
recommended-buffer	✅	Use a 64 KB buffer for encryption and decryption (files < 100 MB), recommended value for most use cases.
medium-buffer	x	Use a 8 MB buffer for encryption and decryption (files 100 MB–5 GB), recommended for large files: logs, CSV/JSON, et cetera.
large-buffer	x	Use a 1GB buffer for encryption and decryption (files > 5 GB), recommended for extremely large files like backups and 4K/8K video without compression.

A Simple Example

use std::error::Error;
use kychacha_crypto::{decrypt_stream, encrypt_stream, generate_keypair};
use std::io::Cursor;

fn main() -> Result<(), Box<dyn Error>> {
    // Generate keypairs for alice and bob
    let alice_keypair = generate_keypair()?;
    let bob_keypair = generate_keypair()?;

    // sink for storing the encrypted data
    let mut sink = Vec::new();

    // encrypt the text to bob
    encrypt_stream(bob_keypair.public_key, &mut Cursor::new(b"Hi bob! :D"), &mut sink)?;

    let mut decrypted_bytes = Vec::new();

    decrypt_stream(&bob_keypair.private_key, &mut Cursor::new(sink), &mut decrypted_bytes)?;

    assert_eq!(String::from_utf8_lossy(&decrypted_bytes), "Hi bob! :D");
    Ok(())
}

A Example With files

Multi-recipient Encryption

Encrypt once for N recipients (each gets a wrapped content key) and stream the payload only a single time. Internally: a random 32-byte content key (ChaCha20-Poly1305) is generated; for every recipient public key we perform KEM encapsulation and then AEAD-encrypt the content key with the derived symmetric key. The ciphertext holds: Vec<(kem_ciphertext, aead_wrap_of_content_key)> followed by the bulk-encrypted data.

Example

use std::error::Error;
use std::io::Cursor;
use kychacha_crypto::{
    generate_keypair,
    encrypt_multiple_recipient,
    decrypt_multiple_recipient,
};

fn main() -> Result<(), Box<dyn Error>> {
    // Generate recipients (alice, bob, carol)
    let alice = generate_keypair()?;
    let bob = generate_keypair()?;
    let carol = generate_keypair()?;

    let mut encrypted = Vec::new();
    encrypt_multiple_recipient(
        vec![alice.public_key.clone(), bob.public_key.clone(), carol.public_key.clone()],
        &mut Cursor::new(b"group message"),
        &mut encrypted,
    )?;

    // Any listed recipient can decrypt
    let mut out = Vec::new();
    decrypt_multiple_recipient(&bob.private_key, &mut Cursor::new(&encrypted), &mut out)?;
    assert_eq!(b"group message", &out[..]);
    Ok(())
}

Security Notes

• Each recipient incurs one ML-KEM encapsulation (O(n)).
• Payload is encrypted only once (constant time w.r.t recipients) with ChaCha20-Poly1305.
• Unknown recipient keys simply fail to unwrap; no partial leakage.
• Consider size: header grows roughly (kem_ct_len + 12 + 32 + 16) per recipient.

When to use

• Broadcast to small/medium groups (tens / low hundreds) efficiently.
• Avoid re-encrypting large payloads per recipient.

When not to use

• Extremely large recipient lists (may become bandwidth heavy) — consider distributing the symmetric key via another channel.

Structs

MlKemKeyPair

MlKemKeyPair contains both the private and public KEM keys for ML-KEM operations.

PublicKey

PublicKey holds the public component of an ML-KEM key pair along with its security level.

SecretKey

SecretKey holds the private component of an ML-KEM key pair along with its security level.

Enums

SecurityLevel

SecurityLevel defines the parameter sets (security strengths) supported by the ML-KEM algorithm.

Functions

decryptDeprecated

Decrypts data from a byte slice.

decrypt_multiple_recipient

decrypt_stream

Decrypts data from a stream that implements std::io::Read

encryptDeprecated

Encrypts data from a &[u8].

encrypt_multiple_recipient

encrypt_stream

Hybrid encryption with Kyber + ChaCha

generate_keypair

Generates ML-KEM keypair

generate_keypair_with_level

Generates an ML-KEM keypair for a specified security level (runtime selection).