sntrup-sys 0.1.2

//! Rust FFI bindings over the extracted, deduplicated SUPERCOP Streamlined
//! NTRU Prime sources in `vendor/`. Every module wraps one parameter set,
//! all sharing one compiled copy of `vendor/common/` (see
//! `vendor/NOTICE.md` for why the split between shared and per-parameter-
//! set code is drawn where it is). Each enabled parameter set gets its own
//! module (gated by the matching Cargo feature), exposing `keypair()`,
//! `encapsulate(pk)`, and `decapsulate(c, sk)`.
//!
//! # Randomness
//!
//! The vendored C code calls a single external `randombytes` C function for
//! all key generation and encapsulation randomness. This crate implements
//! it here using `getrandom` (the OS CSPRNG), satisfying the one external
//! symbol every vendored directory expects (see vendor/NOTICE.md).
//!
//! # Zeroization
//!
//! The secret key (from `keypair()`) and the shared secret (from
//! `encapsulate()`/`decapsulate()`) are returned as
//! `Zeroizing<[u8; N]>` (from the `zeroize` crate): a fixed-size,
//! stack-allocated buffer that's wiped on drop. The FFI call writes
//! directly into that buffer -- there's no intermediate `Vec` the secret
//! passes through first, so there's nothing left unzeroized after the
//! `Zeroizing` wrapper does its job. `decapsulate()` also *takes* `sk` as
//! `&Zeroizing<[u8; SECRET_KEY_BYTES]>` rather than `&[u8]`, so a secret
//! key that was never wrapped in `Zeroizing` in the first place can't be
//! passed in by accident -- the type is part of the contract, not just a
//! runtime length check. The public key and ciphertext are not secret and
//! stay plain `Vec<u8>`/`&[u8]`.

/// # Safety
///
/// `buf` must be valid for writes of `buf_len` bytes and not aliased by any
/// other live reference for the duration of this call. The vendored C code
/// upholds this by construction (it always passes a real buffer of exactly
/// `buf_len` bytes) but Rust can't verify that across the FFI boundary, so
/// the contract is on the caller, hence `unsafe fn`.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn randombytes(buf: *mut u8, buf_len: u64) {
    let slice = unsafe { std::slice::from_raw_parts_mut(buf, buf_len as usize) };
    getrandom::fill(slice).expect("OS randomness source failed");
}

#[cfg(feature = "sntrup653")]
pub mod sntrup653 {
    use std::os::raw::c_int;
    use zeroize::Zeroizing;

    pub const PUBLIC_KEY_BYTES: usize = 994;
    pub const SECRET_KEY_BYTES: usize = 1518;
    pub const CIPHERTEXT_BYTES: usize = 897;
    pub const SHARED_SECRET_BYTES: usize = 32;

    unsafe extern "C" {
        fn sntrup653_ref_crypto_kem_keypair(pk: *mut u8, sk: *mut u8) -> c_int;
        fn sntrup653_ref_crypto_kem_enc(c: *mut u8, k: *mut u8, pk: *const u8) -> c_int;
        fn sntrup653_ref_crypto_kem_dec(k: *mut u8, c: *const u8, sk: *const u8) -> c_int;
    }

    /// Generate a fresh keypair. Returns `(public_key, secret_key)`; the
    /// secret key is zeroized on drop.
    pub fn keypair() -> (Vec<u8>, Zeroizing<[u8; SECRET_KEY_BYTES]>) {
        let mut pk = vec![0u8; PUBLIC_KEY_BYTES];
        let mut sk = Zeroizing::new([0u8; SECRET_KEY_BYTES]);
        let rc = unsafe { sntrup653_ref_crypto_kem_keypair(pk.as_mut_ptr(), sk.as_mut_ptr()) };
        assert_eq!(rc, 0, "sntrup653_ref_crypto_kem_keypair failed");
        (pk, sk)
    }

