https://docs.rs/ciphern

Ciphern Crypto Library

Ciphern is an enterprise-grade, security-first Rust cryptographic library providing cryptographic capabilities that comply with both Chinese National Standards (GuoMi) and international standards. Designed for data storage encryption, communication encryption, and key management.

English | 中文文档

---

✨ Core Features

🔒 Security First

• Memory Protection: Securely clear keys using zeroize, support for memory locking (mlock) and integrity verification
• Side-channel Protection: Provides constant-time operation implementation to prevent timing attacks
• Compliance: Compliant with Chinese National Standards (SM2/SM3/SM4) and FIPS 140-3 basic requirements
• Audit Logs: Full audit trail for cryptographic operations
• Key Lifecycle: Support for basic lifecycle management including key generation, activation, and destruction

⚡ High Performance

• Zero-Copy Design: Minimizes memory allocation and copying
• Smart Caching: Reuses keys and algorithm instances
• Pure Rust Implementation: No external dependencies, compile-time optimization

🔧 Easy Integration

• Unified Interface: Simple API that hides underlying complexity
• Multi-language Support: C FFI interface, basic Java JNI and Python PyO3 bindings
• Pluggable Architecture: Supports custom cryptographic algorithm plugins (basic framework)
• Rich Testing: Includes unit tests, integration tests, and performance tests
• Internationalization (i18n): Full i18n support with English and Chinese locales, string interpolation with arguments

🌐 Standard Compatibility

• International Standards: AES-128/192/256-GCM, ECDSA-P256/P384/P521, RSA-2048/3072/4096, Ed25519
• National Standards: SM2, SM3, SM4-GCM
• Hash Functions: SHA-256/384/512, SHA3-256/384/512, SM3
• Key Derivation: HKDF, PBKDF2, Argon2id, Sm3Kdf

---

🚀 Quick Start

Installation

Rust (Cargo)

[dependencies]
ciphern = "0.1"

Java (Maven)

Java JNI bindings have completed core functionality implementation, supporting encryption/decryption and key management:

<!-- Maven direct installation is not yet supported, requires compilation of the JNI library from source -->

Python (pip)

Python PyO3 bindings have completed core functionality implementation, supporting encryption/decryption, signature verification, and hash calculation:

# pip direct installation is not yet supported, requires compilation from source
# pip install ciphern  # Not available yet

5-Minute Examples

Basic Encryption/Decryption (Rust)

use ciphern::{Cipher, Algorithm, KeyManager};
#[cfg(feature = "hash")]
use ciphern::Hash;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize the library
    ciphern::init()?;
    
    // Initialize KeyManager
    let km = KeyManager::new()?;
    
    // Generate a key
    let key_id = km.generate_key(Algorithm::AES256GCM)?;
    
    // Create a cipher
    let cipher = Cipher::new(Algorithm::AES256GCM)?;
    
    // Encrypt
    let plaintext = b"Hello, Ciphern!";
    let ciphertext = cipher.encrypt(&km, &key_id, plaintext)?;
    
    // Decrypt
    let decrypted = cipher.decrypt(&km, &key_id, &ciphertext)?;
    assert_eq!(plaintext, &decrypted[..]);
    
    println!("✅ Encryption and decryption successful!");
    Ok(())
}

Digital Signature (Rust)

use ciphern::{Cipher, Algorithm, KeyManager};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize the library
    ciphern::init()?;
    
    // Initialize KeyManager
    let km = KeyManager::new()?;
    
    // Generate a key pair (using ECDSA-P256 as an example)
    let key_id = km.generate_key(Algorithm::ECDSAP256)?;
    
    // Create a cipher for signing
    let cipher = Cipher::new(Algorithm::ECDSAP256)?;
    
    // Sign
    let message = b"Important message";
    let signature = cipher.sign(&km, &key_id, message)?;
    
    // Verify
    let is_valid = cipher.verify(&km, &key_id, message, &signature)?;
    assert!(is_valid);
    
    println!("✅ Signature verified!");
    Ok(())
}

National Standard Algorithms (Rust)

use ciphern::{Cipher, Algorithm, KeyManager};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize the library
    ciphern::init()?;
    
    let km = KeyManager::new()?;

    // SM4 Encryption
    let key_id = km.generate_key(Algorithm::SM4GCM)?;
    let cipher = Cipher::new(Algorithm::SM4GCM)?;
    let ciphertext = cipher.encrypt(&km, &key_id, b"GuoMi encryption test")?;
    
    // SM4 Decryption verification
    let decrypted = cipher.decrypt(&km, &key_id, &ciphertext)?;
    assert_eq!(b"GuoMi encryption test", &decrypted[..]);
    
    // SM3 Hash (requires "hash" feature)
    #[cfg(feature = "hash")]
    {
        let hash = Hash::sm3(b"Data integrity verification")?;
        println!("SM3 hash: {:?}", hash);
    }
    
    println!("✅ National standard algorithms executed successfully!");
    Ok(())
}

Java Example

Java JNI bindings have completed core functionality implementation:

import com.ciphern.Ciphern;

