libsilver-nodejs

v0.1.7

Published

8 months ago

Cross-platform cryptography library for Node.js with post-quantum algorithms - built with RustCrypto

LibSilver Node.js Bindings

High-performance cryptography library for Node.js, built with Rust and RustCrypto.

🚀 Features

Post-Quantum Cryptography: ML-KEM (Key Encapsulation) and ML-DSA (Digital Signatures) - NIST standardized algorithms
Symmetric Encryption: AES-256-GCM (RustCrypto + AWS-LC-RS), ChaCha20-Poly1305
Asymmetric Encryption: RSA-OAEP (2048+ bit keys)
Digital Signatures: ECDSA P-256, Ed25519, ML-DSA (Post-Quantum)
Key Encapsulation: ML-KEM (Post-Quantum Key Exchange)
Cryptographic Hashing: SHA-256, SHA-512, BLAKE3, HMAC
Key Derivation Functions: Argon2, HKDF, PBKDF2
Secure Random Generation: OS-backed cryptographically secure random number generation
Memory Safety: Automatic zeroization of sensitive data
Cross-Platform: Works on Windows (x64/ARM64), macOS (Intel/ARM64), and Linux (via CI/CD)
TypeScript Support: Full TypeScript definitions included

📦 Installation

npm install libsilver-nodejs

🔧 Quick Start

const {
  SymmetricCrypto, AwsLcAesCrypto, AsymmetricCrypto, HashFunctions, KeyDerivation, RandomGenerator,
  MlKem768Crypto, MlDsa65Crypto  // Post-Quantum Cryptography
} = require('libsilver-nodejs');

// Symmetric encryption
const key = SymmetricCrypto.generateAesKey();
const plaintext = Buffer.from('Hello, World!', 'utf8');
const ciphertext = SymmetricCrypto.encryptAes(plaintext, key);
const decrypted = SymmetricCrypto.decryptAes(ciphertext, key);

console.log('Decrypted:', decrypted.toString('utf8')); // "Hello, World!"

// Post-Quantum Key Encapsulation (ML-KEM-768)
const kemKeypair = MlKem768Crypto.generateKeypair();
const encapsulation = MlKem768Crypto.encapsulate(kemKeypair.publicKeyBytes);
const sharedSecret = MlKem768Crypto.decapsulate(encapsulation.ciphertext, kemKeypair.privateKeyBytes);

console.log('Post-quantum shared secret established!');

📚 API Documentation

Post-Quantum Cryptography

LibSilver provides NIST-standardized post-quantum cryptographic algorithms to protect against quantum computer attacks.

NIST Security Levels

| Security Level | Classical Security | Quantum Security | Key Sizes | Performance | Recommended Use | |----------------|-------------------|------------------|-----------|-------------|-----------------| | Level 1 | AES-128 | Grover's algorithm | Smallest | Fastest | IoT, embedded systems | | Level 3 | AES-192 | Grover's algorithm | Medium | Balanced | General purpose (recommended) | | Level 5 | AES-256 | Grover's algorithm | Largest | Slowest | High-security applications |

ML-KEM (Key Encapsulation Mechanism)

ML-KEM provides quantum-resistant key exchange. Three security levels are available:

ML-KEM-512 (NIST Level 1)

const { MlKem512Crypto } = require('libsilver-nodejs');

// Generate key pair
const keypair = MlKem512Crypto.generateKeypair();

// Encapsulate shared secret
const encapsulation = MlKem512Crypto.encapsulate(keypair.publicKeyBytes);

// Decapsulate shared secret
const sharedSecret = MlKem512Crypto.decapsulate(
  encapsulation.ciphertext,
  keypair.privateKeyBytes
);

// Get size constants
const sizes = MlKem512Crypto.getSizes();
console.log('Public key size:', sizes.publicKeySize);
console.log('Private key size:', sizes.privateKeySize);
console.log('Ciphertext size:', sizes.ciphertextSize);
console.log('Shared secret size:', sizes.sharedSecretSize);

ML-KEM-768 (NIST Level 3) - Recommended

const { MlKem768Crypto } = require('libsilver-nodejs');

// Same API as ML-KEM-512, but with higher security level
const keypair = MlKem768Crypto.generateKeypair();
const encapsulation = MlKem768Crypto.encapsulate(keypair.publicKeyBytes);
const sharedSecret = MlKem768Crypto.decapsulate(
  encapsulation.ciphertext,
  keypair.privateKeyBytes
);

ML-KEM-1024 (NIST Level 5)

const { MlKem1024Crypto } = require('libsilver-nodejs');

// Same API as ML-KEM-512, but with highest security level
const keypair = MlKem1024Crypto.generateKeypair();
const encapsulation = MlKem1024Crypto.encapsulate(keypair.publicKeyBytes);
const sharedSecret = MlKem1024Crypto.decapsulate(
  encapsulation.ciphertext,
  keypair.privateKeyBytes
);

