crystal-ecc-constant v0.2.1

crystal crystal-lang cryptography security libsodium ecdh gplv3 ed25519 constant-time x25519

Constant-time Ed25519 digital signatures and X25519 ECDH key agreement for Crystal backed by libsodium guarded memory and page protection.

Constant-time Ed25519 digital signatures and X25519 ECDH key agreement for Crystal backed by libsodium guarded memory and page protection.

GitLab Project Metadata:

Description: Constant-time Ed25519 digital signatures and X25519 ECDH key agreement for Crystal backed by libsodium guarded memory and page protection.

Topics and Tags: crystal, crystal-lang, cryptography, ed25519, x25519, ecdh, libsodium, constant-time, security, gplv3

Overview

crystal-ecc-constant is a constant-time Elliptic Curve Cryptography shard for Crystal binding directly to libsodium for Ed25519 and Ed25519ph digital signatures, X25519 ECDH key agreement, and BLAKE2b guarded subkey derivation with complete garbage collector secret isolation. All private keys, streaming hash states, KDF subkeys, and unconsumed shared secrets reside exclusively inside sodium_malloc guarded memory with mlock pinning, surrounding canary and guard pages, sodium_mprotect_readonly page locks, Sync::Mutex FFI synchronization, and deterministic sodium_memzero wiping.

Key Highlights

Guarded Memory & Hardware Page Protection: Secret material (SecureBuffer, PrivateKeyPointer, SharedSecret, and Ed25519PhStream) is allocated via sodium_malloc, locked read-only via sodium_mprotect_readonly while at rest, and deterministically zeroized via sodium_memzero prior to sodium_free.
Constant-Time Ed25519, Ed25519ph, X25519 & KDF Primitives: Random keypair generation, deterministic 32-byte seed derivation, 64-byte detached Ed25519 signatures, multi-part pre-hashed Ed25519ph streaming signatures (Ed25519PhStream), Curve25519 ECDH key exchange with small-order point rejection, BLAKE2b subkey derivation (Kdf.derive_subkey), and sodium_memcmp constant-time equality.
Thread-Safe Parallel Execution: Synchronized across Crystal 1.21 Fiber::ExecutionContext::Parallel threads via Sync::Mutex and Atomic(Bool) double-checked initialization.
Multi-Tier Documentation & Wycheproof Verification: Validated against RFC 8032, RFC 7748, and Project Wycheproof edge-case vectors alongside a complete Sphinx technical, functional, business, ADR, D2 diagram, and Crystal API documentation suite.

Installation

Add crystal-ecc-constant to your application's shard.yml:

dependencies:
  crystal-ecc-constant:
    gitlab: renich/crystal-ecc-constant
    version: ~> 0.2.2

Then install the shard (ensure libsodium-devel is installed on your host):

shards install

Usage

require "crystal-ecc-constant"

# Initialize libsodium (thread-safe, idempotent, verifies major version >= 10)
Crystal::Ecc::Constant::Sodium.init

# Ed25519 Signing & Verification
keypair = Crystal::Ecc::Constant::Ed25519KeyPair.generate
begin
  message = "Strictly FIDO2 assertion payload".to_slice
  signature = keypair.sign(message)
  puts "Signature valid: #{keypair.verify(message, signature)}"

  # Multi-part Ed25519ph Streaming Signature in Guarded Memory
  signer = Crystal::Ecc::Constant::Ed25519PhStream.new
  signer.update("Chunk 1: ".to_slice).update("Chunk 2".to_slice)
  ph_sig = signer.final_sign(keypair)

  verifier = Crystal::Ecc::Constant::Ed25519PhStream.new
  verifier.update("Chunk 1: Chunk 2".to_slice)
  puts "Ed25519ph valid: #{verifier.final_verify(keypair.public_key, ph_sig)}"
ensure
  keypair.dispose
end

# Guarded BLAKE2b Subkey Derivation (crypto_kdf)
master_key = Crystal::Ecc::Constant::SecureBuffer.from_bytes(Random::Secure.random_bytes(32))
subkey = Crystal::Ecc::Constant::Kdf.derive_subkey(master_key, 1_u64, "ECC_KDF1", 32)
subkey.dispose
master_key.dispose

# X25519 ECDH Key Exchange (Block-Scoped Auto-Disposal)
alice = Crystal::Ecc::Constant::X25519KeyPair.generate
bob = Crystal::Ecc::Constant::X25519KeyPair.generate
begin
  alice.diffie_hellman(bob.public_key).consume do |alice_secret|
    bob.diffie_hellman(alice.public_key).consume do |bob_secret|
      matched = Crystal::Ecc::Constant::Sodium.constant_time_equal?(alice_secret, bob_secret)
      puts "Secrets match: #{matched}"
    end
  end
ensure
  alice.dispose
  bob.dispose
end

Build System Targets

The repository includes a comprehensive, standard GNUmakefile:

Target	Description
`make all`	Runs static analysis (`lint`), documentation linting (`doc-check`), and the test suite (`test`)
`make test`	Executes the spec test suite (`crystal spec`)
`make lint`	Runs `crystal tool format --check`, Ameba static analysis, and Flaw SAST security scanner
`make doc-check`	Lints all reStructuredText files using `crstlint` and `rstcheck`
`make check`	Aggregates `lint`, `doc-check`, and `test`
`make docs`	Generates Crystal API docs (`docs/technical/api`) and builds the Sphinx `dirhtml` portal (`docs/build/dirhtml`)
`make deps`	Installs Shards dependencies and builds `bin/ameba` and `bin/flaw`
`make clean`	Removes build artifacts and generated documentation

Documentation

Full architectural blueprints, functional specifications, and operational playbooks are maintained under docs/:

Guide	Scope & Highlights	Entry Point
Business Context & Strategy	Cryptographic security problem statement, ROI metrics, and personas.	Business Specs
Functional Specifications	Requirements `[FUNC-001]`–`[FUNC-007]` and behavioral contracts.	Functional Specs
Technical Architecture	Specifications `[TECH-001]`–`[TECH-007]`, D2 architecture diagram, and threat model.	Technical Specs
Release Playbook	SemVer, Keep a Changelog, and GPG-signed GitLab release steps.	Release Procedure
Architecture Decisions (ADRs)	Immutable logs of architectural decisions and security trade-offs.	ADR Index
Project Roadmap	Dependency-tracked phased milestones, D2 roadmaps, and audit logs.	Project Roadmap
User Guides	Installation, usage examples, and exception handling.	User Manual
Crystal API Reference	Complete interactive type hierarchy and method signatures.	API Reference