Skip to main content

moirai_crypto/
lib.rs

1//! # moirai-crypto
2//!
3//! Pure-Rust cryptographic primitives and an optional `rustls::crypto::CryptoProvider`.
4//!
5//! The standalone SHA-256, HMAC-SHA256 and fixed-width comparison APIs are
6//! available without enabling the `provider` feature. The default feature
7//! enables the complete provider used by the Moirai TLS stack (`moirai-tls`).
8//! All implementations use [RustCrypto](https://github.com/RustCrypto) with
9//! **zero C dependencies**.
10//!
11//! With `provider` enabled, the crate supports the three TLS 1.3 cipher suites,
12//! X25519 and P-256 key exchange, and the ECDSA/RSA signature verification
13//! algorithms required to validate typical web PKI certificate chains — all
14//! implemented in safe, portable Rust.
15//!
16//! ```no_run
17//! # #[cfg(feature = "provider")]
18//! # {
19//! let provider = moirai_crypto::provider();
20//! # }
21//! ```
22
23#![deny(missing_docs)]
24#![forbid(unsafe_code)]
25
26mod primitives;
27
28#[cfg(feature = "provider")]
29mod aead;
30#[cfg(feature = "provider")]
31mod hash;
32#[cfg(feature = "provider")]
33mod hkdf;
34#[cfg(feature = "provider")]
35mod hmac;
36#[cfg(feature = "provider")]
37mod kx;
38#[cfg(feature = "provider")]
39mod random;
40#[cfg(feature = "provider")]
41mod sign;
42#[cfg(feature = "provider")]
43mod verify;
44
45pub use primitives::{
46    Sha1, Sha256, base64_decode, base64_encode, constant_time_eq_32, hmac_sha256, sha1, sha256,
47};
48
49#[cfg(feature = "provider")]
50use std::sync::Arc;
51
52#[cfg(feature = "provider")]
53use rustls::crypto::{CryptoProvider, KeyProvider};
54#[cfg(feature = "provider")]
55use rustls::pki_types::PrivateKeyDer;
56#[cfg(feature = "provider")]
57use rustls::sign::SigningKey;
58#[cfg(feature = "provider")]
59use rustls::{CipherSuite, CipherSuiteCommon, Error, SupportedCipherSuite, Tls13CipherSuite};
60
61#[cfg(feature = "provider")]
62/// Construct a [`CryptoProvider`] backed by RustCrypto (no C dependencies).
63///
64/// The returned provider offers:
65/// - Cipher suites: `TLS13_CHACHA20_POLY1305_SHA256`, `TLS13_AES_128_GCM_SHA256`,
66///   `TLS13_AES_256_GCM_SHA384`.
67/// - Key exchange groups: X25519 and NIST P-256 (secp256r1).
68/// - Signature verification: ECDSA (P-256/P-384) and RSA (PKCS#1 v1.5 and PSS)
69///   with SHA-256/SHA-384.
70#[must_use]
71pub fn provider() -> CryptoProvider {
72    CryptoProvider {
73        cipher_suites: vec![
74            SupportedCipherSuite::Tls13(&TLS13_CHACHA20_POLY1305_SHA256_SUITE),
75            SupportedCipherSuite::Tls13(&TLS13_AES_128_GCM_SHA256_SUITE),
76            SupportedCipherSuite::Tls13(&TLS13_AES_256_GCM_SHA384_SUITE),
77        ],
78        kx_groups: vec![&kx::X25519, &kx::P256],
79        signature_verification_algorithms: verify::ALGORITHMS,
80        secure_random: &random::Getrandom,
81        key_provider: &RustCryptoKeyProvider,
82    }
83}
84
85#[cfg(feature = "provider")]
86static TLS13_CHACHA20_POLY1305_SHA256_SUITE: Tls13CipherSuite = Tls13CipherSuite {
87    common: CipherSuiteCommon {
88        suite: CipherSuite::TLS13_CHACHA20_POLY1305_SHA256,
89        hash_provider: &hash::SHA256,
90        confidentiality_limit: u64::MAX,
91    },
92    hkdf_provider: &hkdf::HKDF_SHA256,
93    aead_alg: &aead::ChaCha20Poly1305,
94    quic: None,
95};
96
97#[cfg(feature = "provider")]
98static TLS13_AES_128_GCM_SHA256_SUITE: Tls13CipherSuite = Tls13CipherSuite {
99    common: CipherSuiteCommon {
100        suite: CipherSuite::TLS13_AES_128_GCM_SHA256,
101        hash_provider: &hash::SHA256,
102        confidentiality_limit: 1 << 23,
103    },
104    hkdf_provider: &hkdf::HKDF_SHA256,
105    aead_alg: &aead::Aes128Gcm,
106    quic: None,
107};
108
109#[cfg(feature = "provider")]
110static TLS13_AES_256_GCM_SHA384_SUITE: Tls13CipherSuite = Tls13CipherSuite {
111    common: CipherSuiteCommon {
112        suite: CipherSuite::TLS13_AES_256_GCM_SHA384,
113        hash_provider: &hash::SHA384,
114        confidentiality_limit: 1 << 23,
115    },
116    hkdf_provider: &hkdf::HKDF_SHA384,
117    aead_alg: &aead::Aes256Gcm,
118    quic: None,
119};
120
121#[cfg(feature = "provider")]
122/// Private-key loader for the provider.
123///
124/// Loads ECDSA (P-256/P-384) and RSA private keys from PKCS#8, SEC1, or PKCS#1
125/// DER, enabling server authentication and client-certificate authentication in
126/// addition to certificate verification.
127#[derive(Debug)]
128struct RustCryptoKeyProvider;
129
130#[cfg(feature = "provider")]
131impl KeyProvider for RustCryptoKeyProvider {
132    fn load_private_key(
133        &self,
134        key_der: PrivateKeyDer<'static>,
135    ) -> Result<Arc<dyn SigningKey>, Error> {
136        sign::any_supported_type(&key_der)
137    }
138}