Herolib Crypt

Comprehensive cryptography library for Rust providing asymmetric, symmetric, and HTTP signature functionality.

Overview

herolib-crypt provides comprehensive cryptographic primitives for the HeroLib ecosystem with optional feature flags for selective compilation.

Features

• Asymmetric Cryptography

  • Ed25519 digital signatures (signing/verification)
  • X25519 ECDH encryption (encrypt/decrypt)
  • Dual keypair architecture (separate keys for signing and encryption)

• Symmetric Cryptography

  • XChaCha20-Poly1305 authenticated encryption
  • Argon2id password-based key derivation
  • Secure key handling with automatic memory zeroization

• HTTP Message Signatures

  • RFC 9421/9530 compliant request authentication
  • Ed25519-based digital signatures for HTTP requests
  • Replay protection and tampering detection

• Ed25519 Keys Module

  • Fast, secure elliptic curve signatures
  • Comprehensive key serialization utilities
  • Constant-time operations for security

• Unified Rhai Integration: Single registration function for all modules

Feature Flags

• httpsig (default): HTTP Message Signatures
• rhai: Enable Rhai scripting support
• full: Enable all features (httpsig + rhai)

Note: The keys module is always included as it's essential for core functionality.

Installation

Add to your Cargo.toml:

[dependencies]
# Default: httpsig enabled
herolib-crypt = { workspace = true }

# Everything including Rhai
herolib-crypt = { workspace = true, features = ["full"] }

# Only core functionality (no HTTP signatures or Rhai)
herolib-crypt = { workspace = true, default-features = false }

Quick Start

Asymmetric: Generate a Keypair

use herolib_crypt::generate_keypair;

let keypair = generate_keypair()?;

// For signing (Ed25519)
println!("Signing Private: {}", keypair.private_key_hex);
println!("Signing Public:  {}", keypair.public_key_hex);

// For encryption (X25519)
println!("Encryption Private: {}", keypair.encryption_private_key_hex);
println!("Encryption Public:  {}", keypair.encryption_public_key_hex);

Asymmetric: Sign and Verify Messages

use herolib_crypt::{generate_keypair, sign_message, verify_signature};

// Generate keypair
let keypair = generate_keypair()?;

// Sign a message (uses Ed25519 signing key)
let message = "Hello, world!";
let signature = sign_message(message, &keypair.private_key_hex)?;

// Verify the signature (uses Ed25519 public key)
let is_valid = verify_signature(message, &signature, &keypair.public_key_hex)?;
assert!(is_valid);

Asymmetric: Encrypt and Decrypt Messages

use herolib_crypt::{generate_keypair, encrypt_message, decrypt_message};

// Alice and Bob generate their keypairs
let alice = generate_keypair()?;
let bob = generate_keypair()?;

// Alice encrypts a message for Bob (uses Bob's X25519 encryption public key)
let message = "Secret message";
let encrypted = encrypt_message(message, &bob.encryption_public_key_hex)?;

// Bob decrypts with his X25519 encryption private key
let decrypted = decrypt_message(&encrypted, &bob.encryption_private_key_hex)?;
assert_eq!(decrypted, message);

Symmetric: Password-Based Encryption (Recommended)

use herolib_crypt::symmetric::{encrypt_with_password, decrypt_with_password};

// Encrypt with just a password - salt is handled automatically!
let encrypted = encrypt_with_password(b"secret data", "my-password")?;

// Decrypt with the same password
let decrypted = decrypt_with_password(&encrypted, "my-password")?;
assert_eq!(decrypted, b"secret data");

Symmetric: String Encryption

use herolib_crypt::symmetric::{encrypt_string, decrypt_string};

// Encrypt string to base64
let encrypted = encrypt_string("Hello, World!", "my-password")?;

// Decrypt back to string
let decrypted = decrypt_string(&encrypted, "my-password")?;
assert_eq!(decrypted, "Hello, World!");

Symmetric: Advanced - Random Key

use herolib_crypt::symmetric::{EncryptionKey, Cipher};

// Generate a random key (for programmatic key management)
let key = EncryptionKey::generate();
let cipher = Cipher::new(key);

// Encrypt and decrypt
let encrypted = cipher.encrypt(b"secret data")?;
let decrypted = cipher.decrypt(&encrypted)?;

Ed25519 Keys Module

