Skip to main content

hyprstream_rpc/crypto/
mod.rs

1//! Cryptographic primitives for secure RPC communication.
2//!
3//! This module provides:
4//! - Ed25519 digital signatures for request envelope authentication
5//! - Diffie-Hellman key exchange (Ristretto255 or ECDH P-256 in FIPS mode)
6//! - Chained MACs for streaming response authentication
7//! - Backend abstraction for KDF and MAC operations
8//!
9//! # Chained MAC
10//!
11//! Streaming responses use chained MACs where each chunk's MAC depends
12//! on the previous chunk's MAC. This provides cryptographic ordering
13//! without explicit sequence numbers:
14//!
15//! ```text
16//! mac_0 = MAC(key, request_id_bytes || data_0)
17//! mac_n = MAC(key, mac_{n-1} || data_n)
18//! ```
19//!
20//! # Feature Flags
21//!
22//! - Default: Blake3 for KDF and MAC (~10+ GB/s with SIMD)
23//! - `fips`: HKDF-SHA256 + HMAC-SHA256 (NIST SP 800-56C, FIPS 198-1)
24//!
25//! Key exchange:
26//! - Default: Ristretto255 (prime-order group, no cofactor issues)
27//! - `fips`: ECDH P-256 for FIPS 140-2 compliance
28
29// Generic crypto primitives now live in the light `hyprstream-crypto` crate.
30// Re-exported here so existing `crate::crypto::{backend,cose_sign,cose_sign1,hmac,pq}`
31// (and external `hyprstream_rpc::crypto::…`) paths keep compiling unchanged (#916).
32pub use hyprstream_crypto::{backend, cose_sign, cose_sign1, hmac, pq};
33
34pub mod broadcast_primitives;
35pub mod cose_encrypt;
36pub mod event_crypto;
37pub mod group_key;
38pub mod hybrid_kem;
39pub mod key_exchange;
40pub mod signing;
41
42/// Policy-selected envelope/token signature suite.
43///
44/// This REPLACES the old compile-time `pq-hybrid` cargo feature. PQ primitives
45/// (ML-DSA-65, ML-KEM-768) are always compiled. Production exposes only the
46/// pinned hybrid suite: there is no runtime algorithm negotiation or downgrade.
47///
48/// - `Hybrid` (default): sign with a COSE composite (EdDSA + ML-DSA-65) and
49///   REQUIRE both components to verify.
50#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
51pub enum CryptoPolicy {
52    /// Test-only EdDSA mode for low-level compatibility fixtures. This variant
53    /// is absent from every production library build.
54    #[cfg(any(test, feature = "test-classical-policy"))]
55    Classical,
56    /// Pinned EdDSA + ML-DSA-65 composite suite. Default and mandatory.
57    #[default]
58    Hybrid,
59}
60
61impl CryptoPolicy {
62    /// Whether this policy emits/requires the post-quantum (ML-DSA-65) component.
63    pub fn uses_pq(self) -> bool {
64        match self {
65            #[cfg(any(test, feature = "test-classical-policy"))]
66            CryptoPolicy::Classical => false,
67            CryptoPolicy::Hybrid => true,
68        }
69    }
70}
71
72pub use backend::{derive_key, keyed_mac, keyed_mac_truncated, keyed_mac_truncated_parts};
73pub use hmac::StreamHmacState;
74pub use key_exchange::{
75    derive_notification_keys, derive_stream_keys, DefaultKeyExchange, KeyExchange,
76    NotificationKeys, SharedSecret, StreamKeys,
77};
78pub use signing::{
79    generate_signing_keypair, signing_key_from_bytes, verifying_key_from_bytes, SigningKey,
80    VerifyingKey,
81};
82
83#[cfg(not(feature = "fips"))]
84pub use key_exchange::{
85    blinded_dh, blinded_dh_raw, generate_ephemeral_keypair, reconstruct_blinded_pub_raw,
86    rerandomize_pubkey, ristretto_dh, ristretto_dh_raw, RistrettoKeyExchange, RistrettoPublic,
87    RistrettoSecret,
88};
89
90#[cfg(feature = "fips")]
91pub use key_exchange::{
92    generate_ephemeral_keypair, p256_dh, EcdhP256KeyExchange, P256PublicKey, P256SecretKey,
93};