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 1 commit
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
49 changes: 40 additions & 9 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,10 +156,10 @@ 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
Expand All @@ -138,7 +169,7 @@ PQ/quantum-safe KEM algorithm and certicate can be set up for example by running
Instead of "dilithium3" any [QSC/PQ signature algorithm supported](#signature-algorithms)
baentsch marked this conversation as resolved.
Show resolved Hide resolved
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 Down