BaileysEx.Crypto (baileys_ex v0.1.0-alpha.8)

Cryptographic primitives for WhatsApp Web protocol communication.

Provides a clean Elixir API wrapping Erlang's :crypto module for all symmetric and asymmetric operations: AES (GCM, CBC, CTR), HMAC, hashing, HKDF key derivation, PBKDF2, Curve25519 ECDH, and Ed25519 signing.

HKDF (RFC 5869) is implemented in pure Elixir since OTP does not expose it directly. All other operations delegate to :crypto (backed by OpenSSL/LibreSSL).

Summary

Types

key_pair()

media_keys()

Functions

aes_cbc_decrypt(key, iv, ciphertext)

Decrypt AES-256-CBC and remove PKCS7 padding.

aes_cbc_encrypt(key, iv, plaintext)

Encrypt with AES-256-CBC and PKCS7 padding.

aes_ctr_decrypt(key, iv, ciphertext)

Decrypt AES-256-CTR (symmetric with encrypt).

aes_ctr_encrypt(key, iv, plaintext)

Encrypt with AES-256-CTR (stream cipher, no padding needed).

aes_gcm_decrypt(key, iv, ciphertext_with_tag, aad \\ <<>>)

Decrypt AES-256-GCM. Expects ciphertext <> 16-byte tag as input.

aes_gcm_encrypt(key, iv, plaintext, aad \\ <<>>)

Encrypt with AES-256-GCM. Returns {:ok, ciphertext <> 16-byte tag}.

ed25519_sign(private_key, message)

Sign a message with an Ed25519 private key.

ed25519_verify(public_key, message, signature)

Verify an Ed25519 signature. Returns true if valid, false otherwise.

expand_media_key(media_key, media_type)

Expand a 32-byte media key to 112 bytes using HKDF with a type-specific info string.

generate_key_pair(curve, opts \\ [])

Generate a key pair for the given curve.

hkdf(ikm, info, length, salt \\ <<>>)

HMAC-based Key Derivation Function (RFC 5869) using SHA-256.

hkdf_expand(prk, info, length)

HKDF expand step: expand a pseudorandom key to the desired length.

hkdf_extract(salt, ikm)

HKDF extract step: derive a pseudorandom key from input keying material.

hmac_sha256(key, data)

Compute HMAC-SHA256.

hmac_sha512(key, data)

Compute HMAC-SHA512.

md5(data)

Compute MD5 digest.

pbkdf2_sha256(password, salt, iterations, length)

PBKDF2 key derivation with HMAC-SHA256.

pkcs7_pad(data, block_size)

Apply PKCS7 padding to align data to the given block size.

pkcs7_unpad(data, block_size)

Remove PKCS7 padding. Returns {:error, :invalid_padding} if padding is malformed.

random_bytes(n)

Generate n cryptographically strong random bytes.

sha256(data)

Compute SHA-256 digest.

shared_secret(my_private, their_public)

Compute X25519 shared secret from a private key and a peer's public key.

Types

key_pair()

@type key_pair() :: %{public: binary(), private: binary()}

media_keys()

@type media_keys() :: %{
  iv: <<_::128>>,
  cipher_key: <<_::256>>,
  mac_key: <<_::256>>,
  ref_key: <<_::256>>
}

Functions

aes_cbc_decrypt(key, iv, ciphertext)

@spec aes_cbc_decrypt(<<_::256>>, <<_::128>>, binary()) ::
  {:ok, binary()} | {:error, :decrypt_failed}

Decrypt AES-256-CBC and remove PKCS7 padding.

Returns {:error, :decrypt_failed} on invalid padding.

aes_cbc_encrypt(key, iv, plaintext)

@spec aes_cbc_encrypt(<<_::256>>, <<_::128>>, binary()) :: {:ok, binary()}

Encrypt with AES-256-CBC and PKCS7 padding.

aes_ctr_decrypt(key, iv, ciphertext)

@spec aes_ctr_decrypt(<<_::256>>, <<_::128>>, binary()) :: {:ok, binary()}

Decrypt AES-256-CTR (symmetric with encrypt).

aes_ctr_encrypt(key, iv, plaintext)

@spec aes_ctr_encrypt(<<_::256>>, <<_::128>>, binary()) :: {:ok, binary()}

Encrypt with AES-256-CTR (stream cipher, no padding needed).

aes_gcm_decrypt(key, iv, ciphertext_with_tag, aad \\ <<>>)

