From 01484a039011a46e27629751230d69a542d0b0c7 Mon Sep 17 00:00:00 2001 From: Antonio Cheong Date: Fri, 10 Nov 2023 00:50:38 +0000 Subject: [PATCH] Migrate to g-utils org --- .golangci.yml | 2 +- README.md | 89 +++++++++++++++++++++++++++++---------------------- go.mod | 2 +- 3 files changed, 53 insertions(+), 40 deletions(-) diff --git a/.golangci.yml b/.golangci.yml index 8d03c82..530e71f 100644 --- a/.golangci.yml +++ b/.golangci.yml @@ -1,6 +1,6 @@ linters-settings: goimports: - local-prefixes: github.com/acheong08/crystals-go + local-prefixes: github.com/g-utils/crystals-go linters: disable-all: true diff --git a/README.md b/README.md index 85782f6..629a8ec 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,14 @@ # 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. +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: + ```shell -go get github.com/acheong08/crystals-go +go get github.com/g-utils/crystals-go ``` The API of Kyber and Dilihtium is very similar, and can be divided in two steps: @@ -15,28 +16,34 @@ 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: ```go -k := NewKyber512() //Creates a Kyber instance with light security level +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. +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: + ```go 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: + ```go k := NewKyber768() c, ss := k.Encaps(pk, coins) ``` + The ciphertext is transmitted to Alice for her to recover the value of ss with: + ```go ss := k.Decaps(sk, c) //Matches the value held by Bob ``` @@ -48,29 +55,34 @@ For Dilithium, the DSA, the main methods are KeyGen, Sign, and Verify, which ver 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: + ```go d := Dilithium2() //Creates a Dilithium instance with recommended security level pk, sk := d.KeyGen() ``` + She can then sign a message of her choice using: + ```go 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: + ```go 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. +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. +They can also be _nil_, in which case the randomness will be generated during using Go's official crypto/rand library. ### Helpers @@ -83,58 +95,59 @@ sizePk := k.SizePk() sizeSk := k.SizeSk() sizeC := k.SizeC() ``` -for Kyber, or + +for Kyber, or + ```go sizePk := k.SizePk() sizeSk := k.SizeSk() sizeSig := d.SizeSig() ``` + for Dilithium. Finally, we noticed that some packages (for example: [binary](https://golang.org/pkg/encoding/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](https://github.com/acheong08/crystals-go/blob/main/crystals-dilithium/params.go#L19) file for an example. +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](https://github.com/g-utils/crystals-go/blob/main/crystals-dilithium/params.go#L19) 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. +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. +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 | [:link:][dan19] | -| ✔️| D | Timing of re-encryption check | [:link:][guo20] | -| | | CM | | -| ✖️| KG | Cache access monitoring | [:link:][fac18] | -| ✖️| S | Cache access monitoring | [:link:][fac18] | -| ✔️| D| Cache access monitoring | [:link:][rav20] | -| | | FA | | -| ✔️| KG | Skip of secret addition | [:link:][bbk19] | -| ✔️| S | Skip of mask addition | [:link:][rav19] | -| ✖️| D | Skip of decryption check | [:link:][pp21] | -| ✖️| D | Skip of +Q/2 instruction | [:link:][pp21] | -| ✖️| KG | Zero of secret | [:link:][bbk19] | -| ✖️| KG | Zero of noise | [:link:][val17] | -| ✖️| KG | Zero of A | [:link:][val17] | -| ✖️| S | Zero of randomness | [:link:][bbk19] | -| ✖️| KG | Zero of noise | [:link:][val17] | -| ✔️| KG | Zero of nonce | [:link:][rav18] | -| ✔️| E | Zero of nonce | [:link:][rav18] | -| ✔️| S | Zero of mask | [:link:][esp18] | -| ✔️| S | Loop-abort of mask addition | [:link:][bbk19] | -| ✔️| KG | Loop abort of noise addition | [:link:][esp18] | -| ✔️| S | Err. in hash polynomial | [:link:][bp18] | -| ✔️| S | Err. in expand function | [:link:][bp18] | - - +| | Alg | Attack | Paper | +| --- | --- | ----------------------------- | :-------------- | +| | | TA | | +| ✔️ | D | Timing of decryption | [:link:][dan19] | +| ✔️ | D | Timing of re-encryption check | [:link:][guo20] | +| | | CM | | +| ✖️ | KG | Cache access monitoring | [:link:][fac18] | +| ✖️ | S | Cache access monitoring | [:link:][fac18] | +| ✔️ | D | Cache access monitoring | [:link:][rav20] | +| | | FA | | +| ✔️ | KG | Skip of secret addition | [:link:][bbk19] | +| ✔️ | S | Skip of mask addition | [:link:][rav19] | +| ✖️ | D | Skip of decryption check | [:link:][pp21] | +| ✖️ | D | Skip of +Q/2 instruction | [:link:][pp21] | +| ✖️ | KG | Zero of secret | [:link:][bbk19] | +| ✖️ | KG | Zero of noise | [:link:][val17] | +| ✖️ | KG | Zero of A | [:link:][val17] | +| ✖️ | S | Zero of randomness | [:link:][bbk19] | +| ✖️ | KG | Zero of noise | [:link:][val17] | +| ✔️ | KG | Zero of nonce | [:link:][rav18] | +| ✔️ | E | Zero of nonce | [:link:][rav18] | +| ✔️ | S | Zero of mask | [:link:][esp18] | +| ✔️ | S | Loop-abort of mask addition | [:link:][bbk19] | +| ✔️ | KG | Loop abort of noise addition | [:link:][esp18] | +| ✔️ | S | Err. in hash polynomial | [:link:][bp18] | +| ✔️ | S | Err. in expand function | [:link:][bp18] | Attacks marked with a gray cross are the ones left, a green checkmark implies that a defense is implemented. diff --git a/go.mod b/go.mod index 5c35ef6..3f42749 100644 --- a/go.mod +++ b/go.mod @@ -1,4 +1,4 @@ -module github.com/acheong08/crystals-go +module github.com/g-utils/crystals-go go 1.19