doc/HOWTO/keys.txt

<DRAFT!>
			HOWTO keys

1. Introduction

Keys are the basis of public key algorithms and PKI.  Keys usually
come in pairs, with one half being the public key and the other half
being the private key.  With OpenSSL, the private key contains the
public key information as well, so a public key doesn't need to be
generated separately.

Public keys come in several flavors, using different cryptographic
algorithms.  The most popular ones associated with certificates are
RSA and ECDSA, and this HOWTO will show how to generate each of them.

2. To generate an RSA key

An RSA key can be used both for encryption and for signing.

Generating a key for the RSA algorithm is quite easy, all you have to
do is the following:

  openssl genrsa -aes256 -out privkey.pem 2048

With this variant, you will be prompted for a protecting password.  If
you don't want your key to be protected by a password, remove the flag
'-aes256' from the command line above.

The number 2048 is the size of the key, in bits.  Today, 2048 or
higher is recommended for RSA keys, as fewer amount of bits is
considered to be insecure.

3. To generate an EC key

An EC key can be used for either key agreement (ECDH), signing (ECDSA) or
key encapsulation (KEM) purposes.
(A key should only be used for one of these purposes)

An EC key can be generated by specifying a curve name such as P-256 using:

  openssl genpkey -algorithm EC -pkeyopt group:P-256 -aes256 -out private.key

With this variant, you will be prompted for a password to protect your key.
If you don't want your key to be protected by a password, remove the flag
'-aes256' from the command line above.

Each curve name is associated with a group of fixed parameters.
Curve names containing numbers lower than 256 are no longer considered
secure.

The NIST P-256 curve name (which is an alias for prime256v1), stands for
'X9.62/SECG curve over a 256-bit prime field'.

4. To generate a X25519 or X448 Key for Key Agreement

X25519, X448, Ed25519 and Ed448 are treated as distinct algorithms and not as
one of the EC curves listed with 'ecparam -list_curves' option.
Unlike other algorithms there are separate key types for signing and
key agreement.

You can use the following command to generate an X25519 key:

  openssl genpkey -algorithm X25519 -out xkey.pem

5. To generate a Ed25519 or Ed448 Key

An Ed25519 or Ed448 key can be used for signing and verification purposes.

You can use the following command to generate an Ed25519 key:
  openssl genpkey -algorithm Ed25519 -out xkey.pem

6. To generate an ML-DSA key

An ML-DSA key can be used for signing (and verification via the public key)
only.

Generating a key for the ML-DSA algorithm is a one-step process.

  openssl genpkey -algorithm ML-DSA-44 -out key.pem
  openssl genpkey -algorithm ML-DSA-65 -out key.pem
  openssl genpkey -algorithm ML-DSA-87 -out key.pem

See L<EVP_PKEY-ML-DSA(7)> for more detail.

7. To generate an ML-KEM key

An ML-KEM key can be used for decapsulation (and encapsulation via the public
key) only.

Generating a key for the ML-KEM algorithm is a one-step process.

  openssl genpkey -algorithm ML-KEM-512 -out key.pem
  openssl genpkey -algorithm ML-KEM-768 -out key.pem
  openssl genpkey -algorithm ML-KEM-1024 -out key.pem

See L<EVP_PKEY-ML-KEM(7)> for more detail.

8. NOTE

If you intend to use the key together with a server certificate,
it may be reasonable to avoid protecting it with a password, since
otherwise someone would have to type in the password every time the
server needs to access the key.

To generate keys using C code refer to the demos located in
https://github.com/openssl/openssl/blob/master/demos/pkey.