    /// Encapsulate against `pk`. Returns `(ciphertext, shared_secret)`; the
    /// shared secret is zeroized on drop.
    pub fn encapsulate(pk: &[u8]) -> (Vec<u8>, Zeroizing<[u8; SHARED_SECRET_BYTES]>) {
        assert_eq!(pk.len(), PUBLIC_KEY_BYTES, "invalid public key length");
        let mut c = vec![0u8; CIPHERTEXT_BYTES];
        let mut ss = Zeroizing::new([0u8; SHARED_SECRET_BYTES]);
        let rc =
            unsafe { sntrup653_ref_crypto_kem_enc(c.as_mut_ptr(), ss.as_mut_ptr(), pk.as_ptr()) };
        assert_eq!(rc, 0, "sntrup653_ref_crypto_kem_enc failed");
        (c, ss)
    }

    /// Decapsulate `c` using `sk`. Returns the shared secret, zeroized on drop.
    ///
    /// `sk` must be a `Zeroizing`-wrapped secret key (exactly what `keypair()`
    /// returns) rather than a bare `&[u8]`, so the type system rules out
    /// passing a secret key that was never protected by `Zeroizing` in the
    /// first place; its length is therefore already guaranteed by the type,
    /// with nothing left to check at runtime.
    ///
    /// Per the Streamlined NTRU Prime KEM spec this always returns *some*
    /// 32-byte value, even for an invalid/malformed ciphertext (implicit
    /// rejection) -- it does not signal failure via the return value, by
    /// design, to avoid a decryption-failure oracle.
    pub fn decapsulate(
        c: &[u8],
        sk: &Zeroizing<[u8; SECRET_KEY_BYTES]>,
    ) -> Zeroizing<[u8; SHARED_SECRET_BYTES]> {
        assert_eq!(c.len(), CIPHERTEXT_BYTES, "invalid ciphertext length");
        let mut ss = Zeroizing::new([0u8; SHARED_SECRET_BYTES]);
        unsafe { sntrup653_ref_crypto_kem_dec(ss.as_mut_ptr(), c.as_ptr(), sk.as_ptr()) };
        ss
    }
}

#[cfg(feature = "sntrup761")]
pub mod sntrup761 {
    use std::os::raw::c_int;
    use zeroize::Zeroizing;

    pub const PUBLIC_KEY_BYTES: usize = 1158;
    pub const SECRET_KEY_BYTES: usize = 1763;
    pub const CIPHERTEXT_BYTES: usize = 1039;
    pub const SHARED_SECRET_BYTES: usize = 32;

    unsafe extern "C" {
        fn sntrup761_ref_crypto_kem_keypair(pk: *mut u8, sk: *mut u8) -> c_int;
        fn sntrup761_ref_crypto_kem_enc(c: *mut u8, k: *mut u8, pk: *const u8) -> c_int;
        fn sntrup761_ref_crypto_kem_dec(k: *mut u8, c: *const u8, sk: *const u8) -> c_int;
    }

    /// Generate a fresh keypair. Returns `(public_key, secret_key)`; the
    /// secret key is zeroized on drop.
    pub fn keypair() -> (Vec<u8>, Zeroizing<[u8; SECRET_KEY_BYTES]>) {
        let mut pk = vec![0u8; PUBLIC_KEY_BYTES];
        let mut sk = Zeroizing::new([0u8; SECRET_KEY_BYTES]);
        let rc = unsafe { sntrup761_ref_crypto_kem_keypair(pk.as_mut_ptr(), sk.as_mut_ptr()) };
        assert_eq!(rc, 0, "sntrup761_ref_crypto_kem_keypair failed");
        (pk, sk)
    }

    /// Encapsulate against `pk`. Returns `(ciphertext, shared_secret)`; the
    /// shared secret is zeroized on drop.
    pub fn encapsulate(pk: &[u8]) -> (Vec<u8>, Zeroizing<[u8; SHARED_SECRET_BYTES]>) {
        assert_eq!(pk.len(), PUBLIC_KEY_BYTES, "invalid public key length");
        let mut c = vec![0u8; CIPHERTEXT_BYTES];
        let mut ss = Zeroizing::new([0u8; SHARED_SECRET_BYTES]);
        let rc =
            unsafe { sntrup761_ref_crypto_kem_enc(c.as_mut_ptr(), ss.as_mut_ptr(), pk.as_ptr()) };
        assert_eq!(rc, 0, "sntrup761_ref_crypto_kem_enc failed");
        (c, ss)
    }

