From 9972653b537e0c823e7ba200e126e4d62411bf23 Mon Sep 17 00:00:00 2001 From: Michael <57787676+baentsch@users.noreply.github.com> Date: Sat, 17 Jun 2023 13:55:13 +0200 Subject: [PATCH 1/2] update documentation [skip ci] --- README.md | 26 +++++++++++++++++++++----- oqs-template/README.md/algs.fragment | 8 ++++++-- 2 files changed, 27 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 4c16855a..6945c94a 100644 --- a/README.md +++ b/README.md @@ -33,10 +33,15 @@ Algorithms This implementation makes available the following quantum safe algorithms: +### KEM algorithms + - **BIKE**: `bikel1`, `p256_bikel1`, `x25519_bikel1`, `bikel3`, `p384_bikel3`, `x448_bikel3`, `bikel5`, `p521_bikel5` - **CRYSTALS-Kyber**: `kyber512`, `p256_kyber512`, `x25519_kyber512`, `kyber768`, `p384_kyber768`, `x448_kyber768`, `x25519_kyber768`, `p256_kyber768`, `kyber1024`, `p521_kyber1024` - **FrodoKEM**: `frodo640aes`, `p256_frodo640aes`, `x25519_frodo640aes`, `frodo640shake`, `p256_frodo640shake`, `x25519_frodo640shake`, `frodo976aes`, `p384_frodo976aes`, `x448_frodo976aes`, `frodo976shake`, `p384_frodo976shake`, `x448_frodo976shake`, `frodo1344aes`, `p521_frodo1344aes`, `frodo1344shake`, `p521_frodo1344shake` - **HQC**: `hqc128`, `p256_hqc128`, `x25519_hqc128`, `hqc192`, `p384_hqc192`, `x448_hqc192`, `hqc256`, `p521_hqc256`† + +### Signature algorithms + - **CRYSTALS-Dilithium**:`dilithium2`\*, `p256_dilithium2`\*, `rsa3072_dilithium2`\*, `dilithium3`\*, `p384_dilithium3`\*, `dilithium5`\*, `p521_dilithium5`\* - **Falcon**:`falcon512`\*, `p256_falcon512`\*, `rsa3072_falcon512`\*, `falcon1024`\*, `p521_falcon1024`\* @@ -206,6 +211,12 @@ One way to do this is to enable it in the OpenSSL config file. Detailed explanations can be found for example [here](https://wiki.openssl.org/index.php/OpenSSL_3.0#Providers). +An example file activating `oqsprovider` by default is `scripts/openssl-ca.cnf`. +This can be activated for example by setting the standard OpenSSl environment +variable "OPENSSL_CONF" to this file before using `openssl`, e.g. in UNIX notation: + + setenv OPENSSL_CONF=scripts/openssl-ca.cnf + Another alternative is to explicitly request its use on the command line. The following examples use that option. All examples below assume openssl (3.0) to be located in a folder `.local` in the local directory as per the @@ -216,18 +227,23 @@ eliminates the need for specific PATH setting as showcased below. LD_LIBRARY_PATH=.local/lib64 .local/bin/openssl list -providers -verbose -provider-path _build/lib -provider oqsprovider -## Creating (classic) keys and certificates +## Creating keys and certificates -This can be facilitated for example by running +This can be facilitated for example by using the usual `openssl` commands: LD_LIBRARY_PATH=.local/lib64 .local/bin/openssl req -x509 -new -newkey rsa -keyout rsa_CA.key -out rsa_CA.crt -nodes -subj "/CN=test CA" -days 365 -config openssl/apps/openssl.cnf LD_LIBRARY_PATH=.local/lib64 .local/bin/openssl genpkey -algorithm rsa -out rsa_srv.key LD_LIBRARY_PATH=.local/lib64 .local/bin/openssl req -new -newkey rsa -keyout rsa_srv.key -out rsa_srv.csr -nodes -subj "/CN=test server" -config openssl/apps/openssl.cnf LD_LIBRARY_PATH=.local/lib64 .local/bin/openssl x509 -req -in rsa_srv.csr -out rsa_srv.crt -CA rsa_CA.crt -CAkey rsa_CA.key -CAcreateserial -days 365 +These examples create classic RSA keys but the very same commands can be used +to create PQ certificates replacing the key type "rsa" with any of the PQ +signature algorithms [listed above](#Signature_algorithms). + ## Setting up a (quantum-safe) test server -This can be facilitated for example by running +A simple server utilizing PQ/quantum-safe KEM algorithms and classic RSA +certicates can be set up for example by running LD_LIBRARY_PATH=.local/lib64 .local/bin/openssl s_server -cert rsa_srv.crt -key rsa_srv.key -www -tls1_3 -groups kyber768:frodo640shake -provider-path _build/lib -provider default -provider oqsprovider @@ -240,7 +256,7 @@ This can be facilitated for example by running By issuing the command `GET /` the quantum-safe crypto enabled OpenSSL3 server returns details about the established connection. -Any [available KEM algorithm](https://github.com/open-quantum-safe/openssl/tree/OQS-OpenSSL_1_1_1-stable#key-exchange) can be selected by passing it in the `-groups` option. +Any [available quantum-safe/PQ KEM algorithm](#KEM_algorithms) can be selected by passing it in the `-groups` option. ## S/MIME message signing -- Cryptographic Message Syntax (CMS) @@ -258,7 +274,7 @@ Step 1: Create quantum-safe key pair and self-signed certificate: LD_LIBRARY_PATH=.local/lib64 .local/bin/openssl req -x509 -new -newkey dilithium3 -keyout qsc.key -out qsc.crt -nodes -subj "/CN=oqstest" -days 365 -config openssl/apps/openssl.cnf -provider-path _build/lib -provider oqsprovider -provider default By changing the `-newkey` parameter algorithm name [any of the -supported quantum-safe or hybrid algorithms](https://github.com/open-quantum-safe/openssl/tree/OQS-OpenSSL_1_1_1-stable#authentication) +supported quantum-safe or hybrid algorithms](#Signature_algorithms) can be utilized instead of the sample algorithm `dilithium3`. Step 2: Sign data: diff --git a/oqs-template/README.md/algs.fragment b/oqs-template/README.md/algs.fragment index f900d930..17e0785c 100644 --- a/oqs-template/README.md/algs.fragment +++ b/oqs-template/README.md/algs.fragment @@ -1,7 +1,11 @@ -{%- for family, kems in config['kems'] | groupby('family') %} + +### KEM algorithms +{% for family, kems in config['kems'] | groupby('family') %} - **{{ family }}**: {% for kem in kems -%} `{{ kem['name_group'] }}` {%- for hybrid in kem['hybrids'] -%}, `{{ hybrid['hybrid_group']}}_{{ kem['name_group'] }}`{%- endfor -%}{%- if not loop.last %}, {% endif -%}{%- if loop.last and family == 'HQC' -%}†{%- endif -%}{%- endfor -%} {%- endfor %} -{%- for sig in config['sigs'] %} + +### Signature algorithms +{% for sig in config['sigs'] %} {% if sig['variants']|length > 0 -%} - **{{ sig['family'] }}**: {%- for variant in sig['variants'] -%} From 188a913513b61c6223ceda3377e98186e371a4c2 Mon Sep 17 00:00:00 2001 From: Michael <57787676+baentsch@users.noreply.github.com> Date: Sat, 17 Jun 2023 13:59:03 +0200 Subject: [PATCH 2/2] correct links [skip ci] --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 6945c94a..38e8bcf0 100644 --- a/README.md +++ b/README.md @@ -238,7 +238,7 @@ This can be facilitated for example by using the usual `openssl` commands: These examples create classic RSA keys but the very same commands can be used to create PQ certificates replacing the key type "rsa" with any of the PQ -signature algorithms [listed above](#Signature_algorithms). +signature algorithms [listed above](#signature-algorithms). ## Setting up a (quantum-safe) test server @@ -256,7 +256,7 @@ This can be facilitated for example by running By issuing the command `GET /` the quantum-safe crypto enabled OpenSSL3 server returns details about the established connection. -Any [available quantum-safe/PQ KEM algorithm](#KEM_algorithms) can be selected by passing it in the `-groups` option. +Any [available quantum-safe/PQ KEM algorithm](#kem-algorithms) can be selected by passing it in the `-groups` option. ## S/MIME message signing -- Cryptographic Message Syntax (CMS) @@ -274,7 +274,7 @@ Step 1: Create quantum-safe key pair and self-signed certificate: LD_LIBRARY_PATH=.local/lib64 .local/bin/openssl req -x509 -new -newkey dilithium3 -keyout qsc.key -out qsc.crt -nodes -subj "/CN=oqstest" -days 365 -config openssl/apps/openssl.cnf -provider-path _build/lib -provider oqsprovider -provider default By changing the `-newkey` parameter algorithm name [any of the -supported quantum-safe or hybrid algorithms](#Signature_algorithms) +supported quantum-safe or hybrid algorithms](#signature-algorithms) can be utilized instead of the sample algorithm `dilithium3`. Step 2: Sign data: