README
¶
CIRCL
CIRCL (Cloudflare Interoperable, Reusable Cryptographic Library) is a collection of cryptographic primitives written in Go. The goal of this library is to be used as a tool for experimental deployment of cryptographic algorithms targeting Post-Quantum (PQ) and Elliptic Curve Cryptography (ECC).
Security Disclaimer
🚨 This library is offered as-is, and without a guarantee. Therefore, it is expected that changes in the code, repository, and API occur in the future. We recommend to take caution before using this library in a production application since part of its content is experimental.
Installation
You can get it by typing:
$ go get -u github.com/cloudflare/circl
Versioning
Version numbers are Semvers. We release a minor version for new functionality, a major version for breaking API changes, and increment the patchlevel for bugfixes.
Implemented Primitives
| Category | Algorithms | Description | Applications |
|---|---|---|---|
| PQ Key Exchange | SIDH | SIDH provide key exchange mechanisms using ephemeral keys. | Post-quantum key exchange in TLS |
| PQ KEM | SIKE | SIKE is a key encapsulation mechanism (KEM). | Post-quantum key exchange in TLS |
| Key Exchange | X25519, X448 | RFC-7748 provides new key exchange mechanisms based on Montgomery elliptic curves. | TLS 1.3. Secure Shell. |
| Key Exchange | FourQ | One of the fastest elliptic curves at 128-bit security level. | Experimental for key agreement and digital signatures. |
| Key Exchange / Digital signatures | P-384 | Our optimizations reduce the burden when moving from P-256 to P-384. | ECDSA and ECDH using Suite B at top secret level. |
| Digital Signatures | Ed25519 | RFC-8032 provides new signature schemes based on Edwards curves. | Digital certificates and authentication. |
Work in Progress
| Category | Algorithms | Description | Applications |
|---|---|---|---|
| Hashing to Elliptic Curve Groups | Several algorithms: Elligator2, Ristretto, SWU, Icart. | Protocols based on elliptic curves require hash functions that map bit strings to points on an elliptic curve. | VOPRF. OPAQUE. PAKE. Verifiable random functions. |
| Bilinear Pairings | Plans for moving BN256 to stronger pairing curves. | A bilineal pairing is a mathematical operation that enables the implementation of advanced cryptographic protocols, such as identity-based encryption (IBE), short digital signatures (BLS), and attribute-based encryption (ABE). | Geo Key Manager, Randomness Beacon, Ethereum and other blockchain applications. |
| PQ KEM | HRSS-SXY | Lattice (NTRU) based key encapsulation mechanism. | Key exchange for low-latency environments |
| PQ KEM | Kyber | Lattice (M-LWE) based key encapsulation mechanism. | Post-Quantum Key exchange |
| PQ Key Exchange | cSIDH | Isogeny based drop-in replacement for Diffie–Hellman | Post-Quantum Key exchange. |
| PQ Digital Signatures | SPHINCS+ | Stateless hash-based signature scheme | Post-Quantum PKI |
Testing and Benchmarking
Library comes with number of make targets which can be used for testing and benchmarking:
test: performs testing of the binary.bench: runs benchmarks.cover: produces coverage.lint: runs set of linters on the code base.
Contributing
To contribute, fork this repository and make your changes, and then make a Pull Request. A Pull Request requires approval of the admin team and a successful CI build.
License
The project is licensed under the BSD License.
Documentation
¶
Overview ¶
Module circl provides collection of cryptographic primitives. The goal of this module is to be used as a tool for experimental deployment of cryptographic algorithms targeting Post-Quantum (PQ) and Elliptic Curve Cryptography (ECC).
Following blog post describes ideas behind CIRCL in more details: https://blog.cloudflare.com/introducing-circl/
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package dh provides variety of Diffie-Hellman key exchange methods.
|
Package dh provides variety of Diffie-Hellman key exchange methods. |
|
curve4q
Package curve4q implements Diffie-Hellman operations using the FourQ curve at the 128-bit security level.
|
Package curve4q implements Diffie-Hellman operations using the FourQ curve at the 128-bit security level. |
|
sidh
Package sidh provides implementation of experimental post-quantum Supersingular Isogeny Diffie-Hellman (SIDH) as well as Supersingular Isogeny Key Encapsulation (SIKE).
|
Package sidh provides implementation of experimental post-quantum Supersingular Isogeny Diffie-Hellman (SIDH) as well as Supersingular Isogeny Key Encapsulation (SIKE). |
|
sidh/internal/common
Package common provides types, variables, constants and functions commonly used in SIDH or SIKE.
|
Package common provides types, variables, constants and functions commonly used in SIDH or SIKE. |
|
sidh/internal/p503
Package p503 provides implementation of field arithmetic used in SIDH and SIKE.
|
Package p503 provides implementation of field arithmetic used in SIDH and SIKE. |
|
sidh/internal/p751
Package p751 provides implementation of field arithmetic used in SIDH and SIKE.
|
Package p751 provides implementation of field arithmetic used in SIDH and SIKE. |
|
sidh/internal/shake
Package shake provides implementation of SHA-3 and cSHAKE This code has been copied from golang.org/x/crypto/sha3 and havily modified.
|
Package shake provides implementation of SHA-3 and cSHAKE This code has been copied from golang.org/x/crypto/sha3 and havily modified. |
|
x25519
Package x25519 provides Diffie-Hellman functions as specified in RFC-7748.
|
Package x25519 provides Diffie-Hellman functions as specified in RFC-7748. |
|
x448
Package x448 provides Diffie-Hellman functions as specified in RFC-7748.
|
Package x448 provides Diffie-Hellman functions as specified in RFC-7748. |
|
Package ecc provides implementation of arithmetic on some elliptic curves.
|
Package ecc provides implementation of arithmetic on some elliptic curves. |
|
fourq
Package fourq provides elliptic curve operations over FourQ curve.
|
Package fourq provides elliptic curve operations over FourQ curve. |
|
p384
Package p384 provides optimized elliptic curve operations on the P-384 curve.
|
Package p384 provides optimized elliptic curve operations on the P-384 curve. |
|
internal
|
|
|
Package math provides some utility functions for big integers.
|
Package math provides some utility functions for big integers. |
|
fp25519
Package fp25519 provides prime field arithmetic over GF(2^255-19).
|
Package fp25519 provides prime field arithmetic over GF(2^255-19). |
|
fp448
Package fp448 provides prime field arithmetic over GF(2^448-2^224-1).
|
Package fp448 provides prime field arithmetic over GF(2^448-2^224-1). |
|
pke
|
|
|
kyber/internal/common/asm
module
|
|
|
sign
|
|
|
ed25519
Package ed25519 implements Ed25519 signature scheme as described in RFC-8032.
|
Package ed25519 implements Ed25519 signature scheme as described in RFC-8032. |
|
internal/dilithium/asm
module
|
|
|
simd
|
|
|
keccakf1600/internal/asm
module
|