    /// Decapsulate `c` using `sk`. Returns the shared secret, zeroized on drop.
    ///
    /// `sk` must be a `Zeroizing`-wrapped secret key (exactly what `keypair()`
    /// returns) rather than a bare `&[u8]`, so the type system rules out
    /// passing a secret key that was never protected by `Zeroizing` in the
    /// first place; its length is therefore already guaranteed by the type,
    /// with nothing left to check at runtime.
    ///
    /// Per the Streamlined NTRU Prime KEM spec this always returns *some*
    /// 32-byte value, even for an invalid/malformed ciphertext (implicit
    /// rejection) -- it does not signal failure via the return value, by
    /// design, to avoid a decryption-failure oracle.
    pub fn decapsulate(
        c: &[u8],
        sk: &Zeroizing<[u8; SECRET_KEY_BYTES]>,
    ) -> Zeroizing<[u8; SHARED_SECRET_BYTES]> {
        assert_eq!(c.len(), CIPHERTEXT_BYTES, "invalid ciphertext length");
        let mut ss = Zeroizing::new([0u8; SHARED_SECRET_BYTES]);
        unsafe { sntrup761_ref_crypto_kem_dec(ss.as_mut_ptr(), c.as_ptr(), sk.as_ptr()) };
        ss
    }
}

#[cfg(feature = "sntrup857")]
pub mod sntrup857 {
    use std::os::raw::c_int;
    use zeroize::Zeroizing;

    pub const PUBLIC_KEY_BYTES: usize = 1322;
    pub const SECRET_KEY_BYTES: usize = 1999;
    pub const CIPHERTEXT_BYTES: usize = 1184;
    pub const SHARED_SECRET_BYTES: usize = 32;

    unsafe extern "C" {
        fn sntrup857_ref_crypto_kem_keypair(pk: *mut u8, sk: *mut u8) -> c_int;
        fn sntrup857_ref_crypto_kem_enc(c: *mut u8, k: *mut u8, pk: *const u8) -> c_int;
        fn sntrup857_ref_crypto_kem_dec(k: *mut u8, c: *const u8, sk: *const u8) -> c_int;
    }

    /// Generate a fresh keypair. Returns `(public_key, secret_key)`; the
    /// secret key is zeroized on drop.
    pub fn keypair() -> (Vec<u8>, Zeroizing<[u8; SECRET_KEY_BYTES]>) {
        let mut pk = vec![0u8; PUBLIC_KEY_BYTES];
        let mut sk = Zeroizing::new([0u8; SECRET_KEY_BYTES]);
        let rc = unsafe { sntrup857_ref_crypto_kem_keypair(pk.as_mut_ptr(), sk.as_mut_ptr()) };
        assert_eq!(rc, 0, "sntrup857_ref_crypto_kem_keypair failed");
        (pk, sk)
    }

    /// Encapsulate against `pk`. Returns `(ciphertext, shared_secret)`; the
    /// shared secret is zeroized on drop.
    pub fn encapsulate(pk: &[u8]) -> (Vec<u8>, Zeroizing<[u8; SHARED_SECRET_BYTES]>) {
        assert_eq!(pk.len(), PUBLIC_KEY_BYTES, "invalid public key length");
        let mut c = vec![0u8; CIPHERTEXT_BYTES];
        let mut ss = Zeroizing::new([0u8; SHARED_SECRET_BYTES]);
        let rc =
            unsafe { sntrup857_ref_crypto_kem_enc(c.as_mut_ptr(), ss.as_mut_ptr(), pk.as_ptr()) };
        assert_eq!(rc, 0, "sntrup857_ref_crypto_kem_enc failed");
        (c, ss)
    }

    /// Decapsulate `c` using `sk`. Returns the shared secret, zeroized on drop.
    ///
    /// `sk` must be a `Zeroizing`-wrapped secret key (exactly what `keypair()`
    /// returns) rather than a bare `&[u8]`, so the type system rules out
    /// passing a secret key that was never protected by `Zeroizing` in the
    /// first place; its length is therefore already guaranteed by the type,
    /// with nothing left to check at runtime.
    ///
    /// Per the Streamlined NTRU Prime KEM spec this always returns *some*
    /// 32-byte value, even for an invalid/malformed ciphertext (implicit
    /// rejection) -- it does not signal failure via the return value, by
    /// design, to avoid a decryption-failure oracle.
    pub fn decapsulate(
        c: &[u8],
        sk: &Zeroizing<[u8; SECRET_KEY_BYTES]>,
    ) -> Zeroizing<[u8; SHARED_SECRET_BYTES]> {
        assert_eq!(c.len(), CIPHERTEXT_BYTES, "invalid ciphertext length");
        let mut ss = Zeroizing::new([0u8; SHARED_SECRET_BYTES]);
        unsafe { sntrup857_ref_crypto_kem_dec(ss.as_mut_ptr(), c.as_ptr(), sk.as_ptr()) };
        ss
    }
}

#[cfg(feature = "sntrup953")]
pub mod sntrup953 {
    use std::os::raw::c_int;
    use zeroize::Zeroizing;

    pub const PUBLIC_KEY_BYTES: usize = 1505;
    pub const SECRET_KEY_BYTES: usize = 2254;
    pub const CIPHERTEXT_BYTES: usize = 1349;
    pub const SHARED_SECRET_BYTES: usize = 32;

    unsafe extern "C" {
        fn sntrup953_ref_crypto_kem_keypair(pk: *mut u8, sk: *mut u8) -> c_int;
        fn sntrup953_ref_crypto_kem_enc(c: *mut u8, k: *mut u8, pk: *const u8) -> c_int;
        fn sntrup953_ref_crypto_kem_dec(k: *mut u8, c: *const u8, sk: *const u8) -> c_int;
    }

    /// Generate a fresh keypair. Returns `(public_key, secret_key)`; the
    /// secret key is zeroized on drop.
    pub fn keypair() -> (Vec<u8>, Zeroizing<[u8; SECRET_KEY_BYTES]>) {
        let mut pk = vec![0u8; PUBLIC_KEY_BYTES];
        let mut sk = Zeroizing::new([0u8; SECRET_KEY_BYTES]);
        let rc = unsafe { sntrup953_ref_crypto_kem_keypair(pk.as_mut_ptr(), sk.as_mut_ptr()) };
        assert_eq!(rc, 0, "sntrup953_ref_crypto_kem_keypair failed");
        (pk, sk)
    }

    /// Encapsulate against `pk`. Returns `(ciphertext, shared_secret)`; the
    /// shared secret is zeroized on drop.
    pub fn encapsulate(pk: &[u8]) -> (Vec<u8>, Zeroizing<[u8; SHARED_SECRET_BYTES]>) {
        assert_eq!(pk.len(), PUBLIC_KEY_BYTES, "invalid public key length");
        let mut c = vec![0u8; CIPHERTEXT_BYTES];
        let mut ss = Zeroizing::new([0u8; SHARED_SECRET_BYTES]);
        let rc =
            unsafe { sntrup953_ref_crypto_kem_enc(c.as_mut_ptr(), ss.as_mut_ptr(), pk.as_ptr()) };
        assert_eq!(rc, 0, "sntrup953_ref_crypto_kem_enc failed");
        (c, ss)
    }

