[ML-KEM] Import ml-kem-ipd source code from Crystals repo (#1514)

This commit only imports the ML-KEM source files from https://github.com/pq-crystals/kyber/tree/standard. We will add them to the build in subsequent PRs.
aws · Apr 1, 2024 · a1f73bc · a1f73bc
1 parent 14b1cf8
commit a1f73bc
Show file tree

Hide file tree

Showing 26 changed files with 2,836 additions and 2 deletions.
diff --git a/LICENSE b/LICENSE
@@ -206,8 +206,8 @@ are met:
    written permission.
 
 
-The code in crypto/kyber/pqcrystals-kyber_kyber512_ref carries the
-Public Domain license:
+The code in crypto/kyber/pqcrystals-kyber_kyber512_ref and
+crypto/ml_kem/ml_kem_ipd_ref_common carries the Public Domain license:
 
 Public Domain (https://creativecommons.org/share-your-work/public-domain/cc0/)
 

diff --git a/crypto/ml_kem/README.md b/crypto/ml_kem/README.md
@@ -0,0 +1,8 @@
+# AWS-LC ML-KEM readme file
+
+The source code in this folder implements ML-KEM-ipd as defined in FIPS 203 (Initial Public Draft) Module-Lattice-Based Key-Encapsulation Mechanism Standard ([link](https://csrc.nist.gov/pubs/fips/203/ipd)).
+
+NOTE: THIS IS AN IMPLEMENTATION OF THE DRAFT VERSION OF FIPS 203, NOT THE FINAL STANDARD. WE WILL CHANGE THIS IMPLEMENTATION TO CONFORM WITH THE STANDARD WHEN IT BECOMES OFFICIAL AND PUBLIC.
+
+**Source code origin and modifications.** The source code was imported from a branch of the official repository of the Crystals-Kyber team that follows the standard draft: https://github.com/pq-crystals/kyber/tree/standard. The code was taken at [commit](https://github.com/pq-crystals/kyber/commit/11d00ff1f20cfca1f72d819e5a45165c1e0a2816) as of 03/26/2024. At the moment, only the reference C implementation is imported.
+
diff --git a/crypto/ml_kem/ml_kem_ipd_ref_common/api.h b/crypto/ml_kem/ml_kem_ipd_ref_common/api.h
@@ -0,0 +1,66 @@
+#ifndef API_H
+#define API_H
+
+#include <stdint.h>
+
+#define pqcrystals_kyber512_SECRETKEYBYTES 1632
+#define pqcrystals_kyber512_PUBLICKEYBYTES 800
+#define pqcrystals_kyber512_CIPHERTEXTBYTES 768
+#define pqcrystals_kyber512_KEYPAIRCOINBYTES 64
+#define pqcrystals_kyber512_ENCCOINBYTES 32
+#define pqcrystals_kyber512_BYTES 32
+
+#define pqcrystals_kyber512_ref_SECRETKEYBYTES pqcrystals_kyber512_SECRETKEYBYTES
+#define pqcrystals_kyber512_ref_PUBLICKEYBYTES pqcrystals_kyber512_PUBLICKEYBYTES
+#define pqcrystals_kyber512_ref_CIPHERTEXTBYTES pqcrystals_kyber512_CIPHERTEXTBYTES
+#define pqcrystals_kyber512_ref_KEYPAIRCOINBYTES pqcrystals_kyber512_KEYPAIRCOINBYTES
+#define pqcrystals_kyber512_ref_ENCCOINBYTES pqcrystals_kyber512_ENCCOINBYTES
+#define pqcrystals_kyber512_ref_BYTES pqcrystals_kyber512_BYTES
+
+int pqcrystals_kyber512_ref_keypair_derand(uint8_t *pk, uint8_t *sk, const uint8_t *coins);
+int pqcrystals_kyber512_ref_keypair(uint8_t *pk, uint8_t *sk);
+int pqcrystals_kyber512_ref_enc_derand(uint8_t *ct, uint8_t *ss, const uint8_t *pk, const uint8_t *coins);
+int pqcrystals_kyber512_ref_enc(uint8_t *ct, uint8_t *ss, const uint8_t *pk);
+int pqcrystals_kyber512_ref_dec(uint8_t *ss, const uint8_t *ct, const uint8_t *sk);
+
+#define pqcrystals_kyber768_SECRETKEYBYTES 2400
+#define pqcrystals_kyber768_PUBLICKEYBYTES 1184
+#define pqcrystals_kyber768_CIPHERTEXTBYTES 1088
+#define pqcrystals_kyber768_KEYPAIRCOINBYTES 64
+#define pqcrystals_kyber768_ENCCOINBYTES 32
+#define pqcrystals_kyber768_BYTES 32
+
+#define pqcrystals_kyber768_ref_SECRETKEYBYTES pqcrystals_kyber768_SECRETKEYBYTES
+#define pqcrystals_kyber768_ref_PUBLICKEYBYTES pqcrystals_kyber768_PUBLICKEYBYTES
+#define pqcrystals_kyber768_ref_CIPHERTEXTBYTES pqcrystals_kyber768_CIPHERTEXTBYTES
+#define pqcrystals_kyber768_ref_KEYPAIRCOINBYTES pqcrystals_kyber768_KEYPAIRCOINBYTES
+#define pqcrystals_kyber768_ref_ENCCOINBYTES pqcrystals_kyber768_ENCCOINBYTES
+#define pqcrystals_kyber768_ref_BYTES pqcrystals_kyber768_BYTES
+
+int pqcrystals_kyber768_ref_keypair_derand(uint8_t *pk, uint8_t *sk, const uint8_t *coins);
+int pqcrystals_kyber768_ref_keypair(uint8_t *pk, uint8_t *sk);
+int pqcrystals_kyber768_ref_enc_derand(uint8_t *ct, uint8_t *ss, const uint8_t *pk, const uint8_t *coins);
+int pqcrystals_kyber768_ref_enc(uint8_t *ct, uint8_t *ss, const uint8_t *pk);
+int pqcrystals_kyber768_ref_dec(uint8_t *ss, const uint8_t *ct, const uint8_t *sk);
+
+#define pqcrystals_kyber1024_SECRETKEYBYTES 3168
+#define pqcrystals_kyber1024_PUBLICKEYBYTES 1568
+#define pqcrystals_kyber1024_CIPHERTEXTBYTES 1568
+#define pqcrystals_kyber1024_KEYPAIRCOINBYTES 64
+#define pqcrystals_kyber1024_ENCCOINBYTES 32
+#define pqcrystals_kyber1024_BYTES 32
+
+#define pqcrystals_kyber1024_ref_SECRETKEYBYTES pqcrystals_kyber1024_SECRETKEYBYTES
+#define pqcrystals_kyber1024_ref_PUBLICKEYBYTES pqcrystals_kyber1024_PUBLICKEYBYTES
+#define pqcrystals_kyber1024_ref_CIPHERTEXTBYTES pqcrystals_kyber1024_CIPHERTEXTBYTES
+#define pqcrystals_kyber1024_ref_KEYPAIRCOINBYTES pqcrystals_kyber1024_KEYPAIRCOINBYTES
+#define pqcrystals_kyber1024_ref_ENCCOINBYTES pqcrystals_kyber1024_ENCCOINBYTES
+#define pqcrystals_kyber1024_ref_BYTES pqcrystals_kyber1024_BYTES
+
+int pqcrystals_kyber1024_ref_keypair_derand(uint8_t *pk, uint8_t *sk, const uint8_t *coins);
+int pqcrystals_kyber1024_ref_keypair(uint8_t *pk, uint8_t *sk);
+int pqcrystals_kyber1024_ref_enc_derand(uint8_t *ct, uint8_t *ss, const uint8_t *pk, const uint8_t *coins);
+int pqcrystals_kyber1024_ref_enc(uint8_t *ct, uint8_t *ss, const uint8_t *pk);
+int pqcrystals_kyber1024_ref_dec(uint8_t *ss, const uint8_t *ct, const uint8_t *sk);
+
+#endif
diff --git a/crypto/ml_kem/ml_kem_ipd_ref_common/cbd.c b/crypto/ml_kem/ml_kem_ipd_ref_common/cbd.c
@@ -0,0 +1,128 @@
+#include <stdint.h>
+#include "params.h"
+#include "cbd.h"
+
+/*************************************************
+* Name:        load32_littleendian
+*
+* Description: load 4 bytes into a 32-bit integer
+*              in little-endian order
+*
+* Arguments:   - const uint8_t *x: pointer to input byte array
+*
+* Returns 32-bit unsigned integer loaded from x
+**************************************************/
+static uint32_t load32_littleendian(const uint8_t x[4])
+{
+  uint32_t r;
+  r  = (uint32_t)x[0];
+  r |= (uint32_t)x[1] << 8;
+  r |= (uint32_t)x[2] << 16;
+  r |= (uint32_t)x[3] << 24;
+  return r;
+}
+
+/*************************************************
+* Name:        load24_littleendian
+*
+* Description: load 3 bytes into a 32-bit integer
+*              in little-endian order.
+*              This function is only needed for Kyber-512
+*
+* Arguments:   - const uint8_t *x: pointer to input byte array
+*
+* Returns 32-bit unsigned integer loaded from x (most significant byte is zero)
+**************************************************/
+#if KYBER_ETA1 == 3
+static uint32_t load24_littleendian(const uint8_t x[3])
+{
+  uint32_t r;
+  r  = (uint32_t)x[0];
+  r |= (uint32_t)x[1] << 8;
+  r |= (uint32_t)x[2] << 16;
+  return r;
+}
+#endif
+
+
+/*************************************************
+* Name:        cbd2
+*
+* Description: Given an array of uniformly random bytes, compute
+*              polynomial with coefficients distributed according to
+*              a centered binomial distribution with parameter eta=2
+*
+* Arguments:   - poly *r: pointer to output polynomial
+*              - const uint8_t *buf: pointer to input byte array
+**************************************************/
+static void cbd2(poly *r, const uint8_t buf[2*KYBER_N/4])
+{
+  unsigned int i,j;
+  uint32_t t,d;
+  int16_t a,b;
+
+  for(i=0;i<KYBER_N/8;i++) {
+    t  = load32_littleendian(buf+4*i);
+    d  = t & 0x55555555;
+    d += (t>>1) & 0x55555555;
+
+    for(j=0;j<8;j++) {
+      a = (d >> (4*j+0)) & 0x3;
+      b = (d >> (4*j+2)) & 0x3;
+      r->coeffs[8*i+j] = a - b;
+    }
+  }
+}
+
+/*************************************************
+* Name:        cbd3
+*
+* Description: Given an array of uniformly random bytes, compute
+*              polynomial with coefficients distributed according to
+*              a centered binomial distribution with parameter eta=3.
+*              This function is only needed for Kyber-512
+*
+* Arguments:   - poly *r: pointer to output polynomial
+*              - const uint8_t *buf: pointer to input byte array
+**************************************************/
+#if KYBER_ETA1 == 3
+static void cbd3(poly *r, const uint8_t buf[3*KYBER_N/4])
+{
+  unsigned int i,j;
+  uint32_t t,d;
+  int16_t a,b;
+
+  for(i=0;i<KYBER_N/4;i++) {
+    t  = load24_littleendian(buf+3*i);
+    d  = t & 0x00249249;
+    d += (t>>1) & 0x00249249;
+    d += (t>>2) & 0x00249249;
+
+    for(j=0;j<4;j++) {
+      a = (d >> (6*j+0)) & 0x7;
+      b = (d >> (6*j+3)) & 0x7;
+      r->coeffs[4*i+j] = a - b;
+    }
+  }
+}
+#endif
+
+void poly_cbd_eta1(poly *r, const uint8_t buf[KYBER_ETA1*KYBER_N/4])
+{
+#if KYBER_ETA1 == 2
+  cbd2(r, buf);
+#elif KYBER_ETA1 == 3
+  cbd3(r, buf);
+#else
+#error "This implementation requires eta1 in {2,3}"
+#endif
+}
+
+void poly_cbd_eta2(poly *r, const uint8_t buf[KYBER_ETA2*KYBER_N/4])
+{
+#if KYBER_ETA2 == 2
+  cbd2(r, buf);
+#else
+#error "This implementation requires eta2 = 2"
+#endif
+}
diff --git a/crypto/ml_kem/ml_kem_ipd_ref_common/cbd.h b/crypto/ml_kem/ml_kem_ipd_ref_common/cbd.h
@@ -0,0 +1,14 @@
+#ifndef CBD_H
+#define CBD_H
+
+#include <stdint.h>
+#include "params.h"
+#include "poly.h"
+
+#define poly_cbd_eta1 KYBER_NAMESPACE(poly_cbd_eta1)
+void poly_cbd_eta1(poly *r, const uint8_t buf[KYBER_ETA1*KYBER_N/4]);
+
+#define poly_cbd_eta2 KYBER_NAMESPACE(poly_cbd_eta2)
+void poly_cbd_eta2(poly *r, const uint8_t buf[KYBER_ETA2*KYBER_N/4]);
+
+#endif