public class Main {
    public static void main(String[] args) {
        // Initialize the library
        Ciphern.init();
        
        // Generate a key
        String keyId = Ciphern.generateKey("AES256GCM");
        
        // Encrypt
        byte[] plaintext = "Hello, Ciphern!".getBytes();
        byte[] ciphertext = Ciphern.encrypt(keyId, plaintext);
        
        // Decrypt
        byte[] decrypted = Ciphern.decrypt(keyId, ciphertext);
        
        System.out.println("Decrypted result: " + new String(decrypted));
    }
}

Python Example

Python PyO3 bindings have completed core functionality implementation:

from ciphern_py import KeyManager, Ciphern

# Initialize KeyManager
km = KeyManager()

# Generate a key
key_id = km.generate_key("AES256GCM")

# Create cipher
cipher = Ciphern(km)

# Encrypt
plaintext = b"Hello, Ciphern!"
ciphertext = cipher.encrypt(key_id, plaintext)

# Decrypt
decrypted = cipher.decrypt(key_id, ciphertext)

print(f"Decrypted result: {decrypted.decode('utf-8')}")

---

📚 Documentation

Core Documentation

• User Guide - Detailed instructions and best practices
• API Reference - Complete API reference
• Examples - Examples covering common scenarios

Advanced Topics

• Architecture - System architecture and design decisions
• Performance Optimization - SIMD, hardware acceleration, benchmark
• Security Guide - Threat model, security best practices
• Multi-Tenancy Guide - Key isolation and access control

Developer Documentation

• Contributing Guide - How to participate in development
• Plugin Development - Implementing custom algorithms
• FFI Guide - C/Java/Python bindings

---

🎯 Use Cases

Data Storage Encryption

Protect sensitive data in databases and file systems

use ciphern::{Cipher, KeyManager, Algorithm};

ciphern::init()?;
let km = KeyManager::new()?;
let key_id = km.generate_key_with_alias(Algorithm::AES256GCM, "database-encryption")?;
let cipher = Cipher::new(Algorithm::AES256GCM)?;

// Encrypt sensitive field
let encrypted_ssn = cipher.encrypt(&km, &key_id, user.ssn.as_bytes())?;
db.save_encrypted_field(user.id, "ssn", &encrypted_ssn)?;

API Communication Encryption

Protect the confidentiality and integrity of API requests and responses

use ciphern::{Cipher, Algorithm, KeyManager};

ciphern::init()?;
let km = KeyManager::new()?;
let key_id = km.generate_key(Algorithm::ECDSAP384)?;
let cipher = Cipher::new(Algorithm::ECDSAP384)?;
let signature = cipher.sign(&km, &key_id, &request_body)?;

http_request
    .header("X-Signature", base64::encode(&signature))
    .body(request_body)
    .send()?;

Key Management

Basic key lifecycle management

use ciphern::{KeyManager, Algorithm};

ciphern::init()?;
let km = KeyManager::new()?;

// Generate a key
let key_id = km.generate_key(Algorithm::AES256GCM)?;

// Manage keys using aliases
let alias_key_id = km.generate_key_with_alias(Algorithm::AES256GCM, "my-app-key")?;

---

🔧 Advanced Features

FIPS 140-3 Compliance Mode

[dependencies]
ciphern = { version = "0.1", features = ["fips"] }

use ciphern::{is_fips_enabled, Algorithm, Cipher};

// Enable FIPS mode during initialization
ciphern::init()?;

// Check if FIPS mode is enabled
if is_fips_enabled() {
    println!("FIPS mode is enabled");
}

// In FIPS mode, non-approved algorithms will be rejected
let result = Cipher::new(Algorithm::SM4GCM);
assert!(result.is_err()); // CryptoError::FipsError

Audit Logging and Monitoring

use ciphern::audit::AuditLogger;
use std::sync::Arc;

// Initialize the library
ciphern::init()?;

// Log an event
AuditLogger::log("ENCRYPT", Some(ciphern::Algorithm::Aes256Gcm), Some("key-123"), Ok(()))?;

// Get performance metrics
let metrics = audit_logger.get_performance_metrics()?;
println!("Throughput: {:.2} ops/sec", metrics.avg_throughput_ops_per_sec);
println!("Cache hit rate: {:.1}%", metrics.avg_cache_hit_rate * 100.0);

Custom Algorithm Plugins

use ciphern::plugin::{Plugin, CipherPlugin};
// Extend algorithms by implementing Plugin and CipherPlugin traits

Internationalization (i18n)

[dependencies]
ciphern = { version = "0.1", features = ["i18n"] }

use ciphern::i18n::{set_locale, tr, tr_with_args};

// Set locale to English or Chinese
set_locale("en"); // or "zh"

// Simple translation
let message = tr("common.ok")?;  // Returns "OK" in English

// Translation with arguments
let error_msg = tr_with_args("error.key_not_found_in_keyring", 
    &[("key_id", "my-key"), ("keyring", "main"), ("reason", "not found")])?;
// Returns: "Key my-key not found in keyring main: not found"

