https://github.com/haskell-cryptography/boringssl-hs
Bindings to BoringSSL in Haskell
https://github.com/haskell-cryptography/boringssl-hs
Last synced: 3 months ago
JSON representation
Bindings to BoringSSL in Haskell
- Host: GitHub
- URL: https://github.com/haskell-cryptography/boringssl-hs
- Owner: haskell-cryptography
- License: apache-2.0
- Created: 2026-02-09T07:08:35.000Z (4 months ago)
- Default Branch: dev
- Last Pushed: 2026-02-28T17:27:20.000Z (4 months ago)
- Last Synced: 2026-02-28T19:58:22.273Z (4 months ago)
- Language: Haskell
- Size: 593 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# boringssl
[](https://github.com/haskell-cryptography/boringssl-hs/actions/workflows/ci.yml)
Idiomatic Haskell bindings to Google's [BoringSSL](https://boringssl.googlesource.com/boringssl/) cryptography library.
> **Warning:** This library is experimental and under active construction. The API
> is unstable and may change without notice. Do not use this in production systems.
## Overview
This library provides idiomatic Haskell bindings to BoringSSL's cryptographic
primitives via the FFI. BoringSSL is Google's maintained fork of OpenSSL,
battle-tested across Chrome, Android, and Google's infrastructure. These
bindings give Haskell programs access to the same well-audited cryptographic
implementations, wrapped in an API that feels natural in Haskell: pure
interfaces where possible, `ByteString`-based data types throughout, and proper
memory management via `ForeignPtr` finalizers.
## Supported GHC versions
| GHC | Linux | macOS | Windows |
|---------|-------|-------|---------|
| 9.6.x | Yes | Yes | Yes |
| 9.8.x | Yes | Yes | — |
| 9.10.x | Yes | Yes | — |
## Features
**Hash functions** — SHA-1, SHA-2 (224/256/384/512/512-256), MD5, BLAKE2b-256.
One-shot and streaming APIs.
**MACs** — HMAC (all hash algorithms), CMAC (AES-128/256), SipHash.
**Key derivation** — HKDF, PBKDF2, scrypt, TLS PRF.
**Authenticated encryption (AEAD)** — AES-GCM (128/192/256),
ChaCha20-Poly1305, XChaCha20-Poly1305, AES-GCM-SIV, AES-CTR-HMAC-SHA256,
AES-EAX, AES-CCM.
**Symmetric ciphers** — AES-128/256 in CBC, CTR, ECB, and OFB modes.
**Asymmetric cryptography** — Ed25519, X25519, ECDSA (P-256/P-384/P-521),
ECDH, RSA (sign/verify/encrypt with PSS, PKCS#1 v1.5, and OAEP).
**Post-quantum** — ML-KEM (Kyber), ML-DSA (Dilithium), SLH-DSA (SPHINCS+),
X-Wing (X25519 + ML-KEM-768 hybrid).
**Protocols** — HPKE (RFC 9180), SPAKE2, TrustToken.
**Encoding & PKI** — Base64, PEM, X.509 parsing, private key
serialization.
## Quick start
```haskell
import Crypto.BoringSSL.AEAD
import Crypto.BoringSSL.Digest
import Crypto.BoringSSL.Random (getRandomBytes)
-- Hash some data
let digest = hashSHA256 "hello, world"
-- Authenticated encryption with AES-256-GCM
main :: IO ()
main = do
key <- getRandomBytes 32
case newAEADCtx AES256GCM key of
Left err -> error (show err)
Right ctx -> do
nonce <- generateNonce ctx
let ad = "" -- associated data
ciphertext = seal ctx nonce ad "secret message"
case open ctx nonce ad ciphertext of
Left err -> error (show err)
Right plaintext -> print plaintext -- "secret message"
```
## Building
The library compiles BoringSSL from source (included as a Git submodule under
`third_party/boringssl`), so no system-level BoringSSL installation is required.
You will need a C++17 compiler (`g++` or `clang++`).
```
git clone --recurse-submodules https://github.com/haskell-cryptography/boringssl-hs.git
cd boringssl-hs
cabal build
```
To run the test suite:
```
cabal test
```
### Assembly optimizations
By default, BoringSSL is compiled with portable C fallback implementations.
On x86\_64 and aarch64 (Linux and macOS), you can enable hand-written assembly
optimizations for improved performance and stronger constant-time guarantees:
```
cabal build -fasm
```
The `-fasm` flag enables optimized routines for AES, SHA, ChaCha20, Poly1305,
P-256, and Montgomery multiplication. On unsupported platforms, the flag is
silently ignored.
### Platform notes
- **Linux**: Requires `g++` (or `clang++`) and `libstdc++`. Tested on x86\_64
and aarch64.
- **macOS**: Requires `clang++` (Xcode command-line tools). Tested on Apple
Silicon and Intel.
- **Windows**: Requires MinGW `g++`. Assembly optimizations are not available.
## Security considerations
- **Nonce management**: AES-GCM nonce reuse is catastrophic — it completely
destroys both confidentiality and authenticity. Use `generateNonce` for
random nonces, or use AES-GCM-SIV for nonce-misuse resistance.
- **Constant-time operations**: BoringSSL provides constant-time
implementations for sensitive operations. Enabling `-fasm` provides stronger
constant-time guarantees via hand-written assembly.
- **Secure memory**: Private key material can be stored in `SecureBytes`, which
is allocated outside the GC heap and zeroed on deallocation.
- **Unauthenticated ciphers**: The `Cipher` module (AES-CBC, CTR, ECB, OFB)
does **not** provide integrity protection. Prefer AEAD ciphers for
encryption.
- **PKCS#1 v1.5 encryption**: The RSA PKCS#1 v1.5 encryption functions are
deprecated due to Bleichenbacher-style attacks. Use OAEP instead.
## Governance
This project is part of the [haskell-cryptography](https://github.com/haskell-cryptography)
organization. See [STRUCTURE.md](https://github.com/haskell-cryptography/governance/blob/main/STRUCTURE.md)
for governance details.
## Disclaimer
This is not an officially supported Google product.
## Current status
This library is a work in progress. The cryptographic primitives listed above
are implemented and tested, but you should expect breaking API changes as the
library matures. Contributions and feedback are welcome.