ML-DSA (Digital Signature Algorithm)

ML-DSA provides quantum-resistant digital signatures. Three security levels are available:

ML-DSA-44 (NIST Level 2)

const { MlDsa44Crypto } = require('libsilver-nodejs');

// Generate key pair
const keypair = MlDsa44Crypto.generateKeypair();

// Sign message
const message = Buffer.from('Hello, post-quantum world!', 'utf8');
const signature = MlDsa44Crypto.sign(message, keypair.privateKeyBytes);

// Verify signature
const isValid = MlDsa44Crypto.verify(message, signature, keypair.publicKeyBytes);

// Get size constants
const sizes = MlDsa44Crypto.getSizes();
console.log('Public key size:', sizes.publicKeySize);
console.log('Private key size:', sizes.privateKeySize);
console.log('Max signature size:', sizes.maxSignatureSize);

ML-DSA-65 (NIST Level 3) - Recommended

const { MlDsa65Crypto } = require('libsilver-nodejs');

// Same API as ML-DSA-44, but with higher security level
const keypair = MlDsa65Crypto.generateKeypair();
const signature = MlDsa65Crypto.sign(message, keypair.privateKeyBytes);
const isValid = MlDsa65Crypto.verify(message, signature, keypair.publicKeyBytes);

ML-DSA-87 (NIST Level 5)

const { MlDsa87Crypto } = require('libsilver-nodejs');

// Same API as ML-DSA-44, but with highest security level
const keypair = MlDsa87Crypto.generateKeypair();
const signature = MlDsa87Crypto.sign(message, keypair.privateKeyBytes);
const isValid = MlDsa87Crypto.verify(message, signature, keypair.publicKeyBytes);

Hybrid Encryption Example

Combine ML-KEM with symmetric encryption for secure communication:

const { MlKem768Crypto, SymmetricCrypto } = require('libsilver-nodejs');

// Alice generates key pair
const aliceKeypair = MlKem768Crypto.generateKeypair();

// Bob wants to send encrypted message to Alice
const message = Buffer.from('Confidential message', 'utf8');

// Bob encapsulates shared secret using Alice's public key
const encapsulation = MlKem768Crypto.encapsulate(aliceKeypair.publicKeyBytes);

// Bob encrypts message with shared secret
const encryptedMessage = SymmetricCrypto.encryptAes(message, encapsulation.sharedSecret);

// Alice decapsulates shared secret
const aliceSharedSecret = MlKem768Crypto.decapsulate(
  encapsulation.ciphertext,
  aliceKeypair.privateKeyBytes
);

// Alice decrypts message
const decryptedMessage = SymmetricCrypto.decryptAes(encryptedMessage, aliceSharedSecret);

Symmetric Encryption

AES-256-GCM (Default - AWS-LC-RS)

const { SymmetricCrypto } = require('libsilver-nodejs');

// Basic encryption/decryption (uses AWS-LC-RS by default)
const key = SymmetricCrypto.generateAesKey();
const plaintext = Buffer.from('Hello, World!', 'utf8');
const ciphertext = SymmetricCrypto.encryptAes(plaintext, key);
const decrypted = SymmetricCrypto.decryptAes(ciphertext, key);

// With Additional Authenticated Data (AAD)
const aad = Buffer.from('user_id:12345,session:abc123', 'utf8');
const ciphertextWithAad = SymmetricCrypto.encryptAesWithAad(plaintext, key, aad);
const decryptedWithAad = SymmetricCrypto.decryptAesWithAad(ciphertextWithAad, key, aad);

// With fixed nonce (for testing only)
const nonce = Buffer.alloc(12, 0x42);
const deterministicCiphertext = SymmetricCrypto.encryptAesWithNonce(plaintext, key, nonce);

Default Benefits (AWS-LC-RS):

🚀 5-20x faster than RustCrypto AES-GCM
🔒 FIPS 140-2 Level 1 validated cryptography
⚡ Hardware acceleration (AES-NI support)
🏷️ AAD support for additional authentication

AES-256-GCM (AWS-LC-RS Explicit)

const { AwsLcAesCrypto } = require('libsilver-nodejs');

// Same as SymmetricCrypto but explicitly using AWS-LC-RS
const key = AwsLcAesCrypto.generateKey();
const ciphertext = AwsLcAesCrypto.encrypt(plaintext, key);
const decrypted = AwsLcAesCrypto.decrypt(ciphertext, key);

AES-256-GCM (RustCrypto Alternative)

const { RustCryptoAesCrypto } = require('libsilver-nodejs');

