AP05/openssl/share/man/man7/EVP_PKEY-ML-DSA.7ossl

.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "EVP_PKEY-ML-DSA 7ossl"
.TH EVP_PKEY-ML-DSA 7ossl "2025-04-23" "3.5.1-dev" "OpenSSL"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
ML-DSA implements the algorithms \fB\s-1ML\-DSA\-44\s0\fR, \fB\s-1ML\-DSA\-65\s0\fR and \fB\s-1ML\-DSA\-87\s0\fR. 
The key types \fB\s-1EVP_PKEY_ML_DSA_44\s0\fR, \fB\s-1EVP_PKEY_ML_DSA_65\s0\fR and
\&\fB\s-1EVP_PKEY_ML_DSA_87\s0\fR are implemented in OpenSSL's default and \s-1FIPS\s0 providers.
These implementations support the associated key, containing the public key \fIpub\fR
and the private key \fIpriv\fR.
.PP
Each of the different key types has an associated security category.
This value is one of 2, 3 or 5 for key types \fB\s-1ML\-DSA\-44\s0\fR, \fB\s-1ML\-DSA\-65\s0\fR
and \fB\s-1ML\-DSA\-87\s0\fR respectively, which correspond to security strengths of
128, 192 and 256 repsectively.
.SS "Keygen Parameters"
.IX Subsection "Keygen Parameters"
.ie n .IP """seed"" (\fB\s-1OSSL_PKEY_PARAM_ML_DSA_SEED\s0\fR) <octet string>" 4
.el .IP "``seed'' (\fB\s-1OSSL_PKEY_PARAM_ML_DSA_SEED\s0\fR) <octet string>" 4
.IX Item "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 \s-1DRBG. \s0
.Sp
Generated keys default to retaining the seed used.
The seed is also by default retained when keys are loaded from \fBPKCS#8\fR 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 \*(L"Provider configuration parameters\*(R" below for related controls.
.Sp
When the seed is retained, it is also available as a \fBgettable\fR parameter,
and private key output to \fBPKCS#8\fR files will by default include the seed.
When the seed was not initially known, or was not retained, \fBPKCS#8\fR private
key files will contain only the private key in \s-1FIPS 204 \s0\f(CW\*(C`sk\*(C'\fR format.
.ie n .IP """properties"" (\fB\s-1OSSL_PKEY_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4
.el .IP "``properties'' (\fB\s-1OSSL_PKEY_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4
.IX Item "properties (OSSL_PKEY_PARAM_PROPERTIES) <UTF8 string>"
Sets properties to be used when fetching algorithm implementations used for
ML-DSA hashing operations.
.PP
Use \fIEVP_PKEY_CTX_set_params\fR\|(3) after calling \fIEVP_PKEY_keygen_init\fR\|(3).
.SS "Common ML-DSA parameters"
.IX Subsection "Common ML-DSA parameters"
In addition to the common parameters that all keytypes should support (see
\&\*(L"Common Information Parameters\*(R" in \fIprovider\-keymgmt\fR\|(7), the implementation of
these key types support the parameters listed below.
These are gettable using
\&\fIEVP_PKEY_get_octet_string_param\fR\|(3) or \fIEVP_PKEY_get_params\fR\|(3).
They can be initialised via \fIEVP_PKEY_fromdata\fR\|(3), and are returned by
\&\fIEVP_PKEY_todata\fR\|(3) given a suitable \fIselection\fR.
Once a public or private key is configured, it can no longer be modified,
nor can another key component be added.
.ie n .IP """pub"" (\fB\s-1OSSL_PKEY_PARAM_PUB_KEY\s0\fR) <octet string>" 4
.el .IP "``pub'' (\fB\s-1OSSL_PKEY_PARAM_PUB_KEY\s0\fR) <octet string>" 4
.IX Item "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 \fB\s-1ML\-DSA\-44\s0\fR, \fB\s-1ML\-DSA\-65\s0\fR or \fB\s-1ML\-DSA\-87\s0\fR.
.ie n .IP """priv"" (\fB\s-1OSSL_PKEY_PARAM_PRIV_KEY\s0\fR) <octet string>" 4
.el .IP "``priv'' (\fB\s-1OSSL_PKEY_PARAM_PRIV_KEY\s0\fR) <octet string>" 4
.IX Item "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 \fB\s-1ML\-DSA\-44\s0\fR, \fB\s-1ML\-DSA\-65\s0\fR or \fB\s-1ML\-DSA\-87\s0\fR.
.SS "Provider configuration parameters"
.IX Subsection "Provider configuration parameters"
See the description of the \fB\-provparam\fR option in \fIopenssl\fR\|(1) to learn
how to set provider configuration parameters in the command line tools.
See \fIOSSL_PROVIDER_add_conf_parameter\fR\|(3) to learn how to set provider
configuration options programmatically.
.ie n .IP """ml\-dsa.retain_seed"" (\fB\s-1OSSL_PKEY_PARAM_ML_DSA_RETAIN_SEED\s0\fR) <\s-1UTF8\s0 string>" 4
.el .IP "\f(CWml\-dsa.retain_seed\fR (\fB\s-1OSSL_PKEY_PARAM_ML_DSA_RETAIN_SEED\s0\fR) <\s-1UTF8\s0 string>" 4
.IX Item "ml-dsa.retain_seed (OSSL_PKEY_PARAM_ML_DSA_RETAIN_SEED) <UTF8 string>"
When set to a string representing a false boolean value (see
\&\fIOSSL_PROVIDER_conf_get_bool\fR\|(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 \s-1FIPS 204 \s0\f(CW\*(C`sk\*(C'\fR key.
.ie n .IP """ml\-dsa.prefer_seed"" (\fB\s-1OSSL_PKEY_PARAM_ML_DSA_PREFER_SEED\s0\fR) <\s-1UTF8\s0 string>" 4
.el .IP "\f(CWml\-dsa.prefer_seed\fR (\fB\s-1OSSL_PKEY_PARAM_ML_DSA_PREFER_SEED\s0\fR) <\s-1UTF8\s0 string>" 4
.IX Item "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 \s-1FIPS 204 \s0\f(CW\*(C`sk\*(C'\fR
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 \fIOSSL_PROVIDER_conf_get_bool\fR\|(3)), the seed is ignored
(neither used to regenerate the key, nor retained), and the companion key is
used instead.
.ie n .IP """ml\-dsa.input_formats"" (\fB\s-1OSSL_PKEY_PARAM_ML_DSA_INPUT_FORMATS\s0\fR) <\s-1UTF8\s0 string>" 4
.el .IP "\f(CWml\-dsa.input_formats\fR (\fB\s-1OSSL_PKEY_PARAM_ML_DSA_INPUT_FORMATS\s0\fR) <\s-1UTF8\s0 string>" 4
.IX Item "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 \*(L"\s-1EXAMPLES\*(R"\s0 section below, or the via the \fB\-provparam\fR command-line
option (see also \fIOSSL_PROVIDER_add_conf_parameter\fR\|(3)).
.Sp
Values specified on the command-line override any configuration file settings.
By default all the supported formats are enabled.
The supported formats are:
.RS 4
.ie n .IP """seed\-priv"":" 4
.el .IP "\f(CWseed\-priv\fR:" 4
.IX Item "seed-priv:"
This format represents \fBPKCS#8\fR objects in which both the \s-1FIPS 204\s0 32\-byte
\&\fBX\fR seed and the secret key \fBsk\fR are present in the private key as part of
the \s-1DER\s0 encoding of the \s-1ASN.1\s0 sequence:
.Sp
.Vb 6
\&    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)) } }
.Ve
.Sp
If the \f(CW\*(C`seed\-priv\*(C'\fR format is not included in the list, this format will not be
recognised on input.
.ie n .IP """seed\-only"":" 4
.el .IP "\f(CWseed\-only\fR:" 4
.IX Item "seed-only:"
This format represents \fBPKCS#8\fR objects in which only the 32\-byte \s-1FIPS 204
\&\s0\fBX\fR seed is present in the above sequence.
If the \f(CW\*(C`seed\-only\*(C'\fR format is not included in the list, this format will not be
recognised on input.
.ie n .IP """priv\-only"":" 4
.el .IP "\f(CWpriv\-only\fR:" 4
.IX Item "priv-only:"
This format represents \fBPKCS#8\fR objects in which only the \s-1FIPS 204\s0
private key \fBsk\fR is present in the above sequence.
If the \f(CW\*(C`priv\-only\*(C'\fR format is not included in the list, this format will not be
recognised on input.
.ie n .IP """oqskeypair"":" 4
.el .IP "\f(CWoqskeypair\fR:" 4
.IX Item "oqskeypair:"
This format represents \fBPKCS#8\fR objects in which the private key is a \s-1DER\s0
encoding of an octet string containing the concatenaton of the \s-1FIPS 204\s0 private
key \fBsk\fR and the public key \fBpk\fR.
This encoding is used in some builds of the \f(CW\*(C`oqsprovider\*(C'\fR.
If the \f(CW\*(C`oqskeypair\*(C'\fR format is not included in the list, this format will not be
recognised on input.
.ie n .IP """bare\-seed"":" 4
.el .IP "\f(CWbare\-seed\fR:" 4
.IX Item "bare-seed:"
This format represents \fBPKCS#8\fR objects in which the private key contains
the 32\-byte \s-1FIPS 204\s0 seed \fBX\fR without any \s-1ASN.1\s0 encapsulation.
If the \f(CW\*(C`bare\-seed\*(C'\fR format is not included in the list, this format will not be
recognised on input.
.ie n .IP """bare\-priv"":" 4
.el .IP "\f(CWbare\-priv\fR:" 4
.IX Item "bare-priv:"
This format represents \fBPKCS#8\fR objects in which the private key contains
the \s-1FIPS 204\s0 secret key \fBsk\fR without any \s-1ASN.1\s0 encapsulation.
If the \f(CW\*(C`bare\-priv\*(C'\fR format is not included in the list, this format will not be
recognised on input.
.RE
.RS 4
.RE
.ie n .IP """ml\-dsa.output_formats"" (\fB\s-1OSSL_PKEY_PARAM_ML_DSA_OUTPUT_FORMATS\s0\fR) <\s-1UTF8\s0 string>" 4
.el .IP "\f(CWml\-dsa.output_formats\fR (\fB\s-1OSSL_PKEY_PARAM_ML_DSA_OUTPUT_FORMATS\s0\fR) <\s-1UTF8\s0 string>" 4
.IX Item "ml-dsa.output_formats (OSSL_PKEY_PARAM_ML_DSA_OUTPUT_FORMATS) <UTF8 string>"
Ordered list of enabled private key output formats when writing \fBPKCS#8\fR 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 \*(L"\s-1EXAMPLES\*(R"\s0 section below, or the via the \fB\-provparam\fR command-line
option.
.Sp
This supports the same set of formats as described under \f(CW\*(C`ml\-dsa.input_formats\*(C'\fR
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 \f(CW\*(C`seed\-priv\*(C'\fR first and \f(CW\*(C`priv\-only\*(C'\fR second, with
both seed and key output when the seed is available, and just the
key otherwise.
If \f(CW\*(C`seed\-only\*(C'\fR is listed first, then the seed will be output without the key
when available, otherwise the output will have just the key.
If \f(CW\*(C`priv\-only\*(C'\fR is listed first, then just the key is output regardless of
whether the seed is present.
The legacy \f(CW\*(C`oqskeypair\*(C'\fR, \f(CW\*(C`bare\-seed\*(C'\fR and \f(CW\*(C`bare\-priv\*(C'\fR formats can also be
output, by listing those first.
.SH "CONFORMING TO"
.IX Header "CONFORMING TO"
.IP "\s-1FIPS 204\s0" 4
.IX Item "FIPS 204"
.SH "EXAMPLES"
.IX Header "EXAMPLES"
An \fB\s-1EVP_PKEY\s0\fR context can be obtained by calling:
.PP
.Vb 2
\&    EVP_PKEY_CTX *pctx =
\&        EVP_PKEY_CTX_new_from_name(NULL, "ML\-DSA\-44", NULL);
.Ve
.PP
An \fB\s-1ML\-DSA\-44\s0\fR key can be generated like this:
.PP
.Vb 1
\&    pkey = EVP_PKEY_Q_keygen(NULL, NULL, "ML\-DSA\-44");
.Ve
.PP
The key pair components can be extracted from a key by calling:
.PP
.Vb 3
\&    /* 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));
.Ve
.PP
An \fBML-DSA\fR private key in seed format can be converted to a key in the \s-1FIPS
204 \s0\fBsk\fR format by running:
.PP
.Vb 2
\&    $ openssl pkey \-provparam ml\-dsa.retain_seed=no \e
\&        \-in seed\-only.pem \-out priv\-only.pem
.Ve
.PP
To generate an, e.g., \fB\s-1ML\-DSA\-65\s0\fR key, in \s-1FIPS 204 \s0\fBsk\fR format, you can run:
.PP
.Vb 2
\&    $ openssl genpkey \-provparam ml\-dsa.retain_seed=no \e
\&        \-algorithm ml\-dsa\-65 \-out priv\-only.pem
.Ve
.PP
If you have a \fBPKCS#8\fR file with both a seed and a key, and prefer to import the
companion key rather than the seed, you can run:
.PP
.Vb 2
\&    $ openssl pkey \-provparam ml\-dsa.prefer_seed=no \e
\&        \-in seed\-priv.pem \-out priv\-only.pem
.Ve
.PP
In the \fBopenssl.cnf\fR file, this looks like:
.PP
.Vb 1
\&    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
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1\fIEVP_KEYMGMT\s0\fR\|(3),
\&\s-1\fIEVP_PKEY\s0\fR\|(3),
\&\fIprovider\-keymgmt\fR\|(7),
\&\fIEVP_PKEY_get_raw_private_key\fR\|(3),
\&\fIEVP_PKEY_get_raw_public_key\fR\|(3),
\&\fIEVP_PKEY_get1_encoded_public_key\fR\|(3),
\&\fIOSSL_PROVIDER_add_conf_parameter\fR\|(3),
\&\fIprovider\-keymgmt\fR\|(7),
\&\s-1\fIEVP_SIGNATURE\-ML\-DSA\s0\fR\|(7)
.SH "HISTORY"
.IX Header "HISTORY"
This functionality was added in OpenSSL 3.5.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2025 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (the \*(L"License\*(R").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.