1<DRAFT!>
2			HOWTO keys
3
41. Introduction
5
6Keys are the basis of public key algorithms and PKI.  Keys usually
7come in pairs, with one half being the public key and the other half
8being the private key.  With OpenSSL, the private key contains the
9public key information as well, so a public key doesn't need to be
10generated separately.
11
12Public keys come in several flavors, using different cryptographic
13algorithms.  The most popular ones associated with certificates are
14RSA and ECDSA, and this HOWTO will show how to generate each of them.
15
162. To generate an RSA key
17
18An RSA key can be used both for encryption and for signing.
19
20Generating a key for the RSA algorithm is quite easy, all you have to
21do is the following:
22
23  openssl genrsa -aes256 -out privkey.pem 2048
24
25With this variant, you will be prompted for a protecting password.  If
26you don't want your key to be protected by a password, remove the flag
27'-aes256' from the command line above.
28
29The number 2048 is the size of the key, in bits.  Today, 2048 or
30higher is recommended for RSA keys, as fewer amount of bits is
31considered to be insecure.
32
333. To generate an EC key
34
35An EC key can be used for either key agreement (ECDH), signing (ECDSA) or
36key encapsulation (KEM) purposes.
37(A key should only be used for one of these purposes)
38
39An EC key can be generated by specifying a curve name such as P-256 using:
40
41  openssl genpkey -algorithm EC -pkeyopt group:P-256 -aes256 -out private.key
42
43With this variant, you will be prompted for a password to protect your key.
44If you don't want your key to be protected by a password, remove the flag
45'-aes256' from the command line above.
46
47Each curve name is associated with a group of fixed parameters.
48Curve names containing numbers lower than 256 are no longer considered
49secure.
50
51The NIST P-256 curve name (which is an alias for prime256v1), stands for
52'X9.62/SECG curve over a 256-bit prime field'.
53
544. To generate a X25519 or X448 Key for Key Agreement
55
56X25519, X448, Ed25519 and Ed448 are treated as distinct algorithms and not as
57one of the EC curves listed with 'ecparam -list_curves' option.
58Unlike other algorithms there are separate key types for signing and
59key agreement.
60
61You can use the following command to generate an X25519 key:
62
63  openssl genpkey -algorithm X25519 -out xkey.pem
64
655. To generate a Ed25519 or Ed448 Key
66
67An Ed25519 or Ed448 key can be used for signing and verification purposes.
68
69You can use the following command to generate an Ed25519 key:
70  openssl genpkey -algorithm Ed25519 -out xkey.pem
71
726. To generate an ML-DSA key
73
74An ML-DSA key can be used for signing (and verification via the public key)
75only.
76
77Generating a key for the ML-DSA algorithm is a one-step process.
78
79  openssl genpkey -algorithm ML-DSA-44 -out key.pem
80  openssl genpkey -algorithm ML-DSA-65 -out key.pem
81  openssl genpkey -algorithm ML-DSA-87 -out key.pem
82
83See L<EVP_PKEY-ML-DSA(7)> for more detail.
84
857. To generate an ML-KEM key
86
87An ML-KEM key can be used for decapsulation (and encapsulation via the public
88key) only.
89
90Generating a key for the ML-KEM algorithm is a one-step process.
91
92  openssl genpkey -algorithm ML-KEM-512 -out key.pem
93  openssl genpkey -algorithm ML-KEM-768 -out key.pem
94  openssl genpkey -algorithm ML-KEM-1024 -out key.pem
95
96See L<EVP_PKEY-ML-KEM(7)> for more detail.
97
988. NOTE
99
100If you intend to use the key together with a server certificate,
101it may be reasonable to avoid protecting it with a password, since
102otherwise someone would have to type in the password every time the
103server needs to access the key.
104
105To generate keys using C code refer to the demos located in
106https://github.com/openssl/openssl/blob/master/demos/pkey.
107