@spec aes_gcm_decrypt(<<_::256>>, binary(), binary(), binary()) ::
  {:ok, binary()} | {:error, :decrypt_failed}

Decrypt AES-256-GCM. Expects ciphertext <> 16-byte tag as input.

Returns {:ok, plaintext} or {:error, :decrypt_failed} if authentication fails.

aes_gcm_encrypt(key, iv, plaintext, aad \\ <<>>)

@spec aes_gcm_encrypt(<<_::256>>, binary(), binary(), binary()) :: {:ok, binary()}

Encrypt with AES-256-GCM. Returns {:ok, ciphertext <> 16-byte tag}.

The 16-byte authentication tag is appended to the ciphertext, matching the WhatsApp wire format where tag is suffixed.

ed25519_sign(private_key, message)

@spec ed25519_sign(binary(), binary()) :: binary()

Sign a message with an Ed25519 private key.

ed25519_verify(public_key, message, signature)

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

Verify an Ed25519 signature. Returns true if valid, false otherwise.

expand_media_key(media_key, media_type)

@spec expand_media_key(<<_::256>>, BaileysEx.Media.Types.media_type()) :: media_keys()

Expand a 32-byte media key to 112 bytes using HKDF with a type-specific info string.

Returns a map with :iv (16 bytes), :cipher_key (32 bytes), :mac_key (32 bytes), and :ref_key (32 bytes).

generate_key_pair(curve, opts \\ [])

@spec generate_key_pair(
  :x25519 | :ed25519,
  keyword()
) :: key_pair()

Generate a key pair for the given curve.

:x25519 — Curve25519 key pair for Diffie-Hellman key exchange
:ed25519 — Ed25519 key pair for digital signatures

hkdf(ikm, info, length, salt \\ <<>>)

@spec hkdf(binary(), binary(), pos_integer(), binary()) :: {:ok, binary()}

HMAC-based Key Derivation Function (RFC 5869) using SHA-256.

Derives length bytes of keying material from input keying material (ikm), optional salt, and application-specific info.

When salt is empty or omitted, a zero-filled salt of hash length (32 bytes) is used per the RFC specification.

hkdf_expand(prk, info, length)

@spec hkdf_expand(<<_::256>>, binary(), pos_integer()) :: binary()

HKDF expand step: expand a pseudorandom key to the desired length.

Iteratively produces output blocks using HMAC-SHA256 with counter bytes. Maximum output length is 255 * 32 = 8160 bytes.

hkdf_extract(salt, ikm)

@spec hkdf_extract(binary(), binary()) :: <<_::256>>

HKDF extract step: derive a pseudorandom key from input keying material.

Uses HMAC-SHA256 with the given salt (or 32 zero bytes if salt is empty).

hmac_sha256(key, data)

@spec hmac_sha256(binary(), iodata()) :: <<_::256>>

Compute HMAC-SHA256.

hmac_sha512(key, data)

@spec hmac_sha512(binary(), iodata()) :: <<_::512>>

Compute HMAC-SHA512.

md5(data)

@spec md5(iodata()) :: <<_::128>>

Compute MD5 digest.

pbkdf2_sha256(password, salt, iterations, length)

@spec pbkdf2_sha256(binary(), binary(), pos_integer(), pos_integer()) ::
  {:ok, binary()}

PBKDF2 key derivation with HMAC-SHA256.

Used for pairing code derivation (131,072 iterations).

pkcs7_pad(data, block_size)

@spec pkcs7_pad(binary(), pos_integer()) :: binary()

Apply PKCS7 padding to align data to the given block size.

Adds 1 to block_size bytes of padding, where each padding byte's value equals the number of padding bytes added.

pkcs7_unpad(data, block_size)

@spec pkcs7_unpad(binary(), pos_integer()) ::
  {:ok, binary()} | {:error, :invalid_padding}

Remove PKCS7 padding. Returns {:error, :invalid_padding} if padding is malformed.

random_bytes(n)

@spec random_bytes(non_neg_integer()) :: binary()

Generate n cryptographically strong random bytes.

sha256(data)

@spec sha256(iodata()) :: <<_::256>>

Compute SHA-256 digest.

shared_secret(my_private, their_public)

@spec shared_secret(binary(), binary()) :: {:ok, binary()}

Compute X25519 shared secret from a private key and a peer's public key.

Returns {:ok, shared_secret} — a 32-byte value.