use herolib_crypt::keys::Ed25519Keypair;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Generate a keypair
    let keypair = Ed25519Keypair::generate()?;
    
    // Sign a message
    let message = b"Hello, World!";
    let signature = keypair.sign(message);
    
    // Verify the signature
    let public_key = keypair.public_key();
    let valid = public_key.verify(message, &signature)?;
    assert!(valid);
    
    Ok(())
}

Key Serialization

use herolib_crypt::keys::Ed25519Keypair;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let keypair = Ed25519Keypair::generate()?;
    
    // Export as hex
    let private_hex = keypair.to_hex();
    let public_hex = keypair.to_public_key_hex();
    
    // Import from hex
    let restored = Ed25519Keypair::from_hex(&private_hex)?;
    
    // Export as bytes
    let private_bytes = keypair.to_bytes();
    let public_bytes = keypair.to_public_key_bytes();
    
    Ok(())
}

HTTP Message Signatures

use herolib_crypt::keys::Ed25519Keypair;
use herolib_crypt::httpsig::HttpSigner;
use http::Request;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Generate keypair
    let keypair = Ed25519Keypair::generate()?;
    let signer = HttpSigner::new(keypair, "user-123");
    
    // Sign an HTTP request
    let body = b"{\"amount\": 100}";
    let mut request = Request::post("https://api.example.com/payments")
        .header("content-type", "application/json")
        .body(body.to_vec())?;
    
    signer.sign_request(&mut request, body)?;
    // Request now has Signature-Input, Signature, and Content-Digest headers
    
    Ok(())
}

Verifying HTTP Signatures

use herolib_crypt::httpsig::HttpVerifier;
use herolib_crypt::keys::Ed25519PublicKey;
use http::Request;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Get the public key (e.g., from hex string stored in database)
    let public_key_hex = "..."; // The signer's public key
    let public_key = Ed25519PublicKey::from_hex(public_key_hex)?;
    
    // Create verifier with a public key
    let verifier = HttpVerifier::new()
        .with_key(public_key)
        .with_tolerance(60); // 1 minute tolerance
    
    // Verify the request (with signature headers from client)
    let body = b"{\"amount\": 100}";
    let request = Request::post("https://api.example.com/payments")
        .header("content-type", "application/json")
        .header("signature-input", "sig1=(...)")
        .header("signature", "sig1=:...:")
        .header("content-digest", "sha-256=:...:")
        .body(body.to_vec())?;
    
    let result = verifier.verify_request(&request, body)?;
    println!("✓ Verified! Key ID: {}", result.key_id);
    
    Ok(())
}

Rhai Integration

The crypt module provides unified Rhai registration:

use rhai::Engine;
use herolib_crypt::rhai::register_crypto_module;

let mut engine = Engine::new();
register_crypto_module(&mut engine)?;

This registers all functions from both keys and httpsig modules.

Rhai Example

// Generate keypair
let keypair = ed25519_generate();
let public_key = public_key(keypair);

// Sign HTTP request
let signer = httpsig_signer_new(keypair, "user-123");
let result = httpsig_sign(
    signer,
    "POST",
    "/api/payments",
    "api.example.com",
    #{},
    `{"amount": 100}`
);

// Verify signature
let verifier = httpsig_verifier_new();
let verifier = httpsig_verifier_with_key(verifier, public_key);

let headers = #{
    "signature-input": result.signature_input,
    "signature": result.signature,
    "content-digest": result.content_digest
};

let verify_result = httpsig_verify(
    verifier,
    "POST",
    "/api/payments",
    "api.example.com",
    headers,
    `{"amount": 100}`
);

if verify_result.verified {
    print(`✓ Verified by ${verify_result.key_id}`);
}

Module Structure

herolib-crypt
├── asymmetric (always included)
│   ├── Ed25519 signing (delegates to keys module)
│   └── X25519 encryption
├── symmetric (always included)
│   ├── XChaCha20-Poly1305 encryption
│   └── Argon2id key derivation
├── keys (always included)
│   ├── Ed25519Keypair
│   ├── Ed25519PublicKey
│   ├── Signature
│   ├── KeyError
│   └── utility functions
├── httpsig (feature: httpsig)
│   ├── HttpSigner
│   ├── HttpVerifier
│   ├── HttpSigError
│   └── utility functions
└── rhai (feature: rhai)
    ├── register() - unified registration
    ├── keys::rhai::register()
    └── httpsig::rhai::register()

API Reference

Asymmetric Key Generation

