docs: Added All FreeBSD Manuals

1 files changed, 352 insertions, 0 deletions

diff --git a/static/freebsd/man7/EVP_PKEY-ML-DSA.7 b/static/freebsd/man7/EVP_PKEY-ML-DSA.7
new file mode 100644
index 00000000..e723fff2
--- /dev/null
+++ b/static/freebsd/man7/EVP_PKEY-ML-DSA.7
@@ -0,0 +1,352 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
+.\"
+.\" 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
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    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 >0, 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
+.\"
+.\" Required to disable full justification in groff 1.23.0.
+.if n .ds AD l
+.\" ========================================================================
+.\"
+.IX Title "EVP_PKEY-ML-DSA 7ossl"
+.TH EVP_PKEY-ML-DSA 7ossl 2026-04-07 3.5.6 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 \fBML\-DSA\-44\fR, \fBML\-DSA\-65\fR and \fBML\-DSA\-87\fR. 
+The key types \fBEVP_PKEY_ML_DSA_44\fR, \fBEVP_PKEY_ML_DSA_65\fR and
+\&\fBEVP_PKEY_ML_DSA_87\fR are implemented in OpenSSL\*(Aqs default and FIPS 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 \fBML\-DSA\-44\fR, \fBML\-DSA\-65\fR
+and \fBML\-DSA\-87\fR respectively, which correspond to security strengths of
+128, 192 and 256 respectively.
+.SS "Keygen Parameters"
+.IX Subsection "Keygen Parameters"
+.IP """seed"" (\fBOSSL_PKEY_PARAM_ML_DSA_SEED\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 DRBG.
+.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 "Provider configuration parameters" 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 FIPS 204 \f(CW\*(C`sk\*(C'\fR format.
+.IP """properties"" (\fBOSSL_PKEY_PARAM_PROPERTIES\fR) <UTF8 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 \fBEVP_PKEY_CTX_set_params\fR\|(3) after calling \fBEVP_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
+"Common Information Parameters" in \fBprovider\-keymgmt\fR\|(7), the implementation of
+these key types support the parameters listed below.
+These are gettable using
+\&\fBEVP_PKEY_get_octet_string_param\fR\|(3) or \fBEVP_PKEY_get_params\fR\|(3).
+They can be initialised via \fBEVP_PKEY_fromdata\fR\|(3), and are returned by
+\&\fBEVP_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.
+.IP """pub"" (\fBOSSL_PKEY_PARAM_PUB_KEY\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 \fBML\-DSA\-44\fR, \fBML\-DSA\-65\fR or \fBML\-DSA\-87\fR.
+.IP """priv"" (\fBOSSL_PKEY_PARAM_PRIV_KEY\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 \fBML\-DSA\-44\fR, \fBML\-DSA\-65\fR or \fBML\-DSA\-87\fR.
+.SS "Provider configuration parameters"
+.IX Subsection "Provider configuration parameters"
+See the description of the \fB\-provparam\fR option in \fBopenssl\fR\|(1) to learn
+how to set provider configuration parameters in the command line tools.
+See \fBOSSL_PROVIDER_add_conf_parameter\fR\|(3) to learn how to set provider
+configuration options programmatically.
+.ie n .IP """ml\-dsa.retain_seed"" (\fBOSSL_PKEY_PARAM_ML_DSA_RETAIN_SEED\fR) <UTF8 string>" 4
+.el .IP "\f(CWml\-dsa.retain_seed\fR (\fBOSSL_PKEY_PARAM_ML_DSA_RETAIN_SEED\fR) <UTF8 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
+\&\fBOSSL_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 FIPS 204 \f(CW\*(C`sk\*(C'\fR key.
+.ie n .IP """ml\-dsa.prefer_seed"" (\fBOSSL_PKEY_PARAM_ML_DSA_PREFER_SEED\fR) <UTF8 string>" 4
+.el .IP "\f(CWml\-dsa.prefer_seed\fR (\fBOSSL_PKEY_PARAM_ML_DSA_PREFER_SEED\fR) <UTF8 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 FIPS 204 \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 \fBOSSL_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"" (\fBOSSL_PKEY_PARAM_ML_DSA_INPUT_FORMATS\fR) <UTF8 string>" 4
+.el .IP "\f(CWml\-dsa.input_formats\fR (\fBOSSL_PKEY_PARAM_ML_DSA_INPUT_FORMATS\fR) <UTF8 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 "EXAMPLES" section below, or the via the \fB\-provparam\fR command\-line
+option (see also \fBOSSL_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 FIPS 204 32\-byte
+\&\fBξ\fR seed and the secret key \fBsk\fR are present in the private key as part of
+the DER encoding of the ASN.1 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 FIPS 204
+\&\fBξ\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 FIPS 204
+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 DER
+encoding of an octet string containing the concatenaton of the FIPS 204 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 FIPS 204 seed \fBξ\fR without any ASN.1 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 FIPS 204 secret key \fBsk\fR without any ASN.1 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"" (\fBOSSL_PKEY_PARAM_ML_DSA_OUTPUT_FORMATS\fR) <UTF8 string>" 4
+.el .IP "\f(CWml\-dsa.output_formats\fR (\fBOSSL_PKEY_PARAM_ML_DSA_OUTPUT_FORMATS\fR) <UTF8 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 "EXAMPLES" 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 "FIPS 204" 4
+.IX Item "FIPS 204"
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+An \fBEVP_PKEY\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 \fBML\-DSA\-44\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 FIPS
+204 \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., \fBML\-DSA\-65\fR key, in FIPS 204 \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"
+\&\fBEVP_KEYMGMT\fR\|(3),
+\&\fBEVP_PKEY\fR\|(3),
+\&\fBprovider\-keymgmt\fR\|(7),
+\&\fBEVP_PKEY_get_raw_private_key\fR\|(3),
+\&\fBEVP_PKEY_get_raw_public_key\fR\|(3),
+\&\fBEVP_PKEY_get1_encoded_public_key\fR\|(3),
+\&\fBOSSL_PROVIDER_add_conf_parameter\fR\|(3),
+\&\fBprovider\-keymgmt\fR\|(7),
+\&\fBEVP_SIGNATURE\-ML\-DSA\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 "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>.