esdb_crypto_nif (reckon_db v1.6.0)

Optimized cryptographic operations for reckon-db.

This module provides high-performance implementations of cryptographic operations used throughout reckon-db. It supports two modes:

Enterprise mode: Uses Rust NIFs for maximum performance
Community mode: Uses pure Erlang fallbacks (fully functional)

The mode is automatically detected at startup based on whether the NIF library is available. Community edition users (hex.pm) will always use the Erlang fallbacks, which provide identical functionality.

Usage

All functions work identically regardless of which implementation is active:

  %% Verify Ed25519 signature
  true = esdb_crypto_nif:verify_ed25519(Message, Signature, PublicKey).
 
  %% Generate token CID (SHA256 + base64)
  CID = esdb_crypto_nif:hash_sha256_base64(Data).
 
  %% Check which mode is active
  true = esdb_crypto_nif:is_nif_loaded().  %% Enterprise
  false = esdb_crypto_nif:is_nif_loaded(). %% Community

Summary

Functions

base64_decode_urlsafe(Data)

Decode URL-safe base64 string.

base64_encode_urlsafe(Data)

Encode binary as URL-safe base64 (no padding).

hash_sha256(Data)

Compute SHA-256 hash.

hash_sha256_base64(Data)

Compute SHA-256 hash and encode as URL-safe base64.

implementation()

Get the current implementation mode.

is_nif_loaded()

Check if the NIF is loaded (Enterprise mode).

secure_compare(A, B)

Constant-time comparison of two binaries.

verify_ed25519(Message, Signature, PublicKey)

Verify an Ed25519 signature.

Functions

base64_decode_urlsafe(Data)

-spec base64_decode_urlsafe(Data :: binary()) -> {ok, binary()} | {error, invalid_base64}.

Decode URL-safe base64 string.

Returns {ok, Binary} on success, {error, invalid_base64} on failure.

base64_encode_urlsafe(Data)

-spec base64_encode_urlsafe(Data :: binary()) -> binary().

Encode binary as URL-safe base64 (no padding).

hash_sha256(Data)

-spec hash_sha256(Data :: binary()) -> binary().

Compute SHA-256 hash.

Returns a 32-byte binary containing the SHA-256 hash of the input.

hash_sha256_base64(Data)

-spec hash_sha256_base64(Data :: binary()) -> binary().

Compute SHA-256 hash and encode as URL-safe base64.

This is optimized for token CID generation - combines hash + encode in a single call to avoid intermediate allocations.

Returns a URL-safe base64 string (no padding).

implementation()

-spec implementation() -> nif | erlang.

Get the current implementation mode.

Returns nif for Enterprise mode or erlang for Community mode.

is_nif_loaded()

-spec is_nif_loaded() -> boolean().

Check if the NIF is loaded (Enterprise mode).

Returns true if running in Enterprise mode with NIF optimizations, false if running in Community mode with pure Erlang.

secure_compare(A, B)

-spec secure_compare(A :: binary(), B :: binary()) -> boolean().

Constant-time comparison of two binaries.

This is important for security - prevents timing attacks when comparing signatures, hashes, or tokens. Always takes the same amount of time regardless of where the difference is (if any).

Returns true if equal, false otherwise.

verify_ed25519(Message, Signature, PublicKey)

-spec verify_ed25519(Message :: binary(), Signature :: binary(), PublicKey :: binary()) -> boolean().

Verify an Ed25519 signature.

This function verifies that a signature was created by the private key corresponding to the given public key.

Arguments:

Message - The original message that was signed (binary)
Signature - The 64-byte Ed25519 signature (binary)
PublicKey - The 32-byte Ed25519 public key (binary)

Returns true if valid, false otherwise.