• generate_keypair() -> CryptoResult<KeyPair> - Generate a new dual keypair (Ed25519 + X25519)
• public_key_from_private(private_key_hex) -> CryptoResult<String> - Derive Ed25519 public key
• encryption_public_key_from_private(encryption_private_key_hex) -> CryptoResult<String> - Derive X25519 public key

Asymmetric Signing (Ed25519)

• sign_message(message, private_key_hex) -> CryptoResult<String> - Sign a message
• verify_signature(message, signature_hex, public_key_hex) -> CryptoResult<bool> - Verify a signature

Asymmetric Encryption (X25519 + ChaCha20-Poly1305)

• encrypt_message(message, recipient_encryption_public_key_hex) -> CryptoResult<String> - Encrypt for a recipient
• decrypt_message(encrypted_hex, encryption_private_key_hex) -> CryptoResult<String> - Decrypt a message

Symmetric Encryption (Simple API)

• encrypt_with_password(data, password) -> SymmetricResult<Vec<u8>> - Encrypt with password
• decrypt_with_password(encrypted, password) -> SymmetricResult<Vec<u8>> - Decrypt with password
• encrypt_string(text, password) -> SymmetricResult<String> - Encrypt string to base64
• decrypt_string(encrypted_base64, password) -> SymmetricResult<String> - Decrypt base64 to string

Symmetric Encryption (Advanced API)

• EncryptionKey::generate() -> EncryptionKey - Generate a random 256-bit key
• EncryptionKey::derive_from_password(password, salt) -> SymmetricResult<EncryptionKey> - Derive key from password
• Cipher::new(key) -> Cipher - Create a cipher
• Cipher::encrypt(plaintext) -> SymmetricResult<Vec<u8>> - Encrypt data
• Cipher::decrypt(ciphertext) -> SymmetricResult<Vec<u8>> - Decrypt data

Keys Module

Ed25519Keypair

• generate() -> Result<Ed25519Keypair, KeyError> - Generate new keypair
• from_bytes(bytes: &[u8]) -> Result<Ed25519Keypair, KeyError> - Import from bytes
• from_hex(hex: &str) -> Result<Ed25519Keypair, KeyError> - Import from hex
• sign(&self, message: &[u8]) -> Signature - Sign message
• verify(&self, message: &[u8], signature: &Signature) -> Result<bool, KeyError> - Verify signature
• public_key(&self) -> Ed25519PublicKey - Get public key
• to_bytes(&self) -> Vec<u8> - Export private key as bytes
• to_hex(&self) -> String - Export private key as hex
• to_public_key_bytes(&self) -> Vec<u8> - Export public key as bytes
• to_public_key_hex(&self) -> String - Export public key as hex

Keys Utility Functions

• generate_random_bytes(size: usize) -> Vec<u8> - Generate cryptographically secure random bytes
• encode_hex(data: &[u8]) -> String - Encode bytes to hex string
• decode_hex(hex: &str) -> Result<Vec<u8>, KeyError> - Decode hex string to bytes
• sha256_digest(data: &[u8]) -> Vec<u8> - Compute SHA-256 hash
• secure_compare(a: &[u8], b: &[u8]) -> bool - Constant-time comparison
• verify_ed25519(pubkey: &[u8], message: &[u8], signature: &[u8]) -> Result<bool, KeyError> - Standalone verification

HTTP Signatures Module

HttpSigner

• new(keypair: Ed25519Keypair, key_id: impl Into<String>) -> Self - Create new signer
• with_headers(self, headers: Vec<String>) -> Self - Add headers to sign
• with_label(self, label: impl Into<String>) -> Self - Set signature label (default: "sig1")
• sign_request(&self, request: &mut Request<Vec<u8>>, body: &[u8]) -> Result<(), HttpSigError> - Sign HTTP request

HttpVerifier

• new() -> Self - Create new verifier
• with_key(self, key: Ed25519PublicKey) -> Self - Set public key for verification
• with_key_getter(self, getter: Box<dyn Fn(&str) -> Result<Ed25519PublicKey, KeyError>>) -> Self - Set dynamic key lookup
• with_tolerance(self, seconds: u64) -> Self - Set timestamp tolerance (default: 60s)
• verify_request(&self, request: &Request<Vec<u8>>, body: &[u8]) -> Result<VerificationResult, HttpSigError> - Verify HTTP request

Wire Format

When a request is signed, it includes these headers:

