cloudflare / circl

CIRCL: Cloudflare Interoperable Reusable Cryptographic Library

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. All security issues must be reported, please notify us immediately following the instructions given in our Security Policy.

Installation

You can get CIRCL by fetching:

go get -u github.com/cloudflare/circl

Alternatively, look at the Cloudflare Go fork to see how to integrate CIRCL natively in Go.

List of Algorithms

Elliptic Curve Cryptography

Diffie-Hellman Protocol

• X25519 and X448 functions. (RFC-7748)
• Curve4Q function based on FourQ curve. (draft-ladd-cfrg-4q)

Digital Signature Schemes

• Ed25519 and Ed448 signatures. (RFC-8032)

Prime Groups

• P-256, P-384, P-521. (FIPS 186-5)
• Ristretto group. (RFC-9496)
• Bilinear pairings: with the BLS12-381 curve, and hash to G1 and G2.
• Hash to curve, hash to field, XMD and XOF expanders. (RFC-9380)

High-Level Protocols

• HPKE: Hybrid Public-Key Encryption (RFC-9180)
• VOPRF: Verifiable Oblivious Pseudorandom functions. (RFC-9497)
• RSA Blind Signatures. (RFC-9474)
• Partilly-blind Signatures. (draft-cfrg-partially-blind-rsa)
• CPABE: Ciphertext-Policy Attribute-Based Encryption. (ia.cr/2019/966)
• OT: Simplest Oblivious Transfer (ia.cr/2015/267).
• Threshold RSA Signatures (Shoup Eurocrypt 2000).

Post-Quantum Cryptography

KEM: Key Encapsulation Methods

• CSIDH: Post-Quantum Commutative Group Action (CSIDH).
• Kyber KEM: modes 512, 768, 1024 (KYBER).
• FrodoKEM: modes 640-SHAKE. (FrodoKEM)
• (insecure, deprecated) SIDH/SIKE: Supersingular Key Encapsulation with primes p434, p503, p751 (SIKE).

Digital Signature Schemes

• Dilithium: modes 2, 3, 5 (Dilithium).

Zero-knowledge Proofs

• Schnorr: Prove knowledge of the Discrete Logarithm. (RFC-8235)
• DLEQ: Prove knowledge of the Discrete Logarithm Equality. (RFC-9497)
• DLEQ in Qn: Prove knowledge of the Discrete Logarithm Equality for subgroup of squares in (Z/nZ)*.

Symmetric Cryptography

XOF: eXtendable Output Functions

• SHAKE128 and SHAKE256 (FIPS 202).
• BLAKE2X: BLAKE2XB and BLAKE2XS (Blake2x)
• KangarooTwelve: fast hashing based on Keccak-p. (KangarooTwelve).
• SIMD Keccak f1600 Permutation.

LWC: Lightweight Cryptography

• Ascon v1.2: Family of AEAD block ciphers (ASCON)

Misc

Integers

• Safe primes generation.
• Integer encoding: wNAF, regular signed digit, mLSBSet representations.

Finite Fields

• Fp25519, Fp448, Fp511, Fp434, Fp503, Fp751.
• Fp381, and its quadratic, sextic and twelveth extensions.
• Polynomials in monomial and Lagrange basis.

Elliptic Curves

• P-384 Curve
• FourQ
• Goldilocks
• BLS12-381

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.

How to Cite

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. v1.3.7 Accessed Dec, 2023.

Bibtex Source

