crypto

import crypto

Comprehensive cryptographic primitives for Zuri applications.

This module exposes symmetric encryption, authenticated encryption, asymmetric key operations, digital signatures, key exchange, and password hashing through a clean, opinionated API.

Algorithm summary

Choosing the right primitive

Encrypting data at rest or in transit: prefer aes_gcm (authenticated encryption with associated data). Use chacha20 on platforms where AES hardware acceleration is absent. Avoid aes_cbc in new designs; it is included for interoperability with legacy systems.

Signing and verifying messages: use ed25519 for modern systems (fastest, no hash to choose, deterministic). Use ecdsa when interoperating with systems that require NIST curves. Use rsa only when constrained by a protocol that demands it.

Asymmetric encryption: use rsa with OAEP. For larger payloads, use a hybrid scheme: exchange a symmetric key with RSA-OAEP, then encrypt the payload with aes_gcm.

Key agreement: use x25519_exchange followed by hkdf to derive a symmetric key from the shared secret.

Password storage: always use argon2_hash. Never use raw hashes (SHA-*, MD5) to store passwords.

Quick start

import crypto

# --- Symmetric (AES-GCM) -----------------------------------------------
var key = crypto.random_bytes(32)              # AES-256
var iv  = crypto.random_bytes(12)              # 96-bit GCM nonce
var ct  = crypto.aes_gcm.encrypt(key, iv, bytes('hello world'))
var pt  = crypto.aes_gcm.decrypt(key, iv, ct)
echo string(pt)  # hello world

# --- Password hashing (Argon2id) ----------------------------------------
var salt = crypto.random_bytes(16)
var hash = crypto.argon2.hash('my password', salt)
echo crypto.argon2.verify(hash, 'my password')  # true

# --- Ed25519 signature --------------------------------------------------
var kp  = crypto.ed25519.generate()
var sig = crypto.ed25519.sign(kp.private_pem, bytes('payload'))
echo crypto.ed25519.verify(kp.public_pem, bytes('payload'), sig)  # true

The crypto API

Every public name in crypto, wherever it is declared. Each links to the page that documents it.

Constants

aes_gcm

crypto.aes_gcm

AES-GCM authenticated encryption namespace.

See also: _AesGcm

aes_cbc

crypto.aes_cbc

AES-CBC encryption namespace.

See also: _AesCbc

chacha20

crypto.chacha20

ChaCha20-Poly1305 AEAD namespace.

See also: _ChaCha20

rsa

crypto.rsa

RSA encryption and signing namespace.

See also: _Rsa

ecdsa

crypto.ecdsa

ECDSA signing namespace.

See also: _Ecdsa

ed25519

crypto.ed25519

Ed25519 signing namespace.

See also: _Ed25519

x25519

crypto.x25519

X25519 key exchange namespace.

See also: _X25519

jwk

crypto.jwk

JWK-to-PEM conversion namespace.

See also: _Jwk

argon2

crypto.argon2

Argon2id password hashing namespace.

See also: _Argon2

Functions

random_bytes()

crypto.random_bytes(n) -> bytes

Returns n cryptographically secure random bytes from the operating system’s entropy source (OpenSSL RAND_bytes, which seeds from /dev/urandom or the OS equivalent).

Use this to generate keys, IVs, nonces, and salts. Never use math.random for these purposes.

var key = crypto.random_bytes(32)  # 256-bit AES key
var iv  = crypto.random_bytes(12)  # 96-bit GCM nonce

Parameters

• n (number) — Number of bytes to generate. Must be between 1 and 65536.

Returns bytes

Raises CryptoError

hkdf()

crypto.hkdf(ikm, salt, info, length) -> bytes

Derives cryptographic key material from a high-entropy input using HKDF-SHA256 (RFC 5869).

HKDF is not a password hashing function: it does not strengthen low-entropy inputs. Use argon2 for passwords. HKDF is appropriate for:

• Expanding X25519 shared secrets into symmetric keys. - Deriving multiple purpose-specific sub-keys from a single master key. - Stretching random key material to the required length.

The info parameter binds the derived key to a specific context and prevents key reuse across different purposes. It does not need to be secret.

Example

import crypto

# Derive an AES-256 encryption key and a separate HMAC key from a
# shared secret, binding each to its intended purpose.

var secret = crypto.x25519.exchange(my_priv, peer_pub)
var salt   = crypto.random_bytes(32)

var enc_key  = crypto.hkdf(secret, salt, bytes('encryption'), 32)
var hmac_key = crypto.hkdf(secret, salt, bytes('authentication'), 32)

Parameters

• ikm (bytes) — Input key material (high entropy required).
• salt (bytes) — Random salt. Use random_bytes(32) or a fixed well-known value if no random salt is available.
• info (bytes) — Context string binding the key to its purpose.
• length (number) — Number of output bytes. Maximum 8160.

Returns bytes

Raises CryptoError

Classes

CryptoError

class crypto.CryptoError < Error

Raised by crypto operations that fail due to invalid input, key material errors, or authentication failures. Always catch this class when decrypting untrusted data.

Constructor

crypto.CryptoError(message)

Parameters

• message (string)

2024, Zuri Project