Quick Start Guide

Get up and running with MetaMUI Crypto Primitives in 5 minutes.

Basic Examples

1. Hashing Data

# Python
from metamui_crypto import SHA256, Blake3

# SHA-256 hash
hash_sha = SHA256.hash(b"Hello, MetaMUI!")
print(f"SHA-256: {hash_sha.hex()}")

# Blake3 hash (faster)
hash_blake = Blake3.hash(b"Hello, MetaMUI!")
print(f"Blake3: {hash_blake.hex()}")

// Rust
use metamui_crypto::{sha256, blake3};

// SHA-256 hash
let hash_sha = sha256::hash(b"Hello, MetaMUI!");
println!("SHA-256: {}", hex::encode(hash_sha));

// Blake3 hash
let hash_blake = blake3::hash(b"Hello, MetaMUI!");
println!("Blake3: {}", hex::encode(hash_blake));

2. Digital Signatures

# Python
from metamui_crypto import Ed25519

# Generate keypair
keypair = Ed25519.generate_keypair()

# Sign message
message = b"Important message"
signature = Ed25519.sign(message, keypair.private_key)

# Verify signature
is_valid = Ed25519.verify(signature, message, keypair.public_key)
print(f"Signature valid: {is_valid}")

// TypeScript
import { Ed25519 } from '@metamui/crypto';

// Generate keypair
const keypair = Ed25519.generateKeypair();

// Sign message
const message = new TextEncoder().encode("Important message");
const signature = await Ed25519.sign(message, keypair.privateKey);

// Verify signature
const isValid = await Ed25519.verify(signature, message, keypair.publicKey);
console.log(`Signature valid: ${isValid}`);

3. Symmetric Encryption

# Python
from metamui_crypto import ChaCha20Poly1305

# Generate key
key = ChaCha20Poly1305.generate_key()

# Encrypt
plaintext = b"Secret message"
ciphertext, nonce = ChaCha20Poly1305.encrypt(plaintext, key)

# Decrypt
decrypted = ChaCha20Poly1305.decrypt(ciphertext, nonce, key)
assert decrypted == plaintext

4. Password Hashing

# Python
from metamui_crypto import Argon2

# Hash password
password = "user_password_123"
salt = Argon2.generate_salt()
hash = Argon2.hash(password, salt)

# Verify password
is_correct = Argon2.verify(password, hash)
print(f"Password correct: {is_correct}")

5. Post-Quantum Key Exchange

# Python
from metamui_crypto import MLKem768

# Alice generates keypair
alice_keypair = MLKem768.generate_keypair()

# Bob encapsulates shared secret
ciphertext, shared_secret_bob = MLKem768.encapsulate(alice_keypair.public_key)

# Alice decapsulates to get same shared secret
shared_secret_alice = MLKem768.decapsulate(ciphertext, alice_keypair.private_key)

# Both now have the same shared secret
assert shared_secret_alice == shared_secret_bob

Common Patterns

Hybrid Encryption (Post-Quantum + AES)

from metamui_crypto import MLKem768, AES256

# Generate ML-KEM keypair
kem_keypair = MLKem768.generate_keypair()

# Sender: Create shared secret and encrypt data
ciphertext, shared_secret = MLKem768.encapsulate(kem_keypair.public_key)
aes_key = shared_secret[:32]  # Use first 32 bytes as AES key

data = b"Sensitive information"
encrypted_data = AES256.encrypt(data, aes_key)

# Receiver: Recover shared secret and decrypt
shared_secret = MLKem768.decapsulate(ciphertext, kem_keypair.private_key)
aes_key = shared_secret[:32]

decrypted_data = AES256.decrypt(encrypted_data, aes_key)
assert decrypted_data == data

Authenticated Encryption

from metamui_crypto import ChaCha20Poly1305

# Encrypt with authentication
key = ChaCha20Poly1305.generate_key()
plaintext = b"Message"
associated_data = b"metadata"

ciphertext, nonce, tag = ChaCha20Poly1305.encrypt_with_ad(
    plaintext, associated_data, key
)

# Decrypt and verify
decrypted = ChaCha20Poly1305.decrypt_with_ad(
    ciphertext, nonce, tag, associated_data, key
)

Key Derivation from Password

from metamui_crypto import Argon2, ChaCha20Poly1305

# Derive encryption key from password
password = "strong_password"
salt = Argon2.generate_salt()

# Derive 32-byte key
key = Argon2.derive_key(password, salt, key_length=32)

# Use derived key for encryption
cipher = ChaCha20Poly1305(key)
encrypted = cipher.encrypt(b"Secret data")

Best Practices

1. Always Use Authenticated Encryption

# Good: ChaCha20-Poly1305 provides authentication
ciphertext = ChaCha20Poly1305.encrypt(data, key)

# Avoid: Plain ChaCha20 without authentication
# ciphertext = ChaCha20.encrypt(data, key)  # Don't use alone

2. Generate Random Keys Properly

# Good: Use library functions
key = Algorithm.generate_key()

# Avoid: Weak randomness
# key = bytes(range(32))  # Never do this!

3. Handle Errors Appropriately

try:
    decrypted = ChaCha20Poly1305.decrypt(ciphertext, nonce, key)
except CryptoError as e:
    # Log error (but not sensitive data!)
    logger.error(f"Decryption failed: {e}")
    # Handle gracefully
    return None

4. Clear Sensitive Data

# Python example with context manager
from metamui_crypto import SecureBytes

with SecureBytes(key) as secure_key:
    # Use secure_key
    result = encrypt(data, secure_key)
# secure_key is automatically cleared

What’s Next?

  1. Explore Algorithms: Learn about our 33 supported algorithms
  2. Platform Guides: Deep dive into platform-specific features
  3. Security Best Practices: Review our security guidelines
  4. Integration Examples: See real-world examples
  5. API Reference: Check the complete API documentation

Need Help?