@manual{circl,
  title        = {Introducing CIRCL: An Advanced Cryptographic Library},
  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
                   deployment of cryptographic algorithms targeting Post-Quantum (PQ)
                   and Elliptic Curve Cryptography (ECC).}},
  note         = {Available at \url{https://github.com/cloudflare/circl}. v1.3.7 Accessed Dec, 2023},
  month        = jun,
  year         = {2019}
}

CFF Style

See attached CITATION.cff file.

License

The project is licensed under the BSD-3-Clause License.

circl's Issues

Encrypted SharedSecret location (Sike)?

Where is the encrypted sharedSecret stored when you call:
kem.Encapsulate(ciphertext, sharedSecret, pubB)

My thought was kem.msg that struct property is unexported and not accessible.

Remove GOCACHE=off from Makefile

https://tip.golang.org/doc/go1.11#gocache

Implement OPRF

• Approve the API
• Review @armfazh decaf's implementation, and see if it will easily fit into this.
• Import the code from the voprf repo; but change it to the current API and draft. Potentially only make it work with P-256.
• Check against the sage repo and the test vectors

Might be too early, but perhaps a tag release including Fp434?

I hope you are doing well. I have been working on this: https://github.com/kuking/go-pqsw
I have been depending on tag v1.0.0 but Fp434 is only on master, so now I am on a master commit dep. It would be nice to use v1.0.1 or something like that... low prio, thank you for the library!

Thanks! Ed

Dilithium build error

I'm trying to use this package and am receiving this error:

# github.com/cloudflare/circl/sign/dilithium/mode1
[CENSORED]/go/pkg/mod/github.com/cloudflare/[email protected]/sign/dilithium/mode1/dilithium.go:33:16: undefined: internal.PublicKey
# github.com/cloudflare/circl/sign/dilithium/mode2
[CENSORED]/go/pkg/mod/github.com/cloudflare/[email protected]/sign/dilithium/mode2/dilithium.go:33:16: undefined: internal.PublicKey
# github.com/cloudflare/circl/sign/dilithium/mode2aes
[CENSORED]/go/pkg/mod/github.com/cloudflare/[email protected]/sign/dilithium/mode2aes/dilithium.go:33:16: undefined: internal.PublicKey
# github.com/cloudflare/circl/sign/dilithium/mode3aes
[CENSORED]/go/pkg/mod/github.com/cloudflare/[email protected]/sign/dilithium/mode3aes/dilithium.go:33:16: undefined: internal.PublicKey
# github.com/cloudflare/circl/sign/dilithium/mode1aes
[CENSORED]/go/pkg/mod/github.com/cloudflare/[email protected]/sign/dilithium/mode1aes/dilithium.go:33:16: undefined: internal.PublicKey
# github.com/cloudflare/circl/sign/dilithium/mode4
[CENSORED]/go/pkg/mod/github.com/cloudflare/[email protected]/sign/dilithium/mode4/dilithium.go:33:16: undefined: internal.PublicKey
# github.com/cloudflare/circl/sign/dilithium/mode4aes
[CENSORED]/go/pkg/mod/github.com/cloudflare/[email protected]/sign/dilithium/mode4aes/dilithium.go:33:16: undefined: internal.PublicKey

Checkin go.sum

Generally, go.sum should be checked in with go.mod.

https://github.com/golang/go/wiki/Modules#should-i-commit-my-gosum-file-as-well-as-my-gomod-file

Develop generic implementation of circl/ecc/p384

The packge circl/ecc/p384 contains optimized code for AMD64 and ARM64, but lacks of a generic implementation using math/bits package.

Linting

I would suggest enabling more comprehensive linting. I have personally had good experience with https://github.com/golangci/golangci-lint. I think it would be a good idea to address existing issues and then start running this in CI, or a similar tool.

Running it over the codebase reports issues with the following sub-linters which are probably worth addressing:

• staticcheck
• unconvert
• nakedret
• deadcode
• gosimple
• unused
• varcheck
• gofmt
• ineffassign
• goimports

Then there are also issues reported by the following, which I think are more-or-less debatable.

• gocritic
• golint
• stylecheck
• errcheck
• misspell
• scopelint
• gosec
• lll
• gochecknoglobals
• gochecknoinits

Implement OPRF

The proposed general API:

For client and/or server:

• SetUp(suite): generates keys and set ups context. Similar to Setup(suite) on the voprf lib(which misses the init of the context).
• Client: Blind(input) (token, blindToken)
• Server: Evaluate(sk, pk, blindToken) evaluation
• Client: Unblind(pk, token, blindToken, evaluation) issuedToken
• Server: Finalize(token, issuedToken, info) output

The group:

type CiphersuiteID int
--
 
const (
// P256 is the group generated by P-256 elliptic curve.
P256 GID = iota
// P384 is the group generated by P-384 elliptic curve.
P384
 
P521

(...)
)

type Ciphersuite interface {
	// Creates a new  Ciphersuite object
	New(CiphersuiteID) (Ciphersuite, error)

	// Returns the identifying name of the ciphersuite
	Name() string

	// Returns the canonical (fixed) generator for defined ciphersuite
	Generator() GroupElement

	// Returns the order of the canonical generator in the ciphersuite.
	Order() *big.Int

	// Returns k * G, where G is the canonical generator of the group, and k is
	// some scalar value provided as input.
        // NOTE: this is not defined in the draft
	ScalarMult(*Scalar) (*Point, error)

	// Performs a transformation to encode bytes as a Ciphersuite Point object in the
	// group. 
	HashToGroup([]byte) (*Point, error)

	// Performs a transformation to encode bytes as a Ciphersuite Scalar object in the
	// appropiate group. 
	HashToScalar([]byte) (Scalar, error)

	// Samples a random scalar value from the field of scalars defined by the
	// group order.
	RandomScalar() (*Scalar, error)

	// Base hash function used in conjunction with the PrimeOrderGroup
	Hash() hash.Hash

	// Returns the ByteLength of objects associated with the Ciphersuite
	ByteLength() int
}

NOTE: should we add here as well the serialization/deserialization of points and scalars?

The point (or a GroupElement):

type Point interface {
	// New constructs a Point object for the associated Ciphersuite
	// instantiation
	New(Ciphersuite) Point

	// Returns a bool indicating that the Point is valid
	IsValid() bool

	// Performs a scalar multiplication of the Point with some Scalar
	ScalarMult(*Scalar) (*Point, error)

	// Performs the group addition operation on the calling Point object
	// along with a separate Point provided as input
	Add(Point) (Point, error)

	// Serializes the Point into a byte slice
	Serialize() ([]byte, error)

	// Attempts to deserialize a byte slice into a Point
	Deserialize([]byte) (Point, error)

	// Returns a bool indicating whether two Points are equal
	Equal(Point) bool
}

The Scalar:

type Scalar interface {
	// Serializes the Scalar into a byte slice
	Serialize() ([]byte, error)

	// Attempts to deserialize a byte slice into a Scalar
	Deserialize([]byte) (Point, error)
}

NOTE: do we need any other exposed function for the Scalar?

Steps:

• Approve the presented API
• Review @armfazh decaf's implementation, and see if it will easily fit into this.
• Import the code from the voprf repo; but change it to the current API and draft. Potentially only make it work with P-256.
• Check against the sage repo and the test vectors

Other questions:

• Do we need batched evaluations?
• Do we want to implement VerifyFinalize?

Versioning

The goal is to clearly document versioning for the library. We should have versioning which will allow to do source code incompatible changes, so that we can improve API when doing major release.

SemVer looks OK
https://semver.org/

AVX2 optimisations to Kyber

• Simple arithmetic
• NTT
• InvNTT
• Sampling
• NTT-domain multiplication
• (De)compression of polynomials
• (Un)packing

ABI testing

In some cases we will use assembly in order to optimize the code. We do need to test such code on multiple OS's as they may have different ABI (at least windows is different than linux).
At least in SIDH we don't restore values of some registers. On windows register usage is different than linux and mac, and hence we may have problems which exist only on Win (some problems, meaning crash, stack corruption, etc). As we don't use Win for development, such problems will be quite hard to discover without CI.

Register usage on windows is here:
https://docs.microsoft.com/en-us/cpp/build/x64-software-conventions?view=vs-2019
Registerst to take special care about are: RDI, RSI, R12-R15, RBX, XMM6-XMM15, RBP and RSP (obviously)
Register usage for SysV64:
https://github.com/hjl-tools/x86-psABI/wiki/x86-64-psABI-1.0.pdf
Registerst to take special care about are: RBX, R12-R15, RBP, and RSP (obviously)

Ideally we would have some kind of ABI testing - we fill important registers with known values, call function under test and check if values in those registers are unchanged (boringssl has a test utility called CHECK_ABI, which implements similar functionality - see abi_test.h).
But it would be great first step, if we simply run testing on Win CI.

Other solution would be - we don't provide optimized assembly for windows. In such case we should modify sources and add build tags.

ecc/p384: ScalarMult not constant time

I believe that since math.SignedDigit does not return a fixed number of coefficients, ScalarMult in ecc/p384 is not constant time.

To demonstrate, insert a log.Print(len(L)) in the ScalarMult function and run the tests

$ go test -v -run ScalarMult
=== RUN   TestScalarMult
=== RUN   TestScalarMult/toOdd
=== RUN   TestScalarMult/k=0
=== RUN   TestScalarMult/random_k
2019/08/18 21:39:02 97
2019/08/18 21:39:02 97
2019/08/18 21:39:02 97
...
2019/08/18 21:39:02 97
2019/08/18 21:39:02 97
2019/08/18 21:39:02 96
2019/08/18 21:39:02 97
2019/08/18 21:39:02 96
2019/08/18 21:39:02 97
...

The reduceScalar function attempts to ensure the scalar is always sizeFp bytes, however this is lost in the conversion to big.Int if there are leading zero bytes.

Note that math.SignedDigit uses BitLen to determine the size of the input, which depends on the value of the integer.

circl/math/wnaf.go

Line 22 in a03c5a1

lenN := (uint(n.BitLen()) + (w - 1) - 1) / (w - 1) // ceil(n.BitLen()/(w-1))

sha-3: Move to internal folder of SIKE

I don't want to expose sha-3, but I don't plan upstream changes at the moment.
I think sha-3 implementation should be moved closer to SIKE implementation in dh/sidh/internal or to /vendor

CSIDH

I am using Go, I would like to create a demonstrator for CSIDH, and have imported:

"github.com/cloudflare/circl/dh/csidh"

but I get the error of:

"module github.com/cloudflare/circl@latest found (v1.0.0), but does not contain package github.com/cloudflare/circl/dh/csidh"

Have I included the import correctly? I can get all the other DH methods to work for Circl, but not for CSIDH.

go-fuzz for CIRCL

We should use both:

• https://github.com/dvyukov/go-fuzz for fuzzing interfaces (see how it's used here: https://github.com/mmcloughlin/cryptofuzz)
• https://github.com/guidovranken/cryptofuzz : for checking against alternative implementation (see this https://guidovranken.com/2019/05/14/differential-fuzzing-of-cryptographic-libraries/). This one will be especially useful for experimental implementations (like pq-crypto), which do not have any official test vectors

Obviously it can't be part of the CI as it will disturb development process. os-fuzz is much better place

ecc/p384: ScalarMult fails for k=6

The P384 ScalarMult implementation does not return the correct result for the scalar k = 6. For a reproducer see:

https://gist.github.com/mmcloughlin/823f698cd20cb299327bec705de0f014

One example result:

$ go run k6.go
got    x=0 y=0
expect x=78d0da4eeeb585f21e4de75c543807e8bd7d479a9b332f2cd5e4fbfc219e54d328ee02cce588805bf5ba9217fc52e1c8 y=723df279aaf436b7f088d60078cf26aef0410a51fbc1ec241532ebf321192749dfde358aef76e8874148c321761984d8

I discovered this because I noticed that the ScalarMult function does not implement the same algorithm as described in Selecting Elliptic Curves for Cryptography: An Efficiency and Security Analysis. It is very similar to Algorithm 1, but does not implement Step 19 which uses a complete addition formula for the final add.

The value k=6 has the property that the final add of the algorithm will be (-3)P + (-3)P. Therefore the add function fails, since it does not support doubling.

ecc/p384: implement crypto/ecdsa.combinedMult interface

The crypto/ecdsa package has a private interface for elliptic.Curve implementations that offer accelerated simultaneous multiplication.

// combinedMult implements fast multiplication S1*g + S2*p (g - generator, p - arbitrary point)
type combinedMult interface {
	CombinedMult(bigX, bigY *big.Int, baseScalar, scalar []byte) (x, y *big.Int)
}

https://github.com/golang/go/blob/b36a7a502a590bd9fbf7f73b9678ba58028acfde/src/crypto/ecdsa/ecdsa.go#L48-L51

Suggest renaming the SimultaneousMult method in ecc/p384 to satisfy this interface.

circl/ecc/p384/p384.go

Lines 19 to 22 in a03c5a1

	// SimultaneousMult calculates P=mG+nQ, where G is the generator and
	// Q=(Qx,Qy). The scalars m and n are positive integers in big-endian form.
	// Runs in non-constant time to be used in signature verification.
	SimultaneousMult(Qx, Qy *big.Int, m, n []byte) (Px, Py *big.Int)

goldilocks: review scalar mult of non-prime order points

The package circl/ecc/goldilocks exposes scalar multiplication functions that assume input points are prime-order (like in the case of EdDSA).

This ticket is for ensuring that multiplication routines work as expected with non-prime order points.

Plans for decaf/ed448

At #100 , I have completed the arithmetic for the goldilocks curve.

There are two follow ups:

• The package circl/sign/ed448 ( #102 )
• The package circl/pog/decaf (@claucece )

• pog = prime order group

cc: @alxdavids

ed25519 is not a drop-in replacement of crypto/ed25519

• GetPublic -> Public
• NewKeyFromSeed returns *KeyPair instead of PrivateKey
• (check for others.)

Slow side-channel free AES fallback

In the Go standard library, there are a lot of different optimized implementations for AES. However, the fallback implementation is still a T-tables based implementation, vulnerable to cache timing attacks. There is a long-standing issue in golang/go asking to solve this: golang/go#13795

Although these vulnerable implementations should almost never be selected, it seems that they might sometimes be selected. For example, if the AES intrinsics are missing on Intel, the code seems to select a vulnerable key-expansion.

The solution to this would likely result in an AES implementation that is a lot slower, but I think this is preferable to an implementation that is insecure according to modern crypto engineering standards. In any case, most of the time Go will be able to use an optimized implementation anyway.

Goal

Provide a side-channel resistant replacement for encryptBlock and decryptBlock and expandKeyGo.

Ideas

To replace encryptBlock and decryptBlock, a {16x/24x/32x} bitsliced implementation would be straightforward for AES{128/192/256}. I am thinking, can we maybe do better in the AES128 case? (Parallelizing over multiple blocks is not possible with the current API.)

• Prioritize readability and simplicity over performance.
  • One function should implement all AES variants.
  • Implementation should be single block-based.
• [key schedule] Try a scanning-lookup-table approach for SubWord?

Speed up Dilithium with AVX2

Our implementation of Dilithium (with AVX2) is faster than the C reference implementation, but it is still quite a bit slower than the optimised reference implementation. There are still several functions that can be sped up easily with AVX2.

Remove cSHAKE or reimplement SHA-3

Currently cSHAKE uses SHA-3. Code of SHA-3 was imported from golang (as implementing cSHAKE on top of public interfaces was hard/impossible to do).
cSHAKE is needed only for current version of SIKE. Nevertheless, it shouldn't be needed in the future, which means we don't need to keep copy of SHA-3 in CIRCL.

90s variants of Kyber

optimized verification for eddsa

In https://eprint.iacr.org/2020/454.pdf, Pornin describes a method for accelerating the calculation of EdDSAsignatures using lattice reduction.

It would be a good improvement this verification method for Ed25519 and Ed448 signatures.

consider to clean up merged branches

Switch to internal sha3

Currently we have a copy of x/crypto/sha3 in circl that only contains shake. For Kyber we use x/crypto/sha3 for SHA3. We should update our copy of x/crypto/sha3 to accommodate SHA3.

Increase coverage of CIRCL packages

Test coverage is in average 78%. Some packages need more test coverage.
Good to have unit tests that cover missing areas of code.

Report from codecov.

Files	Tracked lines	Covered	Partial	Missed	Coverage %
abe	2499	1759	215	525	70.39%
blindsign	353	244	24	85	69.12%
dh	3441	2241	24	1176	65.13%
ecc	5930	5692	24	214	95.99%
expander	85	79	3	3	92.94%
group	518	431	10	77	83.20%
hpke	838	574	60	204	68.50%
internal	184	137	3	44	74.46%
kem	8	8	0	0	100.00%
math	1082	1046	7	29	96.67%
oprf	373	301	23	49	80.70%
ot	145	100	19	26	68.97%
pke	1344	1107	22	215	82.37%
pki	120	71	17	32	59.17%
sign	8343	5894	188	2261	70.65%
simd	60	50	4	6	83.33%
tss	460	372	29	59	80.87%
xof	19	19	0	0	100.00%
zk	247	174	27	46	70.45%

Create a unified Group API

cc./ @armfazh

C version would be better.

A C version and a library would be better for a wider usage.

cSIDH: Implement experimental key exchange

Ongoing here:
https://github.com/cloudflare/circl/tree/csidh

Dilithium inconsistency

Is this expected behavior?

dilithium.Mode4.PublicKeyFromBytes(b) // exists
mode4.PublicKeyFromBytes(b) // does not exist

This seems to be caused by the method existing here but not here.

golint issues

golint flags quite a lot of issues, so I thought I'd summarize them here. Note golint checks for the recommendations in the CodeReviewComments wiki page, which have become pretty standard in Go projects. I personally think these are worth fixing, but I wanted to put it up for discussion.

• don't use MixedCaps in package name: This applies to curve4Q and fourQ.
• don't use underscores in Go names: There are lots of examples of this.
• comment on exported function NewSike503 should be of the form "NewSike503 ...": Go comment style recommends that comments for methods/functions/types are full sentences starting with the name of the thing being documented. Again there are quite a lot of examples of this.

All golint issues

dh/curve4Q/curve4Q.go:3:1: don't use MixedCaps in package name; curve4Q should be curve4q
dh/curve4Q/curve4Q_test.go:3:1: don't use MixedCaps in package name; curve4Q should be curve4q
dh/curve4Q/doc.go:8:1: don't use MixedCaps in package name; curve4Q should be curve4q
dh/sidh/sidh.go:12:1: comment on exported type KeyVariant should be of the form "KeyVariant ..." (with optional leading article)
dh/sidh/sidh.go:24:1: comment on exported type PublicKey should be of the form "PublicKey ..." (with optional leading article)
dh/sidh/sidh.go:31:1: comment on exported type PrivateKey should be of the form "PrivateKey ..." (with optional leading article)
dh/sidh/sidh.go:43:2: don't use ALL_CAPS in Go names; use CamelCase
dh/sidh/sidh.go:44:2: don't use ALL_CAPS in Go names; use CamelCase
dh/sidh/sidh.go:51:2: comment on exported const KeyVariant_SIDH_A should be of the form "KeyVariant_SIDH_A ..."
dh/sidh/sidh.go:52:2: don't use underscores in Go names; const KeyVariant_SIDH_A should be KeyVariantSIDHA
dh/sidh/sidh.go:53:2: comment on exported const KeyVariant_SIDH_B should be of the form "KeyVariant_SIDH_B ..."
dh/sidh/sidh.go:54:2: don't use underscores in Go names; const KeyVariant_SIDH_B should be KeyVariantSIDHB
dh/sidh/sidh.go:55:2: comment on exported const KeyVariant_SIKE should be of the form "KeyVariant_SIKE ..."
dh/sidh/sidh.go:56:2: don't use underscores in Go names; const KeyVariant_SIKE should be KeyVariantSIKE
dh/sidh/sidh.go:96:1: comment on exported method PublicKey.Export should be of the form "Export ..."
dh/sidh/sidh.go:138:1: comment on exported method PrivateKey.Export should be of the form "Export ..."
dh/sidh/sidh.go:154:1: comment on exported method PrivateKey.SharedSecretSize should be of the form "SharedSecretSize ..."
dh/sidh/sidh.go:172:1: comment on exported method PrivateKey.Generate should be of the form "Generate ..."
dh/sidh/sidh.go:213:1: comment on exported method PrivateKey.GeneratePublicKey should be of the form "GeneratePublicKey ..."
dh/sidh/sidh.go:239:1: comment on exported method PrivateKey.DeriveSecret should be of the form "DeriveSecret ..."
dh/sidh/sidh_test.go:229:2: don't use underscores in Go names; var a_hex should be aHex
dh/sidh/sidh_test.go:235:2: don't use underscores in Go names; var b_hex should be bHex
dh/sidh/sike.go:1:1: package comment should be of the form "Package sidh ..."
dh/sidh/sike.go:14:1: comment on exported type KEM should be of the form "KEM ..." (with optional leading article)
dh/sidh/sike.go:24:1: comment on exported function NewSike503 should be of the form "NewSike503 ..."
dh/sidh/sike.go:31:1: comment on exported function NewSike751 should be of the form "NewSike751 ..."
dh/sidh/sike.go:38:1: comment on exported method KEM.Allocate should be of the form "Allocate ..."
dh/sidh/sike.go:58:1: comment on exported method KEM.Encapsulate should be of the form "Encapsulate ..."
dh/sidh/sike.go:146:2: don't use underscores in Go names; var c1_len should be c1Len
dh/sidh/sike.go:178:1: comment on exported method KEM.Reset should be of the form "Reset ..."
dh/sidh/sike.go:191:1: comment on exported method KEM.CiphertextSize should be of the form "CiphertextSize ..."
dh/sidh/sike.go:196:1: comment on exported method KEM.SharedSecretSize should be of the form "SharedSecretSize ..."
dh/sidh/sike.go:244:6: don't use underscores in Go names; var c1_len should be c1Len
dh/sidh/sike.go:246:6: don't use underscores in Go names; var pk_len should be pkLen
dh/sidh/sike_test.go:54:2: don't use underscores in Go names; var pk_hex should be pkHex
dh/sidh/sike_test.go:56:2: don't use underscores in Go names; var sk_hex should be skHex
dh/sidh/sike_test.go:64:2: don't use underscores in Go names; var pt_len should be ptLen
dh/sidh/sike_test.go:93:2: don't use underscores in Go names; var pt_len should be ptLen
dh/sidh/sike_test.go:126:6: don't use underscores in Go names; var ss_e should be ssE
dh/sidh/sike_test.go:127:6: don't use underscores in Go names; var ss_d should be ssD
dh/sidh/sike_test.go:151:6: don't use underscores in Go names; var ss_e should be ssE
dh/sidh/sike_test.go:152:6: don't use underscores in Go names; var ss_d should be ssD
dh/sidh/sike_test.go:174:6: don't use underscores in Go names; var ss_e should be ssE
dh/sidh/sike_test.go:175:6: don't use underscores in Go names; var ss_d should be ssD
dh/sidh/sike_test.go:176:6: don't use underscores in Go names; var ss_tmp should be ssTmp
dh/sidh/sike_test.go:235:6: don't use underscores in Go names; var ss_e should be ssE
dh/sidh/sike_test.go:236:6: don't use underscores in Go names; var ss_d1 should be ssD1
dh/sidh/sike_test.go:237:6: don't use underscores in Go names; var ss_d2 should be ssD2
dh/sidh/internal/common/params.go:17:1: comment on exported function Register should be of the form "Register ..."
dh/sidh/internal/common/types.go:4:2: comment on exported const FP_MAX_WORDS should be of the form "FP_MAX_WORDS ..."
dh/sidh/internal/common/types.go:5:2: don't use ALL_CAPS in Go names; use CamelCase
dh/sidh/internal/common/types.go:6:2: comment on exported const MAX_SIDH_PRIVATE_KEY_BSZ should be of the form "MAX_SIDH_PRIVATE_KEY_BSZ ..."
dh/sidh/internal/common/types.go:7:2: don't use ALL_CAPS in Go names; use CamelCase
dh/sidh/internal/common/types.go:8:2: comment on exported const MAX_SIKE_PRIVATE_KEY_BSZ should be of the form "MAX_SIKE_PRIVATE_KEY_BSZ ..."
dh/sidh/internal/common/types.go:9:2: don't use ALL_CAPS in Go names; use CamelCase
dh/sidh/internal/common/types.go:10:2: comment on exported const MAX_MSG_BSZ should be of the form "MAX_MSG_BSZ ..."
dh/sidh/internal/common/types.go:11:2: don't use ALL_CAPS in Go names; use CamelCase
dh/sidh/internal/common/types.go:12:2: comment on exported const MAX_SHARED_SECRET_BSZ should be of the form "MAX_SHARED_SECRET_BSZ ..."
dh/sidh/internal/common/types.go:13:2: don't use ALL_CAPS in Go names; use CamelCase
dh/sidh/internal/common/types.go:14:2: comment on exported const MAX_PUBLIC_KEY_SZ should be of the form "MAX_PUBLIC_KEY_SZ ..."
dh/sidh/internal/common/types.go:15:2: don't use ALL_CAPS in Go names; use CamelCase
dh/sidh/internal/common/types.go:16:2: comment on exported const MAX_CIPHERTEXT_BSZ should be of the form "MAX_CIPHERTEXT_BSZ ..."
dh/sidh/internal/common/types.go:17:2: don't use ALL_CAPS in Go names; use CamelCase
dh/sidh/internal/common/types.go:23:2: don't use ALL_CAPS in Go names; use CamelCase
dh/sidh/internal/common/types.go:24:2: don't use ALL_CAPS in Go names; use CamelCase
dh/sidh/internal/common/types.go:27:1: comment on exported type Fp should be of the form "Fp ..." (with optional leading article)
dh/sidh/internal/common/types.go:34:1: comment on exported type FpX2 should be of the form "FpX2 ..." (with optional leading article)
dh/sidh/internal/common/types.go:37:1: comment on exported type Fp2 should be of the form "Fp2 ..." (with optional leading article)
dh/sidh/internal/common/types.go:43:6: exported type DomainParams should have comment or be unexported
dh/sidh/internal/common/types.go:45:2: don't use underscores in Go names; struct field Affine_P should be AffineP
dh/sidh/internal/common/types.go:45:12: don't use underscores in Go names; struct field Affine_Q should be AffineQ
dh/sidh/internal/common/types.go:45:22: don't use underscores in Go names; struct field Affine_R should be AffineR
dh/sidh/internal/common/types.go:54:6: exported type SidhParams should have comment or be unexported
dh/sidh/internal/common/types.go:55:2: struct field Id should be ID
dh/sidh/internal/common/types.go:77:1: comment on exported type CurveCoefficientsEquiv should be of the form "CurveCoefficientsEquiv ..." (with optional leading article)
dh/sidh/internal/common/types.go:88:1: comment on exported type ProjectivePoint should be of the form "ProjectivePoint ..." (with optional leading article)
dh/sidh/internal/common/types.go:97:1: comment on exported type ProjectiveCurveParameters should be of the form "ProjectiveCurveParameters ..." (with optional leading article)
dh/sidh/internal/common/utils.go:3:1: comment on exported function Cpick should be of the form "Cpick ..."
dh/sidh/internal/common/utils.go:14:1: comment on exported function BytesToFp2 should be of the form "BytesToFp2 ..."
dh/sidh/internal/common/utils.go:30:1: comment on exported function Fp2ToBytes should be of the form "Fp2ToBytes ..."
dh/sidh/internal/p503/params.go:11:2: comment on exported const FP_WORDS should be of the form "FP_WORDS ..."
dh/sidh/internal/p503/params.go:12:2: don't use ALL_CAPS in Go names; use CamelCase
dh/sidh/internal/p503/params.go:28:1: comment on exported var P503 should be of the form "P503 ..."
dh/sidh/internal/p503/params.go:34:1: comment on exported var P503x2 should be of the form "P503x2 ..."
dh/sidh/internal/p503/params.go:40:1: comment on exported var P503p1 should be of the form "P503p1 ..."
dh/sidh/internal/p503/params.go:46:1: comment on exported var P503R2 should be of the form "P503R2 ..."
dh/sidh/internal/p503/params.go:52:1: comment on exported var P503p1s8 should be of the form "P503p1s8 ..."
dh/sidh/internal/p503/params.go:58:1: comment on exported var P503p1Zeros should be of the form "P503p1Zeros ..."
dh/sidh/internal/p503/params_test.go:19:2: don't use underscores in Go names; var curve_A should be curveA
dh/sidh/internal/p503/params_test.go:24:2: don't use underscores in Go names; var curve_C should be curveC
dh/sidh/internal/p503/params_test.go:28:2: don't use underscores in Go names; var affine_xP should be affineXP
dh/sidh/internal/p503/params_test.go:32:2: don't use underscores in Go names; var affine_xP2 should be affineXP2
dh/sidh/internal/p503/params_test.go:36:2: don't use underscores in Go names; var affine_xP4 should be affineXP4
dh/sidh/internal/p503/params_test.go:40:2: don't use underscores in Go names; var affine_xP9 should be affineXP9
dh/sidh/internal/p751/params.go:11:2: comment on exported const FP_WORDS should be of the form "FP_WORDS ..."
dh/sidh/internal/p751/params.go:12:2: don't use ALL_CAPS in Go names; use CamelCase
dh/sidh/internal/p751/params.go:26:1: comment on exported var P751p1Zeros should be of the form "P751p1Zeros ..."
dh/sidh/internal/p751/params.go:29:1: comment on exported var P751 should be of the form "P751 ..."
dh/sidh/internal/p751/params.go:36:1: comment on exported var P751x2 should be of the form "P751x2 ..."
dh/sidh/internal/p751/params.go:43:1: comment on exported var P751p1 should be of the form "P751p1 ..."
dh/sidh/internal/p751/params.go:50:1: comment on exported var P751R2 should be of the form "P751R2 ..."
dh/sidh/internal/p751/params_test.go:16:2: don't use underscores in Go names; var curve_A should be curveA
dh/sidh/internal/p751/params_test.go:21:2: don't use underscores in Go names; var curve_C should be curveC
dh/sidh/internal/p751/params_test.go:26:2: don't use underscores in Go names; var affine_xP should be affineXP
dh/sidh/internal/p751/params_test.go:31:2: don't use underscores in Go names; var affine_xP2 should be affineXP2
dh/sidh/internal/p751/params_test.go:36:2: don't use underscores in Go names; var affine_xP4 should be affineXP4
dh/sidh/internal/p751/params_test.go:41:2: don't use underscores in Go names; var affine_xP9 should be affineXP9
ecc/fourQ/constants.go:3:1: don't use MixedCaps in package name; fourQ should be fourq
ecc/fourQ/curve.go:3:1: don't use MixedCaps in package name; fourQ should be fourq
ecc/fourQ/doc.go:1:1: package comment should be of the form "Package fourQ ..."
ecc/fourQ/doc.go:13:1: don't use MixedCaps in package name; fourQ should be fourq
ecc/fourQ/fp.go:3:1: don't use MixedCaps in package name; fourQ should be fourq
ecc/fourQ/fp_amd64.go:3:1: don't use MixedCaps in package name; fourQ should be fourq
ecc/fourQ/fp_amd64_test.go:3:1: don't use MixedCaps in package name; fourQ should be fourq
ecc/fourQ/fq.go:3:1: don't use MixedCaps in package name; fourQ should be fourq
ecc/fourQ/fq_amd64.go:3:1: don't use MixedCaps in package name; fourQ should be fourq
ecc/fourQ/fq_test.go:3:1: don't use MixedCaps in package name; fourQ should be fourq
ecc/fourQ/point.go:3:1: don't use MixedCaps in package name; fourQ should be fourq
ecc/fourQ/point.go:240:1: exported method Point.Marshal should have comment or be unexported
ecc/fourQ/point.go:248:1: exported method Point.Unmarshal should have comment or be unexported
ecc/fourQ/point_amd64.go:3:1: don't use MixedCaps in package name; fourQ should be fourq
ecc/fourQ/point_amd64.go:8:2: don't use underscores in Go names; const _x_ should be _x
ecc/fourQ/point_amd64.go:9:2: don't use underscores in Go names; const _y_ should be _y
ecc/fourQ/point_amd64.go:10:2: don't use underscores in Go names; const _z_ should be _z
ecc/fourQ/point_amd64.go:11:2: don't use underscores in Go names; const _ta_ should be _ta
ecc/fourQ/point_amd64.go:12:2: don't use underscores in Go names; const _tb_ should be _tb
ecc/fourQ/point_amd64.go:13:2: don't use underscores in Go names; const _addYX_R2_ should be _addYXR2
ecc/fourQ/point_amd64.go:14:2: don't use underscores in Go names; const _subYX_R2_ should be _subYXR2
ecc/fourQ/point_amd64.go:15:2: don't use underscores in Go names; const _z2_R2_ should be _z2R2
ecc/fourQ/point_amd64.go:16:2: don't use underscores in Go names; const _dt2_R2_ should be _dt2R2
ecc/fourQ/point_amd64.go:17:2: don't use underscores in Go names; const _addYX_R3_ should be _addYXR3
ecc/fourQ/point_amd64.go:18:2: don't use underscores in Go names; const _subYX_R3_ should be _subYXR3
ecc/fourQ/point_amd64.go:19:2: don't use underscores in Go names; const _dt2_R3_ should be _dt2R3
ecc/fourQ/point_test.go:3:1: don't use MixedCaps in package name; fourQ should be fourq
ecc/fourQ/tableBase.go:3:1: don't use MixedCaps in package name; fourQ should be fourq
ecc/fourQ/tableBase.go:7:2: don't use underscores in Go names; const fx_t should be fxT
ecc/fourQ/tableBase.go:9:2: don't use underscores in Go names; const fx_v should be fxV
ecc/fourQ/tableBase.go:11:2: don't use underscores in Go names; const fx_w should be fxW
ecc/fourQ/tableBase.go:13:2: don't use underscores in Go names; const fx_2w1 should be fx2w1
ecdh/ecdh_test.go:16:2: struct field TcId should be TcID
ecdh/ecdh_test.go:186:4: struct field TcId should be TcID
hash/sha3/sha3.go:197:1: comment on exported function NewLegacyKeccak256 should be of the form "NewLegacyKeccak256 ..."
hash/sha3/shake.go:22:1: comment on exported type CShake should be of the form "CShake ..." (with optional leading article)
internal/test/test.go:35:1: comment on exported function CheckNoErr should be of the form "CheckNoErr ..."
internal/test/test.go:38:1: comment on exported function CheckIsErr should be of the form "CheckIsErr ..."
internal/test/test.go:41:1: comment on exported function CheckPanic should be of the form "CheckPanic ..."

Problem with Fourq?

I can get most of the Circl code to work, but Fourq gives an exception. With just a simple example, it crashes when using P.ScalarBaseMult():

package main

import (
"crypto/rand"
"fmt"
"io"

"github.com/cloudflare/circl/ecc/fourq"

)

// Size is the size in bytes of keys.
const Size = 32

// Key represents a public or private key of FourQ.
type Key [Size]byte

// KeyGen calculates a public key k from a secret key.
func KeyGen(public, secret *Key) {

var P fourq.Point

P.ScalarBaseMult((*[32]byte)(secret))

P.Marshal((*[Size]byte)(public))

}

// Shared calculates a shared key k from Alice's secret and Bob's public key.
// Returns true on success.
func Shared(shared, secret, public *Key) bool {
var P, Q fourq.Point

ok := P.Unmarshal((*[Size]byte)(public))

Q.ScalarMult((*[Size]byte)(secret), &P)
Q.Marshal((*[Size]byte)(shared))
ok = ok && Q.IsOnCurve()
return ok

}
func main() {

var AliceSecret, BobSecret,
	AlicePublic, BobPublic,
	AliceShared, BobShared Key

// Generating Alice's secret and public keys
_, _ = io.ReadFull(rand.Reader, AliceSecret[:32])

fmt.Println("Secret ", AliceSecret)
KeyGen(&AlicePublic, &AliceSecret)

fmt.Println("Key %x", AliceSecret)
// Generating Bob's secret and public keys
_, _ = io.ReadFull(rand.Reader, BobSecret[:])
KeyGen(&BobPublic, &BobSecret)

// Deriving Alice's shared key
Shared(&AliceShared, &AliceSecret, &BobPublic)

// Deriving Bob's shared key
Shared(&BobShared, &BobSecret, &AlicePublic)

fmt.Println(AliceShared == BobShared)

}

C:> fourq.exe
Secret [248 49 197 200 23 204 9 133 172 96 220 181 247 45 113 172 201 21 31 235
30 186 124 42 183 115 114 250 127 187 194 224]
Exception 0xc000001d 0x0 0x0 0x4b2758
PC=0x4b2758

github.com/cloudflare/circl/ecc/fourq.doubleAsm(0xc00007bd10)
d:/go/src/src/github.com/cloudflare/circl/ecc/fourq/point_amd64.s:8 +0x8
8
github.com/cloudflare/circl/ecc/fourq.(*pointR1).double(...)
d:/go/src/src/github.com/cloudflare/circl/ecc/fourq/point_amd64.go:24
github.com/cloudflare/circl/ecc/fourq.(*pointR1).ScalarBaseMult(0xc00007bd10, 0x
c00004e140)
d:/go/src/src/github.com/cloudflare/circl/ecc/fourq/point.go:190 +0x284
github.com/cloudflare/circl/ecc/fourq.(*Point).ScalarBaseMult(0xc00007bdd0, 0xc0
0004e140)
d:/go/src/src/github.com/cloudflare/circl/ecc/fourq/curve.go:82 +0x70
main.KeyGen(0xc00007bec8, 0xc00004e140)
C:/Python27/godir/fourq.go:22 +0x53
main.main()
C:/Python27/godir/fourq.go:49 +0x1d0
rax 0x0
rbx 0x0
rcx 0x0
rdi 0xc00007bd10
rsi 0x0
rbp 0xc00007bcf0
rsp 0xc00007bb28
r8 0x0
r9 0x0
r10 0x0
r11 0x0
r12 0x7c2526
r13 0x4db6e0
r14 0x0
r15 0x0
rip 0x4b2758
rflags 0x10246
cs 0x33
fs 0x53
gs 0x2b

Shake is crashing when using unsafe pointer casting

In CI, there is triggered an crash error inside shake package.
Details:

• https://app.circleci.com/jobs/github/cloudflare/circl/1647
• https://app.circleci.com/jobs/github/cloudflare/circl/1648

Bas, could you please take a look on this.

Consider applying Go TargetSpecific policy

Filippo outlined some guidelines for target specific packages and intends to apply them in the Go standard library.

https://github.com/golang/go/wiki/TargetSpecific
golang/go#31470

This could help with differential testing and fuzzing #4, so it may be good to apply it in circl too.

Code coverage output

Currently output from code coverage can be found here:
https://105-147963112-gh.circle-artifacts.com/0/home/circleci/project/build/coverage/coverage.html#file0

Would be better if we use github interface to display it (maybe by using CodeCov plugin)

Make ed25519 and ed448 usable for Golang interfaces

Hi!

Thanks so much for all the work on this!

So, the implementation for ed25519 and ed448 expose a certain API that is quite similar to the way golang handles it in its libraries (ecdsa, rsa, and ed25519). However, when I tried to use it for the crypto signer interface, it panics due to:

panic: interface conversion: ed25519.PrivateKey is not crypto.Signer: missing method Public [recovered]
	panic: interface conversion: ed25519.PrivateKey is not crypto.Signer: missing method Public

I was wondering if we could create a method func (priv *PrivateKey) Public() crypto.PublicKey (in similar fashion as https://golang.org/pkg/crypto/ecdsa/#PrivateKey.Public and https://golang.org/pkg/crypto/ed25519/#PrivateKey.Public) so the APIs can be used for other interfaces as the crypto signer...

Include edge cases in the representation such as 2^w, 2^w-1.

I think we also should test that the length is what we think it is. We might also want to include edge cases in the representation such as 2^w, 2^w-1, etc.

Originally posted by @wbl in #67

Update Dilithium to Round 3

Specification is expected to be released within two weeks.

Test iterations vary based on the -short flag

Not an issue that needs to be addressed right now, but it can be quite nice for things like this is to allow the iterations to vary based on the -short flag. For example:

func NumTrials() {
    if testing.Short() {
        return 16
    }
    return 1 << 8 // or more
}

If you want to get even more fancy, something I've done before is to also define custom -long and -stress flags. So you can do:

// Custom test command line flags.
var (
	long   = flag.Bool("long", false, "enable long running tests")
	stress = flag.Bool("stress", false, "enable stress tests (implies -long)")
)

// timeallowed returns how long a single test is allowed to take.
func timeallowed() time.Duration {
	switch {
	case testing.Short():
		return time.Second / 10
	case *long:
		return 30 * time.Second
	case *stress:
		return 2 * time.Minute
	default:
		return time.Second
	}
}

// Repeat the given trial function. The duration is controlled by custom
// command-line flags. The trial function returns whether it wants to continue
// testing.
//
//	-short		run for less time than usual
//	-long		allow more time
//	-stress		run for an extremely long time
func Repeat(t *testing.T, trial func(t *testing.T) bool) {
	start := time.Now()
	d := timeallowed()
	n := 1
	for time.Since(start) < d && trial(t) {
		n++
	}
	t.Logf("%d trials in %s", n, time.Since(start))
}

I usually put something like this in an internal/test package. Then you wrap your test in a test.Repeat(...) call and it will run until the time limit.

Originally posted by @mmcloughlin in #102

Miscellaneous issues raised during review of Dilithium PR

• Does it negatively impact performance if we implement ShakeHash on AesStream to simplify the sampling code. (Due to esacape-to-heap allocations.)
• How far to go to check keys for consistency
• Document which files gen.go generates.
• Reconsider code layout.
• Use intenal/test when appropriate

Align SIKE with Round 2

Goal:

• implement new starting curve
• implement P434

I've already done it here, so it's a matter of porting
https://github.com/post-quantum-cryptography/go-sike

Consider running code generators in CI

One problem that can arise with code generation is that people will hand edit files after they've been generated. One method to prevent this is to run go generate ./... in CI and fail if the git repo is dirty. Something like the following:

https://github.com/mmcloughlin/avo/blob/83fbad1a6b3cba8ac7711170e57953fd12cdc40a/script/lint#L3-L5

Should be simple to implement: I think it would just be necessary to remove the date comments and make sure the files are gofmted.

circl/dh/sidh/internal/p503/fp2.go

Lines 1 to 2 in 1d8cced

	// Code generated by go generate; DO NOT EDIT.
	// This file was generated by robots at 30 May 19 14:45 +0100.

Just an idea. I can put this in place if you agree.

CIRCL testing and benchmarking

I am trying to run the Makefile, but I get this insisting error :

$ koukabi_sara@kaoukabi-sara-UX410UAR:~/go/src/github.com/cloudflare/circl$ sudo make
[sudo] password for kaoukabi_sara: 
/bin/golangci-lint run --config /home/kaoukabi_sara/go/src/github.com/cloudflare/circl/.etc/golangci.yml ./...
WARN Failed to discover go env: failed to run 'go env': exec: "go": executable file not found in $PATH 
ERRO Running error: context loading failed: failed to load program with go/packages: 'go list' driver requires 'go', but executable file not found in $PATH 
Makefile:27: recipe for target 'lint' failed
make: *** [lint] Error 3

while the PATH is well set :

$ kaoukabi_sara@kaoukabi-sara-UX410UAR:~/go/src/github.com/cloudflare/circl$ echo $PATH
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin:/usr/local/go/bin:/home/kaoukabi_sara/go/bin:/usr/local/go/bin:/home/kaoukabi_sara/go/bin

my go version and env are :

go version go1.12.9 linux/amd64
GOARCH="amd64"
GOBIN=""
GOCACHE="/home/kaoukabi_sara/.cache/go-build"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOOS="linux"
GOPATH="/home/kaoukabi_sara/go"
GOPROXY=""
GORACE=""
GOROOT="/usr/local/go"                                                                                                                                                         
GOTMPDIR=""                                                                                                                                                                    
GOTOOLDIR="/usr/local/go/pkg/tool/linux_amd64"                                                                                                                                 
GCCGO="gccgo"                                                                                                                                                                  
CC="gcc"                                                                                                                                                                       
CXX="g++"                                                                                                                                                                      
CGO_ENABLED="1"                                                                                                                                                                
GOMOD=""                                                                                                                                                                       
CGO_CFLAGS="-g -O2"                                                                                                                                                            
CGO_CPPFLAGS=""                                                                                                                                                                
CGO_CXXFLAGS="-g -O2"                                                                                                                                                          
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build876018540=/tmp/go-build -gno-record-gcc-switches"

Any suggestion?

Consider fetching specific go<arch><version>

This build (https://circleci.com/gh/cloudflare/circl/100) is failing.
Adapt the CI config file to match version and architecture.

It might be worth to fetch from https://hub.docker.com/_/golang

Document and tweak generic signatures API

• Documentation and examples are still lacking
• Deal with multiple very similar modes of the same scheme. I.e. ed{25519,448}{ph,ctx,}

Update signing API for ed25519

The API of ed25519 accepts a public key as input, this is a bad design.

Discussions:
https://moderncrypto.org/mail-archive/curves/2020/001013.html
https://mailarchive.ietf.org/arch/msg/cfrg/pv7X8hrBtMGfmlCMHsLhJDXPHso

Prevent avo ending up in go.mod

As suggested by @mmcloughlin we can move sign/dilithium/internal/ntt_amd64_src.go to sign/dilithium/internal/asm/ntt_amd64_src.go, sign/dilithium/internal/asm/go.mod and let it generate into its parent folder. This will prevent avo from ending up in the top-level go.mod file. However, at the moment avo guesses the name of the package to use in its stubs file by the name of the folder, so it will create a conflicting package asm directive. To fix this we would need to use asm/internal instead of asm or wait for mmcloughlin/avo#147 to be resolved.

(As a workaround we go mod tidy after a go generate.)