Preparing README for next release.

cloudflare · Oct 13, 2021 · 0518755 · 0518755
1 parent 41ce555
commit 0518755
Show file tree

Hide file tree

Showing 4 changed files with 59 additions and 43 deletions.
diff --git a/.gitignore b/.gitignore
diff --git a/README.md b/README.md
@@ -2,6 +2,7 @@
 
 # CIRCL
 
+[![GitHub release](https://img.shields.io/github/release/cloudflare/circl.svg)](https://GitHub.com/cloudflare/circl/releases/)
 [![CIRCL](https://github.com/cloudflare/circl/workflows/CIRCL/badge.svg)](https://github.com/cloudflare/circl/actions)
 [![GoDoc](https://godoc.org/github.com/cloudflare/circl?status.svg)](https://pkg.go.dev/github.com/cloudflare/circl?tab=overview)
 [![Go Report Card](https://goreportcard.com/badge/github.com/cloudflare/circl)](https://goreportcard.com/report/github.com/cloudflare/circl)
@@ -14,44 +15,62 @@ 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.
+🚨 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. All security issues must be reported, please notify us immediately following the instructions given in our [Security Policy](https://github.com/cloudflare/circl/security/policy).
 
 ## Installation
 
-You can get it by typing:
+You can get CIRCL by fetching:
 
 ```sh
 go get -u github.com/cloudflare/circl
 ```
 
-## Versioning
+## List of Algorithms
 
-Version numbers are [Semvers](https://semver.org/). We release a minor version for new functionality, a major version for breaking API changes, and increment the patchlevel for bugfixes.
+#### Diffie-Hellman Protocol
+- [X25519](https://datatracker.ietf.org/doc/html/rfc7748/)
+- [X448](https://datatracker.ietf.org/doc/html/rfc7748/)
+- [Curve4Q](https://datatracker.ietf.org/doc/draft-ladd-cfrg-4q/)
 
-## Implemented Primitives
+#### Digital Signature Schemes
+- [Ed25519](https://datatracker.ietf.org/doc/rfc8032/)
+- [Ed448](https://datatracker.ietf.org/doc/rfc8032/)
 
-| Category | Algorithms | Description | Applications |
-|-----------|------------|-------------|--------------|
-| PQ Key Exchange | SIDH | SIDH provide key exchange mechanisms using ephemeral keys. | Post-quantum key exchange in TLS |
-| PQ Key Exchange | cSIDH | Isogeny based drop-in replacement for Diffie–Hellman | Post-Quantum Key exchange. |
-| 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, Ed448 | RFC-8032 provides new signature schemes based on Edwards curves. | Digital certificates and authentication. |
-| Key Encapsulation | P-256, P-384, P-521, X25519 and X448 | Key encapsulation methods based on Diffie-Hellman. | HPKE |
-| Hybrid Public-Key Encryption | Base, Auth, PSK, AuthPSK | [HPKE](https://www.ietf.org/archive/id/draft-irtf-cfrg-hpke-07.html) is a combination of KEM and AEAD. | TLS |
-| PQ KEM/PKE | Kyber | Lattice (M-LWE) based IND-CCA2 secure key encapsulation mechanism and IND-CPA secure public key encryption  | Post-Quantum Key exchange |
-| PQ Digital Signatures | Dilithium, Hybrid modes | Lattice (Module LWE) based signature scheme | Post-Quantum PKI |
+#### Groups based on Elliptic Curves
+ - P-256, P-384, P-521, [FIPS 186-4](https://doi.org/10.6028/NIST.FIPS.186-4)
+ - [Ristretto](https://datatracker.ietf.org/doc/draft-irtf-cfrg-ristretto255-decaf448/01/)
+ - [Hash to Curve](https://datatracker.ietf.org/doc/draft-irtf-cfrg-hash-to-curve/)
 
-### Work in Progress
+#### High-Level Protocols
+ - Bilinear pairings with [BLS12-381](https://electriccoin.co/blog/new-snark-curve/).
+ - [HPKE](https://datatracker.ietf.org/doc/draft-irtf-cfrg-hpke/): Hybrid Public-Key Encryption
+ - [VOPRF](https://datatracker.ietf.org/doc/draft-irtf-cfrg-voprf/): Verifiable Oblivious Pseudorandom function.
 
-| 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 Digital Signatures | SPHINCS+ | Stateless hash-based signature scheme | Post-Quantum PKI |
+#### Post-Quantum Key Encapsulation Methods
+ - [SIDH/SIKE](https://sike.org/): Supersingular Key Encapsulation with  rimes p434, p503, p751
+ - [CSIDH](https://csidh.isogeny.org/): Post-Quantum Commutative Group Action
+ - [Kyber](https://pq-crystals.org/kyber/) KEM: modes 512, 768, 1024
+
+#### Post-Quantum Public-Key Encryption
+ - [Kyber](https://pq-crystals.org/kyber/) PKE: modes 512, 768, 1024
+
+#### Post-Quantum Digital Signature Schemes
+ - [Dilithium](https://pq-crystals.org/dilithium/): modes 2, 3, 5
+
+#### Field Arithmetic
+ - Fp25519, Fp448, Fp381
+
+#### Elliptic Curves
+ - P-384 Curve
+ - [FourQ](https://eprint.iacr.org/2015/565)
+ - [Goldilocks](https://eprint.iacr.org/2015/625)
+
+#### Parallel SIMD
+ - [Keccak](https://keccak.team/keccak_specs_summary.html) f1600 Permutation
+
+#### XOF: eXtendable Output Functions
+ - [FIPS 202](https://doi.org/10.6028/NIST.FIPS.202): SHAKE128 and SHAKE256
+ - [BLAKE2X](https://www.blake2.net/blake2x.pdf): BLAKE2XB and BLAKE2XS
 
 ## Testing and Benchmarking
 
@@ -69,17 +88,16 @@ 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.
 
-## How to Cite 
+## How to Cite
 
-To cite CIRCL, use one of the following formats and update with the date
-you accessed this project.
+To cite CIRCL, use one of the following formats and update the version and  date you accessed this project.
 
 APA Style
 
 ```
-Faz-Hernández, A. and Kwiatkowski, K. (2019). Introducing CIRCL: 
-An Advanced Cryptographic Library. Cloudflare. Available at 
-https://github.com/cloudflare/circl. Accessed Feb 2021.
+Faz-Hernández, A. and Kwiatkowski, K. (2019). Introducing CIRCL:
+An Advanced Cryptographic Library. Cloudflare. Available at
+https://github.com/cloudflare/circl. v1.1.0 Accessed Oct 2021.
 ```
 
 Bibtex Source
@@ -90,11 +108,11 @@ Bibtex Source
   author       = {Armando Faz-Hern\'{a}ndez and Kris Kwiatkowski},
   organization = {Cloudflare},
   abstract     = {{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 
+                   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).}},
-  note         = {Available at \url{https://github.com/cloudflare/circl}. Accessed Feb 2021},
+  note         = {Available at \url{https://github.com/cloudflare/circl}. v1.1.0 Accessed Oct 2021},
   month        = jun,
   year         = {2019}
 }

diff --git a/go.mod b/go.mod
@@ -1,9 +1,9 @@
 module github.com/cloudflare/circl
 
-go 1.12
+go 1.15
 
 require (
 	github.com/bwesterb/go-ristretto v1.2.0
-	golang.org/x/crypto v0.0.0-20210817164053-32db794688a5
-	golang.org/x/sys v0.0.0-20210902050250-f475640dd07b
+	golang.org/x/crypto v0.0.0-20210921155107-089bfa567519
+	golang.org/x/sys v0.0.0-20211007075335-d3039528d8ac
 )
diff --git a/go.sum b/go.sum
@@ -1,12 +1,12 @@
 github.com/bwesterb/go-ristretto v1.2.0 h1:xxWOVbN5m8NNKiSDZXE1jtZvZnC6JSJ9cYFADiZcWtw=
 github.com/bwesterb/go-ristretto v1.2.0/go.mod h1:fUIoIZaG73pV5biE2Blr2xEzDoMj7NFEuV9ekS419A0=
-golang.org/x/crypto v0.0.0-20210817164053-32db794688a5 h1:HWj/xjIHfjYU5nVXpTM0s39J9CbLn7Cc5a7IC5rwsMQ=
-golang.org/x/crypto v0.0.0-20210817164053-32db794688a5/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
+golang.org/x/crypto v0.0.0-20210921155107-089bfa567519 h1:7I4JAnoQBe7ZtJcBaYHi5UtiO8tQHbUSXxL+pnGRANg=
+golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
 golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.0.0-20210902050250-f475640dd07b h1:S7hKs0Flbq0bbc9xgYt4stIEG1zNDFqyrPwAX2Wj/sE=
-golang.org/x/sys v0.0.0-20210902050250-f475640dd07b/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20211007075335-d3039528d8ac h1:oN6lz7iLW/YC7un8pq+9bOLyXrprv2+DKfkJY+2LJJw=
+golang.org/x/sys v0.0.0-20211007075335-d3039528d8ac/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=