From fc22b3d6507c6745911b9dfcc68f1e665ae13dbc Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:43:11 +0200 Subject: Adding upstream version 4.22.0. Signed-off-by: Daniel Baumann --- upstream/archlinux/man7/EVP_PKEY-FFC.7ssl | 243 ++++++++++++++++++++++++++++++ 1 file changed, 243 insertions(+) create mode 100644 upstream/archlinux/man7/EVP_PKEY-FFC.7ssl (limited to 'upstream/archlinux/man7/EVP_PKEY-FFC.7ssl') diff --git a/upstream/archlinux/man7/EVP_PKEY-FFC.7ssl b/upstream/archlinux/man7/EVP_PKEY-FFC.7ssl new file mode 100644 index 00000000..410315b3 --- /dev/null +++ b/upstream/archlinux/man7/EVP_PKEY-FFC.7ssl @@ -0,0 +1,243 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" 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 +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY-FFC 7ssl" +.TH EVP_PKEY-FFC 7ssl 2024-01-30 3.2.1 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\-FFC \- EVP_PKEY DSA and DH/DHX shared FFC parameters. +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Finite field cryptography (FFC) is a method of implementing discrete logarithm +cryptography using finite field mathematics. DSA is an example of FFC and +Diffie-Hellman key establishment algorithms specified in SP800\-56A can also be +implemented as FFC. +.PP +The \fBDSA\fR, \fBDH\fR and \fBDHX\fR keytypes are implemented in OpenSSL's default and +FIPS providers. +The implementations support the basic DSA, DH and DHX keys, containing the public +and private keys \fIpub\fR and \fIpriv\fR as well as the three main domain parameters +\&\fIp\fR, \fIq\fR and \fIg\fR. +.PP +For \fBDSA\fR (and \fBDH\fR that is not a named group) the FIPS186\-4 standard +specifies that the values used for FFC parameter generation are also required +for parameter validation. +This means that optional FFC domain parameter values for \fIseed\fR, \fIpcounter\fR +and \fIgindex\fR may need to be stored for validation purposes. +For \fBDH\fR the \fIseed\fR and \fIpcounter\fR can be stored in ASN1 data +(but the \fIgindex\fR is not). For \fBDSA\fR however, these fields are not stored in +the ASN1 data so they need to be stored externally if validation is required. +.PP +The \fBDH\fR key type uses PKCS#3 format which saves p and g, but not the 'q' value. +The \fBDHX\fR key type uses X9.42 format which saves the value of 'q' and this +must be used for FIPS186\-4. +.SS "FFC parameters" +.IX Subsection "FFC parameters" +In addition to the common parameters that all keytypes should support (see +"Common parameters" in \fBprovider\-keymgmt\fR\|(7)), the \fBDSA\fR, \fBDH\fR and \fBDHX\fR keytype +implementations support the following. +.IP """pub"" (\fBOSSL_PKEY_PARAM_PUB_KEY\fR) " 4 +.IX Item """pub"" (OSSL_PKEY_PARAM_PUB_KEY) " +The public key value. +.IP """priv"" (\fBOSSL_PKEY_PARAM_PRIV_KEY\fR) " 4 +.IX Item """priv"" (OSSL_PKEY_PARAM_PRIV_KEY) " +The private key value. +.SS "FFC DSA, DH and DHX domain parameters" +.IX Subsection "FFC DSA, DH and DHX domain parameters" +.IP """p"" (\fBOSSL_PKEY_PARAM_FFC_P\fR) " 4 +.IX Item """p"" (OSSL_PKEY_PARAM_FFC_P) " +A DSA or Diffie-Hellman prime "p" value. +.IP """g"" (\fBOSSL_PKEY_PARAM_FFC_G\fR) " 4 +.IX Item """g"" (OSSL_PKEY_PARAM_FFC_G) " +A DSA or Diffie-Hellman generator "g" value. +.SS "FFC DSA and DHX domain parameters" +.IX Subsection "FFC DSA and DHX domain parameters" +.IP """q"" (\fBOSSL_PKEY_PARAM_FFC_Q\fR) " 4 +.IX Item """q"" (OSSL_PKEY_PARAM_FFC_Q) " +A DSA or Diffie-Hellman prime "q" value. +.IP """seed"" (\fBOSSL_PKEY_PARAM_FFC_SEED\fR) " 4 +.IX Item """seed"" (OSSL_PKEY_PARAM_FFC_SEED) " +An optional domain parameter \fIseed\fR value used during generation and validation +of \fIp\fR, \fIq\fR and canonical \fIg\fR. +For validation this needs to set the \fIseed\fR that was produced during generation. +.IP """gindex"" (\fBOSSL_PKEY_PARAM_FFC_GINDEX\fR) " 4 +.IX Item """gindex"" (OSSL_PKEY_PARAM_FFC_GINDEX) " +Sets the index to use for canonical generation and verification of the generator +\&\fIg\fR. +Set this to a positive value from 0..FF to use this mode. This \fIgindex\fR can +then be reused during key validation to verify the value of \fIg\fR. If this value +is not set or is \-1 then unverifiable generation of the generator \fIg\fR will be +used. +.IP """pcounter"" (\fBOSSL_PKEY_PARAM_FFC_PCOUNTER\fR) " 4 +.IX Item """pcounter"" (OSSL_PKEY_PARAM_FFC_PCOUNTER) " +An optional domain parameter \fIcounter\fR value that is output during generation +of \fIp\fR. This value must be saved if domain parameter validation is required. +.IP """hindex"" (\fBOSSL_PKEY_PARAM_FFC_H\fR) " 4 +.IX Item """hindex"" (OSSL_PKEY_PARAM_FFC_H) " +For unverifiable generation of the generator \fIg\fR this value is output during +generation of \fIg\fR. Its value is the first integer larger than one that +satisfies g = h^j mod p (where g != 1 and "j" is the cofactor). +.IP """j"" (\fBOSSL_PKEY_PARAM_FFC_COFACTOR\fR) " 4 +.IX Item """j"" (OSSL_PKEY_PARAM_FFC_COFACTOR) " +An optional informational cofactor parameter that should equal to (p \- 1) / q. +.IP """validate-pq"" (\fBOSSL_PKEY_PARAM_FFC_VALIDATE_PQ\fR) " 4 +.IX Item """validate-pq"" (OSSL_PKEY_PARAM_FFC_VALIDATE_PQ) " +.PD 0 +.IP """validate-g"" (\fBOSSL_PKEY_PARAM_FFC_VALIDATE_G\fR) " 4 +.IX Item """validate-g"" (OSSL_PKEY_PARAM_FFC_VALIDATE_G) " +.PD +These boolean values are used during FIPS186\-4 or FIPS186\-2 key validation checks +(See \fBEVP_PKEY_param_check\fR\|(3)) to select validation options. By default +\&\fIvalidate-pq\fR and \fIvalidate-g\fR are both set to 1 to check that p,q and g are +valid. Either of these may be set to 0 to skip a test, which is mainly useful +for testing purposes. +.IP """validate-legacy"" (\fBOSSL_PKEY_PARAM_FFC_VALIDATE_LEGACY\fR) " 4 +.IX Item """validate-legacy"" (OSSL_PKEY_PARAM_FFC_VALIDATE_LEGACY) " +This boolean value is used during key validation checks +(See \fBEVP_PKEY_param_check\fR\|(3)) to select the validation type. The default +value of 0 selects FIPS186\-4 validation. Setting this value to 1 selects +FIPS186\-2 validation. +.SS "FFC key generation parameters" +.IX Subsection "FFC key generation parameters" +The following key generation types are available for DSA and DHX algorithms: +.IP """type"" (\fBOSSL_PKEY_PARAM_FFC_TYPE\fR) " 4 +.IX Item """type"" (OSSL_PKEY_PARAM_FFC_TYPE) " +Sets the type of parameter generation. The shared valid values are: +.RS 4 +.IP """fips186_4""" 4 +.IX Item """fips186_4""" +The current standard. +.IP """fips186_2""" 4 +.IX Item """fips186_2""" +The old standard that should only be used for legacy purposes. +.IP """default""" 4 +.IX Item """default""" +This can choose one of "fips186_4" or "fips186_2" depending on other +parameters set for parameter generation. +.RE +.RS 4 +.RE +.IP """pbits"" (\fBOSSL_PKEY_PARAM_FFC_PBITS\fR) " 4 +.IX Item """pbits"" (OSSL_PKEY_PARAM_FFC_PBITS) " +Sets the size (in bits) of the prime 'p'. +.IP """qbits"" (\fBOSSL_PKEY_PARAM_FFC_QBITS\fR) " 4 +.IX Item """qbits"" (OSSL_PKEY_PARAM_FFC_QBITS) " +Sets the size (in bits) of the prime 'q'. +.Sp +For "fips186_4" this can be either 224 or 256. +For "fips186_2" this has a size of 160. +.IP """digest"" (\fBOSSL_PKEY_PARAM_FFC_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_PKEY_PARAM_FFC_DIGEST) " +Sets the Digest algorithm to be used as part of the Key Generation Function +associated with the given Key Generation \fIctx\fR. +This must also be set for key validation. +.IP """properties"" (\fBOSSL_PKEY_PARAM_FFC_DIGEST_PROPS\fR) " 4 +.IX Item """properties"" (OSSL_PKEY_PARAM_FFC_DIGEST_PROPS) " +Sets properties to be used upon look up of the implementation for the selected +Digest algorithm for the Key Generation Function associated with the given key +generation \fIctx\fR. This may also be set for key validation. +.IP """seed"" (\fBOSSL_PKEY_PARAM_FFC_SEED\fR) " 4 +.IX Item """seed"" (OSSL_PKEY_PARAM_FFC_SEED) " +For "fips186_4" or "fips186_2" generation this sets the \fIseed\fR data to use +instead of generating a random seed internally. This should be used for +testing purposes only. This will either produce fixed values for the generated +parameters OR it will fail if the seed did not generate valid primes. +.IP """gindex"" (\fBOSSL_PKEY_PARAM_FFC_GINDEX\fR) " 4 +.IX Item """gindex"" (OSSL_PKEY_PARAM_FFC_GINDEX) " +.PD 0 +.IP """pcounter"" (\fBOSSL_PKEY_PARAM_FFC_PCOUNTER\fR) " 4 +.IX Item """pcounter"" (OSSL_PKEY_PARAM_FFC_PCOUNTER) " +.IP """hindex"" (\fBOSSL_PKEY_PARAM_FFC_H\fR) " 4 +.IX Item """hindex"" (OSSL_PKEY_PARAM_FFC_H) " +.PD +These types are described above. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +The following sections of SP800\-56Ar3: +.IP "5.5.1.1 FFC Domain Parameter Selection/Generation" 4 +.IX Item "5.5.1.1 FFC Domain Parameter Selection/Generation" +.PP +The following sections of FIPS186\-4: +.IP "A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function." 4 +.IX Item "A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function." +.PD 0 +.IP "A.2.3 Generation of canonical generator g." 4 +.IX Item "A.2.3 Generation of canonical generator g." +.IP "A.2.1 Unverifiable Generation of the Generator g." 4 +.IX Item "A.2.1 Unverifiable Generation of the Generator g." +.PD +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY\-DSA\fR\|(7), +\&\fBEVP_PKEY\-DH\fR\|(7), +\&\fBEVP_SIGNATURE\-DSA\fR\|(7), +\&\fBEVP_KEYEXCH\-DH\fR\|(7) +\&\fBEVP_KEYMGMT\fR\|(3), +\&\fBEVP_PKEY\fR\|(3), +\&\fBprovider\-keymgmt\fR\|(7), +\&\fBOSSL_PROVIDER\-default\fR\|(7), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7), +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 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 +. -- cgit v1.2.3