jerboa-crypto

OpenSSL libcrypto bindings for Jerboa.

Provides hash digests, HMAC, symmetric encryption, Ed25519 signatures, and scrypt KDF.

Status: experimental. Treat this as a low-level FFI binding until the release gates in SECURITY.md are complete.

Requirements

• Jerboa and jerbuild
• A supported, patched OpenSSL libcrypto. Release evidence currently accepts OpenSSL 4.0.1+, 3.6.3+, 3.5.7+, 3.4.6+, or 3.0.21+.
• GCC

Build & Test

make
make test
make test-loader
make test-native
make scrypt-benchmark
make audit
make sbom
make reproducibility-report
make target-evidence
make release-evidence

Production support is still blocked until make target-evidence records a marker-complete proof through JCRYPTO_TARGET_PROOF_FILE; production release hosts should set JCRYPTO_REQUIRE_TARGET_PROOF=1. The proof covers target OpenSSL advisory/linkage review, platform CVE review, external crypto/FFI review, algorithm-policy exceptions, downstream protocol integration, and cross-platform smoke. It must not contain keys, tokens, plaintext crypto material, private paths, hostnames, customer data, or raw command output.

API

Random

• (random-bytes n) → bytevector of n cryptographically random bytes
• (random-bytes! bv) → fills bytevector in place

Digest (Hash)

• (md5 data), (sha1 data), (sha256 data), (sha384 data), (sha512 data) → bytevector
• (digest algo data) → bytevector (algo = "md5", "sha256", etc.)
• (digest-size algo) → integer
• Streaming: make-digest-ctx, digest-init!, digest-update!, digest-final!, free-digest-ctx

MD5 and SHA-1 are exposed for compatibility and test-vector use, not for new security designs.

Production consumers should use the default allowlist in docs/algorithm-policy.md unless a protocol standard requires otherwise.

HMAC

• (hmac algo key data) → bytevector
• (hmac-md5 key data), (hmac-sha256 key data), etc.

Cipher (Symmetric Encryption)

• (encrypt algo key iv plaintext) → bytevector
• (decrypt algo key iv ciphertext) → bytevector
• (cipher-key-length algo), (cipher-iv-length algo), (cipher-block-size algo)
• Streaming: make-cipher-ctx, encrypt-init!/update!/final!, decrypt-init!/update!/final!

Ed25519

• (ed25519-keygen) → (values private-key public-key)
• (ed25519-sign privkey message) → signature bytevector
• (ed25519-verify pubkey message signature) → #t/#f

KDF

• (scrypt password salt size [N r p]) → derived key bytevector. The three-argument form uses version-1 policy N=65536, r=8, p=2 (64 MiB).
• (scrypt-memory-bytes N r) and (scrypt-work-factor N r p) expose concrete cost estimates; (scrypt-parameters-acceptable? N r p) checks policy.
• (scrypt-password-hash password) creates a random-salt, parameter-encoded record; (scrypt-password-verify? password record) verifies it in constant time and (scrypt-password-needs-rehash? record) signals policy upgrades.

The explicit form still enforces power-of-two N, salt/output/input bounds, 8–256 MiB estimated memory, and bounded work. It does not provide an escape hatch for the former N=1024, r=8, p=16 profile.

Dynamic development loading is disabled unless both JERBOA_CRYPTO_ALLOW_DYNAMIC_NATIVE=1 and an exact canonical absolute JERBOA_CRYPTO_LIB directory are supplied. Production binaries should pre-register the shim symbols; CWD, bare-name, relative, symlinked, writable, and privileged-process overrides are rejected. Inherited DYLD/LD search overrides are also rejected before any development load, and every provider must expose the JCR1 ABI canary and symbol closure.

License

Apache License 2.0.