Change NID_KYBER512 to NID_KYBER512_R3 (#758)

Kyber specification might change before the final standardization. So we label the current one with an "R3" suffix to denote that it corresponds to the NIST PQC project Round-3 specification.
aws · Jan 18, 2023 · ee63cde · ee63cde
1 parent 80f5207
commit ee63cde
Show file tree

Hide file tree

Showing 9 changed files with 39 additions and 31 deletions.
diff --git a/crypto/evp_extra/evp_extra_test.cc b/crypto/evp_extra/evp_extra_test.cc
@@ -1714,7 +1714,7 @@ struct KnownKEM {
 };
 
 static const struct KnownKEM kKEMs[] = {
-  {"Kyber512", NID_KYBER512, 800, 1632, 768, 32, "pq_kem_kat_tests_kyber512.txt"},
+  {"Kyber512r3", NID_KYBER512_R3, 800, 1632, 768, 32, "pq_kem_kat_tests_kyber512.txt"},
 };
 
 class PerKEMTest : public testing::TestWithParam<KnownKEM> {};

diff --git a/crypto/kem/README.md b/crypto/kem/README.md
@@ -37,7 +37,7 @@ The `ctx` variable above is a pointer to a “context” object of type `EVP_PKE
 
 ```
 1. EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_KEM, NULL);
