Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

explain groups in USAGE [skip ci] #214

Merged
merged 3 commits into from
Jul 12, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 42 additions & 11 deletions USAGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,19 +102,50 @@ This configuration is the one used in all examples below.
deliver functionality also needed by `oqsprovider` (e.g., for hashing or high
quality random data during key generation).

## Checking provider version information
## Selecting TLS1.3 default groups

For activating specific [KEMs](README.md#kem-algorithms), two options exist:

### Command line parameter

All commands allowing pre-selecting KEMs for use permit this via the
`-groups` switch. See example commands below.

### Configuration parameter

The set of acceptable KEM groups can also be set in the `openssl.cnf` file
as per this example:

```
[openssl_init]
ssl_conf = ssl_sect

[ssl_sect]
system_default = system_default_sect

[system_default_sect]
Groups = kyber768:kyber1024
```

Be sure to separate permissible KEM names by colon if specifying several.

## Sample commands

The following section provides example commands for certain standard OpenSSL operations.

### Checking provider version information

openssl list -providers -verbose

## Checking quantum safe signature algorithms available for use
### Checking quantum safe signature algorithms available for use

openssl list -signature-algorithms -provider oqsprovider

## Checking quantum safe KEM algorithms available for use
### Checking quantum safe KEM algorithms available for use

openssl list -kem-algorithms -provider oqsprovider

## Creating keys and certificates
### Creating keys and certificates

This can be facilitated for example by using the usual `openssl` commands:

Expand All @@ -125,20 +156,20 @@ This can be facilitated for example by using the usual `openssl` commands:

These examples create QSC dilithium3 keys but the very same commands can be used
to create PQ certificates replacing the key type "dilithium" with any of the PQ
signature algorithms [listed above](#signature-algorithms).
[signature algorithms supported](README.md#signature-algorithms).
Also, any classic signature algorithm like "rsa" may be used.

## Setting up a (quantum-safe) test server
### Setting up a (quantum-safe) test server

Using keys and certificates as created above, a simple server utilizing a
PQ/quantum-safe KEM algorithm and certicate can be set up for example by running

openssl s_server -cert dilithium3_srv.crt -key dilithium3_srv.key -www -tls1_3 -groups kyber768:frodo640shake

Instead of "dilithium3" any [QSC/PQ signature algorithm supported](#signature-algorithms)
Instead of "dilithium3" any [QSC/PQ signature algorithm supported](README.md#signature-algorithms)
may be used as well as any classic crypto signature algorithm.

## Running a client to interact with (quantum-safe) KEM algorithms
### Running a client to interact with (quantum-safe) KEM algorithms

This can be facilitated for example by running

Expand All @@ -147,9 +178,9 @@ 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](README.md#kem-algorithms) can be selected by passing it in the `-groups` option.

## S/MIME message signing -- Cryptographic Message Syntax (CMS)
### S/MIME message signing -- Cryptographic Message Syntax (CMS)

Also possible is the creation and verification of quantum-safe digital
signatures using [CMS](https://datatracker.ietf.org/doc/html/rfc5652).
Expand All @@ -165,7 +196,7 @@ Step 1: Create quantum-safe key pair and self-signed certificate:
openssl req -x509 -new -newkey dilithium3 -keyout qsc.key -out qsc.crt -nodes -subj "/CN=oqstest" -days 365 -config openssl/apps/openssl.cnf

By changing the `-newkey` parameter algorithm name [any of the
supported quantum-safe or hybrid algorithms](#signature-algorithms)
supported quantum-safe or hybrid algorithms](README.md#signature-algorithms)
can be utilized instead of the sample algorithm `dilithium3`.

Step 2: Sign data:
Expand Down