    /// Decapsulate `c` using `sk`. Returns the shared secret, zeroized on drop.
    ///
    /// `sk` must be a `Zeroizing`-wrapped secret key (exactly what `keypair()`
    /// returns) rather than a bare `&[u8]`, so the type system rules out
    /// passing a secret key that was never protected by `Zeroizing` in the
    /// first place; its length is therefore already guaranteed by the type,
    /// with nothing left to check at runtime.
    ///
    /// Per the Streamlined NTRU Prime KEM spec this always returns *some*
    /// 32-byte value, even for an invalid/malformed ciphertext (implicit
    /// rejection) -- it does not signal failure via the return value, by
    /// design, to avoid a decryption-failure oracle.
    pub fn decapsulate(
        c: &[u8],
        sk: &Zeroizing<[u8; SECRET_KEY_BYTES]>,
    ) -> Zeroizing<[u8; SHARED_SECRET_BYTES]> {
        assert_eq!(c.len(), CIPHERTEXT_BYTES, "invalid ciphertext length");
        let mut ss = Zeroizing::new([0u8; SHARED_SECRET_BYTES]);
        unsafe { sntrup953_ref_crypto_kem_dec(ss.as_mut_ptr(), c.as_ptr(), sk.as_ptr()) };
        ss
    }
}

#[cfg(feature = "sntrup1013")]
pub mod sntrup1013 {
    use std::os::raw::c_int;
    use zeroize::Zeroizing;

    pub const PUBLIC_KEY_BYTES: usize = 1623;
    pub const SECRET_KEY_BYTES: usize = 2417;
    pub const CIPHERTEXT_BYTES: usize = 1455;
    pub const SHARED_SECRET_BYTES: usize = 32;

    unsafe extern "C" {
        fn sntrup1013_ref_crypto_kem_keypair(pk: *mut u8, sk: *mut u8) -> c_int;
        fn sntrup1013_ref_crypto_kem_enc(c: *mut u8, k: *mut u8, pk: *const u8) -> c_int;
        fn sntrup1013_ref_crypto_kem_dec(k: *mut u8, c: *const u8, sk: *const u8) -> c_int;
    }

    /// Generate a fresh keypair. Returns `(public_key, secret_key)`; the
    /// secret key is zeroized on drop.
    pub fn keypair() -> (Vec<u8>, Zeroizing<[u8; SECRET_KEY_BYTES]>) {
        let mut pk = vec![0u8; PUBLIC_KEY_BYTES];
        let mut sk = Zeroizing::new([0u8; SECRET_KEY_BYTES]);
        let rc = unsafe { sntrup1013_ref_crypto_kem_keypair(pk.as_mut_ptr(), sk.as_mut_ptr()) };
        assert_eq!(rc, 0, "sntrup1013_ref_crypto_kem_keypair failed");
        (pk, sk)
    }

    /// Encapsulate against `pk`. Returns `(ciphertext, shared_secret)`; the
    /// shared secret is zeroized on drop.
    pub fn encapsulate(pk: &[u8]) -> (Vec<u8>, Zeroizing<[u8; SHARED_SECRET_BYTES]>) {
        assert_eq!(pk.len(), PUBLIC_KEY_BYTES, "invalid public key length");
        let mut c = vec![0u8; CIPHERTEXT_BYTES];
        let mut ss = Zeroizing::new([0u8; SHARED_SECRET_BYTES]);
        let rc =
            unsafe { sntrup1013_ref_crypto_kem_enc(c.as_mut_ptr(), ss.as_mut_ptr(), pk.as_ptr()) };
        assert_eq!(rc, 0, "sntrup1013_ref_crypto_kem_enc failed");
        (c, ss)
    }

    /// Decapsulate `c` using `sk`. Returns the shared secret, zeroized on drop.
    ///
    /// `sk` must be a `Zeroizing`-wrapped secret key (exactly what `keypair()`
    /// returns) rather than a bare `&[u8]`, so the type system rules out
    /// passing a secret key that was never protected by `Zeroizing` in the
    /// first place; its length is therefore already guaranteed by the type,
    /// with nothing left to check at runtime.
    ///
    /// Per the Streamlined NTRU Prime KEM spec this always returns *some*
    /// 32-byte value, even for an invalid/malformed ciphertext (implicit
    /// rejection) -- it does not signal failure via the return value, by
    /// design, to avoid a decryption-failure oracle.
    pub fn decapsulate(
        c: &[u8],
        sk: &Zeroizing<[u8; SECRET_KEY_BYTES]>,
    ) -> Zeroizing<[u8; SHARED_SECRET_BYTES]> {
        assert_eq!(c.len(), CIPHERTEXT_BYTES, "invalid ciphertext length");
        let mut ss = Zeroizing::new([0u8; SHARED_SECRET_BYTES]);
        unsafe { sntrup1013_ref_crypto_kem_dec(ss.as_mut_ptr(), c.as_ptr(), sk.as_ptr()) };
        ss
    }
}

