Adds encoding options for subjectPublicKey and privateKey (open-quant…

…um-safe#123) * Add encoding library - Encodings settable via env variables - Add key encoding options to README.md - Add qsc_encoder version strings Signed-off-by: Felipe Ventura <felipe.ventura@entrust.com>
EntrustCorporation · Mar 13, 2024 · ae9922a · ae9922a
1 parent 105b985
commit ae9922a
Show file tree

Hide file tree

Showing 17 changed files with 540 additions and 157 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -37,6 +37,22 @@ jobs:
           name: Run tests
           command: |
              ./scripts/runtests.sh -V
+      - run:
+          name: Run tests (with encodings)
+          command: |
+            ./scripts/runtests_encodings.sh -V
+      - run:
+          name: Build OQS-OpenSSL provider (only STD algs) with NOPUBKEY_IN_PRIVKEY
+          command: |
+             rm -rf _build && mkdir _build && cd _build && cmake -GNinja -DNOPUBKEY_IN_PRIVKEY=ON -DOPENSSL_ROOT_DIR=$(pwd)/../.local -DCMAKE_PREFIX_PATH=$(pwd)/../.local .. && ninja
+      - run:
+          name: Run tests (-DNOPUBKEY_IN_PRIVKEY=ON)
+          command: |
+             ./scripts/runtests.sh -V
+      - run:
+          name: Run tests (-DNOPUBKEY_IN_PRIVKEY=ON, with encodings)
+          command: |
+            ./scripts/runtests_encodings.sh -V
 workflows:
   version: 2.1
   build:

diff --git a/ALGORITHMS.md b/ALGORITHMS.md
@@ -294,3 +294,63 @@ adapting the OIDs of all supported signature algorithms as per the table below.
 | p521_sphincsshake256256ssimple | 1.3.9999.6.9.8 |No| OQS_OID_P521_SPHINCSSHAKE256256SSIMPLE
 <!--- OQS_TEMPLATE_FRAGMENT_OIDS_END -->
 
+# Key Encodings
+
+By setting environment variables, oqs-provider can be configured to encode keys (subjectPublicKey and and privateKey ASN.1 structures) according to the following IETF drafts:
+
+- https://datatracker.ietf.org/doc/draft-uni-qsckeys-dilithium/00/
+- https://datatracker.ietf.org/doc/draft-uni-qsckeys-falcon/00/
+- https://datatracker.ietf.org/doc/draft-uni-qsckeys-sphincsplus/00/
+
+<!--- OQS_TEMPLATE_FRAGMENT_ENCODINGS_START -->
+|Environment Variable | Permissible Values |
+| --- | --- |
+|`OQS_ENCODING_DILITHIUM2`|`draft-uni-qsckeys-dilithium-00/sk-pk`|
+|`OQS_ENCODING_DILITHIUM3`|`draft-uni-qsckeys-dilithium-00/sk-pk`|
+|`OQS_ENCODING_DILITHIUM5`|`draft-uni-qsckeys-dilithium-00/sk-pk`|
+|`OQS_ENCODING_DILITHIUM2_AES`|`draft-uni-qsckeys-dilithium-00/sk-pk`|
+|`OQS_ENCODING_DILITHIUM3_AES`|`draft-uni-qsckeys-dilithium-00/sk-pk`|
+|`OQS_ENCODING_DILITHIUM5_AES`|`draft-uni-qsckeys-dilithium-00/sk-pk`|
+|`OQS_ENCODING_FALCON512`|`draft-uni-qsckeys-falcon-00/sk-pk`|
+|`OQS_ENCODING_FALCON1024`|`draft-uni-qsckeys-falcon-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSHARAKA128FROBUST`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSHARAKA128FSIMPLE`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSHARAKA128SROBUST`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSHARAKA128SSIMPLE`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSHARAKA192FROBUST`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSHARAKA192FSIMPLE`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSHARAKA192SROBUST`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSHARAKA192SSIMPLE`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSHARAKA256FROBUST`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSHARAKA256FSIMPLE`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSHARAKA256SROBUST`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSHARAKA256SSIMPLE`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHA256128FROBUST`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHA256128FSIMPLE`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHA256128SROBUST`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHA256128SSIMPLE`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHA256192FROBUST`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHA256192FSIMPLE`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHA256192SROBUST`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHA256192SSIMPLE`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHA256256FROBUST`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHA256256FSIMPLE`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHA256256SROBUST`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHA256256SSIMPLE`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHAKE256128FROBUST`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHAKE256128FSIMPLE`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHAKE256128SROBUST`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHAKE256128SSIMPLE`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHAKE256192FROBUST`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHAKE256192FSIMPLE`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHAKE256192SROBUST`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHAKE256192SSIMPLE`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHAKE256256FROBUST`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHAKE256256FSIMPLE`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHAKE256256SROBUST`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+|`OQS_ENCODING_SPHINCSSHAKE256256SSIMPLE`|`draft-uni-qsckeys-sphincsplus-00/sk-pk`|
+<!--- OQS_TEMPLATE_FRAGMENT_ENCODINGS_END -->
+
+If no environment variable is set, or if an unknown value is set, the default is 'no' encoding, meaning that key serialization uses the 'raw' keys of the crypto implementations. 
+
+The test script `scripts/runtests_encodings.sh` (instead of `scripts/runtests.sh`) can be used for a test run with all supported encodings activated.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -17,6 +17,13 @@ if(${NOPUBKEY_IN_PRIVKEY})
 else()
     message(STATUS "Build will store public keys in PKCS#8 structures")
 endif()
+option(USE_ENCODING_LIB "Build with external encoding library for SPKI/PKCS#8 " ON)
+if(${USE_ENCODING_LIB})
+    message(STATUS "Build will include external encoding library for SPKI/PKCS#8")
+    add_compile_definitions( USE_ENCODING_LIB )
+else()
+    message(STATUS "Build will not include external encoding library for SPKI/PKCS#8")
+endif()
 
 include(CheckLibraryExists)
 include(CheckFunctionExists)

diff --git a/README.md b/README.md
@@ -178,6 +178,12 @@ excludes all algorithms of the "Sphincs" family.
 *Note*: By default, interoperability testing with oqs-openssl111 is no longer
 performed by default but can be manually enabled in the script `scripts/runtests.sh`.
 
+### Key Encoding
+
+By setting `-DUSE_ENCODING_LIB=<ON/OFF>` at compile-time, oqs-provider can be compiled with with an an external encoding library `qsc-key-encoder`. Configuring the encodings is done via environment as described in [ALGORITHMS.md](ALGORITHMS.md).
+
+By setting `-DNOPUBKEY_IN_PRIVKEY=<ON/OFF>` at compile-time, it can be further specified to omit explicitly serializing the public key in a `privateKey` structure. The default value is `OFF`.
+
 Building on Windows
 --------------------
 The following steps have been tested on Windows 10 and 11 using MSYS2 MINGW64 and were successful. However, building with Visual Studio 2019 was unsuccessful (see [#47](https://github.com/open-quantum-safe/oqs-provider/issues/47)). Note that the process of building on Windows is considered experimental and may need further adjustments. Please report further issues to [#47](https://github.com/open-quantum-safe/oqs-provider/issues/47). Despite skipping the testing process, setting up a test server and client with post-quantum cryptography algorithms can still be accomplished.

diff --git a/RELEASE.md b/RELEASE.md
@@ -42,6 +42,7 @@ None.
 ### Misc updates
 
 - Dynamic code point and OID changes via environment variables. See [ALGORITHMS.md](ALGORITHMS.md).
+- Dynamic key encoding changes via environment variable using external qsc_key_encoder library. See [ALGORITHMS.md](ALGORITHMS.md).
 
 ---
 

diff --git a/oqs-template/ALGORITHMS.md/encodings.fragment b/oqs-template/ALGORITHMS.md/encodings.fragment
@@ -0,0 +1,13 @@
+
+|Environment Variable | Permissible Values |
+| --- | --- |
+{% for sig in config['sigs'] -%}
+   {%- for variant in sig['variants'] -%}
+   {%- if 'supported_encodings' in variant -%}
+|`OQS_ENCODING_{{variant['name']|upper}}`|
+{%- for item in variant['supported_encodings'] -%}
+`{{item}}`{% if not loop.last %}, {%- endif -%}
+{% endfor %}|
+{% endif %}
+{%- endfor %}
+{%- endfor %}
-Original file line number
+Diff line change
@@ Expand Up / @@ -42,6 +42,7 @@ None. @@
     ### Misc updates
     - Dynamic code point and OID changes via environment variables. See [ALGORITHMS.md](ALGORITHMS.md).
+    - Dynamic key encoding changes via environment variable using external qsc_key_encoder library. See [ALGORITHMS.md](ALGORITHMS.md).
     ---
@@ Expand Down @@