boringssl

Idiomatic Haskell bindings to Google's 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

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 organization. See 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.