search..
No manual entry for -- in section 7SSL
troff:<standard input>:336: warning [p 4, 5.8i]: cannot adjust line
EVP_PKEY-ML-DSA(7SSL)		    OpenSSL		  EVP_PKEY-ML-DSA(7SSL)

NAME
       EVP_PKEY-ML-DSA, EVP_KEYMGMT-ML-DSA, EVP_PKEY-ML-DSA-44,
       EVP_PKEY-ML-DSA-65, EVP_PKEY-ML-DSA-87 - EVP_PKEY ML-DSA keytype and
       algorithm support

DESCRIPTION
       ML-DSA implements the algorithms ML-DSA-44, ML-DSA-65 and ML-DSA-87.
       The key types EVP_PKEY_ML_DSA_44, EVP_PKEY_ML_DSA_65 and
       EVP_PKEY_ML_DSA_87 are implemented in OpenSSL's default and FIPS
       providers.  These implementations support the associated key, containing
       the public key pub and the private key priv.

       Each of the different key types has an associated security category.
       This value is one of 2, 3 or 5 for key types ML-DSA-44, ML-DSA-65 and
       ML-DSA-87 respectively, which correspond to security strengths of 128,
       192 and 256 respectively.

   Keygen Parameters
       "seed" (OSSL_PKEY_PARAM_ML_DSA_SEED) <octet string>
	   The	seed  can  be  used  to	 generate  the	private	 and public key
	   components in a deterministic  manner.   The	 length	 of  the  value
	   supplied must be 32 bytes.  When this value is not supplied the seed
	   is generated randomly using a DRBG.

	   Generated keys default to retaining the seed used.  The seed is also
	   by  default	retained  when keys are loaded from PKCS#8 files in the
	   seed format.	 When available, the seed parameter is also used during
	   key export and import, with keys (by default) regenerated  from  the
	   seed even when also provided on import.  See "Provider configuration
	   parameters" below for related controls.

	   When	 the  seed  is	retained,  it  is  also available as a gettable
	   parameter, and private key output to PKCS#8 files  will  by	default
	   include the seed.  When the seed was not initially known, or was not
	   retained, PKCS#8 private key files will contain only the private key
	   in FIPS 204 "sk" format.

       "properties" (OSSL_PKEY_PARAM_PROPERTIES) <UTF8 string>
	   Sets	 properties  to be used when fetching algorithm implementations
	   used for ML-DSA hashing operations.

       Use EVP_PKEY_CTX_set_params(3) after calling EVP_PKEY_keygen_init(3).

   Common ML-DSA parameters
       In addition to the common parameters that all  keytypes	should	support
       (see   "Common	Information  Parameters"  in  provider-keymgmt(7),  the
       implementation of these key types support the parameters	 listed	 below.
       These   are   gettable	using	EVP_PKEY_get_octet_string_param(3)   or
       EVP_PKEY_get_params(3).	    They     can     be	    initialised	    via
       EVP_PKEY_fromdata(3),  and  are	returned  by EVP_PKEY_todata(3) given a
       suitable selection.  Once a public or private key is configured, it  can
       no longer be modified, nor can another key component be added.

       "pub" (OSSL_PKEY_PARAM_PUB_KEY) <octet string>
	   The	encoded	 public	 key  value  of	 size  1312, 1952 or 2592 bytes
	   depending on the respective key  type  of  ML-DSA-44,  ML-DSA-65  or
	   ML-DSA-87.

       "priv" (OSSL_PKEY_PARAM_PRIV_KEY) <octet string>
	   The	encoded	 private  key  value  of  size 2560, 4032 or 4896 bytes
	   depending on the respective key  type  of  ML-DSA-44,  ML-DSA-65  or
	   ML-DSA-87.

   Provider configuration parameters
       See  the description of the -provparam option in openssl(1) to learn how
       to set provider configuration parameters in the command line tools.  See
       OSSL_PROVIDER_add_conf_parameter(3)  to	learn  how  to	 set   provider
       configuration options programmatically.

       "ml-dsa.retain_seed" (OSSL_PKEY_PARAM_ML_DSA_RETAIN_SEED) <UTF8 string>
	   When	 set  to  a  string  representing  a  false  boolean value (see
	   OSSL_PROVIDER_conf_get_bool(3)), the seed will not be retained after
	   key generation or key import from a seed value.   If	 the  resulting
	   key	is  then  written  to a PKCS#8 object, it will contain only the
	   FIPS 204 "sk" key.

       "ml-dsa.prefer_seed" (OSSL_PKEY_PARAM_ML_DSA_PREFER_SEED) <UTF8 string>
	   When decoding PKCS#8 objects that contain both a seed and  the  FIPS
	   204	"sk" private key, the seed is by default used to regenerate the
	   key,	 and  the  companion  private  key  is	ignored.    When   this
	   configuration  parameter  is	 set  to  a string representing a false
	   boolean value  (see	OSSL_PROVIDER_conf_get_bool(3)),  the  seed  is
	   ignored  (neither used to regenerate the key, nor retained), and the
	   companion key is used instead.

       "ml-dsa.input_formats" (OSSL_PKEY_PARAM_ML_DSA_INPUT_FORMATS) <UTF8
       string>
	   List of enabled  private  key  input	 formats  when	parsing	 PKCS#8
	   objects.   List  elements  are  separated by commas, spaces or tabs.
	   The list of enabled formats can be specified	 in  the  configuration
	   file,  as  seen  in	the  "EXAMPLES"	 section  below, or the via the
	   -provparam	     command-line	 option	       (see	   also
	   OSSL_PROVIDER_add_conf_parameter(3)).

	   Values specified on the command-line override any configuration file
	   settings.   By  default  all the supported formats are enabled.  The
	   supported formats are:

	   "seed-priv":
	       This format represents PKCS#8 objects in which both the FIPS 204
	       32-byte <xi> seed and the secret	 key  sk  are  present	in  the
	       private key as part of the DER encoding of the ASN.1 sequence:

		   ML-DSA-PrivateKey ::= CHOICE {
		     seed [0] IMPLICIT OCTET STRING (SIZE (32)),
		     expandedKey OCTET STRING (SIZE (2560 | 4032 | 4896)),
		     both SEQUENCE {
		       seed OCTET STRING (SIZE (32)),
		       expandedKey OCTET STRING (SIZE (2560 | 4032 | 4896)) } }

	       If  the	"seed-priv"  format  is	 not included in the list, this
	       format will not be recognised on input.

	   "seed-only":
	       This format represents PKCS#8 objects in which only the	32-byte
	       FIPS  204  <xi>	seed  is present in the above sequence.	 If the
	       "seed-only" format is not included in the list, this format will
	       not be recognised on input.

	   "priv-only":
	       This format represents PKCS#8 objects in which only the FIPS 204
	       private key sk  is  present  in	the  above  sequence.	If  the
	       "priv-only" format is not included in the list, this format will
	       not be recognised on input.

	   "oqskeypair":
	       This  format  represents PKCS#8 objects in which the private key
	       is a DER encoding of an octet string containing the concatenaton
	       of the FIPS 204 private key sk and  the	public	key  pk.   This
	       encoding	 is  used  in some builds of the "oqsprovider".	 If the
	       "oqskeypair" format is not included in  the  list,  this	 format
	       will not be recognised on input.

	   "bare-seed":
	       This  format  represents PKCS#8 objects in which the private key
	       contains the 32-byte  FIPS  204	seed  <xi>  without  any  ASN.1
	       encapsulation.  If the "bare-seed" format is not included in the
	       list, this format will not be recognised on input.

	   "bare-priv":
	       This  format  represents PKCS#8 objects in which the private key
	       contains	 the  FIPS  204	 secret	 key  sk  without   any	  ASN.1
	       encapsulation.  If the "bare-priv" format is not included in the
	       list, this format will not be recognised on input.

       "ml-dsa.output_formats" (OSSL_PKEY_PARAM_ML_DSA_OUTPUT_FORMATS) <UTF8
       string>
	   Ordered  list  of  enabled  private	key output formats when writing
	   PKCS#8 files.  List elements are  separated	by  commas,  spaces  or
	   tabs.   The	list  of  enabled  formats  can	 be  specified	in  the
	   configuration file, as seen in the "EXAMPLES" section below, or  the
	   via the -provparam command-line option.

	   This	  supports   the   same	 set  of  formats  as  described  under
	   "ml-dsa.input_formats" above.   The	order  in  which  elements  are
	   listed  is important, the selected format will be the first one that
	   is possible to output.  If the key seed is known, the  first	 listed
	   format  will	 be  selected.	If the key seed is not known, the first
	   format that omits the seed will be selected.	 The default  order  is
	   equivalent  to  "seed-priv"	first and "priv-only" second, with both
	   seed and key output when the seed is available,  and	 just  the  key
	   otherwise.	If  "seed-only"	 is listed first, then the seed will be
	   output without the key when available,  otherwise  the  output  will
	   have	 just  the  key.  If "priv-only" is listed first, then just the
	   key is output regardless of whether the seed is present.  The legacy
	   "oqskeypair",  "bare-seed"  and  "bare-priv"	 formats  can  also  be
	   output, by listing those first.

CONFORMING TO
       FIPS 204

EXAMPLES
       An EVP_PKEY context can be obtained by calling:

	   EVP_PKEY_CTX *pctx =
	       EVP_PKEY_CTX_new_from_name(NULL, "ML-DSA-44", NULL);

       An ML-DSA-44 key can be generated like this:

	   pkey = EVP_PKEY_Q_keygen(NULL, NULL, "ML-DSA-44");

       The key pair components can be extracted from a key by calling:

	   /* Sizes large enough for ML-DSA-87 */
	   uint8_t pub[2592], priv[4896], seed[32]:
	   size_t priv_len, pub_len, seed_len;

	   EVP_PKEY_get_octet_string_param(pkey, OSSL_PKEY_PARAM_ML_DSA_SEED,
					   seed, sizeof(seed), &seed_len);
	   EVP_PKEY_get_octet_string_param(pkey, OSSL_PKEY_PARAM_PRIV_KEY,
					   priv, sizeof(priv), &priv_len);
	   EVP_PKEY_get_octet_string_param(pkey, OSSL_PKEY_PARAM_PUB_KEY,
					   pub, sizeof(pub), &pub_len));

       An  ML-DSA  private  key in seed format can be converted to a key in the
       FIPS 204 sk format by running:

	   $ openssl pkey -provparam ml-dsa.retain_seed=no \
	       -in seed-only.pem -out priv-only.pem

       To generate an, e.g., ML-DSA-65 key, in FIPS 204 sk format, you can run:

	   $ openssl genpkey -provparam ml-dsa.retain_seed=no \
	       -algorithm ml-dsa-65 -out priv-only.pem

       If you have a PKCS#8 file with both a seed and  a  key,	and  prefer  to
       import the companion key rather than the seed, you can run:

	   $ openssl pkey -provparam ml-dsa.prefer_seed=no \
	       -in seed-priv.pem -out priv-only.pem

       In the openssl.cnf file, this looks like:

	   openssl_conf = openssl_init

	   [openssl_init]
	   providers = providers_sect

	   # Can be referenced in one or more provider sections
	   [ml_dsa_sect]
	   prefer_seed = yes
	   retain_seed = yes
	   # OQS legacy formats disabled
	   input_formats = seed-priv, seed-only, priv-only
	   # Output either the seed alone, or else the key alone
	   output_formats = seed-only, priv-only

	   [providers_sect]
	   default = default_sect
	   # Or perhaps just: base = default_sect
	   base = base_sect

	   [default_sect]
	   ml-dsa = ml_dsa_sect

	   [base_sect]
	   ml-dsa = ml_dsa_sect

SEE ALSO
       EVP_KEYMGMT(3),		   EVP_PKEY(3),		   provider-keymgmt(7),
       EVP_PKEY_get_raw_private_key(3),		EVP_PKEY_get_raw_public_key(3),
       EVP_PKEY_get1_encoded_public_key(3),
       OSSL_PROVIDER_add_conf_parameter(3),		   provider-keymgmt(7),
       EVP_SIGNATURE-ML-DSA(7)

HISTORY
       This functionality was added in OpenSSL 3.5.

COPYRIGHT
       Copyright 2025 The OpenSSL Project Authors. All Rights Reserved.

       Licensed under the Apache License 2.0 (the "License").  You may not  use
       this  file except in compliance with the License.  You can obtain a copy
       in   the	  file	 LICENSE   in	the   source   distribution    or    at
       <https://www.openssl.org/source/license.html>.

3.5.7				   2026-06-09		  EVP_PKEY-ML-DSA(7SSL)