-   EVP_PKEY_CTX_kem_set_params(ctx, NID_KYBER512);
+   EVP_PKEY_CTX_kem_set_params(ctx, NID_KYBER512_R3);
 ```
 
 This creates a fresh context of type `EVP_PKEY_KEM` and sets the specific KEM parameters (Kyber512 in this example). The context is now ready for key generation (`EVP_PKEY_keygen`). However, the context created in this way doesn’t have an associated key (`EVP_PKEY`), so obviously, we can’t encapsulate/decapsulate with it. Therefore, this is useful for key generation only, i.e. before we have a key.
@@ -145,7 +145,7 @@ int get_raw_public_key(/* IN  */ EVP_PKEY *key,
 //
 //   1. Generate the key (Kyber512 key in our example),
 EVP_PKEY *key = NULL;
-if (generate_key_pair(&key, NID_KYBER512) != SUCCESS) {
+if (generate_key_pair(&key, NID_KYBER512_R3) != SUCCESS) {
   return FAIL;
 }
 
@@ -222,7 +222,7 @@ Note: you can use the generated |key| directly
                                                                                   uint8_t *ct = NULL, *ss = NULL; // ciphertext and shared secret,
                                                                                   size_t ct_len, ss_len;          // and their lengths.
 
-                                                                                  int ret = encapsulate(NID_KYBER512, pub_key, pub_key_len,
+                                                                                  int ret = encapsulate(NID_KYBER512_R3, pub_key, pub_key_len,
                                                                                                         &ct, &ct_len, &ss, &ss_len);
 
                                                                                   // On |ret| being SUCCESS, |ss| is the generated shared secret you can use,

diff --git a/crypto/kem/internal.h b/crypto/kem/internal.h
@@ -25,7 +25,7 @@ typedef struct {
                 const uint8_t *secret_key);
 } KEM_METHOD;
 
-extern const KEM_METHOD kem_kyber512_method;
+extern const KEM_METHOD kem_kyber512_r3_method;
 // extern const KEM_METHOD *KEM_kyber768_method;
 
 // KEM structure and helper functions.

diff --git a/crypto/kem/kem.c b/crypto/kem/kem.c
@@ -12,26 +12,26 @@
 
 // The KEM parameters listed below are taken from corresponding specifications.
 //
-// Kyber: https://pq-crystals.org/kyber/data/kyber-specification-round3-20210804.pdf
-// TODO(awslc): replace the specification reference with the actual NIST standard
-//              reference once it's published.
+// Kyber: - https://pq-crystals.org/kyber/data/kyber-specification-round3-20210804.pdf
+//        - Kyber is not standardized yet, so we use the latest specification
+//          from Round 3 of NIST PQC project.
 
 #define AWSLC_NUM_BUILT_IN_KEMS 1
 
 // TODO(awslc): placeholder OID, replace with the real one when available.
-static const uint8_t kOIDKyber512[] = {0xff, 0xff, 0xff, 0xff};
+static const uint8_t kOIDKyber512r3[] = {0xff, 0xff, 0xff, 0xff};
 
 static const KEM built_in_kems[AWSLC_NUM_BUILT_IN_KEMS] = {
   {
-    NID_KYBER512,         // kem.nid
-    kOIDKyber512,         // kem.oid
-    sizeof(kOIDKyber512), // kem.oid_len
-    "Kyber512",           // kem.comment
-    800,                  // kem.public_key_len
-    1632,                 // kem.secret_key_len
-    768,                  // kem.ciphertext_len
-    32,                   // kem.shared_secret_len
-    &kem_kyber512_method, // kem.method
+    NID_KYBER512_R3,         // kem.nid
+    kOIDKyber512r3,          // kem.oid
+    sizeof(kOIDKyber512r3),  // kem.oid_len
+    "Kyber512 Round-3",      // kem.comment
+    800,                     // kem.public_key_len
+    1632,                    // kem.secret_key_len
+    768,                     // kem.ciphertext_len
+    32,                      // kem.shared_secret_len
+    &kem_kyber512_r3_method, // kem.method
   },
 
   // Example how adding new KEM looks like:

diff --git a/crypto/kem/kyber_methods_placeholder.c b/crypto/kem/kyber_methods_placeholder.c
@@ -13,27 +13,27 @@
 
 #include "../kyber/kem_kyber.h"
 
-static int kyber512_keygen_placeholder(uint8_t *public_key,
-                                       uint8_t *secret_key) {
+static int kyber512_r3_keygen_placeholder(uint8_t *public_key,
+                                          uint8_t *secret_key) {
   return kyber512_keypair(public_key, secret_key) == 0;
 }
 
-static int kyber512_encaps_placeholder(uint8_t *ciphertext,
-                                       uint8_t *shared_secret,
-                                       const uint8_t *public_key) {
+static int kyber512_r3_encaps_placeholder(uint8_t *ciphertext,
+                                          uint8_t *shared_secret,
+                                          const uint8_t *public_key) {
   return kyber512_encapsulate(ciphertext, shared_secret, public_key) == 0;
 }
 
-static int kyber512_decaps_placeholder(uint8_t *shared_secret,
-                                       const uint8_t *ciphertext,
-                                       const uint8_t *secret_key) {
+static int kyber512_r3_decaps_placeholder(uint8_t *shared_secret,
+                                          const uint8_t *ciphertext,
+                                          const uint8_t *secret_key) {
   return kyber512_decapsulate(shared_secret, ciphertext, secret_key) == 0;
 }
 
-const KEM_METHOD kem_kyber512_method = {
-  kyber512_keygen_placeholder,
-  kyber512_encaps_placeholder,
-  kyber512_decaps_placeholder,
+const KEM_METHOD kem_kyber512_r3_method = {
+  kyber512_r3_keygen_placeholder,
+  kyber512_r3_encaps_placeholder,
+  kyber512_r3_decaps_placeholder,
 };
 
 // Example how adding new KEM_METHOD looks like:

diff --git a/crypto/obj/obj_dat.h b/crypto/obj/obj_dat.h
@@ -57,7 +57,7 @@
 /* This file is generated by crypto/obj/objects.go. */
 
 
-#define NUM_NID 972
+#define NUM_NID 973
 
 static const uint8_t kObjectData[] = {
     /* NID_rsadsi */
@@ -8832,6 +8832,7 @@ static const ASN1_OBJECT kObjects[NUM_NID] = {
     {"HKDF", "hkdf", NID_hkdf, 0, NULL, 0},
     {"KEM", "kem", NID_kem, 0, NULL, 0},
     {"KYBER512", "KYBER512", NID_KYBER512, 0, NULL, 0},
+    {"KYBER512_R3", "KYBER512_R3", NID_KYBER512_R3, 0, NULL, 0},
 };
 
 static const uint16_t kNIDsInShortNameOrder[] = {
@@ -8947,6 +8948,7 @@ static const uint16_t kNIDsInShortNameOrder[] = {
     970 /* KEM */,
     773 /* KISA */,
     971 /* KYBER512 */,
+    972 /* KYBER512_R3 */,
     957 /* KxANY */,
     952 /* KxECDHE */,
     953 /* KxPSK */,
@@ -9854,6 +9856,7 @@ static const uint16_t kNIDsInLongNameOrder[] = {
     647 /* International Organizations */,
     142 /* Invalidity Date */,
     971 /* KYBER512 */,
+    972 /* KYBER512_R3 */,
     504 /* MIME MHS */,
     388 /* Mail */,
     383 /* Management */,

diff --git a/crypto/obj/obj_mac.num b/crypto/obj/obj_mac.num
@@ -960,3 +960,4 @@ sha3_512		968
 hkdf		969
 kem		970
 KYBER512		971
+KYBER512_R3		972
diff --git a/crypto/obj/objects.txt b/crypto/obj/objects.txt
@@ -1373,3 +1373,4 @@ nist_sha3hashalgs 10		: SHA3-512		: sha3-512
 # NIDs for KEM type and specific KEMs (no corresponding OID).
  : KEM : kem
  : KYBER512
+ : KYBER512_R3
diff --git a/include/openssl/nid.h b/include/openssl/nid.h
@@ -4290,6 +4290,9 @@ extern "C" {
 #define SN_KYBER512 "KYBER512"
 #define NID_KYBER512 971
 
+#define SN_KYBER512_R3 "KYBER512_R3"
+#define NID_KYBER512_R3 972
+
 
 #if defined(__cplusplus)
 } /* extern C */