Apero.Crypto (Apero v1.0.0)

Copy Markdown View Source

Cryptographic utilities — hashing, symmetric/asymmetric encryption, KDF.

Provides a unified interface for common cryptographic operations:

  • Hashing: SHA-256, SHA-512, MD5, HMAC
  • Symmetric authenticated: AES-256-GCM, ChaCha20-Poly1305
  • Symmetric streaming: AES-256-CTR (for large files/streams)
  • Key exchange: ECDH (X25519)
  • Key derivation: PBKDF2, Argon2id
  • Asymmetric: RSA key generation
  • Random generation: hex, token, password
  • Utilities: secure_compare, generate_key

All keys and IVs use :crypto.strong_rand_bytes/1. Encrypted values are self-contained (IV/nonce + tag + ciphertext, Base64-encoded).

Summary

Functions

argon2id(password, salt, opts \\ [])

Derives a key using Argon2id (requires optional argon2_elixir dependency).

compute_ecdh_secret(my_private, peer_public)

Computes a shared secret from your private key and peer's public key.

decrypt(encoded, key)

Decrypts a value encrypted with encrypt/2. Returns {:ok, plaintext} or {:error, reason}.

decrypt_chacha20(encoded, key)

Decrypts ChaCha20-Poly1305 encrypted data.

decrypt_ctr(ciphertext, key, iv)

Decrypts data encrypted with AES-256-CTR streaming.

encrypt(plaintext, key \\ nil)

Encrypts plaintext with AES-256-GCM. Returns {:ok, ciphertext}.

encrypt_chacha20(plaintext, key)

Encrypts plaintext with ChaCha20-Poly1305.

generate_ecdh_keypair()

Generates an X25519 key pair. Returns {private_key, public_key} (both raw binary).

generate_key()

Generates a random 256-bit key.

generate_rsa_keypair()

Generates an RSA key pair (2048-bit). Returns {private_der, public_der}.

hmac(secret, data)

HMAC-SHA256 (hex encoded).

md5(data)

MD5 hash (hex encoded). NOTE: MD5 is cryptographically broken — only for checksums.

pbkdf2(password, salt, opts \\ [])

Derives a key using PBKDF2-HMAC-SHA256.

random_hex(bytes \\ 32)

Generates a random hex string.

random_password(length \\ 24, opts \\ [])

Generates a random password with configurable length and character sets.

random_token(bytes \\ 32)

Generates a random URL-safe token.

secure_compare(a, b)

Timing-safe string comparison.

sha256(data)

SHA-256 hash (hex encoded).

sha512(data)

SHA-512 hash (hex encoded).

stream_encrypt(arg, chunk)

Encrypts a chunk of data in streaming mode.

stream_finalize(state)

Finalizes a streaming encryption. Returns the final state (discard after).

stream_init(key)

Starts an AES-256-CTR encryption stream. Use with stream_encrypt/2 and stream_finalize/1.

Functions

argon2id(password, salt, opts \\ [])

@spec argon2id(binary(), binary(), keyword()) :: {:ok, binary()} | {:error, term()}

Derives a key using Argon2id (requires optional argon2_elixir dependency).

compute_ecdh_secret(my_private, peer_public)

@spec compute_ecdh_secret(binary(), binary()) :: {:ok, binary()} | :error

Computes a shared secret from your private key and peer's public key.

decrypt(encoded, key)

@spec decrypt(binary(), binary()) :: {:ok, binary()} | {:error, term()}

Decrypts a value encrypted with encrypt/2. Returns {:ok, plaintext} or {:error, reason}.

decrypt_chacha20(encoded, key)

@spec decrypt_chacha20(binary(), binary()) :: {:ok, binary()} | :error

Decrypts ChaCha20-Poly1305 encrypted data.

decrypt_ctr(ciphertext, key, iv)

@spec decrypt_ctr(binary(), binary(), binary()) :: {:ok, binary()} | :error

Decrypts data encrypted with AES-256-CTR streaming.

encrypt(plaintext, key \\ nil)

@spec encrypt(binary(), binary() | nil) :: {:ok, binary()}

Encrypts plaintext with AES-256-GCM. Returns {:ok, ciphertext}.

encrypt_chacha20(plaintext, key)

@spec encrypt_chacha20(binary(), binary()) :: binary()

Encrypts plaintext with ChaCha20-Poly1305.

generate_ecdh_keypair()

@spec generate_ecdh_keypair() :: {binary(), binary()}

Generates an X25519 key pair. Returns {private_key, public_key} (both raw binary).

generate_key()

@spec generate_key() :: binary()

Generates a random 256-bit key.

generate_rsa_keypair()

@spec generate_rsa_keypair() :: {:ok, {binary(), binary()}} | {:error, term()}

Generates an RSA key pair (2048-bit). Returns {private_der, public_der}.

hmac(secret, data)

@spec hmac(binary(), binary()) :: binary()

HMAC-SHA256 (hex encoded).

md5(data)

@spec md5(binary()) :: binary()

MD5 hash (hex encoded). NOTE: MD5 is cryptographically broken — only for checksums.

pbkdf2(password, salt, opts \\ [])

@spec pbkdf2(binary(), binary(), keyword()) :: binary()

Derives a key using PBKDF2-HMAC-SHA256.

random_hex(bytes \\ 32)

@spec random_hex(non_neg_integer()) :: binary()

Generates a random hex string.

random_password(length \\ 24, opts \\ [])

@spec random_password(
  non_neg_integer(),
  keyword()
) :: binary()

Generates a random password with configurable length and character sets.

random_token(bytes \\ 32)

@spec random_token(non_neg_integer()) :: binary()

Generates a random URL-safe token.

secure_compare(a, b)

@spec secure_compare(binary(), binary()) :: boolean()

Timing-safe string comparison.

sha256(data)

@spec sha256(binary()) :: binary()

SHA-256 hash (hex encoded).

sha512(data)

@spec sha512(binary()) :: binary()

SHA-512 hash (hex encoded).

stream_encrypt(arg, chunk)

@spec stream_encrypt(
  {any(), binary()},
  binary()
) :: {any(), binary(), binary()}

Encrypts a chunk of data in streaming mode.

stream_finalize(state)

@spec stream_finalize(any()) :: binary()

Finalizes a streaming encryption. Returns the final state (discard after).

stream_init(key)

@spec stream_init(binary()) :: {any(), binary()}

Starts an AES-256-CTR encryption stream. Use with stream_encrypt/2 and stream_finalize/1.