Go Post Quantum Safe Lib

This library offers a fast, secure, and easy to use implementation of the post-quantum candidates of the CRYSTALS suite. It contains Kyber, a key-encapsulation mechanism whose goal is to securely transmit symmetric key material over an insecure channel, and Dilithium, a digital signature algorithm that produces a signature that can be verified against a key, and can be used towards authentication or integrity.

API

To begin with, the crystal-go module can be installed via:

go get -u github.com/kudelskisecurity/crystals-go

The API of Kyber and Dilihtium is very similar, and can be divided in two steps:

The user first has to define which level of security they want to work with by creating an instance of Kyber or Dilithium among (in increasing level of security) Kyber512, Kyber768, Kyber1024 and Dilithium2, Dilithium3, Dilithium5. For example:

k := NewKyber512() //Creates a Kyber instance with light security level 
d := Dilithium3() //Creates a Dilithium instance with recommended/medium security level

The newly created instance defines all parameters used internally. In a second step, the user can now invoke our generic methods on an instance of Kyber or Dilithium.

Kyber

The core functions of Kyber, a KEM, are a tuple KeyGen, Encaps, and Decaps. The key generation function returns a public key that can be openly disclosed, and a secret key that should remain private. The encapsulation function is used to generate and encrypt a shared secret given a public key. Secret that can be recovered using the associated secret key. No one except the secret key holder can recover the value of the shared secret.

Translated to code, a KEM protocol between Alice and Bob using our API looks like this:

Alice and Bob agreed on using the recommended security level. Alice can now generate a public and private key pair by calling:

k := NewKyber768()
pk, sk := k.KeyGen(seed)

Once the keys are generated, Alice can send her public key to Bob, who encapsulates a shared secret using:

k := NewKyber768()
c, ss := k.Encaps(pk, coins)

The ciphertext is transmitted to Alice for her to recover the value of ss with:

ss := k.Decaps(sk, c) //Matches the value held by Bob

Dilithium

For Dilithium, the DSA, the main methods are KeyGen, Sign, and Verify, which very intuitively, correspond to the verification key (public) and signing key (secret) generation, the signature algorithm, and the verification algorithm. The signature, given a message and a signing key, produces a signature that is verifiable against the associated public verification key. Dilithium signatures are said to be unforgeable, meaning that it is extremely hard to create a valid signature without actually holding the signing key. In that case, Dilithium can be used as an authentication mechanism, as a valid signature is the proof that the signer is the secret key holder. If the message is tampered, the signature will not verify anymore, so Dilithium can also be used to enforce message integrity.

Similarly, we can translate the Dilithium protocol to code. W.L.O.G, we choose Alice to be the signer, and Bob the verifier, and assume that they agreed on using the light security level.

Alice starts by generating a key pair:

d := Dilithium2() //Creates a Dilithium instance with recommended security level
pk, sk := d.KeyGen()

She can then sign a message of her choice using:

msg := []byte("This is a message.")
sig := d.Sign(sk, msg)

Then transmit her public key, message, and signature to Bob for him to verify it with:

d := Dilithium2()
verified := d.Verify(pk, sig, msg) //verified is true for honest executions

A feature of Dilithium is to be available both in randomized or deterministic mode. When creating a Dilithium instance, a boolean is given as parameter to indicate which one to use. By default, the boolean is set to true, setting Dilithium to the randomized mode, but passing false as parameter will choose the deterministic mode. For example, d := NewDilithium3(false) will create a Dilithium instance with parameters set to the security level 3, and a deterministic signature. The signing and verification procedure is the same for both and follows the aforementioned flow.

Random inputs

This leads us to the final feature of the API regarding randomization. Both Kyber and Dilithium use random numbers. The concerned methods accept as argument seed or coins of 32 bytes to be used as random material, which allows for reproducibility for example, or is useful if the user does not trust the environment to generate good randomness and wants to use randomness from their own source. They can also be nil, in which case the randomness will be generated during using Go's official crypto/rand library.

Helpers

The output sizes of Kyber and Dilithium (keys, signature,...) vary based on the security level. We provide for both schemes getter functions that return the size of the keys and ciphertext or signature structures based on the security level of the instance used. They can be called as follows:

sizePk := k.SizePk()
sizeSk := k.SizeSk()
sizeC := k.SizeC()

for Kyber, or

sizePk := k.SizePk()
sizeSk := k.SizeSk()
sizeSig := d.SizeSig()

for Dilithium.

Finally, we noticed that some packages (for example: binary are only compatible with constant-size objects. Our API outputs slices, which are variable-sized arrays, and function calls in Go return non-constant values, breaking the compatibility with such packages. For applications where resources need to be allocated using constant-size structures, we hardcode the size of our scheme's outputs for each security level, and expose them as constants as part of the Kyber/Dilithium packages. Have a look at the param.go file for an example.

Errors

In order to keep the API pretty simple, any error will result in a nil output (false is the case or Verify). For now the error is printed, but we are working on Log Levels.

Security

Our library stands out because of its security properties. Among the vulnerabilities reported on the original implementation, we integrate countermeasures for most of them, providing a library that is both theoretically and practically secure. We predict that new attacks will be published as the candidates are refined, and expect changes in the code to occur as the security of our library is treated as a continuous process.

We recall that side-channel attacks are high-risk threats and encourage users to prefer libraries with strong implementation security, such as our library, over implementations that lack these guarantees.

Dashboard SCA (work in progress)

	Alg	Attack	Paper
		TA
✔️	D	Timing of decryption	🔗
✔️	D	Timing of re-encryption check	🔗
		CM
✖️	KG	Cache access monitoring	🔗
✖️	S	Cache access monitoring	🔗
✔️	D	Cache access monitoring	🔗
		FA
✔️	KG	Skip of secret addition	🔗
✔️	S	Skip of mask addition	🔗
✖️	D	Skip of decryption check	🔗
✖️	D	Skip of +Q/2 instruction	🔗
✖️	KG	Zero of secret	🔗
✖️	KG	Zero of noise	🔗
✖️	KG	Zero of A	🔗
✖️	S	Zero of randomness	🔗
✖️	KG	Zero of noise	🔗
✔️	KG	Zero of nonce	🔗
✔️	E	Zero of nonce	🔗
✔️	S	Zero of mask	🔗
✔️	S	Loop-abort of mask addition	🔗
✔️	KG	Loop abort of noise addition	🔗
✔️	S	Err. in hash polynomial	🔗
✔️	S	Err. in expand function	🔗

Attacks marked with a gray cross are the ones left, a green checkmark implies that a defense is implemented.

karalef / libcrystals