Cryptography primitives and wrappers
npm install @darkbio/crypto
This repository is parameter selection and lightweight wrapper around a number of (WASM wrapped) Rust cryptographic libraries. Its purpose isn't to implement primitives, rather to unify the API surface of existing libraries; limited to the tiny subset needed by the Dark Bio project.
The library is opinionated. Parameters and primitives were selected to provide matching levels of security in a post-quantum world. APIs were designed to make the library easy to use and hard to misuse. Flexibility will always be rejected in favor of safety.
- Certificates
- x509 (RFC-5280): xDSA, xHPKE
- Digital signatures
- xDSA (RFC-DRAFT): MLDSA, EdDSA, SHA512
- EdDSA (RFC-8032): Ed25519
- MLDSA (RFC-DRAFT): Security level 3 (ML-DSA-65)
- RSA¹ (RFC-8017): 2048-bit, SHA256
- Encryption
- xHPKE (RFC-9180): X-WING, HKDF, SHA256, ChaCha20, Poly1305
- X-WING (RFC-DRAFT): MLKEM, ECC
- ECC (RFC-7748): X25519
- MLKEM(RFC-DRAFT): Security level 3 (ML-KEM-768)
- STREAM (RFC N/A, Rage): ChaCha20, Poly1305, 16B tag, 64KB chunk
- Key derivation
- Argon2 (RFC-9106): id variant
- HKDF (RFC-5869): SHA256
- Serialization
- CBOR² (RFC-8949): restricted to bool,null, integer, text, bytes, array, map[int], option
- COSE (RFC-8152): COSE_Sign1, COSE_Encrypt0, dark-bio-v1: domain prefix
¹ Whilst RSA is used in the Dark Bio project for secure boot signatures on pre-quantum hardware, there was no reason to expose that in the TypeScript wrappers. It's available in Rust so anyone needing it can expose it easily themselves.
² As CBOR encoding/decoding would require a full reimplementation in TypeScript, that is delegated to any preferred 3rd party library. To ensure correctness, this package provides a cbor.verify, which it also implicitly enforces that when crossing through cose.
The underlying implementation exists in two sibling repos, which track the same feature set and API surfaces, released at corresponding version points.
- Rust github.com/dark-bio/crypto-rs
- Go github.com/dark-bio/crypto-go
Sibling wrapper exists in one other repo:
- Flutter github.com/dark-bio/crypto-fl
Shoutout to Filippo Valsorda (@filosottile) for lots of tips and nudges on what kind of cryptographic primitives to use and how to combine them properly; and also for his work in general on cryptography standards.
Naturally, many thanks to the authors of all the libraries this project depends on.