// For users who specifically want RustCrypto implementation
const key = RustCryptoAesCrypto.generateKey();
const ciphertext = RustCryptoAesCrypto.encrypt(plaintext, key);
const decrypted = RustCryptoAesCrypto.decrypt(ciphertext, key);

// RustCrypto also supports AAD
const ciphertextWithAad = RustCryptoAesCrypto.encryptWithAad(plaintext, key, aad);
const decryptedWithAad = RustCryptoAesCrypto.decryptWithAad(ciphertextWithAad, key, aad);

ChaCha20-Poly1305

const key = SymmetricCrypto.generateChacha20Key();
const ciphertext = SymmetricCrypto.encryptChacha20(plaintext, key);
const decrypted = SymmetricCrypto.decryptChacha20(ciphertext, key);

Asymmetric Encryption

RSA-OAEP

const keypair = AsymmetricCrypto.generateRsaKeypair();
const ciphertext = AsymmetricCrypto.encryptRsa(plaintext, keypair.publicKeyPem);
const decrypted = AsymmetricCrypto.decryptRsa(ciphertext, keypair.privateKeyPem);

Digital Signatures

Ed25519

const keypair = AsymmetricCrypto.generateEd25519Keypair();
const signature = AsymmetricCrypto.signEd25519(message, keypair.signingKeyBytes);
const isValid = AsymmetricCrypto.verifyEd25519(message, signature, keypair.verifyingKeyBytes);

ECDSA P-256

const keypair = AsymmetricCrypto.generateEcdsaKeypair();
const signature = AsymmetricCrypto.signEcdsa(message, keypair.signingKeyBytes);
const isValid = AsymmetricCrypto.verifyEcdsa(message, signature, keypair.verifyingKeyBytes);

Cryptographic Hashing

// SHA-256
const hash = HashFunctions.sha256(data);
const hexHash = HashFunctions.sha256Hex(data);

// BLAKE3
const blake3Hash = HashFunctions.blake3(data);
const customLengthHash = HashFunctions.blake3WithLength(data, 64);

// HMAC
const mac = HashFunctions.hmacSha256(key, message);
const isValid = HashFunctions.verifyHmacSha256(key, message, mac);

Key Derivation Functions

// Argon2 (recommended for password hashing)
const salt = RandomGenerator.generateSalt();
const key = KeyDerivation.argon2(password, salt, 32);

// PBKDF2
const pbkdf2Key = KeyDerivation.pbkdf2Sha256(password, salt, 100000, 32);

// HKDF (for key expansion)
const hkdfKey = KeyDerivation.hkdfSha256(inputKey, salt, info, 32);

Secure Random Generation

const randomBytes = RandomGenerator.generateBytes(32);
const secureKey = RandomGenerator.generateKey(32);
const nonce = RandomGenerator.generateNonce(12);
const salt = RandomGenerator.generateSalt();

🛡️ Security Features

Post-Quantum Security: NIST-standardized ML-KEM and ML-DSA algorithms protect against quantum computer attacks
Memory Safety: All sensitive data is automatically zeroized when no longer needed
Secure Defaults: Uses secure parameters and algorithms by default
Constant-Time Operations: Leverages RustCrypto's constant-time implementations
No Unsafe Code: Pure safe Rust implementation with secure FFI bindings
Audited Dependencies: Built on well-audited RustCrypto crates and NIST reference implementations

🏗️ Building from Source

# Clone the repository
git clone https://github.com/DangVTNhan/libsilver.git
cd libsilver

# Install dependencies
npm install

# Build the native module
npm run build

# Run tests
npm test

# Run examples
npm run example                    # Basic cryptography examples
npm run example:post-quantum       # Post-quantum cryptography examples
node examples/aws-lc-aes-example.js  # AWS-LC-RS AES performance demo

🧪 Testing

# Run basic tests
npm test

# Run post-quantum cryptography tests
npm run test:post-quantum

# Run all comprehensive tests
npm run test:all

# Run specific test suites
npm run test:basic          # Basic cryptography tests
npm run test:integration    # Integration tests
npm run test:performance    # Performance benchmarks

🖥️ Platform Support

| Platform | Architecture | Status | Notes | |----------|-------------|--------|-------| | macOS | ARM64 (M1/M2) | ✅ | Native compilation | | macOS | Intel x64 | ✅ | Cross-compilation | | Windows | x64 | ✅ | Cross-compilation | | Windows | ARM64 | ✅ | Cross-compilation | | Linux | x64 | ⚠️ | CI/CD builds | | Linux | ARM64 | ⚠️ | CI/CD builds |

Pre-built binaries are available for all supported platforms via npm.

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

🔗 Related Projects

LibSilver Core - The main Rust library
LibSilver Swift - Swift bindings
LibSilver Kotlin - Kotlin/Android bindings