Nuckle

NaCl for Knuckleheads — pure Crystal crypto primitives, no libsodium.

A Crystal port of the Ruby nuckle gem. Same algorithms, same API shape, same "don't use this" disclaimers.

Is it any good?

No. See SECURITY.md.

Don't use this

BigInt arithmetic (used by Curve25519 and Poly1305) is not constant-time, so private keys leak via timing side channels. Use natron (libsodium binding) for anything that matters.

Why does this exist?

• Zero-dependency environments and CI
• Seeing how fast Crystal's native UInt32/UInt64 and LLVM codegen are at these algorithms, vs. real libsodium
• Education — all five primitives fit in ~800 readable lines of Crystal
• Testing and fuzzing against natron

Primitives

Usage

require "nuckle"

# Keypair
sk = Nuckle::PrivateKey.generate
pk = sk.public_key

# Public-key encryption
alice = Nuckle::PrivateKey.generate
bob   = Nuckle::PrivateKey.generate
nonce = Nuckle::Random.random_bytes(24)

box = Nuckle::Box.new(bob.public_key, alice)
ct  = box.encrypt(nonce, "hello".to_slice)

box2 = Nuckle::Box.new(alice.public_key, bob)
pt   = box2.decrypt(nonce, ct)  # => "hello"

# Symmetric
key   = Nuckle::Random.random_bytes(32)
nonce = Nuckle::Random.random_bytes(24)
box   = Nuckle::SecretBox.new(key)
ct    = box.encrypt(nonce, "hello".to_slice)
pt    = box.decrypt(nonce, ct)

API Compatibility

The public API mirrors natron exactly — swap the module name and it Just Works.

Verification

All primitives are tested against official test vectors (RFC 7748, RFC 8439, NaCl distribution, BLAKE3 spec) and cross-validated against libsodium (via natron) to produce byte-identical output.

License

ISC