README.md — sigil-crypto

1# sigil-crypto

3Cryptographic primitives for [Sigil](https://codeberg.org/sigil/sigil).

5Hashing, message authentication, key derivation, Ed25519 signatures,

6minisign verification, base64 encoding, and

7cryptographically secure random bytes. Built on a vendored mbedTLS and

8usable independently of TLS.

10## Modules

12| Module | Purpose |

13|--------------------------|----------------------------------------------------------|

14| `(sigil crypto)` | SHA/HMAC/PBKDF2 hashes, Ed25519, BLAKE2b, base64, random |

15| `(sigil crypto minisign)`| Parse and verify minisign public keys and signatures |

17## API summary

19| Procedure | Purpose |

20|-------------------------|-------------------------------------------------|

21| `sha1` | SHA-1 hex digest of a string or bytevector |

22| `sha256` | SHA-256 hex digest of a string or bytevector |

23| `sha256-bytes` | SHA-256 digest as a bytevector |

24| `hmac-sha256` | HMAC-SHA256 hex digest (key + message) |

25| `hmac-sha1` | HMAC-SHA1 hex digest (key + message) |

26| `pbkdf2-sha1` | PBKDF2-SHA1 key derivation (hex digest) |

27| `base64-encode` | Base64 encoding of a string or bytevector |

28| `base64-decode` | Base64 decoding to a string |

29| `random-bytes` | Cryptographically secure random bytevector |

30| `timing-safe-equal?` | Constant-time string comparison |

31| `ed25519-verify` | Verify an Ed25519 (RFC 8032) signature |

32| `ed25519-public-key` | Ed25519 public key from a 32-byte seed |

33| `ed25519-sign` | Ed25519 signature with a 32-byte seed |

34| `blake2b-512` | BLAKE2b digest (64 bytes) as a bytevector |

35| `minisign-verify` | Verify a minisign signature; returns the trusted comment or #f |

36| `minisign-verify-prehashed` | As `minisign-verify`, refusing legacy signatures (`minisign -V -H`) |

37| `minisign-failure-reason` | #f when a signature verifies, else why it failed |

39## minisign without the minisign binary

41```scheme

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

44(define key (minisign-parse-public-key

45 "RWRa9dPSUBFexBbLdzZIfuAmuCYL736UeHC7IbdAOIYpgGIyDmWRaQHY"))

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

48(minisign-verify-prehashed key sig (read-file-bytes "registry.json"))

49; => "registry=pkg.usesigil.org path=/v1/meta/registry.json seq=1 ts=..."

50; or #f when the file, signature or trusted comment has been altered

51```

53Checks the key id, the signature over the file (`ED`, prehashed with

54BLAKE2b-512, or legacy `Ed`) and the global signature over the trusted

55comment, as `minisign -V` does. Verification is cofactored (RFC 8032

56section 5.1.7) and rejects small-order keys and R values; it agrees with

57libsodium, which minisign uses, except when the key or R has a

58small-order component, which only the key holder can produce and

59minisign never does. Use `minisign-verify-prehashed` (`-V -H`) for new

60code: without it, a prehashed signature relabelled as legacy verifies

61over the file's BLAKE2b digest, as it does in `minisign -V`.

63## WebAssembly

65On wasm32-wasi only the Monocypher half of the package is built:

66`ed25519-verify`, `ed25519-public-key`, `ed25519-sign`, `blake2b-512` and

67`(sigil crypto minisign)`. Every Mbed TLS-backed procedure raises

68"not available on wasm" there, because Mbed TLS does not build for

69wasm32-wasi yet. The browser build uses this same compiled Ed25519 rather

70than WebCrypto, so the API stays synchronous.

72## System prerequisites

74None beyond a working C toolchain. mbedTLS is vendored under

75`vendor/mbedtls/` and compiled in-tree with a minimal

76`sigil_mbedtls_config.h`. TLS 1.2 and certificate-authenticated TLS 1.3

77are enabled, including PSA, HKDF and RSA-PSS support. Session tickets,

78PSK handshakes and early data remain disabled. The vendored version is

79Mbed TLS 3.6.7; see `vendor/MBEDTLS.md` for upstream provenance.

81Ed25519 and BLAKE2b come from Monocypher 4.0.3, vendored unmodified under

82`vendor/monocypher/` (provenance and the reasons for choosing it in

83`vendor/MONOCYPHER.md`).

85## Dependencies

87- sigil-stdlib

89## Build

91```sh

92sigil deps install

93sigil build

94sigil test --report

95```

97Two further gates need tools the suite does not:

99```sh

100test/differential/run.sh # Ed25519 against libsodium (needs guix)

101node test/wasm/run-wasm-test.mjs # host, static musl and wasm32-wasi agree (needs guix, node)

102```

103

104The first build compiles ~108 mbedTLS translation units plus

105`native/crypto.c`. Subsequent builds hit the cache. The minisign

106fixtures in `test/fixtures/minisign` are regenerated with

107`test/fixtures/minisign/make-fixtures.sh`.

108

109## Usage

110

111```scheme

112(import (sigil crypto))

113

114(sha256 "hello") ; => hex string

115(sha256-bytes "hello") ; => 32-byte bytevector

116(hmac-sha256 "secret-key" "message") ; => hex string

117(pbkdf2-sha1 "password" "salt" 4096 20) ; => hex string

118(base64-encode "hello") ; => "aGVsbG8="

119(base64-decode "aGVsbG8=") ; => "hello"

120(random-bytes 16) ; => #u8(...)

121(timing-safe-equal? "abc" "abc") ; => #t

122```

123

124## License

125

126BSD-3-Clause.

127

128Vendored mbedTLS (under `vendor/mbedtls/`) is distributed under

129Apache-2.0 OR GPL-2.0-or-later. sigil-crypto's own sources are

130BSD-3-Clause. See `vendor/mbedtls/LICENSE` for the mbedTLS terms.

131

132Vendored Monocypher (under `vendor/monocypher/`) is dual-licensed

133BSD-2-Clause OR CC0-1.0; sigil-crypto uses it under BSD-2-Clause. See

134`vendor/monocypher/LICENCE.md`.