noxtls-crypto 0.2.11

Internal implementation crate for noxtls: hash, symmetric cipher, public-key, and DRBG primitives.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

// Copyright (c) 2019-2026, Argenox Technologies LLC
// All rights reserved.
//
// SPDX-License-Identifier: GPL-2.0-only OR LicenseRef-Argenox-Commercial-License
//
// This file is part of the NoxTLS Library.
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by the
// Free Software Foundation; version 2 of the License.
//
// Alternatively, this file may be used under the terms of a commercial
// license from Argenox Technologies LLC.
//
// See `noxtls/LICENSE` and `noxtls/LICENSE.md` in this repository for full details.
// CONTACT: info@argenox.com

use crate::drbg::HmacDrbgSha256;
use noxtls_core::{Error, Result};

use super::{
    noxtls_mldsa_generate_keypair_auto, noxtls_mldsa_verify, noxtls_mlkem_decapsulate,
    noxtls_mlkem_encapsulate_auto, noxtls_mlkem_generate_keypair_auto,
};

/// Runs deterministic ML-KEM and ML-DSA self-tests for startup-time assurance.
///
/// # Returns
///
/// `Ok(())` when every packaged round-trip succeeds.
///
/// # Errors
///
/// Returns [`Error::InvalidLength`], [`Error::StateError`], or other errors from DRBG setup and PQ primitives, or [`Error::CryptoFailure`] when a self-test assertion fails.
///
/// # Panics
///
/// This function does not panic.
pub fn noxtls_run_pq_self_tests() -> Result<()> {
    run_mlkem_self_test()?;
    run_mldsa_self_test()?;
    Ok(())
}

/// Executes one ML-KEM keygen, encapsulation, and decapsulation round-trip.
///
/// # Returns
///
/// `Ok(())` when sender and receiver shared secrets match.
///
/// # Errors
///
/// Propagates errors from DRBG construction, ML-KEM key generation, encapsulation, or decapsulation, or returns [`Error::CryptoFailure`] on shared-secret mismatch.
///
/// # Panics
///
/// This function does not panic.
fn run_mlkem_self_test() -> Result<()> {
    let mut drbg =
        HmacDrbgSha256::noxtls_new(b"pq-selftest-mlkem-entropy-seed", b"nonce", b"selftest")?;
    let (private, public) = noxtls_mlkem_generate_keypair_auto(&mut drbg)?;
    let (ciphertext, shared_sender) = noxtls_mlkem_encapsulate_auto(&public, &mut drbg)?;
    let shared_receiver = noxtls_mlkem_decapsulate(&private, &ciphertext)?;
    if shared_sender != shared_receiver {
        return Err(Error::CryptoFailure(
            "pq self-test mlkem shared secret mismatch",
        ));
    }
    Ok(())
}

/// Executes one ML-DSA sign and verify cycle plus a tampered-signature negative test.
///
/// # Returns
///
/// `Ok(())` when verification accepts the genuine signature and rejects the flipped-byte variant.
///
/// # Errors
///
/// Propagates errors from DRBG construction, ML-DSA key generation, signing, or verification, or returns [`Error::CryptoFailure`] when tamper detection misbehaves.
///
/// # Panics
///
/// This function does not panic.
fn run_mldsa_self_test() -> Result<()> {
    let mut drbg =
        HmacDrbgSha256::noxtls_new(b"pq-selftest-mldsa-entropy-seed", b"nonce", b"selftest")?;
    let (private, public) = noxtls_mldsa_generate_keypair_auto(&mut drbg)?;
    let message = b"pq-selftest-message";
    let mut signature = private.sign(message);
    noxtls_mldsa_verify(&public, message, &signature)?;
    signature[0] ^= 0x01;
    if noxtls_mldsa_verify(&public, message, &signature).is_ok() {
        return Err(Error::CryptoFailure(
            "pq self-test mldsa tamper check unexpectedly passed",
        ));
    }
    Ok(())
}