Merge pull request #198 from PQClean/ds-aes-key-schedule

Add release function for AES key schedule

CONTRIBUTING.md

@@ -57,6 +57,7 @@ See the section [API](#API) below.
     astyle --project crypto_kem/yourschemename/clean/*.[ch]
     ```
     4. You may run the tests in the `tests/` folder. See the `README` for how to run the test suite.
+    5. Migrate your use of AES, SHA-2, and SHA-3 to the API in the `common` directory. Note that if you use the AES API, you must use the `aes128_keyexp` routine (or 192 or 256) to expand the key into a key schedule object, then use `aes128_ctx_release` to release the key schedule object once you're finished with it.
 
 5. Create `Makefile` and `Makefile.Microsoft_nmake` files to compile your scheme as static library.
     * We suggest you copy these from `crypto_kem/kyber768/clean` and modify them to suit your scheme.

README.md

@@ -130,7 +130,7 @@ Their integration strategies may serve as examples for your own projects.
 
 - **[pqcrypto crate](https://github.com/rustpq/pqcrypto)**: Rust integration that automatically generates wrappers from PQClean source code.
 - **[mupq](https://github.com/mupq/)**: Runs the implementations from PQClean as reference implementations to compare with microcontroller-optimized code.
-- **[Open Quantum Safe](https://github.com/open-quantum-safe/)**: The Open Quantum Safe project integrates implementations from PQClean into their [liboqs](https://github.com/open-quantum-safe/liboqs) C library, which then exposes them via [C++](https://github.com/open-quantum-safe/liboqs-cpp), [C# / .NET](https://github.com/open-quantum-safe/liboqs-dotnet), and [Python](https://github.com/open-quantum-safe/liboqs-python) wrappers, as well as to forks of [OpenSSL](https://github.com/open-quantum-safe/openssl) and [OpenSSH](https://github.com/open-quantum-safe/openssh-portable).
+- **[Open Quantum Safe](https://github.com/open-quantum-safe/)**: The Open Quantum Safe project integrates implementations from PQClean into their [liboqs](https://github.com/open-quantum-safe/liboqs/) C library, which then exposes them via [C++](https://github.com/open-quantum-safe/liboqs-cpp), [C# / .NET](https://github.com/open-quantum-safe/liboqs-dotnet), and [Python](https://github.com/open-quantum-safe/liboqs-python) wrappers, as well as to forks of [OpenSSL](https://github.com/open-quantum-safe/openssl) and [OpenSSH](https://github.com/open-quantum-safe/openssh-portable).
 
 ## License
 

common/aes.c

@@ -622,3 +622,18 @@ void aes256_ctr(unsigned char *out, size_t outlen, const unsigned char *iv, cons
     aes_ctr(out, outlen, iv, ctx->sk_exp, 14);
 }
 
+void aes128_ctx_release(aes128ctx *r) {
+    // no-op for PQClean's basic AES operation
+    (void) r;
+}
+
+void aes192_ctx_release(aes192ctx *r) {
+    // no-op for PQClean's basic AES operation
+    (void) r;
+}
+
+void aes256_ctx_release(aes256ctx *r) {
+    // no-op for PQClean's basic AES operation
+    (void) r;
+}
+

common/aes.h

@@ -30,6 +30,8 @@ void aes128_ecb(unsigned char *out, const unsigned char *in, size_t nblocks, con
 
 void aes128_ctr(unsigned char *out, size_t outlen, const unsigned char *iv, const aes128ctx *ctx);
 
+void aes128_ctx_release(aes128ctx *r);
+
 
 void aes192_keyexp(aes192ctx *r, const unsigned char *key);
 
@@ -37,6 +39,8 @@ void aes192_ecb(unsigned char *out, const unsigned char *in, size_t nblocks, con
 
 void aes192_ctr(unsigned char *out, size_t outlen, const unsigned char *iv, const aes192ctx *ctx);
 
+void aes192_ctx_release(aes192ctx *r);
+
 
 void aes256_keyexp(aes256ctx *r, const unsigned char *key);
 
@@ -44,5 +48,7 @@ void aes256_ecb(unsigned char *out, const unsigned char *in, size_t nblocks, con
 
 void aes256_ctr(unsigned char *out, size_t outlen, const unsigned char *iv, const aes256ctx *ctx);
 
+void aes256_ctx_release(aes256ctx *r);
+
 
 #endif

crypto_kem/frodokem1344aes/clean/matrix_aes.c

@@ -33,6 +33,7 @@ int PQCLEAN_FRODOKEM1344AES_CLEAN_mul_add_as_plus_e(uint16_t *out, const uint16_
     }
 
     aes128_ecb((uint8_t *) A, (uint8_t *) A, PARAMS_N * PARAMS_N * sizeof(int16_t) / AES_BLOCKBYTES, &ctx128);
+    aes128_ctx_release(&ctx128);
 
     for (i = 0; i < PARAMS_N * PARAMS_N; i++) {
         A[i] = PQCLEAN_FRODOKEM1344AES_CLEAN_LE_TO_UINT16(A[i]);
@@ -73,6 +74,7 @@ int PQCLEAN_FRODOKEM1344AES_CLEAN_mul_add_sa_plus_e(uint16_t *out, const uint16_
     }
 
     aes128_ecb((uint8_t *) A, (uint8_t *) A, PARAMS_N * PARAMS_N * sizeof(int16_t) / AES_BLOCKBYTES, &ctx128);
+    aes128_ctx_release(&ctx128);
 
     for (i = 0; i < PARAMS_N * PARAMS_N; i++) {
         A[i] = PQCLEAN_FRODOKEM1344AES_CLEAN_LE_TO_UINT16(A[i]);

crypto_kem/frodokem1344aes/opt/matrix_aes.c

@@ -63,6 +63,7 @@ int PQCLEAN_FRODOKEM1344AES_OPT_mul_add_as_plus_e(uint16_t *out, const uint16_t
             out[(i + 3)*PARAMS_NBAR + k] += sum[3];
         }
     }
+    aes128_ctx_release(&ctx128);
     return 1;
 }
 
@@ -121,5 +122,6 @@ int PQCLEAN_FRODOKEM1344AES_OPT_mul_add_sa_plus_e(uint16_t *out, const uint16_t
             }
         }
     }
+    aes128_ctx_release(&ctx128);
     return 1;
 }

crypto_kem/frodokem640aes/clean/matrix_aes.c

@@ -33,6 +33,7 @@ int PQCLEAN_FRODOKEM640AES_CLEAN_mul_add_as_plus_e(uint16_t *out, const uint16_t
     }
 
     aes128_ecb((uint8_t *) A, (uint8_t *) A, PARAMS_N * PARAMS_N * sizeof(int16_t) / AES_BLOCKBYTES, &ctx128);
+    aes128_ctx_release(&ctx128);
 
     for (i = 0; i < PARAMS_N * PARAMS_N; i++) {
         A[i] = PQCLEAN_FRODOKEM640AES_CLEAN_LE_TO_UINT16(A[i]);
@@ -73,6 +74,7 @@ int PQCLEAN_FRODOKEM640AES_CLEAN_mul_add_sa_plus_e(uint16_t *out, const uint16_t
     }
 
     aes128_ecb((uint8_t *) A, (uint8_t *) A, PARAMS_N * PARAMS_N * sizeof(int16_t) / AES_BLOCKBYTES, &ctx128);
+    aes128_ctx_release(&ctx128);
 
     for (i = 0; i < PARAMS_N * PARAMS_N; i++) {
         A[i] = PQCLEAN_FRODOKEM640AES_CLEAN_LE_TO_UINT16(A[i]);

crypto_kem/frodokem640aes/opt/matrix_aes.c

@@ -63,6 +63,7 @@ int PQCLEAN_FRODOKEM640AES_OPT_mul_add_as_plus_e(uint16_t *out, const uint16_t *
             out[(i + 3)*PARAMS_NBAR + k] += sum[3];
         }
     }
+    aes128_ctx_release(&ctx128);
     return 1;
 }
 
@@ -121,5 +122,6 @@ int PQCLEAN_FRODOKEM640AES_OPT_mul_add_sa_plus_e(uint16_t *out, const uint16_t *
             }
         }
     }
+    aes128_ctx_release(&ctx128);
     return 1;
 }

crypto_kem/frodokem976aes/clean/matrix_aes.c

@@ -33,6 +33,7 @@ int PQCLEAN_FRODOKEM976AES_CLEAN_mul_add_as_plus_e(uint16_t *out, const uint16_t
     }
 
     aes128_ecb((uint8_t *) A, (uint8_t *) A, PARAMS_N * PARAMS_N * sizeof(int16_t) / AES_BLOCKBYTES, &ctx128);
+    aes128_ctx_release(&ctx128);
 
     for (i = 0; i < PARAMS_N * PARAMS_N; i++) {
         A[i] = PQCLEAN_FRODOKEM976AES_CLEAN_LE_TO_UINT16(A[i]);
@@ -73,6 +74,7 @@ int PQCLEAN_FRODOKEM976AES_CLEAN_mul_add_sa_plus_e(uint16_t *out, const uint16_t
     }
 
     aes128_ecb((uint8_t *) A, (uint8_t *) A, PARAMS_N * PARAMS_N * sizeof(int16_t) / AES_BLOCKBYTES, &ctx128);
+    aes128_ctx_release(&ctx128);
 
     for (i = 0; i < PARAMS_N * PARAMS_N; i++) {
         A[i] = PQCLEAN_FRODOKEM976AES_CLEAN_LE_TO_UINT16(A[i]);

crypto_kem/frodokem976aes/opt/matrix_aes.c

@@ -63,6 +63,7 @@ int PQCLEAN_FRODOKEM976AES_OPT_mul_add_as_plus_e(uint16_t *out, const uint16_t *
             out[(i + 3)*PARAMS_NBAR + k] += sum[3];
         }
     }
+    aes128_ctx_release(&ctx128);
     return 1;
 }
 
@@ -121,5 +122,6 @@ int PQCLEAN_FRODOKEM976AES_OPT_mul_add_sa_plus_e(uint16_t *out, const uint16_t *
             }
         }
     }
+    aes128_ctx_release(&ctx128);
     return 1;
 }

crypto_kem/ledakemlt12/leaktime/rng.c

@@ -103,6 +103,7 @@ int PQCLEAN_LEDAKEMLT12_LEAKTIME_seedexpander(AES_XOF_struct *ctx, unsigned char
         }
 
     }
+    aes256_ctx_release(&ctx256);
 
     return RNG_SUCCESS;
 }

crypto_kem/ledakemlt32/leaktime/rng.c

@@ -103,6 +103,7 @@ int PQCLEAN_LEDAKEMLT32_LEAKTIME_seedexpander(AES_XOF_struct *ctx, unsigned char
         }
 
     }
+    aes256_ctx_release(&ctx256);
 
     return RNG_SUCCESS;
 }

crypto_kem/ledakemlt52/leaktime/rng.c

@@ -103,6 +103,7 @@ int PQCLEAN_LEDAKEMLT52_LEAKTIME_seedexpander(AES_XOF_struct *ctx, unsigned char
         }
 
     }
+    aes256_ctx_release(&ctx256);
 
     return RNG_SUCCESS;
 }

test/common/aes.c

@@ -96,5 +96,9 @@ int main(void)
     r = 1;
   }
 
+  aes128_ctx_release(&ctx128);
+  aes192_ctx_release(&ctx192);
+  aes256_ctx_release(&ctx256);
+
   return r;
 }