1 =pod 2 3 =head1 NAME 4 5 EVP_PKEY-ML-KEM, 6 EVP_KEYMGMT-ML-KEM, 7 EVP_PKEY-ML-KEM-512, 8 EVP_PKEY-ML-KEM-768, 9 EVP_PKEY-ML-KEM-1024, 10 EVP_KEYMGMT-ML-KEM-512, 11 EVP_KEYMGMT-ML-KEM-768, 12 EVP_KEYMGMT-ML-KEM-1024 13 - ML-KEM keytype and algorithm support 14 15 =head1 DESCRIPTION 16 17 The B<ML-KEM-512>, B<ML-KEM-768>, and B<ML-KEM-1024> keytypes are implemented 18 in OpenSSL's default and FIPS providers. 19 20 =head2 Keygen Parameters 21 22 No mandatory parameters are required for generating a key pair. 23 To set explicit parameters, use EVP_PKEY_CTX_set_params() after calling 24 EVP_PKEY_keygen_init(). 25 26 =over 4 27 28 =item "seed" (B<OSSL_PKEY_PARAM_ML_KEM_SEED>) <octet string> 29 30 Internally, ML-KEM generates keys using a 64-byte random value (seed), which is 31 the concatenation of the 32-byte I<d> and I<z> parameters described in FIPS 203. 32 This optional parameter can be used to set a pre-determined seed prior to 33 keypair generation. 34 35 Generated keys default to retaining the seed used. 36 The seed is also by default retained when keys are loaded from B<PKCS#8> files 37 in the seed format. 38 When available, the seed parameter is also used during key export and import, 39 with keys (by default) regenerated from the seed even when also provided on import. 40 See L</Provider configuration parameters> below for related controls. 41 42 When the seed is retained, it is also available as a B<gettable> parameter, 43 and private key output to B<PKCS#8> files will by default include the seed. 44 When the seed was not initially known, or was not retained, B<PKCS#8> private 45 key files will contain only the private key in FIPS 203 C<dk> format. 46 47 =item "properties" (B<OSSL_PKEY_PARAM_PROPERTIES>) <UTF8 string> 48 49 Sets properties to be used when fetching algorithm implementations used for 50 ML-KEM hashing operations. 51 52 Use L<EVP_PKEY_CTX_set_params(3)> after calling L<EVP_PKEY_keygen_init(3)>. 53 54 =back 55 56 =head2 Common parameters 57 58 In addition to the common parameters that all keytypes should support (see 59 L<provider-keymgmt(7)/Common Information Parameters>), B<ML-KEM> keys 60 keys support the parameters listed below. 61 These are gettable using 62 L<EVP_PKEY_get_octet_string_param(3)> or L<EVP_PKEY_get_params(3)>. 63 They can be initialised via L<EVP_PKEY_fromdata(3)>, and are returned by 64 L<EVP_PKEY_todata(3)> given a suitable I<selection>. 65 Once a public or private key is configured, it can no longer be modified, 66 nor can another key component be added. 67 68 =over 4 69 70 =item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string> 71 72 The public key value. 73 74 This parameter is used when importing or exporting the public key value with 75 the EVP_PKEY_fromdata() and EVP_PKEY_todata() functions. 76 The key length and content is that of the FIPS 203 (Algorithm 16: 77 B<ML-KEM.KeyGen_internal>) B<ek> public key for the given ML-KEM variant. 78 Initial import aside, this parameter is otherwise only gettable. 79 80 =item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <octet string> 81 82 The private key value. 83 84 This parameter is used when importing or exporting the private key value with 85 the EVP_PKEY_fromdata() and EVP_PKEY_todata() functions. 86 The key length and content is that of the FIPS 203 (Algorithm 16: 87 B<ML-KEM.KeyGen_internal>) B<dk> private key for the given ML-KEM variant. 88 Initial import aside, this parameter is otherwise only gettable. 89 90 =item "encoded-pub-key" (B<OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY>) <octet string> 91 92 Used for getting and setting the encoding of a public key. 93 The key format is that of B<ek> in FIPS 203, Algorithm 16: 94 B<ML-KEM.KeyGen_internal>. 95 Updates of the public and private key components are only allowed on keys that 96 are empty. 97 Once a public or private key component is set, no further changes are allowed. 98 This parameter is gettable and settable (once only). 99 100 =back 101 102 =head2 Provider configuration parameters 103 104 See the description of the B<-provparam> option in L<openssl(1)> to learn 105 how to set provider configuration parameters in the command line tools. 106 See L<OSSL_PROVIDER_add_conf_parameter(3)> to learn how to set provider 107 configuration options programmatically. 108 109 =over 4 110 111 =item C<ml-kem.import_pct_type> (B<OSSL_PKEY_PARAM_ML_KEM_IMPORT_PCT_TYPE>) <UTF8 string> 112 113 When an B<ML-KEM> key is imported as an explicit FIPS 203 B<dk> decapsulation 114 key, rather than a seed, a pairwise consistency test (PCT) is optionally 115 performed. 116 By default, or when this parameter is set explicitly to C<random>, the PCT 117 is performed with a random entropy value for the encapsulation step. 118 Setting the parameter to C<fixed>, still runs the test, but the encapsulation 119 entropy is a fixed 32 byte value. 120 Specifying any other value of the parameter, e.g. C<none>, skips the test. 121 122 =item C<ml-kem.retain_seed> (B<OSSL_PKEY_PARAM_ML_KEM_RETAIN_SEED>) <UTF8 string> 123 124 When set to a string representing a false boolean value (see 125 L<OSSL_PROVIDER_conf_get_bool(3)>), the seed will not be retained after key 126 generation or key import from a seed value. 127 If the resulting key is then written to a PKCS#8 object, it will contain 128 only the FIPS 203 C<dk> key. 129 130 =item C<ml-kem.prefer_seed> (B<OSSL_PKEY_PARAM_ML_KEM_PREFER_SEED>) <UTF8 string> 131 132 When decoding PKCS#8 objects that contain both a seed and the FIPS 203 C<dk> 133 private key, the seed is by default used to regenerate the key, and the 134 companion key is ignored. 135 When this configuration parameter is set to a string representing a false 136 boolean value (see L<OSSL_PROVIDER_conf_get_bool(3)>), the seed is ignored 137 (neither used to regenerate the key, nor retained), and the companion key is 138 used instead. 139 140 =item C<ml-kem.input_formats> (B<OSSL_PKEY_PARAM_ML_KEM_INPUT_FORMATS>) <UTF8 string> 141 142 List of enabled private key input formats when parsing PKCS#8 objects. 143 List elements are separated by commas and/or spaces or tabs. 144 The list of enabled formats can be specified in the configuration file, as seen 145 in the L</EXAMPLES> section below, or the via the B<-provparam> command-line 146 option (see also L<OSSL_PROVIDER_add_conf_parameter(3)>). 147 148 Values specified on the command-line override any configuration file settings. 149 By default all the supported formats are enabled. 150 The supported formats are: 151 152 =over 4 153 154 =item C<seed-priv>: 155 156 This format represents B<PKCS#8> objects in which both the FIPS 203 64-byte 157 B<(d, z)> seed and the decapsulation key B<dk> are present in the private key 158 as part of the DER encoding of the ASN.1 sequence: 159 160 ML-KEM-PrivateKey ::= CHOICE { 161 seed [0] IMPLICIT OCTET STRING (SIZE (64)), 162 expandedKey OCTET STRING (SIZE (1632 | 2400 | 3168)), 163 both SEQUENCE { 164 seed OCTET STRING (SIZE (64)), 165 expandedKey OCTET STRING (SIZE (1632 | 2400 | 3168)) } } 166 167 If the C<seed-priv> format is not included in the list, this format will not be 168 recognised on input. 169 170 =item C<seed-only>: 171 172 This format represents B<PKCS#8> objects in which only the 64-byte B<(d, z)> 173 seed is present in the above sequence. 174 If the C<seed-only> format is not included in the list, this format will not be 175 recognised on input. 176 177 =item C<priv-only>: 178 179 This format represents B<PKCS#8> objects in which only the FIPS 203 180 decapsulation key B<dk> is present in the above sequence. 181 If the C<priv-only> format is not included in the list, this format will not be 182 recognised on input. 183 184 =item C<oqskeypair>: 185 186 This format represents B<PKCS#8> objects in which the private key is a DER 187 encoding of an octet string containing the concatenaton of the FIPS 203 188 decapsulation key B<dk> and the encapsulation key B<ek>. 189 This encoding is used in some builds of the C<oqsprovider>. 190 If the C<oqskeypair> format is not included in the list, this format will not be 191 recognised on input. 192 193 =item C<bare-seed>: 194 195 This format represents B<PKCS#8> objects in which the private key contains 196 the 64-byte FIPS 204 seed B<(d, z)> without any ASN.1 encapsulation. 197 If the C<bare-seed> format is not included in the list, this format will not be 198 recognised on input. 199 200 =item C<bare-priv>: 201 202 This format represents B<PKCS#8> objects in which the private key contains 203 the FIPS 204 decapsulation key B<dk> without any ASN.1 encapsulation. 204 If the C<bare-priv> format is not included in the list, this format will not be 205 recognised on input. 206 207 =back 208 209 =item C<ml-kem.output_formats> (B<OSSL_PKEY_PARAM_ML_KEM_OUTPUT_FORMATS>) <UTF8 string> 210 211 Ordered list of enabled private key output formats when writing B<PKCS#8> files. 212 List elements are separated by commas, spaces or tabs. 213 The list of enabled formats can be specified in the configuration file, as seen 214 in the L</EXAMPLES> section below, or the via the B<-provparam> command-line 215 option. 216 217 This supports the same set of formats as described under C<ml-kem.input_formats> 218 above. 219 The order in which elements are listed is important, the selected format will be 220 the first one that is possible to output. 221 If the key seed is known, the first listed format will be selected. 222 If the key seed is not known, the first format that omits the seed will be selected. 223 The default order is equivalent to C<seed-priv> first and C<priv-only> second, with 224 both seed and key output when the seed is available, and just the 225 key otherwise. 226 If C<seed-only> is listed first, then the seed will be output without the key 227 when available, otherwise the output will have just the key. 228 If C<priv-only> is listed first, then just the key is output regardless of 229 whether the seed is present. 230 The legacy C<oqskeypair>, C<bare-seed> and C<bare-priv> formats can also be 231 output, by listing those first. 232 233 =back 234 235 =head1 CONFORMING TO 236 237 =over 4 238 239 =item FIPS 203 240 241 =back 242 243 =head1 EXAMPLES 244 245 An B<EVP_PKEY> context can be obtained by calling: 246 247 EVP_PKEY_CTX *pctx = 248 EVP_PKEY_CTX_new_from_name(NULL, "ML-KEM-768", NULL); 249 250 An B<ML-KEM-768> key can be generated like this: 251 252 pkey = EVP_PKEY_Q_keygen(NULL, NULL, "ML-KEM-768"); 253 254 An B<ML-KEM> private key in seed format can be converted to a key in the FIPS 255 203 B<dk> format by running: 256 257 $ openssl pkey -provparam ml-kem.retain_seed=no \ 258 -in seed-only.pem -out priv-only.pem 259 260 To generate an, e.g., B<ML-KEM-768> key, in FIPS 203 B<dk> format, you can run: 261 262 $ openssl genpkey -provparam ml-kem.retain_seed=no \ 263 -algorithm ml-kem-768 -out priv-only.pem 264 265 If you have a B<PKCS#8> file with both a seed and a key, and prefer to import the 266 companion key rather than the seed, you can run: 267 268 $ openssl pkey -provparam ml-kem.prefer_seed=no \ 269 -in seed-priv.pem -out priv-only.pem 270 271 In the B<openssl.cnf> file, this looks like: 272 273 openssl_conf = openssl_init 274 275 [openssl_init] 276 providers = providers_sect 277 278 # Can be referenced in one or more provider sections 279 [ml_kem_sect] 280 prefer_seed = yes 281 retain_seed = yes 282 # OQS legacy formats disabled 283 input_formats = seed-priv, seed-only, priv-only 284 # Output either the seed alone, or else the key alone 285 output_formats = seed-only, priv-only 286 287 [providers_sect] 288 default = default_sect 289 # Or perhaps just: base = default_sect 290 base = base_sect 291 292 [default_sect] 293 ml-kem = ml_kem_sect 294 295 [base_sect] 296 ml-kem = ml_kem_sect 297 298 =head1 SEE ALSO 299 300 L<openssl(1)>, 301 L<openssl-pkey(1)>, 302 L<openssl-genpkey(1)>, 303 L<EVP_KEYMGMT(3)>, 304 L<EVP_PKEY(3)>, 305 L<EVP_PKEY_get_raw_private_key(3)>, 306 L<EVP_PKEY_get_raw_public_key(3)>, 307 L<EVP_PKEY_get1_encoded_public_key(3)>, 308 L<OSSL_PROVIDER_add_conf_parameter(3)>, 309 L<provider-keymgmt(7)>, 310 L<EVP_KEM-ML-KEM(7)> 311 312 =head1 HISTORY 313 314 This functionality was added in OpenSSL 3.5. 315 316 =head1 COPYRIGHT 317 318 Copyright 2024-2025 The OpenSSL Project Authors. All Rights Reserved. 319 320 Licensed under the Apache License 2.0 (the "License"). You may not use 321 this file except in compliance with the License. You can obtain a copy 322 in the file LICENSE in the source distribution or at 323 L<https://www.openssl.org/source/license.html>. 324 325 =cut 326
Indexes created Fri Oct 09 00:27:48 UTC 2026