λgitsite

~ober/jerboa-crypto

Imported from ~/mine/jerboa-crypto

download snapshot

about

# 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

```bash
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.

recent commits