#[cfg(feature = "sntrup1277")]
pub mod sntrup1277 {
    use std::os::raw::c_int;
    use zeroize::Zeroizing;

    pub const PUBLIC_KEY_BYTES: usize = 2067;
    pub const SECRET_KEY_BYTES: usize = 3059;
    pub const CIPHERTEXT_BYTES: usize = 1847;
    pub const SHARED_SECRET_BYTES: usize = 32;

    unsafe extern "C" {
        fn sntrup1277_ref_crypto_kem_keypair(pk: *mut u8, sk: *mut u8) -> c_int;
        fn sntrup1277_ref_crypto_kem_enc(c: *mut u8, k: *mut u8, pk: *const u8) -> c_int;
        fn sntrup1277_ref_crypto_kem_dec(k: *mut u8, c: *const u8, sk: *const u8) -> c_int;
    }

    /// Generate a fresh keypair. Returns `(public_key, secret_key)`; the
    /// secret key is zeroized on drop.
    pub fn keypair() -> (Vec<u8>, Zeroizing<[u8; SECRET_KEY_BYTES]>) {
        let mut pk = vec![0u8; PUBLIC_KEY_BYTES];
        let mut sk = Zeroizing::new([0u8; SECRET_KEY_BYTES]);
        let rc = unsafe { sntrup1277_ref_crypto_kem_keypair(pk.as_mut_ptr(), sk.as_mut_ptr()) };
        assert_eq!(rc, 0, "sntrup1277_ref_crypto_kem_keypair failed");
        (pk, sk)
    }

    /// Encapsulate against `pk`. Returns `(ciphertext, shared_secret)`; the
    /// shared secret is zeroized on drop.
    pub fn encapsulate(pk: &[u8]) -> (Vec<u8>, Zeroizing<[u8; SHARED_SECRET_BYTES]>) {
        assert_eq!(pk.len(), PUBLIC_KEY_BYTES, "invalid public key length");
        let mut c = vec![0u8; CIPHERTEXT_BYTES];
        let mut ss = Zeroizing::new([0u8; SHARED_SECRET_BYTES]);
        let rc =
            unsafe { sntrup1277_ref_crypto_kem_enc(c.as_mut_ptr(), ss.as_mut_ptr(), pk.as_ptr()) };
        assert_eq!(rc, 0, "sntrup1277_ref_crypto_kem_enc failed");
        (c, ss)
    }

    /// Decapsulate `c` using `sk`. Returns the shared secret, zeroized on drop.
    ///
    /// `sk` must be a `Zeroizing`-wrapped secret key (exactly what `keypair()`
    /// returns) rather than a bare `&[u8]`, so the type system rules out
    /// passing a secret key that was never protected by `Zeroizing` in the
    /// first place; its length is therefore already guaranteed by the type,
    /// with nothing left to check at runtime.
    ///
    /// Per the Streamlined NTRU Prime KEM spec this always returns *some*
    /// 32-byte value, even for an invalid/malformed ciphertext (implicit
    /// rejection) -- it does not signal failure via the return value, by
    /// design, to avoid a decryption-failure oracle.
    pub fn decapsulate(
        c: &[u8],
        sk: &Zeroizing<[u8; SECRET_KEY_BYTES]>,
    ) -> Zeroizing<[u8; SHARED_SECRET_BYTES]> {
        assert_eq!(c.len(), CIPHERTEXT_BYTES, "invalid ciphertext length");
        let mut ss = Zeroizing::new([0u8; SHARED_SECRET_BYTES]);
        unsafe { sntrup1277_ref_crypto_kem_dec(ss.as_mut_ptr(), c.as_ptr(), sk.as_ptr()) };
        ss
    }
}