sigil-crypto

Cryptographic primitives for Sigil.

Hashing, message authentication, key derivation, Ed25519 signatures, minisign verification, base64 encoding, and cryptographically secure random bytes. Built on a vendored mbedTLS and usable independently of TLS.

Modules

Module	Purpose
`(sigil crypto)`	SHA/HMAC/PBKDF2 hashes, Ed25519, BLAKE2b, base64, random
`(sigil crypto minisign)`	Parse and verify minisign public keys and signatures

API summary

Procedure	Purpose
`sha1`	SHA-1 hex digest of a string or bytevector
`sha256`	SHA-256 hex digest of a string or bytevector
`sha256-bytes`	SHA-256 digest as a bytevector
`hmac-sha256`	HMAC-SHA256 hex digest (key + message)
`hmac-sha1`	HMAC-SHA1 hex digest (key + message)
`pbkdf2-sha1`	PBKDF2-SHA1 key derivation (hex digest)
`base64-encode`	Base64 encoding of a string or bytevector
`base64-decode`	Base64 decoding to a string
`random-bytes`	Cryptographically secure random bytevector
`timing-safe-equal?`	Constant-time string comparison
`ed25519-verify`	Verify an Ed25519 (RFC 8032) signature
`ed25519-public-key`	Ed25519 public key from a 32-byte seed
`ed25519-sign`	Ed25519 signature with a 32-byte seed
`blake2b-512`	BLAKE2b digest (64 bytes) as a bytevector
`minisign-verify`	Verify a minisign signature; returns the trusted comment or #f
`minisign-verify-prehashed`	As `minisign-verify`, refusing legacy signatures (`minisign -V -H`)
`minisign-failure-reason`	#f when a signature verifies, else why it failed

minisign without the minisign binary

(import (sigil crypto minisign) (sigil fs))

(define key (minisign-parse-public-key
              "RWRa9dPSUBFexBbLdzZIfuAmuCYL736UeHC7IbdAOIYpgGIyDmWRaQHY"))
(define sig (minisign-parse-signature (read-file-bytes "registry.json.minisig")))

(minisign-verify-prehashed key sig (read-file-bytes "registry.json"))
; => "registry=pkg.usesigil.org path=/v1/meta/registry.json seq=1 ts=..."
;    or #f when the file, signature or trusted comment has been altered

Checks the key id, the signature over the file (ED, prehashed with BLAKE2b-512, or legacy Ed) and the global signature over the trusted comment, as minisign -V does. Verification is cofactored (RFC 8032 section 5.1.7) and rejects small-order keys and R values; it agrees with libsodium, which minisign uses, except when the key or R has a small-order component, which only the key holder can produce and minisign never does. Use minisign-verify-prehashed (-V -H) for new code: without it, a prehashed signature relabelled as legacy verifies over the file's BLAKE2b digest, as it does in minisign -V.

WebAssembly

On wasm32-wasi only the Monocypher half of the package is built: ed25519-verify, ed25519-public-key, ed25519-sign, blake2b-512 and (sigil crypto minisign). Every Mbed TLS-backed procedure raises "not available on wasm" there, because Mbed TLS does not build for wasm32-wasi yet. The browser build uses this same compiled Ed25519 rather than WebCrypto, so the API stays synchronous.

System prerequisites

None beyond a working C toolchain. mbedTLS is vendored under vendor/mbedtls/ and compiled in-tree with a minimal sigil_mbedtls_config.h. TLS 1.2 and certificate-authenticated TLS 1.3 are enabled, including PSA, HKDF and RSA-PSS support. Session tickets, PSK handshakes and early data remain disabled. The vendored version is Mbed TLS 3.6.7; see vendor/MBEDTLS.md for upstream provenance.

Ed25519 and BLAKE2b come from Monocypher 4.0.3, vendored unmodified under vendor/monocypher/ (provenance and the reasons for choosing it in vendor/MONOCYPHER.md).

Dependencies

sigil-stdlib

Build

sigil deps install
sigil build
sigil test --report

Two further gates need tools the suite does not:

test/differential/run.sh          # Ed25519 against libsodium (needs guix)
node test/wasm/run-wasm-test.mjs  # host, static musl and wasm32-wasi agree (needs guix, node)

The first build compiles ~108 mbedTLS translation units plus native/crypto.c. Subsequent builds hit the cache. The minisign fixtures in test/fixtures/minisign are regenerated with test/fixtures/minisign/make-fixtures.sh.

Usage

(import (sigil crypto))

(sha256 "hello")                          ; => hex string
(sha256-bytes "hello")                    ; => 32-byte bytevector
(hmac-sha256 "secret-key" "message")      ; => hex string
(pbkdf2-sha1 "password" "salt" 4096 20)   ; => hex string
(base64-encode "hello")                   ; => "aGVsbG8="
(base64-decode "aGVsbG8=")                ; => "hello"
(random-bytes 16)                         ; => #u8(...)
(timing-safe-equal? "abc" "abc")          ; => #t

License

BSD-3-Clause.

Vendored mbedTLS (under vendor/mbedtls/) is distributed under Apache-2.0 OR GPL-2.0-or-later. sigil-crypto's own sources are BSD-3-Clause. See vendor/mbedtls/LICENSE for the mbedTLS terms.

Vendored Monocypher (under vendor/monocypher/) is dual-licensed BSD-2-Clause OR CC0-1.0; sigil-crypto uses it under BSD-2-Clause. See vendor/monocypher/LICENCE.md.