phalanx_crypto/
lib.rs

1//! # Phalanx Protocol
2//!
3//! A general-purpose group E2E encryption protocol designed for maximum security and flexibility.
4//!
5//! Phalanx provides cryptographically secure group communication with forward secrecy,
6//! post-compromise security, and efficient key rotation. While designed for Legion Protocol,
7//! it can be used by any communication system requiring group E2E encryption.
8//!
9//! ## Features
10//!
11//! - **Double Ratchet** for forward secrecy and post-compromise security
12//! - **Group key agreement** using X25519 key exchange
13//! - **ChaCha20-Poly1305** for authenticated encryption
14//! - **BLAKE3** for key derivation and message authentication
15//! - **Ed25519** for digital signatures
16//! - **Flexible transport layer** - works over any reliable channel
17//! - **Zero-knowledge proofs** for membership verification (planned)
18//!
19//! ## Security Properties
20//!
21//! - **End-to-End Encryption**: Only group members can decrypt messages
22//! - **Forward Secrecy**: Past messages remain secure even if current keys are compromised
23//! - **Post-Compromise Security**: Future messages remain secure after key compromise recovery
24//! - **Authentication**: All messages are cryptographically authenticated
25//! - **Deniability**: Messages cannot be proven to have been sent by a specific user
26//! - **Metadata Protection**: Minimal metadata leakage
27//!
28//! ## Basic Usage
29//!
30//! ```rust
31//! use phalanx::{PhalanxGroup, Identity, GroupMessage};
32//!
33//! // Create a new identity
34//! let identity = Identity::generate();
35//!
36//! // Create or join a group
37//! let mut group = PhalanxGroup::new(identity);
38//!
39//! // Encrypt a message
40//! let plaintext = b"Hello, secure world!";
41//! let encrypted = group.encrypt_message(plaintext)?;
42//!
43//! // Decrypt a message
44//! let decrypted = group.decrypt_message(&encrypted)?;
45//! assert_eq!(decrypted, plaintext);
46//! # Ok::<(), phalanx::PhalanxError>(())
47//! ```
48
49#![warn(missing_docs, rustdoc::missing_crate_level_docs)]
50#![deny(unsafe_code)]
51
52pub mod identity;
53pub mod group;
54pub mod message;
55pub mod crypto;
56pub mod error;
57pub mod protocol;
58pub mod key_manager;
59
60#[cfg(feature = "async")]
61pub mod async_group;
62
63// Re-export main types for convenience
64pub use identity::{Identity, PublicKey, PrivateKey};
65pub use group::{PhalanxGroup, GroupConfig, MembershipProof};
66pub use message::{GroupMessage, MessageContent, MessageType, EncryptedMessage};
67pub use error::{PhalanxError, Result};
68pub use protocol::{ProtocolVersion, HandshakeMessage, KeyRotationMessage};
69pub use key_manager::{AdvancedKeyManager, KeyBackupStorage, HsmProvider};
70
71#[cfg(feature = "async")]
72pub use async_group::AsyncPhalanxGroup;
73
74/// Protocol constants
75pub mod constants {
76    /// Maximum supported group size
77    pub const MAX_GROUP_SIZE: usize = 1000;
78    
79    /// Key rotation interval in seconds (24 hours by default)
80    pub const DEFAULT_KEY_ROTATION_INTERVAL: u64 = 24 * 60 * 60;
81    
82    /// Maximum message size in bytes (1MB)
83    pub const MAX_MESSAGE_SIZE: usize = 1024 * 1024;
84    
85    /// Current protocol version
86    pub const PROTOCOL_VERSION: u8 = 1;
87    
88    /// Minimum supported protocol version
89    pub const MIN_PROTOCOL_VERSION: u8 = 1;
90}
91
92/// Cryptographic parameters and algorithms used by Phalanx
93pub mod algorithms {
94    /// AEAD algorithm used for message encryption
95    pub const AEAD: &str = "ChaCha20-Poly1305";
96    
97    /// Key exchange algorithm
98    pub const KEY_EXCHANGE: &str = "X25519";
99    
100    /// Signature algorithm
101    pub const SIGNATURE: &str = "Ed25519";
102    
103    /// Hash and KDF algorithm
104    pub const HASH_KDF: &str = "BLAKE3";
105    
106    /// Key size in bytes
107    pub const KEY_SIZE: usize = 32;
108    
109    /// Nonce size in bytes
110    pub const NONCE_SIZE: usize = 12;
111    
112    /// Authentication tag size in bytes
113    pub const TAG_SIZE: usize = 16;
114}
115
116#[cfg(test)]
117mod tests {
118    use super::*;
119    
120    #[test]
121    fn test_basic_encryption_flow() {
122        let identity = Identity::generate();
123        let mut group = PhalanxGroup::new(identity);
124        
125        let content = MessageContent::text("Test message");
126        let encrypted = group.encrypt_message(&content).unwrap();
127        let decrypted = group.decrypt_message(&encrypted).unwrap();
128        
129        assert_eq!(decrypted, content);
130    }
131}
phalanx_crypto/lib.rs

phalanx_crypto/
lib.rs
