libsignal-protocol-nif

High-performance Signal Protocol cryptographic primitives for the BEAM ecosystem

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)

{deps, [
    {libsignal_protocol_nif, "0.1.1"}
]}.

Elixir (mix.exs)

def deps do
  [
    {:libsignal_protocol, "~> 0.1.1"}
  ]
end

Gleam (gleam.toml)

[dependencies]
libsignal_protocol_gleam = "~> 0.1.1"

---

What's Included

Cryptographic Primitives

• Key Generation: Curve25519 (ECDH) and Ed25519 (signatures)
• Digital Signatures: Ed25519 signing and verification
• Encryption: AES-GCM authenticated encryption
• Hashing: SHA-256, SHA-512, HMAC-SHA256
• Memory Safety: Secure memory clearing with sodium_memzero()

Multi-Language Support

• Erlang/OTP: Native NIF implementation
• Elixir: Idiomatic Elixir wrapper
• Gleam: Type-safe functional wrapper

Production Ready

• High Performance: Native C implementation with libsodium
• Memory Efficient: Minimal overhead, secure memory management
• Cross-Platform: Linux, macOS, Windows support
• Well Tested: Comprehensive test suite with 100% crypto coverage

---

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

sudo apt-get update
sudo apt-get install libsodium-dev cmake build-essential

macOS

brew install libsodium cmake

Nix (Recommended)

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

# 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

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

# 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

# Install CMake
sudo apt-get install cmake  # Ubuntu/Debian
brew install cmake           # macOS

Runtime Errors

{error, {load_failed, "Failed to load NIF library"}}

# Rebuild and verify NIF files
make clean && make build
ls -la priv/  # Should show .so/.dylib files

macOS library loading issues

# 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

• Quick fixes: docs/IMMEDIATE_ACTIONS.md
• Bug reports: GitHub Issues
• Questions: GitHub Discussions
• Security: docs/SECURITY.md

---

Technical Details

Implementation

• Core: Native C implementation using libsodium
• Interface: Erlang NIF for high-performance integration
• Memory: Secure allocation and automatic cleanup
• Error Handling: Comprehensive validation and reporting

Key Specifications

• Curve25519: 32-byte keys, X25519 ECDH
• Ed25519: 32-byte keys, 64-byte signatures
• AES-GCM: 256-bit keys, authenticated encryption
• SHA-256/512: Standard hash functions
• HMAC-SHA256: Message authentication codes

Platform Support

• Linux: x86_64, ARM64 ✅
• macOS: Intel, Apple Silicon ✅
• Windows: x86_64 (experimental) ⚠️

---

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:

• Bug fixes and improvements
• Documentation enhancements
• Additional test coverage
• New language wrappers
• Performance optimizations

---

Made with ❤️ for the BEAM ecosystem

⭐ Star this project • Report Issues • Discussions