libsignal-protocol-nif

High-performance Signal Protocol cryptographic primitives for the BEAM ecosystem

Erlang/OTPElixirGleamBuild StatusLicense

A native Erlang NIF (Native Implemented Function) library that provides Signal Protocol cryptographic primitives using libsodium. Built for performance, security, and cross-language compatibility across Erlang, Elixir, and Gleam.

Quick Start

Get up and running in 30 seconds:

# Clone and build
git clone https://github.com/Hydepwns/libsignal-protocol-nif.git
cd libsignal-protocol-nif
nix-shell --run "make build"

# Verify it works
nix-shell --run "make test-unit"

Add to your project:

Erlang (rebar.config) ```erlang {deps, [ {libsignal_protocol_nif, "0.1.1"} ]}. ```
Elixir (mix.exs) ```elixir def deps do [ {:libsignal_protocol, "~> 0.1.1"} ] end ```
Gleam (gleam.toml) ```toml [dependencies] libsignal_protocol_gleam = "~> 0.1.1" ```

What's Included

Cryptographic Primitives

Multi-Language Support

Production Ready

Installation

System Requirements

Component Version Purpose
libsodium 1.0.18+ Cryptographic operations
CMake 3.15+ Build system
Erlang/OTP 24.0+ Runtime
GCC/Clang Any recent C compiler

Platform-Specific Setup

Ubuntu/Debian ```bash sudo apt-get update sudo apt-get install libsodium-dev cmake build-essential ```
macOS ```bash brew install libsodium cmake ```
Nix (Recommended) ```bash nix-shell # All dependencies included automatically ```

Usage Examples

Basic Cryptographic Operations

%% Generate key pairs
{ok, {Curve25519Pub, Curve25519Priv}} = signal_nif:generate_curve25519_keypair(),
{ok, {Ed25519Pub, Ed25519Priv}} = signal_nif:generate_ed25519_keypair(),

%% Digital signatures
Message = <<"Hello, Signal Protocol!">>,
{ok, Signature} = signal_nif:sign_data(Ed25519Priv, Message),
ok = signal_nif:verify_signature(Ed25519Pub, Message, Signature),

%% Hashing and authentication
{ok, Hash} = signal_nif:sha256(Message),
{ok, Hmac} = signal_nif:hmac_sha256(<<"secret-key">>, Message),

%% Authenticated encryption
Key = crypto:strong_rand_bytes(32),
IV = crypto:strong_rand_bytes(12),
{ok, Ciphertext, Tag} = signal_nif:aes_gcm_encrypt(Key, IV, Message, <<>>, 16),
{ok, Plaintext} = signal_nif:aes_gcm_decrypt(Key, IV, Ciphertext, <<>>, Tag, byte_size(Message)).

Language-Specific Examples

Elixir ```elixir # Generate keys {:ok, {public_key, private_key}} = SignalProtocol.generate_keypair() # Sign and verify message = "Hello from Elixir!" {:ok, signature} = SignalProtocol.sign(private_key, message) :ok = SignalProtocol.verify(public_key, message, signature) ```
Gleam ```gleam import signal_protocol // Generate keys let assert Ok(#(public_key, private_key)) = signal_protocol.generate_keypair() // Sign and verify let message = "Hello from Gleam!" let assert Ok(signature) = signal_protocol.sign(private_key, message) let assert Ok(Nil) = signal_protocol.verify(public_key, message, signature) ```

Development

Building from Source

# Clean build
make clean && make build

# Run tests
make test-unit          # Unit tests
make test-integration   # Integration tests
make test-cover         # With coverage

# Performance testing
make perf-test          # Benchmarks

Docker Development

# Build all environments
make docker-build

# Test in containers
make docker-test

Documentation

Resource Description
Quick Start Guide Get started in 5 minutes
API Reference Complete function documentation
Architecture System design and internals
Security Guide Cryptographic security considerations
Language Comparison Erlang vs Elixir vs Gleam
Documentation Plan Comprehensive roadmap

Troubleshooting

Common Issues

Build Errors **`fatal error: sodium.h: No such file or directory`** ```bash # Install libsodium development headers sudo apt-get install libsodium-dev # Ubuntu/Debian brew install libsodium # macOS ``` **`CMake Error: Could not find a package configuration file`** ```bash # Install CMake sudo apt-get install cmake # Ubuntu/Debian brew install cmake # macOS ```
Runtime Errors **`{error, {load_failed, "Failed to load NIF library"}}`** ```bash # Rebuild and verify NIF files make clean && make build ls -la priv/ # Should show .so/.dylib files ``` **macOS library loading issues** ```bash # Check and set library paths otool -L priv/signal_nif.so export DYLD_LIBRARY_PATH=/opt/homebrew/opt/openssl@3/lib ```
Performance Issues - **Slow builds**: Use `make -j$(nproc)` for parallel compilation - **Memory monitoring**: Run `make monitor-memory` during tests - **Benchmarking**: Use `make perf-test` for performance metrics

Getting Help

Technical Details

Implementation

Key Specifications

Platform Support

License

This project is licensed under the Apache License 2.0. See LICENSE for details.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Key Areas:

**Made with ❤️ for the BEAM ecosystem** [⭐ Star this project](https://github.com/Hydepwns/libsignal-protocol-nif) • [Report Issues](https://github.com/Hydepwns/libsignal-protocol-nif/issues) • [Discussions](https://github.com/Hydepwns/libsignal-protocol-nif/discussions)