This repository is parameter selection and lightweight wrapper around a number of Go 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.
- Digital signatures
- Encryption
- Key derivation
- Serialization
- Credential / Attestation
Signatures come from xdsa, encryption from xhpke, and cose wraps both into COSE envelopes using the Dark Bio wire profile documented in the cose package.
go get github.com/dark-bio/crypto-goCOSE signing and verification and xHPKE encryption and decryption use an application domain that both sides must agree on. It is prefixed with dark-bio-v1: internally and binds the operation to one purpose. Choose distinct domains for distinct purposes. Raw xdsa signatures carry no such application domain, which is why the cose envelopes are the recommended entry point.
func example() (string, error) {
// Long term identities, one for signing and one for receiving
signer := xdsa.GenerateKey()
recipient := xhpke.GenerateKey()
domain, drift := []byte("example"), uint64(60)
// A detached signature over a message that travels separately
signature, err := cose.SignDetached("payload", signer, domain)
if err != nil {
return "", err
}
if err := cose.VerifyDetached(signature, "payload", signer.PublicKey(), domain, &drift); err != nil {
return "", err
}
// Sign and encrypt a payload to the recipient, then open and verify it back.
// The second argument is authenticated but must be supplied separately.
sealed, err := cose.Seal("payload", "metadata", signer, recipient.PublicKey(), domain)
if err != nil {
return "", err
}
return cose.Open[string](sealed, "metadata", recipient, signer.PublicKey(), domain, &drift)
}The cbor package uses Go struct tags to generate encoders and decoders for structs. By default, structs are represented as maps, with the possibility of requesting array encoding.
In map encoding mode, all keys are integers. This is a deliberate restriction to support maps but still force non-wasteful encoding. Each field requires cbor:"N,key". To encode a struct as an array, use cbor:"_,array".
This is a sibling package with the Rust github.com/dark-bio/crypto-rs; as in, both repositories implement the same feature sets and API surfaces at the same version points. This naturally means PRs merged into one project necessarily have to have a counter-PR in the other project.
The Rust sibling currently has a Flutter binding github.com/dark-bio/crypto-fl that exposes the same API surface and versioning; implemented by wrapping the Rust code via FFI rather than reimplementing it.
The Rust sibling also has a TypeScript binding github.com/dark-bio/crypto-ts that also exposes the same API surface and versioning; implemented by wrapping the Rust code via WASM rather than reimplementing it.
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.