Rust crate implementing the cryptographic core of Hush. Wraps OpenMLS 0.8.1 (RFC 9420) and is compiled to WASM for use in the web client via wasm-pack. All encryption happens here - the server never sees plaintext.
| Operation | Description |
|---|---|
| Credential generation | Creates an Ed25519 BasicCredential for MLS group membership |
| KeyPackage creation | Builds one-time-use MLS KeyPackages for asynchronous group add |
| Group operations | Create group, add/remove members, commit, process incoming commits |
| Message encryption | MlsGroup::create_message(plaintext) → MLS Application Message ciphertext |
| Message decryption | process_message(ciphertext) → plaintext, epoch validated |
export_secret |
Derives AES-256-GCM keys for voice frame encryption and guild metadata encryption |
| Metadata encryption | AES-256-GCM encrypt/decrypt using keys derived from MLS export_secret() |
MLS_256_XWING_CHACHA20POLY1305_SHA256_Ed25519 (0x004D)
| Primitive | Algorithm | Specification |
|---|---|---|
| Key encapsulation | X-Wing hybrid KEM | X-Wing draft |
| Symmetric encryption | ChaCha20-Poly1305 | RFC 8439 |
| Hash | SHA-256 | FIPS 180-4 |
| Signature | Ed25519 | RFC 8032 |
cargo buildRequires wasm-pack:
# Install wasm-pack if needed
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
# Build for web target (generates pkg/ directory)
wasm-pack build --target webThe build output in pkg/ contains:
hush_crypto.js- ES module JS bindingshush_crypto_bg.wasm- WASM binaryhush_crypto.d.ts- TypeScript type definitionspackage.json- npm package metadata
The hush-web client installs the WASM package from npmjs.org as @gethush/hush-crypto.
# Run all tests
cargo test
# Run with output
cargo test -- --nocapture
# Run a specific test
cargo test group::tests::test_create_group
# Audit dependencies for known vulnerabilities
cargo auditAll tests run on the native target. WASM-specific behavior is tested in hush-web using Vitest with @vitest/browser.
The compiled WASM package is published to npmjs.com as @gethush/hush-crypto. No extra authentication is needed to install it.
All public API is exposed via wasm.rs using wasm-bindgen. Key types and functions:
// Generate a new Ed25519 BasicCredential
pub fn generate_credential(identity: &[u8]) -> Result<Credential, JsValue>// Create a new one-time-use KeyPackage
pub fn create_key_package(credential: &Credential) -> Result<KeyPackageBundle, JsValue>// Create a new group
pub fn create_group(group_id: &[u8], credential: &Credential) -> Result<MlsGroup, JsValue>
// Add a member via their KeyPackage
pub fn add_member(group: &mut MlsGroup, key_package: &[u8]) -> Result<AddResult, JsValue>
// Remove a member
pub fn remove_member(group: &mut MlsGroup, member_index: u32) -> Result<CommitResult, JsValue>
// Encrypt a message
pub fn create_message(group: &mut MlsGroup, plaintext: &[u8]) -> Result<Vec<u8>, JsValue>
// Process an incoming commit, welcome, or application message
pub fn process_message(group: &mut MlsGroup, message: &[u8]) -> Result<ProcessedMessage, JsValue>
// Derive an epoch-scoped export secret (for voice frame keys, metadata keys)
pub fn export_secret(group: &MlsGroup, label: &str, length: usize) -> Result<Vec<u8>, JsValue>// AES-256-GCM encrypt using an MLS-derived key
pub fn encrypt_metadata(key: &[u8], plaintext: &[u8]) -> Result<Vec<u8>, JsValue>
// AES-256-GCM decrypt
pub fn decrypt_metadata(key: &[u8], ciphertext: &[u8]) -> Result<Vec<u8>, JsValue>hush-crypto/
├── src/
│ ├── credential.rs # Ed25519 BasicCredential generation
│ ├── key_package.rs # MLS KeyPackage builder
│ ├── group.rs # Group operations: create, add/remove, commit, export_secret
│ ├── metadata.rs # AES-256-GCM metadata encryption (key from export_secret)
│ └── wasm.rs # wasm-bindgen JS bindings
├── tests/ # Integration tests (native target)
├── Cargo.toml
└── Cargo.lock
See CONTRIBUTING.md.
AGPL-3.0. If you modify this crate and distribute it (including as part of a compiled application), you must publish your changes under the same license.