Python API Reference

Complete API documentation for MetaMUI Crypto Primitives in Python.

Installation

pip install metamui-crypto

Quick Start

from metamui_crypto import Ed25519, ChaCha20Poly1305, Blake3, Argon2

# Generate keypair
keypair = Ed25519.generate_keypair()

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

# Verify signature
is_valid = Ed25519.verify(signature, b"Hello", keypair.public_key)

API Documentation

For detailed API documentation, see:

Available Modules

Hash Functions

Digital Signatures

Encryption

Key Exchange

Key Derivation

Utilities

Type Hints

All functions include comprehensive type hints:

from typing import Tuple, Optional
from metamui_crypto import Ed25519, KeyPair

def sign_message(
    message: bytes, 
    private_key: bytes
) -> bytes:
    """Sign a message with Ed25519.
    
    Args:
        message: The message to sign
        private_key: 32-byte private key
        
    Returns:
        64-byte signature
        
    Raises:
        InvalidKeyError: If private key is invalid
    """
    return Ed25519.sign(message, private_key)

Error Handling

from metamui_crypto import (
    CryptoError,
    InvalidKeyError,
    DecryptionError,
    VerificationError
)

try:
    result = some_operation()
except InvalidKeyError as e:
    print(f"Invalid key: {e}")
except DecryptionError as e:
    print(f"Decryption failed: {e}")
except CryptoError as e:
    print(f"Crypto error: {e}")

Examples

Password Hashing

from metamui_crypto import Argon2

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

# Verify password
is_valid = Argon2.verify(password, hash)

Authenticated Encryption

from metamui_crypto import ChaCha20Poly1305

# Generate key
key = ChaCha20Poly1305.generate_key()

# Encrypt with associated data
plaintext = b"Secret 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
)

Post-Quantum Key Exchange

from metamui_crypto import MLKem768

# Generate keypair
keypair = MLKem768.generate_keypair()

# Encapsulate (sender)
ciphertext, shared_secret = MLKem768.encapsulate(
    keypair.public_key
)

# Decapsulate (receiver)
shared_secret_2 = MLKem768.decapsulate(
    ciphertext, keypair.private_key
)

assert shared_secret == shared_secret_2

Performance

Batch Operations

# Batch signature verification
signatures = [sig1, sig2, sig3]
messages = [msg1, msg2, msg3]
public_keys = [pk1, pk2, pk3]

results = Ed25519.batch_verify(
    signatures, messages, public_keys
)

Streaming

from metamui_crypto import Blake3

# Hash large file
hasher = Blake3.new()
with open('large_file.bin', 'rb') as f:
    while chunk := f.read(8192):
        hasher.update(chunk)
        
hash = hasher.finalize()

Security Notes

from metamui_crypto import SecureBytes

with SecureBytes(32) as key:
    # Use key
    cipher = ChaCha20Poly1305(key)
    encrypted = cipher.encrypt(data)
# key is automatically cleared

See Also