POST /api/v1/payments HTTP/1.1
Host: api.example.com
Content-Type: application/json
Content-Digest: sha-256=:X48E9qHmRKpD1nxWnGjcKuXG7AEn9ELUE30CQSY9p3w=:
Signature-Input: sig1=("@method" "@path" "@authority" "content-digest");keyid="user-123";alg="ed25519";created=1735652986
Signature: sig1=:p7By5l82mNkP9qHmRKpD1nxWnGjcKuXG7AEn9ELUE30CQSY9p3w=:

{"amount": 100}

Key Formats

All keys are represented as hex strings:

Key Type	Size (bytes)	Hex Length
Ed25519 Private Key	32	64 chars
Ed25519 Public Key	32	64 chars
X25519 Private Key	32	64 chars
X25519 Public Key	32	64 chars
Ed25519 Signature	64	128 chars

Security Properties

Signing (Ed25519)

• Deterministic: Same message + key = same signature
• Unforgeable: Cannot create valid signature without the private key
• Verifiable: Anyone with public key can verify authenticity

Encryption (X25519 + ChaCha20-Poly1305)

• Confidential: Only recipient's private key can decrypt
• Authenticated: Tampering is detected (AEAD)
• Forward Secure: Each message uses ephemeral keys

Symmetric (XChaCha20-Poly1305)

• Authenticated: Tampering detection via Poly1305 MAC
• Large Nonce: 192-bit nonces prevent collisions
• Memory Safe: Keys are automatically zeroized on drop

Security Considerations

Ed25519 Keys

1. Private Key Storage: Never store private keys in plaintext. Use secure key management.
2. Random Generation: Uses OS entropy via rand::thread_rng() for cryptographically secure randomness.
3. Constant-Time Operations: secure_compare prevents timing attacks.
4. WASM Compatibility: Uses getrandom with wasm_js feature for browser support.

HTTP Signatures

• ✅ Authenticity: Only the holder of the private key can create valid signatures
• ✅ Integrity: Headers and body are cryptographically bound to the signature
• ✅ Replay Protection: Configurable timestamp tolerance (default: 60s)
• ✅ Mandatory Digest: All requests include Content-Digest, even GET/DELETE
• ✅ Canonical Authority: Normalized host:port prevents proxy attacks

RFC Compliance

• RFC 9421: HTTP Message Signatures - Full compliance
• RFC 9530: Digest Fields - Content-Digest implementation
• Ed25519: Fast, secure elliptic curve signatures

Testing

# From workspace root (runs all Rust unit tests AND Rhai integration tests)
cargo test -p herolib-crypt --features full

# Run Rhai examples
cargo run --features full --example run_rhai

# Run specific Rhai examples manually
cargo run --features full --example run_rhai -- packages/crypt/examples_rhai/keys/basic_signing.rhai
cargo run --features full --example run_rhai -- packages/crypt/examples_rhai/httpsig/basic_usage.rhai

# Run Rhai tests
cargo run --features full --example run_rhai -- packages/crypt/rhai_tests/keys/run_all_tests.rhai
cargo run --features full --example run_rhai -- packages/crypt/rhai_tests/httpsig/run_all_tests.rhai

Test coverage:

• 119 unit tests - Core functionality
• 33 doc tests - Documentation examples
• Rhai examples - Keys and HTTP signatures
• Rhai tests - Comprehensive test suites for keys and httpsig

Architecture

The package is organized with clear module boundaries:

• Feature Flags: Compile only what you need (httpsig, rhai)
• Clean Modules: Clear boundaries between asymmetric, symmetric, keys, and httpsig
• Unified API: Single entry point for all cryptographic operations
• Mandatory Keys: Core Ed25519 functionality always available

Benefits:

• ✅ Simplified dependency management
• ✅ Selective compilation via features
• ✅ Unified Rhai integration
• ✅ Comprehensive cryptographic coverage

Dependencies

• ed25519-dalek - Ed25519 signatures
• x25519-dalek - X25519 key exchange
• chacha20poly1305 - AEAD encryption
• sha3 - Key derivation (KDF)
• sha2 - SHA-256 hashing
• argon2 - Password-based key derivation
• zeroize - Secure memory handling
• http (optional) - HTTP types for httpsig
• rhai (optional) - Scripting support

Specifications

See the detailed specifications:

• SPEC_SIGNING.md - Signing specification
• SPEC_ENCRYPTION.md - Encryption specification

License

Apache-2.0