// Check supported locales
use ciphern::i18n::{is_locale_supported, get_supported_locales};
assert!(is_locale_supported("en"));
assert!(is_locale_supported("zh"));
let locales = get_supported_locales(); // Returns vec!["en", "zh"]

---

📊 Performance Metrics

Performance Metrics

The current version is based on a pure Rust implementation. Performance data can be obtained through the audit system:

// Performance monitoring is handled internally by the audit system

// The current version collects performance metrics internally
// Performance data is available through internal monitoring systems

Note: SIMD optimization and hardware acceleration features are under development. The current version provides a basic implementation of cryptographic functions.

Run benchmark:

cargo bench

---

🔐 Security

Security Features

• ✅ Automatic Memory Erasure: Securely clear keys using zeroize
• ✅ Memory Locking: Uses mlock to prevent sensitive data from being swapped to disk
• ✅ Integrity Verification: Key integrity checks to prevent memory tampering
• ✅ Constant-time Operations: Side-channel protection to prevent timing attacks
• ✅ FIPS 140-3 Basic Compliance: Supports verification of FIPS-approved algorithms
• ✅ Audit Logs: Full audit trail for cryptographic operations
• ✅ Algorithm Verification: Built-in algorithm correctness self-checks
• ✅ Error Handling: Secure error state management

Security Audit

Ciphern security features are based on the following implementations:

• ✅ Uses mature cryptographic libraries (ring, libsm) as the underlying implementation
• ✅ Built-in algorithm correctness verification
• ✅ FIPS 140-3 algorithm approval checks
• ✅ Comprehensive error handling and state management

Note: NIST CAVP testing, Fuzzing, third-party security audits, etc., are planned.

Vulnerability Reporting

If you find a security vulnerability, please report it in the GitHub Issues.

Note: A dedicated security email and SECURITY.md documentation are being prepared.

---

🛠️ Development Environment

Prerequisites

• Rust 1.75+ (stable)
• Standard C compiler (for FFI bindings)

Build

# Clone the repository
git clone https://github.com/Kirky-X/ciphern.git
cd ciphern

# Default build
cargo build --release

# Enable all features
cargo build --release --all-features

# FIPS mode
cargo build --release --features fips

Test

# Run all tests
cargo test --all-features

# Run benchmarks
cargo bench

# Check code quality
cargo clippy --all-features

Cross-Compilation

# ARM64 Linux
cargo build --target aarch64-unknown-linux-gnu --release

# Windows
cargo build --target x86_64-pc-windows-msvc --release

# macOS ARM (Apple Silicon)
cargo build --target aarch64-apple-darwin --release

---

🗺️ Roadmap

v0.1.0 - MVP (Completed) ✅

• Core encryption (AES-128/192/256-GCM, SM4-GCM)
• Digital signatures (ECDSA-P256/P384/P521, RSA-2048/3072/4096, Ed25519, SM2)
• Hash functions (SHA-256/384/512, SHA3-256/384/512, SM3)
• Key derivation (HKDF, PBKDF2, Argon2id, Sm3Kdf)
• Basic key management
• Rust API
• Audit logging system
• FIPS 140-3 basic support

v0.2.0 - Multi-language Support (Completed) ✅

• C FFI interface
• Java JNI bindings (core functionality implemented)
• Python PyO3 bindings (core functionality implemented)
• Memory protection enhancements (mlock + integrity verification)
• Side-channel protection (constant-time operations)
• Plugin system improvements
• Internationalization (i18n) with English and Chinese locale support

v0.3.0 - Extensibility (Planned) 📋

• SIMD optimization
• WASM support
• HSM integration (PKCS#11)
• TEE support (Intel SGX, ARM TrustZone)

v1.0.0 - Production Ready (Planned) 🎯

• Complete security audit
• FIPS 140-3 certification
• Performance optimization (SIMD, multi-core)
• Full documentation and examples

---

🤝 Contributing

We welcome all forms of contribution!

How to Contribute

1. Fork this repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Create a Pull Request

Note: CONTRIBUTING.md documentation is being prepared.

Contributors

Thanks to all contributors!

---

📄 License

This project is dual-licensed:

• MIT License - see LICENSE-MIT
• Apache License 2.0 - see LICENSE-APACHE

You may choose either license for your use.

Note: License files are being prepared. The current version follows standard Rust open-source protocols.

---

🙏 Acknowledgments

Ciphern is built upon these excellent open-source projects:

• ring - High-performance cryptography library (v0.17)
• libsm - GuoMi algorithm implementation (v0.6)
• aes-gcm - AES-GCM implementation (v0.10)
• argon2 - Argon2 key derivation (v0.5)
• zeroize - Secure memory erasure (v1.7)

Special thanks to all security researchers who audited the code and provided feedback.

---

📞 Contact

• Issues: https://github.com/Kirky-X/ciphern/issues
• Discussions: https://github.com/Kirky-X/ciphern/discussions

Note: Official website, documentation site, and dedicated support email are being prepared.

---

⭐ Star History

---

Built with ❤️ by the Ciphern Team

⬆ Back to Top