README.md — sigil-crypto

1# sigil-crypto

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

5Hashing, message authentication, key derivation, base64 encoding, and

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

7usable independently of TLS.

9## Modules

11| Module | Purpose |

12|-----------------|-----------------------------------------------|

13| `(sigil crypto)`| SHA/HMAC/PBKDF2 hashes, base64, random bytes |

15## API summary

17| Procedure | Purpose |

18|-------------------------|-------------------------------------------------|

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

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

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

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

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

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

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

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

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

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

30## System prerequisites

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

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

34`sigil_mbedtls_config.h` (TLS 1.2 primitives only — TLS 1.3 and the PSA

35crypto machinery are compiled out).

37## Dependencies

39- sigil-stdlib

41## Build

43```sh

44sigil deps install

45sigil build

46sigil test --report

47```

49The first build compiles ~108 mbedTLS translation units plus

50`native/crypto.c`. Subsequent builds hit the cache.

52## Usage

54```scheme

55(import (sigil crypto))

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

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

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

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

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

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

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

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

65```

67## License

69BSD-3-Clause.

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

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

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