diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man7')
127 files changed, 31435 insertions, 1030 deletions
diff --git a/secure/lib/libcrypto/man/man7/EVP_ASYM_CIPHER-RSA.7 b/secure/lib/libcrypto/man/man7/EVP_ASYM_CIPHER-RSA.7 new file mode 100644 index 000000000000..9ea289bcedf9 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_ASYM_CIPHER-RSA.7 @@ -0,0 +1,231 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_ASYM_CIPHER-RSA 7ossl" +.TH EVP_ASYM_CIPHER-RSA 7ossl "2023-09-19" "3.0.11" "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_ASYM_CIPHER\-RSA +\&\- RSA Asymmetric Cipher algorithm support +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Asymmetric Cipher support for the \fB\s-1RSA\s0\fR key type. +.SS "\s-1RSA\s0 Asymmetric Cipher parameters" +.IX Subsection "RSA Asymmetric Cipher parameters" +.ie n .IP """pad-mode"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_PAD_MODE\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``pad-mode'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_PAD_MODE\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "pad-mode (OSSL_ASYM_CIPHER_PARAM_PAD_MODE) <UTF8 string>" +The default provider understands these \s-1RSA\s0 padding modes in string form: +.RS 4 +.ie n .IP """none"" (\fB\s-1OSSL_PKEY_RSA_PAD_MODE_NONE\s0\fR)" 4 +.el .IP "``none'' (\fB\s-1OSSL_PKEY_RSA_PAD_MODE_NONE\s0\fR)" 4 +.IX Item "none (OSSL_PKEY_RSA_PAD_MODE_NONE)" +.PD 0 +.ie n .IP """oaep"" (\fB\s-1OSSL_PKEY_RSA_PAD_MODE_OAEP\s0\fR)" 4 +.el .IP "``oaep'' (\fB\s-1OSSL_PKEY_RSA_PAD_MODE_OAEP\s0\fR)" 4 +.IX Item "oaep (OSSL_PKEY_RSA_PAD_MODE_OAEP)" +.ie n .IP """pkcs1"" (\fB\s-1OSSL_PKEY_RSA_PAD_MODE_PKCSV15\s0\fR)" 4 +.el .IP "``pkcs1'' (\fB\s-1OSSL_PKEY_RSA_PAD_MODE_PKCSV15\s0\fR)" 4 +.IX Item "pkcs1 (OSSL_PKEY_RSA_PAD_MODE_PKCSV15)" +.ie n .IP """x931"" (\fB\s-1OSSL_PKEY_RSA_PAD_MODE_X931\s0\fR)" 4 +.el .IP "``x931'' (\fB\s-1OSSL_PKEY_RSA_PAD_MODE_X931\s0\fR)" 4 +.IX Item "x931 (OSSL_PKEY_RSA_PAD_MODE_X931)" +.RE +.RS 4 +.RE +.ie n .IP """pad-mode"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_PAD_MODE\s0\fR) <integer>" 4 +.el .IP "``pad-mode'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_PAD_MODE\s0\fR) <integer>" 4 +.IX Item "pad-mode (OSSL_ASYM_CIPHER_PARAM_PAD_MODE) <integer>" +.PD +The default provider understands these \s-1RSA\s0 padding modes in integer form: +.RS 4 +.IP "1 (\fB\s-1RSA_PKCS1_PADDING\s0\fR)" 4 +.IX Item "1 (RSA_PKCS1_PADDING)" +.PD 0 +.IP "3 (\fB\s-1RSA_NO_PADDING\s0\fR)" 4 +.IX Item "3 (RSA_NO_PADDING)" +.IP "4 (\fB\s-1RSA_PKCS1_OAEP_PADDING\s0\fR)" 4 +.IX Item "4 (RSA_PKCS1_OAEP_PADDING)" +.IP "5 (\fB\s-1RSA_X931_PADDING\s0\fR)" 4 +.IX Item "5 (RSA_X931_PADDING)" +.RE +.RS 4 +.PD +.Sp +See \fBEVP_PKEY_CTX_set_rsa_padding\fR\|(3) for further details. +.RE +.ie n .IP """digest"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST) <UTF8 string>" +.PD 0 +.ie n .IP """digest-props"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest-props'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest-props (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS) <UTF8 string>" +.ie n .IP """mgf1\-digest"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``mgf1\-digest'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "mgf1-digest (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST) <UTF8 string>" +.ie n .IP """mgf1\-digest\-props"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST_PROPS\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``mgf1\-digest\-props'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST_PROPS\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "mgf1-digest-props (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST_PROPS) <UTF8 string>" +.ie n .IP """oaep-label"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL\s0\fR) <octet string>" 4 +.el .IP "``oaep-label'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL\s0\fR) <octet string>" 4 +.IX Item "oaep-label (OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL) <octet string>" +.ie n .IP """tls-client-version"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION\s0\fR) <unsigned integer>" 4 +.el .IP "``tls-client-version'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION\s0\fR) <unsigned integer>" 4 +.IX Item "tls-client-version (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION) <unsigned integer>" +.PD +See \fB\s-1RSA_PKCS1_WITH_TLS_PADDING\s0\fR on the page \fBEVP_PKEY_CTX_set_rsa_padding\fR\|(3). +.ie n .IP """tls-negotiated-version"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION\s0\fR) <unsigned integer>" 4 +.el .IP "``tls-negotiated-version'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION\s0\fR) <unsigned integer>" 4 +.IX Item "tls-negotiated-version (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION) <unsigned integer>" +See \fB\s-1RSA_PKCS1_WITH_TLS_PADDING\s0\fR on the page \fBEVP_PKEY_CTX_set_rsa_padding\fR\|(3). +.Sp +See \*(L"Asymmetric Cipher Parameters\*(R" in \fBprovider\-asym_cipher\fR\|(7) for more information. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_PKEY\-RSA\s0\fR\|(7), +\&\s-1\fBEVP_PKEY\s0\fR\|(3), +\&\fBprovider\-asym_cipher\fR\|(7), +\&\fBprovider\-keymgmt\fR\|(7), +\&\fBOSSL_PROVIDER\-default\fR\|(7) +\&\s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2022 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_ASYM_CIPHER-SM2.7 b/secure/lib/libcrypto/man/man7/EVP_ASYM_CIPHER-SM2.7 new file mode 100644 index 000000000000..7f9dcdf94ade --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_ASYM_CIPHER-SM2.7 @@ -0,0 +1,170 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_ASYM_CIPHER-SM2 7ossl" +.TH EVP_ASYM_CIPHER-SM2 7ossl "2023-09-19" "3.0.11" "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_ASYM_CIPHER\-SM2 +\&\- SM2 Asymmetric Cipher algorithm support +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Asymmetric Cipher support for the \fB\s-1SM2\s0\fR key type. +.SS "\s-1SM2\s0 Asymmetric Cipher parameters" +.IX Subsection "SM2 Asymmetric Cipher parameters" +.ie n .IP """digest"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_ASYM_CIPHER_PARAM_DIGEST) <UTF8 string>" +.PD 0 +.ie n .IP """digest-props"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_DIGEST_PROPS\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest-props'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_DIGEST_PROPS\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest-props (OSSL_ASYM_CIPHER_PARAM_DIGEST_PROPS) <UTF8 string>" +.PD +See \*(L"Asymmetric Cipher Parameters\*(R" in \fBprovider\-asym_cipher\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_PKEY\-SM2\s0\fR\|(7), +\&\s-1\fBEVP_PKEY\s0\fR\|(3), +\&\fBprovider\-asym_cipher\fR\|(7), +\&\fBprovider\-keymgmt\fR\|(7), +\&\fBOSSL_PROVIDER\-default\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_CIPHER-AES.7 b/secure/lib/libcrypto/man/man7/EVP_CIPHER-AES.7 new file mode 100644 index 000000000000..a9730056ef87 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_CIPHER-AES.7 @@ -0,0 +1,208 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_CIPHER-AES 7ossl" +.TH EVP_CIPHER-AES 7ossl "2023-09-19" "3.0.11" "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_CIPHER\-AES \- The AES EVP_CIPHER implementations +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for \s-1AES\s0 symmetric encryption using the \fB\s-1EVP_CIPHER\s0\fR \s-1API.\s0 +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the \s-1FIPS\s0 provider as well as the +default provider: +.ie n .IP """\s-1AES\-128\-CBC"", ""AES\-192\-CBC""\s0 and ""\s-1AES\-256\-CBC""\s0" 4 +.el .IP "``\s-1AES\-128\-CBC'', ``AES\-192\-CBC''\s0 and ``\s-1AES\-256\-CBC''\s0" 4 +.IX Item "AES-128-CBC, AES-192-CBC and AES-256-CBC" +.PD 0 +.ie n .IP """\s-1AES\-128\-CBC\-CTS"", ""AES\-192\-CBC\-CTS""\s0 and ""\s-1AES\-256\-CBC\-CTS""\s0" 4 +.el .IP "``\s-1AES\-128\-CBC\-CTS'', ``AES\-192\-CBC\-CTS''\s0 and ``\s-1AES\-256\-CBC\-CTS''\s0" 4 +.IX Item "AES-128-CBC-CTS, AES-192-CBC-CTS and AES-256-CBC-CTS" +.ie n .IP """\s-1AES\-128\-CFB"", ""AES\-192\-CFB"", ""AES\-256\-CFB"", ""AES\-128\-CFB1"", ""AES\-192\-CFB1"", ""AES\-256\-CFB1"", ""AES\-128\-CFB8"", ""AES\-192\-CFB8""\s0 and ""\s-1AES\-256\-CFB8""\s0" 4 +.el .IP "``\s-1AES\-128\-CFB'', ``AES\-192\-CFB'', ``AES\-256\-CFB'', ``AES\-128\-CFB1'', ``AES\-192\-CFB1'', ``AES\-256\-CFB1'', ``AES\-128\-CFB8'', ``AES\-192\-CFB8''\s0 and ``\s-1AES\-256\-CFB8''\s0" 4 +.IX Item "AES-128-CFB, AES-192-CFB, AES-256-CFB, AES-128-CFB1, AES-192-CFB1, AES-256-CFB1, AES-128-CFB8, AES-192-CFB8 and AES-256-CFB8" +.ie n .IP """\s-1AES\-128\-CTR"", ""AES\-192\-CTR""\s0 and ""\s-1AES\-256\-CTR""\s0" 4 +.el .IP "``\s-1AES\-128\-CTR'', ``AES\-192\-CTR''\s0 and ``\s-1AES\-256\-CTR''\s0" 4 +.IX Item "AES-128-CTR, AES-192-CTR and AES-256-CTR" +.ie n .IP """\s-1AES\-128\-ECB"", ""AES\-192\-ECB""\s0 and ""\s-1AES\-256\-ECB""\s0" 4 +.el .IP "``\s-1AES\-128\-ECB'', ``AES\-192\-ECB''\s0 and ``\s-1AES\-256\-ECB''\s0" 4 +.IX Item "AES-128-ECB, AES-192-ECB and AES-256-ECB" +.ie n .IP """\s-1AES\-192\-OFB"", ""AES\-128\-OFB""\s0 and ""\s-1AES\-256\-OFB""\s0" 4 +.el .IP "``\s-1AES\-192\-OFB'', ``AES\-128\-OFB''\s0 and ``\s-1AES\-256\-OFB''\s0" 4 +.IX Item "AES-192-OFB, AES-128-OFB and AES-256-OFB" +.ie n .IP """\s-1AES\-128\-XTS""\s0 and ""\s-1AES\-256\-XTS""\s0" 4 +.el .IP "``\s-1AES\-128\-XTS''\s0 and ``\s-1AES\-256\-XTS''\s0" 4 +.IX Item "AES-128-XTS and AES-256-XTS" +.ie n .IP """\s-1AES\-128\-CCM"", ""AES\-192\-CCM""\s0 and ""\s-1AES\-256\-CCM""\s0" 4 +.el .IP "``\s-1AES\-128\-CCM'', ``AES\-192\-CCM''\s0 and ``\s-1AES\-256\-CCM''\s0" 4 +.IX Item "AES-128-CCM, AES-192-CCM and AES-256-CCM" +.ie n .IP """\s-1AES\-128\-GCM"", ""AES\-192\-GCM""\s0 and ""\s-1AES\-256\-GCM""\s0" 4 +.el .IP "``\s-1AES\-128\-GCM'', ``AES\-192\-GCM''\s0 and ``\s-1AES\-256\-GCM''\s0" 4 +.IX Item "AES-128-GCM, AES-192-GCM and AES-256-GCM" +.ie n .IP """\s-1AES\-128\-WRAP"", ""AES\-192\-WRAP"", ""AES\-256\-WRAP"", ""AES\-128\-WRAP\-PAD"", ""AES\-192\-WRAP\-PAD"", ""AES\-256\-WRAP\-PAD"", ""AES\-128\-WRAP\-INV"", ""AES\-192\-WRAP\-INV"", ""AES\-256\-WRAP\-INV"", ""AES\-128\-WRAP\-PAD\-INV"", ""AES\-192\-WRAP\-PAD\-INV""\s0 and ""\s-1AES\-256\-WRAP\-PAD\-INV""\s0" 4 +.el .IP "``\s-1AES\-128\-WRAP'', ``AES\-192\-WRAP'', ``AES\-256\-WRAP'', ``AES\-128\-WRAP\-PAD'', ``AES\-192\-WRAP\-PAD'', ``AES\-256\-WRAP\-PAD'', ``AES\-128\-WRAP\-INV'', ``AES\-192\-WRAP\-INV'', ``AES\-256\-WRAP\-INV'', ``AES\-128\-WRAP\-PAD\-INV'', ``AES\-192\-WRAP\-PAD\-INV''\s0 and ``\s-1AES\-256\-WRAP\-PAD\-INV''\s0" 4 +.IX Item "AES-128-WRAP, AES-192-WRAP, AES-256-WRAP, AES-128-WRAP-PAD, AES-192-WRAP-PAD, AES-256-WRAP-PAD, AES-128-WRAP-INV, AES-192-WRAP-INV, AES-256-WRAP-INV, AES-128-WRAP-PAD-INV, AES-192-WRAP-PAD-INV and AES-256-WRAP-PAD-INV" +.ie n .IP """\s-1AES\-128\-CBC\-HMAC\-SHA1"", ""AES\-256\-CBC\-HMAC\-SHA1"", ""AES\-128\-CBC\-HMAC\-SHA256""\s0 and ""\s-1AES\-256\-CBC\-HMAC\-SHA256""\s0" 4 +.el .IP "``\s-1AES\-128\-CBC\-HMAC\-SHA1'', ``AES\-256\-CBC\-HMAC\-SHA1'', ``AES\-128\-CBC\-HMAC\-SHA256''\s0 and ``\s-1AES\-256\-CBC\-HMAC\-SHA256''\s0" 4 +.IX Item "AES-128-CBC-HMAC-SHA1, AES-256-CBC-HMAC-SHA1, AES-128-CBC-HMAC-SHA256 and AES-256-CBC-HMAC-SHA256" +.PD +.PP +The following algorithms are available in the default provider, but not the +\&\s-1FIPS\s0 provider: +.ie n .IP """\s-1AES\-128\-OCB"", ""AES\-192\-OCB""\s0 and ""\s-1AES\-256\-OCB""\s0" 4 +.el .IP "``\s-1AES\-128\-OCB'', ``AES\-192\-OCB''\s0 and ``\s-1AES\-256\-OCB''\s0" 4 +.IX Item "AES-128-OCB, AES-192-OCB and AES-256-OCB" +.PD 0 +.ie n .IP """\s-1AES\-128\-SIV"", ""AES\-192\-SIV""\s0 and ""\s-1AES\-256\-SIV""\s0" 4 +.el .IP "``\s-1AES\-128\-SIV'', ``AES\-192\-SIV''\s0 and ``\s-1AES\-256\-SIV''\s0" 4 +.IX Item "AES-128-SIV, AES-192-SIV and AES-256-SIV" +.PD +.SS "Parameters" +.IX Subsection "Parameters" +This implementation supports the parameters described in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021\-2022 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_CIPHER-ARIA.7 b/secure/lib/libcrypto/man/man7/EVP_CIPHER-ARIA.7 new file mode 100644 index 000000000000..57fd0fd1dbb2 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_CIPHER-ARIA.7 @@ -0,0 +1,187 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_CIPHER-ARIA 7ossl" +.TH EVP_CIPHER-ARIA 7ossl "2023-09-19" "3.0.11" "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_CIPHER\-ARIA \- The ARIA EVP_CIPHER implementations +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for \s-1ARIA\s0 symmetric encryption using the \fB\s-1EVP_CIPHER\s0\fR \s-1API.\s0 +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the default provider: +.ie n .IP """\s-1ARIA\-128\-CBC"", ""ARIA\-192\-CBC""\s0 and ""\s-1ARIA\-256\-CBC""\s0" 4 +.el .IP "``\s-1ARIA\-128\-CBC'', ``ARIA\-192\-CBC''\s0 and ``\s-1ARIA\-256\-CBC''\s0" 4 +.IX Item "ARIA-128-CBC, ARIA-192-CBC and ARIA-256-CBC" +.PD 0 +.ie n .IP """\s-1ARIA\-128\-CFB"", ""ARIA\-192\-CFB"", ""ARIA\-256\-CFB"", ""ARIA\-128\-CFB1"", ""ARIA\-192\-CFB1"", ""ARIA\-256\-CFB1"", ""ARIA\-128\-CFB8"", ""ARIA\-192\-CFB8""\s0 and ""\s-1ARIA\-256\-CFB8""\s0" 4 +.el .IP "``\s-1ARIA\-128\-CFB'', ``ARIA\-192\-CFB'', ``ARIA\-256\-CFB'', ``ARIA\-128\-CFB1'', ``ARIA\-192\-CFB1'', ``ARIA\-256\-CFB1'', ``ARIA\-128\-CFB8'', ``ARIA\-192\-CFB8''\s0 and ``\s-1ARIA\-256\-CFB8''\s0" 4 +.IX Item "ARIA-128-CFB, ARIA-192-CFB, ARIA-256-CFB, ARIA-128-CFB1, ARIA-192-CFB1, ARIA-256-CFB1, ARIA-128-CFB8, ARIA-192-CFB8 and ARIA-256-CFB8" +.ie n .IP """\s-1ARIA\-128\-CTR"", ""ARIA\-192\-CTR""\s0 and ""\s-1ARIA\-256\-CTR""\s0" 4 +.el .IP "``\s-1ARIA\-128\-CTR'', ``ARIA\-192\-CTR''\s0 and ``\s-1ARIA\-256\-CTR''\s0" 4 +.IX Item "ARIA-128-CTR, ARIA-192-CTR and ARIA-256-CTR" +.ie n .IP """\s-1ARIA\-128\-ECB"", ""ARIA\-192\-ECB""\s0 and ""\s-1ARIA\-256\-ECB""\s0" 4 +.el .IP "``\s-1ARIA\-128\-ECB'', ``ARIA\-192\-ECB''\s0 and ``\s-1ARIA\-256\-ECB''\s0" 4 +.IX Item "ARIA-128-ECB, ARIA-192-ECB and ARIA-256-ECB" +.ie n .IP """\s-1AES\-192\-OCB"", ""AES\-128\-OCB""\s0 and ""\s-1AES\-256\-OCB""\s0" 4 +.el .IP "``\s-1AES\-192\-OCB'', ``AES\-128\-OCB''\s0 and ``\s-1AES\-256\-OCB''\s0" 4 +.IX Item "AES-192-OCB, AES-128-OCB and AES-256-OCB" +.ie n .IP """\s-1ARIA\-128\-OFB"", ""ARIA\-192\-OFB""\s0 and ""\s-1ARIA\-256\-OFB""\s0" 4 +.el .IP "``\s-1ARIA\-128\-OFB'', ``ARIA\-192\-OFB''\s0 and ``\s-1ARIA\-256\-OFB''\s0" 4 +.IX Item "ARIA-128-OFB, ARIA-192-OFB and ARIA-256-OFB" +.ie n .IP """\s-1ARIA\-128\-CCM"", ""ARIA\-192\-CCM""\s0 and ""\s-1ARIA\-256\-CCM""\s0" 4 +.el .IP "``\s-1ARIA\-128\-CCM'', ``ARIA\-192\-CCM''\s0 and ``\s-1ARIA\-256\-CCM''\s0" 4 +.IX Item "ARIA-128-CCM, ARIA-192-CCM and ARIA-256-CCM" +.ie n .IP """\s-1ARIA\-128\-GCM"", ""ARIA\-192\-GCM""\s0 and ""\s-1ARIA\-256\-GCM""\s0" 4 +.el .IP "``\s-1ARIA\-128\-GCM'', ``ARIA\-192\-GCM''\s0 and ``\s-1ARIA\-256\-GCM''\s0" 4 +.IX Item "ARIA-128-GCM, ARIA-192-GCM and ARIA-256-GCM" +.PD +.SS "Parameters" +.IX Subsection "Parameters" +This implementation supports the parameters described in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_CIPHER-BLOWFISH.7 b/secure/lib/libcrypto/man/man7/EVP_CIPHER-BLOWFISH.7 new file mode 100644 index 000000000000..0b07c7ba2cc6 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_CIPHER-BLOWFISH.7 @@ -0,0 +1,175 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_CIPHER-BLOWFISH 7ossl" +.TH EVP_CIPHER-BLOWFISH 7ossl "2023-09-19" "3.0.11" "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_CIPHER\-BLOWFISH \- The BLOBFISH EVP_CIPHER implementations +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for \s-1BLOWFISH\s0 symmetric encryption using the \fB\s-1EVP_CIPHER\s0\fR \s-1API.\s0 +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the legacy provider: +.ie n .IP """BF-ECB""" 4 +.el .IP "``BF-ECB''" 4 +.IX Item "BF-ECB" +.PD 0 +.ie n .IP """BF-CBC""" 4 +.el .IP "``BF-CBC''" 4 +.IX Item "BF-CBC" +.ie n .IP """BF-OFB""" 4 +.el .IP "``BF-OFB''" 4 +.IX Item "BF-OFB" +.ie n .IP """BF-CFB""" 4 +.el .IP "``BF-CFB''" 4 +.IX Item "BF-CFB" +.PD +.SS "Parameters" +.IX Subsection "Parameters" +This implementation supports the parameters described in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_CIPHER-CAMELLIA.7 b/secure/lib/libcrypto/man/man7/EVP_CIPHER-CAMELLIA.7 new file mode 100644 index 000000000000..fa128996498c --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_CIPHER-CAMELLIA.7 @@ -0,0 +1,181 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_CIPHER-CAMELLIA 7ossl" +.TH EVP_CIPHER-CAMELLIA 7ossl "2023-09-19" "3.0.11" "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_CIPHER\-CAMELLIA \- The CAMELLIA EVP_CIPHER implementations +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for \s-1CAMELLIA\s0 symmetric encryption using the \fB\s-1EVP_CIPHER\s0\fR \s-1API.\s0 +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the default provider: +.ie n .IP """\s-1CAMELLIA\-128\-CBC"", ""CAMELLIA\-192\-CBC""\s0 and ""\s-1CAMELLIA\-256\-CBC""\s0" 4 +.el .IP "``\s-1CAMELLIA\-128\-CBC'', ``CAMELLIA\-192\-CBC''\s0 and ``\s-1CAMELLIA\-256\-CBC''\s0" 4 +.IX Item "CAMELLIA-128-CBC, CAMELLIA-192-CBC and CAMELLIA-256-CBC" +.PD 0 +.ie n .IP """\s-1CAMELLIA\-128\-CBC\-CTS"", ""CAMELLIA\-192\-CBC\-CTS""\s0 and ""\s-1CAMELLIA\-256\-CBC\-CTS""\s0" 4 +.el .IP "``\s-1CAMELLIA\-128\-CBC\-CTS'', ``CAMELLIA\-192\-CBC\-CTS''\s0 and ``\s-1CAMELLIA\-256\-CBC\-CTS''\s0" 4 +.IX Item "CAMELLIA-128-CBC-CTS, CAMELLIA-192-CBC-CTS and CAMELLIA-256-CBC-CTS" +.ie n .IP """\s-1CAMELLIA\-128\-CFB"", ""CAMELLIA\-192\-CFB"", ""CAMELLIA\-256\-CFB"", ""CAMELLIA\-128\-CFB1"", ""CAMELLIA\-192\-CFB1"", ""CAMELLIA\-256\-CFB1"", ""CAMELLIA\-128\-CFB8"", ""CAMELLIA\-192\-CFB8""\s0 and ""\s-1CAMELLIA\-256\-CFB8""\s0" 4 +.el .IP "``\s-1CAMELLIA\-128\-CFB'', ``CAMELLIA\-192\-CFB'', ``CAMELLIA\-256\-CFB'', ``CAMELLIA\-128\-CFB1'', ``CAMELLIA\-192\-CFB1'', ``CAMELLIA\-256\-CFB1'', ``CAMELLIA\-128\-CFB8'', ``CAMELLIA\-192\-CFB8''\s0 and ``\s-1CAMELLIA\-256\-CFB8''\s0" 4 +.IX Item "CAMELLIA-128-CFB, CAMELLIA-192-CFB, CAMELLIA-256-CFB, CAMELLIA-128-CFB1, CAMELLIA-192-CFB1, CAMELLIA-256-CFB1, CAMELLIA-128-CFB8, CAMELLIA-192-CFB8 and CAMELLIA-256-CFB8" +.ie n .IP """\s-1CAMELLIA\-128\-CTR"", ""CAMELLIA\-192\-CTR""\s0 and ""\s-1CAMELLIA\-256\-CTR""\s0" 4 +.el .IP "``\s-1CAMELLIA\-128\-CTR'', ``CAMELLIA\-192\-CTR''\s0 and ``\s-1CAMELLIA\-256\-CTR''\s0" 4 +.IX Item "CAMELLIA-128-CTR, CAMELLIA-192-CTR and CAMELLIA-256-CTR" +.ie n .IP """\s-1CAMELLIA\-128\-ECB"", ""CAMELLIA\-192\-ECB""\s0 and ""\s-1CAMELLIA\-256\-ECB""\s0" 4 +.el .IP "``\s-1CAMELLIA\-128\-ECB'', ``CAMELLIA\-192\-ECB''\s0 and ``\s-1CAMELLIA\-256\-ECB''\s0" 4 +.IX Item "CAMELLIA-128-ECB, CAMELLIA-192-ECB and CAMELLIA-256-ECB" +.ie n .IP """\s-1CAMELLIA\-192\-OFB"", ""CAMELLIA\-128\-OFB""\s0 and ""\s-1CAMELLIA\-256\-OFB""\s0" 4 +.el .IP "``\s-1CAMELLIA\-192\-OFB'', ``CAMELLIA\-128\-OFB''\s0 and ``\s-1CAMELLIA\-256\-OFB''\s0" 4 +.IX Item "CAMELLIA-192-OFB, CAMELLIA-128-OFB and CAMELLIA-256-OFB" +.PD +.SS "Parameters" +.IX Subsection "Parameters" +This implementation supports the parameters described in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_CIPHER-CAST.7 b/secure/lib/libcrypto/man/man7/EVP_CIPHER-CAST.7 new file mode 100644 index 000000000000..dff008aa485d --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_CIPHER-CAST.7 @@ -0,0 +1,175 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_CIPHER-CAST 7ossl" +.TH EVP_CIPHER-CAST 7ossl "2023-09-19" "3.0.11" "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_CIPHER\-CAST \- The CAST EVP_CIPHER implementations +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for \s-1CAST\s0 symmetric encryption using the \fB\s-1EVP_CIPHER\s0\fR \s-1API.\s0 +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the legacy provider: +.ie n .IP """\s-1CAST\-128\-CBC"", ""CAST\-192\-CBC""\s0 and ""\s-1CAST\-256\-CBC""\s0" 4 +.el .IP "``\s-1CAST\-128\-CBC'', ``CAST\-192\-CBC''\s0 and ``\s-1CAST\-256\-CBC''\s0" 4 +.IX Item "CAST-128-CBC, CAST-192-CBC and CAST-256-CBC" +.PD 0 +.ie n .IP """\s-1CAST\-128\-CFB"", ""CAST\-192\-CFB"", ""CAST\-256\-CFB""\s0" 4 +.el .IP "``\s-1CAST\-128\-CFB'', ``CAST\-192\-CFB'', ``CAST\-256\-CFB''\s0" 4 +.IX Item "CAST-128-CFB, CAST-192-CFB, CAST-256-CFB" +.ie n .IP """\s-1CAST\-128\-ECB"", ""CAST\-192\-ECB""\s0 and ""\s-1CAST\-256\-ECB""\s0" 4 +.el .IP "``\s-1CAST\-128\-ECB'', ``CAST\-192\-ECB''\s0 and ``\s-1CAST\-256\-ECB''\s0" 4 +.IX Item "CAST-128-ECB, CAST-192-ECB and CAST-256-ECB" +.ie n .IP """\s-1CAST\-192\-OFB"", ""CAST\-128\-OFB""\s0 and ""\s-1CAST\-256\-OFB""\s0" 4 +.el .IP "``\s-1CAST\-192\-OFB'', ``CAST\-128\-OFB''\s0 and ``\s-1CAST\-256\-OFB''\s0" 4 +.IX Item "CAST-192-OFB, CAST-128-OFB and CAST-256-OFB" +.PD +.SS "Parameters" +.IX Subsection "Parameters" +This implementation supports the parameters described in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_CIPHER-CHACHA.7 b/secure/lib/libcrypto/man/man7/EVP_CIPHER-CHACHA.7 new file mode 100644 index 000000000000..1e6320dc9e7d --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_CIPHER-CHACHA.7 @@ -0,0 +1,169 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_CIPHER-CHACHA 7ossl" +.TH EVP_CIPHER-CHACHA 7ossl "2023-09-19" "3.0.11" "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_CIPHER\-CHACHA \- The CHACHA EVP_CIPHER implementations +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for \s-1CHACHA\s0 symmetric encryption using the \fB\s-1EVP_CIPHER\s0\fR \s-1API.\s0 +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the default provider: +.ie n .IP """ChaCha20""" 4 +.el .IP "``ChaCha20''" 4 +.IX Item "ChaCha20" +.PD 0 +.ie n .IP """ChaCha20\-Poly1305""" 4 +.el .IP "``ChaCha20\-Poly1305''" 4 +.IX Item "ChaCha20-Poly1305" +.PD +.SS "Parameters" +.IX Subsection "Parameters" +This implementation supports the parameters described in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_CIPHER-DES.7 b/secure/lib/libcrypto/man/man7/EVP_CIPHER-DES.7 new file mode 100644 index 000000000000..54d91917064b --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_CIPHER-DES.7 @@ -0,0 +1,213 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_CIPHER-DES 7ossl" +.TH EVP_CIPHER-DES 7ossl "2023-09-19" "3.0.11" "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_CIPHER\-DES \- The DES EVP_CIPHER implementations +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for \s-1DES\s0 symmetric encryption using the \fB\s-1EVP_CIPHER\s0\fR \s-1API.\s0 +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the \s-1FIPS\s0 provider as well as the +default provider: +.ie n .IP """\s-1DES\-EDE3\-ECB""\s0 or ""\s-1DES\-EDE3""\s0" 4 +.el .IP "``\s-1DES\-EDE3\-ECB''\s0 or ``\s-1DES\-EDE3''\s0" 4 +.IX Item "DES-EDE3-ECB or DES-EDE3" +.PD 0 +.ie n .IP """\s-1DES\-EDE3\-CBC""\s0 or ""\s-1DES3""\s0" 4 +.el .IP "``\s-1DES\-EDE3\-CBC''\s0 or ``\s-1DES3''\s0" 4 +.IX Item "DES-EDE3-CBC or DES3" +.PD +.PP +The following algorithms are available in the default provider, but not the +\&\s-1FIPS\s0 provider: +.ie n .IP """\s-1DES\-EDE3\-CFB8""\s0 and ""\s-1DES\-EDE3\-CFB1""\s0" 4 +.el .IP "``\s-1DES\-EDE3\-CFB8''\s0 and ``\s-1DES\-EDE3\-CFB1''\s0" 4 +.IX Item "DES-EDE3-CFB8 and DES-EDE3-CFB1" +.PD 0 +.ie n .IP """DES-EDE-ECB"" or ""DES-EDE""" 4 +.el .IP "``DES-EDE-ECB'' or ``DES-EDE''" 4 +.IX Item "DES-EDE-ECB or DES-EDE" +.ie n .IP """DES-EDE-CBC""" 4 +.el .IP "``DES-EDE-CBC''" 4 +.IX Item "DES-EDE-CBC" +.ie n .IP """DES-EDE-OFB""" 4 +.el .IP "``DES-EDE-OFB''" 4 +.IX Item "DES-EDE-OFB" +.ie n .IP """DES-EDE-CFB""" 4 +.el .IP "``DES-EDE-CFB''" 4 +.IX Item "DES-EDE-CFB" +.ie n .IP """\s-1DES3\-WRAP""\s0" 4 +.el .IP "``\s-1DES3\-WRAP''\s0" 4 +.IX Item "DES3-WRAP" +.PD +.PP +The following algorithms are available in the legacy provider: +.ie n .IP """DES-ECB""" 4 +.el .IP "``DES-ECB''" 4 +.IX Item "DES-ECB" +.PD 0 +.ie n .IP """DES-CBC""" 4 +.el .IP "``DES-CBC''" 4 +.IX Item "DES-CBC" +.ie n .IP """DES-OFB""" 4 +.el .IP "``DES-OFB''" 4 +.IX Item "DES-OFB" +.ie n .IP """DES-CFB"", ""\s-1DES\-CFB1""\s0 and ""\s-1DES\-CFB8""\s0" 4 +.el .IP "``DES-CFB'', ``\s-1DES\-CFB1''\s0 and ``\s-1DES\-CFB8''\s0" 4 +.IX Item "DES-CFB, DES-CFB1 and DES-CFB8" +.ie n .IP """DESX-CBC""" 4 +.el .IP "``DESX-CBC''" 4 +.IX Item "DESX-CBC" +.PD +.SS "Parameters" +.IX Subsection "Parameters" +This implementation supports the parameters described in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7), +\&\fBOSSL_PROVIDER\-legacy\fR\|(7), +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_CIPHER-IDEA.7 b/secure/lib/libcrypto/man/man7/EVP_CIPHER-IDEA.7 new file mode 100644 index 000000000000..c40eb344a7e5 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_CIPHER-IDEA.7 @@ -0,0 +1,175 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_CIPHER-IDEA 7ossl" +.TH EVP_CIPHER-IDEA 7ossl "2023-09-19" "3.0.11" "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_CIPHER\-IDEA \- The IDEA EVP_CIPHER implementations +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for \s-1IDEA\s0 symmetric encryption using the \fB\s-1EVP_CIPHER\s0\fR \s-1API.\s0 +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the legacy provider: +.ie n .IP """IDEA-ECB""" 4 +.el .IP "``IDEA-ECB''" 4 +.IX Item "IDEA-ECB" +.PD 0 +.ie n .IP """IDEA-CBC""" 4 +.el .IP "``IDEA-CBC''" 4 +.IX Item "IDEA-CBC" +.ie n .IP """IDEA-OFB"" or ""\s-1IDEA\-OFB64""\s0" 4 +.el .IP "``IDEA-OFB'' or ``\s-1IDEA\-OFB64''\s0" 4 +.IX Item "IDEA-OFB or IDEA-OFB64" +.ie n .IP """IDEA-CFB"" or ""\s-1IDEA\-CFB64""\s0" 4 +.el .IP "``IDEA-CFB'' or ``\s-1IDEA\-CFB64''\s0" 4 +.IX Item "IDEA-CFB or IDEA-CFB64" +.PD +.SS "Parameters" +.IX Subsection "Parameters" +This implementation supports the parameters described in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_CIPHER-NULL.7 b/secure/lib/libcrypto/man/man7/EVP_CIPHER-NULL.7 new file mode 100644 index 000000000000..fc39ddbd0a68 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_CIPHER-NULL.7 @@ -0,0 +1,197 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_CIPHER-NULL 7ossl" +.TH EVP_CIPHER-NULL 7ossl "2023-09-19" "3.0.11" "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_CIPHER\-NULL \- The NULL EVP_CIPHER implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for a \s-1NULL\s0 symmetric encryption using the \fB\s-1EVP_CIPHER\s0\fR \s-1API.\s0 +This is used when the \s-1TLS\s0 cipher suite is \s-1TLS_NULL_WITH_NULL_NULL.\s0 +This does no encryption (just copies the data) and has a mac size of zero. +.SS "Algorithm Name" +.IX Subsection "Algorithm Name" +The following algorithm is available in the default provider: +.ie n .IP """\s-1NULL""\s0" 4 +.el .IP "``\s-1NULL''\s0" 4 +.IX Item "NULL" +.SS "Parameters" +.IX Subsection "Parameters" +This implementation supports the following parameters: +.PP +\fIGettable \s-1EVP_CIPHER\s0 parameters\fR +.IX Subsection "Gettable EVP_CIPHER parameters" +.PP +See \*(L"Gettable \s-1EVP_CIPHER\s0 parameters\*(R" in \fBEVP_EncryptInit\fR\|(3) +.PP +\fIGettable \s-1EVP_CIPHER_CTX\s0 parameters\fR +.IX Subsection "Gettable EVP_CIPHER_CTX parameters" +.ie n .IP """keylen"" (\fB\s-1OSSL_CIPHER_PARAM_KEYLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``keylen'' (\fB\s-1OSSL_CIPHER_PARAM_KEYLEN\s0\fR) <unsigned integer>" 4 +.IX Item "keylen (OSSL_CIPHER_PARAM_KEYLEN) <unsigned integer>" +.PD 0 +.ie n .IP """ivlen"" (\fB\s-1OSSL_CIPHER_PARAM_IVLEN\s0\fR and <\fB\s-1OSSL_CIPHER_PARAM_AEAD_IVLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``ivlen'' (\fB\s-1OSSL_CIPHER_PARAM_IVLEN\s0\fR and <\fB\s-1OSSL_CIPHER_PARAM_AEAD_IVLEN\s0\fR) <unsigned integer>" 4 +.IX Item "ivlen (OSSL_CIPHER_PARAM_IVLEN and <OSSL_CIPHER_PARAM_AEAD_IVLEN) <unsigned integer>" +.ie n .IP """tls-mac"" (\fB\s-1OSSL_CIPHER_PARAM_TLS_MAC\s0\fR) <octet ptr>" 4 +.el .IP "``tls-mac'' (\fB\s-1OSSL_CIPHER_PARAM_TLS_MAC\s0\fR) <octet ptr>" 4 +.IX Item "tls-mac (OSSL_CIPHER_PARAM_TLS_MAC) <octet ptr>" +.PD +.PP +See \*(L"\s-1PARAMETERS\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3) for further information. +.PP +\fISettable \s-1EVP_CIPHER_CTX\s0 parameters\fR +.IX Subsection "Settable EVP_CIPHER_CTX parameters" +.ie n .IP """tls-mac-size"" (\fB\s-1OSSL_CIPHER_PARAM_TLS_MAC_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``tls-mac-size'' (\fB\s-1OSSL_CIPHER_PARAM_TLS_MAC_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "tls-mac-size (OSSL_CIPHER_PARAM_TLS_MAC_SIZE) <unsigned integer>" +.PP +See \*(L"\s-1PARAMETERS\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3) for further information. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1RFC 5246\s0 section\-6.2.3.1 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2023 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_CIPHER-RC2.7 b/secure/lib/libcrypto/man/man7/EVP_CIPHER-RC2.7 new file mode 100644 index 000000000000..aa3030def6e0 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_CIPHER-RC2.7 @@ -0,0 +1,181 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_CIPHER-RC2 7ossl" +.TH EVP_CIPHER-RC2 7ossl "2023-09-19" "3.0.11" "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_CIPHER\-RC2 \- The RC2 EVP_CIPHER implementations +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for \s-1RC2\s0 symmetric encryption using the \fB\s-1EVP_CIPHER\s0\fR \s-1API.\s0 +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the legacy provider: +.ie n .IP """\s-1RC2\-CBC"", ""RC2""\s0 or ""\s-1RC2\-128""\s0" 4 +.el .IP "``\s-1RC2\-CBC'', ``RC2''\s0 or ``\s-1RC2\-128''\s0" 4 +.IX Item "RC2-CBC, RC2 or RC2-128" +.PD 0 +.ie n .IP """\s-1RC2\-40\-CBC""\s0 or ""\s-1RC2\-40""\s0" 4 +.el .IP "``\s-1RC2\-40\-CBC''\s0 or ``\s-1RC2\-40''\s0" 4 +.IX Item "RC2-40-CBC or RC2-40" +.ie n .IP """\s-1RC2\-64\-CBC""\s0 or ""\s-1RC2\-64""\s0" 4 +.el .IP "``\s-1RC2\-64\-CBC''\s0 or ``\s-1RC2\-64''\s0" 4 +.IX Item "RC2-64-CBC or RC2-64" +.ie n .IP """\s-1RC2\-ECB""\s0" 4 +.el .IP "``\s-1RC2\-ECB''\s0" 4 +.IX Item "RC2-ECB" +.ie n .IP """\s-1RC2\-CFB""\s0" 4 +.el .IP "``\s-1RC2\-CFB''\s0" 4 +.IX Item "RC2-CFB" +.ie n .IP """\s-1RC2\-OFB""\s0" 4 +.el .IP "``\s-1RC2\-OFB''\s0" 4 +.IX Item "RC2-OFB" +.PD +.SS "Parameters" +.IX Subsection "Parameters" +This implementation supports the parameters described in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_CIPHER-RC4.7 b/secure/lib/libcrypto/man/man7/EVP_CIPHER-RC4.7 new file mode 100644 index 000000000000..aadd1d3f1a51 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_CIPHER-RC4.7 @@ -0,0 +1,172 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_CIPHER-RC4 7ossl" +.TH EVP_CIPHER-RC4 7ossl "2023-09-19" "3.0.11" "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_CIPHER\-RC4 \- The RC4 EVP_CIPHER implementations +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for \s-1RC4\s0 symmetric encryption using the \fB\s-1EVP_CIPHER\s0\fR \s-1API.\s0 +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the legacy provider: +.ie n .IP """\s-1RC4""\s0" 4 +.el .IP "``\s-1RC4''\s0" 4 +.IX Item "RC4" +.PD 0 +.ie n .IP """\s-1RC4\-40""\s0" 4 +.el .IP "``\s-1RC4\-40''\s0" 4 +.IX Item "RC4-40" +.ie n .IP """\s-1RC4\-HMAC\-MD5""\s0" 4 +.el .IP "``\s-1RC4\-HMAC\-MD5''\s0" 4 +.IX Item "RC4-HMAC-MD5" +.PD +.SS "Parameters" +.IX Subsection "Parameters" +This implementation supports the parameters described in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_CIPHER-RC5.7 b/secure/lib/libcrypto/man/man7/EVP_CIPHER-RC5.7 new file mode 100644 index 000000000000..c2e3aab7dcab --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_CIPHER-RC5.7 @@ -0,0 +1,177 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_CIPHER-RC5 7ossl" +.TH EVP_CIPHER-RC5 7ossl "2023-09-19" "3.0.11" "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_CIPHER\-RC5 \- The RC5 EVP_CIPHER implementations +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for \s-1RC5\s0 symmetric encryption using the \fB\s-1EVP_CIPHER\s0\fR \s-1API.\s0 +.PP +Disabled by default. Use the \fIenable\-rc5\fR configuration option to enable. +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the legacy provider: +.ie n .IP """\s-1RC5\-CBC""\s0 or ""\s-1RC5""\s0" 4 +.el .IP "``\s-1RC5\-CBC''\s0 or ``\s-1RC5''\s0" 4 +.IX Item "RC5-CBC or RC5" +.PD 0 +.ie n .IP """\s-1RC5\-ECB""\s0" 4 +.el .IP "``\s-1RC5\-ECB''\s0" 4 +.IX Item "RC5-ECB" +.ie n .IP """\s-1RC5\-OFB""\s0" 4 +.el .IP "``\s-1RC5\-OFB''\s0" 4 +.IX Item "RC5-OFB" +.ie n .IP """\s-1RC5\-CFB""\s0" 4 +.el .IP "``\s-1RC5\-CFB''\s0" 4 +.IX Item "RC5-CFB" +.PD +.SS "Parameters" +.IX Subsection "Parameters" +This implementation supports the parameters described in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_CIPHER-SEED.7 b/secure/lib/libcrypto/man/man7/EVP_CIPHER-SEED.7 new file mode 100644 index 000000000000..ee30270a9201 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_CIPHER-SEED.7 @@ -0,0 +1,175 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_CIPHER-SEED 7ossl" +.TH EVP_CIPHER-SEED 7ossl "2023-09-19" "3.0.11" "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_CIPHER\-SEED \- The SEED EVP_CIPHER implementations +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for \s-1SEED\s0 symmetric encryption using the \fB\s-1EVP_CIPHER\s0\fR \s-1API.\s0 +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the legacy provider: +.ie n .IP """SEED-CBC"" or ""\s-1SEED""\s0" 4 +.el .IP "``SEED-CBC'' or ``\s-1SEED''\s0" 4 +.IX Item "SEED-CBC or SEED" +.PD 0 +.ie n .IP """SEED-ECB""" 4 +.el .IP "``SEED-ECB''" 4 +.IX Item "SEED-ECB" +.ie n .IP """SEED-OFB"" or ""\s-1SEED\-OFB128""\s0" 4 +.el .IP "``SEED-OFB'' or ``\s-1SEED\-OFB128''\s0" 4 +.IX Item "SEED-OFB or SEED-OFB128" +.ie n .IP """SEED-CFB"" or ""\s-1SEED\-CFB128""\s0" 4 +.el .IP "``SEED-CFB'' or ``\s-1SEED\-CFB128''\s0" 4 +.IX Item "SEED-CFB or SEED-CFB128" +.PD +.SS "Parameters" +.IX Subsection "Parameters" +This implementation supports the parameters described in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_CIPHER-SM4.7 b/secure/lib/libcrypto/man/man7/EVP_CIPHER-SM4.7 new file mode 100644 index 000000000000..329189ba789e --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_CIPHER-SM4.7 @@ -0,0 +1,178 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_CIPHER-SM4 7ossl" +.TH EVP_CIPHER-SM4 7ossl "2023-09-19" "3.0.11" "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_CIPHER\-SM4 \- The SM4 EVP_CIPHER implementations +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for \s-1SM4\s0 symmetric encryption using the \fB\s-1EVP_CIPHER\s0\fR \s-1API.\s0 +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the default provider: +.ie n .IP """\s-1SM4\-CBC:SM4""\s0" 4 +.el .IP "``\s-1SM4\-CBC:SM4''\s0" 4 +.IX Item "SM4-CBC:SM4" +.PD 0 +.ie n .IP """\s-1SM4\-ECB""\s0" 4 +.el .IP "``\s-1SM4\-ECB''\s0" 4 +.IX Item "SM4-ECB" +.ie n .IP """\s-1SM4\-CTR""\s0" 4 +.el .IP "``\s-1SM4\-CTR''\s0" 4 +.IX Item "SM4-CTR" +.ie n .IP """\s-1SM4\-OFB""\s0 or ""\s-1SM4\-OFB128""\s0" 4 +.el .IP "``\s-1SM4\-OFB''\s0 or ``\s-1SM4\-OFB128''\s0" 4 +.IX Item "SM4-OFB or SM4-OFB128" +.ie n .IP """\s-1SM4\-CFB""\s0 or ""\s-1SM4\-CFB128""\s0" 4 +.el .IP "``\s-1SM4\-CFB''\s0 or ``\s-1SM4\-CFB128''\s0" 4 +.IX Item "SM4-CFB or SM4-CFB128" +.PD +.SS "Parameters" +.IX Subsection "Parameters" +This implementation supports the parameters described in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_KDF-HKDF.7 b/secure/lib/libcrypto/man/man7/EVP_KDF-HKDF.7 new file mode 100644 index 000000000000..da992a187d1a --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_KDF-HKDF.7 @@ -0,0 +1,285 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_KDF-HKDF 7ossl" +.TH EVP_KDF-HKDF 7ossl "2023-09-19" "3.0.11" "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_KDF\-HKDF \- The HKDF EVP_KDF implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing the \fB\s-1HKDF\s0\fR \s-1KDF\s0 through the \fB\s-1EVP_KDF\s0\fR \s-1API.\s0 +.PP +The \s-1EVP_KDF\-HKDF\s0 algorithm implements the \s-1HKDF\s0 key derivation function. +\&\s-1HKDF\s0 follows the \*(L"extract-then-expand\*(R" paradigm, where the \s-1KDF\s0 logically +consists of two modules. The first stage takes the input keying material +and \*(L"extracts\*(R" from it a fixed-length pseudorandom key K. The second stage +\&\*(L"expands\*(R" the key K into several additional pseudorandom keys (the output +of the \s-1KDF\s0). +.SS "Identity" +.IX Subsection "Identity" +\&\*(L"\s-1HKDF\*(R"\s0 is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.ie n .IP """properties"" (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>" +.PD 0 +.ie n .IP """digest"" (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_KDF_PARAM_DIGEST) <UTF8 string>" +.ie n .IP """key"" (\fB\s-1OSSL_KDF_PARAM_KEY\s0\fR) <octet string>" 4 +.el .IP "``key'' (\fB\s-1OSSL_KDF_PARAM_KEY\s0\fR) <octet string>" 4 +.IX Item "key (OSSL_KDF_PARAM_KEY) <octet string>" +.ie n .IP """salt"" (\fB\s-1OSSL_KDF_PARAM_SALT\s0\fR) <octet string>" 4 +.el .IP "``salt'' (\fB\s-1OSSL_KDF_PARAM_SALT\s0\fR) <octet string>" 4 +.IX Item "salt (OSSL_KDF_PARAM_SALT) <octet string>" +.PD +These parameters work as described in \*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3). +.ie n .IP """info"" (\fB\s-1OSSL_KDF_PARAM_INFO\s0\fR) <octet string>" 4 +.el .IP "``info'' (\fB\s-1OSSL_KDF_PARAM_INFO\s0\fR) <octet string>" 4 +.IX Item "info (OSSL_KDF_PARAM_INFO) <octet string>" +This parameter sets the info value. +The length of the context info buffer cannot exceed 1024 bytes; +this should be more than enough for any normal use of \s-1HKDF.\s0 +.ie n .IP """mode"" (\fB\s-1OSSL_KDF_PARAM_MODE\s0\fR) <\s-1UTF8\s0 string> or <integer>" 4 +.el .IP "``mode'' (\fB\s-1OSSL_KDF_PARAM_MODE\s0\fR) <\s-1UTF8\s0 string> or <integer>" 4 +.IX Item "mode (OSSL_KDF_PARAM_MODE) <UTF8 string> or <integer>" +This parameter sets the mode for the \s-1HKDF\s0 operation. +There are three modes that are currently defined: +.RS 4 +.ie n .IP """\s-1EXTRACT_AND_EXPAND""\s0 or \fB\s-1EVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND\s0\fR" 4 +.el .IP "``\s-1EXTRACT_AND_EXPAND''\s0 or \fB\s-1EVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND\s0\fR" 4 +.IX Item "EXTRACT_AND_EXPAND or EVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND" +This is the default mode. Calling \fBEVP_KDF_derive\fR\|(3) on an \s-1EVP_KDF_CTX\s0 set +up for \s-1HKDF\s0 will perform an extract followed by an expand operation in one go. +The derived key returned will be the result after the expand operation. The +intermediate fixed-length pseudorandom key K is not returned. +.Sp +In this mode the digest, key, salt and info values must be set before a key is +derived otherwise an error will occur. +.ie n .IP """\s-1EXTRACT_ONLY""\s0 or \fB\s-1EVP_KDF_HKDF_MODE_EXTRACT_ONLY\s0\fR" 4 +.el .IP "``\s-1EXTRACT_ONLY''\s0 or \fB\s-1EVP_KDF_HKDF_MODE_EXTRACT_ONLY\s0\fR" 4 +.IX Item "EXTRACT_ONLY or EVP_KDF_HKDF_MODE_EXTRACT_ONLY" +In this mode calling \fBEVP_KDF_derive\fR\|(3) will just perform the extract +operation. The value returned will be the intermediate fixed-length pseudorandom +key K. The \fIkeylen\fR parameter must match the size of K, which can be looked +up by calling \fBEVP_KDF_CTX_get_kdf_size()\fR after setting the mode and digest. +.Sp +The digest, key and salt values must be set before a key is derived otherwise +an error will occur. +.ie n .IP """\s-1EXPAND_ONLY""\s0 or \fB\s-1EVP_KDF_HKDF_MODE_EXPAND_ONLY\s0\fR" 4 +.el .IP "``\s-1EXPAND_ONLY''\s0 or \fB\s-1EVP_KDF_HKDF_MODE_EXPAND_ONLY\s0\fR" 4 +.IX Item "EXPAND_ONLY or EVP_KDF_HKDF_MODE_EXPAND_ONLY" +In this mode calling \fBEVP_KDF_derive\fR\|(3) will just perform the expand +operation. The input key should be set to the intermediate fixed-length +pseudorandom key K returned from a previous extract operation. +.Sp +The digest, key and info values must be set before a key is derived otherwise +an error will occur. +.RE +.RS 4 +.RE +.SH "NOTES" +.IX Header "NOTES" +A context for \s-1HKDF\s0 can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "HKDF", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); +.Ve +.PP +The output length of an \s-1HKDF\s0 expand operation is specified via the \fIkeylen\fR +parameter to the \fBEVP_KDF_derive\fR\|(3) function. When using +\&\s-1EVP_KDF_HKDF_MODE_EXTRACT_ONLY\s0 the \fIkeylen\fR parameter must equal the size of +the intermediate fixed-length pseudorandom key otherwise an error will occur. +For that mode, the fixed output size can be looked up by calling \fBEVP_KDF_CTX_get_kdf_size()\fR +after setting the mode and digest on the \fB\s-1EVP_KDF_CTX\s0\fR. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +This example derives 10 bytes using \s-1SHA\-256\s0 with the secret key \*(L"secret\*(R", +salt value \*(L"salt\*(R" and info value \*(L"label\*(R": +.PP +.Vb 4 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& unsigned char out[10]; +\& OSSL_PARAM params[5], *p = params; +\& +\& kdf = EVP_KDF_fetch(NULL, "HKDF", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, +\& SN_sha256, strlen(SN_sha256)); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, +\& "secret", (size_t)6); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, +\& "label", (size_t)5); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, +\& "salt", (size_t)4); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { +\& error("EVP_KDF_derive"); +\& } +\& +\& EVP_KDF_CTX_free(kctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1RFC 5869\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_KDF\s0\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_get_kdf_size\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3), +\&\s-1\fBEVP_KDF\-TLS13_KDF\s0\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2016\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_KDF-KB.7 b/secure/lib/libcrypto/man/man7/EVP_KDF-KB.7 new file mode 100644 index 000000000000..9a05e4556576 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_KDF-KB.7 @@ -0,0 +1,305 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_KDF-KB 7ossl" +.TH EVP_KDF-KB 7ossl "2023-09-19" "3.0.11" "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_KDF\-KB \- The Key\-Based EVP_KDF implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \s-1EVP_KDF\-KB\s0 algorithm implements the Key-Based key derivation function +(\s-1KBKDF\s0). \s-1KBKDF\s0 derives a key from repeated application of a keyed \s-1MAC\s0 to an +input secret (and other optional values). +.SS "Identity" +.IX Subsection "Identity" +\&\*(L"\s-1KBKDF\*(R"\s0 is the name for this implementation; it can be used with the +\&\fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.ie n .IP """mode"" (\fB\s-1OSSL_KDF_PARAM_MODE\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``mode'' (\fB\s-1OSSL_KDF_PARAM_MODE\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "mode (OSSL_KDF_PARAM_MODE) <UTF8 string>" +The mode parameter determines which flavor of \s-1KBKDF\s0 to use \- currently the +choices are \*(L"counter\*(R" and \*(L"feedback\*(R". \*(L"counter\*(R" is the default, and will be +used if unspecified. +.ie n .IP """mac"" (\fB\s-1OSSL_KDF_PARAM_MAC\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``mac'' (\fB\s-1OSSL_KDF_PARAM_MAC\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "mac (OSSL_KDF_PARAM_MAC) <UTF8 string>" +The value is either \s-1CMAC\s0 or \s-1HMAC.\s0 +.ie n .IP """digest"" (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_KDF_PARAM_DIGEST) <UTF8 string>" +.PD 0 +.ie n .IP """cipher"" (\fB\s-1OSSL_KDF_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``cipher'' (\fB\s-1OSSL_KDF_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "cipher (OSSL_KDF_PARAM_CIPHER) <UTF8 string>" +.ie n .IP """properties"" (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>" +.ie n .IP """key"" (\fB\s-1OSSL_KDF_PARAM_KEY\s0\fR) <octet string>" 4 +.el .IP "``key'' (\fB\s-1OSSL_KDF_PARAM_KEY\s0\fR) <octet string>" 4 +.IX Item "key (OSSL_KDF_PARAM_KEY) <octet string>" +.ie n .IP """salt"" (\fB\s-1OSSL_KDF_PARAM_SALT\s0\fR) <octet string>" 4 +.el .IP "``salt'' (\fB\s-1OSSL_KDF_PARAM_SALT\s0\fR) <octet string>" 4 +.IX Item "salt (OSSL_KDF_PARAM_SALT) <octet string>" +.IP """info (\fB\s-1OSSL_KDF_PARAM_INFO\s0\fR) <octet string>" 4 +.IX Item """info (OSSL_KDF_PARAM_INFO) <octet string>" +.ie n .IP """seed"" (\fB\s-1OSSL_KDF_PARAM_SEED\s0\fR) <octet string>" 4 +.el .IP "``seed'' (\fB\s-1OSSL_KDF_PARAM_SEED\s0\fR) <octet string>" 4 +.IX Item "seed (OSSL_KDF_PARAM_SEED) <octet string>" +.PD +The seed parameter is unused in counter mode. +.ie n .IP """use-l"" (\fB\s-1OSSL_KDF_PARAM_KBKDF_USE_L\s0\fR) <integer>" 4 +.el .IP "``use-l'' (\fB\s-1OSSL_KDF_PARAM_KBKDF_USE_L\s0\fR) <integer>" 4 +.IX Item "use-l (OSSL_KDF_PARAM_KBKDF_USE_L) <integer>" +Set to \fB0\fR to disable use of the optional Fixed Input data 'L' (see \s-1SP800\-108\s0). +The default value of \fB1\fR will be used if unspecified. +.ie n .IP """use-separator"" (\fB\s-1OSSL_KDF_PARAM_KBKDF_USE_SEPARATOR\s0\fR) <integer>" 4 +.el .IP "``use-separator'' (\fB\s-1OSSL_KDF_PARAM_KBKDF_USE_SEPARATOR\s0\fR) <integer>" 4 +.IX Item "use-separator (OSSL_KDF_PARAM_KBKDF_USE_SEPARATOR) <integer>" +Set to \fB0\fR to disable use of the optional Fixed Input data 'zero separator' +(see \s-1SP800\-108\s0) that is placed between the Label and Context. +The default value of \fB1\fR will be used if unspecified. +.PP +Depending on whether mac is \s-1CMAC\s0 or \s-1HMAC,\s0 either digest or cipher is required +(respectively) and the other is unused. +.PP +The parameters key, salt, info, and seed correspond to \s-1KI,\s0 Label, Context, and +\&\s-1IV\s0 (respectively) in \s-1SP800\-108.\s0 As in that document, salt, info, and seed are +optional and may be omitted. +.PP +\&\*(L"mac\*(R", \*(L"digest\*(R", cipher\*(L" and \*(R"properties" are described in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3). +.SH "NOTES" +.IX Header "NOTES" +A context for \s-1KBKDF\s0 can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); +.Ve +.PP +The output length of an \s-1KBKDF\s0 is specified via the \f(CW\*(C`keylen\*(C'\fR +parameter to the \fBEVP_KDF_derive\fR\|(3) function. +.PP +Note that currently OpenSSL only implements counter and feedback modes. Other +variants may be supported in the future. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +This example derives 10 bytes using \s-1COUNTER\-HMAC\-SHA256,\s0 with \s-1KI\s0 \*(L"secret\*(R", +Label \*(L"label\*(R", and Context \*(L"context\*(R". +.PP +.Vb 4 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& unsigned char out[10]; +\& OSSL_PARAM params[6], *p = params; +\& +\& kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, +\& "SHA2\-256", 0); +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, +\& "HMAC", 0); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, +\& "secret", strlen("secret")); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, +\& "label", strlen("label")); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, +\& "context", strlen("context")); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) +\& error("EVP_KDF_derive"); +\& +\& EVP_KDF_CTX_free(kctx); +.Ve +.PP +This example derives 10 bytes using \s-1FEEDBACK\-CMAC\-AES256,\s0 with \s-1KI\s0 \*(L"secret\*(R", +Label \*(L"label\*(R", and \s-1IV\s0 \*(L"sixteen bytes iv\*(R". +.PP +.Vb 5 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& unsigned char out[10]; +\& OSSL_PARAM params[8], *p = params; +\& unsigned char *iv = "sixteen bytes iv"; +\& +\& kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CIPHER, "AES256", 0); +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, "CMAC", 0); +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MODE, "FEEDBACK", 0); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, +\& "secret", strlen("secret")); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, +\& "label", strlen("label")); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, +\& "context", strlen("context")); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED, +\& iv, strlen(iv)); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) +\& error("EVP_KDF_derive"); +\& +\& EVP_KDF_CTX_free(kctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1NIST SP800\-108, IETF RFC 6803, IETF RFC 8009.\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_KDF\s0\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_get_kdf_size\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019 Red Hat, Inc. +.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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_KDF-KRB5KDF.7 b/secure/lib/libcrypto/man/man7/EVP_KDF-KRB5KDF.7 new file mode 100644 index 000000000000..374a45d2931f --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_KDF-KRB5KDF.7 @@ -0,0 +1,242 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_KDF-KRB5KDF 7ossl" +.TH EVP_KDF-KRB5KDF 7ossl "2023-09-19" "3.0.11" "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_KDF\-KRB5KDF \- The RFC3961 Krb5 KDF EVP_KDF implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing the \fB\s-1KRB5KDF\s0\fR \s-1KDF\s0 through the \fB\s-1EVP_KDF\s0\fR \s-1API.\s0 +.PP +The \s-1EVP_KDF\-KRB5KDF\s0 algorithm implements the key derivation function defined +in \s-1RFC 3961,\s0 section 5.1 and is used by Krb5 to derive session keys. +Three inputs are required to perform key derivation: a cipher, (for example +\&\s-1AES\-128\-CBC\s0), the initial key, and a constant. +.SS "Identity" +.IX Subsection "Identity" +\&\*(L"\s-1KRB5KDF\*(R"\s0 is the name for this implementation; +it can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.ie n .IP """properties"" (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>" +.PD 0 +.ie n .IP """cipher"" (\fB\s-1OSSL_KDF_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``cipher'' (\fB\s-1OSSL_KDF_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "cipher (OSSL_KDF_PARAM_CIPHER) <UTF8 string>" +.ie n .IP """key"" (\fB\s-1OSSL_KDF_PARAM_KEY\s0\fR) <octet string>" 4 +.el .IP "``key'' (\fB\s-1OSSL_KDF_PARAM_KEY\s0\fR) <octet string>" 4 +.IX Item "key (OSSL_KDF_PARAM_KEY) <octet string>" +.PD +These parameters work as described in \*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3). +.ie n .IP """constant"" (\fB\s-1OSSL_KDF_PARAM_CONSTANT\s0\fR) <octet string>" 4 +.el .IP "``constant'' (\fB\s-1OSSL_KDF_PARAM_CONSTANT\s0\fR) <octet string>" 4 +.IX Item "constant (OSSL_KDF_PARAM_CONSTANT) <octet string>" +This parameter sets the constant value for the \s-1KDF.\s0 +If a value is already set, the contents are replaced. +.SH "NOTES" +.IX Header "NOTES" +A context for \s-1KRB5KDF\s0 can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "KRB5KDF", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); +.Ve +.PP +The output length of the \s-1KRB5KDF\s0 derivation is specified via the \fIkeylen\fR +parameter to the \fBEVP_KDF_derive\fR\|(3) function, and \s-1MUST\s0 match the key +length for the chosen cipher or an error is returned. Moreover, the +constant's length must not exceed the block size of the cipher. +Since the \s-1KRB5KDF\s0 output length depends on the chosen cipher, calling +\&\fBEVP_KDF_CTX_get_kdf_size\fR\|(3) to obtain the requisite length returns the correct length +only after the cipher is set. Prior to that \fB\s-1EVP_MAX_KEY_LENGTH\s0\fR is returned. +The caller must allocate a buffer of the correct length for the chosen +cipher, and pass that buffer to the \fBEVP_KDF_derive\fR\|(3) function along +with that length. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +This example derives a key using the \s-1AES\-128\-CBC\s0 cipher: +.PP +.Vb 7 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& unsigned char key[16] = "01234..."; +\& unsigned char constant[] = "I\*(Aqm a constant"; +\& unsigned char out[16]; +\& size_t outlen = sizeof(out); +\& OSSL_PARAM params[4], *p = params; +\& +\& kdf = EVP_KDF_fetch(NULL, "KRB5KDF", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CIPHER, +\& SN_aes_128_cbc, +\& strlen(SN_aes_128_cbc)); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, +\& key, (size_t)16); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_CONSTANT, +\& constant, strlen(constant)); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, outlen, params) <= 0) +\& /* Error */ +\& +\& EVP_KDF_CTX_free(kctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1RFC 3961\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_KDF\s0\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_get_kdf_size\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2016\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_KDF-PBKDF1.7 b/secure/lib/libcrypto/man/man7/EVP_KDF-PBKDF1.7 new file mode 100644 index 000000000000..71875fe44e42 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_KDF-PBKDF1.7 @@ -0,0 +1,210 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_KDF-PBKDF1 7ossl" +.TH EVP_KDF-PBKDF1 7ossl "2023-09-19" "3.0.11" "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_KDF\-PBKDF1 \- The PBKDF1 EVP_KDF implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing the \fB\s-1PBKDF1\s0\fR password-based \s-1KDF\s0 through the \fB\s-1EVP_KDF\s0\fR +\&\s-1API.\s0 +.PP +The \s-1EVP_KDF\-PBKDF1\s0 algorithm implements the \s-1PBKDF1\s0 password-based key +derivation function, as described in \s-1RFC 8018\s0; it derives a key from a password +using a salt and iteration count. +.SS "Identity" +.IX Subsection "Identity" +\&\*(L"\s-1PBKDF1\*(R"\s0 is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.ie n .IP """pass"" (\fB\s-1OSSL_KDF_PARAM_PASSWORD\s0\fR) <octet string>" 4 +.el .IP "``pass'' (\fB\s-1OSSL_KDF_PARAM_PASSWORD\s0\fR) <octet string>" 4 +.IX Item "pass (OSSL_KDF_PARAM_PASSWORD) <octet string>" +.PD 0 +.ie n .IP """salt"" (\fB\s-1OSSL_KDF_PARAM_SALT\s0\fR) <octet string>" 4 +.el .IP "``salt'' (\fB\s-1OSSL_KDF_PARAM_SALT\s0\fR) <octet string>" 4 +.IX Item "salt (OSSL_KDF_PARAM_SALT) <octet string>" +.ie n .IP """iter"" (\fB\s-1OSSL_KDF_PARAM_ITER\s0\fR) <unsigned integer>" 4 +.el .IP "``iter'' (\fB\s-1OSSL_KDF_PARAM_ITER\s0\fR) <unsigned integer>" 4 +.IX Item "iter (OSSL_KDF_PARAM_ITER) <unsigned integer>" +.PD +This parameter has a default value of 0 and should be set. +.ie n .IP """properties"" (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>" +.PD 0 +.ie n .IP """digest"" (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_KDF_PARAM_DIGEST) <UTF8 string>" +.PD +These parameters work as described in \*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3). +.SH "NOTES" +.IX Header "NOTES" +A typical application of this algorithm is to derive keying material for an +encryption algorithm from a password in the \*(L"pass\*(R", a salt in \*(L"salt\*(R", +and an iteration count. +.PP +Increasing the \*(L"iter\*(R" parameter slows down the algorithm which makes it +harder for an attacker to perform a brute force attack using a large number +of candidate passwords. +.PP +No assumption is made regarding the given password; it is simply treated as a +byte sequence. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1RFC 8018\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_KDF\s0\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_KDF-PBKDF2.7 b/secure/lib/libcrypto/man/man7/EVP_KDF-PBKDF2.7 new file mode 100644 index 000000000000..b68738ab2964 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_KDF-PBKDF2.7 @@ -0,0 +1,234 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_KDF-PBKDF2 7ossl" +.TH EVP_KDF-PBKDF2 7ossl "2023-09-19" "3.0.11" "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_KDF\-PBKDF2 \- The PBKDF2 EVP_KDF implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing the \fB\s-1PBKDF2\s0\fR password-based \s-1KDF\s0 through the \fB\s-1EVP_KDF\s0\fR +\&\s-1API.\s0 +.PP +The \s-1EVP_KDF\-PBKDF2\s0 algorithm implements the \s-1PBKDF2\s0 password-based key +derivation function, as described in \s-1SP800\-132\s0; it derives a key from a password +using a salt and iteration count. +.SS "Identity" +.IX Subsection "Identity" +\&\*(L"\s-1PBKDF2\*(R"\s0 is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.ie n .IP """pass"" (\fB\s-1OSSL_KDF_PARAM_PASSWORD\s0\fR) <octet string>" 4 +.el .IP "``pass'' (\fB\s-1OSSL_KDF_PARAM_PASSWORD\s0\fR) <octet string>" 4 +.IX Item "pass (OSSL_KDF_PARAM_PASSWORD) <octet string>" +.PD 0 +.ie n .IP """salt"" (\fB\s-1OSSL_KDF_PARAM_SALT\s0\fR) <octet string>" 4 +.el .IP "``salt'' (\fB\s-1OSSL_KDF_PARAM_SALT\s0\fR) <octet string>" 4 +.IX Item "salt (OSSL_KDF_PARAM_SALT) <octet string>" +.ie n .IP """iter"" (\fB\s-1OSSL_KDF_PARAM_ITER\s0\fR) <unsigned integer>" 4 +.el .IP "``iter'' (\fB\s-1OSSL_KDF_PARAM_ITER\s0\fR) <unsigned integer>" 4 +.IX Item "iter (OSSL_KDF_PARAM_ITER) <unsigned integer>" +.PD +This parameter has a default value of 2048. +.ie n .IP """properties"" (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>" +.PD 0 +.ie n .IP """digest"" (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_KDF_PARAM_DIGEST) <UTF8 string>" +.PD +These parameters work as described in \*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3). +.ie n .IP """pkcs5"" (\fB\s-1OSSL_KDF_PARAM_PKCS5\s0\fR) <integer>" 4 +.el .IP "``pkcs5'' (\fB\s-1OSSL_KDF_PARAM_PKCS5\s0\fR) <integer>" 4 +.IX Item "pkcs5 (OSSL_KDF_PARAM_PKCS5) <integer>" +This parameter can be used to enable or disable \s-1SP800\-132\s0 compliance checks. +Setting the mode to 0 enables the compliance checks. +.Sp +The checks performed are: +.RS 4 +.IP "\- the iteration count is at least 1000." 4 +.IX Item "- the iteration count is at least 1000." +.PD 0 +.IP "\- the salt length is at least 128 bits." 4 +.IX Item "- the salt length is at least 128 bits." +.IP "\- the derived key length is at least 112 bits." 4 +.IX Item "- the derived key length is at least 112 bits." +.RE +.RS 4 +.PD +.Sp +The default provider uses a default mode of 1 for backwards compatibility, +and the \s-1FIPS\s0 provider uses a default mode of 0. +.Sp +The value string is expected to be a decimal number 0 or 1. +.RE +.SH "NOTES" +.IX Header "NOTES" +A typical application of this algorithm is to derive keying material for an +encryption algorithm from a password in the \*(L"pass\*(R", a salt in \*(L"salt\*(R", +and an iteration count. +.PP +Increasing the \*(L"iter\*(R" parameter slows down the algorithm which makes it +harder for an attacker to perform a brute force attack using a large number +of candidate passwords. +.PP +No assumption is made regarding the given password; it is simply treated as a +byte sequence. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1SP800\-132\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_KDF\s0\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2018\-2022 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_KDF-PKCS12KDF.7 b/secure/lib/libcrypto/man/man7/EVP_KDF-PKCS12KDF.7 new file mode 100644 index 000000000000..48e726a12187 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_KDF-PKCS12KDF.7 @@ -0,0 +1,217 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_KDF-PKCS12KDF 7ossl" +.TH EVP_KDF-PKCS12KDF 7ossl "2023-09-19" "3.0.11" "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_KDF\-PKCS12KDF \- The PKCS#12 EVP_KDF implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing the \fBPKCS#12\fR password-based \s-1KDF\s0 through the \fB\s-1EVP_KDF\s0\fR +\&\s-1API.\s0 +.PP +The \s-1EVP_KDF\-PKCS12KDF\s0 algorithm implements the PKCS#12 password-based key +derivation function, as described in appendix B of \s-1RFC 7292\s0 (\s-1PKCS\s0 #12: +Personal Information Exchange Syntax); it derives a key from a password +using a salt, iteration count and the intended usage. +.SS "Identity" +.IX Subsection "Identity" +\&\*(L"\s-1PKCS12KDF\*(R"\s0 is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.ie n .IP """pass"" (\fB\s-1OSSL_KDF_PARAM_PASSWORD\s0\fR) <octet string>" 4 +.el .IP "``pass'' (\fB\s-1OSSL_KDF_PARAM_PASSWORD\s0\fR) <octet string>" 4 +.IX Item "pass (OSSL_KDF_PARAM_PASSWORD) <octet string>" +.PD 0 +.ie n .IP """salt"" (\fB\s-1OSSL_KDF_PARAM_SALT\s0\fR) <octet string>" 4 +.el .IP "``salt'' (\fB\s-1OSSL_KDF_PARAM_SALT\s0\fR) <octet string>" 4 +.IX Item "salt (OSSL_KDF_PARAM_SALT) <octet string>" +.ie n .IP """iter"" (\fB\s-1OSSL_KDF_PARAM_ITER\s0\fR) <unsigned integer>" 4 +.el .IP "``iter'' (\fB\s-1OSSL_KDF_PARAM_ITER\s0\fR) <unsigned integer>" 4 +.IX Item "iter (OSSL_KDF_PARAM_ITER) <unsigned integer>" +.ie n .IP """properties"" (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>" +.ie n .IP """digest"" (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_KDF_PARAM_DIGEST) <UTF8 string>" +.PD +These parameters work as described in \*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3). +.ie n .IP """id"" (\fB\s-1OSSL_KDF_PARAM_PKCS12_ID\s0\fR) <integer>" 4 +.el .IP "``id'' (\fB\s-1OSSL_KDF_PARAM_PKCS12_ID\s0\fR) <integer>" 4 +.IX Item "id (OSSL_KDF_PARAM_PKCS12_ID) <integer>" +This parameter is used to specify the intended usage of the output bits, as per +\&\s-1RFC 7292\s0 section B.3. +.SH "NOTES" +.IX Header "NOTES" +This algorithm is not available in the \s-1FIPS\s0 provider as it is not \s-1FIPS\s0 +approvable. +.PP +A typical application of this algorithm is to derive keying material for an +encryption algorithm from a password in the \*(L"pass\*(R", a salt in \*(L"salt\*(R", +and an iteration count. +.PP +Increasing the \*(L"iter\*(R" parameter slows down the algorithm which makes it +harder for an attacker to perform a brute force attack using a large number +of candidate passwords. +.PP +No assumption is made regarding the given password; it is simply treated as a +byte sequence. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1RFC7292\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_KDF\s0\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3), +\&\s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2023 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>. diff --git a/secure/lib/libcrypto/man/man7/scrypt.7 b/secure/lib/libcrypto/man/man7/EVP_KDF-SCRYPT.7 index 08089461653e..5b84dbfe0d24 100644 --- a/secure/lib/libcrypto/man/man7/scrypt.7 +++ b/secure/lib/libcrypto/man/man7/EVP_KDF-SCRYPT.7 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .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 \{\ @@ -132,17 +130,20 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "SCRYPT 7" -.TH SCRYPT 7 "2022-06-21" "1.1.1p" "OpenSSL" +.IX Title "EVP_KDF-SCRYPT 7ossl" +.TH EVP_KDF-SCRYPT 7ossl "2023-09-19" "3.0.11" "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" -scrypt \- EVP_PKEY scrypt KDF support +EVP_KDF\-SCRYPT \- The scrypt EVP_KDF implementation .SH "DESCRIPTION" .IX Header "DESCRIPTION" -The \s-1EVP_PKEY_SCRYPT\s0 algorithm implements the scrypt password based key +Support for computing the \fBscrypt\fR password-based \s-1KDF\s0 through the \fB\s-1EVP_KDF\s0\fR +\&\s-1API.\s0 +.PP +The \s-1EVP_KDF\-SCRYPT\s0 algorithm implements the scrypt password-based key derivation function, as described in \s-1RFC 7914.\s0 It is memory-hard in the sense that it deliberately requires a significant amount of \s-1RAM\s0 for efficient computation. The intention of this is to render brute forcing of passwords on @@ -162,50 +163,82 @@ computation time of less than 5 seconds on a 2.5 GHz Intel Core 2 Duo are N = 2^20 = 1048576, r = 8, p = 1. Consequently, the required amount of memory for this computation is roughly 1 GiB. On a more recent \s-1CPU\s0 (Intel i7\-5930K at 3.5 GHz), this computation takes about 3 seconds. When N, r or p are not specified, -they default to 1048576, 8, and 1, respectively. The default amount of \s-1RAM\s0 that +they default to 1048576, 8, and 1, respectively. The maximum amount of \s-1RAM\s0 that may be used by scrypt defaults to 1025 MiB. +.SS "Identity" +.IX Subsection "Identity" +\&\*(L"\s-1SCRYPT\*(R"\s0 is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.ie n .IP """pass"" (\fB\s-1OSSL_KDF_PARAM_PASSWORD\s0\fR) <octet string>" 4 +.el .IP "``pass'' (\fB\s-1OSSL_KDF_PARAM_PASSWORD\s0\fR) <octet string>" 4 +.IX Item "pass (OSSL_KDF_PARAM_PASSWORD) <octet string>" +.PD 0 +.ie n .IP """salt"" (\fB\s-1OSSL_KDF_PARAM_SALT\s0\fR) <octet string>" 4 +.el .IP "``salt'' (\fB\s-1OSSL_KDF_PARAM_SALT\s0\fR) <octet string>" 4 +.IX Item "salt (OSSL_KDF_PARAM_SALT) <octet string>" +.PD +These parameters work as described in \*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3). +.ie n .IP """n"" (\fB\s-1OSSL_KDF_PARAM_SCRYPT_N\s0\fR) <unsigned integer>" 4 +.el .IP "``n'' (\fB\s-1OSSL_KDF_PARAM_SCRYPT_N\s0\fR) <unsigned integer>" 4 +.IX Item "n (OSSL_KDF_PARAM_SCRYPT_N) <unsigned integer>" +.PD 0 +.ie n .IP """r"" (\fB\s-1OSSL_KDF_PARAM_SCRYPT_R\s0\fR) <unsigned integer>" 4 +.el .IP "``r'' (\fB\s-1OSSL_KDF_PARAM_SCRYPT_R\s0\fR) <unsigned integer>" 4 +.IX Item "r (OSSL_KDF_PARAM_SCRYPT_R) <unsigned integer>" +.ie n .IP """p"" (\fB\s-1OSSL_KDF_PARAM_SCRYPT_P\s0\fR) <unsigned integer>" 4 +.el .IP "``p'' (\fB\s-1OSSL_KDF_PARAM_SCRYPT_P\s0\fR) <unsigned integer>" 4 +.IX Item "p (OSSL_KDF_PARAM_SCRYPT_P) <unsigned integer>" +.ie n .IP """maxmem_bytes"" (\fB\s-1OSSL_KDF_PARAM_SCRYPT_MAXMEM\s0\fR) <unsigned integer>" 4 +.el .IP "``maxmem_bytes'' (\fB\s-1OSSL_KDF_PARAM_SCRYPT_MAXMEM\s0\fR) <unsigned integer>" 4 +.IX Item "maxmem_bytes (OSSL_KDF_PARAM_SCRYPT_MAXMEM) <unsigned integer>" +.PD +These parameters configure the scrypt work factors N, r, maxmem and p. +Both N and maxmem_bytes are parameters of type \fBuint64_t\fR. +Both r and p are parameters of type \fBuint32_t\fR. +.ie n .IP """properties"" (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>" +This can be used to set the property query string when fetching the +fixed digest internally. \s-1NULL\s0 is used if this value is not set. .SH "NOTES" .IX Header "NOTES" A context for scrypt can be obtained by calling: .PP -.Vb 1 -\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_SCRYPT, NULL); +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SCRYPT", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); .Ve .PP The output length of an scrypt key derivation is specified via the -length parameter to the \fBEVP_PKEY_derive\fR\|(3) function. +\&\*(L"keylen\*(R" parameter to the \fBEVP_KDF_derive\fR\|(3) function. .SH "EXAMPLES" .IX Header "EXAMPLES" -This example derives a 64\-byte long test vector using scrypt using the password +This example derives a 64\-byte long test vector using scrypt with the password \&\*(L"password\*(R", salt \*(L"NaCl\*(R" and N = 1024, r = 8, p = 16. .PP -.Vb 2 -\& EVP_PKEY_CTX *pctx; +.Vb 4 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; \& unsigned char out[64]; +\& OSSL_PARAM params[6], *p = params; \& -\& size_t outlen = sizeof(out); -\& pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_SCRYPT, NULL); +\& kdf = EVP_KDF_fetch(NULL, "SCRYPT", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); \& -\& if (EVP_PKEY_derive_init(pctx) <= 0) { -\& error("EVP_PKEY_derive_init"); -\& } -\& if (EVP_PKEY_CTX_set1_pbe_pass(pctx, "password", 8) <= 0) { -\& error("EVP_PKEY_CTX_set1_pbe_pass"); -\& } -\& if (EVP_PKEY_CTX_set1_scrypt_salt(pctx, "NaCl", 4) <= 0) { -\& error("EVP_PKEY_CTX_set1_scrypt_salt"); -\& } -\& if (EVP_PKEY_CTX_set_scrypt_N(pctx, 1024) <= 0) { -\& error("EVP_PKEY_CTX_set_scrypt_N"); -\& } -\& if (EVP_PKEY_CTX_set_scrypt_r(pctx, 8) <= 0) { -\& error("EVP_PKEY_CTX_set_scrypt_r"); -\& } -\& if (EVP_PKEY_CTX_set_scrypt_p(pctx, 16) <= 0) { -\& error("EVP_PKEY_CTX_set_scrypt_p"); -\& } -\& if (EVP_PKEY_derive(pctx, out, &outlen) <= 0) { -\& error("EVP_PKEY_derive"); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_PASSWORD, +\& "password", (size_t)8); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, +\& "NaCl", (size_t)4); +\& *p++ = OSSL_PARAM_construct_uint64(OSSL_KDF_PARAM_SCRYPT_N, (uint64_t)1024); +\& *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_R, (uint32_t)8); +\& *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_P, (uint32_t)16); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { +\& error("EVP_KDF_derive"); \& } \& \& { @@ -223,26 +256,27 @@ This example derives a 64\-byte long test vector using scrypt using the password \& assert(!memcmp(out, expected, sizeof(out))); \& } \& -\& EVP_PKEY_CTX_free(pctx); +\& EVP_KDF_CTX_free(kctx); .Ve .SH "CONFORMING TO" .IX Header "CONFORMING TO" \&\s-1RFC 7914\s0 .SH "SEE ALSO" .IX Header "SEE ALSO" -\&\fBEVP_PKEY_CTX_set1_scrypt_salt\fR\|(3), -\&\fBEVP_PKEY_CTX_set_scrypt_N\fR\|(3), -\&\fBEVP_PKEY_CTX_set_scrypt_r\fR\|(3), -\&\fBEVP_PKEY_CTX_set_scrypt_p\fR\|(3), -\&\fBEVP_PKEY_CTX_set_scrypt_maxmem_bytes\fR\|(3), -\&\fBEVP_PKEY_CTX_new\fR\|(3), -\&\fBEVP_PKEY_CTX_ctrl_str\fR\|(3), -\&\fBEVP_PKEY_derive\fR\|(3) +\&\s-1\fBEVP_KDF\s0\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2017\-2019 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_KDF-SS.7 b/secure/lib/libcrypto/man/man7/EVP_KDF-SS.7 new file mode 100644 index 000000000000..f76307b3716b --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_KDF-SS.7 @@ -0,0 +1,321 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_KDF-SS 7ossl" +.TH EVP_KDF-SS 7ossl "2023-09-19" "3.0.11" "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_KDF\-SS \- The Single Step / One Step EVP_KDF implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \s-1EVP_KDF\-SS\s0 algorithm implements the Single Step key derivation function (\s-1SSKDF\s0). +\&\s-1SSKDF\s0 derives a key using input such as a shared secret key (that was generated +during the execution of a key establishment scheme) and fixedinfo. +\&\s-1SSKDF\s0 is also informally referred to as 'Concat \s-1KDF\s0'. +.SS "Auxiliary function" +.IX Subsection "Auxiliary function" +The implementation uses a selectable auxiliary function H, which can be one of: +.IP "\fBH(x) = hash(x, digest=md)\fR" 4 +.IX Item "H(x) = hash(x, digest=md)" +.PD 0 +.IP "\fBH(x) = HMAC_hash(x, key=salt, digest=md)\fR" 4 +.IX Item "H(x) = HMAC_hash(x, key=salt, digest=md)" +.ie n .IP "\fBH(x) = KMACxxx(x, key=salt, custom=""\s-1KDF"",\s0 outlen=mac_size)\fR" 4 +.el .IP "\fBH(x) = KMACxxx(x, key=salt, custom=``\s-1KDF'',\s0 outlen=mac_size)\fR" 4 +.IX Item "H(x) = KMACxxx(x, key=salt, custom=KDF, outlen=mac_size)" +.PD +.PP +Both the \s-1HMAC\s0 and \s-1KMAC\s0 implementations set the key using the 'salt' value. +The hash and \s-1HMAC\s0 also require the digest to be set. +.SS "Identity" +.IX Subsection "Identity" +\&\*(L"\s-1SSKDF\*(R"\s0 is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.ie n .IP """properties"" (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>" +.PD 0 +.ie n .IP """digest"" (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_KDF_PARAM_DIGEST) <UTF8 string>" +.PD +This parameter is ignored for \s-1KMAC.\s0 +.ie n .IP """mac"" (\fB\s-1OSSL_KDF_PARAM_MAC\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``mac'' (\fB\s-1OSSL_KDF_PARAM_MAC\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "mac (OSSL_KDF_PARAM_MAC) <UTF8 string>" +.PD 0 +.ie n .IP """maclen"" (\fB\s-1OSSL_KDF_PARAM_MAC_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``maclen'' (\fB\s-1OSSL_KDF_PARAM_MAC_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "maclen (OSSL_KDF_PARAM_MAC_SIZE) <unsigned integer>" +.ie n .IP """salt"" (\fB\s-1OSSL_KDF_PARAM_SALT\s0\fR) <octet string>" 4 +.el .IP "``salt'' (\fB\s-1OSSL_KDF_PARAM_SALT\s0\fR) <octet string>" 4 +.IX Item "salt (OSSL_KDF_PARAM_SALT) <octet string>" +.PD +These parameters work as described in \*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3). +.ie n .IP """key"" (\fB\s-1EVP_KDF_CTRL_SET_KEY\s0\fR) <octet string>" 4 +.el .IP "``key'' (\fB\s-1EVP_KDF_CTRL_SET_KEY\s0\fR) <octet string>" 4 +.IX Item "key (EVP_KDF_CTRL_SET_KEY) <octet string>" +This parameter set the shared secret that is used for key derivation. +.ie n .IP """info"" (\fB\s-1OSSL_KDF_PARAM_INFO\s0\fR) <octet string>" 4 +.el .IP "``info'' (\fB\s-1OSSL_KDF_PARAM_INFO\s0\fR) <octet string>" 4 +.IX Item "info (OSSL_KDF_PARAM_INFO) <octet string>" +This parameter sets an optional value for fixedinfo, also known as otherinfo. +.SH "NOTES" +.IX Header "NOTES" +A context for \s-1SSKDF\s0 can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); +.Ve +.PP +The output length of an \s-1SSKDF\s0 is specified via the \fIkeylen\fR +parameter to the \fBEVP_KDF_derive\fR\|(3) function. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +This example derives 10 bytes using H(x) = \s-1SHA\-256,\s0 with the secret key \*(L"secret\*(R" +and fixedinfo value \*(L"label\*(R": +.PP +.Vb 4 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& unsigned char out[10]; +\& OSSL_PARAM params[4], *p = params; +\& +\& kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, +\& SN_sha256, strlen(SN_sha256)); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, +\& "secret", (size_t)6); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, +\& "label", (size_t)5); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { +\& error("EVP_KDF_derive"); +\& } +\& +\& EVP_KDF_CTX_free(kctx); +.Ve +.PP +This example derives 10 bytes using H(x) = \s-1HMAC\s0(\s-1SHA\-256\s0), with the secret key \*(L"secret\*(R", +fixedinfo value \*(L"label\*(R" and salt \*(L"salt\*(R": +.PP +.Vb 4 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& unsigned char out[10]; +\& OSSL_PARAM params[6], *p = params; +\& +\& kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, +\& SN_hmac, strlen(SN_hmac)); +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, +\& SN_sha256, strlen(SN_sha256)); +\& *p++ = OSSL_PARAM_construct_octet_string(EVP_KDF_CTRL_SET_KEY, +\& "secret", (size_t)6); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, +\& "label", (size_t)5); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, +\& "salt", (size_t)4); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { +\& error("EVP_KDF_derive"); +\& } +\& +\& EVP_KDF_CTX_free(kctx); +.Ve +.PP +This example derives 10 bytes using H(x) = \s-1KMAC128\s0(x,salt,outlen), with the secret key \*(L"secret\*(R" +fixedinfo value \*(L"label\*(R", salt of \*(L"salt\*(R" and \s-1KMAC\s0 outlen of 20: +.PP +.Vb 4 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& unsigned char out[10]; +\& OSSL_PARAM params[6], *p = params; +\& +\& kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, +\& SN_kmac128, strlen(SN_kmac128)); +\& *p++ = OSSL_PARAM_construct_octet_string(EVP_KDF_CTRL_SET_KEY, +\& "secret", (size_t)6); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, +\& "label", (size_t)5); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, +\& "salt", (size_t)4); +\& *p++ = OSSL_PARAM_construct_size_t(OSSL_KDF_PARAM_MAC_SIZE, (size_t)20); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { +\& error("EVP_KDF_derive"); +\& } +\& +\& EVP_KDF_CTX_free(kctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1NIST\s0 SP800\-56Cr1. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_KDF\s0\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_CTX_get_kdf_size\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2019\-2023 The OpenSSL Project Authors. All Rights Reserved. Copyright +(c) 2019, Oracle and/or its affiliates. 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_KDF-SSHKDF.7 b/secure/lib/libcrypto/man/man7/EVP_KDF-SSHKDF.7 new file mode 100644 index 000000000000..feccc434bbc5 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_KDF-SSHKDF.7 @@ -0,0 +1,284 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_KDF-SSHKDF 7ossl" +.TH EVP_KDF-SSHKDF 7ossl "2023-09-19" "3.0.11" "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_KDF\-SSHKDF \- The SSHKDF EVP_KDF implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing the \fB\s-1SSHKDF\s0\fR \s-1KDF\s0 through the \fB\s-1EVP_KDF\s0\fR \s-1API.\s0 +.PP +The \s-1EVP_KDF\-SSHKDF\s0 algorithm implements the \s-1SSHKDF\s0 key derivation function. +It is defined in \s-1RFC 4253,\s0 section 7.2 and is used by \s-1SSH\s0 to derive IVs, +encryption keys and integrity keys. +Five inputs are required to perform key derivation: The hashing function +(for example \s-1SHA256\s0), the Initial Key, the Exchange Hash, the Session \s-1ID,\s0 +and the derivation key type. +.SS "Identity" +.IX Subsection "Identity" +\&\*(L"\s-1SSHKDF\*(R"\s0 is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.ie n .IP """properties"" (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>" +.PD 0 +.ie n .IP """digest"" (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_KDF_PARAM_DIGEST) <UTF8 string>" +.ie n .IP """key"" (\fB\s-1OSSL_KDF_PARAM_KEY\s0\fR) <octet string>" 4 +.el .IP "``key'' (\fB\s-1OSSL_KDF_PARAM_KEY\s0\fR) <octet string>" 4 +.IX Item "key (OSSL_KDF_PARAM_KEY) <octet string>" +.PD +These parameters work as described in \*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3). +.ie n .IP """xcghash"" (\fB\s-1OSSL_KDF_PARAM_SSHKDF_XCGHASH\s0\fR) <octet string>" 4 +.el .IP "``xcghash'' (\fB\s-1OSSL_KDF_PARAM_SSHKDF_XCGHASH\s0\fR) <octet string>" 4 +.IX Item "xcghash (OSSL_KDF_PARAM_SSHKDF_XCGHASH) <octet string>" +.PD 0 +.ie n .IP """session_id"" (\fB\s-1OSSL_KDF_PARAM_SSHKDF_SESSION_ID\s0\fR) <octet string>" 4 +.el .IP "``session_id'' (\fB\s-1OSSL_KDF_PARAM_SSHKDF_SESSION_ID\s0\fR) <octet string>" 4 +.IX Item "session_id (OSSL_KDF_PARAM_SSHKDF_SESSION_ID) <octet string>" +.PD +These parameters set the respective values for the \s-1KDF.\s0 +If a value is already set, the contents are replaced. +.ie n .IP """type"" (\fB\s-1OSSL_KDF_PARAM_SSHKDF_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``type'' (\fB\s-1OSSL_KDF_PARAM_SSHKDF_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "type (OSSL_KDF_PARAM_SSHKDF_TYPE) <UTF8 string>" +This parameter sets the type for the \s-1SSHKDF\s0 operation. +There are six supported types: +.RS 4 +.IP "\s-1EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV\s0" 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV" +The Initial \s-1IV\s0 from client to server. +A single char of value 65 (\s-1ASCII\s0 char 'A'). +.IP "\s-1EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI\s0" 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI" +The Initial \s-1IV\s0 from server to client +A single char of value 66 (\s-1ASCII\s0 char 'B'). +.IP "\s-1EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV\s0" 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV" +The Encryption Key from client to server +A single char of value 67 (\s-1ASCII\s0 char 'C'). +.IP "\s-1EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI\s0" 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI" +The Encryption Key from server to client +A single char of value 68 (\s-1ASCII\s0 char 'D'). +.IP "\s-1EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV\s0" 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV" +The Integrity Key from client to server +A single char of value 69 (\s-1ASCII\s0 char 'E'). +.IP "\s-1EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI\s0" 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI" +The Integrity Key from client to server +A single char of value 70 (\s-1ASCII\s0 char 'F'). +.RE +.RS 4 +.RE +.SH "NOTES" +.IX Header "NOTES" +A context for \s-1SSHKDF\s0 can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); +.Ve +.PP +The output length of the \s-1SSHKDF\s0 derivation is specified via the \fIkeylen\fR +parameter to the \fBEVP_KDF_derive\fR\|(3) function. +Since the \s-1SSHKDF\s0 output length is variable, calling \fBEVP_KDF_CTX_get_kdf_size\fR\|(3) +to obtain the requisite length is not meaningful. The caller must +allocate a buffer of the desired length, and pass that buffer to the +\&\fBEVP_KDF_derive\fR\|(3) function along with the desired length. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +This example derives an 8 byte \s-1IV\s0 using \s-1SHA\-256\s0 with a 1K \*(L"key\*(R" and appropriate +\&\*(L"xcghash\*(R" and \*(L"session_id\*(R" values: +.PP +.Vb 9 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& char type = EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV; +\& unsigned char key[1024] = "01234..."; +\& unsigned char xcghash[32] = "012345..."; +\& unsigned char session_id[32] = "012345..."; +\& unsigned char out[8]; +\& size_t outlen = sizeof(out); +\& OSSL_PARAM params[6], *p = params; +\& +\& kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, +\& SN_sha256, strlen(SN_sha256)); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, +\& key, (size_t)1024); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_XCGHASH, +\& xcghash, (size_t)32); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_SESSION_ID, +\& session_id, (size_t)32); +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_SSHKDF_TYPE, +\& &type, sizeof(type)); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, outlen, params) <= 0) +\& /* Error */ +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1RFC 4253\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_KDF\s0\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_CTX_get_kdf_size\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2016\-2022 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_KDF-TLS13_KDF.7 b/secure/lib/libcrypto/man/man7/EVP_KDF-TLS13_KDF.7 new file mode 100644 index 000000000000..0cf37210f47b --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_KDF-TLS13_KDF.7 @@ -0,0 +1,260 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_KDF-TLS13_KDF 7ossl" +.TH EVP_KDF-TLS13_KDF 7ossl "2023-09-19" "3.0.11" "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_KDF\-TLS13_KDF \- The TLS 1.3 EVP_KDF implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing the \s-1TLS 1.3\s0 version of the \fB\s-1HKDF\s0\fR \s-1KDF\s0 through +the \fB\s-1EVP_KDF\s0\fR \s-1API.\s0 +.PP +The \s-1EVP_KDF\-TLS13_KDF\s0 algorithm implements the \s-1HKDF\s0 key derivation function +as used by \s-1TLS 1.3.\s0 +.SS "Identity" +.IX Subsection "Identity" +\&\*(L"\s-1TLS13\-KDF\*(R"\s0 is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.ie n .IP """properties"" (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>" +.PD 0 +.ie n .IP """digest"" (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_KDF_PARAM_DIGEST) <UTF8 string>" +.ie n .IP """key"" (\fB\s-1OSSL_KDF_PARAM_KEY\s0\fR) <octet string>" 4 +.el .IP "``key'' (\fB\s-1OSSL_KDF_PARAM_KEY\s0\fR) <octet string>" 4 +.IX Item "key (OSSL_KDF_PARAM_KEY) <octet string>" +.ie n .IP """salt"" (\fB\s-1OSSL_KDF_PARAM_SALT\s0\fR) <octet string>" 4 +.el .IP "``salt'' (\fB\s-1OSSL_KDF_PARAM_SALT\s0\fR) <octet string>" 4 +.IX Item "salt (OSSL_KDF_PARAM_SALT) <octet string>" +.PD +These parameters work as described in \*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3). +.ie n .IP """prefix"" (\fB\s-1OSSL_KDF_PARAM_PREFIX\s0\fR) <octet string>" 4 +.el .IP "``prefix'' (\fB\s-1OSSL_KDF_PARAM_PREFIX\s0\fR) <octet string>" 4 +.IX Item "prefix (OSSL_KDF_PARAM_PREFIX) <octet string>" +This parameter sets the label prefix on the specified \s-1TLS 1.3 KDF\s0 context. +For \s-1TLS 1.3\s0 this should be set to the \s-1ASCII\s0 string \*(L"tls13 \*(R" without a +trailing zero byte. Refer to \s-1RFC 8446\s0 section 7.1 \*(L"Key Schedule\*(R" for details. +.ie n .IP """label"" (\fB\s-1OSSL_KDF_PARAM_LABEL\s0\fR) <octet string>" 4 +.el .IP "``label'' (\fB\s-1OSSL_KDF_PARAM_LABEL\s0\fR) <octet string>" 4 +.IX Item "label (OSSL_KDF_PARAM_LABEL) <octet string>" +This parameter sets the label on the specified \s-1TLS 1.3 KDF\s0 context. +Refer to \s-1RFC 8446\s0 section 7.1 \*(L"Key Schedule\*(R" for details. +.ie n .IP """data"" (\fB\s-1OSSL_KDF_PARAM_DATA\s0\fR) <octet string>" 4 +.el .IP "``data'' (\fB\s-1OSSL_KDF_PARAM_DATA\s0\fR) <octet string>" 4 +.IX Item "data (OSSL_KDF_PARAM_DATA) <octet string>" +This parameter sets the context data on the specified \s-1TLS 1.3 KDF\s0 context. +Refer to \s-1RFC 8446\s0 section 7.1 \*(L"Key Schedule\*(R" for details. +.ie n .IP """mode"" (\fB\s-1OSSL_KDF_PARAM_MODE\s0\fR) <\s-1UTF8\s0 string> or <integer>" 4 +.el .IP "``mode'' (\fB\s-1OSSL_KDF_PARAM_MODE\s0\fR) <\s-1UTF8\s0 string> or <integer>" 4 +.IX Item "mode (OSSL_KDF_PARAM_MODE) <UTF8 string> or <integer>" +This parameter sets the mode for the \s-1TLS 1.3 KDF\s0 operation. +There are two modes that are currently defined: +.RS 4 +.ie n .IP """\s-1EXTRACT_ONLY""\s0 or \fB\s-1EVP_KDF_HKDF_MODE_EXTRACT_ONLY\s0\fR" 4 +.el .IP "``\s-1EXTRACT_ONLY''\s0 or \fB\s-1EVP_KDF_HKDF_MODE_EXTRACT_ONLY\s0\fR" 4 +.IX Item "EXTRACT_ONLY or EVP_KDF_HKDF_MODE_EXTRACT_ONLY" +In this mode calling \fBEVP_KDF_derive\fR\|(3) will just perform the extract +operation. The value returned will be the intermediate fixed-length pseudorandom +key K. The \fIkeylen\fR parameter must match the size of K, which can be looked +up by calling \fBEVP_KDF_CTX_get_kdf_size()\fR after setting the mode and digest. +.Sp +The digest, key and salt values must be set before a key is derived otherwise +an error will occur. +.ie n .IP """\s-1EXPAND_ONLY""\s0 or \fB\s-1EVP_KDF_HKDF_MODE_EXPAND_ONLY\s0\fR" 4 +.el .IP "``\s-1EXPAND_ONLY''\s0 or \fB\s-1EVP_KDF_HKDF_MODE_EXPAND_ONLY\s0\fR" 4 +.IX Item "EXPAND_ONLY or EVP_KDF_HKDF_MODE_EXPAND_ONLY" +In this mode calling \fBEVP_KDF_derive\fR\|(3) will just perform the expand +operation. The input key should be set to the intermediate fixed-length +pseudorandom key K returned from a previous extract operation. +.Sp +The digest, key and info values must be set before a key is derived otherwise +an error will occur. +.RE +.RS 4 +.RE +.SH "NOTES" +.IX Header "NOTES" +This \s-1KDF\s0 is intended for use by the \s-1TLS 1.3\s0 implementation in libssl. +It does not support all the options and capabilities that \s-1HKDF\s0 does. +.PP +The \fI\s-1OSSL_PARAM\s0\fR array passed to \fBEVP_KDF_derive\fR\|(3) or +\&\fBEVP_KDF_CTX_set_params\fR\|(3) must specify all of the parameters required. +This \s-1KDF\s0 does not support a piecemeal approach to providing these. +.PP +A context for a \s-1TLS 1.3 KDF\s0 can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "TLS13\-KDF", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); +.Ve +.PP +The output length of a \s-1TLS 1.3 KDF\s0 expand operation is specified via the +\&\fIkeylen\fR parameter to the \fBEVP_KDF_derive\fR\|(3) function. When using +\&\s-1EVP_KDF_HKDF_MODE_EXTRACT_ONLY\s0 the \fIkeylen\fR parameter must equal the size of +the intermediate fixed-length pseudorandom key otherwise an error will occur. +For that mode, the fixed output size can be looked up by calling +\&\fBEVP_KDF_CTX_get_kdf_size()\fR after setting the mode and digest on the +\&\fB\s-1EVP_KDF_CTX\s0\fR. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1RFC 8446\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_KDF\s0\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_get_kdf_size\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3), +\&\s-1\fBEVP_KDF\-HKDF\s0\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_KDF-TLS1_PRF.7 b/secure/lib/libcrypto/man/man7/EVP_KDF-TLS1_PRF.7 new file mode 100644 index 000000000000..efbaee1ffc8d --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_KDF-TLS1_PRF.7 @@ -0,0 +1,241 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_KDF-TLS1_PRF 7ossl" +.TH EVP_KDF-TLS1_PRF 7ossl "2023-09-19" "3.0.11" "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_KDF\-TLS1_PRF \- The TLS1 PRF EVP_KDF implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing the \fB\s-1TLS1\s0\fR \s-1PRF\s0 through the \fB\s-1EVP_KDF\s0\fR \s-1API.\s0 +.PP +The \s-1EVP_KDF\-TLS1_PRF\s0 algorithm implements the \s-1PRF\s0 used by \s-1TLS\s0 versions up to +and including \s-1TLS 1.2.\s0 +.SS "Identity" +.IX Subsection "Identity" +\&\*(L"\s-1TLS1\-PRF\*(R"\s0 is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.ie n .IP """properties"" (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>" +.PD 0 +.ie n .IP """digest"" (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_KDF_PARAM_DIGEST) <UTF8 string>" +.PD +These parameters work as described in \*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3). +.Sp +The \fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR parameter is used to set the message digest +associated with the \s-1TLS PRF.\s0 +\&\fBEVP_md5_sha1()\fR is treated as a special case which uses the +\&\s-1PRF\s0 algorithm using both \fB\s-1MD5\s0\fR and \fB\s-1SHA1\s0\fR as used in \s-1TLS 1.0\s0 and 1.1. +.ie n .IP """secret"" (\fB\s-1OSSL_KDF_PARAM_SECRET\s0\fR) <octet string>" 4 +.el .IP "``secret'' (\fB\s-1OSSL_KDF_PARAM_SECRET\s0\fR) <octet string>" 4 +.IX Item "secret (OSSL_KDF_PARAM_SECRET) <octet string>" +This parameter sets the secret value of the \s-1TLS PRF.\s0 +Any existing secret value is replaced. +.ie n .IP """seed"" (\fB\s-1OSSL_KDF_PARAM_SEED\s0\fR) <octet string>" 4 +.el .IP "``seed'' (\fB\s-1OSSL_KDF_PARAM_SEED\s0\fR) <octet string>" 4 +.IX Item "seed (OSSL_KDF_PARAM_SEED) <octet string>" +This parameter sets the context seed. +The length of the context seed cannot exceed 1024 bytes; +this should be more than enough for any normal use of the \s-1TLS PRF.\s0 +.SH "NOTES" +.IX Header "NOTES" +A context for the \s-1TLS PRF\s0 can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "TLS1\-PRF", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); +.Ve +.PP +The digest, secret value and seed must be set before a key is derived otherwise +an error will occur. +.PP +The output length of the \s-1PRF\s0 is specified by the \fIkeylen\fR parameter to the +\&\fBEVP_KDF_derive()\fR function. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +This example derives 10 bytes using \s-1SHA\-256\s0 with the secret key \*(L"secret\*(R" +and seed value \*(L"seed\*(R": +.PP +.Vb 4 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& unsigned char out[10]; +\& OSSL_PARAM params[4], *p = params; +\& +\& kdf = EVP_KDF_fetch(NULL, "TLS1\-PRF", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, +\& SN_sha256, strlen(SN_sha256)); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, +\& "secret", (size_t)6); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED, +\& "seed", (size_t)4); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { +\& error("EVP_KDF_derive"); +\& } +\& EVP_KDF_CTX_free(kctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1RFC 2246, RFC 5246\s0 and \s-1NIST SP 800\-135\s0 r1 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_KDF\s0\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2018\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_KDF-X942-ASN1.7 b/secure/lib/libcrypto/man/man7/EVP_KDF-X942-ASN1.7 new file mode 100644 index 000000000000..3455ae9798f1 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_KDF-X942-ASN1.7 @@ -0,0 +1,278 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_KDF-X942-ASN1 7ossl" +.TH EVP_KDF-X942-ASN1 7ossl "2023-09-19" "3.0.11" "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_KDF\-X942\-ASN1 \- The X9.42\-2003 asn1 EVP_KDF implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \s-1EVP_KDF\-X942\-ASN1\s0 algorithm implements the key derivation function +X942KDF\-ASN1. It is used by \s-1DH\s0 KeyAgreement, to derive a key using input such as +a shared secret key and other info. The other info is \s-1DER\s0 encoded data that +contains a 32 bit counter as well as optional fields for \*(L"partyu-info\*(R", +\&\*(L"partyv-info\*(R", \*(L"supp-pubinfo\*(R" and \*(L"supp-privinfo\*(R". +This kdf is used by Cryptographic Message Syntax (\s-1CMS\s0). +.SS "Identity" +.IX Subsection "Identity" +\&\*(L"X942KDF\-ASN1\*(R" or \*(L"X942KDF\*(R" is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.ie n .IP """properties"" (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>" +.PD 0 +.ie n .IP """digest"" (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_KDF_PARAM_DIGEST) <UTF8 string>" +.PD +These parameters work as described in \*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3). +.ie n .IP """secret"" (\fB\s-1OSSL_KDF_PARAM_SECRET\s0\fR) <octet string>" 4 +.el .IP "``secret'' (\fB\s-1OSSL_KDF_PARAM_SECRET\s0\fR) <octet string>" 4 +.IX Item "secret (OSSL_KDF_PARAM_SECRET) <octet string>" +The shared secret used for key derivation. This parameter sets the secret. +.ie n .IP """acvp-info"" (\fB\s-1OSSL_KDF_PARAM_X942_ACVPINFO\s0\fR) <octet string>" 4 +.el .IP "``acvp-info'' (\fB\s-1OSSL_KDF_PARAM_X942_ACVPINFO\s0\fR) <octet string>" 4 +.IX Item "acvp-info (OSSL_KDF_PARAM_X942_ACVPINFO) <octet string>" +This value should not be used in production and should only be used for \s-1ACVP\s0 +testing. It is an optional octet string containing a combined \s-1DER\s0 encoded blob +of any of the optional fields related to \*(L"partyu-info\*(R", \*(L"partyv-info\*(R", +\&\*(L"supp-pubinfo\*(R" and \*(L"supp-privinfo\*(R". If it is specified then none of these other +fields should be used. +.ie n .IP """partyu-info"" (\fB\s-1OSSL_KDF_PARAM_X942_PARTYUINFO\s0\fR) <octet string>" 4 +.el .IP "``partyu-info'' (\fB\s-1OSSL_KDF_PARAM_X942_PARTYUINFO\s0\fR) <octet string>" 4 +.IX Item "partyu-info (OSSL_KDF_PARAM_X942_PARTYUINFO) <octet string>" +An optional octet string containing public info contributed by the initiator. +.ie n .IP """ukm"" (\fB\s-1OSSL_KDF_PARAM_UKM\s0\fR) <octet string>" 4 +.el .IP "``ukm'' (\fB\s-1OSSL_KDF_PARAM_UKM\s0\fR) <octet string>" 4 +.IX Item "ukm (OSSL_KDF_PARAM_UKM) <octet string>" +An alias for \*(L"partyu-info\*(R". +In \s-1CMS\s0 this is the user keying material. +.ie n .IP """partyv-info"" (\fB\s-1OSSL_KDF_PARAM_X942_PARTYVINFO\s0\fR) <octet string>" 4 +.el .IP "``partyv-info'' (\fB\s-1OSSL_KDF_PARAM_X942_PARTYVINFO\s0\fR) <octet string>" 4 +.IX Item "partyv-info (OSSL_KDF_PARAM_X942_PARTYVINFO) <octet string>" +An optional octet string containing public info contributed by the responder. +.ie n .IP """supp-pubinfo"" (\fB\s-1OSSL_KDF_PARAM_X942_SUPP_PUBINFO\s0\fR) <octet string>" 4 +.el .IP "``supp-pubinfo'' (\fB\s-1OSSL_KDF_PARAM_X942_SUPP_PUBINFO\s0\fR) <octet string>" 4 +.IX Item "supp-pubinfo (OSSL_KDF_PARAM_X942_SUPP_PUBINFO) <octet string>" +An optional octet string containing some additional, mutually-known public +information. Setting this value also sets \*(L"use-keybits\*(R" to 0. +.ie n .IP """use-keybits"" (\fB\s-1OSSL_KDF_PARAM_X942_USE_KEYBITS\s0\fR) <integer>" 4 +.el .IP "``use-keybits'' (\fB\s-1OSSL_KDF_PARAM_X942_USE_KEYBITS\s0\fR) <integer>" 4 +.IX Item "use-keybits (OSSL_KDF_PARAM_X942_USE_KEYBITS) <integer>" +The default value of 1 will use the \s-1KEK\s0 key length (in bits) as the +\&\*(L"supp-pubinfo\*(R". A value of 0 disables setting the \*(L"supp-pubinfo\*(R". +.ie n .IP """supp-privinfo"" (\fB\s-1OSSL_KDF_PARAM_X942_SUPP_PRIVINFO\s0\fR) <octet string>" 4 +.el .IP "``supp-privinfo'' (\fB\s-1OSSL_KDF_PARAM_X942_SUPP_PRIVINFO\s0\fR) <octet string>" 4 +.IX Item "supp-privinfo (OSSL_KDF_PARAM_X942_SUPP_PRIVINFO) <octet string>" +An optional octet string containing some additional, mutually-known private +information. +.ie n .IP """cekalg"" (\fB\s-1OSSL_KDF_PARAM_CEK_ALG\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``cekalg'' (\fB\s-1OSSL_KDF_PARAM_CEK_ALG\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "cekalg (OSSL_KDF_PARAM_CEK_ALG) <UTF8 string>" +This parameter sets the \s-1CEK\s0 wrapping algorithm name. +Valid values are \*(L"\s-1AES\-128\-WRAP\*(R", \*(L"AES\-192\-WRAP\*(R", \*(L"AES\-256\-WRAP\*(R"\s0 and \*(L"\s-1DES3\-WRAP\*(R".\s0 +.SH "NOTES" +.IX Header "NOTES" +A context for X942KDF can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); +.Ve +.PP +The output length of an X942KDF is specified via the \fIkeylen\fR +parameter to the \fBEVP_KDF_derive\fR\|(3) function. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +This example derives 24 bytes, with the secret key \*(L"secret\*(R" and random user +keying material: +.PP +.Vb 5 +\& EVP_KDF_CTX *kctx; +\& EVP_KDF_CTX *kctx; +\& unsigned char out[192/8]; +\& unsignred char ukm[64]; +\& OSSL_PARAM params[5], *p = params; +\& +\& if (RAND_bytes(ukm, sizeof(ukm)) <= 0) +\& error("RAND_bytes"); +\& +\& kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL); +\& if (kctx == NULL) +\& error("EVP_KDF_fetch"); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& if (kctx == NULL) +\& error("EVP_KDF_CTX_new"); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, "SHA256", 0); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, +\& "secret", (size_t)6); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_UKM, ukm, sizeof(ukm)); +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CEK_ALG, "AES\-256\-WRAP, 0); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) +\& error("EVP_KDF_derive"); +\& +\& EVP_KDF_CTX_free(kctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1ANS1 X9.42\-2003 +RFC 2631\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_KDF\s0\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_CTX_get_kdf_size\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2019\-2022 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_KDF-X942-CONCAT.7 b/secure/lib/libcrypto/man/man7/EVP_KDF-X942-CONCAT.7 new file mode 100644 index 000000000000..83f6acc90138 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_KDF-X942-CONCAT.7 @@ -0,0 +1,164 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_KDF-X942-CONCAT 7ossl" +.TH EVP_KDF-X942-CONCAT 7ossl "2023-09-19" "3.0.11" "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_KDF\-X942\-CONCAT \- The X942 Concat EVP_KDF implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \s-1EVP_KDF\-X942\-CONCAT\s0 algorithm is identical to \s-1EVP_KDF\-X963.\s0 It is +used for key agreement to derive a key using input such as a shared secret key +and shared info. +.SS "Identity" +.IX Subsection "Identity" +\&\*(L"X942KDF_CONCAT\*(R" is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.PP +This is an alias for \*(L"X963KDF\*(R". +.PP +See \s-1\fBEVP_KDF\-X963\s0\fR\|(7) for a list of supported parameters and examples. +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_KDF-X963.7 b/secure/lib/libcrypto/man/man7/EVP_KDF-X963.7 new file mode 100644 index 000000000000..20c7a48de9ad --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_KDF-X963.7 @@ -0,0 +1,235 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_KDF-X963 7ossl" +.TH EVP_KDF-X963 7ossl "2023-09-19" "3.0.11" "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_KDF\-X963 \- The X9.63\-2001 EVP_KDF implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \s-1EVP_KDF\-X963\s0 algorithm implements the key derivation function (X963KDF). +X963KDF is used by Cryptographic Message Syntax (\s-1CMS\s0) for \s-1EC\s0 KeyAgreement, to +derive a key using input such as a shared secret key and shared info. +.SS "Identity" +.IX Subsection "Identity" +\&\*(L"X963KDF\*(R" is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.ie n .IP """properties"" (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>" +.PD 0 +.ie n .IP """digest"" (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_KDF_PARAM_DIGEST) <UTF8 string>" +.PD +These parameters work as described in \*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3). +.ie n .IP """key"" (\fB\s-1OSSL_KDF_PARAM_KEY\s0\fR) <octet string>" 4 +.el .IP "``key'' (\fB\s-1OSSL_KDF_PARAM_KEY\s0\fR) <octet string>" 4 +.IX Item "key (OSSL_KDF_PARAM_KEY) <octet string>" +The shared secret used for key derivation. +This parameter sets the secret. +.ie n .IP """info"" (\fB\s-1OSSL_KDF_PARAM_INFO\s0\fR) <octet string>" 4 +.el .IP "``info'' (\fB\s-1OSSL_KDF_PARAM_INFO\s0\fR) <octet string>" 4 +.IX Item "info (OSSL_KDF_PARAM_INFO) <octet string>" +This parameter specifies an optional value for shared info. +.SH "NOTES" +.IX Header "NOTES" +X963KDF is very similar to the \s-1SSKDF\s0 that uses a digest as the auxiliary function, +X963KDF appends the counter to the secret, whereas \s-1SSKDF\s0 prepends the counter. +.PP +A context for X963KDF can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); +.Ve +.PP +The output length of an X963KDF is specified via the \fIkeylen\fR +parameter to the \fBEVP_KDF_derive\fR\|(3) function. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +This example derives 10 bytes, with the secret key \*(L"secret\*(R" and sharedinfo +value \*(L"label\*(R": +.PP +.Vb 4 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& unsigned char out[10]; +\& OSSL_PARAM params[4], *p = params; +\& +\& kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, +\& SN_sha256, strlen(SN_sha256)); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, +\& "secret", (size_t)6); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, +\& "label", (size_t)5); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { +\& error("EVP_KDF_derive"); +\& } +\& +\& EVP_KDF_CTX_free(kctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\*(L"\s-1SEC 1:\s0 Elliptic Curve Cryptography\*(R" +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_KDF\s0\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_CTX_get_kdf_size\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_KDF\s0\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2019\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_KEM-RSA.7 b/secure/lib/libcrypto/man/man7/EVP_KEM-RSA.7 new file mode 100644 index 000000000000..992a588f488c --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_KEM-RSA.7 @@ -0,0 +1,189 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_KEM-RSA 7ossl" +.TH EVP_KEM-RSA 7ossl "2023-09-19" "3.0.11" "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_KEM\-RSA +\&\- EVP_KEM RSA keytype and algorithm support +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\s-1RSA\s0\fR keytype and its parameters are described in \s-1\fBEVP_PKEY\-RSA\s0\fR\|(7). +See \fBEVP_PKEY_encapsulate\fR\|(3) and \fBEVP_PKEY_decapsulate\fR\|(3) for more info. +.SS "\s-1RSA KEM\s0 parameters" +.IX Subsection "RSA KEM parameters" +.ie n .IP """operation"" (\fB\s-1OSSL_KEM_PARAM_OPERATION\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``operation'' (\fB\s-1OSSL_KEM_PARAM_OPERATION\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "operation (OSSL_KEM_PARAM_OPERATION) <UTF8 string>" +The OpenSSL \s-1RSA\s0 Key Encapsulation Mechanism only currently supports the +following operation +.RS 4 +.ie n .IP """\s-1RSASVE""\s0" 4 +.el .IP "``\s-1RSASVE''\s0" 4 +.IX Item "RSASVE" +The encapsulate function simply generates a secret using random bytes and then +encrypts the secret using the \s-1RSA\s0 public key (with no padding). +The decapsulate function recovers the secret using the \s-1RSA\s0 private key. +.RE +.RS 4 +.Sp +This can be set using \fBEVP_PKEY_CTX_set_kem_op()\fR. +.RE +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +.IP "SP800\-56Br2" 4 +.IX Item "SP800-56Br2" +Section 7.2.1.2 \s-1RSASVE\s0 Generate Operation (\s-1RSASVE.GENERATE\s0). +Section 7.2.1.3 \s-1RSASVE\s0 Recovery Operation (\s-1RSASVE.RECOVER\s0). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_set_kem_op\fR\|(3), +\&\fBEVP_PKEY_encapsulate\fR\|(3), +\&\fBEVP_PKEY_decapsulate\fR\|(3) +\&\s-1\fBEVP_KEYMGMT\s0\fR\|(3), +\&\s-1\fBEVP_PKEY\s0\fR\|(3), +\&\fBprovider\-keymgmt\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_KEYEXCH-DH.7 b/secure/lib/libcrypto/man/man7/EVP_KEYEXCH-DH.7 new file mode 100644 index 000000000000..5bd029857a40 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_KEYEXCH-DH.7 @@ -0,0 +1,263 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_KEYEXCH-DH 7ossl" +.TH EVP_KEYEXCH-DH 7ossl "2023-09-19" "3.0.11" "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_KEYEXCH\-DH +\&\- DH Key Exchange algorithm support +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Key exchange support for the \fB\s-1DH\s0\fR key type. +.SS "\s-1DH\s0 key exchange parameters" +.IX Subsection "DH key exchange parameters" +.ie n .IP """pad"" (\fB\s-1OSSL_EXCHANGE_PARAM_PAD\s0\fR) <unsigned integer>" 4 +.el .IP "``pad'' (\fB\s-1OSSL_EXCHANGE_PARAM_PAD\s0\fR) <unsigned integer>" 4 +.IX Item "pad (OSSL_EXCHANGE_PARAM_PAD) <unsigned integer>" +Sets the padding mode for the associated key exchange ctx. +Setting a value of 1 will turn padding on. +Setting a value of 0 will turn padding off. +If padding is off then the derived shared secret may be smaller than the +largest possible secret size. +If padding is on then the derived shared secret will have its first bytes +filled with zeros where necessary to make the shared secret the same size as +the largest possible secret size. +The padding mode parameter is ignored (and padding implicitly enabled) when +the \s-1KDF\s0 type is set to \*(L"X942KDF\-ASN1\*(R" (\fB\s-1OSSL_KDF_NAME_X942KDF_ASN1\s0\fR). +.ie n .IP """kdf-type"" (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``kdf-type'' (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "kdf-type (OSSL_EXCHANGE_PARAM_KDF_TYPE) <UTF8 string>" +See \*(L"Common Key Exchange parameters\*(R" in \fBprovider\-keyexch\fR\|(7). +.ie n .IP """kdf-digest"" (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``kdf-digest'' (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "kdf-digest (OSSL_EXCHANGE_PARAM_KDF_DIGEST) <UTF8 string>" +See \*(L"Common Key Exchange parameters\*(R" in \fBprovider\-keyexch\fR\|(7). +.ie n .IP """kdf-digest-props"" (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``kdf-digest-props'' (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "kdf-digest-props (OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS) <UTF8 string>" +See \*(L"Common Key Exchange parameters\*(R" in \fBprovider\-keyexch\fR\|(7). +.ie n .IP """kdf-outlen"" (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_OUTLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``kdf-outlen'' (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_OUTLEN\s0\fR) <unsigned integer>" 4 +.IX Item "kdf-outlen (OSSL_EXCHANGE_PARAM_KDF_OUTLEN) <unsigned integer>" +See \*(L"Common Key Exchange parameters\*(R" in \fBprovider\-keyexch\fR\|(7). +.ie n .IP """kdf-ukm"" (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_UKM\s0\fR) <octet string>" 4 +.el .IP "``kdf-ukm'' (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_UKM\s0\fR) <octet string>" 4 +.IX Item "kdf-ukm (OSSL_EXCHANGE_PARAM_KDF_UKM) <octet string>" +See \*(L"Common Key Exchange parameters\*(R" in \fBprovider\-keyexch\fR\|(7). +.ie n .IP """cekalg"" (\fB\s-1OSSL_KDF_PARAM_CEK_ALG\s0\fR) <octet string ptr>" 4 +.el .IP "``cekalg'' (\fB\s-1OSSL_KDF_PARAM_CEK_ALG\s0\fR) <octet string ptr>" 4 +.IX Item "cekalg (OSSL_KDF_PARAM_CEK_ALG) <octet string ptr>" +See \*(L"\s-1KDF\s0 Parameters\*(R" in \fBprovider\-kdf\fR\|(7). +.SH "EXAMPLES" +.IX Header "EXAMPLES" +The examples assume a host and peer both generate keys using the same +named group (or domain parameters). See \*(L"Examples\*(R" in \s-1\fBEVP_PKEY\-DH\s0\fR\|(7). +Both the host and peer transfer their public key to each other. +.PP +To convert the peer's generated key pair to a public key in \s-1DER\s0 format in order +to transfer to the host: +.PP +.Vb 3 +\& EVP_PKEY *peer_key; /* It is assumed this contains the peers generated key */ +\& unsigned char *peer_pub_der = NULL; +\& int peer_pub_der_len; +\& +\& peer_pub_der_len = i2d_PUBKEY(peer_key, &peer_pub_der); +\& ... +\& OPENSSL_free(peer_pub_der); +.Ve +.PP +To convert the received peer's public key from \s-1DER\s0 format on the host: +.PP +.Vb 4 +\& const unsigned char *pd = peer_pub_der; +\& EVP_PKEY *peer_pub_key = d2i_PUBKEY(NULL, &pd, peer_pub_der_len); +\& ... +\& EVP_PKEY_free(peer_pub_key); +.Ve +.PP +To derive a shared secret on the host using the host's key and the peer's public +key: +.PP +.Vb 8 +\& /* It is assumed that the host_key and peer_pub_key are set up */ +\& void derive_secret(EVP_KEY *host_key, EVP_PKEY *peer_pub_key) +\& { +\& unsigned int pad = 1; +\& OSSL_PARAM params[2]; +\& unsigned char *secret = NULL; +\& size_t secret_len = 0; +\& EVP_PKEY_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL); +\& +\& EVP_PKEY_derive_init(dctx); +\& +\& /* Optionally set the padding */ +\& params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad); +\& params[1] = OSSL_PARAM_construct_end(); +\& EVP_PKEY_CTX_set_params(dctx, params); +\& +\& EVP_PKEY_derive_set_peer(dctx, peer_pub_key); +\& +\& /* Get the size by passing NULL as the buffer */ +\& EVP_PKEY_derive(dctx, NULL, &secret_len); +\& secret = OPENSSL_zalloc(secret_len); +\& +\& EVP_PKEY_derive(dctx, secret, &secret_len); +\& ... +\& OPENSSL_clear_free(secret, secret_len); +\& EVP_PKEY_CTX_free(dctx); +\& } +.Ve +.PP +Very similar code can be used by the peer to derive the same shared secret +using the host's public key and the peer's generated key pair. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_PKEY\-DH\s0\fR\|(7), +\&\s-1\fBEVP_PKEY\-FFC\s0\fR\|(7), +\&\s-1\fBEVP_PKEY\s0\fR\|(3), +\&\fBprovider\-keyexch\fR\|(7), +\&\fBprovider\-keymgmt\fR\|(7), +\&\fBOSSL_PROVIDER\-default\fR\|(7), +\&\s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7), +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2022 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_KEYEXCH-ECDH.7 b/secure/lib/libcrypto/man/man7/EVP_KEYEXCH-ECDH.7 new file mode 100644 index 000000000000..7d3198f97944 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_KEYEXCH-ECDH.7 @@ -0,0 +1,244 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_KEYEXCH-ECDH 7ossl" +.TH EVP_KEYEXCH-ECDH 7ossl "2023-09-19" "3.0.11" "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_KEYEXCH\-ECDH \- ECDH Key Exchange algorithm support +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Key exchange support for the \fB\s-1ECDH\s0\fR key type. +.SS "\s-1ECDH\s0 Key Exchange parameters" +.IX Subsection "ECDH Key Exchange parameters" +.ie n .IP """ecdh-cofactor-mode"" (\fB\s-1OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE\s0\fR) <integer>" 4 +.el .IP "``ecdh-cofactor-mode'' (\fB\s-1OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE\s0\fR) <integer>" 4 +.IX Item "ecdh-cofactor-mode (OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE) <integer>" +Sets or gets the \s-1ECDH\s0 mode of operation for the associated key exchange ctx. +.Sp +In the context of an Elliptic Curve Diffie-Hellman key exchange, this parameter +can be used to select between the plain Diffie-Hellman (\s-1DH\s0) or Cofactor +Diffie-Hellman (\s-1CDH\s0) variants of the key exchange algorithm. +.Sp +When setting, the value should be 1, 0 or \-1, respectively forcing cofactor mode +on, off, or resetting it to the default for the private key associated with the +given key exchange ctx. +.Sp +When getting, the value should be either 1 or 0, respectively signaling if the +cofactor mode is on or off. +.Sp +See also \fBprovider\-keymgmt\fR\|(7) for the related +\&\fB\s-1OSSL_PKEY_PARAM_USE_COFACTOR_ECDH\s0\fR parameter that can be set on a +per-key basis. +.ie n .IP """kdf-type"" (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``kdf-type'' (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "kdf-type (OSSL_EXCHANGE_PARAM_KDF_TYPE) <UTF8 string>" +See \*(L"Common Key Exchange parameters\*(R" in \fBprovider\-keyexch\fR\|(7). +.ie n .IP """kdf-digest"" (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``kdf-digest'' (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "kdf-digest (OSSL_EXCHANGE_PARAM_KDF_DIGEST) <UTF8 string>" +See \*(L"Common Key Exchange parameters\*(R" in \fBprovider\-keyexch\fR\|(7). +.ie n .IP """kdf-digest-props"" (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``kdf-digest-props'' (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "kdf-digest-props (OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS) <UTF8 string>" +See \*(L"Common Key Exchange parameters\*(R" in \fBprovider\-keyexch\fR\|(7). +.ie n .IP """kdf-outlen"" (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_OUTLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``kdf-outlen'' (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_OUTLEN\s0\fR) <unsigned integer>" 4 +.IX Item "kdf-outlen (OSSL_EXCHANGE_PARAM_KDF_OUTLEN) <unsigned integer>" +See \*(L"Common Key Exchange parameters\*(R" in \fBprovider\-keyexch\fR\|(7). +.ie n .IP """kdf-ukm"" (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_UKM\s0\fR) <octet string>" 4 +.el .IP "``kdf-ukm'' (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_UKM\s0\fR) <octet string>" 4 +.IX Item "kdf-ukm (OSSL_EXCHANGE_PARAM_KDF_UKM) <octet string>" +See \*(L"Common Key Exchange parameters\*(R" in \fBprovider\-keyexch\fR\|(7). +.SH "EXAMPLES" +.IX Header "EXAMPLES" +Keys for the host and peer must be generated as shown in +\&\*(L"Examples\*(R" in \s-1\fBEVP_PKEY\-EC\s0\fR\|(7) using the same curve name. +.PP +The code to generate a shared secret for the normal case is identical to +\&\*(L"Examples\*(R" in \s-1\fBEVP_KEYEXCH\-DH\s0\fR\|(7). +.PP +To derive a shared secret on the host using the host's key and the peer's public +key but also using X963KDF with a user key material: +.PP +.Vb 10 +\& /* It is assumed that the host_key, peer_pub_key and ukm are set up */ +\& void derive_secret(EVP_PKEY *host_key, EVP_PKEY *peer_key, +\& unsigned char *ukm, size_t ukm_len) +\& { +\& unsigned char secret[64]; +\& size_t out_len = sizeof(secret); +\& size_t secret_len = out_len; +\& unsigned int pad = 1; +\& OSSL_PARAM params[6]; +\& EVP_PKEY_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL); +\& +\& EVP_PKEY_derive_init(dctx); +\& +\& params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad); +\& params[1] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_TYPE, +\& "X963KDF", 0); +\& params[2] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_DIGEST, +\& "SHA1", 0); +\& params[3] = OSSL_PARAM_construct_size_t(OSSL_EXCHANGE_PARAM_KDF_OUTLEN, +\& &out_len); +\& params[4] = OSSL_PARAM_construct_octet_string(OSSL_EXCHANGE_PARAM_KDF_UKM, +\& ukm, ukm_len); +\& params[5] = OSSL_PARAM_construct_end(); +\& EVP_PKEY_CTX_set_params(dctx, params); +\& +\& EVP_PKEY_derive_set_peer(dctx, peer_pub_key); +\& EVP_PKEY_derive(dctx, secret, &secret_len); +\& ... +\& OPENSSL_clear_free(secret, secret_len); +\& EVP_PKEY_CTX_free(dctx); +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_PKEY\-EC\s0\fR\|(7) +\&\s-1\fBEVP_PKEY\s0\fR\|(3), +\&\fBprovider\-keyexch\fR\|(7), +\&\fBprovider\-keymgmt\fR\|(7), +\&\fBOSSL_PROVIDER\-default\fR\|(7), +\&\s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7), +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2022 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_KEYEXCH-X25519.7 b/secure/lib/libcrypto/man/man7/EVP_KEYEXCH-X25519.7 new file mode 100644 index 000000000000..f46f0f08402b --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_KEYEXCH-X25519.7 @@ -0,0 +1,175 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_KEYEXCH-X25519 7ossl" +.TH EVP_KEYEXCH-X25519 7ossl "2023-09-19" "3.0.11" "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_KEYEXCH\-X25519, +EVP_KEYEXCH\-X448 +\&\- X25519 and X448 Key Exchange algorithm support +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Key exchange support for the \fBX25519\fR and \fBX448\fR key types. +.SS "Key exchange parameters" +.IX Subsection "Key exchange parameters" +.ie n .IP """pad"" (\fB\s-1OSSL_EXCHANGE_PARAM_PAD\s0\fR) <unsigned integer>" 4 +.el .IP "``pad'' (\fB\s-1OSSL_EXCHANGE_PARAM_PAD\s0\fR) <unsigned integer>" 4 +.IX Item "pad (OSSL_EXCHANGE_PARAM_PAD) <unsigned integer>" +See \*(L"Common Key Exchange parameters\*(R" in \fBprovider\-keyexch\fR\|(7). +.SH "EXAMPLES" +.IX Header "EXAMPLES" +Keys for the host and peer can be generated as shown in +\&\*(L"Examples\*(R" in \s-1\fBEVP_PKEY\-X25519\s0\fR\|(7). +.PP +The code to generate a shared secret is identical to +\&\*(L"Examples\*(R" in \s-1\fBEVP_KEYEXCH\-DH\s0\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_PKEY\-FFC\s0\fR\|(7), +\&\s-1\fBEVP_PKEY\-DH\s0\fR\|(7) +\&\s-1\fBEVP_PKEY\s0\fR\|(3), +\&\fBprovider\-keyexch\fR\|(7), +\&\fBprovider\-keymgmt\fR\|(7), +\&\fBOSSL_PROVIDER\-default\fR\|(7), +\&\s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7), +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MAC-BLAKE2.7 b/secure/lib/libcrypto/man/man7/EVP_MAC-BLAKE2.7 new file mode 100644 index 000000000000..7fb0643f8f81 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MAC-BLAKE2.7 @@ -0,0 +1,213 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MAC-BLAKE2 7ossl" +.TH EVP_MAC-BLAKE2 7ossl "2023-09-19" "3.0.11" "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_MAC\-BLAKE2, EVP_MAC\-BLAKE2BMAC, EVP_MAC\-BLAKE2SMAC +\&\- The BLAKE2 EVP_MAC implementations +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1BLAKE2\s0 MACs through the \fB\s-1EVP_MAC\s0\fR \s-1API.\s0 +.SS "Identity" +.IX Subsection "Identity" +These implementations are identified with one of these names and +properties, to be used with \fBEVP_MAC_fetch()\fR: +.ie n .IP """\s-1BLAKE2BMAC"",\s0 ""provider=default""" 4 +.el .IP "``\s-1BLAKE2BMAC'',\s0 ``provider=default''" 4 +.IX Item "BLAKE2BMAC, provider=default" +.PD 0 +.ie n .IP """\s-1BLAKE2SMAC"",\s0 ""provider=default""" 4 +.el .IP "``\s-1BLAKE2SMAC'',\s0 ``provider=default''" 4 +.IX Item "BLAKE2SMAC, provider=default" +.PD +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The general description of these parameters can be found in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_MAC\s0\fR\|(3). +.PP +All these parameters can be set with \fBEVP_MAC_CTX_set_params()\fR. +Furthermore, the \*(L"size\*(R" parameter can be retrieved with +\&\fBEVP_MAC_CTX_get_params()\fR, or with \fBEVP_MAC_CTX_get_mac_size()\fR. +The length of the \*(L"size\*(R" parameter should not exceed that of a \fBsize_t\fR. +Likewise, the \*(L"block-size\*(R" parameter can be retrieved with +\&\fBEVP_MAC_CTX_get_params()\fR, or with \fBEVP_MAC_CTX_get_block_size()\fR. +.ie n .IP """key"" (\fB\s-1OSSL_MAC_PARAM_KEY\s0\fR) <octet string>" 4 +.el .IP "``key'' (\fB\s-1OSSL_MAC_PARAM_KEY\s0\fR) <octet string>" 4 +.IX Item "key (OSSL_MAC_PARAM_KEY) <octet string>" +Sets the \s-1MAC\s0 key. +It may be at most 64 bytes for \s-1BLAKE2BMAC\s0 or 32 for \s-1BLAKE2SMAC\s0 and at +least 1 byte in both cases. +Setting this parameter is identical to passing a \fIkey\fR to \fBEVP_MAC_init\fR\|(3). +.ie n .IP """custom"" (\fB\s-1OSSL_MAC_PARAM_CUSTOM\s0\fR) <octet string>" 4 +.el .IP "``custom'' (\fB\s-1OSSL_MAC_PARAM_CUSTOM\s0\fR) <octet string>" 4 +.IX Item "custom (OSSL_MAC_PARAM_CUSTOM) <octet string>" +Sets the custom value. +It is an optional value of at most 16 bytes for \s-1BLAKE2BMAC\s0 or 8 for +\&\s-1BLAKE2SMAC,\s0 and is empty by default. +.ie n .IP """salt"" (\fB\s-1OSSL_MAC_PARAM_SALT\s0\fR) <octet string>" 4 +.el .IP "``salt'' (\fB\s-1OSSL_MAC_PARAM_SALT\s0\fR) <octet string>" 4 +.IX Item "salt (OSSL_MAC_PARAM_SALT) <octet string>" +Sets the salt. +It is an optional value of at most 16 bytes for \s-1BLAKE2BMAC\s0 or 8 for +\&\s-1BLAKE2SMAC,\s0 and is empty by default. +.ie n .IP """size"" (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``size'' (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "size (OSSL_MAC_PARAM_SIZE) <unsigned integer>" +Sets the \s-1MAC\s0 size. +It can be any number between 1 and 32 for \s-1EVP_MAC_BLAKE2S\s0 or between 1 +and 64 for \s-1EVP_MAC_BLAKE2B.\s0 +It is 32 and 64 respectively by default. +.ie n .IP """block-size"" (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``block-size'' (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "block-size (OSSL_MAC_PARAM_SIZE) <unsigned integer>" +Gets the \s-1MAC\s0 block size. +By default, it is 64 for \s-1EVP_MAC_BLAKE2S\s0 and 128 for \s-1EVP_MAC_BLAKE2B.\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MAC_CTX_get_params\fR\|(3), \fBEVP_MAC_CTX_set_params\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_MAC\s0\fR\|(3), \s-1\fBOSSL_PARAM\s0\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +The macros and functions described here were added to OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2018\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MAC-CMAC.7 b/secure/lib/libcrypto/man/man7/EVP_MAC-CMAC.7 new file mode 100644 index 000000000000..1deecd76353f --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MAC-CMAC.7 @@ -0,0 +1,199 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MAC-CMAC 7ossl" +.TH EVP_MAC-CMAC 7ossl "2023-09-19" "3.0.11" "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_MAC\-CMAC \- The CMAC EVP_MAC implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1CMAC\s0 MACs through the \fB\s-1EVP_MAC\s0\fR \s-1API.\s0 +.PP +This implementation uses \s-1EVP_CIPHER\s0 functions to get access to the underlying +cipher. +.SS "Identity" +.IX Subsection "Identity" +This implementation is identified with this name and properties, to be +used with \fBEVP_MAC_fetch()\fR: +.ie n .IP """\s-1CMAC"",\s0 ""provider=default"" or ""provider=fips""" 4 +.el .IP "``\s-1CMAC'',\s0 ``provider=default'' or ``provider=fips''" 4 +.IX Item "CMAC, provider=default or provider=fips" +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The general description of these parameters can be found in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_MAC\s0\fR\|(3). +.PP +The following parameter can be set with \fBEVP_MAC_CTX_set_params()\fR: +.ie n .IP """key"" (\fB\s-1OSSL_MAC_PARAM_KEY\s0\fR) <octet string>" 4 +.el .IP "``key'' (\fB\s-1OSSL_MAC_PARAM_KEY\s0\fR) <octet string>" 4 +.IX Item "key (OSSL_MAC_PARAM_KEY) <octet string>" +Sets the \s-1MAC\s0 key. +Setting this parameter is identical to passing a \fIkey\fR to \fBEVP_MAC_init\fR\|(3). +.ie n .IP """cipher"" (\fB\s-1OSSL_MAC_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``cipher'' (\fB\s-1OSSL_MAC_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "cipher (OSSL_MAC_PARAM_CIPHER) <UTF8 string>" +Sets the name of the underlying cipher to be used. +.ie n .IP """properties"" (\fB\s-1OSSL_MAC_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_MAC_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_MAC_PARAM_PROPERTIES) <UTF8 string>" +Sets the properties to be queried when trying to fetch the underlying cipher. +This must be given together with the cipher naming parameter to be considered +valid. +.PP +The following parameters can be retrieved with +\&\fBEVP_MAC_CTX_get_params()\fR: +.ie n .IP """size"" (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``size'' (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "size (OSSL_MAC_PARAM_SIZE) <unsigned integer>" +The \*(L"size\*(R" parameter can also be retrieved with with \fBEVP_MAC_CTX_get_mac_size()\fR. +The length of the \*(L"size\*(R" parameter is equal to that of an \fBunsigned int\fR. +.ie n .IP """block-size"" (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``block-size'' (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "block-size (OSSL_MAC_PARAM_SIZE) <unsigned integer>" +Gets the \s-1MAC\s0 block size. The \*(L"block-size\*(R" parameter can also be retrieved with +\&\fBEVP_MAC_CTX_get_block_size()\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MAC_CTX_get_params\fR\|(3), \fBEVP_MAC_CTX_set_params\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_MAC\s0\fR\|(3), \s-1\fBOSSL_PARAM\s0\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2018\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MAC-GMAC.7 b/secure/lib/libcrypto/man/man7/EVP_MAC-GMAC.7 new file mode 100644 index 000000000000..a3b6ffef7cf0 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MAC-GMAC.7 @@ -0,0 +1,200 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MAC-GMAC 7ossl" +.TH EVP_MAC-GMAC 7ossl "2023-09-19" "3.0.11" "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_MAC\-GMAC \- The GMAC EVP_MAC implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1GMAC\s0 MACs through the \fB\s-1EVP_MAC\s0\fR \s-1API.\s0 +.PP +This implementation uses \s-1EVP_CIPHER\s0 functions to get access to the underlying +cipher. +.SS "Identity" +.IX Subsection "Identity" +This implementation is identified with this name and properties, to be +used with \fBEVP_MAC_fetch()\fR: +.ie n .IP """\s-1GMAC"",\s0 ""provider=default"" or ""provider=fips""" 4 +.el .IP "``\s-1GMAC'',\s0 ``provider=default'' or ``provider=fips''" 4 +.IX Item "GMAC, provider=default or provider=fips" +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The general description of these parameters can be found in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_MAC\s0\fR\|(3). +.PP +The following parameter can be set with \fBEVP_MAC_CTX_set_params()\fR: +.ie n .IP """key"" (\fB\s-1OSSL_MAC_PARAM_KEY\s0\fR) <octet string>" 4 +.el .IP "``key'' (\fB\s-1OSSL_MAC_PARAM_KEY\s0\fR) <octet string>" 4 +.IX Item "key (OSSL_MAC_PARAM_KEY) <octet string>" +Sets the \s-1MAC\s0 key. +Setting this parameter is identical to passing a \fIkey\fR to \fBEVP_MAC_init\fR\|(3). +.ie n .IP """iv"" (\fB\s-1OSSL_MAC_PARAM_IV\s0\fR) <octet string>" 4 +.el .IP "``iv'' (\fB\s-1OSSL_MAC_PARAM_IV\s0\fR) <octet string>" 4 +.IX Item "iv (OSSL_MAC_PARAM_IV) <octet string>" +Sets the \s-1IV\s0 of the underlying cipher, when applicable. +.ie n .IP """cipher"" (\fB\s-1OSSL_MAC_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``cipher'' (\fB\s-1OSSL_MAC_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "cipher (OSSL_MAC_PARAM_CIPHER) <UTF8 string>" +Sets the name of the underlying cipher to be used. +.ie n .IP """properties"" (\fB\s-1OSSL_MAC_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_MAC_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_MAC_PARAM_PROPERTIES) <UTF8 string>" +Sets the properties to be queried when trying to fetch the underlying cipher. +This must be given together with the cipher naming parameter to be considered +valid. +.PP +The following parameters can be retrieved with +\&\fBEVP_MAC_CTX_get_params()\fR: +.ie n .IP """size"" (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``size'' (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "size (OSSL_MAC_PARAM_SIZE) <unsigned integer>" +Gets the \s-1MAC\s0 size. +.PP +The \*(L"size\*(R" parameter can also be retrieved with \fBEVP_MAC_CTX_get_mac_size()\fR. +The length of the \*(L"size\*(R" parameter is equal to that of an \fBunsigned int\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MAC_CTX_get_params\fR\|(3), \fBEVP_MAC_CTX_set_params\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_MAC\s0\fR\|(3), \s-1\fBOSSL_PARAM\s0\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2018\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MAC-HMAC.7 b/secure/lib/libcrypto/man/man7/EVP_MAC-HMAC.7 new file mode 100644 index 000000000000..8ab1d90ec2e8 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MAC-HMAC.7 @@ -0,0 +1,212 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MAC-HMAC 7ossl" +.TH EVP_MAC-HMAC 7ossl "2023-09-19" "3.0.11" "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_MAC\-HMAC \- The HMAC EVP_MAC implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1HMAC\s0 MACs through the \fB\s-1EVP_MAC\s0\fR \s-1API.\s0 +.PP +This implementation uses \s-1EVP_MD\s0 functions to get access to the underlying +digest. +.SS "Identity" +.IX Subsection "Identity" +This implementation is identified with this name and properties, to be +used with \fBEVP_MAC_fetch()\fR: +.ie n .IP """\s-1HMAC"",\s0 ""provider=default"" or ""provider=fips""" 4 +.el .IP "``\s-1HMAC'',\s0 ``provider=default'' or ``provider=fips''" 4 +.IX Item "HMAC, provider=default or provider=fips" +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The general description of these parameters can be found in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_MAC\s0\fR\|(3). +.PP +The following parameter can be set with \fBEVP_MAC_CTX_set_params()\fR: +.ie n .IP """key"" (\fB\s-1OSSL_MAC_PARAM_KEY\s0\fR) <octet string>" 4 +.el .IP "``key'' (\fB\s-1OSSL_MAC_PARAM_KEY\s0\fR) <octet string>" 4 +.IX Item "key (OSSL_MAC_PARAM_KEY) <octet string>" +Sets the \s-1MAC\s0 key. +Setting this parameter is identical to passing a \fIkey\fR to \fBEVP_MAC_init\fR\|(3). +.ie n .IP """digest"" (\fB\s-1OSSL_MAC_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_MAC_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_MAC_PARAM_DIGEST) <UTF8 string>" +Sets the name of the underlying digest to be used. +.ie n .IP """properties"" (\fB\s-1OSSL_MAC_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_MAC_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_MAC_PARAM_PROPERTIES) <UTF8 string>" +Sets the properties to be queried when trying to fetch the underlying digest. +This must be given together with the digest naming parameter (\*(L"digest\*(R", or +\&\fB\s-1OSSL_MAC_PARAM_DIGEST\s0\fR) to be considered valid. +.ie n .IP """digest-noinit"" (\fB\s-1OSSL_MAC_PARAM_DIGEST_NOINIT\s0\fR) <integer>" 4 +.el .IP "``digest-noinit'' (\fB\s-1OSSL_MAC_PARAM_DIGEST_NOINIT\s0\fR) <integer>" 4 +.IX Item "digest-noinit (OSSL_MAC_PARAM_DIGEST_NOINIT) <integer>" +A flag to set the \s-1MAC\s0 digest to not initialise the implementation +specific data. +The value 0 or 1 is expected. +.ie n .IP """digest-oneshot"" (\fB\s-1OSSL_MAC_PARAM_DIGEST_ONESHOT\s0\fR) <integer>" 4 +.el .IP "``digest-oneshot'' (\fB\s-1OSSL_MAC_PARAM_DIGEST_ONESHOT\s0\fR) <integer>" 4 +.IX Item "digest-oneshot (OSSL_MAC_PARAM_DIGEST_ONESHOT) <integer>" +A flag to set the \s-1MAC\s0 digest to be a one-shot operation. +The value 0 or 1 is expected. +.ie n .IP """tls-data-size"" (\fB\s-1OSSL_MAC_PARAM_TLS_DATA_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``tls-data-size'' (\fB\s-1OSSL_MAC_PARAM_TLS_DATA_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "tls-data-size (OSSL_MAC_PARAM_TLS_DATA_SIZE) <unsigned integer>" +.PP +The following parameter can be retrieved with \fBEVP_MAC_CTX_get_params()\fR: +.ie n .IP """size"" (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``size'' (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "size (OSSL_MAC_PARAM_SIZE) <unsigned integer>" +The \*(L"size\*(R" parameter can also be retrieved with \fBEVP_MAC_CTX_get_mac_size()\fR. +The length of the \*(L"size\*(R" parameter is equal to that of an \fBunsigned int\fR. +.ie n .IP """block-size"" (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``block-size'' (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "block-size (OSSL_MAC_PARAM_SIZE) <unsigned integer>" +Gets the \s-1MAC\s0 block size. The \*(L"block-size\*(R" parameter can also be retrieved with +\&\fBEVP_MAC_CTX_get_block_size()\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MAC_CTX_get_params\fR\|(3), \fBEVP_MAC_CTX_set_params\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_MAC\s0\fR\|(3), \s-1\fBOSSL_PARAM\s0\fR\|(3), \s-1\fBHMAC\s0\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2018\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MAC-KMAC.7 b/secure/lib/libcrypto/man/man7/EVP_MAC-KMAC.7 new file mode 100644 index 000000000000..116c9a57577b --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MAC-KMAC.7 @@ -0,0 +1,276 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MAC-KMAC 7ossl" +.TH EVP_MAC-KMAC 7ossl "2023-09-19" "3.0.11" "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_MAC\-KMAC, EVP_MAC\-KMAC128, EVP_MAC\-KMAC256 +\&\- The KMAC EVP_MAC implementations +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1KMAC\s0 MACs through the \fB\s-1EVP_MAC\s0\fR \s-1API.\s0 +.SS "Identity" +.IX Subsection "Identity" +These implementations are identified with one of these names and +properties, to be used with \fBEVP_MAC_fetch()\fR: +.ie n .IP """\s-1KMAC\-128"",\s0 ""provider=default"" or ""provider=fips""" 4 +.el .IP "``\s-1KMAC\-128'',\s0 ``provider=default'' or ``provider=fips''" 4 +.IX Item "KMAC-128, provider=default or provider=fips" +.PD 0 +.ie n .IP """\s-1KMAC\-256"",\s0 ""provider=default"" or ""provider=fips""" 4 +.el .IP "``\s-1KMAC\-256'',\s0 ``provider=default'' or ``provider=fips''" 4 +.IX Item "KMAC-256, provider=default or provider=fips" +.PD +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The general description of these parameters can be found in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_MAC\s0\fR\|(3). +.PP +All these parameters can be set with \fBEVP_MAC_CTX_set_params()\fR. +Furthermore, the \*(L"size\*(R" parameter can be retrieved with +\&\fBEVP_MAC_CTX_get_params()\fR, or with \fBEVP_MAC_CTX_get_mac_size()\fR. +The length of the \*(L"size\*(R" parameter should not exceed that of a \fBsize_t\fR. +Likewise, the \*(L"block-size\*(R" parameter can be retrieved with +\&\fBEVP_MAC_CTX_get_params()\fR, or with \fBEVP_MAC_CTX_get_block_size()\fR. +.ie n .IP """key"" (\fB\s-1OSSL_MAC_PARAM_KEY\s0\fR) <octet string>" 4 +.el .IP "``key'' (\fB\s-1OSSL_MAC_PARAM_KEY\s0\fR) <octet string>" 4 +.IX Item "key (OSSL_MAC_PARAM_KEY) <octet string>" +Sets the \s-1MAC\s0 key. +Setting this parameter is identical to passing a \fIkey\fR to \fBEVP_MAC_init\fR\|(3). +The length of the key (in bytes) must be in the range 4...512. +.ie n .IP """custom"" (\fB\s-1OSSL_MAC_PARAM_CUSTOM\s0\fR) <octet string>" 4 +.el .IP "``custom'' (\fB\s-1OSSL_MAC_PARAM_CUSTOM\s0\fR) <octet string>" 4 +.IX Item "custom (OSSL_MAC_PARAM_CUSTOM) <octet string>" +Sets the custom value. +It is an optional value with a length of at most 512 bytes, and is empty by default. +.ie n .IP """size"" (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``size'' (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "size (OSSL_MAC_PARAM_SIZE) <unsigned integer>" +Sets the \s-1MAC\s0 size. +By default, it is 16 for \f(CW\*(C`KMAC\-128\*(C'\fR and 32 for \f(CW\*(C`KMAC\-256\*(C'\fR. +.ie n .IP """block-size"" (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``block-size'' (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "block-size (OSSL_MAC_PARAM_SIZE) <unsigned integer>" +Gets the \s-1MAC\s0 block size. +By default, it is 168 for \f(CW\*(C`KMAC\-128\*(C'\fR and 136 for \f(CW\*(C`KMAC\-256\*(C'\fR. +.ie n .IP """xof"" (\fB\s-1OSSL_MAC_PARAM_XOF\s0\fR) <integer>" 4 +.el .IP "``xof'' (\fB\s-1OSSL_MAC_PARAM_XOF\s0\fR) <integer>" 4 +.IX Item "xof (OSSL_MAC_PARAM_XOF) <integer>" +The \*(L"xof\*(R" parameter value is expected to be 1 or 0. Use 1 to enable \s-1XOF\s0 mode. +The default value is 0. +.PP +The \*(L"custom\*(R" parameter must be set as part of or before the \fBEVP_MAC_init()\fR call. +The \*(L"xof\*(R" and \*(L"size\*(R" parameters can be set at any time before \fBEVP_MAC_final()\fR. +The \*(L"key\*(R" parameter is set as part of the \fBEVP_MAC_init()\fR call, but can be +set before it instead. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +.Vb 2 +\& #include <openssl/evp.h> +\& #include <openssl/params.h> +\& +\& static int do_kmac(const unsigned char *in, size_t in_len, +\& const unsigned char *key, size_t key_len, +\& const unsigned char *custom, size_t custom_len, +\& int xof_enabled, unsigned char *out, int out_len) +\& { +\& EVP_MAC_CTX *ctx = NULL; +\& EVP_MAC *mac = NULL; +\& OSSL_PARAM params[4], *p; +\& int ret = 0; +\& size_t l = 0; +\& +\& mac = EVP_MAC_fetch(NULL, "KMAC\-128", NULL); +\& if (mac == NULL) +\& goto err; +\& ctx = EVP_MAC_CTX_new(mac); +\& /* The mac can be freed after it is used by EVP_MAC_CTX_new */ +\& EVP_MAC_free(mac); +\& if (ctx == NULL) +\& goto err; +\& +\& /* +\& * Setup parameters required before calling EVP_MAC_init() +\& * The parameters OSSL_MAC_PARAM_XOF and OSSL_MAC_PARAM_SIZE may also be +\& * used at this point. +\& */ +\& p = params; +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_MAC_PARAM_KEY, +\& (void *)key, key_len); +\& if (custom != NULL && custom_len != 0) +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_MAC_PARAM_CUSTOM, +\& (void *)custom, custom_len); +\& *p = OSSL_PARAM_construct_end(); +\& if (!EVP_MAC_CTX_set_params(ctx, params)) +\& goto err; +\& +\& if (!EVP_MAC_init(ctx)) +\& goto err; +\& +\& /* +\& * Note: the following optional parameters can be set any time +\& * before EVP_MAC_final(). +\& */ +\& p = params; +\& *p++ = OSSL_PARAM_construct_int(OSSL_MAC_PARAM_XOF, &xof_enabled); +\& *p++ = OSSL_PARAM_construct_int(OSSL_MAC_PARAM_SIZE, &out_len); +\& *p = OSSL_PARAM_construct_end(); +\& if (!EVP_MAC_CTX_set_params(ctx, params)) +\& goto err; +\& +\& /* The update may be called multiple times here for streamed input */ +\& if (!EVP_MAC_update(ctx, in, in_len)) +\& goto err; +\& if (!EVP_MAC_final(ctx, out, &l, out_len)) +\& goto err; +\& ret = 1; +\& err: +\& EVP_MAC_CTX_free(ctx); +\& return ret; +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MAC_CTX_get_params\fR\|(3), \fBEVP_MAC_CTX_set_params\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_MAC\s0\fR\|(3), \s-1\fBOSSL_PARAM\s0\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2018\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MAC-Poly1305.7 b/secure/lib/libcrypto/man/man7/EVP_MAC-Poly1305.7 new file mode 100644 index 000000000000..443a55de81b3 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MAC-Poly1305.7 @@ -0,0 +1,189 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MAC-POLY1305 7ossl" +.TH EVP_MAC-POLY1305 7ossl "2023-09-19" "3.0.11" "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_MAC\-Poly1305 \- The Poly1305 EVP_MAC implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing Poly1305 MACs through the \fB\s-1EVP_MAC\s0\fR \s-1API.\s0 +.SS "Identity" +.IX Subsection "Identity" +This implementation is identified with this name and properties, to be +used with \fBEVP_MAC_fetch()\fR: +.ie n .IP """\s-1POLY1305"",\s0 ""provider=default""" 4 +.el .IP "``\s-1POLY1305'',\s0 ``provider=default''" 4 +.IX Item "POLY1305, provider=default" +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The general description of these parameters can be found in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_MAC\s0\fR\|(3). +.PP +The following parameter can be set with \fBEVP_MAC_CTX_set_params()\fR: +.ie n .IP """key"" (\fB\s-1OSSL_MAC_PARAM_KEY\s0\fR) <octet string>" 4 +.el .IP "``key'' (\fB\s-1OSSL_MAC_PARAM_KEY\s0\fR) <octet string>" 4 +.IX Item "key (OSSL_MAC_PARAM_KEY) <octet string>" +Sets the \s-1MAC\s0 key. +Setting this parameter is identical to passing a \fIkey\fR to \fBEVP_MAC_init\fR\|(3). +.PP +The following parameters can be retrieved with +\&\fBEVP_MAC_CTX_get_params()\fR: +.ie n .IP """size"" (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``size'' (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "size (OSSL_MAC_PARAM_SIZE) <unsigned integer>" +Gets the \s-1MAC\s0 size. +.PP +The \*(L"size\*(R" parameter can also be retrieved with with \fBEVP_MAC_CTX_get_mac_size()\fR. +The length of the \*(L"size\*(R" parameter should not exceed that of an \fBunsigned int\fR. +.SH "NOTES" +.IX Header "NOTES" +The OpenSSL implementation of the Poly 1305 \s-1MAC\s0 corresponds to \s-1RFC 7539.\s0 +.PP +It is critical to never reuse the key. The security implication noted in +\&\s-1RFC 8439\s0 applies equally to the OpenSSL implementation. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MAC_CTX_get_params\fR\|(3), \fBEVP_MAC_CTX_set_params\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_MAC\s0\fR\|(3), \s-1\fBOSSL_PARAM\s0\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2018\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MAC-Siphash.7 b/secure/lib/libcrypto/man/man7/EVP_MAC-Siphash.7 new file mode 100644 index 000000000000..7d00c3d78bd2 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MAC-Siphash.7 @@ -0,0 +1,188 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MAC-SIPHASH 7ossl" +.TH EVP_MAC-SIPHASH 7ossl "2023-09-19" "3.0.11" "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_MAC\-Siphash \- The Siphash EVP_MAC implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing Siphash MACs through the \fB\s-1EVP_MAC\s0\fR \s-1API.\s0 +.SS "Identity" +.IX Subsection "Identity" +This implementation is identified with this name and properties, to be +used with \fBEVP_MAC_fetch()\fR: +.ie n .IP """\s-1SIPHASH"",\s0 ""provider=default""" 4 +.el .IP "``\s-1SIPHASH'',\s0 ``provider=default''" 4 +.IX Item "SIPHASH, provider=default" +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The general description of these parameters can be found in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_MAC\s0\fR\|(3). +.PP +All these parameters can be set with \fBEVP_MAC_CTX_set_params()\fR. +Furthermore, the \*(L"size\*(R" parameter can be retrieved with +\&\fBEVP_MAC_CTX_get_params()\fR, or with \fBEVP_MAC_CTX_get_mac_size()\fR. +The length of the \*(L"size\*(R" parameter should not exceed that of a \fBsize_t\fR. +.ie n .IP """key"" (\fB\s-1OSSL_MAC_PARAM_KEY\s0\fR) <octet string>" 4 +.el .IP "``key'' (\fB\s-1OSSL_MAC_PARAM_KEY\s0\fR) <octet string>" 4 +.IX Item "key (OSSL_MAC_PARAM_KEY) <octet string>" +Sets the \s-1MAC\s0 key. +Setting this parameter is identical to passing a \fIkey\fR to \fBEVP_MAC_init\fR\|(3). +.ie n .IP """size"" (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``size'' (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "size (OSSL_MAC_PARAM_SIZE) <unsigned integer>" +Sets the \s-1MAC\s0 size. +.ie n .IP """c\-rounds"" (\fB\s-1OSSL_MAC_PARAM_C_ROUNDS\s0\fR) <unsigned integer>" 4 +.el .IP "``c\-rounds'' (\fB\s-1OSSL_MAC_PARAM_C_ROUNDS\s0\fR) <unsigned integer>" 4 +.IX Item "c-rounds (OSSL_MAC_PARAM_C_ROUNDS) <unsigned integer>" +Specifies the number of rounds per message block. By default this is \fI2\fR. +.ie n .IP """d\-rounds"" (\fB\s-1OSSL_MAC_PARAM_D_ROUNDS\s0\fR) <unsigned integer>" 4 +.el .IP "``d\-rounds'' (\fB\s-1OSSL_MAC_PARAM_D_ROUNDS\s0\fR) <unsigned integer>" 4 +.IX Item "d-rounds (OSSL_MAC_PARAM_D_ROUNDS) <unsigned integer>" +Specifies the number of finalisation rounds. By default this is \fI4\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MAC_CTX_get_params\fR\|(3), \fBEVP_MAC_CTX_set_params\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_MAC\s0\fR\|(3), \s-1\fBOSSL_PARAM\s0\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2018\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MD-BLAKE2.7 b/secure/lib/libcrypto/man/man7/EVP_MD-BLAKE2.7 new file mode 100644 index 000000000000..b00535364c7a --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MD-BLAKE2.7 @@ -0,0 +1,168 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MD-BLAKE2 7ossl" +.TH EVP_MD-BLAKE2 7ossl "2023-09-19" "3.0.11" "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_MD\-BLAKE2 \- The BLAKE2 EVP_MD implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1BLAKE2\s0 digests through the \fB\s-1EVP_MD\s0\fR \s-1API.\s0 +.SS "Identities" +.IX Subsection "Identities" +This implementation is only available with the default provider, and +includes the following varieties: +.IP "\s-1BLAKE2S\-256\s0" 4 +.IX Item "BLAKE2S-256" +Known names are \*(L"\s-1BLAKE2S\-256\*(R"\s0 and \*(L"BLAKE2s256\*(R". +.IP "\s-1BLAKE2B\-512\s0" 4 +.IX Item "BLAKE2B-512" +Known names are \*(L"\s-1BLAKE2B\-512\*(R"\s0 and \*(L"BLAKE2b512\*(R". +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2022 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MD-MD2.7 b/secure/lib/libcrypto/man/man7/EVP_MD-MD2.7 new file mode 100644 index 000000000000..c3bbd22b5117 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MD-MD2.7 @@ -0,0 +1,162 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MD-MD2 7ossl" +.TH EVP_MD-MD2 7ossl "2023-09-19" "3.0.11" "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_MD\-MD2 \- The MD2 EVP_MD implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1MD2\s0 digests through the \fB\s-1EVP_MD\s0\fR \s-1API.\s0 +.SS "Identity" +.IX Subsection "Identity" +This implementation is only available with the legacy provider, and is +identified with the name \*(L"\s-1MD2\*(R".\s0 +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MD-MD4.7 b/secure/lib/libcrypto/man/man7/EVP_MD-MD4.7 new file mode 100644 index 000000000000..c171280822fd --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MD-MD4.7 @@ -0,0 +1,162 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MD-MD4 7ossl" +.TH EVP_MD-MD4 7ossl "2023-09-19" "3.0.11" "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_MD\-MD4 \- The MD4 EVP_MD implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1MD4\s0 digests through the \fB\s-1EVP_MD\s0\fR \s-1API.\s0 +.SS "Identity" +.IX Subsection "Identity" +This implementation is only available with the legacy provider, and is +identified with the name \*(L"\s-1MD4\*(R".\s0 +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MD-MD5-SHA1.7 b/secure/lib/libcrypto/man/man7/EVP_MD-MD5-SHA1.7 new file mode 100644 index 000000000000..e64d91a41161 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MD-MD5-SHA1.7 @@ -0,0 +1,179 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MD-MD5-SHA1 7ossl" +.TH EVP_MD-MD5-SHA1 7ossl "2023-09-19" "3.0.11" "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_MD\-MD5\-SHA1 \- The MD5\-SHA1 EVP_MD implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1MD5\-SHA1\s0 digests through the \fB\s-1EVP_MD\s0\fR \s-1API.\s0 +.PP +\&\s-1MD5\-SHA1\s0 is a rather special digest that's used with SSLv3. +.SS "Identity" +.IX Subsection "Identity" +This implementation is only available with the default provider, and is +identified with the name \*(L"\s-1MD5\-SHA1\*(R".\s0 +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SS "Settable Context Parameters" +.IX Subsection "Settable Context Parameters" +This implementation supports the following \s-1\fBOSSL_PARAM\s0\fR\|(3) entries, +settable for an \fB\s-1EVP_MD_CTX\s0\fR with \fBEVP_MD_CTX_set_params\fR\|(3): +.ie n .IP """ssl3\-ms"" (\fB\s-1OSSL_DIGEST_PARAM_SSL3_MS\s0\fR) <octet string>" 4 +.el .IP "``ssl3\-ms'' (\fB\s-1OSSL_DIGEST_PARAM_SSL3_MS\s0\fR) <octet string>" 4 +.IX Item "ssl3-ms (OSSL_DIGEST_PARAM_SSL3_MS) <octet string>" +This parameter is set by libssl in order to calculate a signature hash for an +SSLv3 CertificateVerify message as per \s-1RFC6101.\s0 +It is only set after all handshake messages have already been digested via +\&\fBOP_digest_update()\fR calls. +The parameter provides the master secret value to be added to the digest. +The digest implementation should calculate the complete digest as per \s-1RFC6101\s0 +section 5.6.8. +The next call after setting this parameter should be \fBOP_digest_final()\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MD_CTX_set_params\fR\|(3), \fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MD-MD5.7 b/secure/lib/libcrypto/man/man7/EVP_MD-MD5.7 new file mode 100644 index 000000000000..817b9529efb4 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MD-MD5.7 @@ -0,0 +1,162 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MD-MD5 7ossl" +.TH EVP_MD-MD5 7ossl "2023-09-19" "3.0.11" "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_MD\-MD5 \- The MD5 EVP_MD implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1MD5\s0 digests through the \fB\s-1EVP_MD\s0\fR \s-1API.\s0 +.SS "Identity" +.IX Subsection "Identity" +This implementation is only available with the default provider, and is +identified with the name \*(L"\s-1MD5\*(R".\s0 +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MD-MDC2.7 b/secure/lib/libcrypto/man/man7/EVP_MD-MDC2.7 new file mode 100644 index 000000000000..d637c89a2424 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MD-MDC2.7 @@ -0,0 +1,173 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MD-MDC2 7ossl" +.TH EVP_MD-MDC2 7ossl "2023-09-19" "3.0.11" "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_MD\-MDC2 \- The MDC2 EVP_MD implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1MDC2\s0 digests through the \fB\s-1EVP_MD\s0\fR \s-1API.\s0 +.SS "Identity" +.IX Subsection "Identity" +This implementation is only available with the legacy provider, and is +identified with the name \*(L"\s-1MDC2\*(R".\s0 +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SS "Settable Context Parameters" +.IX Subsection "Settable Context Parameters" +This implementation supports the following \s-1\fBOSSL_PARAM\s0\fR\|(3) entries, +settable for an \fB\s-1EVP_MD_CTX\s0\fR with \fBEVP_MD_CTX_set_params\fR\|(3): +.ie n .IP """pad-type"" (\fB\s-1OSSL_DIGEST_PARAM_PAD_TYPE\s0\fR) <unsigned integer>" 4 +.el .IP "``pad-type'' (\fB\s-1OSSL_DIGEST_PARAM_PAD_TYPE\s0\fR) <unsigned integer>" 4 +.IX Item "pad-type (OSSL_DIGEST_PARAM_PAD_TYPE) <unsigned integer>" +Sets the padding type to be used. +Normally the final \s-1MDC2\s0 block is padded with zeros. +If the pad type is set to 2 then the final block is padded with 0x80 followed by +zeros. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MD_CTX_set_params\fR\|(3), \fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-legacy\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 \*(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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MD-NULL.7 b/secure/lib/libcrypto/man/man7/EVP_MD-NULL.7 new file mode 100644 index 000000000000..699a8b29355e --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MD-NULL.7 @@ -0,0 +1,167 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MD-NULL 7ossl" +.TH EVP_MD-NULL 7ossl "2023-09-19" "3.0.11" "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_MD\-NULL \- The NULL EVP_MD implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for a \s-1NULL\s0 digest through the \fB\s-1EVP_MD\s0\fR \s-1API.\s0 +This algorithm does nothing and returns 1 for its init, +update and final methods. +.SS "Algorithm Name" +.IX Subsection "Algorithm Name" +The following algorithm is available in the default provider: +.ie n .IP """\s-1NULL""\s0" 4 +.el .IP "``\s-1NULL''\s0" 4 +.IX Item "NULL" +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MD_CTX_set_params\fR\|(3), \fBprovider\-digest\fR\|(7), +\&\fBOSSL_PROVIDER\-default\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2023 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MD-RIPEMD160.7 b/secure/lib/libcrypto/man/man7/EVP_MD-RIPEMD160.7 new file mode 100644 index 000000000000..eb080649e373 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MD-RIPEMD160.7 @@ -0,0 +1,166 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MD-RIPEMD160 7ossl" +.TH EVP_MD-RIPEMD160 7ossl "2023-09-19" "3.0.11" "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_MD\-RIPEMD160 \- The RIPEMD160 EVP_MD implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1RIPEMD160\s0 digests through the \fB\s-1EVP_MD\s0\fR \s-1API.\s0 +.SS "Identities" +.IX Subsection "Identities" +This implementation is available in both the default and legacy providers, and is +identified with any of the names \*(L"\s-1RIPEMD\-160\*(R", \*(L"RIPEMD160\*(R", \*(L"RIPEMD\*(R"\s0 and +\&\*(L"\s-1RMD160\*(R".\s0 +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +This digest was added to the default provider in OpenSSL 3.0.7. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2022 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MD-SHA1.7 b/secure/lib/libcrypto/man/man7/EVP_MD-SHA1.7 new file mode 100644 index 000000000000..6d93e505502f --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MD-SHA1.7 @@ -0,0 +1,178 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MD-SHA1 7ossl" +.TH EVP_MD-SHA1 7ossl "2023-09-19" "3.0.11" "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_MD\-SHA1 \- The SHA1 EVP_MD implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1SHA1\s0 digests through the \fB\s-1EVP_MD\s0\fR \s-1API.\s0 +.SS "Identities" +.IX Subsection "Identities" +This implementation is available with the \s-1FIPS\s0 provider as well as the +default provider, and is identified with the names \*(L"\s-1SHA1\*(R"\s0 and \*(L"\s-1SHA\-1\*(R".\s0 +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SS "Settable Context Parameters" +.IX Subsection "Settable Context Parameters" +This implementation supports the following \s-1\fBOSSL_PARAM\s0\fR\|(3) entries, +settable for an \fB\s-1EVP_MD_CTX\s0\fR with \fBEVP_MD_CTX_set_params\fR\|(3): +.ie n .IP """ssl3\-ms"" (\fB\s-1OSSL_DIGEST_PARAM_SSL3_MS\s0\fR) <octet string>" 4 +.el .IP "``ssl3\-ms'' (\fB\s-1OSSL_DIGEST_PARAM_SSL3_MS\s0\fR) <octet string>" 4 +.IX Item "ssl3-ms (OSSL_DIGEST_PARAM_SSL3_MS) <octet string>" +This parameter is set by libssl in order to calculate a signature hash for an +SSLv3 CertificateVerify message as per \s-1RFC6101.\s0 +It is only set after all handshake messages have already been digested via +\&\fBOP_digest_update()\fR calls. +The parameter provides the master secret value to be added to the digest. +The digest implementation should calculate the complete digest as per \s-1RFC6101\s0 +section 5.6.8. +The next call after setting this parameter should be \fBOP_digest_final()\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MD_CTX_set_params\fR\|(3), \fBprovider\-digest\fR\|(7), +\&\s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MD-SHA2.7 b/secure/lib/libcrypto/man/man7/EVP_MD-SHA2.7 new file mode 100644 index 000000000000..bf33c33221f1 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MD-SHA2.7 @@ -0,0 +1,191 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MD-SHA2 7ossl" +.TH EVP_MD-SHA2 7ossl "2023-09-19" "3.0.11" "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_MD\-SHA2 \- The SHA2 EVP_MD implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1SHA2\s0 digests through the \fB\s-1EVP_MD\s0\fR \s-1API.\s0 +.SS "Identities" +.IX Subsection "Identities" +This implementation includes the following varieties: +.IP "\(bu" 4 +Available with the \s-1FIPS\s0 provider as well as the default provider: +.RS 4 +.IP "\s-1SHA2\-224\s0" 4 +.IX Item "SHA2-224" +Known names are \*(L"\s-1SHA2\-224\*(R", \*(L"SHA\-224\*(R"\s0 and \*(L"\s-1SHA224\*(R".\s0 +.IP "\s-1SHA2\-256\s0" 4 +.IX Item "SHA2-256" +Known names are \*(L"\s-1SHA2\-256\*(R", \*(L"SHA\-256\*(R"\s0 and \*(L"\s-1SHA256\*(R".\s0 +.IP "\s-1SHA2\-384\s0" 4 +.IX Item "SHA2-384" +Known names are \*(L"\s-1SHA2\-384\*(R", \*(L"SHA\-384\*(R"\s0 and \*(L"\s-1SHA384\*(R".\s0 +.IP "\s-1SHA2\-512\s0" 4 +.IX Item "SHA2-512" +Known names are \*(L"\s-1SHA2\-512\*(R", \*(L"SHA\-512\*(R"\s0 and \*(L"\s-1SHA512\*(R".\s0 +.RE +.RS 4 +.RE +.IP "\(bu" 4 +Available with the default provider: +.RS 4 +.IP "\s-1SHA2\-512/224\s0" 4 +.IX Item "SHA2-512/224" +Known names are \*(L"\s-1SHA2\-512/224\*(R", \*(L"SHA\-512/224\*(R"\s0 and \*(L"\s-1SHA512\-224\*(R".\s0 +.IP "\s-1SHA2\-512/256\s0" 4 +.IX Item "SHA2-512/256" +Known names are \*(L"\s-1SHA2\-512/256\*(R", \*(L"SHA\-512/256\*(R"\s0 and \*(L"\s-1SHA512\-256\*(R".\s0 +.RE +.RS 4 +.RE +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MD-SHA3.7 b/secure/lib/libcrypto/man/man7/EVP_MD-SHA3.7 new file mode 100644 index 000000000000..62cf05474936 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MD-SHA3.7 @@ -0,0 +1,176 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MD-SHA3 7ossl" +.TH EVP_MD-SHA3 7ossl "2023-09-19" "3.0.11" "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_MD\-SHA3 \- The SHA3 EVP_MD implementations +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1SHA3\s0 digests through the \fB\s-1EVP_MD\s0\fR \s-1API.\s0 +.SS "Identities" +.IX Subsection "Identities" +This implementation is available with the \s-1FIPS\s0 provider as well as the +default provider, and includes the following varieties: +.ie n .IP """\s-1SHA3\-224""\s0" 4 +.el .IP "``\s-1SHA3\-224''\s0" 4 +.IX Item "SHA3-224" +.PD 0 +.ie n .IP """\s-1SHA3\-256""\s0" 4 +.el .IP "``\s-1SHA3\-256''\s0" 4 +.IX Item "SHA3-256" +.ie n .IP """\s-1SHA3\-384""\s0" 4 +.el .IP "``\s-1SHA3\-384''\s0" 4 +.IX Item "SHA3-384" +.ie n .IP """\s-1SHA3\-512""\s0" 4 +.el .IP "``\s-1SHA3\-512''\s0" 4 +.IX Item "SHA3-512" +.PD +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MD-SHAKE.7 b/secure/lib/libcrypto/man/man7/EVP_MD-SHAKE.7 new file mode 100644 index 000000000000..4d3be8040de0 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MD-SHAKE.7 @@ -0,0 +1,198 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MD-SHAKE 7ossl" +.TH EVP_MD-SHAKE 7ossl "2023-09-19" "3.0.11" "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_MD\-SHAKE, EVP_MD\-KECCAK\-KMAC +\&\- The SHAKE / KECCAK family EVP_MD implementations +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1SHAKE\s0 or KECCAK-KMAC digests through the +\&\fB\s-1EVP_MD\s0\fR \s-1API.\s0 +.PP +KECCAK-KMAC is a special digest that's used by the \s-1KMAC EVP_MAC\s0 +implementation (see \s-1\fBEVP_MAC\-KMAC\s0\fR\|(7)). +.SS "Identities" +.IX Subsection "Identities" +This implementation is available in the \s-1FIPS\s0 provider as well as the default +provider, and includes the following varieties: +.IP "\s-1KECCAK\-KMAC\-128\s0" 4 +.IX Item "KECCAK-KMAC-128" +Known names are \*(L"\s-1KECCAK\-KMAC\-128\*(R"\s0 and \*(L"\s-1KECCAK\-KMAC128\*(R"\s0 +This is used by \s-1\fBEVP_MAC\-KMAC128\s0\fR\|(7) +.IP "\s-1KECCAK\-KMAC\-256\s0" 4 +.IX Item "KECCAK-KMAC-256" +Known names are \*(L"\s-1KECCAK\-KMAC\-256\*(R"\s0 and \*(L"\s-1KECCAK\-KMAC256\*(R"\s0 +This is used by \s-1\fBEVP_MAC\-KMAC256\s0\fR\|(7) +.IP "\s-1SHAKE\-128\s0" 4 +.IX Item "SHAKE-128" +Known names are \*(L"\s-1SHAKE\-128\*(R"\s0 and \*(L"\s-1SHAKE128\*(R"\s0 +.IP "\s-1SHAKE\-256\s0" 4 +.IX Item "SHAKE-256" +Known names are \*(L"\s-1SHAKE\-256\*(R"\s0 and \*(L"\s-1SHAKE256\*(R"\s0 +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SS "Settable Context Parameters" +.IX Subsection "Settable Context Parameters" +These implementations support the following \s-1\fBOSSL_PARAM\s0\fR\|(3) entries, +settable for an \fB\s-1EVP_MD_CTX\s0\fR with \fBEVP_MD_CTX_set_params\fR\|(3): +.ie n .IP """xoflen"" (\fB\s-1OSSL_DIGEST_PARAM_XOFLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``xoflen'' (\fB\s-1OSSL_DIGEST_PARAM_XOFLEN\s0\fR) <unsigned integer>" 4 +.IX Item "xoflen (OSSL_DIGEST_PARAM_XOFLEN) <unsigned integer>" +Sets the digest length for extendable output functions. +The length of the \*(L"xoflen\*(R" parameter should not exceed that of a \fBsize_t\fR. +.Sp +For backwards compatibility reasons the default xoflen length for \s-1SHAKE\-128\s0 is +16 (bytes) which results in a security strength of only 64 bits. To ensure the +maximum security strength of 128 bits, the xoflen should be set to at least 32. +.Sp +For backwards compatibility reasons the default xoflen length for \s-1SHAKE\-256\s0 is +32 (bytes) which results in a security strength of only 128 bits. To ensure the +maximum security strength of 256 bits, the xoflen should be set to at least 64. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MD_CTX_set_params\fR\|(3), \fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2022 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MD-SM3.7 b/secure/lib/libcrypto/man/man7/EVP_MD-SM3.7 new file mode 100644 index 000000000000..2e0fb458e534 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MD-SM3.7 @@ -0,0 +1,162 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MD-SM3 7ossl" +.TH EVP_MD-SM3 7ossl "2023-09-19" "3.0.11" "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_MD\-SM3 \- The SM3 EVP_MD implementations +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1SM3\s0 digests through the \fB\s-1EVP_MD\s0\fR \s-1API.\s0 +.SS "Identity" +.IX Subsection "Identity" +This implementation is only available with the default provider, and is +identified with the name \*(L"\s-1SM3\*(R".\s0 +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MD-WHIRLPOOL.7 b/secure/lib/libcrypto/man/man7/EVP_MD-WHIRLPOOL.7 new file mode 100644 index 000000000000..2a241ef83862 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MD-WHIRLPOOL.7 @@ -0,0 +1,162 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MD-WHIRLPOOL 7ossl" +.TH EVP_MD-WHIRLPOOL 7ossl "2023-09-19" "3.0.11" "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_MD\-WHIRLPOOL \- The WHIRLPOOL EVP_MD implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1WHIRLPOOL\s0 digests through the \fB\s-1EVP_MD\s0\fR \s-1API.\s0 +.SS "Identity" +.IX Subsection "Identity" +This implementation is only available with the legacy provider, and is +identified with the name \*(L"\s-1WHIRLPOOL\*(R".\s0 +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_MD-common.7 b/secure/lib/libcrypto/man/man7/EVP_MD-common.7 new file mode 100644 index 000000000000..b5648944f9c4 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_MD-common.7 @@ -0,0 +1,181 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_MD-COMMON 7ossl" +.TH EVP_MD-COMMON 7ossl "2023-09-19" "3.0.11" "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_MD\-common \- The OpenSSL EVP_MD implementations, common things +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +All the OpenSSL \s-1EVP_MD\s0 implementations understand the following +\&\s-1\fBOSSL_PARAM\s0\fR\|(3) entries that are +gettable with \fBEVP_MD_get_params\fR\|(3), as well as these: +.ie n .IP """blocksize"" (\fB\s-1OSSL_DIGEST_PARAM_BLOCK_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``blocksize'' (\fB\s-1OSSL_DIGEST_PARAM_BLOCK_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "blocksize (OSSL_DIGEST_PARAM_BLOCK_SIZE) <unsigned integer>" +The digest block size. +The length of the \*(L"blocksize\*(R" parameter should not exceed that of a +\&\fBsize_t\fR. +.Sp +This value can also be retrieved with \fBEVP_MD_get_block_size\fR\|(3). +.ie n .IP """size"" (\fB\s-1OSSL_DIGEST_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``size'' (\fB\s-1OSSL_DIGEST_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "size (OSSL_DIGEST_PARAM_SIZE) <unsigned integer>" +The digest output size. +The length of the \*(L"size\*(R" parameter should not exceed that of a \fBsize_t\fR. +.Sp +This value can also be retrieved with \fBEVP_MD_get_size\fR\|(3). +.ie n .IP """flags"" (\fB\s-1OSSL_DIGEST_PARAM_FLAGS\s0\fR) <unsigned integer>" 4 +.el .IP "``flags'' (\fB\s-1OSSL_DIGEST_PARAM_FLAGS\s0\fR) <unsigned integer>" 4 +.IX Item "flags (OSSL_DIGEST_PARAM_FLAGS) <unsigned integer>" +Diverse flags that describe exceptional behaviour for the digest. +These flags are described in \*(L"\s-1DESCRIPTION\*(R"\s0 in \fBEVP_MD_meth_set_flags\fR\|(3). +.Sp +The length of the \*(L"flags\*(R" parameter should equal that of an +\&\fBunsigned long int\fR. +.Sp +This value can also be retrieved with \fBEVP_MD_get_flags\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MD_get_params\fR\|(3), \fBprovider\-digest\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 \*(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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_PKEY-DH.7 b/secure/lib/libcrypto/man/man7/EVP_PKEY-DH.7 new file mode 100644 index 000000000000..69d92750e3eb --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_PKEY-DH.7 @@ -0,0 +1,455 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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-DH 7ossl" +.TH EVP_PKEY-DH 7ossl "2023-09-19" "3.0.11" "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\-DH, EVP_PKEY\-DHX, EVP_KEYMGMT\-DH, EVP_KEYMGMT\-DHX +\&\- EVP_PKEY DH and DHX keytype and algorithm support +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +For \fB\s-1DH\s0\fR \s-1FFC\s0 key agreement, two classes of domain parameters can be used: +\&\*(L"safe\*(R" domain parameters that are associated with approved named safe-prime +groups, and a class of \*(L"FIPS186\-type\*(R" domain parameters. FIPS186\-type domain +parameters should only be used for backward compatibility with existing +applications that cannot be upgraded to use the approved safe-prime groups. +.PP +See \s-1\fBEVP_PKEY\-FFC\s0\fR\|(7) for more information about \s-1FFC\s0 keys. +.PP +The \fB\s-1DH\s0\fR key type uses PKCS#3 format which saves \fIp\fR and \fIg\fR, but not the +\&\fIq\fR value. +The \fB\s-1DHX\s0\fR key type uses X9.42 format which saves the value of \fIq\fR and this +must be used for \s-1FIPS186\-4.\s0 If key validation is required, users should be aware +of the nuances associated with \s-1FIPS186\-4\s0 style parameters as discussed in +\&\*(L"\s-1DH\s0 key validation\*(R". +.SS "\s-1DH\s0 and \s-1DHX\s0 domain parameters" +.IX Subsection "DH and DHX domain parameters" +In addition to the common \s-1FCC\s0 parameters that all \s-1FFC\s0 keytypes should support +(see \*(L"\s-1FFC\s0 parameters\*(R" in \s-1\fBEVP_PKEY\-FFC\s0\fR\|(7)) the \fB\s-1DHX\s0\fR and \fB\s-1DH\s0\fR keytype +implementations support the following: +.ie n .IP """group"" (\fB\s-1OSSL_PKEY_PARAM_GROUP_NAME\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``group'' (\fB\s-1OSSL_PKEY_PARAM_GROUP_NAME\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "group (OSSL_PKEY_PARAM_GROUP_NAME) <UTF8 string>" +Sets or gets a string that associates a \fB\s-1DH\s0\fR or \fB\s-1DHX\s0\fR named safe prime group +with known values for \fIp\fR, \fIq\fR and \fIg\fR. +.Sp +The following values can be used by the OpenSSL's default and \s-1FIPS\s0 providers: +\&\*(L"ffdhe2048\*(R", \*(L"ffdhe3072\*(R", \*(L"ffdhe4096\*(R", \*(L"ffdhe6144\*(R", \*(L"ffdhe8192\*(R", +\&\*(L"modp_2048\*(R", \*(L"modp_3072\*(R", \*(L"modp_4096\*(R", \*(L"modp_6144\*(R", \*(L"modp_8192\*(R". +.Sp +The following additional values can also be used by OpenSSL's default provider: +\&\*(L"modp_1536\*(R", \*(L"dh_1024_160\*(R", \*(L"dh_2048_224\*(R", \*(L"dh_2048_256\*(R". +.Sp +\&\s-1DH/DHX\s0 named groups can be easily validated since the parameters are well known. +For protocols that only transfer \fIp\fR and \fIg\fR the value of \fIq\fR can also be +retrieved. +.SS "\s-1DH\s0 and \s-1DHX\s0 additional parameters" +.IX Subsection "DH and DHX additional parameters" +.ie n .IP """encoded-pub-key"" (\fB\s-1OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY\s0\fR) <octet string>" 4 +.el .IP "``encoded-pub-key'' (\fB\s-1OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY\s0\fR) <octet string>" 4 +.IX Item "encoded-pub-key (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) <octet string>" +Used for getting and setting the encoding of the \s-1DH\s0 public key used in a key +exchange message for the \s-1TLS\s0 protocol. +See \fBEVP_PKEY_set1_encoded_public_key()\fR and \fBEVP_PKEY_get1_encoded_public_key()\fR. +.SS "\s-1DH\s0 additional domain parameters" +.IX Subsection "DH additional domain parameters" +.ie n .IP """safeprime-generator"" (\fB\s-1OSSL_PKEY_PARAM_DH_GENERATOR\s0\fR) <integer>" 4 +.el .IP "``safeprime-generator'' (\fB\s-1OSSL_PKEY_PARAM_DH_GENERATOR\s0\fR) <integer>" 4 +.IX Item "safeprime-generator (OSSL_PKEY_PARAM_DH_GENERATOR) <integer>" +Used for \s-1DH\s0 generation of safe primes using the old safe prime generator code. +The default value is 2. +It is recommended to use a named safe prime group instead, if domain parameter +validation is required. +.Sp +Randomly generated safe primes are not allowed by \s-1FIPS,\s0 so setting this value +for the OpenSSL \s-1FIPS\s0 provider will instead choose a named safe prime group +based on the size of \fIp\fR. +.SS "\s-1DH\s0 and \s-1DHX\s0 domain parameter / key generation parameters" +.IX Subsection "DH and DHX domain parameter / key generation parameters" +In addition to the common \s-1FFC\s0 key generation parameters that all \s-1FFC\s0 key types +should support (see \*(L"\s-1FFC\s0 key generation parameters\*(R" in \s-1\fBEVP_PKEY\-FFC\s0\fR\|(7)) the +\&\fB\s-1DH\s0\fR and \fB\s-1DHX\s0\fR keytype implementation supports the following: +.ie n .IP """type"" (\fB\s-1OSSL_PKEY_PARAM_FFC_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``type'' (\fB\s-1OSSL_PKEY_PARAM_FFC_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "type (OSSL_PKEY_PARAM_FFC_TYPE) <UTF8 string>" +Sets the type of parameter generation. For \fB\s-1DH\s0\fR valid values are: +.RS 4 +.ie n .IP """fips186_4""" 4 +.el .IP "``fips186_4''" 4 +.IX Item "fips186_4" +.PD 0 +.ie n .IP """default""" 4 +.el .IP "``default''" 4 +.IX Item "default" +.ie n .IP """fips186_2""" 4 +.el .IP "``fips186_2''" 4 +.IX Item "fips186_2" +.PD +These are described in \*(L"\s-1FFC\s0 key generation parameters\*(R" in \s-1\fBEVP_PKEY\-FFC\s0\fR\|(7) +.ie n .IP """group""" 4 +.el .IP "``group''" 4 +.IX Item "group" +This specifies that a named safe prime name will be chosen using the \*(L"pbits\*(R" +type. +.ie n .IP """generator""" 4 +.el .IP "``generator''" 4 +.IX Item "generator" +A safe prime generator. See the \*(L"safeprime-generator\*(R" type above. +This is only valid for \fB\s-1DH\s0\fR keys. +.RE +.RS 4 +.RE +.ie n .IP """pbits"" (\fB\s-1OSSL_PKEY_PARAM_FFC_PBITS\s0\fR) <unsigned integer>" 4 +.el .IP "``pbits'' (\fB\s-1OSSL_PKEY_PARAM_FFC_PBITS\s0\fR) <unsigned integer>" 4 +.IX Item "pbits (OSSL_PKEY_PARAM_FFC_PBITS) <unsigned integer>" +Sets the size (in bits) of the prime 'p'. +.Sp +For \*(L"fips186_4\*(R" this must be 2048. +For \*(L"fips186_2\*(R" this must be 1024. +For \*(L"group\*(R" this can be any one of 2048, 3072, 4096, 6144 or 8192. +.ie n .IP """priv_len"" (\fB\s-1OSSL_PKEY_PARAM_DH_PRIV_LEN\s0\fR) <integer>" 4 +.el .IP "``priv_len'' (\fB\s-1OSSL_PKEY_PARAM_DH_PRIV_LEN\s0\fR) <integer>" 4 +.IX Item "priv_len (OSSL_PKEY_PARAM_DH_PRIV_LEN) <integer>" +An optional value to set the maximum length of the generated private key. +The default value used if this is not set is the maximum value of +BN_num_bits(\fIq\fR)). The minimum value that this can be set to is 2 * s. +Where s is the security strength of the key which has values of +112, 128, 152, 176 and 200 for key sizes of 2048, 3072, 4096, 6144 and 8192. +.SS "\s-1DH\s0 key validation" +.IX Subsection "DH key validation" +For \fB\s-1DHX\s0\fR that is not a named group the \s-1FIPS186\-4\s0 standard specifies that the +values used for \s-1FFC\s0 parameter generation are also required for parameter +validation. This means that optional \s-1FFC\s0 domain parameter values for +\&\fIseed\fR, \fIpcounter\fR and \fIgindex\fR or \fIhindex\fR may need to be stored for +validation purposes. +For \fB\s-1DHX\s0\fR the \fIseed\fR and \fIpcounter\fR can be stored in \s-1ASN1\s0 data +(but the \fIgindex\fR or \fIhindex\fR cannot be stored). It is recommended to use a +named safe prime group instead. +.PP +For \s-1DH\s0 keys, \fBEVP_PKEY_param_check\fR\|(3) behaves in the following way: +The OpenSSL \s-1FIPS\s0 provider tests if the parameters are either an approved safe +prime group \s-1OR\s0 that the \s-1FFC\s0 parameters conform to \s-1FIPS186\-4\s0 as defined in +SP800\-56Ar3 \fIAssurances of Domain-Parameter Validity\fR. +The OpenSSL default provider uses simpler checks that allows there to be no \fIq\fR +value for backwards compatibility. +.PP +For \s-1DH\s0 keys, \fBEVP_PKEY_param_check_quick\fR\|(3) is equivalent to +\&\fBEVP_PKEY_param_check\fR\|(3). +.PP +For \s-1DH\s0 keys, \fBEVP_PKEY_public_check\fR\|(3) conforms to +SP800\-56Ar3 \fI\s-1FFC\s0 Full Public-Key Validation\fR. +.PP +For \s-1DH\s0 keys, \fBEVP_PKEY_public_check_quick\fR\|(3) conforms to +SP800\-56Ar3 \fI\s-1FFC\s0 Partial Public-Key Validation\fR when the +\&\s-1DH\s0 key is an approved named safe prime group, otherwise it is the same as +\&\fBEVP_PKEY_public_check\fR\|(3). +.PP +For \s-1DH\s0 Keys, \fBEVP_PKEY_private_check\fR\|(3) tests that the private key is in the +correct range according to SP800\-56Ar3. The OpenSSL \s-1FIPS\s0 provider requires the +value of \fIq\fR to be set (note that this is set for named safe prime groups). +For backwards compatibility the OpenSSL default provider only requires \fIp\fR to +be set. +.PP +For \s-1DH\s0 keys, \fBEVP_PKEY_pairwise_check\fR\|(3) conforms to +SP800\-56Ar3 \fIOwner Assurance of Pair-wise Consistency\fR. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +An \fB\s-1EVP_PKEY\s0\fR context can be obtained by calling: +.PP +.Vb 1 +\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL); +.Ve +.PP +A \fB\s-1DH\s0\fR key can be generated with a named safe prime group by calling: +.PP +.Vb 4 +\& int priv_len = 2 * 112; +\& OSSL_PARAM params[3]; +\& EVP_PKEY *pkey = NULL; +\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL); +\& +\& params[0] = OSSL_PARAM_construct_utf8_string("group", "ffdhe2048", 0); +\& /* "priv_len" is optional */ +\& params[1] = OSSL_PARAM_construct_int("priv_len", &priv_len); +\& params[2] = OSSL_PARAM_construct_end(); +\& +\& EVP_PKEY_keygen_init(pctx); +\& EVP_PKEY_CTX_set_params(pctx, params); +\& EVP_PKEY_generate(pctx, &pkey); +\& ... +\& EVP_PKEY_free(pkey); +\& EVP_PKEY_CTX_free(pctx); +.Ve +.PP +\&\fB\s-1DHX\s0\fR domain parameters can be generated according to \fB\s-1FIPS186\-4\s0\fR by calling: +.PP +.Vb 6 +\& int gindex = 2; +\& unsigned int pbits = 2048; +\& unsigned int qbits = 256; +\& OSSL_PARAM params[6]; +\& EVP_PKEY *param_key = NULL; +\& EVP_PKEY_CTX *pctx = NULL; +\& +\& pctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL); +\& EVP_PKEY_paramgen_init(pctx); +\& +\& params[0] = OSSL_PARAM_construct_uint("pbits", &pbits); +\& params[1] = OSSL_PARAM_construct_uint("qbits", &qbits); +\& params[2] = OSSL_PARAM_construct_int("gindex", &gindex); +\& params[3] = OSSL_PARAM_construct_utf8_string("type", "fips186_4", 0); +\& params[4] = OSSL_PARAM_construct_utf8_string("digest", "SHA256", 0); +\& params[5] = OSSL_PARAM_construct_end(); +\& EVP_PKEY_CTX_set_params(pctx, params); +\& +\& EVP_PKEY_generate(pctx, ¶m_key); +\& +\& EVP_PKEY_print_params(bio_out, param_key, 0, NULL); +\& ... +\& EVP_PKEY_free(param_key); +\& EVP_PKEY_CTX_free(pctx); +.Ve +.PP +A \fB\s-1DH\s0\fR key can be generated using domain parameters by calling: +.PP +.Vb 2 +\& EVP_PKEY *key = NULL; +\& EVP_PKEY_CTX *gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL); +\& +\& EVP_PKEY_keygen_init(gctx); +\& EVP_PKEY_generate(gctx, &key); +\& EVP_PKEY_print_private(bio_out, key, 0, NULL); +\& ... +\& EVP_PKEY_free(key); +\& EVP_PKEY_CTX_free(gctx); +.Ve +.PP +To validate \fB\s-1FIPS186\-4\s0\fR \fB\s-1DHX\s0\fR domain parameters decoded from \fB\s-1PEM\s0\fR or +\&\fB\s-1DER\s0\fR data, additional values used during generation may be required to +be set into the key. +.PP +\&\fBEVP_PKEY_todata()\fR, \fBOSSL_PARAM_merge()\fR, and \fBEVP_PKEY_fromdata()\fR are useful +to add these parameters to the original key or domain parameters before +the actual validation. In production code the return values should be checked. +.PP +.Vb 11 +\& EVP_PKEY *received_domp = ...; /* parameters received and decoded */ +\& unsigned char *seed = ...; /* and additional parameters received */ +\& size_t seedlen = ...; /* by other means, required */ +\& int gindex = ...; /* for the validation */ +\& int pcounter = ...; +\& int hindex = ...; +\& OSSL_PARAM extra_params[4]; +\& OSSL_PARAM *domain_params = NULL; +\& OSSL_PARAM *merged_params = NULL; +\& EVP_PKEY_CTX *ctx = NULL, *validate_ctx = NULL; +\& EVP_PKEY *complete_domp = NULL; +\& +\& EVP_PKEY_todata(received_domp, OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS, +\& &domain_params); +\& extra_params[0] = OSSL_PARAM_construct_octet_string("seed", seed, seedlen); +\& /* +\& * NOTE: For unverifiable g use "hindex" instead of "gindex" +\& * extra_params[1] = OSSL_PARAM_construct_int("hindex", &hindex); +\& */ +\& extra_params[1] = OSSL_PARAM_construct_int("gindex", &gindex); +\& extra_params[2] = OSSL_PARAM_construct_int("pcounter", &pcounter); +\& extra_params[3] = OSSL_PARAM_construct_end(); +\& merged_params = OSSL_PARAM_merge(domain_params, extra_params); +\& +\& ctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL); +\& EVP_PKEY_fromdata_init(ctx); +\& EVP_PKEY_fromdata(ctx, &complete_domp, OSSL_KEYMGMT_SELECT_ALL, +\& merged_params); +\& +\& validate_ctx = EVP_PKEY_CTX_new_from_pkey(NULL, complete_domp, NULL); +\& if (EVP_PKEY_param_check(validate_ctx) > 0) +\& /* validation_passed(); */ +\& else +\& /* validation_failed(); */ +\& +\& OSSL_PARAM_free(domain_params); +\& OSSL_PARAM_free(merged_params); +\& EVP_PKEY_CTX_free(ctx); +\& EVP_PKEY_CTX_free(validate_ctx); +\& EVP_PKEY_free(complete_domp); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +.IP "\s-1RFC 7919\s0 (\s-1TLS\s0 ffdhe named safe prime groups)" 4 +.IX Item "RFC 7919 (TLS ffdhe named safe prime groups)" +.PD 0 +.IP "\s-1RFC 3526\s0 (\s-1IKE\s0 modp named safe prime groups)" 4 +.IX Item "RFC 3526 (IKE modp named safe prime groups)" +.ie n .IP "\s-1RFC 5114\s0 (Additional \s-1DH\s0 named groups for dh_1024_160"", ""dh_2048_224"" and ""dh_2048_256"")." 4 +.el .IP "\s-1RFC 5114\s0 (Additional \s-1DH\s0 named groups for dh_1024_160``, ''dh_2048_224`` and ''dh_2048_256"")." 4 +.IX Item "RFC 5114 (Additional DH named groups for dh_1024_160, dh_2048_224 and dh_2048_256"")." +.PD +.PP +The following sections of SP800\-56Ar3: +.IP "5.5.1.1 \s-1FFC\s0 Domain Parameter Selection/Generation" 4 +.IX Item "5.5.1.1 FFC Domain Parameter Selection/Generation" +.PD 0 +.IP "Appendix D: \s-1FFC\s0 Safe-prime Groups" 4 +.IX Item "Appendix D: FFC Safe-prime Groups" +.PD +.PP +The following sections of \s-1FIPS186\-4:\s0 +.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" +\&\s-1\fBEVP_PKEY\-FFC\s0\fR\|(7), +\&\s-1\fBEVP_KEYEXCH\-DH\s0\fR\|(7) +\&\s-1\fBEVP_PKEY\s0\fR\|(3), +\&\fBprovider\-keymgmt\fR\|(7), +\&\s-1\fBEVP_KEYMGMT\s0\fR\|(3), +\&\fBOSSL_PROVIDER\-default\fR\|(7), +\&\s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2022 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_PKEY-DSA.7 b/secure/lib/libcrypto/man/man7/EVP_PKEY-DSA.7 new file mode 100644 index 000000000000..646834ae94dd --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_PKEY-DSA.7 @@ -0,0 +1,251 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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-DSA 7ossl" +.TH EVP_PKEY-DSA 7ossl "2023-09-19" "3.0.11" "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\-DSA, EVP_KEYMGMT\-DSA \- EVP_PKEY DSA keytype and algorithm support +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +For \fB\s-1DSA\s0\fR the \s-1FIPS186\-4\s0 standard specifies that the values used for \s-1FFC\s0 +parameter generation are also required for parameter validation. +This means that optional \s-1FFC\s0 domain parameter values for \fIseed\fR, \fIpcounter\fR +and \fIgindex\fR may need to be stored for validation purposes. For \fB\s-1DSA\s0\fR these +fields are not stored in the \s-1ASN1\s0 data so they need to be stored externally if +validation is required. +.SS "\s-1DSA\s0 parameters" +.IX Subsection "DSA parameters" +The \fB\s-1DSA\s0\fR key type supports the \s-1FFC\s0 parameters (see +\&\*(L"\s-1FFC\s0 parameters\*(R" in \s-1\fBEVP_PKEY\-FFC\s0\fR\|(7)). +.SS "\s-1DSA\s0 key generation parameters" +.IX Subsection "DSA key generation parameters" +The \fB\s-1DSA\s0\fR key type supports the \s-1FFC\s0 key generation parameters (see +\&\*(L"\s-1FFC\s0 key generation parameters\*(R" in \s-1\fBEVP_PKEY\-FFC\s0\fR\|(7) +.PP +The following restrictions apply to the \*(L"pbits\*(R" field: +.PP +For \*(L"fips186_4\*(R" this must be either 2048 or 3072. +For \*(L"fips186_2\*(R" this must be 1024. +For \*(L"group\*(R" this can be any one of 2048, 3072, 4096, 6144 or 8192. +.SS "\s-1DSA\s0 key validation" +.IX Subsection "DSA key validation" +For \s-1DSA\s0 keys, \fBEVP_PKEY_param_check\fR\|(3) behaves in the following way: +The OpenSSL \s-1FIPS\s0 provider conforms to the rules within the \s-1FIPS186\-4\s0 +standard for \s-1FFC\s0 parameter validation. For backwards compatibility the OpenSSL +default provider uses a much simpler check (see below) for parameter validation, +unless the seed parameter is set. +.PP +For \s-1DSA\s0 keys, \fBEVP_PKEY_param_check_quick\fR\|(3) behaves in the following way: +A simple check of L and N and partial g is performed. The default provider +also supports validation of legacy \*(L"fips186_2\*(R" keys. +.PP +For \s-1DSA\s0 keys, \fBEVP_PKEY_public_check\fR\|(3), \fBEVP_PKEY_private_check\fR\|(3) and +\&\fBEVP_PKEY_pairwise_check\fR\|(3) the OpenSSL default and \s-1FIPS\s0 providers conform to +the rules within SP800\-56Ar3 for public, private and pairwise tests respectively. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +An \fB\s-1EVP_PKEY\s0\fR context can be obtained by calling: +.PP +.Vb 1 +\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DSA", NULL); +.Ve +.PP +The \fB\s-1DSA\s0\fR domain parameters can be generated by calling: +.PP +.Vb 6 +\& unsigned int pbits = 2048; +\& unsigned int qbits = 256; +\& int gindex = 1; +\& OSSL_PARAM params[5]; +\& EVP_PKEY *param_key = NULL; +\& EVP_PKEY_CTX *pctx = NULL; +\& +\& pctx = EVP_PKEY_CTX_new_from_name(NULL, "DSA", NULL); +\& EVP_PKEY_paramgen_init(pctx); +\& +\& params[0] = OSSL_PARAM_construct_uint("pbits", &pbits); +\& params[1] = OSSL_PARAM_construct_uint("qbits", &qbits); +\& params[2] = OSSL_PARAM_construct_int("gindex", &gindex); +\& params[3] = OSSL_PARAM_construct_utf8_string("digest", "SHA384", 0); +\& params[4] = OSSL_PARAM_construct_end(); +\& EVP_PKEY_CTX_set_params(pctx, params); +\& +\& EVP_PKEY_generate(pctx, ¶m_key); +\& EVP_PKEY_CTX_free(pctx); +\& +\& EVP_PKEY_print_params(bio_out, param_key, 0, NULL); +.Ve +.PP +A \fB\s-1DSA\s0\fR key can be generated using domain parameters by calling: +.PP +.Vb 2 +\& EVP_PKEY *key = NULL; +\& EVP_PKEY_CTX *gctx = NULL; +\& +\& gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL); +\& EVP_PKEY_keygen_init(gctx); +\& EVP_PKEY_generate(gctx, &key); +\& EVP_PKEY_CTX_free(gctx); +\& EVP_PKEY_print_private(bio_out, key, 0, NULL); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +The following sections of \s-1FIPS186\-4:\s0 +.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" +\&\s-1\fBEVP_PKEY\-FFC\s0\fR\|(7), +\&\s-1\fBEVP_SIGNATURE\-DSA\s0\fR\|(7) +\&\s-1\fBEVP_PKEY\s0\fR\|(3), +\&\fBprovider\-keymgmt\fR\|(7), +\&\s-1\fBEVP_KEYMGMT\s0\fR\|(3), +\&\fBOSSL_PROVIDER\-default\fR\|(7), +\&\s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2022 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_PKEY-EC.7 b/secure/lib/libcrypto/man/man7/EVP_PKEY-EC.7 new file mode 100644 index 000000000000..a59429889b2a --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_PKEY-EC.7 @@ -0,0 +1,423 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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-EC 7ossl" +.TH EVP_PKEY-EC 7ossl "2023-09-19" "3.0.11" "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\-EC, +EVP_KEYMGMT\-EC +\&\- EVP_PKEY EC keytype and algorithm support +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\s-1EC\s0\fR keytype is implemented in OpenSSL's default provider. +.SS "Common \s-1EC\s0 parameters" +.IX Subsection "Common EC parameters" +The normal way of specifying domain parameters for an \s-1EC\s0 curve is via the +curve name \*(L"group\*(R". For curves with no curve name, explicit parameters can be +used that specify \*(L"field-type\*(R", \*(L"p\*(R", \*(L"a\*(R", \*(L"b\*(R", \*(L"generator\*(R" and \*(L"order\*(R". +Explicit parameters are supported for backwards compatibility reasons, but they +are not compliant with multiple standards (including \s-1RFC5915\s0) which only allow +named curves. +.PP +The following KeyGen/Gettable/Import/Export types are available for the +built-in \s-1EC\s0 algorithm: +.ie n .IP """group"" (\fB\s-1OSSL_PKEY_PARAM_GROUP_NAME\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``group'' (\fB\s-1OSSL_PKEY_PARAM_GROUP_NAME\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "group (OSSL_PKEY_PARAM_GROUP_NAME) <UTF8 string>" +The curve name. +.ie n .IP """field-type"" (\fB\s-1OSSL_PKEY_PARAM_EC_FIELD_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``field-type'' (\fB\s-1OSSL_PKEY_PARAM_EC_FIELD_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "field-type (OSSL_PKEY_PARAM_EC_FIELD_TYPE) <UTF8 string>" +The value should be either \*(L"prime-field\*(R" or \*(L"characteristic-two-field\*(R", +which correspond to prime field Fp and binary field F2^m. +.ie n .IP """p"" (\fB\s-1OSSL_PKEY_PARAM_EC_P\s0\fR) <unsigned integer>" 4 +.el .IP "``p'' (\fB\s-1OSSL_PKEY_PARAM_EC_P\s0\fR) <unsigned integer>" 4 +.IX Item "p (OSSL_PKEY_PARAM_EC_P) <unsigned integer>" +For a curve over Fp \fIp\fR is the prime for the field. For a curve over F2^m \fIp\fR +represents the irreducible polynomial \- each bit represents a term in the +polynomial. Therefore, there will either be three or five bits set dependent on +whether the polynomial is a trinomial or a pentanomial. +.ie n .IP """a"" (\fB\s-1OSSL_PKEY_PARAM_EC_A\s0\fR) <unsigned integer>" 4 +.el .IP "``a'' (\fB\s-1OSSL_PKEY_PARAM_EC_A\s0\fR) <unsigned integer>" 4 +.IX Item "a (OSSL_PKEY_PARAM_EC_A) <unsigned integer>" +.PD 0 +.ie n .IP """b"" (\fB\s-1OSSL_PKEY_PARAM_EC_B\s0\fR) <unsigned integer>" 4 +.el .IP "``b'' (\fB\s-1OSSL_PKEY_PARAM_EC_B\s0\fR) <unsigned integer>" 4 +.IX Item "b (OSSL_PKEY_PARAM_EC_B) <unsigned integer>" +.ie n .IP """seed"" (\fB\s-1OSSL_PKEY_PARAM_EC_SEED\s0\fR) <octet string>" 4 +.el .IP "``seed'' (\fB\s-1OSSL_PKEY_PARAM_EC_SEED\s0\fR) <octet string>" 4 +.IX Item "seed (OSSL_PKEY_PARAM_EC_SEED) <octet string>" +.PD +\&\fIa\fR and \fIb\fR represents the coefficients of the curve +For Fp: y^2 mod p = x^3 +ax + b mod p \s-1OR\s0 +For F2^m: y^2 + xy = x^3 + ax^2 + b +.Sp +\&\fIseed\fR is an optional value that is for information purposes only. +It represents the random number seed used to generate the coefficient \fIb\fR from a +random number. +.ie n .IP """generator"" (\fB\s-1OSSL_PKEY_PARAM_EC_GENERATOR\s0\fR) <octet string>" 4 +.el .IP "``generator'' (\fB\s-1OSSL_PKEY_PARAM_EC_GENERATOR\s0\fR) <octet string>" 4 +.IX Item "generator (OSSL_PKEY_PARAM_EC_GENERATOR) <octet string>" +.PD 0 +.ie n .IP """order"" (\fB\s-1OSSL_PKEY_PARAM_EC_ORDER\s0\fR) <unsigned integer>" 4 +.el .IP "``order'' (\fB\s-1OSSL_PKEY_PARAM_EC_ORDER\s0\fR) <unsigned integer>" 4 +.IX Item "order (OSSL_PKEY_PARAM_EC_ORDER) <unsigned integer>" +.ie n .IP """cofactor"" (\fB\s-1OSSL_PKEY_PARAM_EC_COFACTOR\s0\fR) <unsigned integer>" 4 +.el .IP "``cofactor'' (\fB\s-1OSSL_PKEY_PARAM_EC_COFACTOR\s0\fR) <unsigned integer>" 4 +.IX Item "cofactor (OSSL_PKEY_PARAM_EC_COFACTOR) <unsigned integer>" +.PD +The \fIgenerator\fR is a well defined point on the curve chosen for cryptographic +operations. The encoding conforms with Sec. 2.3.3 of the \s-1SECG SEC 1\s0 (\*(L"Elliptic Curve +Cryptography\*(R") standard. See \fBEC_POINT_oct2point()\fR. +Integers used for point multiplications will be between 0 and +\&\fIorder\fR \- 1. +\&\fIcofactor\fR is an optional value. +\&\fIorder\fR multiplied by the \fIcofactor\fR gives the number of points on the curve. +.ie n .IP """decoded-from-explicit"" (\fB\s-1OSSL_PKEY_PARAM_EC_DECODED_FROM_EXPLICIT_PARAMS\s0\fR) <integer>" 4 +.el .IP "``decoded-from-explicit'' (\fB\s-1OSSL_PKEY_PARAM_EC_DECODED_FROM_EXPLICIT_PARAMS\s0\fR) <integer>" 4 +.IX Item "decoded-from-explicit (OSSL_PKEY_PARAM_EC_DECODED_FROM_EXPLICIT_PARAMS) <integer>" +Gets a flag indicating whether the key or parameters were decoded from explicit +curve parameters. Set to 1 if so or 0 if a named curve was used. +.ie n .IP """use-cofactor-flag"" (\fB\s-1OSSL_PKEY_PARAM_USE_COFACTOR_ECDH\s0\fR) <integer>" 4 +.el .IP "``use-cofactor-flag'' (\fB\s-1OSSL_PKEY_PARAM_USE_COFACTOR_ECDH\s0\fR) <integer>" 4 +.IX Item "use-cofactor-flag (OSSL_PKEY_PARAM_USE_COFACTOR_ECDH) <integer>" +Enable Cofactor \s-1DH\s0 (\s-1ECC CDH\s0) if this value is 1, otherwise it uses normal \s-1EC DH\s0 +if the value is zero. The cofactor variant multiplies the shared secret by the +\&\s-1EC\s0 curve's cofactor (note for some curves the cofactor is 1). +.Sp +See also \s-1\fBEVP_KEYEXCH\-ECDH\s0\fR\|(7) for the related +\&\fB\s-1OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE\s0\fR parameter that can be set on a +per-operation basis. +.ie n .IP """encoding"" (\fB\s-1OSSL_PKEY_PARAM_EC_ENCODING\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``encoding'' (\fB\s-1OSSL_PKEY_PARAM_EC_ENCODING\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "encoding (OSSL_PKEY_PARAM_EC_ENCODING) <UTF8 string>" +Set the format used for serializing the \s-1EC\s0 group parameters. +Valid values are \*(L"explicit\*(R" or \*(L"named_curve\*(R". The default value is \*(L"named_curve\*(R". +.ie n .IP """point-format"" (\fB\s-1OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``point-format'' (\fB\s-1OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "point-format (OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT) <UTF8 string>" +Sets or gets the point_conversion_form for the \fIkey\fR. For a description of +point_conversion_forms please see \fBEC_POINT_new\fR\|(3). Valid values are +\&\*(L"uncompressed\*(R" or \*(L"compressed\*(R". The default value is \*(L"uncompressed\*(R". +.ie n .IP """group-check"" (\fB\s-1OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``group-check'' (\fB\s-1OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "group-check (OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE) <UTF8 string>" +Sets or Gets the type of group check done when \fBEVP_PKEY_param_check()\fR is called. +Valid values are \*(L"default\*(R", \*(L"named\*(R" and \*(L"named-nist\*(R". +The \*(L"named\*(R" type checks that the domain parameters match the inbuilt curve parameters, +\&\*(L"named-nist\*(R" is similar but also checks that the named curve is a nist curve. +The \*(L"default\*(R" type does domain parameter validation for the OpenSSL default provider, +but is equivalent to \*(L"named-nist\*(R" for the OpenSSL \s-1FIPS\s0 provider. +.ie n .IP """include-public"" (\fB\s-1OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC\s0\fR) <integer>" 4 +.el .IP "``include-public'' (\fB\s-1OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC\s0\fR) <integer>" 4 +.IX Item "include-public (OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC) <integer>" +Setting this value to 0 indicates that the public key should not be included when +encoding the private key. The default value of 1 will include the public key. +.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 public key value in encoded \s-1EC\s0 point format conforming to Sec. 2.3.3 and +2.3.4 of the \s-1SECG SEC 1\s0 (\*(L"Elliptic Curve Cryptography\*(R") standard. +This parameter is used when importing or exporting the public key value with the +\&\fBEVP_PKEY_fromdata()\fR and \fBEVP_PKEY_todata()\fR functions. +.Sp +Note, in particular, that the choice of point compression format used for +encoding the exported value via \fBEVP_PKEY_todata()\fR depends on the underlying +provider implementation. +Before OpenSSL 3.0.8, the implementation of providers included with OpenSSL always +opted for an encoding in compressed format, unconditionally. +Since OpenSSL 3.0.8, the implementation has been changed to honor the +\&\fB\s-1OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT\s0\fR parameter, if set, or to default +to uncompressed format. +.ie n .IP """priv"" (\fB\s-1OSSL_PKEY_PARAM_PRIV_KEY\s0\fR) <unsigned integer>" 4 +.el .IP "``priv'' (\fB\s-1OSSL_PKEY_PARAM_PRIV_KEY\s0\fR) <unsigned integer>" 4 +.IX Item "priv (OSSL_PKEY_PARAM_PRIV_KEY) <unsigned integer>" +The private key value. +.ie n .IP """encoded-pub-key"" (\fB\s-1OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY\s0\fR) <octet string>" 4 +.el .IP "``encoded-pub-key'' (\fB\s-1OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY\s0\fR) <octet string>" 4 +.IX Item "encoded-pub-key (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) <octet string>" +Used for getting and setting the encoding of an \s-1EC\s0 public key. The public key +is expected to be a point conforming to Sec. 2.3.4 of the \s-1SECG SEC 1\s0 (\*(L"Elliptic +Curve Cryptography\*(R") standard. +.ie n .IP """qx"" (\fB\s-1OSSL_PKEY_PARAM_EC_PUB_X\s0\fR) <unsigned integer>" 4 +.el .IP "``qx'' (\fB\s-1OSSL_PKEY_PARAM_EC_PUB_X\s0\fR) <unsigned integer>" 4 +.IX Item "qx (OSSL_PKEY_PARAM_EC_PUB_X) <unsigned integer>" +Used for getting the \s-1EC\s0 public key X component. +.ie n .IP """qy"" (\fB\s-1OSSL_PKEY_PARAM_EC_PUB_Y\s0\fR) <unsigned integer>" 4 +.el .IP "``qy'' (\fB\s-1OSSL_PKEY_PARAM_EC_PUB_Y\s0\fR) <unsigned integer>" 4 +.IX Item "qy (OSSL_PKEY_PARAM_EC_PUB_Y) <unsigned integer>" +Used for getting the \s-1EC\s0 public key Y component. +.ie n .IP """default-digest"" (\fB\s-1OSSL_PKEY_PARAM_DEFAULT_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``default-digest'' (\fB\s-1OSSL_PKEY_PARAM_DEFAULT_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "default-digest (OSSL_PKEY_PARAM_DEFAULT_DIGEST) <UTF8 string>" +Getter that returns the default digest name. +(Currently returns \*(L"\s-1SHA256\*(R"\s0 as of OpenSSL 3.0). +.PP +The following Gettable types are also available for the built-in \s-1EC\s0 algorithm: +.ie n .IP """basis-type"" (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``basis-type'' (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "basis-type (OSSL_PKEY_PARAM_EC_CHAR2_TYPE) <UTF8 string>" +Supports the values \*(L"tpBasis\*(R" for a trinomial or \*(L"ppBasis\*(R" for a pentanomial. +This field is only used for a binary field F2^m. +.ie n .IP """m"" (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_M\s0\fR) <integer>" 4 +.el .IP "``m'' (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_M\s0\fR) <integer>" 4 +.IX Item "m (OSSL_PKEY_PARAM_EC_CHAR2_M) <integer>" +.PD 0 +.ie n .IP """tp"" (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS\s0\fR) <integer>" 4 +.el .IP "``tp'' (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS\s0\fR) <integer>" 4 +.IX Item "tp (OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS) <integer>" +.ie n .IP """k1"" (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_PP_K1\s0\fR) <integer>" 4 +.el .IP "``k1'' (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_PP_K1\s0\fR) <integer>" 4 +.IX Item "k1 (OSSL_PKEY_PARAM_EC_CHAR2_PP_K1) <integer>" +.ie n .IP """k2"" (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_PP_K2\s0\fR) <integer>" 4 +.el .IP "``k2'' (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_PP_K2\s0\fR) <integer>" 4 +.IX Item "k2 (OSSL_PKEY_PARAM_EC_CHAR2_PP_K2) <integer>" +.ie n .IP """k3"" (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_PP_K3\s0\fR) <integer>" 4 +.el .IP "``k3'' (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_PP_K3\s0\fR) <integer>" 4 +.IX Item "k3 (OSSL_PKEY_PARAM_EC_CHAR2_PP_K3) <integer>" +.PD +These fields are only used for a binary field F2^m. +\&\fIm\fR is the degree of the binary field. +.Sp +\&\fItp\fR is the middle bit of a trinomial so its value must be in the +range m > tp > 0. +.Sp +\&\fIk1\fR, \fIk2\fR and \fIk3\fR are used to get the middle bits of a pentanomial such +that m > k3 > k2 > k1 > 0 +.SS "\s-1EC\s0 key validation" +.IX Subsection "EC key validation" +For \s-1EC\s0 keys, \fBEVP_PKEY_param_check\fR\|(3) behaves in the following way: +For the OpenSSL default provider it uses either +\&\fBEC_GROUP_check\fR\|(3) or \fBEC_GROUP_check_named_curve\fR\|(3) depending on the flag +\&\s-1EC_FLAG_CHECK_NAMED_GROUP.\s0 +The OpenSSL \s-1FIPS\s0 provider uses \fBEC_GROUP_check_named_curve\fR\|(3) in order to +conform to SP800\-56Ar3 \fIAssurances of Domain-Parameter Validity\fR. +.PP +For \s-1EC\s0 keys, \fBEVP_PKEY_param_check_quick\fR\|(3) is equivalent to +\&\fBEVP_PKEY_param_check\fR\|(3). +.PP +For \s-1EC\s0 keys, \fBEVP_PKEY_public_check\fR\|(3) and \fBEVP_PKEY_public_check_quick\fR\|(3) +conform to SP800\-56Ar3 \fI\s-1ECC\s0 Full Public-Key Validation\fR and +\&\fI\s-1ECC\s0 Partial Public-Key Validation\fR respectively. +.PP +For \s-1EC\s0 Keys, \fBEVP_PKEY_private_check\fR\|(3) and \fBEVP_PKEY_pairwise_check\fR\|(3) +conform to SP800\-56Ar3 \fIPrivate key validity\fR and +\&\fIOwner Assurance of Pair-wise Consistency\fR respectively. +.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, "EC", NULL); +.Ve +.PP +An \fB\s-1EVP_PKEY\s0\fR \s-1ECDSA\s0 or \s-1ECDH\s0 key can be generated with a \*(L"P\-256\*(R" named group by +calling: +.PP +.Vb 1 +\& pkey = EVP_EC_gen("P\-256"); +.Ve +.PP +or like this: +.PP +.Vb 4 +\& EVP_PKEY *key = NULL; +\& OSSL_PARAM params[2]; +\& EVP_PKEY_CTX *gctx = +\& EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL); +\& +\& EVP_PKEY_keygen_init(gctx); +\& +\& params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME, +\& "P\-256", 0); +\& params[1] = OSSL_PARAM_construct_end(); +\& EVP_PKEY_CTX_set_params(gctx, params); +\& +\& EVP_PKEY_generate(gctx, &key); +\& +\& EVP_PKEY_print_private(bio_out, key, 0, NULL); +\& ... +\& EVP_PKEY_free(key); +\& EVP_PKEY_CTX_free(gctx); +.Ve +.PP +An \fB\s-1EVP_PKEY\s0\fR \s-1EC CDH\s0 (Cofactor Diffie-Hellman) key can be generated with a +\&\*(L"K\-571\*(R" named group by calling: +.PP +.Vb 5 +\& int use_cdh = 1; +\& EVP_PKEY *key = NULL; +\& OSSL_PARAM params[3]; +\& EVP_PKEY_CTX *gctx = +\& EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL); +\& +\& EVP_PKEY_keygen_init(gctx); +\& +\& params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME, +\& "K\-571", 0); +\& /* +\& * This curve has a cofactor that is not 1 \- so setting CDH mode changes +\& * the behaviour. For many curves the cofactor is 1 \- so setting this has +\& * no effect. +\& */ +\& params[1] = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_USE_COFACTOR_ECDH, +\& &use_cdh); +\& params[2] = OSSL_PARAM_construct_end(); +\& EVP_PKEY_CTX_set_params(gctx, params); +\& +\& EVP_PKEY_generate(gctx, &key); +\& EVP_PKEY_print_private(bio_out, key, 0, NULL); +\& ... +\& EVP_PKEY_free(key); +\& EVP_PKEY_CTX_free(gctx); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_EC_gen\fR\|(3), +\&\s-1\fBEVP_KEYMGMT\s0\fR\|(3), +\&\s-1\fBEVP_PKEY\s0\fR\|(3), +\&\fBprovider\-keymgmt\fR\|(7), +\&\s-1\fBEVP_SIGNATURE\-ECDSA\s0\fR\|(7), +\&\s-1\fBEVP_KEYEXCH\-ECDH\s0\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2023 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_PKEY-FFC.7 b/secure/lib/libcrypto/man/man7/EVP_PKEY-FFC.7 new file mode 100644 index 000000000000..aa77863f4184 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_PKEY-FFC.7 @@ -0,0 +1,344 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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-FFC 7ossl" +.TH EVP_PKEY-FFC 7ossl "2023-09-19" "3.0.11" "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 (\s-1FFC\s0) is a method of implementing discrete logarithm +cryptography using finite field mathematics. \s-1DSA\s0 is an example of \s-1FFC\s0 and +Diffie-Hellman key establishment algorithms specified in \s-1SP800\-56A\s0 can also be +implemented as \s-1FFC.\s0 +.PP +The \fB\s-1DSA\s0\fR, \fB\s-1DH\s0\fR and \fB\s-1DHX\s0\fR keytypes are implemented in OpenSSL's default and +\&\s-1FIPS\s0 providers. +The implementations support the basic \s-1DSA, DH\s0 and \s-1DHX\s0 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 \fB\s-1DSA\s0\fR (and \fB\s-1DH\s0\fR that is not a named group) the \s-1FIPS186\-4\s0 standard +specifies that the values used for \s-1FFC\s0 parameter generation are also required +for parameter validation. +This means that optional \s-1FFC\s0 domain parameter values for \fIseed\fR, \fIpcounter\fR +and \fIgindex\fR may need to be stored for validation purposes. +For \fB\s-1DH\s0\fR the \fIseed\fR and \fIpcounter\fR can be stored in \s-1ASN1\s0 data +(but the \fIgindex\fR is not). For \fB\s-1DSA\s0\fR however, these fields are not stored in +the \s-1ASN1\s0 data so they need to be stored externally if validation is required. +.PP +The \fB\s-1DH\s0\fR key type uses PKCS#3 format which saves p and g, but not the 'q' value. +The \fB\s-1DHX\s0\fR key type uses X9.42 format which saves the value of 'q' and this +must be used for \s-1FIPS186\-4.\s0 +.SS "\s-1FFC\s0 parameters" +.IX Subsection "FFC parameters" +In addition to the common parameters that all keytypes should support (see +\&\*(L"Common parameters\*(R" in \fBprovider\-keymgmt\fR\|(7)), the \fB\s-1DSA\s0\fR, \fB\s-1DH\s0\fR and \fB\s-1DHX\s0\fR keytype +implementations support the following. +.ie n .IP """pub"" (\fB\s-1OSSL_PKEY_PARAM_PUB_KEY\s0\fR) <unsigned integer>" 4 +.el .IP "``pub'' (\fB\s-1OSSL_PKEY_PARAM_PUB_KEY\s0\fR) <unsigned integer>" 4 +.IX Item "pub (OSSL_PKEY_PARAM_PUB_KEY) <unsigned integer>" +The public key value. +.ie n .IP """priv"" (\fB\s-1OSSL_PKEY_PARAM_PRIV_KEY\s0\fR) <unsigned integer>" 4 +.el .IP "``priv'' (\fB\s-1OSSL_PKEY_PARAM_PRIV_KEY\s0\fR) <unsigned integer>" 4 +.IX Item "priv (OSSL_PKEY_PARAM_PRIV_KEY) <unsigned integer>" +The private key value. +.SS "\s-1FFC DSA, DH\s0 and \s-1DHX\s0 domain parameters" +.IX Subsection "FFC DSA, DH and DHX domain parameters" +.ie n .IP """p"" (\fB\s-1OSSL_PKEY_PARAM_FFC_P\s0\fR) <unsigned integer>" 4 +.el .IP "``p'' (\fB\s-1OSSL_PKEY_PARAM_FFC_P\s0\fR) <unsigned integer>" 4 +.IX Item "p (OSSL_PKEY_PARAM_FFC_P) <unsigned integer>" +A \s-1DSA\s0 or Diffie-Hellman prime \*(L"p\*(R" value. +.ie n .IP """g"" (\fB\s-1OSSL_PKEY_PARAM_FFC_G\s0\fR) <unsigned integer>" 4 +.el .IP "``g'' (\fB\s-1OSSL_PKEY_PARAM_FFC_G\s0\fR) <unsigned integer>" 4 +.IX Item "g (OSSL_PKEY_PARAM_FFC_G) <unsigned integer>" +A \s-1DSA\s0 or Diffie-Hellman generator \*(L"g\*(R" value. +.SS "\s-1FFC DSA\s0 and \s-1DHX\s0 domain parameters" +.IX Subsection "FFC DSA and DHX domain parameters" +.ie n .IP """q"" (\fB\s-1OSSL_PKEY_PARAM_FFC_Q\s0\fR) <unsigned integer>" 4 +.el .IP "``q'' (\fB\s-1OSSL_PKEY_PARAM_FFC_Q\s0\fR) <unsigned integer>" 4 +.IX Item "q (OSSL_PKEY_PARAM_FFC_Q) <unsigned integer>" +A \s-1DSA\s0 or Diffie-Hellman prime \*(L"q\*(R" value. +.ie n .IP """seed"" (\fB\s-1OSSL_PKEY_PARAM_FFC_SEED\s0\fR) <octet string>" 4 +.el .IP "``seed'' (\fB\s-1OSSL_PKEY_PARAM_FFC_SEED\s0\fR) <octet string>" 4 +.IX Item "seed (OSSL_PKEY_PARAM_FFC_SEED) <octet string>" +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. +.ie n .IP """gindex"" (\fB\s-1OSSL_PKEY_PARAM_FFC_GINDEX\s0\fR) <integer>" 4 +.el .IP "``gindex'' (\fB\s-1OSSL_PKEY_PARAM_FFC_GINDEX\s0\fR) <integer>" 4 +.IX Item "gindex (OSSL_PKEY_PARAM_FFC_GINDEX) <integer>" +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. +.ie n .IP """pcounter"" (\fB\s-1OSSL_PKEY_PARAM_FFC_PCOUNTER\s0\fR) <integer>" 4 +.el .IP "``pcounter'' (\fB\s-1OSSL_PKEY_PARAM_FFC_PCOUNTER\s0\fR) <integer>" 4 +.IX Item "pcounter (OSSL_PKEY_PARAM_FFC_PCOUNTER) <integer>" +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. +.ie n .IP """hindex"" (\fB\s-1OSSL_PKEY_PARAM_FFC_H\s0\fR) <integer>" 4 +.el .IP "``hindex'' (\fB\s-1OSSL_PKEY_PARAM_FFC_H\s0\fR) <integer>" 4 +.IX Item "hindex (OSSL_PKEY_PARAM_FFC_H) <integer>" +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 \*(L"j\*(R" is the cofactor). +.ie n .IP """j"" (\fB\s-1OSSL_PKEY_PARAM_FFC_COFACTOR\s0\fR) <unsigned integer>" 4 +.el .IP "``j'' (\fB\s-1OSSL_PKEY_PARAM_FFC_COFACTOR\s0\fR) <unsigned integer>" 4 +.IX Item "j (OSSL_PKEY_PARAM_FFC_COFACTOR) <unsigned integer>" +An optional informational cofactor parameter that should equal to (p \- 1) / q. +.ie n .IP """validate-pq"" (\fB\s-1OSSL_PKEY_PARAM_FFC_VALIDATE_PQ\s0\fR) <unsigned integer>" 4 +.el .IP "``validate-pq'' (\fB\s-1OSSL_PKEY_PARAM_FFC_VALIDATE_PQ\s0\fR) <unsigned integer>" 4 +.IX Item "validate-pq (OSSL_PKEY_PARAM_FFC_VALIDATE_PQ) <unsigned integer>" +.PD 0 +.ie n .IP """validate-g"" (\fB\s-1OSSL_PKEY_PARAM_FFC_VALIDATE_G\s0\fR) <unsigned integer>" 4 +.el .IP "``validate-g'' (\fB\s-1OSSL_PKEY_PARAM_FFC_VALIDATE_G\s0\fR) <unsigned integer>" 4 +.IX Item "validate-g (OSSL_PKEY_PARAM_FFC_VALIDATE_G) <unsigned integer>" +.PD +These boolean values are used during \s-1FIPS186\-4\s0 or \s-1FIPS186\-2\s0 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. +.ie n .IP """validate-legacy"" (\fB\s-1OSSL_PKEY_PARAM_FFC_VALIDATE_LEGACY\s0\fR) <unsigned integer>" 4 +.el .IP "``validate-legacy'' (\fB\s-1OSSL_PKEY_PARAM_FFC_VALIDATE_LEGACY\s0\fR) <unsigned integer>" 4 +.IX Item "validate-legacy (OSSL_PKEY_PARAM_FFC_VALIDATE_LEGACY) <unsigned integer>" +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 \s-1FIPS186\-4\s0 validation. Setting this value to 1 selects +\&\s-1FIPS186\-2\s0 validation. +.SS "\s-1FFC\s0 key generation parameters" +.IX Subsection "FFC key generation parameters" +The following key generation types are available for \s-1DSA\s0 and \s-1DHX\s0 algorithms: +.ie n .IP """type"" (\fB\s-1OSSL_PKEY_PARAM_FFC_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``type'' (\fB\s-1OSSL_PKEY_PARAM_FFC_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "type (OSSL_PKEY_PARAM_FFC_TYPE) <UTF8 string>" +Sets the type of parameter generation. The shared valid values are: +.RS 4 +.ie n .IP """fips186_4""" 4 +.el .IP "``fips186_4''" 4 +.IX Item "fips186_4" +The current standard. +.ie n .IP """fips186_2""" 4 +.el .IP "``fips186_2''" 4 +.IX Item "fips186_2" +The old standard that should only be used for legacy purposes. +.ie n .IP """default""" 4 +.el .IP "``default''" 4 +.IX Item "default" +This can choose one of \*(L"fips186_4\*(R" or \*(L"fips186_2\*(R" depending on other +parameters set for parameter generation. +.RE +.RS 4 +.RE +.ie n .IP """pbits"" (\fB\s-1OSSL_PKEY_PARAM_FFC_PBITS\s0\fR) <unsigned integer>" 4 +.el .IP "``pbits'' (\fB\s-1OSSL_PKEY_PARAM_FFC_PBITS\s0\fR) <unsigned integer>" 4 +.IX Item "pbits (OSSL_PKEY_PARAM_FFC_PBITS) <unsigned integer>" +Sets the size (in bits) of the prime 'p'. +.ie n .IP """qbits"" (\fB\s-1OSSL_PKEY_PARAM_FFC_QBITS\s0\fR) <unsigned integer>" 4 +.el .IP "``qbits'' (\fB\s-1OSSL_PKEY_PARAM_FFC_QBITS\s0\fR) <unsigned integer>" 4 +.IX Item "qbits (OSSL_PKEY_PARAM_FFC_QBITS) <unsigned integer>" +Sets the size (in bits) of the prime 'q'. +.Sp +For \*(L"fips186_4\*(R" this can be either 224 or 256. +For \*(L"fips186_2\*(R" this has a size of 160. +.ie n .IP """digest"" (\fB\s-1OSSL_PKEY_PARAM_FFC_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_PKEY_PARAM_FFC_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_PKEY_PARAM_FFC_DIGEST) <UTF8 string>" +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. +.ie n .IP """properties"" (\fB\s-1OSSL_PKEY_PARAM_FFC_DIGEST_PROPS\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_PKEY_PARAM_FFC_DIGEST_PROPS\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_PKEY_PARAM_FFC_DIGEST_PROPS) <UTF8 string>" +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. +.ie n .IP """seed"" (\fB\s-1OSSL_PKEY_PARAM_FFC_SEED\s0\fR) <octet string>" 4 +.el .IP "``seed'' (\fB\s-1OSSL_PKEY_PARAM_FFC_SEED\s0\fR) <octet string>" 4 +.IX Item "seed (OSSL_PKEY_PARAM_FFC_SEED) <octet string>" +For \*(L"fips186_4\*(R" or \*(L"fips186_2\*(R" 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 \s-1OR\s0 it will fail if the seed did not generate valid primes. +.ie n .IP """gindex"" (\fB\s-1OSSL_PKEY_PARAM_FFC_GINDEX\s0\fR) <integer>" 4 +.el .IP "``gindex'' (\fB\s-1OSSL_PKEY_PARAM_FFC_GINDEX\s0\fR) <integer>" 4 +.IX Item "gindex (OSSL_PKEY_PARAM_FFC_GINDEX) <integer>" +.PD 0 +.ie n .IP """pcounter"" (\fB\s-1OSSL_PKEY_PARAM_FFC_PCOUNTER\s0\fR) <integer>" 4 +.el .IP "``pcounter'' (\fB\s-1OSSL_PKEY_PARAM_FFC_PCOUNTER\s0\fR) <integer>" 4 +.IX Item "pcounter (OSSL_PKEY_PARAM_FFC_PCOUNTER) <integer>" +.ie n .IP """hindex"" (\fB\s-1OSSL_PKEY_PARAM_FFC_H\s0\fR) <integer>" 4 +.el .IP "``hindex'' (\fB\s-1OSSL_PKEY_PARAM_FFC_H\s0\fR) <integer>" 4 +.IX Item "hindex (OSSL_PKEY_PARAM_FFC_H) <integer>" +.PD +These types are described above. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +The following sections of SP800\-56Ar3: +.IP "5.5.1.1 \s-1FFC\s0 Domain Parameter Selection/Generation" 4 +.IX Item "5.5.1.1 FFC Domain Parameter Selection/Generation" +.PP +The following sections of \s-1FIPS186\-4:\s0 +.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" +\&\s-1\fBEVP_PKEY\-DSA\s0\fR\|(7), +\&\s-1\fBEVP_PKEY\-DH\s0\fR\|(7), +\&\s-1\fBEVP_SIGNATURE\-DSA\s0\fR\|(7), +\&\s-1\fBEVP_KEYEXCH\-DH\s0\fR\|(7) +\&\s-1\fBEVP_KEYMGMT\s0\fR\|(3), +\&\s-1\fBEVP_PKEY\s0\fR\|(3), +\&\fBprovider\-keymgmt\fR\|(7), +\&\fBOSSL_PROVIDER\-default\fR\|(7), +\&\s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7), +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2022 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_PKEY-HMAC.7 b/secure/lib/libcrypto/man/man7/EVP_PKEY-HMAC.7 new file mode 100644 index 000000000000..9f93ee1566e0 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_PKEY-HMAC.7 @@ -0,0 +1,205 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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-HMAC 7ossl" +.TH EVP_PKEY-HMAC 7ossl "2023-09-19" "3.0.11" "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\-HMAC, EVP_KEYMGMT\-HMAC, EVP_PKEY\-Siphash, EVP_KEYMGMT\-Siphash, +EVP_PKEY\-Poly1305, EVP_KEYMGMT\-Poly1305, EVP_PKEY\-CMAC, EVP_KEYMGMT\-CMAC +\&\- EVP_PKEY legacy MAC keytypes and algorithm support +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\s-1HMAC\s0\fR and \fB\s-1CMAC\s0\fR key types are implemented in OpenSSL's default and \s-1FIPS\s0 +providers. Additionally the \fBSiphash\fR and \fBPoly1305\fR key types are implemented +in the default provider. Performing \s-1MAC\s0 operations via an \s-1EVP_PKEY\s0 +is considered legacy and are only available for backwards compatibility purposes +and for a restricted set of algorithms. The preferred way of performing \s-1MAC\s0 +operations is via the \s-1EVP_MAC\s0 APIs. See \fBEVP_MAC_init\fR\|(3). +.PP +For further details on using \s-1EVP_PKEY\s0 based \s-1MAC\s0 keys see +\&\s-1\fBEVP_SIGNATURE\-HMAC\s0\fR\|(7), \fBEVP_SIGNATURE\-Siphash\fR\|(7), +\&\fBEVP_SIGNATURE\-Poly1305\fR\|(7) or \s-1\fBEVP_SIGNATURE\-CMAC\s0\fR\|(7). +.SS "Common \s-1MAC\s0 parameters" +.IX Subsection "Common MAC parameters" +All the \fB\s-1MAC\s0\fR keytypes support the following parameters. +.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 \s-1MAC\s0 key value. +.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>" +A property query string to be used when any algorithms are fetched. +.SS "\s-1CMAC\s0 parameters" +.IX Subsection "CMAC parameters" +As well as the parameters described above, the \fB\s-1CMAC\s0\fR keytype additionally +supports the following parameters. +.ie n .IP """cipher"" (\fB\s-1OSSL_PKEY_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``cipher'' (\fB\s-1OSSL_PKEY_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "cipher (OSSL_PKEY_PARAM_CIPHER) <UTF8 string>" +The name of a cipher to be used when generating the \s-1MAC.\s0 +.ie n .IP """engine"" (\fB\s-1OSSL_PKEY_PARAM_ENGINE\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``engine'' (\fB\s-1OSSL_PKEY_PARAM_ENGINE\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "engine (OSSL_PKEY_PARAM_ENGINE) <UTF8 string>" +The name of an engine to be used for the specified cipher (if any). +.SS "Common \s-1MAC\s0 key generation parameters" +.IX Subsection "Common MAC key generation parameters" +\&\s-1MAC\s0 key generation is unusual in that no new key is actually generated. Instead +a new provider side key object is created with the supplied raw key value. This +is done for backwards compatibility with previous versions of OpenSSL. +.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 \s-1MAC\s0 key value. +.SS "\s-1CMAC\s0 key generation parameters" +.IX Subsection "CMAC key generation parameters" +In addition to the common \s-1MAC\s0 key generation parameters, the \s-1CMAC\s0 key generation +additionally recognises the following. +.ie n .IP """cipher"" (\fB\s-1OSSL_PKEY_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``cipher'' (\fB\s-1OSSL_PKEY_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "cipher (OSSL_PKEY_PARAM_CIPHER) <UTF8 string>" +The name of a cipher to be used when generating the \s-1MAC.\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_KEYMGMT\s0\fR\|(3), \s-1\fBEVP_PKEY\s0\fR\|(3), \fBprovider\-keymgmt\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_PKEY-RSA.7 b/secure/lib/libcrypto/man/man7/EVP_PKEY-RSA.7 new file mode 100644 index 000000000000..6923fbfcc06f --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_PKEY-RSA.7 @@ -0,0 +1,427 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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-RSA 7ossl" +.TH EVP_PKEY-RSA 7ossl "2023-09-19" "3.0.11" "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\-RSA, EVP_KEYMGMT\-RSA, RSA +\&\- EVP_PKEY RSA keytype and algorithm support +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\s-1RSA\s0\fR keytype is implemented in OpenSSL's default and \s-1FIPS\s0 providers. +That implementation supports the basic \s-1RSA\s0 keys, containing the modulus \fIn\fR, +the public exponent \fIe\fR, the private exponent \fId\fR, and a collection of prime +factors, exponents and coefficient for \s-1CRT\s0 calculations, of which the first +few are known as \fIp\fR and \fIq\fR, \fIdP\fR and \fIdQ\fR, and \fIqInv\fR. +.SS "Common \s-1RSA\s0 parameters" +.IX Subsection "Common RSA parameters" +In addition to the common parameters that all keytypes should support (see +\&\*(L"Common parameters\*(R" in \fBprovider\-keymgmt\fR\|(7)), the \fB\s-1RSA\s0\fR keytype implementation +supports the following. +.ie n .IP """n"" (\fB\s-1OSSL_PKEY_PARAM_RSA_N\s0\fR) <unsigned integer>" 4 +.el .IP "``n'' (\fB\s-1OSSL_PKEY_PARAM_RSA_N\s0\fR) <unsigned integer>" 4 +.IX Item "n (OSSL_PKEY_PARAM_RSA_N) <unsigned integer>" +The \s-1RSA\s0 modulus \*(L"n\*(R" value. +.ie n .IP """e"" (\fB\s-1OSSL_PKEY_PARAM_RSA_E\s0\fR) <unsigned integer>" 4 +.el .IP "``e'' (\fB\s-1OSSL_PKEY_PARAM_RSA_E\s0\fR) <unsigned integer>" 4 +.IX Item "e (OSSL_PKEY_PARAM_RSA_E) <unsigned integer>" +The \s-1RSA\s0 public exponent \*(L"e\*(R" value. +This value must always be set when creating a raw key using \fBEVP_PKEY_fromdata\fR\|(3). +Note that when a decryption operation is performed, that this value is used for +blinding purposes to prevent timing attacks. +.ie n .IP """d"" (\fB\s-1OSSL_PKEY_PARAM_RSA_D\s0\fR) <unsigned integer>" 4 +.el .IP "``d'' (\fB\s-1OSSL_PKEY_PARAM_RSA_D\s0\fR) <unsigned integer>" 4 +.IX Item "d (OSSL_PKEY_PARAM_RSA_D) <unsigned integer>" +The \s-1RSA\s0 private exponent \*(L"d\*(R" value. +.ie n .IP """rsa\-factor1"" (\fB\s-1OSSL_PKEY_PARAM_RSA_FACTOR1\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-factor1'' (\fB\s-1OSSL_PKEY_PARAM_RSA_FACTOR1\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-factor1 (OSSL_PKEY_PARAM_RSA_FACTOR1) <unsigned integer>" +.PD 0 +.ie n .IP """rsa\-factor2"" (\fB\s-1OSSL_PKEY_PARAM_RSA_FACTOR2\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-factor2'' (\fB\s-1OSSL_PKEY_PARAM_RSA_FACTOR2\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-factor2 (OSSL_PKEY_PARAM_RSA_FACTOR2) <unsigned integer>" +.ie n .IP """rsa\-factor3"" (\fB\s-1OSSL_PKEY_PARAM_RSA_FACTOR3\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-factor3'' (\fB\s-1OSSL_PKEY_PARAM_RSA_FACTOR3\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-factor3 (OSSL_PKEY_PARAM_RSA_FACTOR3) <unsigned integer>" +.ie n .IP """rsa\-factor4"" (\fB\s-1OSSL_PKEY_PARAM_RSA_FACTOR4\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-factor4'' (\fB\s-1OSSL_PKEY_PARAM_RSA_FACTOR4\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-factor4 (OSSL_PKEY_PARAM_RSA_FACTOR4) <unsigned integer>" +.ie n .IP """rsa\-factor5"" (\fB\s-1OSSL_PKEY_PARAM_RSA_FACTOR5\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-factor5'' (\fB\s-1OSSL_PKEY_PARAM_RSA_FACTOR5\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-factor5 (OSSL_PKEY_PARAM_RSA_FACTOR5) <unsigned integer>" +.ie n .IP """rsa\-factor6"" (\fB\s-1OSSL_PKEY_PARAM_RSA_FACTOR6\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-factor6'' (\fB\s-1OSSL_PKEY_PARAM_RSA_FACTOR6\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-factor6 (OSSL_PKEY_PARAM_RSA_FACTOR6) <unsigned integer>" +.ie n .IP """rsa\-factor7"" (\fB\s-1OSSL_PKEY_PARAM_RSA_FACTOR7\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-factor7'' (\fB\s-1OSSL_PKEY_PARAM_RSA_FACTOR7\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-factor7 (OSSL_PKEY_PARAM_RSA_FACTOR7) <unsigned integer>" +.ie n .IP """rsa\-factor8"" (\fB\s-1OSSL_PKEY_PARAM_RSA_FACTOR8\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-factor8'' (\fB\s-1OSSL_PKEY_PARAM_RSA_FACTOR8\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-factor8 (OSSL_PKEY_PARAM_RSA_FACTOR8) <unsigned integer>" +.ie n .IP """rsa\-factor9"" (\fB\s-1OSSL_PKEY_PARAM_RSA_FACTOR9\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-factor9'' (\fB\s-1OSSL_PKEY_PARAM_RSA_FACTOR9\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-factor9 (OSSL_PKEY_PARAM_RSA_FACTOR9) <unsigned integer>" +.ie n .IP """rsa\-factor10"" (\fB\s-1OSSL_PKEY_PARAM_RSA_FACTOR10\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-factor10'' (\fB\s-1OSSL_PKEY_PARAM_RSA_FACTOR10\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-factor10 (OSSL_PKEY_PARAM_RSA_FACTOR10) <unsigned integer>" +.PD +\&\s-1RSA\s0 prime factors. The factors are known as \*(L"p\*(R", \*(L"q\*(R" and \*(L"r_i\*(R" in \s-1RFC8017.\s0 +Up to eight additional \*(L"r_i\*(R" prime factors are supported. +.ie n .IP """rsa\-exponent1"" (\fB\s-1OSSL_PKEY_PARAM_RSA_EXPONENT1\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-exponent1'' (\fB\s-1OSSL_PKEY_PARAM_RSA_EXPONENT1\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-exponent1 (OSSL_PKEY_PARAM_RSA_EXPONENT1) <unsigned integer>" +.PD 0 +.ie n .IP """rsa\-exponent2"" (\fB\s-1OSSL_PKEY_PARAM_RSA_EXPONENT2\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-exponent2'' (\fB\s-1OSSL_PKEY_PARAM_RSA_EXPONENT2\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-exponent2 (OSSL_PKEY_PARAM_RSA_EXPONENT2) <unsigned integer>" +.ie n .IP """rsa\-exponent3"" (\fB\s-1OSSL_PKEY_PARAM_RSA_EXPONENT3\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-exponent3'' (\fB\s-1OSSL_PKEY_PARAM_RSA_EXPONENT3\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-exponent3 (OSSL_PKEY_PARAM_RSA_EXPONENT3) <unsigned integer>" +.ie n .IP """rsa\-exponent4"" (\fB\s-1OSSL_PKEY_PARAM_RSA_EXPONENT4\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-exponent4'' (\fB\s-1OSSL_PKEY_PARAM_RSA_EXPONENT4\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-exponent4 (OSSL_PKEY_PARAM_RSA_EXPONENT4) <unsigned integer>" +.ie n .IP """rsa\-exponent5"" (\fB\s-1OSSL_PKEY_PARAM_RSA_EXPONENT5\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-exponent5'' (\fB\s-1OSSL_PKEY_PARAM_RSA_EXPONENT5\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-exponent5 (OSSL_PKEY_PARAM_RSA_EXPONENT5) <unsigned integer>" +.ie n .IP """rsa\-exponent6"" (\fB\s-1OSSL_PKEY_PARAM_RSA_EXPONENT6\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-exponent6'' (\fB\s-1OSSL_PKEY_PARAM_RSA_EXPONENT6\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-exponent6 (OSSL_PKEY_PARAM_RSA_EXPONENT6) <unsigned integer>" +.ie n .IP """rsa\-exponent7"" (\fB\s-1OSSL_PKEY_PARAM_RSA_EXPONENT7\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-exponent7'' (\fB\s-1OSSL_PKEY_PARAM_RSA_EXPONENT7\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-exponent7 (OSSL_PKEY_PARAM_RSA_EXPONENT7) <unsigned integer>" +.ie n .IP """rsa\-exponent8"" (\fB\s-1OSSL_PKEY_PARAM_RSA_EXPONENT8\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-exponent8'' (\fB\s-1OSSL_PKEY_PARAM_RSA_EXPONENT8\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-exponent8 (OSSL_PKEY_PARAM_RSA_EXPONENT8) <unsigned integer>" +.ie n .IP """rsa\-exponent9"" (\fB\s-1OSSL_PKEY_PARAM_RSA_EXPONENT9\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-exponent9'' (\fB\s-1OSSL_PKEY_PARAM_RSA_EXPONENT9\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-exponent9 (OSSL_PKEY_PARAM_RSA_EXPONENT9) <unsigned integer>" +.ie n .IP """rsa\-exponent10"" (\fB\s-1OSSL_PKEY_PARAM_RSA_EXPONENT10\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-exponent10'' (\fB\s-1OSSL_PKEY_PARAM_RSA_EXPONENT10\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-exponent10 (OSSL_PKEY_PARAM_RSA_EXPONENT10) <unsigned integer>" +.PD +\&\s-1RSA CRT\s0 (Chinese Remainder Theorem) exponents. The exponents are known +as \*(L"dP\*(R", \*(L"dQ\*(R" and \*(L"d_i in \s-1RFC8017\*(R".\s0 +Up to eight additional \*(L"d_i\*(R" exponents are supported. +.ie n .IP """rsa\-coefficient1"" (\fB\s-1OSSL_PKEY_PARAM_RSA_COEFFICIENT1\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-coefficient1'' (\fB\s-1OSSL_PKEY_PARAM_RSA_COEFFICIENT1\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-coefficient1 (OSSL_PKEY_PARAM_RSA_COEFFICIENT1) <unsigned integer>" +.PD 0 +.ie n .IP """rsa\-coefficient2"" (\fB\s-1OSSL_PKEY_PARAM_RSA_COEFFICIENT2\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-coefficient2'' (\fB\s-1OSSL_PKEY_PARAM_RSA_COEFFICIENT2\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-coefficient2 (OSSL_PKEY_PARAM_RSA_COEFFICIENT2) <unsigned integer>" +.ie n .IP """rsa\-coefficient3"" (\fB\s-1OSSL_PKEY_PARAM_RSA_COEFFICIENT3\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-coefficient3'' (\fB\s-1OSSL_PKEY_PARAM_RSA_COEFFICIENT3\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-coefficient3 (OSSL_PKEY_PARAM_RSA_COEFFICIENT3) <unsigned integer>" +.ie n .IP """rsa\-coefficient4"" (\fB\s-1OSSL_PKEY_PARAM_RSA_COEFFICIENT4\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-coefficient4'' (\fB\s-1OSSL_PKEY_PARAM_RSA_COEFFICIENT4\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-coefficient4 (OSSL_PKEY_PARAM_RSA_COEFFICIENT4) <unsigned integer>" +.ie n .IP """rsa\-coefficient5"" (\fB\s-1OSSL_PKEY_PARAM_RSA_COEFFICIENT5\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-coefficient5'' (\fB\s-1OSSL_PKEY_PARAM_RSA_COEFFICIENT5\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-coefficient5 (OSSL_PKEY_PARAM_RSA_COEFFICIENT5) <unsigned integer>" +.ie n .IP """rsa\-coefficient6"" (\fB\s-1OSSL_PKEY_PARAM_RSA_COEFFICIENT6\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-coefficient6'' (\fB\s-1OSSL_PKEY_PARAM_RSA_COEFFICIENT6\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-coefficient6 (OSSL_PKEY_PARAM_RSA_COEFFICIENT6) <unsigned integer>" +.ie n .IP """rsa\-coefficient7"" (\fB\s-1OSSL_PKEY_PARAM_RSA_COEFFICIENT7\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-coefficient7'' (\fB\s-1OSSL_PKEY_PARAM_RSA_COEFFICIENT7\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-coefficient7 (OSSL_PKEY_PARAM_RSA_COEFFICIENT7) <unsigned integer>" +.ie n .IP """rsa\-coefficient8"" (\fB\s-1OSSL_PKEY_PARAM_RSA_COEFFICIENT8\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-coefficient8'' (\fB\s-1OSSL_PKEY_PARAM_RSA_COEFFICIENT8\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-coefficient8 (OSSL_PKEY_PARAM_RSA_COEFFICIENT8) <unsigned integer>" +.ie n .IP """rsa\-coefficient9"" (\fB\s-1OSSL_PKEY_PARAM_RSA_COEFFICIENT9\s0\fR) <unsigned integer>" 4 +.el .IP "``rsa\-coefficient9'' (\fB\s-1OSSL_PKEY_PARAM_RSA_COEFFICIENT9\s0\fR) <unsigned integer>" 4 +.IX Item "rsa-coefficient9 (OSSL_PKEY_PARAM_RSA_COEFFICIENT9) <unsigned integer>" +.PD +\&\s-1RSA CRT\s0 (Chinese Remainder Theorem) coefficients. The coefficients are known as +\&\*(L"qInv\*(R" and \*(L"t_i\*(R". +Up to eight additional \*(L"t_i\*(R" exponents are supported. +.SS "\s-1RSA\s0 key generation parameters" +.IX Subsection "RSA key generation parameters" +When generating \s-1RSA\s0 keys, the following key generation parameters may be used. +.ie n .IP """bits"" (\fB\s-1OSSL_PKEY_PARAM_RSA_BITS\s0\fR) <unsigned integer>" 4 +.el .IP "``bits'' (\fB\s-1OSSL_PKEY_PARAM_RSA_BITS\s0\fR) <unsigned integer>" 4 +.IX Item "bits (OSSL_PKEY_PARAM_RSA_BITS) <unsigned integer>" +The value should be the cryptographic length for the \fB\s-1RSA\s0\fR cryptosystem, in +bits. +.ie n .IP """primes"" (\fB\s-1OSSL_PKEY_PARAM_RSA_PRIMES\s0\fR) <unsigned integer>" 4 +.el .IP "``primes'' (\fB\s-1OSSL_PKEY_PARAM_RSA_PRIMES\s0\fR) <unsigned integer>" 4 +.IX Item "primes (OSSL_PKEY_PARAM_RSA_PRIMES) <unsigned integer>" +The value should be the number of primes for the generated \fB\s-1RSA\s0\fR key. The +default is 2. It isn't permitted to specify a larger number of primes than +10. Additionally, the number of primes is limited by the length of the key +being generated so the maximum number could be less. +Some providers may only support a value of 2. +.ie n .IP """e"" (\fB\s-1OSSL_PKEY_PARAM_RSA_E\s0\fR) <unsigned integer>" 4 +.el .IP "``e'' (\fB\s-1OSSL_PKEY_PARAM_RSA_E\s0\fR) <unsigned integer>" 4 +.IX Item "e (OSSL_PKEY_PARAM_RSA_E) <unsigned integer>" +The \s-1RSA\s0 \*(L"e\*(R" value. The value may be any odd number greater than or equal to +65537. The default value is 65537. +For legacy reasons a value of 3 is currently accepted but is deprecated. +.SS "\s-1RSA\s0 key generation parameters for \s-1FIPS\s0 module testing" +.IX Subsection "RSA key generation parameters for FIPS module testing" +When generating \s-1RSA\s0 keys, the following additional key generation parameters may +be used for algorithm testing purposes only. Do not use these to generate +\&\s-1RSA\s0 keys for a production environment. +.ie n .IP """xp"" (\fB\s-1OSSL_PKEY_PARAM_RSA_TEST_XP\s0\fR) <unsigned integer>" 4 +.el .IP "``xp'' (\fB\s-1OSSL_PKEY_PARAM_RSA_TEST_XP\s0\fR) <unsigned integer>" 4 +.IX Item "xp (OSSL_PKEY_PARAM_RSA_TEST_XP) <unsigned integer>" +.PD 0 +.ie n .IP """xq"" (\fB\s-1OSSL_PKEY_PARAM_RSA_TEST_XQ\s0\fR) <unsigned integer>" 4 +.el .IP "``xq'' (\fB\s-1OSSL_PKEY_PARAM_RSA_TEST_XQ\s0\fR) <unsigned integer>" 4 +.IX Item "xq (OSSL_PKEY_PARAM_RSA_TEST_XQ) <unsigned integer>" +.PD +These 2 fields are normally randomly generated and are used to generate \*(L"p\*(R" and +\&\*(L"q\*(R". +.ie n .IP """xp1"" (\fB\s-1OSSL_PKEY_PARAM_RSA_TEST_XP1\s0\fR) <unsigned integer>" 4 +.el .IP "``xp1'' (\fB\s-1OSSL_PKEY_PARAM_RSA_TEST_XP1\s0\fR) <unsigned integer>" 4 +.IX Item "xp1 (OSSL_PKEY_PARAM_RSA_TEST_XP1) <unsigned integer>" +.PD 0 +.ie n .IP """xp2"" (\fB\s-1OSSL_PKEY_PARAM_RSA_TEST_XP2\s0\fR) <unsigned integer>" 4 +.el .IP "``xp2'' (\fB\s-1OSSL_PKEY_PARAM_RSA_TEST_XP2\s0\fR) <unsigned integer>" 4 +.IX Item "xp2 (OSSL_PKEY_PARAM_RSA_TEST_XP2) <unsigned integer>" +.ie n .IP """xq1"" (\fB\s-1OSSL_PKEY_PARAM_RSA_TEST_XQ1\s0\fR) <unsigned integer>" 4 +.el .IP "``xq1'' (\fB\s-1OSSL_PKEY_PARAM_RSA_TEST_XQ1\s0\fR) <unsigned integer>" 4 +.IX Item "xq1 (OSSL_PKEY_PARAM_RSA_TEST_XQ1) <unsigned integer>" +.ie n .IP """xq2"" (\fB\s-1OSSL_PKEY_PARAM_RSA_TEST_XQ2\s0\fR) <unsigned integer>" 4 +.el .IP "``xq2'' (\fB\s-1OSSL_PKEY_PARAM_RSA_TEST_XQ2\s0\fR) <unsigned integer>" 4 +.IX Item "xq2 (OSSL_PKEY_PARAM_RSA_TEST_XQ2) <unsigned integer>" +.PD +These 4 fields are normally randomly generated. The prime factors \*(L"p1\*(R", \*(L"p2\*(R", +\&\*(L"q1\*(R" and \*(L"q2\*(R" are determined from these values. +.SS "\s-1RSA\s0 key parameters for \s-1FIPS\s0 module testing" +.IX Subsection "RSA key parameters for FIPS module testing" +The following intermediate values can be retrieved only if the values +specified in \*(L"\s-1RSA\s0 key generation parameters for \s-1FIPS\s0 module testing\*(R" are set. +These should not be accessed in a production environment. +.ie n .IP """p1"" (\fB\s-1OSSL_PKEY_PARAM_RSA_TEST_P1\s0\fR) <unsigned integer>" 4 +.el .IP "``p1'' (\fB\s-1OSSL_PKEY_PARAM_RSA_TEST_P1\s0\fR) <unsigned integer>" 4 +.IX Item "p1 (OSSL_PKEY_PARAM_RSA_TEST_P1) <unsigned integer>" +.PD 0 +.ie n .IP """p2"" (\fB\s-1OSSL_PKEY_PARAM_RSA_TEST_P2\s0\fR) <unsigned integer>" 4 +.el .IP "``p2'' (\fB\s-1OSSL_PKEY_PARAM_RSA_TEST_P2\s0\fR) <unsigned integer>" 4 +.IX Item "p2 (OSSL_PKEY_PARAM_RSA_TEST_P2) <unsigned integer>" +.ie n .IP """q1"" (\fB\s-1OSSL_PKEY_PARAM_RSA_TEST_Q1\s0\fR) <unsigned integer>" 4 +.el .IP "``q1'' (\fB\s-1OSSL_PKEY_PARAM_RSA_TEST_Q1\s0\fR) <unsigned integer>" 4 +.IX Item "q1 (OSSL_PKEY_PARAM_RSA_TEST_Q1) <unsigned integer>" +.ie n .IP """q2"" (\fB\s-1OSSL_PKEY_PARAM_RSA_TEST_Q2\s0\fR) <unsigned integer>" 4 +.el .IP "``q2'' (\fB\s-1OSSL_PKEY_PARAM_RSA_TEST_Q2\s0\fR) <unsigned integer>" 4 +.IX Item "q2 (OSSL_PKEY_PARAM_RSA_TEST_Q2) <unsigned integer>" +.PD +The auxiliary probable primes. +.SS "\s-1RSA\s0 key validation" +.IX Subsection "RSA key validation" +For \s-1RSA\s0 keys, \fBEVP_PKEY_param_check\fR\|(3) and \fBEVP_PKEY_param_check_quick\fR\|(3) +both return 1 unconditionally. +.PP +For \s-1RSA\s0 keys, \fBEVP_PKEY_public_check\fR\|(3) conforms to the SP800\-56Br1 \fIpublic key +check\fR when the OpenSSL \s-1FIPS\s0 provider is used. The OpenSSL default provider +performs similar tests but relaxes the keysize restrictions for backwards +compatibility. +.PP +For \s-1RSA\s0 keys, \fBEVP_PKEY_public_check_quick\fR\|(3) is the same as +\&\fBEVP_PKEY_public_check\fR\|(3). +.PP +For \s-1RSA\s0 keys, \fBEVP_PKEY_private_check\fR\|(3) conforms to the SP800\-56Br1 +\&\fIprivate key test\fR. +.PP +For \s-1RSA\s0 keys, \fBEVP_PKEY_pairwise_check\fR\|(3) conforms to the +SP800\-56Br1 \fIKeyPair Validation check\fR for the OpenSSL \s-1FIPS\s0 provider. The +OpenSSL default provider allows testing of the validity of multi-primes. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +.IP "\s-1FIPS186\-4\s0" 4 +.IX Item "FIPS186-4" +Section B.3.6 Generation of Probable Primes with Conditions Based on +Auxiliary Probable Primes +.IP "\s-1RFC 8017,\s0 excluding RSA-PSS and RSA-OAEP" 4 +.IX Item "RFC 8017, excluding RSA-PSS and RSA-OAEP" +.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, "RSA", NULL); +.Ve +.PP +An \fB\s-1RSA\s0\fR key can be generated simply like this: +.PP +.Vb 1 +\& pkey = EVP_RSA_gen(4096); +.Ve +.PP +or like this: +.PP +.Vb 3 +\& EVP_PKEY *pkey = NULL; +\& EVP_PKEY_CTX *pctx = +\& EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL); +\& +\& EVP_PKEY_keygen_init(pctx); +\& EVP_PKEY_generate(pctx, &pkey); +\& EVP_PKEY_CTX_free(pctx); +.Ve +.PP +An \fB\s-1RSA\s0\fR key can be generated with key generation parameters: +.PP +.Vb 5 +\& unsigned int primes = 3; +\& unsigned int bits = 4096; +\& OSSL_PARAM params[3]; +\& EVP_PKEY *pkey = NULL; +\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL); +\& +\& EVP_PKEY_keygen_init(pctx); +\& +\& params[0] = OSSL_PARAM_construct_uint("bits", &bits); +\& params[1] = OSSL_PARAM_construct_uint("primes", &primes); +\& params[2] = OSSL_PARAM_construct_end(); +\& EVP_PKEY_CTX_set_params(pctx, params); +\& +\& EVP_PKEY_generate(pctx, &pkey); +\& EVP_PKEY_print_private(bio_out, pkey, 0, NULL); +\& EVP_PKEY_CTX_free(pctx); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_RSA_gen\fR\|(3), \s-1\fBEVP_KEYMGMT\s0\fR\|(3), \s-1\fBEVP_PKEY\s0\fR\|(3), \fBprovider\-keymgmt\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2023 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>. diff --git a/secure/lib/libcrypto/man/man7/SM2.7 b/secure/lib/libcrypto/man/man7/EVP_PKEY-SM2.7 index 4536f1a42cf9..285528e9e525 100644 --- a/secure/lib/libcrypto/man/man7/SM2.7 +++ b/secure/lib/libcrypto/man/man7/EVP_PKEY-SM2.7 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .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 \{\ @@ -132,14 +130,15 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "SM2 7" -.TH SM2 7 "2022-06-21" "1.1.1p" "OpenSSL" +.IX Title "EVP_PKEY-SM2 7ossl" +.TH EVP_PKEY-SM2 7ossl "2023-09-19" "3.0.11" "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" -SM2 \- Chinese SM2 signature and encryption algorithm support +EVP_PKEY\-SM2, EVP_KEYMGMT\-SM2, SM2 +\&\- EVP_PKEY keytype support for the Chinese SM2 signature and encryption algorithms .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \fB\s-1SM2\s0\fR algorithm was first defined by the Chinese national standard \s-1GM/T @@ -149,38 +148,46 @@ both signature and encryption schemes via the \s-1EVP\s0 interface. .PP When doing the \fB\s-1SM2\s0\fR signature algorithm, it requires a distinguishing identifier to form the message prefix which is hashed before the real message is hashed. +.SS "Common \s-1SM2\s0 parameters" +.IX Subsection "Common SM2 parameters" +\&\s-1SM2\s0 uses the parameters defined in \*(L"Common \s-1EC\s0 parameters\*(R" in \s-1\fBEVP_PKEY\-EC\s0\fR\|(7). +The following parameters are different: +.ie n .IP """cofactor"" (\fB\s-1OSSL_PKEY_PARAM_EC_COFACTOR\s0\fR) <unsigned integer>" 4 +.el .IP "``cofactor'' (\fB\s-1OSSL_PKEY_PARAM_EC_COFACTOR\s0\fR) <unsigned integer>" 4 +.IX Item "cofactor (OSSL_PKEY_PARAM_EC_COFACTOR) <unsigned integer>" +This parameter is ignored for \fB\s-1SM2\s0\fR. +.IP "(\fB\s-1OSSL_PKEY_PARAM_DEFAULT_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "(OSSL_PKEY_PARAM_DEFAULT_DIGEST) <UTF8 string>" +Getter that returns the default digest name. +(Currently returns \*(L"\s-1SM3\*(R"\s0 as of OpenSSL 3.0). .SH "NOTES" .IX Header "NOTES" \&\fB\s-1SM2\s0\fR signatures can be generated by using the 'DigestSign' series of APIs, for instance, \fBEVP_DigestSignInit()\fR, \fBEVP_DigestSignUpdate()\fR and \fBEVP_DigestSignFinal()\fR. Ditto for the verification process by calling the 'DigestVerify' series of APIs. .PP -There are several special steps that need to be done before computing an \fB\s-1SM2\s0\fR -signature. -.PP -The \fB\s-1EVP_PKEY\s0\fR structure will default to using \s-1ECDSA\s0 for signatures when it is -created. It should be set to \fB\s-1EVP_PKEY_SM2\s0\fR by calling: -.PP -.Vb 1 -\& EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2); -.Ve -.PP -Then an \s-1ID\s0 should be set by calling: +Before computing an \fB\s-1SM2\s0\fR signature, an \fB\s-1EVP_PKEY_CTX\s0\fR needs to be created, +and an \fB\s-1SM2\s0\fR \s-1ID\s0 must be set for it, like this: .PP .Vb 1 \& EVP_PKEY_CTX_set1_id(pctx, id, id_len); .Ve .PP -When calling the \fBEVP_DigestSignInit()\fR or \fBEVP_DigestVerifyInit()\fR functions, a -preallocated \fB\s-1EVP_PKEY_CTX\s0\fR should be assigned to the \fB\s-1EVP_MD_CTX\s0\fR. This is -done by calling: +Before calling the \fBEVP_DigestSignInit()\fR or \fBEVP_DigestVerifyInit()\fR functions, +that \fB\s-1EVP_PKEY_CTX\s0\fR should be assigned to the \fB\s-1EVP_MD_CTX\s0\fR, like this: .PP .Vb 1 \& EVP_MD_CTX_set_pkey_ctx(mctx, pctx); .Ve .PP -And normally there is no need to pass a \fBpctx\fR parameter to \fBEVP_DigestSignInit()\fR +There is normally no need to pass a \fBpctx\fR parameter to \fBEVP_DigestSignInit()\fR or \fBEVP_DigestVerifyInit()\fR in such a scenario. +.PP +\&\s-1SM2\s0 can be tested with the \fBopenssl\-speed\fR\|(1) application since version 3.0. +Currently, the only valid algorithm name is \fBsm2\fR. +.PP +Since version 3.0, \s-1SM2\s0 keys can be generated and loaded only when the domain +parameters specify the \s-1SM2\s0 elliptic curve. .SH "EXAMPLES" .IX Header "EXAMPLES" This example demonstrates the calling sequence for using an \fB\s-1EVP_PKEY\s0\fR to verify @@ -190,11 +197,10 @@ a message with the \s-1SM2\s0 signature algorithm and the \s-1SM3\s0 hash algori \& #include <openssl/evp.h> \& \& /* obtain an EVP_PKEY using whatever methods... */ -\& EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2); \& mctx = EVP_MD_CTX_new(); \& pctx = EVP_PKEY_CTX_new(pkey, NULL); \& EVP_PKEY_CTX_set1_id(pctx, id, id_len); -\& EVP_MD_CTX_set_pkey_ctx(mctx, pctx);; +\& EVP_MD_CTX_set_pkey_ctx(mctx, pctx); \& EVP_DigestVerifyInit(mctx, NULL, EVP_sm3(), NULL, pkey); \& EVP_DigestVerifyUpdate(mctx, msg, msg_len); \& EVP_DigestVerifyFinal(mctx, sig, sig_len) @@ -202,16 +208,15 @@ a message with the \s-1SM2\s0 signature algorithm and the \s-1SM3\s0 hash algori .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBEVP_PKEY_CTX_new\fR\|(3), -\&\fBEVP_PKEY_set_alias_type\fR\|(3), \&\fBEVP_DigestSignInit\fR\|(3), \&\fBEVP_DigestVerifyInit\fR\|(3), \&\fBEVP_PKEY_CTX_set1_id\fR\|(3), \&\fBEVP_MD_CTX_set_pkey_ctx\fR\|(3) .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2018\-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_PKEY-X25519.7 b/secure/lib/libcrypto/man/man7/EVP_PKEY-X25519.7 new file mode 100644 index 000000000000..6bbacd1a8cc5 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_PKEY-X25519.7 @@ -0,0 +1,227 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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-X25519 7ossl" +.TH EVP_PKEY-X25519 7ossl "2023-09-19" "3.0.11" "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\-X25519, EVP_PKEY\-X448, EVP_PKEY\-ED25519, EVP_PKEY\-ED448, +EVP_KEYMGMT\-X25519, EVP_KEYMGMT\-X448, EVP_KEYMGMT\-ED25519, EVP_KEYMGMT\-ED448 +\&\- EVP_PKEY X25519, X448, ED25519 and ED448 keytype and algorithm support +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fBX25519\fR, \fBX448\fR, \fB\s-1ED25519\s0\fR and \fB\s-1ED448\s0\fR keytypes 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 +No additional parameters can be set during key generation. +.SS "Common X25519, X448, \s-1ED25519\s0 and \s-1ED448\s0 parameters" +.IX Subsection "Common X25519, X448, ED25519 and ED448 parameters" +In addition to the common parameters that all keytypes should support (see +\&\*(L"Common parameters\*(R" in \fBprovider\-keymgmt\fR\|(7)), the implementation of these keytypes +support the following. +.ie n .IP """group"" (\fB\s-1OSSL_PKEY_PARAM_GROUP_NAME\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``group'' (\fB\s-1OSSL_PKEY_PARAM_GROUP_NAME\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "group (OSSL_PKEY_PARAM_GROUP_NAME) <UTF8 string>" +This is only supported by X25519 and X448. The group name must be \*(L"x25519\*(R" or +\&\*(L"x448\*(R" respectively for those algorithms. This is only present for consistency +with other key exchange algorithms and is typically not needed. +.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 public key value. +.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 private key value. +.ie n .IP """encoded-pub-key"" (\fB\s-1OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY\s0\fR) <octet string>" 4 +.el .IP "``encoded-pub-key'' (\fB\s-1OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY\s0\fR) <octet string>" 4 +.IX Item "encoded-pub-key (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) <octet string>" +Used for getting and setting the encoding of a public key for the \fBX25519\fR and +\&\fBX448\fR key types. Public keys are expected be encoded in a format as defined by +\&\s-1RFC7748.\s0 +.SS "\s-1ED25519\s0 and \s-1ED448\s0 parameters" +.IX Subsection "ED25519 and ED448 parameters" +.ie n .IP """mandatory-digest"" (\fB\s-1OSSL_PKEY_PARAM_MANDATORY_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``mandatory-digest'' (\fB\s-1OSSL_PKEY_PARAM_MANDATORY_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "mandatory-digest (OSSL_PKEY_PARAM_MANDATORY_DIGEST) <UTF8 string>" +The empty string, signifying that no digest may be specified. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +.IP "\s-1RFC 8032\s0" 4 +.IX Item "RFC 8032" +.PD 0 +.IP "\s-1RFC 8410\s0" 4 +.IX Item "RFC 8410" +.PD +.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, "X25519", NULL); +\& +\& EVP_PKEY_CTX *pctx = +\& EVP_PKEY_CTX_new_from_name(NULL, "X448", NULL); +\& +\& EVP_PKEY_CTX *pctx = +\& EVP_PKEY_CTX_new_from_name(NULL, "ED25519", NULL); +\& +\& EVP_PKEY_CTX *pctx = +\& EVP_PKEY_CTX_new_from_name(NULL, "ED448", NULL); +.Ve +.PP +An \fBX25519\fR key can be generated like this: +.PP +.Vb 1 +\& pkey = EVP_PKEY_Q_keygen(NULL, NULL, "X25519"); +.Ve +.PP +An \fBX448\fR, \fB\s-1ED25519\s0\fR, or \fB\s-1ED448\s0\fR key can be generated likewise. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_KEYMGMT\s0\fR\|(3), \s-1\fBEVP_PKEY\s0\fR\|(3), \fBprovider\-keymgmt\fR\|(7), +\&\s-1\fBEVP_KEYEXCH\-X25519\s0\fR\|(7), \s-1\fBEVP_KEYEXCH\-X448\s0\fR\|(7), +\&\s-1\fBEVP_SIGNATURE\-ED25519\s0\fR\|(7), \s-1\fBEVP_SIGNATURE\-ED448\s0\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 \*(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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_RAND-CTR-DRBG.7 b/secure/lib/libcrypto/man/man7/EVP_RAND-CTR-DRBG.7 new file mode 100644 index 000000000000..ec01146899b7 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_RAND-CTR-DRBG.7 @@ -0,0 +1,247 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_RAND-CTR-DRBG 7ossl" +.TH EVP_RAND-CTR-DRBG 7ossl "2023-09-19" "3.0.11" "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_RAND\-CTR\-DRBG \- The CTR DRBG EVP_RAND implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for the counter deterministic random bit generator through the +\&\fB\s-1EVP_RAND\s0\fR \s-1API.\s0 +.SS "Identity" +.IX Subsection "Identity" +\&\*(L"CTR-DRBG\*(R" is the name for this implementation; it can be used with the +\&\fBEVP_RAND_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.ie n .IP """state"" (\fB\s-1OSSL_RAND_PARAM_STATE\s0\fR) <integer>" 4 +.el .IP "``state'' (\fB\s-1OSSL_RAND_PARAM_STATE\s0\fR) <integer>" 4 +.IX Item "state (OSSL_RAND_PARAM_STATE) <integer>" +.PD 0 +.ie n .IP """strength"" (\fB\s-1OSSL_RAND_PARAM_STRENGTH\s0\fR) <unsigned integer>" 4 +.el .IP "``strength'' (\fB\s-1OSSL_RAND_PARAM_STRENGTH\s0\fR) <unsigned integer>" 4 +.IX Item "strength (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>" +.ie n .IP """max_request"" (\fB\s-1OSSL_RAND_PARAM_MAX_REQUEST\s0\fR) <unsigned integer>" 4 +.el .IP "``max_request'' (\fB\s-1OSSL_RAND_PARAM_MAX_REQUEST\s0\fR) <unsigned integer>" 4 +.IX Item "max_request (OSSL_RAND_PARAM_MAX_REQUEST) <unsigned integer>" +.ie n .IP """reseed_requests"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_REQUESTS\s0\fR) <unsigned integer>" 4 +.el .IP "``reseed_requests'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_REQUESTS\s0\fR) <unsigned integer>" 4 +.IX Item "reseed_requests (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>" +.ie n .IP """reseed_time_interval"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL\s0\fR) <integer>" 4 +.el .IP "``reseed_time_interval'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL\s0\fR) <integer>" 4 +.IX Item "reseed_time_interval (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <integer>" +.ie n .IP """min_entropylen"" (\fB\s-1OSSL_DRBG_PARAM_MIN_ENTROPYLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``min_entropylen'' (\fB\s-1OSSL_DRBG_PARAM_MIN_ENTROPYLEN\s0\fR) <unsigned integer>" 4 +.IX Item "min_entropylen (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>" +.ie n .IP """max_entropylen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_ENTROPYLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``max_entropylen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_ENTROPYLEN\s0\fR) <unsigned integer>" 4 +.IX Item "max_entropylen (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>" +.ie n .IP """min_noncelen"" (\fB\s-1OSSL_DRBG_PARAM_MIN_NONCELEN\s0\fR) <unsigned integer>" 4 +.el .IP "``min_noncelen'' (\fB\s-1OSSL_DRBG_PARAM_MIN_NONCELEN\s0\fR) <unsigned integer>" 4 +.IX Item "min_noncelen (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>" +.ie n .IP """max_noncelen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_NONCELEN\s0\fR) <unsigned integer>" 4 +.el .IP "``max_noncelen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_NONCELEN\s0\fR) <unsigned integer>" 4 +.IX Item "max_noncelen (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>" +.ie n .IP """max_perslen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_PERSLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``max_perslen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_PERSLEN\s0\fR) <unsigned integer>" 4 +.IX Item "max_perslen (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>" +.ie n .IP """max_adinlen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_ADINLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``max_adinlen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_ADINLEN\s0\fR) <unsigned integer>" 4 +.IX Item "max_adinlen (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>" +.ie n .IP """reseed_counter"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_COUNTER\s0\fR) <unsigned integer>" 4 +.el .IP "``reseed_counter'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_COUNTER\s0\fR) <unsigned integer>" 4 +.IX Item "reseed_counter (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>" +.ie n .IP """properties"" (\fB\s-1OSSL_DRBG_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_DRBG_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_DRBG_PARAM_PROPERTIES) <UTF8 string>" +.ie n .IP """cipher"" (\fB\s-1OSSL_DRBG_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``cipher'' (\fB\s-1OSSL_DRBG_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "cipher (OSSL_DRBG_PARAM_CIPHER) <UTF8 string>" +.PD +These parameters work as described in \*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_RAND\s0\fR\|(3). +.ie n .IP """use_derivation_function"" (\fB\s-1OSSL_DRBG_PARAM_USE_DF\s0\fR) <integer>" 4 +.el .IP "``use_derivation_function'' (\fB\s-1OSSL_DRBG_PARAM_USE_DF\s0\fR) <integer>" 4 +.IX Item "use_derivation_function (OSSL_DRBG_PARAM_USE_DF) <integer>" +This Boolean indicates if a derivation function should be used or not. +A nonzero value (the default) uses the derivation function. A zero value +does not. +.SH "NOTES" +.IX Header "NOTES" +A context for \s-1CTR DRBG\s0 can be obtained by calling: +.PP +.Vb 2 +\& EVP_RAND *rand = EVP_RAND_fetch(NULL, "CTR\-DRBG", NULL); +\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand); +.Ve +.SH "EXAMPLES" +.IX Header "EXAMPLES" +.Vb 5 +\& EVP_RAND *rand; +\& EVP_RAND_CTX *rctx; +\& unsigned char bytes[100]; +\& OSSL_PARAM params[2], *p = params; +\& unsigned int strength = 128; +\& +\& rand = EVP_RAND_fetch(NULL, "CTR\-DRBG", NULL); +\& rctx = EVP_RAND_CTX_new(rand, NULL); +\& EVP_RAND_free(rand); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_CIPHER, +\& SN_aes_256_ctr, 0); +\& *p = OSSL_PARAM_construct_end(); +\& EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params); +\& +\& EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0); +\& +\& EVP_RAND_CTX_free(rctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1NIST SP 800\-90A\s0 and \s-1SP 800\-90B\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_RAND\s0\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_RAND\s0\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_RAND-HASH-DRBG.7 b/secure/lib/libcrypto/man/man7/EVP_RAND-HASH-DRBG.7 new file mode 100644 index 000000000000..f9d8f02d0a48 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_RAND-HASH-DRBG.7 @@ -0,0 +1,240 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_RAND-HASH-DRBG 7ossl" +.TH EVP_RAND-HASH-DRBG 7ossl "2023-09-19" "3.0.11" "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_RAND\-HASH\-DRBG \- The HASH DRBG EVP_RAND implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for the hash deterministic random bit generator through the +\&\fB\s-1EVP_RAND\s0\fR \s-1API.\s0 +.SS "Identity" +.IX Subsection "Identity" +\&\*(L"HASH-DRBG\*(R" is the name for this implementation; it can be used with the +\&\fBEVP_RAND_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.ie n .IP """state"" (\fB\s-1OSSL_RAND_PARAM_STATE\s0\fR) <integer>" 4 +.el .IP "``state'' (\fB\s-1OSSL_RAND_PARAM_STATE\s0\fR) <integer>" 4 +.IX Item "state (OSSL_RAND_PARAM_STATE) <integer>" +.PD 0 +.ie n .IP """strength"" (\fB\s-1OSSL_RAND_PARAM_STRENGTH\s0\fR) <unsigned integer>" 4 +.el .IP "``strength'' (\fB\s-1OSSL_RAND_PARAM_STRENGTH\s0\fR) <unsigned integer>" 4 +.IX Item "strength (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>" +.ie n .IP """max_request"" (\fB\s-1OSSL_RAND_PARAM_MAX_REQUEST\s0\fR) <unsigned integer>" 4 +.el .IP "``max_request'' (\fB\s-1OSSL_RAND_PARAM_MAX_REQUEST\s0\fR) <unsigned integer>" 4 +.IX Item "max_request (OSSL_RAND_PARAM_MAX_REQUEST) <unsigned integer>" +.ie n .IP """reseed_requests"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_REQUESTS\s0\fR) <unsigned integer>" 4 +.el .IP "``reseed_requests'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_REQUESTS\s0\fR) <unsigned integer>" 4 +.IX Item "reseed_requests (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>" +.ie n .IP """reseed_time_interval"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL\s0\fR) <integer>" 4 +.el .IP "``reseed_time_interval'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL\s0\fR) <integer>" 4 +.IX Item "reseed_time_interval (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <integer>" +.ie n .IP """min_entropylen"" (\fB\s-1OSSL_DRBG_PARAM_MIN_ENTROPYLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``min_entropylen'' (\fB\s-1OSSL_DRBG_PARAM_MIN_ENTROPYLEN\s0\fR) <unsigned integer>" 4 +.IX Item "min_entropylen (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>" +.ie n .IP """max_entropylen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_ENTROPYLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``max_entropylen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_ENTROPYLEN\s0\fR) <unsigned integer>" 4 +.IX Item "max_entropylen (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>" +.ie n .IP """min_noncelen"" (\fB\s-1OSSL_DRBG_PARAM_MIN_NONCELEN\s0\fR) <unsigned integer>" 4 +.el .IP "``min_noncelen'' (\fB\s-1OSSL_DRBG_PARAM_MIN_NONCELEN\s0\fR) <unsigned integer>" 4 +.IX Item "min_noncelen (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>" +.ie n .IP """max_noncelen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_NONCELEN\s0\fR) <unsigned integer>" 4 +.el .IP "``max_noncelen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_NONCELEN\s0\fR) <unsigned integer>" 4 +.IX Item "max_noncelen (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>" +.ie n .IP """max_perslen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_PERSLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``max_perslen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_PERSLEN\s0\fR) <unsigned integer>" 4 +.IX Item "max_perslen (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>" +.ie n .IP """max_adinlen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_ADINLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``max_adinlen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_ADINLEN\s0\fR) <unsigned integer>" 4 +.IX Item "max_adinlen (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>" +.ie n .IP """reseed_counter"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_COUNTER\s0\fR) <unsigned integer>" 4 +.el .IP "``reseed_counter'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_COUNTER\s0\fR) <unsigned integer>" 4 +.IX Item "reseed_counter (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>" +.ie n .IP """properties"" (\fB\s-1OSSL_DRBG_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_DRBG_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_DRBG_PARAM_PROPERTIES) <UTF8 string>" +.ie n .IP """digest"" (\fB\s-1OSSL_DRBG_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_DRBG_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_DRBG_PARAM_DIGEST) <UTF8 string>" +.PD +These parameters work as described in \*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_RAND\s0\fR\|(3). +.SH "NOTES" +.IX Header "NOTES" +A context for \s-1HASH DRBG\s0 can be obtained by calling: +.PP +.Vb 2 +\& EVP_RAND *rand = EVP_RAND_fetch(NULL, "HASH\-DRBG", NULL); +\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand); +.Ve +.SH "EXAMPLES" +.IX Header "EXAMPLES" +.Vb 5 +\& EVP_RAND *rand; +\& EVP_RAND_CTX *rctx; +\& unsigned char bytes[100]; +\& OSSL_PARAM params[2], *p = params; +\& unsigned int strength = 128; +\& +\& rand = EVP_RAND_fetch(NULL, "HASH\-DRBG", NULL); +\& rctx = EVP_RAND_CTX_new(rand, NULL); +\& EVP_RAND_free(rand); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_DIGEST, SN_sha512, 0); +\& *p = OSSL_PARAM_construct_end(); +\& EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params); +\& +\& EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0); +\& +\& EVP_RAND_CTX_free(rctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1NIST SP 800\-90A\s0 and \s-1SP 800\-90B\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_RAND\s0\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_RAND\s0\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_RAND-HMAC-DRBG.7 b/secure/lib/libcrypto/man/man7/EVP_RAND-HMAC-DRBG.7 new file mode 100644 index 000000000000..7e86d096e1b3 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_RAND-HMAC-DRBG.7 @@ -0,0 +1,244 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_RAND-HMAC-DRBG 7ossl" +.TH EVP_RAND-HMAC-DRBG 7ossl "2023-09-19" "3.0.11" "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_RAND\-HMAC\-DRBG \- The HMAC DRBG EVP_RAND implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for the \s-1HMAC\s0 deterministic random bit generator through the +\&\fB\s-1EVP_RAND\s0\fR \s-1API.\s0 +.SS "Identity" +.IX Subsection "Identity" +\&\*(L"HMAC-DRBG\*(R" is the name for this implementation; it can be used with the +\&\fBEVP_RAND_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.ie n .IP """state"" (\fB\s-1OSSL_RAND_PARAM_STATE\s0\fR) <integer>" 4 +.el .IP "``state'' (\fB\s-1OSSL_RAND_PARAM_STATE\s0\fR) <integer>" 4 +.IX Item "state (OSSL_RAND_PARAM_STATE) <integer>" +.PD 0 +.ie n .IP """strength"" (\fB\s-1OSSL_RAND_PARAM_STRENGTH\s0\fR) <unsigned integer>" 4 +.el .IP "``strength'' (\fB\s-1OSSL_RAND_PARAM_STRENGTH\s0\fR) <unsigned integer>" 4 +.IX Item "strength (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>" +.ie n .IP """max_request"" (\fB\s-1OSSL_RAND_PARAM_MAX_REQUEST\s0\fR) <unsigned integer>" 4 +.el .IP "``max_request'' (\fB\s-1OSSL_RAND_PARAM_MAX_REQUEST\s0\fR) <unsigned integer>" 4 +.IX Item "max_request (OSSL_RAND_PARAM_MAX_REQUEST) <unsigned integer>" +.ie n .IP """reseed_requests"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_REQUESTS\s0\fR) <unsigned integer>" 4 +.el .IP "``reseed_requests'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_REQUESTS\s0\fR) <unsigned integer>" 4 +.IX Item "reseed_requests (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>" +.ie n .IP """reseed_time_interval"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL\s0\fR) <integer>" 4 +.el .IP "``reseed_time_interval'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL\s0\fR) <integer>" 4 +.IX Item "reseed_time_interval (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <integer>" +.ie n .IP """min_entropylen"" (\fB\s-1OSSL_DRBG_PARAM_MIN_ENTROPYLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``min_entropylen'' (\fB\s-1OSSL_DRBG_PARAM_MIN_ENTROPYLEN\s0\fR) <unsigned integer>" 4 +.IX Item "min_entropylen (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>" +.ie n .IP """max_entropylen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_ENTROPYLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``max_entropylen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_ENTROPYLEN\s0\fR) <unsigned integer>" 4 +.IX Item "max_entropylen (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>" +.ie n .IP """min_noncelen"" (\fB\s-1OSSL_DRBG_PARAM_MIN_NONCELEN\s0\fR) <unsigned integer>" 4 +.el .IP "``min_noncelen'' (\fB\s-1OSSL_DRBG_PARAM_MIN_NONCELEN\s0\fR) <unsigned integer>" 4 +.IX Item "min_noncelen (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>" +.ie n .IP """max_noncelen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_NONCELEN\s0\fR) <unsigned integer>" 4 +.el .IP "``max_noncelen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_NONCELEN\s0\fR) <unsigned integer>" 4 +.IX Item "max_noncelen (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>" +.ie n .IP """max_perslen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_PERSLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``max_perslen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_PERSLEN\s0\fR) <unsigned integer>" 4 +.IX Item "max_perslen (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>" +.ie n .IP """max_adinlen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_ADINLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``max_adinlen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_ADINLEN\s0\fR) <unsigned integer>" 4 +.IX Item "max_adinlen (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>" +.ie n .IP """reseed_counter"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_COUNTER\s0\fR) <unsigned integer>" 4 +.el .IP "``reseed_counter'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_COUNTER\s0\fR) <unsigned integer>" 4 +.IX Item "reseed_counter (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>" +.ie n .IP """properties"" (\fB\s-1OSSL_DRBG_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_DRBG_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_DRBG_PARAM_PROPERTIES) <UTF8 string>" +.ie n .IP """mac"" (\fB\s-1OSSL_DRBG_PARAM_MAC\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``mac'' (\fB\s-1OSSL_DRBG_PARAM_MAC\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "mac (OSSL_DRBG_PARAM_MAC) <UTF8 string>" +.ie n .IP """digest"" (\fB\s-1OSSL_DRBG_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_DRBG_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_DRBG_PARAM_DIGEST) <UTF8 string>" +.PD +These parameters work as described in \*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_RAND\s0\fR\|(3). +.SH "NOTES" +.IX Header "NOTES" +A context for \s-1HMAC DRBG\s0 can be obtained by calling: +.PP +.Vb 2 +\& EVP_RAND *rand = EVP_RAND_fetch(NULL, "HMAC\-DRBG", NULL); +\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand); +.Ve +.SH "EXAMPLES" +.IX Header "EXAMPLES" +.Vb 5 +\& EVP_RAND *rand; +\& EVP_RAND_CTX *rctx; +\& unsigned char bytes[100]; +\& OSSL_PARAM params[3], *p = params; +\& unsigned int strength = 128; +\& +\& rand = EVP_RAND_fetch(NULL, "HMAC\-DRBG", NULL); +\& rctx = EVP_RAND_CTX_new(rand, NULL); +\& EVP_RAND_free(rand); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_MAC, SN_hmac, 0); +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_DIGEST, SN_sha256, 0); +\& *p = OSSL_PARAM_construct_end(); +\& EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params); +\& +\& EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0); +\& +\& EVP_RAND_CTX_free(rctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1NIST SP 800\-90A\s0 and \s-1SP 800\-90B\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_RAND\s0\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_RAND\s0\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_RAND-SEED-SRC.7 b/secure/lib/libcrypto/man/man7/EVP_RAND-SEED-SRC.7 new file mode 100644 index 000000000000..d5172b6432ff --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_RAND-SEED-SRC.7 @@ -0,0 +1,217 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_RAND-SEED-SRC 7ossl" +.TH EVP_RAND-SEED-SRC 7ossl "2023-09-19" "3.0.11" "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_RAND\-SEED\-SRC \- The randomness seed source EVP_RAND implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for deterministic random number generator seeding through the +\&\fB\s-1EVP_RAND\s0\fR \s-1API.\s0 +.PP +The seed sources used are specified at the time OpenSSL is configured for +building using the \fB\-\-with\-rand\-seed=\fR option. By default, operating system +randomness sources are used. +.SS "Identity" +.IX Subsection "Identity" +\&\*(L"SEED-SRC\*(R" is the name for this implementation; it can be used with the +\&\fBEVP_RAND_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.ie n .IP """state"" (\fB\s-1OSSL_RAND_PARAM_STATE\s0\fR) <integer>" 4 +.el .IP "``state'' (\fB\s-1OSSL_RAND_PARAM_STATE\s0\fR) <integer>" 4 +.IX Item "state (OSSL_RAND_PARAM_STATE) <integer>" +.PD 0 +.ie n .IP """strength"" (\fB\s-1OSSL_RAND_PARAM_STRENGTH\s0\fR) <unsigned integer>" 4 +.el .IP "``strength'' (\fB\s-1OSSL_RAND_PARAM_STRENGTH\s0\fR) <unsigned integer>" 4 +.IX Item "strength (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>" +.ie n .IP """max_request"" (\fB\s-1OSSL_RAND_PARAM_MAX_REQUEST\s0\fR) <unsigned integer>" 4 +.el .IP "``max_request'' (\fB\s-1OSSL_RAND_PARAM_MAX_REQUEST\s0\fR) <unsigned integer>" 4 +.IX Item "max_request (OSSL_RAND_PARAM_MAX_REQUEST) <unsigned integer>" +.PD +These parameters work as described in \*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_RAND\s0\fR\|(3). +.SH "NOTES" +.IX Header "NOTES" +A context for the seed source can be obtained by calling: +.PP +.Vb 2 +\& EVP_RAND *rand = EVP_RAND_fetch(NULL, "SEED\-SRC", NULL); +\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand); +.Ve +.SH "EXAMPLES" +.IX Header "EXAMPLES" +.Vb 5 +\& EVP_RAND *rand; +\& EVP_RAND_CTX *seed, *rctx; +\& unsigned char bytes[100]; +\& OSSL_PARAM params[2], *p = params; +\& unsigned int strength = 128; +\& +\& /* Create a seed source */ +\& rand = EVP_RAND_fetch(NULL, "SEED\-SRC", NULL); +\& seed = EVP_RAND_CTX_new(rand, NULL); +\& EVP_RAND_free(rand); +\& +\& /* Feed this into a DRBG */ +\& rand = EVP_RAND_fetch(NULL, "CTR\-DRBG", NULL); +\& rctx = EVP_RAND_CTX_new(rand, seed); +\& EVP_RAND_free(rand); +\& +\& /* Configure the DRBG */ +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_CIPHER, +\& SN_aes_256_ctr, 0); +\& *p = OSSL_PARAM_construct_end(); +\& EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params); +\& +\& EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0); +\& +\& EVP_RAND_CTX_free(rctx); +\& EVP_RAND_CTX_free(seed); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_RAND\s0\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_RAND\s0\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_RAND-TEST-RAND.7 b/secure/lib/libcrypto/man/man7/EVP_RAND-TEST-RAND.7 new file mode 100644 index 000000000000..539ab5faafd9 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_RAND-TEST-RAND.7 @@ -0,0 +1,253 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_RAND-TEST-RAND 7ossl" +.TH EVP_RAND-TEST-RAND 7ossl "2023-09-19" "3.0.11" "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_RAND\-TEST\-RAND \- The test EVP_RAND implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for a test generator through the \fB\s-1EVP_RAND\s0\fR \s-1API.\s0 This generator is +for test purposes only, it does not generate random numbers. +.SS "Identity" +.IX Subsection "Identity" +\&\*(L"TEST-RAND\*(R" is the name for this implementation; it can be used with the +\&\fBEVP_RAND_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.ie n .IP """state"" (\fB\s-1OSSL_RAND_PARAM_STATE\s0\fR) <integer>" 4 +.el .IP "``state'' (\fB\s-1OSSL_RAND_PARAM_STATE\s0\fR) <integer>" 4 +.IX Item "state (OSSL_RAND_PARAM_STATE) <integer>" +These parameter works as described in \*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_RAND\s0\fR\|(3). +.ie n .IP """strength"" (\fB\s-1OSSL_RAND_PARAM_STRENGTH\s0\fR) <unsigned integer>" 4 +.el .IP "``strength'' (\fB\s-1OSSL_RAND_PARAM_STRENGTH\s0\fR) <unsigned integer>" 4 +.IX Item "strength (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>" +.PD 0 +.ie n .IP """reseed_requests"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_REQUESTS\s0\fR) <unsigned integer>" 4 +.el .IP "``reseed_requests'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_REQUESTS\s0\fR) <unsigned integer>" 4 +.IX Item "reseed_requests (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>" +.ie n .IP """reseed_time_interval"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL\s0\fR) <integer>" 4 +.el .IP "``reseed_time_interval'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL\s0\fR) <integer>" 4 +.IX Item "reseed_time_interval (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <integer>" +.ie n .IP """max_request"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_REQUESTS\s0\fR) <unsigned integer>" 4 +.el .IP "``max_request'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_REQUESTS\s0\fR) <unsigned integer>" 4 +.IX Item "max_request (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>" +.ie n .IP """min_entropylen"" (\fB\s-1OSSL_DRBG_PARAM_MIN_ENTROPYLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``min_entropylen'' (\fB\s-1OSSL_DRBG_PARAM_MIN_ENTROPYLEN\s0\fR) <unsigned integer>" 4 +.IX Item "min_entropylen (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>" +.ie n .IP """max_entropylen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_ENTROPYLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``max_entropylen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_ENTROPYLEN\s0\fR) <unsigned integer>" 4 +.IX Item "max_entropylen (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>" +.ie n .IP """min_noncelen"" (\fB\s-1OSSL_DRBG_PARAM_MIN_NONCELEN\s0\fR) <unsigned integer>" 4 +.el .IP "``min_noncelen'' (\fB\s-1OSSL_DRBG_PARAM_MIN_NONCELEN\s0\fR) <unsigned integer>" 4 +.IX Item "min_noncelen (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>" +.ie n .IP """max_noncelen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_NONCELEN\s0\fR) <unsigned integer>" 4 +.el .IP "``max_noncelen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_NONCELEN\s0\fR) <unsigned integer>" 4 +.IX Item "max_noncelen (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>" +.ie n .IP """max_perslen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_PERSLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``max_perslen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_PERSLEN\s0\fR) <unsigned integer>" 4 +.IX Item "max_perslen (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>" +.ie n .IP """max_adinlen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_ADINLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``max_adinlen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_ADINLEN\s0\fR) <unsigned integer>" 4 +.IX Item "max_adinlen (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>" +.ie n .IP """reseed_counter"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_COUNTER\s0\fR) <unsigned integer>" 4 +.el .IP "``reseed_counter'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_COUNTER\s0\fR) <unsigned integer>" 4 +.IX Item "reseed_counter (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>" +.PD +These parameters work as described in \*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_RAND\s0\fR\|(3), except that +they can all be set as well as read. +.ie n .IP """test_entropy"" (\fB\s-1OSSL_RAND_PARAM_TEST_ENTROPY\s0\fR) <octet string>" 4 +.el .IP "``test_entropy'' (\fB\s-1OSSL_RAND_PARAM_TEST_ENTROPY\s0\fR) <octet string>" 4 +.IX Item "test_entropy (OSSL_RAND_PARAM_TEST_ENTROPY) <octet string>" +Sets the bytes returned when the test generator is sent an entropy request. +The current position is remembered across generate calls. +If there are insufficient data present to satisfy a call, an error is returned. +.ie n .IP """test_nonce"" (\fB\s-1OSSL_RAND_PARAM_TEST_NONCE\s0\fR) <octet string>" 4 +.el .IP "``test_nonce'' (\fB\s-1OSSL_RAND_PARAM_TEST_NONCE\s0\fR) <octet string>" 4 +.IX Item "test_nonce (OSSL_RAND_PARAM_TEST_NONCE) <octet string>" +Sets the bytes returned when the test generator is sent a nonce request. +Each nonce request will return all of the bytes. +.SH "NOTES" +.IX Header "NOTES" +A context for a test generator can be obtained by calling: +.PP +.Vb 2 +\& EVP_RAND *rand = EVP_RAND_fetch(NULL, "TEST\-RAND", NULL); +\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand); +.Ve +.SH "EXAMPLES" +.IX Header "EXAMPLES" +.Vb 7 +\& EVP_RAND *rand; +\& EVP_RAND_CTX *rctx; +\& unsigned char bytes[100]; +\& OSSL_PARAM params[4], *p = params; +\& unsigned char entropy[1000] = { ... }; +\& unsigned char nonce[20] = { ... }; +\& unsigned int strength = 48; +\& +\& rand = EVP_RAND_fetch(NULL, "TEST\-RAND", NULL); +\& rctx = EVP_RAND_CTX_new(rand, NULL); +\& EVP_RAND_free(rand); +\& +\& *p++ = OSSL_PARAM_construct_uint(OSSL_RAND_PARAM_STRENGTH, &strength); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_RAND_PARAM_TEST_ENTROPY, +\& entropy, sizeof(entropy)); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_RAND_PARAM_TEST_NONCE, +\& nonce, sizeof(nonce)); +\& *p = OSSL_PARAM_construct_end(); +\& EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params); +\& +\& EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0); +\& +\& EVP_RAND_CTX_free(rctx); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBEVP_RAND\s0\fR\|(3), +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \s-1\fBEVP_RAND\s0\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/RAND_DRBG.7 b/secure/lib/libcrypto/man/man7/EVP_RAND.7 index 21a9a8c69327..698f4008d804 100644 --- a/secure/lib/libcrypto/man/man7/RAND_DRBG.7 +++ b/secure/lib/libcrypto/man/man7/EVP_RAND.7 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .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 \{\ @@ -132,36 +130,37 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "RAND_DRBG 7" -.TH RAND_DRBG 7 "2022-06-21" "1.1.1p" "OpenSSL" +.IX Title "EVP_RAND 7ossl" +.TH EVP_RAND 7ossl "2023-09-19" "3.0.11" "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" -RAND_DRBG \- the deterministic random bit generator +EVP_RAND \- the random bit generator .SH "SYNOPSIS" .IX Header "SYNOPSIS" -.Vb 1 -\& #include <openssl/rand_drbg.h> +.Vb 2 +\& #include <openssl/evp.h> +\& #include <rand.h> .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" -The default OpenSSL \s-1RAND\s0 method is based on the \s-1RAND_DRBG\s0 class, -which implements a deterministic random bit generator (\s-1DRBG\s0). -A \s-1DRBG\s0 is a certain type of cryptographically-secure pseudo-random -number generator (\s-1CSPRNG\s0), which is described in -[\s-1NIST SP 800\-90A\s0 Rev. 1]. +The default OpenSSL \s-1RAND\s0 method is based on the \s-1EVP_RAND\s0 classes to provide +non-deterministic inputs to other cryptographic algorithms. .PP While the \s-1RAND API\s0 is the 'frontend' which is intended to be used by -application developers for obtaining random bytes, the \s-1RAND_DRBG API\s0 +application developers for obtaining random bytes, the \s-1EVP_RAND API\s0 serves as the 'backend', connecting the former with the operating -systems's entropy sources and providing access to the \s-1DRBG\s0's -configuration parameters. +systems's entropy sources and providing access to deterministic random +bit generators (\s-1DRBG\s0) and their configuration parameters. +A \s-1DRBG\s0 is a certain type of cryptographically-secure pseudo-random +number generator (\s-1CSPRNG\s0), which is described in +[\s-1NIST SP 800\-90A\s0 Rev. 1]. .SS "Disclaimer" .IX Subsection "Disclaimer" Unless you have very specific requirements for your random generator, -it is in general not necessary to utilize the \s-1RAND_DRBG API\s0 directly. +it is in general not necessary to utilize the \s-1EVP_RAND API\s0 directly. The usual way to obtain random bytes is to use \fBRAND_bytes\fR\|(3) or \&\fBRAND_priv_bytes\fR\|(3), see also \s-1\fBRAND\s0\fR\|(7). .SS "Typical Use Cases" @@ -175,31 +174,36 @@ better scalability in multithreaded applications (because they don't need to be locked). .IP "\(bu" 2 You need to integrate a previously unsupported entropy source. +Refer to \fBprovider\-rand\fR\|(7) for the implementation details to support adding +randomness sources to \s-1EVP_RAND.\s0 .IP "\(bu" 2 You need to change the default settings of the standard OpenSSL \s-1RAND\s0 implementation to meet specific requirements. -.SH "CHAINING" -.IX Header "CHAINING" -A \s-1DRBG\s0 instance can be used as the entropy source of another \s-1DRBG\s0 instance, -provided it has itself access to a valid entropy source. -The \s-1DRBG\s0 instance which acts as entropy source is called the \fIparent\fR \s-1DRBG,\s0 -the other instance the \fIchild\fR \s-1DRBG.\s0 +.SH "EVP_RAND CHAINING" +.IX Header "EVP_RAND CHAINING" +An \s-1EVP_RAND\s0 instance can be used as the entropy source of another +\&\s-1EVP_RAND\s0 instance, provided it has itself access to a valid entropy source. +The \s-1EVP_RAND\s0 instance which acts as entropy source is called the \fIparent\fR, +the other instance the \fIchild\fR. Typically, the child will be a \s-1DRBG\s0 because +it does not make sense for the child to be an entropy source. .PP -This is called chaining. A chained \s-1DRBG\s0 instance is created by passing -a pointer to the parent \s-1DRBG\s0 as argument to the \fBRAND_DRBG_new()\fR call. +This is called chaining. A chained \s-1EVP_RAND\s0 instance is created by passing +a pointer to the parent \s-1EVP_RAND_CTX\s0 as argument to the \fBEVP_RAND_CTX_new()\fR call. It is possible to create chains of more than two \s-1DRBG\s0 in a row. +It is also possible to use any \s-1EVP_RAND_CTX\s0 class as the parent, however, only +a live entropy source may ignore and not use its parent. .SH "THE THREE SHARED DRBG INSTANCES" .IX Header "THE THREE SHARED DRBG INSTANCES" Currently, there are three shared \s-1DRBG\s0 instances, -the <master>, <public>, and <private> \s-1DRBG.\s0 -While the <master> \s-1DRBG\s0 is a single global instance, the <public> and <private> +the <primary>, <public>, and <private> \s-1DRBG.\s0 +While the <primary> \s-1DRBG\s0 is a single global instance, the <public> and <private> \&\s-1DRBG\s0 are created per thread and accessed through thread-local storage. .PP By default, the functions \fBRAND_bytes\fR\|(3) and \fBRAND_priv_bytes\fR\|(3) use the thread-local <public> and <private> \s-1DRBG\s0 instance, respectively. -.SS "The <master> \s-1DRBG\s0 instance" -.IX Subsection "The <master> DRBG instance" -The <master> \s-1DRBG\s0 is not used directly by the application, only for reseeding +.SS "The <primary> \s-1DRBG\s0 instance" +.IX Subsection "The <primary> DRBG instance" +The <primary> \s-1DRBG\s0 is not used directly by the application, only for reseeding the two other two \s-1DRBG\s0 instances. It reseeds itself by obtaining randomness either from os entropy sources or by consuming randomness which was added previously by \fBRAND_add\fR\|(3). @@ -211,18 +215,16 @@ This instance is used per default by \fBRAND_bytes\fR\|(3). This instance is used per default by \fBRAND_priv_bytes\fR\|(3) .SH "LOCKING" .IX Header "LOCKING" -The <master> \s-1DRBG\s0 is intended to be accessed concurrently for reseeding +The <primary> \s-1DRBG\s0 is intended to be accessed concurrently for reseeding by its child \s-1DRBG\s0 instances. The necessary locking is done internally. -It is \fInot\fR thread-safe to access the <master> \s-1DRBG\s0 directly via the -\&\s-1RAND_DRBG\s0 interface. +It is \fInot\fR thread-safe to access the <primary> \s-1DRBG\s0 directly via the +\&\s-1EVP_RAND\s0 interface. The <public> and <private> \s-1DRBG\s0 are thread-local, i.e. there is an instance of each per thread. So they can safely be accessed without -locking via the \s-1RAND_DRBG\s0 interface. +locking via the \s-1EVP_RAND\s0 interface. .PP Pointers to these \s-1DRBG\s0 instances can be obtained using -\&\fBRAND_DRBG_get0_master()\fR, -\&\fBRAND_DRBG_get0_public()\fR, and -\&\fBRAND_DRBG_get0_private()\fR, respectively. +\&\fBRAND_get0_primary()\fR, \fBRAND_get0_public()\fR and \fBRAND_get0_private()\fR, respectively. Note that it is not allowed to store a pointer to one of the thread-local \&\s-1DRBG\s0 instances in a variable or other memory location where it will be accessed and used by multiple threads. @@ -231,9 +233,9 @@ All other \s-1DRBG\s0 instances created by an application don't support locking, because they are intended to be used by a single thread. Instead of accessing a single \s-1DRBG\s0 instance concurrently from different threads, it is recommended to instantiate a separate \s-1DRBG\s0 instance per -thread. Using the <master> \s-1DRBG\s0 as entropy source for multiple \s-1DRBG\s0 +thread. Using the <primary> \s-1DRBG\s0 as entropy source for multiple \s-1DRBG\s0 instances on different threads is thread-safe, because the \s-1DRBG\s0 instance -will lock the <master> \s-1DRBG\s0 automatically for obtaining random input. +will lock the <primary> \s-1DRBG\s0 automatically for obtaining random input. .SH "THE OVERALL PICTURE" .IX Header "THE OVERALL PICTURE" The following picture gives an overview over how the \s-1DRBG\s0 instances work @@ -245,7 +247,7 @@ together and are being used. \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | \& v +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ -\& RAND_add() ==> <master> <\-| shared DRBG (with locking) | +\& RAND_add() ==> <primary> <\-| shared DRBG (with locking) | \& / \e +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& / \e +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& <public> <private> <\- | per\-thread DRBG instances | @@ -262,10 +264,9 @@ together and are being used. .PP The usual way to obtain random bytes is to call RAND_bytes(...) or RAND_priv_bytes(...). These calls are roughly equivalent to calling -RAND_DRBG_bytes(<public>, ...) and RAND_DRBG_bytes(<private>, ...), -respectively. The method \fBRAND_DRBG_bytes\fR\|(3) is a convenience method -wrapping the \fBRAND_DRBG_generate\fR\|(3) function, which serves the actual -request for random data. +EVP_RAND_generate(<public>, ...) and +EVP_RAND_generate(<private>, ...), +respectively. .SH "RESEEDING" .IX Header "RESEEDING" A \s-1DRBG\s0 instance seeds itself automatically, pulling random input from @@ -278,7 +279,7 @@ time using the \-\-with\-rand\-seed option. The following sections explain the reseeding process in more detail. .SS "Automatic Reseeding" .IX Subsection "Automatic Reseeding" -Before satisfying a generate request (\fBRAND_DRBG_generate\fR\|(3)), the \s-1DRBG\s0 +Before satisfying a generate request (\fBEVP_RAND_generate\fR\|(3)), the \s-1DRBG\s0 reseeds itself automatically, if one of the following conditions holds: .PP \&\- the \s-1DRBG\s0 was not instantiated (=seeded) yet or has been uninstantiated. @@ -301,51 +302,52 @@ from the error as soon as the entropy source is available again. .IX Subsection "Manual Reseeding" In addition to automatic reseeding, the caller can request an immediate reseeding of the \s-1DRBG\s0 with fresh entropy by setting the -\&\fIprediction resistance\fR parameter to 1 when calling \fBRAND_DRBG_generate\fR\|(3). +\&\fIprediction resistance\fR parameter to 1 when calling +\&\fBEVP_RAND_generate\fR\|(3). .PP The document [\s-1NIST SP 800\-90C\s0] describes prediction resistance requests in detail and imposes strict conditions on the entropy sources that are approved for providing prediction resistance. -Since the default \s-1DRBG\s0 implementation does not have access to such an approved -entropy source, a request for prediction resistance will currently always fail. -In other words, prediction resistance is currently not supported yet by the \s-1DRBG.\s0 +A request for prediction resistance can only be satisfied by pulling fresh +entropy from a live entropy source (section 5.5.2 of [\s-1NIST SP 800\-90C\s0]). +It is up to the user to ensure that a live entropy source is configured +and is being used. .PP For the three shared DRBGs (and only for these) there is another way to reseed them manually: If \fBRAND_add\fR\|(3) is called with a positive \fIrandomness\fR argument -(or \fBRAND_seed\fR\|(3)), then this will immediately reseed the <master> \s-1DRBG.\s0 +(or \fBRAND_seed\fR\|(3)), then this will immediately reseed the <primary> \s-1DRBG.\s0 The <public> and <private> \s-1DRBG\s0 will detect this on their next generate -call and reseed, pulling randomness from <master>. +call and reseed, pulling randomness from <primary>. .PP The last feature has been added to support the common practice used with previous OpenSSL versions to call \fBRAND_add()\fR before calling \fBRAND_bytes()\fR. -.SS "Entropy Input vs. Additional Data" -.IX Subsection "Entropy Input vs. Additional Data" +.SS "Entropy Input and Additional Data" +.IX Subsection "Entropy Input and Additional Data" The \s-1DRBG\s0 distinguishes two different types of random input: \fIentropy\fR, which comes from a trusted source, and \fIadditional input\fR', which can optionally be added by the user and is considered untrusted. It is possible to add \fIadditional input\fR not only during reseeding, but also for every generate request. -This is in fact done automatically by \fBRAND_DRBG_bytes\fR\|(3). .SS "Configuring the Random Seed Source" .IX Subsection "Configuring the Random Seed Source" In most cases OpenSSL will automatically choose a suitable seed source -for automatically seeding and reseeding its <master> \s-1DRBG.\s0 In some cases +for automatically seeding and reseeding its <primary> \s-1DRBG.\s0 In some cases however, it will be necessary to explicitly specify a seed source during configuration, using the \-\-with\-rand\-seed option. For more information, see the \s-1INSTALL\s0 instructions. There are also operating systems where no seed source is available and automatic reseeding is disabled by default. .PP -The following two sections describe the reseeding process of the master +The following two sections describe the reseeding process of the primary \&\s-1DRBG,\s0 depending on whether automatic reseeding is available or not. -.SS "Reseeding the master \s-1DRBG\s0 with automatic seeding enabled" -.IX Subsection "Reseeding the master DRBG with automatic seeding enabled" +.SS "Reseeding the primary \s-1DRBG\s0 with automatic seeding enabled" +.IX Subsection "Reseeding the primary DRBG with automatic seeding enabled" Calling \fBRAND_poll()\fR or \fBRAND_add()\fR is not necessary, because the \s-1DRBG\s0 pulls the necessary entropy from its source automatically. However, both calls are permitted, and do reseed the \s-1RNG.\s0 .PP \&\fBRAND_add()\fR can be used to add both kinds of random input, depending on the -value of the \fBrandomness\fR argument: +value of the \fIrandomness\fR argument: .IP "randomness == 0:" 4 .IX Item "randomness == 0:" The random bytes are mixed as additional input into the current state of @@ -362,8 +364,15 @@ security strength of the \s-1DRBG.\s0 Currently it defaults to 256 bits (32 byte It is possible to provide less randomness than required. In this case the missing randomness will be obtained by pulling random input from the trusted entropy sources. -.SS "Reseeding the master \s-1DRBG\s0 with automatic seeding disabled" -.IX Subsection "Reseeding the master DRBG with automatic seeding disabled" +.PP +\&\s-1NOTE:\s0 Manual reseeding is *not allowed* in \s-1FIPS\s0 mode, because +[\s-1NIST\s0 SP\-800\-90Ar1] mandates that entropy *shall not* be provided by +the consuming application for instantiation (Section 9.1) or +reseeding (Section 9.2). For that reason, the \fIrandomness\fR +argument is ignored and the random bytes provided by the \fBRAND_add\fR\|(3) and +\&\fBRAND_seed\fR\|(3) calls are treated as additional data. +.SS "Reseeding the primary \s-1DRBG\s0 with automatic seeding disabled" +.IX Subsection "Reseeding the primary DRBG with automatic seeding disabled" Calling \fBRAND_poll()\fR will always fail. .PP \&\fBRAND_add()\fR needs to be called for initial seeding and periodic reseeding. @@ -376,21 +385,15 @@ More precisely, the number of bytes needed for seeding depend on the \&\fIsecurity strength\fR of the \s-1DRBG,\s0 which is set to 256 by default. .SH "SEE ALSO" .IX Header "SEE ALSO" -\&\fBRAND_DRBG_bytes\fR\|(3), -\&\fBRAND_DRBG_generate\fR\|(3), -\&\fBRAND_DRBG_reseed\fR\|(3), -\&\fBRAND_DRBG_get0_master\fR\|(3), -\&\fBRAND_DRBG_get0_public\fR\|(3), -\&\fBRAND_DRBG_get0_private\fR\|(3), -\&\fBRAND_DRBG_set_reseed_interval\fR\|(3), -\&\fBRAND_DRBG_set_reseed_time_interval\fR\|(3), -\&\fBRAND_DRBG_set_reseed_defaults\fR\|(3), -\&\s-1\fBRAND\s0\fR\|(7), +\&\s-1\fBRAND\s0\fR\|(7), \s-1\fBEVP_RAND\s0\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_SIGNATURE-DSA.7 b/secure/lib/libcrypto/man/man7/EVP_SIGNATURE-DSA.7 new file mode 100644 index 000000000000..7d5b4b3ec782 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_SIGNATURE-DSA.7 @@ -0,0 +1,185 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_SIGNATURE-DSA 7ossl" +.TH EVP_SIGNATURE-DSA 7ossl "2023-09-19" "3.0.11" "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_SIGNATURE\-DSA +\&\- The EVP_PKEY DSA signature implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1DSA\s0 signatures. +See \s-1\fBEVP_PKEY\-DSA\s0\fR\|(7) for information related to \s-1DSA\s0 keys. +.SS "Signature Parameters" +.IX Subsection "Signature Parameters" +The following signature parameters can be set using \fBEVP_PKEY_CTX_set_params()\fR. +This may be called after \fBEVP_PKEY_sign_init()\fR or \fBEVP_PKEY_verify_init()\fR, +and before calling \fBEVP_PKEY_sign()\fR or \fBEVP_PKEY_verify()\fR. +.ie n .IP """digest"" (\fB\s-1OSSL_SIGNATURE_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_SIGNATURE_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_SIGNATURE_PARAM_DIGEST) <UTF8 string>" +.PD 0 +.ie n .IP """properties"" (\fB\s-1OSSL_SIGNATURE_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_SIGNATURE_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_SIGNATURE_PARAM_PROPERTIES) <UTF8 string>" +.PD +The settable parameters are described in \fBprovider\-signature\fR\|(7). +.PP +The following signature parameters can be retrieved using +\&\fBEVP_PKEY_CTX_get_params()\fR. +.ie n .IP """algorithm-id"" (\fB\s-1OSSL_SIGNATURE_PARAM_ALGORITHM_ID\s0\fR) <octet string>" 4 +.el .IP "``algorithm-id'' (\fB\s-1OSSL_SIGNATURE_PARAM_ALGORITHM_ID\s0\fR) <octet string>" 4 +.IX Item "algorithm-id (OSSL_SIGNATURE_PARAM_ALGORITHM_ID) <octet string>" +.PD 0 +.ie n .IP """digest"" (\fB\s-1OSSL_SIGNATURE_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_SIGNATURE_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_SIGNATURE_PARAM_DIGEST) <UTF8 string>" +.PD +The gettable parameters are described in \fBprovider\-signature\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_set_params\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify\fR\|(3), +\&\fBprovider\-signature\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 \*(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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_SIGNATURE-ECDSA.7 b/secure/lib/libcrypto/man/man7/EVP_SIGNATURE-ECDSA.7 new file mode 100644 index 000000000000..b7e8c1a7a1fc --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_SIGNATURE-ECDSA.7 @@ -0,0 +1,184 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_SIGNATURE-ECDSA 7ossl" +.TH EVP_SIGNATURE-ECDSA 7ossl "2023-09-19" "3.0.11" "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_SIGNATURE\-ECDSA \- The EVP_PKEY ECDSA signature implementation. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1ECDSA\s0 signatures. +See \s-1\fBEVP_PKEY\-EC\s0\fR\|(7) for information related to \s-1EC\s0 keys. +.SS "\s-1ECDSA\s0 Signature Parameters" +.IX Subsection "ECDSA Signature Parameters" +The following signature parameters can be set using \fBEVP_PKEY_CTX_set_params()\fR. +This may be called after \fBEVP_PKEY_sign_init()\fR or \fBEVP_PKEY_verify_init()\fR, +and before calling \fBEVP_PKEY_sign()\fR or \fBEVP_PKEY_verify()\fR. +.ie n .IP """digest"" (\fB\s-1OSSL_SIGNATURE_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_SIGNATURE_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_SIGNATURE_PARAM_DIGEST) <UTF8 string>" +.PD 0 +.ie n .IP """properties"" (\fB\s-1OSSL_SIGNATURE_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_SIGNATURE_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_SIGNATURE_PARAM_PROPERTIES) <UTF8 string>" +.PD +These parameters are described in \fBprovider\-signature\fR\|(7). +.PP +The following signature parameters can be retrieved using +\&\fBEVP_PKEY_CTX_get_params()\fR. +.ie n .IP """algorithm-id"" (\fB\s-1OSSL_SIGNATURE_PARAM_ALGORITHM_ID\s0\fR) <octet string>" 4 +.el .IP "``algorithm-id'' (\fB\s-1OSSL_SIGNATURE_PARAM_ALGORITHM_ID\s0\fR) <octet string>" 4 +.IX Item "algorithm-id (OSSL_SIGNATURE_PARAM_ALGORITHM_ID) <octet string>" +.PD 0 +.ie n .IP """digest"" (\fB\s-1OSSL_SIGNATURE_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_SIGNATURE_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_SIGNATURE_PARAM_DIGEST) <UTF8 string>" +.PD +The parameters are described in \fBprovider\-signature\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_set_params\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify\fR\|(3), +\&\fBprovider\-signature\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 \*(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>. diff --git a/secure/lib/libcrypto/man/man7/Ed25519.7 b/secure/lib/libcrypto/man/man7/EVP_SIGNATURE-ED25519.7 index e6ff23c293a8..237d5162589a 100644 --- a/secure/lib/libcrypto/man/man7/Ed25519.7 +++ b/secure/lib/libcrypto/man/man7/EVP_SIGNATURE-ED25519.7 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .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 \{\ @@ -132,24 +130,37 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "ED25519 7" -.TH ED25519 7 "2022-06-21" "1.1.1p" "OpenSSL" +.IX Title "EVP_SIGNATURE-ED25519 7ossl" +.TH EVP_SIGNATURE-ED25519 7ossl "2023-09-19" "3.0.11" "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" -Ed25519, Ed448 \&\- EVP_PKEY Ed25519 and Ed448 support +EVP_SIGNATURE\-ED25519, +EVP_SIGNATURE\-ED448, +Ed25519, +Ed448 +\&\- EVP_PKEY Ed25519 and Ed448 support .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \fBEd25519\fR and \fBEd448\fR \s-1EVP_PKEY\s0 implementation supports key generation, one-shot digest sign and digest verify using PureEdDSA and \fBEd25519\fR or \fBEd448\fR (see \s-1RFC8032\s0). It has associated private and public key formats compatible with \&\s-1RFC 8410.\s0 +.SS "\s-1ED25519\s0 and \s-1ED448\s0 Signature Parameters" +.IX Subsection "ED25519 and ED448 Signature Parameters" +No additional parameters can be set during one-shot signing or verification. +In particular, because PureEdDSA is used, a digest must \fB\s-1NOT\s0\fR be specified when +signing or verifying. +See \s-1\fBEVP_PKEY\-X25519\s0\fR\|(7) for information related to \fBX25519\fR and \fBX448\fR keys. .PP -No additional parameters can be set during key generation, one-shot signing or -verification. In particular, because PureEdDSA is used, a digest must \fB\s-1NOT\s0\fR be -specified when signing or verifying. +The following signature parameters can be retrieved using +\&\fBEVP_PKEY_CTX_get_params()\fR. +.ie n .IP """algorithm-id"" (\fB\s-1OSSL_SIGNATURE_PARAM_ALGORITHM_ID\s0\fR) <octet string>" 4 +.el .IP "``algorithm-id'' (\fB\s-1OSSL_SIGNATURE_PARAM_ALGORITHM_ID\s0\fR) <octet string>" 4 +.IX Item "algorithm-id (OSSL_SIGNATURE_PARAM_ALGORITHM_ID) <octet string>" +The parameters are described in \fBprovider\-signature\fR\|(7). .SH "NOTES" .IX Header "NOTES" The PureEdDSA algorithm does not support the streaming mechanism @@ -158,24 +169,12 @@ The message to sign or verify must be passed using the one-shot \&\fBEVP_DigestSign()\fR and \fBEVP_DigestVerify()\fR functions. .PP When calling \fBEVP_DigestSignInit()\fR or \fBEVP_DigestVerifyInit()\fR, the -digest \fBtype\fR parameter \fB\s-1MUST\s0\fR be set to \fB\s-1NULL\s0\fR. +digest \fItype\fR parameter \fB\s-1MUST\s0\fR be set to \s-1NULL.\s0 .PP Applications wishing to sign certificates (or other structures such as CRLs or certificate requests) using Ed25519 or Ed448 can either use \fBX509_sign()\fR or \fBX509_sign_ctx()\fR in the usual way. .PP -A context for the \fBEd25519\fR algorithm can be obtained by calling: -.PP -.Vb 1 -\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED25519, NULL); -.Ve -.PP -For the \fBEd448\fR algorithm a context can be obtained by calling: -.PP -.Vb 1 -\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED448, NULL); -.Ve -.PP Ed25519 or Ed448 private keys can be set directly using \&\fBEVP_PKEY_new_raw_private_key\fR\|(3) or loaded from a PKCS#8 private key file using \fBPEM_read_bio_PrivateKey\fR\|(3) (or similar function). Completely new keys @@ -186,36 +185,43 @@ Ed25519 or Ed448 public keys can be set directly using \&\fBEVP_PKEY_new_raw_public_key\fR\|(3) or loaded from a SubjectPublicKeyInfo structure in a \s-1PEM\s0 file using \fBPEM_read_bio_PUBKEY\fR\|(3) (or similar function). .PP -Ed25519 and Ed448 can be tested within \fBspeed\fR\|(1) application since version 1.1.1. +Ed25519 and Ed448 can be tested with the \fBopenssl\-speed\fR\|(1) application +since version 1.1.1. Valid algorithm names are \fBed25519\fR, \fBed448\fR and \fBeddsa\fR. If \fBeddsa\fR is specified, then both Ed25519 and Ed448 are benchmarked. .SH "EXAMPLES" .IX Header "EXAMPLES" -This example generates an \fB\s-1ED25519\s0\fR private key and writes it to standard -output in \s-1PEM\s0 format: +To sign a message using a \s-1ED25519\s0 or \s-1ED448\s0 key: .PP -.Vb 9 -\& #include <openssl/evp.h> -\& #include <openssl/pem.h> -\& ... -\& EVP_PKEY *pkey = NULL; -\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED25519, NULL); -\& EVP_PKEY_keygen_init(pctx); -\& EVP_PKEY_keygen(pctx, &pkey); -\& EVP_PKEY_CTX_free(pctx); -\& PEM_write_PrivateKey(stdout, pkey, NULL, NULL, 0, NULL, NULL); +.Vb 5 +\& void do_sign(EVP_PKEY *ed_key, unsigned char *msg, size_t msg_len) +\& { +\& size_t sig_len; +\& unsigned char *sig = NULL; +\& EVP_MD_CTX *md_ctx = EVP_MD_CTX_new(); +\& +\& EVP_DigestSignInit(md_ctx, NULL, NULL, NULL, ed_key); +\& /* Calculate the requires size for the signature by passing a NULL buffer */ +\& EVP_DigestSign(md_ctx, NULL, &sig_len, msg, msg_len); +\& sig = OPENSSL_zalloc(sig_len); +\& +\& EVP_DigestSign(md_ctx, sig, &sig_len, msg, msg_len); +\& ... +\& OPENSSL_free(sig); +\& EVP_MD_CTX_free(md_ctx); +\& } .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" -\&\fBEVP_PKEY_CTX_new\fR\|(3), -\&\fBEVP_PKEY_keygen\fR\|(3), +\&\s-1\fBEVP_PKEY\-X25519\s0\fR\|(7) +\&\fBprovider\-signature\fR\|(7), \&\fBEVP_DigestSignInit\fR\|(3), \&\fBEVP_DigestVerifyInit\fR\|(3), .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_SIGNATURE-HMAC.7 b/secure/lib/libcrypto/man/man7/EVP_SIGNATURE-HMAC.7 new file mode 100644 index 000000000000..8c8119943dff --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_SIGNATURE-HMAC.7 @@ -0,0 +1,181 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_SIGNATURE-HMAC 7ossl" +.TH EVP_SIGNATURE-HMAC 7ossl "2023-09-19" "3.0.11" "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_SIGNATURE\-HMAC, EVP_SIGNATURE\-Siphash, EVP_SIGNATURE\-Poly1305, +EVP_SIGNATURE\-CMAC +\&\- The legacy EVP_PKEY MAC signature implementations +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The algorithms described here have legacy support for creating MACs using +\&\fBEVP_DigestSignInit\fR\|(3) and related functions. This is not the preferred way of +creating MACs. Instead you should use the newer \fBEVP_MAC_init\fR\|(3) functions. +This mechanism is provided for backwards compatibility with older versions of +OpenSSL. +.PP +The same signature parameters can be set using \fBEVP_PKEY_CTX_set_params()\fR as can +be set via \fBEVP_MAC_CTX_set_params()\fR for the underlying \s-1EVP_MAC.\s0 See +\&\s-1\fBEVP_MAC\-HMAC\s0\fR\|(7), \fBEVP_MAC\-Siphash\fR\|(7), \fBEVP_MAC\-Poly1305\fR\|(7) and +\&\s-1\fBEVP_MAC\-CMAC\s0\fR\|(7) for details. +.PP +.Vb 3 +\& See L<EVP_PKEY\-HMAC(7)>, L<EVP_PKEY\-Siphash(7)>, L<EVP_PKEY\-Poly1305(7)> or +\& L<EVP_PKEY\-CMAC(7)> for details about parameters that are supported during the +\& creation of an EVP_PKEY. +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MAC_init\fR\|(3), +\&\fBEVP_DigestSignInit\fR\|(3), +\&\s-1\fBEVP_PKEY\-HMAC\s0\fR\|(7), +\&\fBEVP_PKEY\-Siphash\fR\|(7), +\&\fBEVP_PKEY\-Poly1305\fR\|(7), +\&\s-1\fBEVP_PKEY\-CMAC\s0\fR\|(7), +\&\s-1\fBEVP_MAC\-HMAC\s0\fR\|(7), +\&\fBEVP_MAC\-Siphash\fR\|(7), +\&\fBEVP_MAC\-Poly1305\fR\|(7), +\&\s-1\fBEVP_MAC\-CMAC\s0\fR\|(7), +\&\fBprovider\-signature\fR\|(7), +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020 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>. diff --git a/secure/lib/libcrypto/man/man7/EVP_SIGNATURE-RSA.7 b/secure/lib/libcrypto/man/man7/EVP_SIGNATURE-RSA.7 new file mode 100644 index 000000000000..25401e4167e9 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_SIGNATURE-RSA.7 @@ -0,0 +1,247 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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_SIGNATURE-RSA 7ossl" +.TH EVP_SIGNATURE-RSA 7ossl "2023-09-19" "3.0.11" "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_SIGNATURE\-RSA +\&\- The EVP_PKEY RSA signature implementation +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Support for computing \s-1RSA\s0 signatures. +See \s-1\fBEVP_PKEY\-RSA\s0\fR\|(7) for information related to \s-1RSA\s0 keys. +.SS "Signature Parameters" +.IX Subsection "Signature Parameters" +The following signature parameters can be set using \fBEVP_PKEY_CTX_set_params()\fR. +This may be called after \fBEVP_PKEY_sign_init()\fR or \fBEVP_PKEY_verify_init()\fR, +and before calling \fBEVP_PKEY_sign()\fR or \fBEVP_PKEY_verify()\fR. +.ie n .IP """digest"" (\fB\s-1OSSL_SIGNATURE_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_SIGNATURE_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_SIGNATURE_PARAM_DIGEST) <UTF8 string>" +.PD 0 +.ie n .IP """properties"" (\fB\s-1OSSL_SIGNATURE_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_SIGNATURE_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_SIGNATURE_PARAM_PROPERTIES) <UTF8 string>" +.PD +These common parameters are described in \fBprovider\-signature\fR\|(7). +.ie n .IP """pad-mode"" (\fB\s-1OSSL_SIGNATURE_PARAM_PAD_MODE\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``pad-mode'' (\fB\s-1OSSL_SIGNATURE_PARAM_PAD_MODE\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "pad-mode (OSSL_SIGNATURE_PARAM_PAD_MODE) <UTF8 string>" +The type of padding to be used. Its value can be one of the following: +.RS 4 +.ie n .IP """none"" (\fB\s-1OSSL_PKEY_RSA_PAD_MODE_NONE\s0\fR)" 4 +.el .IP "``none'' (\fB\s-1OSSL_PKEY_RSA_PAD_MODE_NONE\s0\fR)" 4 +.IX Item "none (OSSL_PKEY_RSA_PAD_MODE_NONE)" +.PD 0 +.ie n .IP """pkcs1"" (\fB\s-1OSSL_PKEY_RSA_PAD_MODE_PKCSV15\s0\fR)" 4 +.el .IP "``pkcs1'' (\fB\s-1OSSL_PKEY_RSA_PAD_MODE_PKCSV15\s0\fR)" 4 +.IX Item "pkcs1 (OSSL_PKEY_RSA_PAD_MODE_PKCSV15)" +.ie n .IP """x931"" (\fB\s-1OSSL_PKEY_RSA_PAD_MODE_X931\s0\fR)" 4 +.el .IP "``x931'' (\fB\s-1OSSL_PKEY_RSA_PAD_MODE_X931\s0\fR)" 4 +.IX Item "x931 (OSSL_PKEY_RSA_PAD_MODE_X931)" +.ie n .IP """pss"" (\fB\s-1OSSL_PKEY_RSA_PAD_MODE_PSS\s0\fR)" 4 +.el .IP "``pss'' (\fB\s-1OSSL_PKEY_RSA_PAD_MODE_PSS\s0\fR)" 4 +.IX Item "pss (OSSL_PKEY_RSA_PAD_MODE_PSS)" +.RE +.RS 4 +.RE +.ie n .IP """mgf1\-digest"" (\fB\s-1OSSL_SIGNATURE_PARAM_MGF1_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``mgf1\-digest'' (\fB\s-1OSSL_SIGNATURE_PARAM_MGF1_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "mgf1-digest (OSSL_SIGNATURE_PARAM_MGF1_DIGEST) <UTF8 string>" +.PD +The digest algorithm name to use for the maskGenAlgorithm used by \*(L"pss\*(R" mode. +.ie n .IP """mgf1\-properties"" (\fB\s-1OSSL_SIGNATURE_PARAM_MGF1_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``mgf1\-properties'' (\fB\s-1OSSL_SIGNATURE_PARAM_MGF1_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "mgf1-properties (OSSL_SIGNATURE_PARAM_MGF1_PROPERTIES) <UTF8 string>" +Sets the name of the property query associated with the \*(L"mgf1\-digest\*(R" algorithm. +\&\s-1NULL\s0 is used if this optional value is not set. +.ie n .IP """saltlen"" (\fB\s-1OSSL_SIGNATURE_PARAM_PSS_SALTLEN\s0\fR) <integer> or <\s-1UTF8\s0 string>" 4 +.el .IP "``saltlen'' (\fB\s-1OSSL_SIGNATURE_PARAM_PSS_SALTLEN\s0\fR) <integer> or <\s-1UTF8\s0 string>" 4 +.IX Item "saltlen (OSSL_SIGNATURE_PARAM_PSS_SALTLEN) <integer> or <UTF8 string>" +The \*(L"pss\*(R" mode minimum salt length. The value can either be an integer, +a string value representing a number or one of the following string values: +.RS 4 +.ie n .IP """digest"" (\fB\s-1OSSL_PKEY_RSA_PSS_SALT_LEN_DIGEST\s0\fR)" 4 +.el .IP "``digest'' (\fB\s-1OSSL_PKEY_RSA_PSS_SALT_LEN_DIGEST\s0\fR)" 4 +.IX Item "digest (OSSL_PKEY_RSA_PSS_SALT_LEN_DIGEST)" +Use the same length as the digest size. +.ie n .IP """max"" (\fB\s-1OSSL_PKEY_RSA_PSS_SALT_LEN_MAX\s0\fR)" 4 +.el .IP "``max'' (\fB\s-1OSSL_PKEY_RSA_PSS_SALT_LEN_MAX\s0\fR)" 4 +.IX Item "max (OSSL_PKEY_RSA_PSS_SALT_LEN_MAX)" +Use the maximum salt length. +.ie n .IP """auto"" (\fB\s-1OSSL_PKEY_RSA_PSS_SALT_LEN_AUTO\s0\fR)" 4 +.el .IP "``auto'' (\fB\s-1OSSL_PKEY_RSA_PSS_SALT_LEN_AUTO\s0\fR)" 4 +.IX Item "auto (OSSL_PKEY_RSA_PSS_SALT_LEN_AUTO)" +Auto detect the salt length. +.RE +.RS 4 +.RE +.PP +The following signature parameters can be retrieved using +\&\fBEVP_PKEY_CTX_get_params()\fR. +.ie n .IP """algorithm-id"" (\fB\s-1OSSL_SIGNATURE_PARAM_ALGORITHM_ID\s0\fR) <octet string>" 4 +.el .IP "``algorithm-id'' (\fB\s-1OSSL_SIGNATURE_PARAM_ALGORITHM_ID\s0\fR) <octet string>" 4 +.IX Item "algorithm-id (OSSL_SIGNATURE_PARAM_ALGORITHM_ID) <octet string>" +This common parameter is described in \fBprovider\-signature\fR\|(7). +.ie n .IP """digest"" (\fB\s-1OSSL_SIGNATURE_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_SIGNATURE_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_SIGNATURE_PARAM_DIGEST) <UTF8 string>" +.PD 0 +.ie n .IP """pad-mode"" (\fB\s-1OSSL_SIGNATURE_PARAM_PAD_MODE\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``pad-mode'' (\fB\s-1OSSL_SIGNATURE_PARAM_PAD_MODE\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "pad-mode (OSSL_SIGNATURE_PARAM_PAD_MODE) <UTF8 string>" +.ie n .IP """mgf1\-digest"" (\fB\s-1OSSL_SIGNATURE_PARAM_MGF1_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``mgf1\-digest'' (\fB\s-1OSSL_SIGNATURE_PARAM_MGF1_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "mgf1-digest (OSSL_SIGNATURE_PARAM_MGF1_DIGEST) <UTF8 string>" +.ie n .IP """saltlen"" (\fB\s-1OSSL_SIGNATURE_PARAM_PSS_SALTLEN\s0\fR) <integer> or <\s-1UTF8\s0 string>" 4 +.el .IP "``saltlen'' (\fB\s-1OSSL_SIGNATURE_PARAM_PSS_SALTLEN\s0\fR) <integer> or <\s-1UTF8\s0 string>" 4 +.IX Item "saltlen (OSSL_SIGNATURE_PARAM_PSS_SALTLEN) <integer> or <UTF8 string>" +.PD +These parameters are as described above. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_set_params\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify\fR\|(3), +\&\fBprovider\-signature\fR\|(7), +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2022 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>. diff --git a/secure/lib/libcrypto/man/man7/Makefile b/secure/lib/libcrypto/man/man7/Makefile index a9de694537fb..06def852520b 100644 --- a/secure/lib/libcrypto/man/man7/Makefile +++ b/secure/lib/libcrypto/man/man7/Makefile @@ -1,21 +1,164 @@ -# $FreeBSD$ -MAN+= Ed25519.7 +MAN+= EVP_ASYM_CIPHER-RSA.7 +MAN+= EVP_ASYM_CIPHER-SM2.7 +MAN+= EVP_CIPHER-AES.7 +MAN+= EVP_CIPHER-ARIA.7 +MAN+= EVP_CIPHER-BLOWFISH.7 +MAN+= EVP_CIPHER-CAMELLIA.7 +MAN+= EVP_CIPHER-CAST.7 +MAN+= EVP_CIPHER-CHACHA.7 +MAN+= EVP_CIPHER-DES.7 +MAN+= EVP_CIPHER-IDEA.7 +MAN+= EVP_CIPHER-NULL.7 +MAN+= EVP_CIPHER-RC2.7 +MAN+= EVP_CIPHER-RC4.7 +MAN+= EVP_CIPHER-RC5.7 +MAN+= EVP_CIPHER-SEED.7 +MAN+= EVP_CIPHER-SM4.7 +MAN+= EVP_KDF-HKDF.7 +MAN+= EVP_KDF-KB.7 +MAN+= EVP_KDF-KRB5KDF.7 +MAN+= EVP_KDF-PBKDF1.7 +MAN+= EVP_KDF-PBKDF2.7 +MAN+= EVP_KDF-PKCS12KDF.7 +MAN+= EVP_KDF-SCRYPT.7 +MAN+= EVP_KDF-SS.7 +MAN+= EVP_KDF-SSHKDF.7 +MAN+= EVP_KDF-TLS13_KDF.7 +MAN+= EVP_KDF-TLS1_PRF.7 +MAN+= EVP_KDF-X942-ASN1.7 +MAN+= EVP_KDF-X942-CONCAT.7 +MAN+= EVP_KDF-X963.7 +MAN+= EVP_KEM-RSA.7 +MAN+= EVP_KEYEXCH-DH.7 +MAN+= EVP_KEYEXCH-ECDH.7 +MAN+= EVP_KEYEXCH-X25519.7 +MAN+= EVP_MAC-BLAKE2.7 +MAN+= EVP_MAC-CMAC.7 +MAN+= EVP_MAC-GMAC.7 +MAN+= EVP_MAC-HMAC.7 +MAN+= EVP_MAC-KMAC.7 +MAN+= EVP_MAC-Poly1305.7 +MAN+= EVP_MAC-Siphash.7 +MAN+= EVP_MD-BLAKE2.7 +MAN+= EVP_MD-MD2.7 +MAN+= EVP_MD-MD4.7 +MAN+= EVP_MD-MD5-SHA1.7 +MAN+= EVP_MD-MD5.7 +MAN+= EVP_MD-MDC2.7 +MAN+= EVP_MD-NULL.7 +MAN+= EVP_MD-RIPEMD160.7 +MAN+= EVP_MD-SHA1.7 +MAN+= EVP_MD-SHA2.7 +MAN+= EVP_MD-SHA3.7 +MAN+= EVP_MD-SHAKE.7 +MAN+= EVP_MD-SM3.7 +MAN+= EVP_MD-WHIRLPOOL.7 +MAN+= EVP_MD-common.7 +MAN+= EVP_PKEY-DH.7 +MAN+= EVP_PKEY-DSA.7 +MAN+= EVP_PKEY-EC.7 +MAN+= EVP_PKEY-FFC.7 +MAN+= EVP_PKEY-HMAC.7 +MAN+= EVP_PKEY-RSA.7 +MAN+= EVP_PKEY-SM2.7 +MAN+= EVP_PKEY-X25519.7 +MAN+= EVP_RAND-CTR-DRBG.7 +MAN+= EVP_RAND-HASH-DRBG.7 +MAN+= EVP_RAND-HMAC-DRBG.7 +MAN+= EVP_RAND-SEED-SRC.7 +MAN+= EVP_RAND-TEST-RAND.7 +MAN+= EVP_RAND.7 +MAN+= EVP_SIGNATURE-DSA.7 +MAN+= EVP_SIGNATURE-ECDSA.7 +MAN+= EVP_SIGNATURE-ED25519.7 +MAN+= EVP_SIGNATURE-HMAC.7 +MAN+= EVP_SIGNATURE-RSA.7 +MAN+= OSSL_PROVIDER-FIPS.7 +MAN+= OSSL_PROVIDER-base.7 +MAN+= OSSL_PROVIDER-default.7 +MAN+= OSSL_PROVIDER-legacy.7 +MAN+= OSSL_PROVIDER-null.7 MAN+= RAND.7 -MAN+= RAND_DRBG.7 MAN+= RSA-PSS.7 -MAN+= SM2.7 MAN+= X25519.7 MAN+= bio.7 -# MAN+= crypto.7 +MAN+= crypto.7 MAN+= ct.7 MAN+= des_modes.7 MAN+= evp.7 +MAN+= fips_module.7 +MAN+= life_cycle-cipher.7 +MAN+= life_cycle-digest.7 +MAN+= life_cycle-kdf.7 +MAN+= life_cycle-mac.7 +MAN+= life_cycle-pkey.7 +MAN+= life_cycle-rand.7 +MAN+= migration_guide.7 +MAN+= openssl-core.h.7 +MAN+= openssl-core_dispatch.h.7 +MAN+= openssl-core_names.h.7 +MAN+= openssl-env.7 +MAN+= openssl-glossary.7 +MAN+= openssl-threads.7 +MAN+= openssl_user_macros.7 MAN+= ossl_store-file.7 MAN+= ossl_store.7 MAN+= passphrase-encoding.7 +MAN+= property.7 +MAN+= provider-asym_cipher.7 +MAN+= provider-base.7 +MAN+= provider-cipher.7 +MAN+= provider-decoder.7 +MAN+= provider-digest.7 +MAN+= provider-encoder.7 +MAN+= provider-kdf.7 +MAN+= provider-kem.7 +MAN+= provider-keyexch.7 +MAN+= provider-keymgmt.7 +MAN+= provider-mac.7 +MAN+= provider-object.7 +MAN+= provider-rand.7 +MAN+= provider-signature.7 +MAN+= provider-storemgmt.7 +MAN+= provider.7 MAN+= proxy-certificates.7 -MAN+= scrypt.7 MAN+= ssl.7 MAN+= x509.7 -MLINKS+= Ed25519.7 Ed448.7 +MLINKS+= EVP_KEYEXCH-X25519.7 EVP_KEYEXCH-X448.7 +MLINKS+= EVP_PKEY-HMAC.7 EVP_KEYMGMT-CMAC.7 +MLINKS+= EVP_PKEY-DH.7 EVP_KEYMGMT-DH.7 +MLINKS+= EVP_PKEY-DH.7 EVP_KEYMGMT-DHX.7 +MLINKS+= EVP_PKEY-DSA.7 EVP_KEYMGMT-DSA.7 +MLINKS+= EVP_PKEY-EC.7 EVP_KEYMGMT-EC.7 +MLINKS+= EVP_PKEY-X25519.7 EVP_KEYMGMT-ED25519.7 +MLINKS+= EVP_PKEY-X25519.7 EVP_KEYMGMT-ED448.7 +MLINKS+= EVP_PKEY-HMAC.7 EVP_KEYMGMT-HMAC.7 +MLINKS+= EVP_PKEY-HMAC.7 EVP_KEYMGMT-Poly1305.7 +MLINKS+= EVP_PKEY-RSA.7 EVP_KEYMGMT-RSA.7 +MLINKS+= EVP_PKEY-SM2.7 EVP_KEYMGMT-SM2.7 +MLINKS+= EVP_PKEY-HMAC.7 EVP_KEYMGMT-Siphash.7 +MLINKS+= EVP_PKEY-X25519.7 EVP_KEYMGMT-X25519.7 +MLINKS+= EVP_PKEY-X25519.7 EVP_KEYMGMT-X448.7 +MLINKS+= EVP_MAC-BLAKE2.7 EVP_MAC-BLAKE2BMAC.7 +MLINKS+= EVP_MAC-BLAKE2.7 EVP_MAC-BLAKE2SMAC.7 +MLINKS+= EVP_MAC-KMAC.7 EVP_MAC-KMAC128.7 +MLINKS+= EVP_MAC-KMAC.7 EVP_MAC-KMAC256.7 +MLINKS+= EVP_MD-SHAKE.7 EVP_MD-KECCAK-KMAC.7 +MLINKS+= EVP_PKEY-HMAC.7 EVP_PKEY-CMAC.7 +MLINKS+= EVP_PKEY-DH.7 EVP_PKEY-DHX.7 +MLINKS+= EVP_PKEY-X25519.7 EVP_PKEY-ED25519.7 +MLINKS+= EVP_PKEY-X25519.7 EVP_PKEY-ED448.7 +MLINKS+= EVP_PKEY-HMAC.7 EVP_PKEY-Poly1305.7 +MLINKS+= EVP_PKEY-HMAC.7 EVP_PKEY-Siphash.7 +MLINKS+= EVP_PKEY-X25519.7 EVP_PKEY-X448.7 +MLINKS+= EVP_SIGNATURE-HMAC.7 EVP_SIGNATURE-CMAC.7 +MLINKS+= EVP_SIGNATURE-ED25519.7 EVP_SIGNATURE-ED448.7 +MLINKS+= EVP_SIGNATURE-HMAC.7 EVP_SIGNATURE-Poly1305.7 +MLINKS+= EVP_SIGNATURE-HMAC.7 EVP_SIGNATURE-Siphash.7 +MLINKS+= EVP_SIGNATURE-ED25519.7 Ed25519.7 +MLINKS+= EVP_SIGNATURE-ED25519.7 Ed448.7 +MLINKS+= openssl_user_macros.7 OPENSSL_API_COMPAT.7 +MLINKS+= openssl_user_macros.7 OPENSSL_NO_DEPRECATED.7 +MLINKS+= EVP_PKEY-RSA.7 RSA.7 +MLINKS+= EVP_PKEY-SM2.7 SM2.7 MLINKS+= X25519.7 X448.7 diff --git a/secure/lib/libcrypto/man/man7/OSSL_PROVIDER-FIPS.7 b/secure/lib/libcrypto/man/man7/OSSL_PROVIDER-FIPS.7 new file mode 100644 index 000000000000..ba53edf486f7 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/OSSL_PROVIDER-FIPS.7 @@ -0,0 +1,580 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "OSSL_PROVIDER-FIPS 7ossl" +.TH OSSL_PROVIDER-FIPS 7ossl "2023-09-19" "3.0.11" "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" +OSSL_PROVIDER\-FIPS \- OpenSSL FIPS provider +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The OpenSSL \s-1FIPS\s0 provider is a special provider that conforms to the Federal +Information Processing Standards (\s-1FIPS\s0) specified in \s-1FIPS 140\-2.\s0 This 'module' +contains an approved set of cryptographic algorithms that is validated by an +accredited testing laboratory. +.SS "Properties" +.IX Subsection "Properties" +The implementations in this provider specifically have these properties +defined: +.ie n .IP """provider=fips""" 4 +.el .IP "``provider=fips''" 4 +.IX Item "provider=fips" +.PD 0 +.ie n .IP """fips=yes""" 4 +.el .IP "``fips=yes''" 4 +.IX Item "fips=yes" +.PD +.PP +It may be used in a property query string with fetching functions such as +\&\fBEVP_MD_fetch\fR\|(3) or \fBEVP_CIPHER_fetch\fR\|(3), as well as with other +functions that take a property query string, such as +\&\fBEVP_PKEY_CTX_new_from_name\fR\|(3). +.PP +It isn't mandatory to query for any of these properties, except to +make sure to get implementations of this provider and none other. +.PP +The \*(L"fips=yes\*(R" property can be use to make sure only \s-1FIPS\s0 approved +implementations are used for crypto operations. This may also include +other non-crypto support operations that are not in the \s-1FIPS\s0 provider, +such as asymmetric key encoders, +see \*(L"Asymmetric Key Management\*(R" in \fBOSSL_PROVIDER\-default\fR\|(7). +.SH "OPERATIONS AND ALGORITHMS" +.IX Header "OPERATIONS AND ALGORITHMS" +The OpenSSL \s-1FIPS\s0 provider supports these operations and algorithms: +.SS "Hashing Algorithms / Message Digests" +.IX Subsection "Hashing Algorithms / Message Digests" +.IP "\s-1SHA1,\s0 see \s-1\fBEVP_MD\-SHA1\s0\fR\|(7)" 4 +.IX Item "SHA1, see EVP_MD-SHA1" +.PD 0 +.IP "\s-1SHA2,\s0 see \s-1\fBEVP_MD\-SHA2\s0\fR\|(7)" 4 +.IX Item "SHA2, see EVP_MD-SHA2" +.IP "\s-1SHA3,\s0 see \s-1\fBEVP_MD\-SHA3\s0\fR\|(7)" 4 +.IX Item "SHA3, see EVP_MD-SHA3" +.IP "KECCAK-KMAC, see \s-1\fBEVP_MD\-KECCAK\-KMAC\s0\fR\|(7)" 4 +.IX Item "KECCAK-KMAC, see EVP_MD-KECCAK-KMAC" +.PD +.SS "Symmetric Ciphers" +.IX Subsection "Symmetric Ciphers" +.IP "\s-1AES,\s0 see \s-1\fBEVP_CIPHER\-AES\s0\fR\|(7)" 4 +.IX Item "AES, see EVP_CIPHER-AES" +.PD 0 +.IP "\s-1DES\-EDE3\s0 (TripleDES), see \s-1\fBEVP_CIPHER\-DES\s0\fR\|(7)" 4 +.IX Item "DES-EDE3 (TripleDES), see EVP_CIPHER-DES" +.PD +.SS "Message Authentication Code (\s-1MAC\s0)" +.IX Subsection "Message Authentication Code (MAC)" +.IP "\s-1CMAC,\s0 see \s-1\fBEVP_MAC\-CMAC\s0\fR\|(7)" 4 +.IX Item "CMAC, see EVP_MAC-CMAC" +.PD 0 +.IP "\s-1GMAC,\s0 see \s-1\fBEVP_MAC\-GMAC\s0\fR\|(7)" 4 +.IX Item "GMAC, see EVP_MAC-GMAC" +.IP "\s-1HMAC,\s0 see \s-1\fBEVP_MAC\-HMAC\s0\fR\|(7)" 4 +.IX Item "HMAC, see EVP_MAC-HMAC" +.IP "\s-1KMAC,\s0 see \s-1\fBEVP_MAC\-KMAC\s0\fR\|(7)" 4 +.IX Item "KMAC, see EVP_MAC-KMAC" +.PD +.SS "Key Derivation Function (\s-1KDF\s0)" +.IX Subsection "Key Derivation Function (KDF)" +.IP "\s-1HKDF,\s0 see \s-1\fBEVP_KDF\-HKDF\s0\fR\|(7)" 4 +.IX Item "HKDF, see EVP_KDF-HKDF" +.PD 0 +.IP "\s-1TLS13\-KDF,\s0 see \s-1\fBEVP_KDF\-TLS13_KDF\s0\fR\|(7)" 4 +.IX Item "TLS13-KDF, see EVP_KDF-TLS13_KDF" +.IP "\s-1SSKDF,\s0 see \s-1\fBEVP_KDF\-SS\s0\fR\|(7)" 4 +.IX Item "SSKDF, see EVP_KDF-SS" +.IP "\s-1PBKDF2,\s0 see \s-1\fBEVP_KDF\-PBKDF2\s0\fR\|(7)" 4 +.IX Item "PBKDF2, see EVP_KDF-PBKDF2" +.IP "\s-1SSHKDF,\s0 see \s-1\fBEVP_KDF\-SSHKDF\s0\fR\|(7)" 4 +.IX Item "SSHKDF, see EVP_KDF-SSHKDF" +.IP "\s-1TLS1\-PRF,\s0 see \s-1\fBEVP_KDF\-TLS1_PRF\s0\fR\|(7)" 4 +.IX Item "TLS1-PRF, see EVP_KDF-TLS1_PRF" +.IP "\s-1KBKDF,\s0 see \s-1\fBEVP_KDF\-KB\s0\fR\|(7)" 4 +.IX Item "KBKDF, see EVP_KDF-KB" +.IP "X942KDF\-ASN1, see \s-1\fBEVP_KDF\-X942\-ASN1\s0\fR\|(7)" 4 +.IX Item "X942KDF-ASN1, see EVP_KDF-X942-ASN1" +.IP "X942KDF\-CONCAT, see \s-1\fBEVP_KDF\-X942\-CONCAT\s0\fR\|(7)" 4 +.IX Item "X942KDF-CONCAT, see EVP_KDF-X942-CONCAT" +.IP "X963KDF, see \s-1\fBEVP_KDF\-X963\s0\fR\|(7)" 4 +.IX Item "X963KDF, see EVP_KDF-X963" +.PD +.SS "Key Exchange" +.IX Subsection "Key Exchange" +.IP "\s-1DH,\s0 see \s-1\fBEVP_KEYEXCH\-DH\s0\fR\|(7)" 4 +.IX Item "DH, see EVP_KEYEXCH-DH" +.PD 0 +.IP "\s-1ECDH,\s0 see \s-1\fBEVP_KEYEXCH\-ECDH\s0\fR\|(7)" 4 +.IX Item "ECDH, see EVP_KEYEXCH-ECDH" +.IP "X25519, see \s-1\fBEVP_KEYEXCH\-X25519\s0\fR\|(7)" 4 +.IX Item "X25519, see EVP_KEYEXCH-X25519" +.IP "X448, see \s-1\fBEVP_KEYEXCH\-X448\s0\fR\|(7)" 4 +.IX Item "X448, see EVP_KEYEXCH-X448" +.PD +.SS "Asymmetric Signature" +.IX Subsection "Asymmetric Signature" +.IP "\s-1RSA,\s0 see \s-1\fBEVP_SIGNATURE\-RSA\s0\fR\|(7)" 4 +.IX Item "RSA, see EVP_SIGNATURE-RSA" +.PD 0 +.IP "X25519, see \s-1\fBEVP_SIGNATURE\-ED25519\s0\fR\|(7)" 4 +.IX Item "X25519, see EVP_SIGNATURE-ED25519" +.IP "X448, see \s-1\fBEVP_SIGNATURE\-ED448\s0\fR\|(7)" 4 +.IX Item "X448, see EVP_SIGNATURE-ED448" +.IP "\s-1HMAC,\s0 see \s-1\fBEVP_SIGNATURE\-HMAC\s0\fR\|(7)" 4 +.IX Item "HMAC, see EVP_SIGNATURE-HMAC" +.IP "\s-1CMAC,\s0 see \s-1\fBEVP_SIGNATURE\-CMAC\s0\fR\|(7)" 4 +.IX Item "CMAC, see EVP_SIGNATURE-CMAC" +.PD +.SS "Asymmetric Cipher" +.IX Subsection "Asymmetric Cipher" +.IP "\s-1RSA,\s0 see \s-1\fBEVP_ASYM_CIPHER\-RSA\s0\fR\|(7)" 4 +.IX Item "RSA, see EVP_ASYM_CIPHER-RSA" +.SS "Asymmetric Key Encapsulation" +.IX Subsection "Asymmetric Key Encapsulation" +.PD 0 +.IP "\s-1RSA,\s0 see \s-1\fBEVP_KEM\-RSA\s0\fR\|(7)" 4 +.IX Item "RSA, see EVP_KEM-RSA" +.PD +.SS "Asymmetric Key Management" +.IX Subsection "Asymmetric Key Management" +.IP "\s-1DH,\s0 see \s-1\fBEVP_KEYMGMT\-DH\s0\fR\|(7)" 4 +.IX Item "DH, see EVP_KEYMGMT-DH" +.PD 0 +.IP "\s-1DHX,\s0 see \s-1\fBEVP_KEYMGMT\-DHX\s0\fR\|(7)" 4 +.IX Item "DHX, see EVP_KEYMGMT-DHX" +.IP "\s-1DSA,\s0 see \s-1\fBEVP_KEYMGMT\-DSA\s0\fR\|(7)" 4 +.IX Item "DSA, see EVP_KEYMGMT-DSA" +.IP "\s-1RSA,\s0 see \s-1\fBEVP_KEYMGMT\-RSA\s0\fR\|(7)" 4 +.IX Item "RSA, see EVP_KEYMGMT-RSA" +.IP "\s-1EC,\s0 see \s-1\fBEVP_KEYMGMT\-EC\s0\fR\|(7)" 4 +.IX Item "EC, see EVP_KEYMGMT-EC" +.IP "X25519, see \s-1\fBEVP_KEYMGMT\-X25519\s0\fR\|(7)" 4 +.IX Item "X25519, see EVP_KEYMGMT-X25519" +.IP "X448, see \s-1\fBEVP_KEYMGMT\-X448\s0\fR\|(7)" 4 +.IX Item "X448, see EVP_KEYMGMT-X448" +.PD +.SS "Random Number Generation" +.IX Subsection "Random Number Generation" +.IP "CTR-DRBG, see \s-1\fBEVP_RAND\-CTR\-DRBG\s0\fR\|(7)" 4 +.IX Item "CTR-DRBG, see EVP_RAND-CTR-DRBG" +.PD 0 +.IP "HASH-DRBG, see \s-1\fBEVP_RAND\-HASH\-DRBG\s0\fR\|(7)" 4 +.IX Item "HASH-DRBG, see EVP_RAND-HASH-DRBG" +.IP "HMAC-DRBG, see \s-1\fBEVP_RAND\-HMAC\-DRBG\s0\fR\|(7)" 4 +.IX Item "HMAC-DRBG, see EVP_RAND-HMAC-DRBG" +.IP "TEST-RAND, see \s-1\fBEVP_RAND\-TEST\-RAND\s0\fR\|(7)" 4 +.IX Item "TEST-RAND, see EVP_RAND-TEST-RAND" +.PD +TEST-RAND is an unapproved algorithm. +.SH "SELF TESTING" +.IX Header "SELF TESTING" +One of the requirements for the \s-1FIPS\s0 module is self testing. An optional callback +mechanism is available to return information to the user using +\&\fBOSSL_SELF_TEST_set_callback\fR\|(3). +.PP +The parameters passed to the callback are described in \fBOSSL_SELF_TEST_new\fR\|(3) +.PP +The OpenSSL \s-1FIPS\s0 module uses the following mechanism to provide information +about the self tests as they run. +This is useful for debugging if a self test is failing. +The callback also allows forcing any self test to fail, in order to check that +it operates correctly on failure. +Note that all self tests run even if a self test failure occurs. +.PP +The \s-1FIPS\s0 module passes the following type(s) to \fBOSSL_SELF_TEST_onbegin()\fR. +.ie n .IP """Module_Integrity"" (\fB\s-1OSSL_SELF_TEST_TYPE_MODULE_INTEGRITY\s0\fR)" 4 +.el .IP "``Module_Integrity'' (\fB\s-1OSSL_SELF_TEST_TYPE_MODULE_INTEGRITY\s0\fR)" 4 +.IX Item "Module_Integrity (OSSL_SELF_TEST_TYPE_MODULE_INTEGRITY)" +Uses \s-1HMAC SHA256\s0 on the module file to validate that the module has not been +modified. The integrity value is compared to a value written to a configuration +file during installation. +.ie n .IP """Install_Integrity"" (\fB\s-1OSSL_SELF_TEST_TYPE_INSTALL_INTEGRITY\s0\fR)" 4 +.el .IP "``Install_Integrity'' (\fB\s-1OSSL_SELF_TEST_TYPE_INSTALL_INTEGRITY\s0\fR)" 4 +.IX Item "Install_Integrity (OSSL_SELF_TEST_TYPE_INSTALL_INTEGRITY)" +Uses \s-1HMAC SHA256\s0 on a fixed string to validate that the installation process +has already been performed and the self test \s-1KATS\s0 have already been tested, +The integrity value is compared to a value written to a configuration +file after successfully running the self tests during installation. +.ie n .IP """KAT_Cipher"" (\fB\s-1OSSL_SELF_TEST_TYPE_KAT_CIPHER\s0\fR)" 4 +.el .IP "``KAT_Cipher'' (\fB\s-1OSSL_SELF_TEST_TYPE_KAT_CIPHER\s0\fR)" 4 +.IX Item "KAT_Cipher (OSSL_SELF_TEST_TYPE_KAT_CIPHER)" +Known answer test for a symmetric cipher. +.ie n .IP """KAT_AsymmetricCipher"" (\fB\s-1OSSL_SELF_TEST_TYPE_KAT_ASYM_CIPHER\s0\fR)" 4 +.el .IP "``KAT_AsymmetricCipher'' (\fB\s-1OSSL_SELF_TEST_TYPE_KAT_ASYM_CIPHER\s0\fR)" 4 +.IX Item "KAT_AsymmetricCipher (OSSL_SELF_TEST_TYPE_KAT_ASYM_CIPHER)" +Known answer test for a asymmetric cipher. +.ie n .IP """KAT_Digest"" (\fB\s-1OSSL_SELF_TEST_TYPE_KAT_DIGEST\s0\fR)" 4 +.el .IP "``KAT_Digest'' (\fB\s-1OSSL_SELF_TEST_TYPE_KAT_DIGEST\s0\fR)" 4 +.IX Item "KAT_Digest (OSSL_SELF_TEST_TYPE_KAT_DIGEST)" +Known answer test for a digest. +.ie n .IP """KAT_Signature"" (\fB\s-1OSSL_SELF_TEST_TYPE_KAT_SIGNATURE\s0\fR)" 4 +.el .IP "``KAT_Signature'' (\fB\s-1OSSL_SELF_TEST_TYPE_KAT_SIGNATURE\s0\fR)" 4 +.IX Item "KAT_Signature (OSSL_SELF_TEST_TYPE_KAT_SIGNATURE)" +Known answer test for a signature. +.ie n .IP """PCT_Signature"" (\fB\s-1OSSL_SELF_TEST_TYPE_PCT_SIGNATURE\s0\fR)" 4 +.el .IP "``PCT_Signature'' (\fB\s-1OSSL_SELF_TEST_TYPE_PCT_SIGNATURE\s0\fR)" 4 +.IX Item "PCT_Signature (OSSL_SELF_TEST_TYPE_PCT_SIGNATURE)" +Pairwise Consistency check for a signature. +.ie n .IP """\s-1KAT_KDF""\s0 (\fB\s-1OSSL_SELF_TEST_TYPE_KAT_KDF\s0\fR)" 4 +.el .IP "``\s-1KAT_KDF''\s0 (\fB\s-1OSSL_SELF_TEST_TYPE_KAT_KDF\s0\fR)" 4 +.IX Item "KAT_KDF (OSSL_SELF_TEST_TYPE_KAT_KDF)" +Known answer test for a key derivation function. +.ie n .IP """\s-1KAT_KA""\s0 (\fB\s-1OSSL_SELF_TEST_TYPE_KAT_KA\s0\fR)" 4 +.el .IP "``\s-1KAT_KA''\s0 (\fB\s-1OSSL_SELF_TEST_TYPE_KAT_KA\s0\fR)" 4 +.IX Item "KAT_KA (OSSL_SELF_TEST_TYPE_KAT_KA)" +Known answer test for key agreement. +.ie n .IP """\s-1DRBG""\s0 (\fB\s-1OSSL_SELF_TEST_TYPE_DRBG\s0\fR)" 4 +.el .IP "``\s-1DRBG''\s0 (\fB\s-1OSSL_SELF_TEST_TYPE_DRBG\s0\fR)" 4 +.IX Item "DRBG (OSSL_SELF_TEST_TYPE_DRBG)" +Known answer test for a Deterministic Random Bit Generator. +.ie n .IP """Conditional_PCT"" (\fB\s-1OSSL_SELF_TEST_TYPE_PCT\s0\fR)" 4 +.el .IP "``Conditional_PCT'' (\fB\s-1OSSL_SELF_TEST_TYPE_PCT\s0\fR)" 4 +.IX Item "Conditional_PCT (OSSL_SELF_TEST_TYPE_PCT)" +Conditional test that is run during the generation of key pairs. +.ie n .IP """Continuous_RNG_Test"" (\fB\s-1OSSL_SELF_TEST_TYPE_CRNG\s0\fR)" 4 +.el .IP "``Continuous_RNG_Test'' (\fB\s-1OSSL_SELF_TEST_TYPE_CRNG\s0\fR)" 4 +.IX Item "Continuous_RNG_Test (OSSL_SELF_TEST_TYPE_CRNG)" +Continuous random number generator test. +.PP +The \*(L"Module_Integrity\*(R" self test is always run at startup. +The \*(L"Install_Integrity\*(R" self test is used to check if the self tests have +already been run at installation time. If they have already run then the +self tests are not run on subsequent startups. +All other self test categories are run once at installation time, except for the +\&\*(L"Pairwise_Consistency_Test\*(R". +.PP +There is only one instance of the \*(L"Module_Integrity\*(R" and \*(L"Install_Integrity\*(R" +self tests. All other self tests may have multiple instances. +.PP +The \s-1FIPS\s0 module passes the following descriptions(s) to \fBOSSL_SELF_TEST_onbegin()\fR. +.ie n .IP """\s-1HMAC""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_INTEGRITY_HMAC\s0\fR)" 4 +.el .IP "``\s-1HMAC''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_INTEGRITY_HMAC\s0\fR)" 4 +.IX Item "HMAC (OSSL_SELF_TEST_DESC_INTEGRITY_HMAC)" +\&\*(L"Module_Integrity\*(R" and \*(L"Install_Integrity\*(R" use this. +.ie n .IP """\s-1RSA""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_PCT_RSA_PKCS1\s0\fR)" 4 +.el .IP "``\s-1RSA''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_PCT_RSA_PKCS1\s0\fR)" 4 +.IX Item "RSA (OSSL_SELF_TEST_DESC_PCT_RSA_PKCS1)" +.PD 0 +.ie n .IP """\s-1ECDSA""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_PCT_ECDSA\s0\fR)" 4 +.el .IP "``\s-1ECDSA''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_PCT_ECDSA\s0\fR)" 4 +.IX Item "ECDSA (OSSL_SELF_TEST_DESC_PCT_ECDSA)" +.ie n .IP """\s-1DSA""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_PCT_DSA\s0\fR)" 4 +.el .IP "``\s-1DSA''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_PCT_DSA\s0\fR)" 4 +.IX Item "DSA (OSSL_SELF_TEST_DESC_PCT_DSA)" +.PD +Key generation tests used with the \*(L"Pairwise_Consistency_Test\*(R" type. +.ie n .IP """RSA_Encrypt"" (\fB\s-1OSSL_SELF_TEST_DESC_ASYM_RSA_ENC\s0\fR)" 4 +.el .IP "``RSA_Encrypt'' (\fB\s-1OSSL_SELF_TEST_DESC_ASYM_RSA_ENC\s0\fR)" 4 +.IX Item "RSA_Encrypt (OSSL_SELF_TEST_DESC_ASYM_RSA_ENC)" +.PD 0 +.ie n .IP """RSA_Decrypt"" (\fB\s-1OSSL_SELF_TEST_DESC_ASYM_RSA_DEC\s0\fR)" 4 +.el .IP "``RSA_Decrypt'' (\fB\s-1OSSL_SELF_TEST_DESC_ASYM_RSA_DEC\s0\fR)" 4 +.IX Item "RSA_Decrypt (OSSL_SELF_TEST_DESC_ASYM_RSA_DEC)" +.PD +\&\*(L"KAT_AsymmetricCipher\*(R" uses this to indicate an encrypt or decrypt \s-1KAT.\s0 +.ie n .IP """\s-1AES_GCM""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_CIPHER_AES_GCM\s0\fR)" 4 +.el .IP "``\s-1AES_GCM''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_CIPHER_AES_GCM\s0\fR)" 4 +.IX Item "AES_GCM (OSSL_SELF_TEST_DESC_CIPHER_AES_GCM)" +.PD 0 +.ie n .IP """AES_ECB_Decrypt"" (\fB\s-1OSSL_SELF_TEST_DESC_CIPHER_AES_ECB\s0\fR)" 4 +.el .IP "``AES_ECB_Decrypt'' (\fB\s-1OSSL_SELF_TEST_DESC_CIPHER_AES_ECB\s0\fR)" 4 +.IX Item "AES_ECB_Decrypt (OSSL_SELF_TEST_DESC_CIPHER_AES_ECB)" +.ie n .IP """\s-1TDES""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_CIPHER_TDES\s0\fR)" 4 +.el .IP "``\s-1TDES''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_CIPHER_TDES\s0\fR)" 4 +.IX Item "TDES (OSSL_SELF_TEST_DESC_CIPHER_TDES)" +.PD +Symmetric cipher tests used with the \*(L"KAT_Cipher\*(R" type. +.ie n .IP """\s-1SHA1""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_MD_SHA1\s0\fR)" 4 +.el .IP "``\s-1SHA1''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_MD_SHA1\s0\fR)" 4 +.IX Item "SHA1 (OSSL_SELF_TEST_DESC_MD_SHA1)" +.PD 0 +.ie n .IP """\s-1SHA2""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_MD_SHA2\s0\fR)" 4 +.el .IP "``\s-1SHA2''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_MD_SHA2\s0\fR)" 4 +.IX Item "SHA2 (OSSL_SELF_TEST_DESC_MD_SHA2)" +.ie n .IP """\s-1SHA3""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_MD_SHA3\s0\fR)" 4 +.el .IP "``\s-1SHA3''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_MD_SHA3\s0\fR)" 4 +.IX Item "SHA3 (OSSL_SELF_TEST_DESC_MD_SHA3)" +.PD +Digest tests used with the \*(L"KAT_Digest\*(R" type. +.ie n .IP """\s-1DSA""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_SIGN_DSA\s0\fR)" 4 +.el .IP "``\s-1DSA''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_SIGN_DSA\s0\fR)" 4 +.IX Item "DSA (OSSL_SELF_TEST_DESC_SIGN_DSA)" +.PD 0 +.ie n .IP """\s-1RSA""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_SIGN_RSA\s0\fR)" 4 +.el .IP "``\s-1RSA''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_SIGN_RSA\s0\fR)" 4 +.IX Item "RSA (OSSL_SELF_TEST_DESC_SIGN_RSA)" +.ie n .IP """\s-1ECDSA""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_SIGN_ECDSA\s0\fR)" 4 +.el .IP "``\s-1ECDSA''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_SIGN_ECDSA\s0\fR)" 4 +.IX Item "ECDSA (OSSL_SELF_TEST_DESC_SIGN_ECDSA)" +.PD +Signature tests used with the \*(L"KAT_Signature\*(R" type. +.ie n .IP """\s-1ECDH""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_KA_ECDH\s0\fR)" 4 +.el .IP "``\s-1ECDH''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_KA_ECDH\s0\fR)" 4 +.IX Item "ECDH (OSSL_SELF_TEST_DESC_KA_ECDH)" +.PD 0 +.ie n .IP """\s-1DH""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_KA_DH\s0\fR)" 4 +.el .IP "``\s-1DH''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_KA_DH\s0\fR)" 4 +.IX Item "DH (OSSL_SELF_TEST_DESC_KA_DH)" +.PD +Key agreement tests used with the \*(L"\s-1KAT_KA\*(R"\s0 type. +.ie n .IP """\s-1HKDF""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_KDF_HKDF\s0\fR)" 4 +.el .IP "``\s-1HKDF''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_KDF_HKDF\s0\fR)" 4 +.IX Item "HKDF (OSSL_SELF_TEST_DESC_KDF_HKDF)" +.PD 0 +.ie n .IP """\s-1TLS13_KDF_EXTRACT""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_KDF_TLS13_EXTRACT\s0\fR)" 4 +.el .IP "``\s-1TLS13_KDF_EXTRACT''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_KDF_TLS13_EXTRACT\s0\fR)" 4 +.IX Item "TLS13_KDF_EXTRACT (OSSL_SELF_TEST_DESC_KDF_TLS13_EXTRACT)" +.ie n .IP """\s-1TLS13_KDF_EXPAND""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_KDF_TLS13_EXPAND\s0\fR)" 4 +.el .IP "``\s-1TLS13_KDF_EXPAND''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_KDF_TLS13_EXPAND\s0\fR)" 4 +.IX Item "TLS13_KDF_EXPAND (OSSL_SELF_TEST_DESC_KDF_TLS13_EXPAND)" +.ie n .IP """\s-1SSKDF""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_KDF_SSKDF\s0\fR)" 4 +.el .IP "``\s-1SSKDF''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_KDF_SSKDF\s0\fR)" 4 +.IX Item "SSKDF (OSSL_SELF_TEST_DESC_KDF_SSKDF)" +.ie n .IP """X963KDF"" (\fB\s-1OSSL_SELF_TEST_DESC_KDF_X963KDF\s0\fR)" 4 +.el .IP "``X963KDF'' (\fB\s-1OSSL_SELF_TEST_DESC_KDF_X963KDF\s0\fR)" 4 +.IX Item "X963KDF (OSSL_SELF_TEST_DESC_KDF_X963KDF)" +.ie n .IP """X942KDF"" (\fB\s-1OSSL_SELF_TEST_DESC_KDF_X942KDF\s0\fR)" 4 +.el .IP "``X942KDF'' (\fB\s-1OSSL_SELF_TEST_DESC_KDF_X942KDF\s0\fR)" 4 +.IX Item "X942KDF (OSSL_SELF_TEST_DESC_KDF_X942KDF)" +.ie n .IP """\s-1PBKDF2""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_KDF_PBKDF2\s0\fR)" 4 +.el .IP "``\s-1PBKDF2''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_KDF_PBKDF2\s0\fR)" 4 +.IX Item "PBKDF2 (OSSL_SELF_TEST_DESC_KDF_PBKDF2)" +.ie n .IP """\s-1SSHKDF""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_KDF_SSHKDF\s0\fR)" 4 +.el .IP "``\s-1SSHKDF''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_KDF_SSHKDF\s0\fR)" 4 +.IX Item "SSHKDF (OSSL_SELF_TEST_DESC_KDF_SSHKDF)" +.ie n .IP """\s-1TLS12_PRF""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_KDF_TLS12_PRF\s0\fR)" 4 +.el .IP "``\s-1TLS12_PRF''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_KDF_TLS12_PRF\s0\fR)" 4 +.IX Item "TLS12_PRF (OSSL_SELF_TEST_DESC_KDF_TLS12_PRF)" +.ie n .IP """\s-1KBKDF""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_KDF_KBKDF\s0\fR)" 4 +.el .IP "``\s-1KBKDF''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_KDF_KBKDF\s0\fR)" 4 +.IX Item "KBKDF (OSSL_SELF_TEST_DESC_KDF_KBKDF)" +.PD +Key Derivation Function tests used with the \*(L"\s-1KAT_KDF\*(R"\s0 type. +.ie n .IP """\s-1CTR""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_DRBG_CTR\s0\fR)" 4 +.el .IP "``\s-1CTR''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_DRBG_CTR\s0\fR)" 4 +.IX Item "CTR (OSSL_SELF_TEST_DESC_DRBG_CTR)" +.PD 0 +.ie n .IP """\s-1HASH""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_DRBG_HASH\s0\fR)" 4 +.el .IP "``\s-1HASH''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_DRBG_HASH\s0\fR)" 4 +.IX Item "HASH (OSSL_SELF_TEST_DESC_DRBG_HASH)" +.ie n .IP """\s-1HMAC""\s0 (\fB\s-1OSSL_SELF_TEST_DESC_DRBG_HMAC\s0\fR)" 4 +.el .IP "``\s-1HMAC''\s0 (\fB\s-1OSSL_SELF_TEST_DESC_DRBG_HMAC\s0\fR)" 4 +.IX Item "HMAC (OSSL_SELF_TEST_DESC_DRBG_HMAC)" +.PD +\&\s-1DRBG\s0 tests used with the \*(L"\s-1DRBG\*(R"\s0 type. +.Sp += item \*(L"\s-1RNG\*(R"\s0 (\fB\s-1OSSL_SELF_TEST_DESC_RNG\s0\fR) +.Sp +\&\*(L"Continuous_RNG_Test\*(R" uses this. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +A simple self test callback is shown below for illustrative purposes. +.PP +.Vb 1 +\& #include <openssl/self_test.h> +\& +\& static OSSL_CALLBACK self_test_cb; +\& +\& static int self_test_cb(const OSSL_PARAM params[], void *arg) +\& { +\& int ret = 0; +\& const OSSL_PARAM *p = NULL; +\& const char *phase = NULL, *type = NULL, *desc = NULL; +\& +\& p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_PHASE); +\& if (p == NULL || p\->data_type != OSSL_PARAM_UTF8_STRING) +\& goto err; +\& phase = (const char *)p\->data; +\& +\& p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_DESC); +\& if (p == NULL || p\->data_type != OSSL_PARAM_UTF8_STRING) +\& goto err; +\& desc = (const char *)p\->data; +\& +\& p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_TYPE); +\& if (p == NULL || p\->data_type != OSSL_PARAM_UTF8_STRING) +\& goto err; +\& type = (const char *)p\->data; +\& +\& /* Do some logging */ +\& if (strcmp(phase, OSSL_SELF_TEST_PHASE_START) == 0) +\& BIO_printf(bio_out, "%s : (%s) : ", desc, type); +\& if (strcmp(phase, OSSL_SELF_TEST_PHASE_PASS) == 0 +\& || strcmp(phase, OSSL_SELF_TEST_PHASE_FAIL) == 0) +\& BIO_printf(bio_out, "%s\en", phase); +\& +\& /* Corrupt the SHA1 self test during the \*(Aqcorrupt\*(Aq phase by returning 0 */ +\& if (strcmp(phase, OSSL_SELF_TEST_PHASE_CORRUPT) == 0 +\& && strcmp(desc, OSSL_SELF_TEST_DESC_MD_SHA1) == 0) { +\& BIO_printf(bio_out, "%s %s", phase, desc); +\& return 0; +\& } +\& ret = 1; +\& err: +\& return ret; +\& } +.Ve +.SH "NOTES" +.IX Header "NOTES" +Some released versions of OpenSSL do not include a validated +\&\s-1FIPS\s0 provider. To determine which versions have undergone +the validation process, please refer to the +OpenSSL Downloads page <https://www.openssl.org/source/>. If you +require FIPS-approved functionality, it is essential to build your \s-1FIPS\s0 +provider using one of the validated versions listed there. Normally, +it is possible to utilize a \s-1FIPS\s0 provider constructed from one of the +validated versions alongside \fIlibcrypto\fR and \fIlibssl\fR compiled from any +release within the same major release series. This flexibility enables +you to address bug fixes and CVEs that fall outside the \s-1FIPS\s0 boundary. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-fipsinstall\fR\|(1), +\&\fBfips_config\fR\|(5), +\&\fBOSSL_SELF_TEST_set_callback\fR\|(3), +\&\fBOSSL_SELF_TEST_new\fR\|(3), +\&\s-1\fBOSSL_PARAM\s0\fR\|(3), +\&\fBopenssl\-core.h\fR\|(7), +\&\fBopenssl\-core_dispatch.h\fR\|(7), +\&\fBprovider\fR\|(7), +<https://www.openssl.org/source/> +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2019\-2023 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>. diff --git a/secure/lib/libcrypto/man/man7/OSSL_PROVIDER-base.7 b/secure/lib/libcrypto/man/man7/OSSL_PROVIDER-base.7 new file mode 100644 index 000000000000..6127b4d31f6c --- /dev/null +++ b/secure/lib/libcrypto/man/man7/OSSL_PROVIDER-base.7 @@ -0,0 +1,223 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "OSSL_PROVIDER-BASE 7ossl" +.TH OSSL_PROVIDER-BASE 7ossl "2023-09-19" "3.0.11" "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" +OSSL_PROVIDER\-base \- OpenSSL base provider +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The OpenSSL base provider supplies the encoding for OpenSSL's +asymmetric cryptography. +.SS "Properties" +.IX Subsection "Properties" +The implementations in this provider specifically have this property +defined: +.ie n .IP """provider=base""" 4 +.el .IP "``provider=base''" 4 +.IX Item "provider=base" +.PP +It may be used in a property query string with fetching functions. +.PP +It isn't mandatory to query for this property, except to make sure to get +implementations of this provider and none other. +.ie n .IP """type=parameters""" 4 +.el .IP "``type=parameters''" 4 +.IX Item "type=parameters" +.PD 0 +.ie n .IP """type=private""" 4 +.el .IP "``type=private''" 4 +.IX Item "type=private" +.ie n .IP """type=public""" 4 +.el .IP "``type=public''" 4 +.IX Item "type=public" +.PD +.PP +These may be used in a property query string with fetching functions to select +which data are to be encoded. Either the private key material, the public +key material or the domain parameters can be selected. +.ie n .IP """format=der""" 4 +.el .IP "``format=der''" 4 +.IX Item "format=der" +.PD 0 +.ie n .IP """format=pem""" 4 +.el .IP "``format=pem''" 4 +.IX Item "format=pem" +.ie n .IP """format=text""" 4 +.el .IP "``format=text''" 4 +.IX Item "format=text" +.PD +.PP +These may be used in a property query string with fetching functions to select +the encoding output format. Either the \s-1DER, PEM\s0 and plaintext are +currently permitted. +.SH "OPERATIONS AND ALGORITHMS" +.IX Header "OPERATIONS AND ALGORITHMS" +The OpenSSL base provider supports these operations and algorithms: +.SS "Asymmetric Key Encoder" +.IX Subsection "Asymmetric Key Encoder" +In addition to \*(L"provider=base\*(R", some of these encoders define the +property \*(L"fips=yes\*(R", to allow them to be used together with the \s-1FIPS\s0 +provider. +.IP "\s-1RSA,\s0 see \s-1\fBOSSL_ENCODER\-RSA\s0\fR\|(7)" 4 +.IX Item "RSA, see OSSL_ENCODER-RSA" +.PD 0 +.IP "\s-1DH,\s0 see \s-1\fBOSSL_ENCODER\-DH\s0\fR\|(7)" 4 +.IX Item "DH, see OSSL_ENCODER-DH" +.IP "\s-1DSA,\s0 see \s-1\fBOSSL_ENCODER\-DSA\s0\fR\|(7)" 4 +.IX Item "DSA, see OSSL_ENCODER-DSA" +.IP "\s-1EC,\s0 see \s-1\fBOSSL_ENCODER\-EC\s0\fR\|(7)" 4 +.IX Item "EC, see OSSL_ENCODER-EC" +.IP "X25519, see \s-1\fBOSSL_ENCODER\-X25519\s0\fR\|(7)" 4 +.IX Item "X25519, see OSSL_ENCODER-X25519" +.IP "X448, see \s-1\fBOSSL_ENCODER\-X448\s0\fR\|(7)" 4 +.IX Item "X448, see OSSL_ENCODER-X448" +.PD +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_PROVIDER\-default\fR\|(7), \fBopenssl\-core.h\fR\|(7), +\&\fBopenssl\-core_dispatch.h\fR\|(7), \fBprovider\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020 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>. diff --git a/secure/lib/libcrypto/man/man7/OSSL_PROVIDER-default.7 b/secure/lib/libcrypto/man/man7/OSSL_PROVIDER-default.7 new file mode 100644 index 000000000000..58331313e4cd --- /dev/null +++ b/secure/lib/libcrypto/man/man7/OSSL_PROVIDER-default.7 @@ -0,0 +1,379 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "OSSL_PROVIDER-DEFAULT 7ossl" +.TH OSSL_PROVIDER-DEFAULT 7ossl "2023-09-19" "3.0.11" "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" +OSSL_PROVIDER\-default \- OpenSSL default provider +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The OpenSSL default provider supplies the majority of OpenSSL's diverse +algorithm implementations. If an application doesn't specify anything else +explicitly (e.g. in the application or via config), then this is the +provider that will be used as fallback: It is loaded automatically the +first time that an algorithm is fetched from a provider or a function +acting on providers is called and no other provider has been loaded yet. +.PP +If an attempt to load a provider has already been made (whether successful +or not) then the default provider won't be loaded automatically. Therefore +if the default provider is to be used in conjunction with other providers +then it must be loaded explicitly. Automatic loading of the default +provider only occurs a maximum of once; if the default provider is +explicitly unloaded then the default provider will not be automatically +loaded again. +.SS "Properties" +.IX Subsection "Properties" +The implementations in this provider specifically have this property +defined: +.ie n .IP """provider=default""" 4 +.el .IP "``provider=default''" 4 +.IX Item "provider=default" +.PP +It may be used in a property query string with fetching functions such as +\&\fBEVP_MD_fetch\fR\|(3) or \fBEVP_CIPHER_fetch\fR\|(3), as well as with other +functions that take a property query string, such as +\&\fBEVP_PKEY_CTX_new_from_name\fR\|(3). +.PP +It isn't mandatory to query for this property, except to make sure to get +implementations of this provider and none other. +.PP +Some implementations may define additional properties. Exact information is +listed below +.SH "OPERATIONS AND ALGORITHMS" +.IX Header "OPERATIONS AND ALGORITHMS" +The OpenSSL default provider supports these operations and algorithms: +.SS "Hashing Algorithms / Message Digests" +.IX Subsection "Hashing Algorithms / Message Digests" +.IP "\s-1SHA1,\s0 see \s-1\fBEVP_MD\-SHA1\s0\fR\|(7)" 4 +.IX Item "SHA1, see EVP_MD-SHA1" +.PD 0 +.IP "\s-1SHA2,\s0 see \s-1\fBEVP_MD\-SHA2\s0\fR\|(7)" 4 +.IX Item "SHA2, see EVP_MD-SHA2" +.IP "\s-1SHA3,\s0 see \s-1\fBEVP_MD\-SHA3\s0\fR\|(7)" 4 +.IX Item "SHA3, see EVP_MD-SHA3" +.IP "KECCAK-KMAC, see \s-1\fBEVP_MD\-KECCAK\-KMAC\s0\fR\|(7)" 4 +.IX Item "KECCAK-KMAC, see EVP_MD-KECCAK-KMAC" +.IP "\s-1SHAKE,\s0 see \s-1\fBEVP_MD\-SHAKE\s0\fR\|(7)" 4 +.IX Item "SHAKE, see EVP_MD-SHAKE" +.IP "\s-1BLAKE2,\s0 see \s-1\fBEVP_MD\-BLAKE2\s0\fR\|(7)" 4 +.IX Item "BLAKE2, see EVP_MD-BLAKE2" +.IP "\s-1SM3,\s0 see \s-1\fBEVP_MD\-SM3\s0\fR\|(7)" 4 +.IX Item "SM3, see EVP_MD-SM3" +.IP "\s-1MD5,\s0 see \s-1\fBEVP_MD\-MD5\s0\fR\|(7)" 4 +.IX Item "MD5, see EVP_MD-MD5" +.IP "\s-1MD5\-SHA1,\s0 see \s-1\fBEVP_MD\-MD5\-SHA1\s0\fR\|(7)" 4 +.IX Item "MD5-SHA1, see EVP_MD-MD5-SHA1" +.IP "\s-1RIPEMD160,\s0 see \s-1\fBEVP_MD\-RIPEMD160\s0\fR\|(7)" 4 +.IX Item "RIPEMD160, see EVP_MD-RIPEMD160" +.IP "\s-1NULL,\s0 see \s-1\fBEVP_MD\-NULL\s0\fR\|(7)" 4 +.IX Item "NULL, see EVP_MD-NULL" +.PD +.SS "Symmetric Ciphers" +.IX Subsection "Symmetric Ciphers" +.IP "\s-1AES,\s0 see \s-1\fBEVP_CIPHER\-AES\s0\fR\|(7)" 4 +.IX Item "AES, see EVP_CIPHER-AES" +.PD 0 +.IP "\s-1ARIA,\s0 see \s-1\fBEVP_CIPHER\-ARIA\s0\fR\|(7)" 4 +.IX Item "ARIA, see EVP_CIPHER-ARIA" +.IP "\s-1CAMELLIA,\s0 see \s-1\fBEVP_CIPHER\-CAMELLIA\s0\fR\|(7)" 4 +.IX Item "CAMELLIA, see EVP_CIPHER-CAMELLIA" +.IP "3DES, see \s-1\fBEVP_CIPHER\-DES\s0\fR\|(7)" 4 +.IX Item "3DES, see EVP_CIPHER-DES" +.IP "\s-1SEED,\s0 see \s-1\fBEVP_CIPHER\-SEED\s0\fR\|(7)" 4 +.IX Item "SEED, see EVP_CIPHER-SEED" +.IP "\s-1SM4,\s0 see \s-1\fBEVP_CIPHER\-SM4\s0\fR\|(7)" 4 +.IX Item "SM4, see EVP_CIPHER-SM4" +.IP "ChaCha20, see \s-1\fBEVP_CIPHER\-CHACHA\s0\fR\|(7)" 4 +.IX Item "ChaCha20, see EVP_CIPHER-CHACHA" +.IP "ChaCha20\-Poly1305, see \s-1\fBEVP_CIPHER\-CHACHA\s0\fR\|(7)" 4 +.IX Item "ChaCha20-Poly1305, see EVP_CIPHER-CHACHA" +.IP "\s-1NULL,\s0 see \s-1\fBEVP_CIPHER\-NULL\s0\fR\|(7)" 4 +.IX Item "NULL, see EVP_CIPHER-NULL" +.PD +.SS "Message Authentication Code (\s-1MAC\s0)" +.IX Subsection "Message Authentication Code (MAC)" +.IP "\s-1BLAKE2,\s0 see \s-1\fBEVP_MAC\-BLAKE2\s0\fR\|(7)" 4 +.IX Item "BLAKE2, see EVP_MAC-BLAKE2" +.PD 0 +.IP "\s-1CMAC,\s0 see \s-1\fBEVP_MAC\-CMAC\s0\fR\|(7)" 4 +.IX Item "CMAC, see EVP_MAC-CMAC" +.IP "\s-1GMAC,\s0 see \s-1\fBEVP_MAC\-GMAC\s0\fR\|(7)" 4 +.IX Item "GMAC, see EVP_MAC-GMAC" +.IP "\s-1HMAC,\s0 see \s-1\fBEVP_MAC\-HMAC\s0\fR\|(7)" 4 +.IX Item "HMAC, see EVP_MAC-HMAC" +.IP "\s-1KMAC,\s0 see \s-1\fBEVP_MAC\-KMAC\s0\fR\|(7)" 4 +.IX Item "KMAC, see EVP_MAC-KMAC" +.IP "\s-1SIPHASH,\s0 see \fBEVP_MAC\-Siphash\fR\|(7)" 4 +.IX Item "SIPHASH, see EVP_MAC-Siphash" +.IP "\s-1POLY1305,\s0 see \fBEVP_MAC\-Poly1305\fR\|(7)" 4 +.IX Item "POLY1305, see EVP_MAC-Poly1305" +.PD +.SS "Key Derivation Function (\s-1KDF\s0)" +.IX Subsection "Key Derivation Function (KDF)" +.IP "\s-1HKDF,\s0 see \s-1\fBEVP_KDF\-HKDF\s0\fR\|(7)" 4 +.IX Item "HKDF, see EVP_KDF-HKDF" +.PD 0 +.IP "\s-1SSKDF,\s0 see \s-1\fBEVP_KDF\-SS\s0\fR\|(7)" 4 +.IX Item "SSKDF, see EVP_KDF-SS" +.IP "\s-1PBKDF2,\s0 see \s-1\fBEVP_KDF\-PBKDF2\s0\fR\|(7)" 4 +.IX Item "PBKDF2, see EVP_KDF-PBKDF2" +.IP "\s-1PKCS12KDF,\s0 see \s-1\fBEVP_KDF\-PKCS12KDF\s0\fR\|(7)" 4 +.IX Item "PKCS12KDF, see EVP_KDF-PKCS12KDF" +.IP "\s-1SSHKDF,\s0 see \s-1\fBEVP_KDF\-SSHKDF\s0\fR\|(7)" 4 +.IX Item "SSHKDF, see EVP_KDF-SSHKDF" +.IP "\s-1TLS1\-PRF,\s0 see \s-1\fBEVP_KDF\-TLS1_PRF\s0\fR\|(7)" 4 +.IX Item "TLS1-PRF, see EVP_KDF-TLS1_PRF" +.IP "\s-1KBKDF,\s0 see \s-1\fBEVP_KDF\-KB\s0\fR\|(7)" 4 +.IX Item "KBKDF, see EVP_KDF-KB" +.IP "X942KDF\-ASN1, see \s-1\fBEVP_KDF\-X942\-ASN1\s0\fR\|(7)" 4 +.IX Item "X942KDF-ASN1, see EVP_KDF-X942-ASN1" +.IP "X942KDF\-CONCAT, see \s-1\fBEVP_KDF\-X942\-CONCAT\s0\fR\|(7)" 4 +.IX Item "X942KDF-CONCAT, see EVP_KDF-X942-CONCAT" +.IP "X963KDF, see \s-1\fBEVP_KDF\-X963\s0\fR\|(7)" 4 +.IX Item "X963KDF, see EVP_KDF-X963" +.IP "\s-1SCRYPT,\s0 see \s-1\fBEVP_KDF\-SCRYPT\s0\fR\|(7)" 4 +.IX Item "SCRYPT, see EVP_KDF-SCRYPT" +.IP "\s-1KRB5KDF,\s0 see \s-1\fBEVP_KDF\-KRB5KDF\s0\fR\|(7)" 4 +.IX Item "KRB5KDF, see EVP_KDF-KRB5KDF" +.PD +.SS "Key Exchange" +.IX Subsection "Key Exchange" +.IP "\s-1DH,\s0 see \s-1\fBEVP_KEYEXCH\-DH\s0\fR\|(7)" 4 +.IX Item "DH, see EVP_KEYEXCH-DH" +.PD 0 +.IP "\s-1ECDH,\s0 see \s-1\fBEVP_KEYEXCH\-ECDH\s0\fR\|(7)" 4 +.IX Item "ECDH, see EVP_KEYEXCH-ECDH" +.IP "X25519, see \s-1\fBEVP_KEYEXCH\-X25519\s0\fR\|(7)" 4 +.IX Item "X25519, see EVP_KEYEXCH-X25519" +.IP "X448, see \s-1\fBEVP_KEYEXCH\-X448\s0\fR\|(7)" 4 +.IX Item "X448, see EVP_KEYEXCH-X448" +.PD +.SS "Asymmetric Signature" +.IX Subsection "Asymmetric Signature" +.IP "\s-1DSA,\s0 see \s-1\fBEVP_SIGNATURE\-DSA\s0\fR\|(7)" 4 +.IX Item "DSA, see EVP_SIGNATURE-DSA" +.PD 0 +.IP "\s-1RSA,\s0 see \s-1\fBEVP_SIGNATURE\-RSA\s0\fR\|(7)" 4 +.IX Item "RSA, see EVP_SIGNATURE-RSA" +.IP "\s-1HMAC,\s0 see \s-1\fBEVP_SIGNATURE\-HMAC\s0\fR\|(7)" 4 +.IX Item "HMAC, see EVP_SIGNATURE-HMAC" +.IP "\s-1SIPHASH,\s0 see \fBEVP_SIGNATURE\-Siphash\fR\|(7)" 4 +.IX Item "SIPHASH, see EVP_SIGNATURE-Siphash" +.IP "\s-1POLY1305,\s0 see \fBEVP_SIGNATURE\-Poly1305\fR\|(7)" 4 +.IX Item "POLY1305, see EVP_SIGNATURE-Poly1305" +.IP "\s-1CMAC,\s0 see \s-1\fBEVP_SIGNATURE\-CMAC\s0\fR\|(7)" 4 +.IX Item "CMAC, see EVP_SIGNATURE-CMAC" +.PD +.SS "Asymmetric Cipher" +.IX Subsection "Asymmetric Cipher" +.IP "\s-1RSA,\s0 see \s-1\fBEVP_ASYM_CIPHER\-RSA\s0\fR\|(7)" 4 +.IX Item "RSA, see EVP_ASYM_CIPHER-RSA" +.PD 0 +.IP "\s-1SM2,\s0 see \s-1\fBEVP_ASYM_CIPHER\-SM2\s0\fR\|(7)" 4 +.IX Item "SM2, see EVP_ASYM_CIPHER-SM2" +.PD +.SS "Asymmetric Key Encapsulation" +.IX Subsection "Asymmetric Key Encapsulation" +.IP "\s-1RSA,\s0 see \s-1\fBEVP_KEM\-RSA\s0\fR\|(7)" 4 +.IX Item "RSA, see EVP_KEM-RSA" +.SS "Asymmetric Key Management" +.IX Subsection "Asymmetric Key Management" +.PD 0 +.IP "\s-1DH,\s0 see \s-1\fBEVP_KEYMGMT\-DH\s0\fR\|(7)" 4 +.IX Item "DH, see EVP_KEYMGMT-DH" +.IP "\s-1DHX,\s0 see \s-1\fBEVP_KEYMGMT\-DHX\s0\fR\|(7)" 4 +.IX Item "DHX, see EVP_KEYMGMT-DHX" +.IP "\s-1DSA,\s0 see \s-1\fBEVP_KEYMGMT\-DSA\s0\fR\|(7)" 4 +.IX Item "DSA, see EVP_KEYMGMT-DSA" +.IP "\s-1RSA,\s0 see \s-1\fBEVP_KEYMGMT\-RSA\s0\fR\|(7)" 4 +.IX Item "RSA, see EVP_KEYMGMT-RSA" +.IP "\s-1EC,\s0 see \s-1\fBEVP_KEYMGMT\-EC\s0\fR\|(7)" 4 +.IX Item "EC, see EVP_KEYMGMT-EC" +.IP "X25519, see \s-1\fBEVP_KEYMGMT\-X25519\s0\fR\|(7)" 4 +.IX Item "X25519, see EVP_KEYMGMT-X25519" +.IP "X448, see \s-1\fBEVP_KEYMGMT\-X448\s0\fR\|(7)" 4 +.IX Item "X448, see EVP_KEYMGMT-X448" +.PD +.SS "Random Number Generation" +.IX Subsection "Random Number Generation" +.IP "CTR-DRBG, see \s-1\fBEVP_RAND\-CTR\-DRBG\s0\fR\|(7)" 4 +.IX Item "CTR-DRBG, see EVP_RAND-CTR-DRBG" +.PD 0 +.IP "HASH-DRBG, see \s-1\fBEVP_RAND\-HASH\-DRBG\s0\fR\|(7)" 4 +.IX Item "HASH-DRBG, see EVP_RAND-HASH-DRBG" +.IP "HMAC-DRBG, see \s-1\fBEVP_RAND\-HMAC\-DRBG\s0\fR\|(7)" 4 +.IX Item "HMAC-DRBG, see EVP_RAND-HMAC-DRBG" +.IP "SEED-SRC, see \s-1\fBEVP_RAND\-SEED\-SRC\s0\fR\|(7)" 4 +.IX Item "SEED-SRC, see EVP_RAND-SEED-SRC" +.IP "TEST-RAND, see \s-1\fBEVP_RAND\-TEST\-RAND\s0\fR\|(7)" 4 +.IX Item "TEST-RAND, see EVP_RAND-TEST-RAND" +.PD +.SS "Asymmetric Key Encoder" +.IX Subsection "Asymmetric Key Encoder" +The default provider also includes all of the encoding algorithms +present in the base provider. Some of these have the property \*(L"fips=yes\*(R", +to allow them to be used together with the \s-1FIPS\s0 provider. +.IP "\s-1RSA,\s0 see \s-1\fBOSSL_ENCODER\-RSA\s0\fR\|(7)" 4 +.IX Item "RSA, see OSSL_ENCODER-RSA" +.PD 0 +.IP "\s-1DH,\s0 see \s-1\fBOSSL_ENCODER\-DH\s0\fR\|(7)" 4 +.IX Item "DH, see OSSL_ENCODER-DH" +.IP "\s-1DSA,\s0 see \s-1\fBOSSL_ENCODER\-DSA\s0\fR\|(7)" 4 +.IX Item "DSA, see OSSL_ENCODER-DSA" +.IP "\s-1EC,\s0 see \s-1\fBOSSL_ENCODER\-EC\s0\fR\|(7)" 4 +.IX Item "EC, see OSSL_ENCODER-EC" +.IP "X25519, see \s-1\fBOSSL_ENCODER\-X25519\s0\fR\|(7)" 4 +.IX Item "X25519, see OSSL_ENCODER-X25519" +.IP "X448, see \s-1\fBOSSL_ENCODER\-X448\s0\fR\|(7)" 4 +.IX Item "X448, see OSSL_ENCODER-X448" +.PD +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-core.h\fR\|(7), \fBopenssl\-core_dispatch.h\fR\|(7), \fBprovider\fR\|(7), +\&\fBOSSL_PROVIDER\-base\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The \s-1RIPEMD160\s0 digest was added to the default provider in OpenSSL 3.0.7. +.PP +All other functionality was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2023 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>. diff --git a/secure/lib/libcrypto/man/man7/OSSL_PROVIDER-legacy.7 b/secure/lib/libcrypto/man/man7/OSSL_PROVIDER-legacy.7 new file mode 100644 index 000000000000..61c168883137 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/OSSL_PROVIDER-legacy.7 @@ -0,0 +1,229 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "OSSL_PROVIDER-LEGACY 7ossl" +.TH OSSL_PROVIDER-LEGACY 7ossl "2023-09-19" "3.0.11" "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" +OSSL_PROVIDER\-legacy \- OpenSSL legacy provider +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The OpenSSL legacy provider supplies OpenSSL implementations of algorithms +that have been deemed legacy. Such algorithms have commonly fallen out of +use, have been deemed insecure by the cryptography community, or something +similar. +.PP +We can consider this the retirement home of cryptographic algorithms. +.SS "Properties" +.IX Subsection "Properties" +The implementations in this provider specifically has this property +defined: +.ie n .IP """provider=legacy""" 4 +.el .IP "``provider=legacy''" 4 +.IX Item "provider=legacy" +.PP +It may be used in a property query string with fetching functions such as +\&\fBEVP_MD_fetch\fR\|(3) or \fBEVP_CIPHER_fetch\fR\|(3), as well as with other +functions that take a property query string, such as +\&\fBEVP_PKEY_CTX_new_from_name\fR\|(3). +.PP +It isn't mandatory to query for any of these properties, except to +make sure to get implementations of this provider and none other. +.SH "OPERATIONS AND ALGORITHMS" +.IX Header "OPERATIONS AND ALGORITHMS" +The OpenSSL legacy provider supports these operations and algorithms: +.SS "Hashing Algorithms / Message Digests" +.IX Subsection "Hashing Algorithms / Message Digests" +.IP "\s-1MD2,\s0 see \s-1\fBEVP_MD\-MD2\s0\fR\|(7)" 4 +.IX Item "MD2, see EVP_MD-MD2" +.PD 0 +.IP "\s-1MD4,\s0 see \s-1\fBEVP_MD\-MD4\s0\fR\|(7)" 4 +.IX Item "MD4, see EVP_MD-MD4" +.IP "\s-1MDC2,\s0 see \s-1\fBEVP_MD\-MDC2\s0\fR\|(7)" 4 +.IX Item "MDC2, see EVP_MD-MDC2" +.IP "\s-1WHIRLPOOL,\s0 see \s-1\fBEVP_MD\-WHIRLPOOL\s0\fR\|(7)" 4 +.IX Item "WHIRLPOOL, see EVP_MD-WHIRLPOOL" +.IP "\s-1RIPEMD160,\s0 see \s-1\fBEVP_MD\-RIPEMD160\s0\fR\|(7)" 4 +.IX Item "RIPEMD160, see EVP_MD-RIPEMD160" +.PD +.SS "Symmetric Ciphers" +.IX Subsection "Symmetric Ciphers" +Not all of these symmetric cipher algorithms are enabled by default. +.IP "Blowfish, see \s-1\fBEVP_CIPHER\-BLOWFISH\s0\fR\|(7)" 4 +.IX Item "Blowfish, see EVP_CIPHER-BLOWFISH" +.PD 0 +.IP "\s-1CAST,\s0 see \s-1\fBEVP_CIPHER\-CAST\s0\fR\|(7)" 4 +.IX Item "CAST, see EVP_CIPHER-CAST" +.IP "\s-1DES,\s0 see \s-1\fBEVP_CIPHER\-DES\s0\fR\|(7)" 4 +.IX Item "DES, see EVP_CIPHER-DES" +.PD +The algorithm names are: \s-1DES_ECB, DES_CBC, DES_OFB, DES_CFB, DES_CFB1, DES_CFB8\s0 +and \s-1DESX_CBC.\s0 +.IP "\s-1IDEA,\s0 see \s-1\fBEVP_CIPHER\-IDEA\s0\fR\|(7)" 4 +.IX Item "IDEA, see EVP_CIPHER-IDEA" +.PD 0 +.IP "\s-1RC2,\s0 see \s-1\fBEVP_CIPHER\-RC2\s0\fR\|(7)" 4 +.IX Item "RC2, see EVP_CIPHER-RC2" +.IP "\s-1RC4,\s0 see \s-1\fBEVP_CIPHER\-RC4\s0\fR\|(7)" 4 +.IX Item "RC4, see EVP_CIPHER-RC4" +.IP "\s-1RC5,\s0 see \s-1\fBEVP_CIPHER\-RC5\s0\fR\|(7)" 4 +.IX Item "RC5, see EVP_CIPHER-RC5" +.PD +Disabled by default. Use \fIenable\-rc5\fR config option to enable. +.IP "\s-1SEED,\s0 see \s-1\fBEVP_CIPHER\-SEED\s0\fR\|(7)" 4 +.IX Item "SEED, see EVP_CIPHER-SEED" +.SS "Key Derivation Function (\s-1KDF\s0)" +.IX Subsection "Key Derivation Function (KDF)" +.PD 0 +.IP "\s-1PBKDF1\s0" 4 +.IX Item "PBKDF1" +.PD +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\s-1\fBOSSL_PARAM\s0\fR\|(3), +\&\fBopenssl\-core.h\fR\|(7), +\&\fBopenssl\-core_dispatch.h\fR\|(7), +\&\fBprovider\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/OSSL_PROVIDER-null.7 b/secure/lib/libcrypto/man/man7/OSSL_PROVIDER-null.7 new file mode 100644 index 000000000000..16be0731b3ad --- /dev/null +++ b/secure/lib/libcrypto/man/man7/OSSL_PROVIDER-null.7 @@ -0,0 +1,166 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "OSSL_PROVIDER-NULL 7ossl" +.TH OSSL_PROVIDER-NULL 7ossl "2023-09-19" "3.0.11" "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" +OSSL_PROVIDER\-null \- OpenSSL null provider +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The OpenSSL null provider supplies no algorithms. +.PP +It can used to guarantee that the default library context and a fallback +provider will not be accidentally accessed. +.SS "Properties" +.IX Subsection "Properties" +The null provider defines no properties. +.SH "OPERATIONS AND ALGORITHMS" +.IX Header "OPERATIONS AND ALGORITHMS" +The OpenSSL null provider supports no operations and algorithms. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020 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>. diff --git a/secure/lib/libcrypto/man/man7/RAND.7 b/secure/lib/libcrypto/man/man7/RAND.7 index 6a70a21ced3a..f2b8e4545944 100644 --- a/secure/lib/libcrypto/man/man7/RAND.7 +++ b/secure/lib/libcrypto/man/man7/RAND.7 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .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 \{\ @@ -132,14 +130,15 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "RAND 7" -.TH RAND 7 "2022-06-21" "1.1.1p" "OpenSSL" +.IX Title "RAND 7ossl" +.TH RAND 7ossl "2023-09-19" "3.0.11" "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" -RAND \&\- the OpenSSL random generator +RAND +\&\- the OpenSSL random generator .SH "DESCRIPTION" .IX Header "DESCRIPTION" Random numbers are a vital part of cryptography, they are needed to provide @@ -168,11 +167,12 @@ is available or the trusted source(s) temporarily fail to provide sufficient random seed material. In this case the \s-1CSPRNG\s0 enters an error state and ceases to provide output, until it is able to recover from the error by reseeding itself. -For more details on reseeding and error recovery, see \s-1\fBRAND_DRBG\s0\fR\|(7). +For more details on reseeding and error recovery, see \s-1\fBEVP_RAND\s0\fR\|(7). .PP For values that should remain secret, you can use \fBRAND_priv_bytes\fR\|(3) instead. -This method does not provide 'better' randomness, it uses the same type of \s-1CSPRNG.\s0 +This method does not provide 'better' randomness, it uses the same type of +\&\s-1CSPRNG.\s0 The intention behind using a dedicated \s-1CSPRNG\s0 exclusively for private values is that none of its output should be visible to an attacker (e.g., used as salt value), in order to reveal as little information as @@ -180,31 +180,31 @@ possible about its internal state, and that a compromise of the \*(L"public\*(R" \&\s-1CSPRNG\s0 instance will not affect the secrecy of these private values. .PP In the rare case where the default implementation does not satisfy your special -requirements, there are two options: -.IP "\(bu" 2 -Replace the default \s-1RAND\s0 method by your own \s-1RAND\s0 method using -\&\fBRAND_set_rand_method\fR\|(3). -.IP "\(bu" 2 -Modify the default settings of the OpenSSL \s-1RAND\s0 method by modifying the security -parameters of the underlying \s-1DRBG,\s0 which is described in detail in \s-1\fBRAND_DRBG\s0\fR\|(7). +requirements, the default \s-1RAND\s0 internals can be replaced by your own +\&\s-1\fBEVP_RAND\s0\fR\|(3) objects. .PP -Changing the default random generator or its default parameters should be necessary -only in exceptional cases and is not recommended, unless you have a profound knowledge -of cryptographic principles and understand the implications of your changes. +Changing the default random generator should be necessary +only in exceptional cases and is not recommended, unless you have a profound +knowledge of cryptographic principles and understand the implications of your +changes. +.SH "DEFAULT SETUP" +.IX Header "DEFAULT SETUP" +The default OpenSSL \s-1RAND\s0 method is based on the \s-1EVP_RAND\s0 deterministic random +bit generator (\s-1DRBG\s0) classes. +A \s-1DRBG\s0 is a certain type of cryptographically-secure pseudo-random +number generator (\s-1CSPRNG\s0), which is described in [\s-1NIST SP 800\-90A\s0 Rev. 1]. .SH "SEE ALSO" .IX Header "SEE ALSO" -\&\fBRAND_add\fR\|(3), \&\fBRAND_bytes\fR\|(3), \&\fBRAND_priv_bytes\fR\|(3), -\&\fBRAND_get_rand_method\fR\|(3), -\&\fBRAND_set_rand_method\fR\|(3), -\&\fBRAND_OpenSSL\fR\|(3), -\&\s-1\fBRAND_DRBG\s0\fR\|(7) +\&\s-1\fBEVP_RAND\s0\fR\|(3), +\&\fBRAND_get0_primary\fR\|(3), +\&\s-1\fBEVP_RAND\s0\fR\|(7) .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2018\-2019 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +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>. diff --git a/secure/lib/libcrypto/man/man7/RSA-PSS.7 b/secure/lib/libcrypto/man/man7/RSA-PSS.7 index 3943e79a60c4..c00f3087f404 100644 --- a/secure/lib/libcrypto/man/man7/RSA-PSS.7 +++ b/secure/lib/libcrypto/man/man7/RSA-PSS.7 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .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 \{\ @@ -132,8 +130,8 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "RSA-PSS 7" -.TH RSA-PSS 7 "2022-06-21" "1.1.1p" "OpenSSL" +.IX Title "RSA-PSS 7ossl" +.TH RSA-PSS 7ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -183,7 +181,7 @@ present, restricts the key parameters in the same way as the public key. .IX Header "COPYRIGHT" Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +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>. diff --git a/secure/lib/libcrypto/man/man7/X25519.7 b/secure/lib/libcrypto/man/man7/X25519.7 index c408ccd78741..bf23c061e476 100644 --- a/secure/lib/libcrypto/man/man7/X25519.7 +++ b/secure/lib/libcrypto/man/man7/X25519.7 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .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 \{\ @@ -132,14 +130,16 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "X25519 7" -.TH X25519 7 "2022-06-21" "1.1.1p" "OpenSSL" +.IX Title "X25519 7ossl" +.TH X25519 7ossl "2023-09-19" "3.0.11" "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" -X25519, X448 \&\- EVP_PKEY X25519 and X448 support +X25519, +X448 +\&\- EVP_PKEY X25519 and X448 support .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \fBX25519\fR and \fBX448\fR \s-1EVP_PKEY\s0 implementation supports key generation and @@ -202,7 +202,7 @@ The key derivation example in \fBEVP_PKEY_derive\fR\|(3) can be used with .IX Header "COPYRIGHT" Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +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>. diff --git a/secure/lib/libcrypto/man/man7/bio.7 b/secure/lib/libcrypto/man/man7/bio.7 index 288ec0dd27f7..7db46aad4e68 100644 --- a/secure/lib/libcrypto/man/man7/bio.7 +++ b/secure/lib/libcrypto/man/man7/bio.7 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .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 \{\ @@ -132,8 +130,8 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "BIO 7" -.TH BIO 7 "2022-06-21" "1.1.1p" "OpenSSL" +.IX Title "BIO 7ossl" +.TH BIO 7ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -152,7 +150,7 @@ details from an application. If an application uses a \s-1BIO\s0 for its I/O it can transparently handle \s-1SSL\s0 connections, unencrypted network connections and file I/O. .PP -There are two type of \s-1BIO,\s0 a source/sink \s-1BIO\s0 and a filter \s-1BIO.\s0 +There are two types of \s-1BIO,\s0 a source/sink \s-1BIO\s0 and a filter \s-1BIO.\s0 .PP As its name implies a source/sink \s-1BIO\s0 is a source and/or sink of data, examples include a socket \s-1BIO\s0 and a file \s-1BIO.\s0 @@ -166,7 +164,7 @@ to the I/O operation it is performing: for example an encryption if it is being read from. .PP BIOs can be joined together to form a chain (a single \s-1BIO\s0 is a chain -with one component). A chain normally consist of one source/sink +with one component). A chain normally consists of one source/sink \&\s-1BIO\s0 and one or more filter BIOs. Data read from or written to the first \s-1BIO\s0 then traverses the chain to the end (normally a source/sink \&\s-1BIO\s0). @@ -181,10 +179,10 @@ in a memory leak. Calling \fBBIO_free_all()\fR on a single \s-1BIO\s0 has the same effect as calling \&\fBBIO_free()\fR on it other than the discarded return value. .PP -Normally the \fBtype\fR argument is supplied by a function which returns a +Normally the \fItype\fR argument is supplied by a function which returns a pointer to a \s-1BIO_METHOD.\s0 There is a naming convention for such functions: -a source/sink \s-1BIO\s0 is normally called BIO_s_*() and a filter \s-1BIO\s0 -BIO_f_*(); +a source/sink \s-1BIO\s0 typically starts with \fIBIO_s_\fR and +a filter \s-1BIO\s0 with \fIBIO_f_\fR. .SH "EXAMPLES" .IX Header "EXAMPLES" Create a memory \s-1BIO:\s0 @@ -198,6 +196,7 @@ Create a memory \s-1BIO:\s0 \&\fBBIO_f_base64\fR\|(3), \fBBIO_f_buffer\fR\|(3), \&\fBBIO_f_cipher\fR\|(3), \fBBIO_f_md\fR\|(3), \&\fBBIO_f_null\fR\|(3), \fBBIO_f_ssl\fR\|(3), +\&\fBBIO_f_readbuffer\fR\|(3), \&\fBBIO_find_type\fR\|(3), \fBBIO_new\fR\|(3), \&\fBBIO_new_bio_pair\fR\|(3), \&\fBBIO_push\fR\|(3), \fBBIO_read_ex\fR\|(3), @@ -209,9 +208,9 @@ Create a memory \s-1BIO:\s0 \&\fBBIO_should_retry\fR\|(3) .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2000\-2019 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +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>. diff --git a/secure/lib/libcrypto/man/man7/crypto.7 b/secure/lib/libcrypto/man/man7/crypto.7 new file mode 100644 index 000000000000..041c046d4b24 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/crypto.7 @@ -0,0 +1,687 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "CRYPTO 7ossl" +.TH CRYPTO 7ossl "2023-09-19" "3.0.11" "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" +crypto \- OpenSSL cryptographic library +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +See the individual manual pages for details. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The OpenSSL crypto library (\f(CW\*(C`libcrypto\*(C'\fR) implements a wide range of +cryptographic algorithms used in various Internet standards. The services +provided by this library are used by the OpenSSL implementations of \s-1TLS\s0 and +\&\s-1CMS,\s0 and they have also been used to implement many other third party products +and protocols. +.PP +The functionality includes symmetric encryption, public key cryptography, key +agreement, certificate handling, cryptographic hash functions, cryptographic +pseudo-random number generators, message authentication codes (MACs), key +derivation functions (KDFs), and various utilities. +.SS "Algorithms" +.IX Subsection "Algorithms" +Cryptographic primitives such as the \s-1SHA256\s0 digest, or \s-1AES\s0 encryption are +referred to in OpenSSL as \*(L"algorithms\*(R". Each algorithm may have multiple +implementations available for use. For example the \s-1RSA\s0 algorithm is available as +a \*(L"default\*(R" implementation suitable for general use, and a \*(L"fips\*(R" implementation +which has been validated to \s-1FIPS\s0 standards for situations where that is +important. It is also possible that a third party could add additional +implementations such as in a hardware security module (\s-1HSM\s0). +.SS "Operations" +.IX Subsection "Operations" +Different algorithms can be grouped together by their purpose. For example there +are algorithms for encryption, and different algorithms for digesting data. +These different groups are known as \*(L"operations\*(R" in OpenSSL. Each operation +has a different set of functions associated with it. For example to perform an +encryption operation using \s-1AES\s0 (or any other encryption algorithm) you would use +the encryption functions detailed on the \fBEVP_EncryptInit\fR\|(3) page. Or to +perform a digest operation using \s-1SHA256\s0 then you would use the digesting +functions on the \fBEVP_DigestInit\fR\|(3) page. +.SS "Providers" +.IX Subsection "Providers" +A provider in OpenSSL is a component that collects together algorithm +implementations. In order to use an algorithm you must have at least one +provider loaded that contains an implementation of it. OpenSSL comes with a +number of providers and they may also be obtained from third parties. If you +don't load a provider explicitly (either in program code or via config) then the +OpenSSL built-in \*(L"default\*(R" provider will be automatically loaded. +.SS "Library contexts" +.IX Subsection "Library contexts" +A library context can be thought of as a \*(L"scope\*(R" within which configuration +options take effect. When a provider is loaded, it is only loaded within the +scope of a given library context. In this way it is possible for different +components of a complex application to each use a different library context and +have different providers loaded with different configuration settings. +.PP +If an application does not explicitly create a library context then the +\&\*(L"default\*(R" library context will be used. +.PP +Library contexts are represented by the \fB\s-1OSSL_LIB_CTX\s0\fR type. Many OpenSSL \s-1API\s0 +functions take a library context as a parameter. Applications can always pass +\&\fB\s-1NULL\s0\fR for this parameter to just use the default library context. +.PP +The default library context is automatically created the first time it is +needed. This will automatically load any available configuration file and will +initialise OpenSSL for use. Unlike in earlier versions of OpenSSL (prior to +1.1.0) no explicit initialisation steps need to be taken. +.PP +Similarly when the application exits the default library context is +automatically destroyed. No explicit de-initialisation steps need to be taken. +.PP +See \s-1\fBOSSL_LIB_CTX\s0\fR\|(3) for more information about library contexts. +See also \*(L"\s-1ALGORITHM FETCHING\*(R"\s0. +.SS "Multi-threaded applications" +.IX Subsection "Multi-threaded applications" +As long as OpenSSL has been built with support for threads (the default case +on most platforms) then most OpenSSL \fIfunctions\fR are thread-safe in the sense +that it is safe to call the same function from multiple threads at the same +time. However most OpenSSL \fIdata structures\fR are not thread-safe. For example +the \fBBIO_write\fR\|(3) and \fBBIO_read\fR\|(3) functions are thread safe. However it +would not be thread safe to call \fBBIO_write()\fR from one thread while calling +\&\fBBIO_read()\fR in another where both functions are passed the same \fB\s-1BIO\s0\fR object +since both of them may attempt to make changes to the same \fB\s-1BIO\s0\fR object. +.PP +There are exceptions to these rules. A small number of functions are not thread +safe at all. Where this is the case this restriction should be noted in the +documentation for the function. Similarly some data structures may be partially +or fully thread safe. For example it is safe to use an \fB\s-1OSSL_LIB_CTX\s0\fR in +multiple threads. +.PP +See \fBopenssl\-threads\fR\|(7) for a more detailed discussion on OpenSSL threading +support. +.SH "ALGORITHM FETCHING" +.IX Header "ALGORITHM FETCHING" +In order to use an algorithm an implementation for it must first be \*(L"fetched\*(R". +Fetching is the process of looking through the available implementations, +applying selection criteria (via a property query string), and finally choosing +the implementation that will be used. +.PP +Two types of fetching are supported by OpenSSL \- explicit fetching and implicit +fetching. +.SS "Property query strings" +.IX Subsection "Property query strings" +When fetching an algorithm it is possible to specify a property query string to +guide the selection process. For example a property query string of +\&\*(L"provider=default\*(R" could be used to force the selection to only consider +algorithm implementations in the default provider. +.PP +Property query strings can be specified explicitly as an argument to a function. +It is also possible to specify a default property query string for the whole +library context using the \fBEVP_set_default_properties\fR\|(3) or +\&\fBEVP_default_properties_enable_fips\fR\|(3) functions. Where both +default properties and function specific properties are specified then they are +combined. Function specific properties will override default properties where +there is a conflict. +.PP +See \fBproperty\fR\|(7) for more information about properties. +.SS "Explicit fetching" +.IX Subsection "Explicit fetching" +Users of the OpenSSL libraries never query a provider directly for an algorithm +implementation. Instead, the diverse OpenSSL APIs often have explicit fetching +functions that do the work, and they return an appropriate algorithm object back +to the user. These functions usually have the name \f(CW\*(C`APINAME_fetch\*(C'\fR, where +\&\f(CW\*(C`APINAME\*(C'\fR is the name of the operation. For example \fBEVP_MD_fetch\fR\|(3) can +be used to explicitly fetch a digest algorithm implementation. The user is +responsible for freeing the object returned from the \f(CW\*(C`APINAME_fetch\*(C'\fR function +using \f(CW\*(C`APINAME_free\*(C'\fR when it is no longer needed. +.PP +These fetching functions follow a fairly common pattern, where three +arguments are passed: +.IP "The library context" 4 +.IX Item "The library context" +See \s-1\fBOSSL_LIB_CTX\s0\fR\|(3) for a more detailed description. +This may be \s-1NULL\s0 to signify the default (global) library context, or a +context created by the user. Only providers loaded in this library context (see +\&\fBOSSL_PROVIDER_load\fR\|(3)) will be considered by the fetching function. In case +no provider has been loaded in this library context then the default provider +will be loaded as a fallback (see \fBOSSL_PROVIDER\-default\fR\|(7)). +.IP "An identifier" 4 +.IX Item "An identifier" +For all currently implemented fetching functions this is the algorithm name. +.IP "A property query string" 4 +.IX Item "A property query string" +The property query string used to guide selection of the algorithm +implementation. +.PP +The algorithm implementation that is fetched can then be used with other diverse +functions that use them. For example the \fBEVP_DigestInit_ex\fR\|(3) function takes +as a parameter an \fB\s-1EVP_MD\s0\fR object which may have been returned from an earlier +call to \fBEVP_MD_fetch\fR\|(3). +.SS "Implicit fetching" +.IX Subsection "Implicit fetching" +OpenSSL has a number of functions that return an algorithm object with no +associated implementation, such as \fBEVP_sha256\fR\|(3), \fBEVP_aes_128_cbc\fR\|(3), +\&\fBEVP_get_cipherbyname\fR\|(3) or \fBEVP_get_digestbyname\fR\|(3). These are present for +compatibility with OpenSSL before version 3.0 where explicit fetching was not +available. +.PP +When they are used with functions like \fBEVP_DigestInit_ex\fR\|(3) or +\&\fBEVP_CipherInit_ex\fR\|(3), the actual implementation to be used is +fetched implicitly using default search criteria. +.PP +In some cases implicit fetching can also occur when a \s-1NULL\s0 algorithm parameter +is supplied. In this case an algorithm implementation is implicitly fetched +using default search criteria and an algorithm name that is consistent with +the context in which it is being used. +.PP +Functions that revolve around \fB\s-1EVP_PKEY_CTX\s0\fR and \s-1\fBEVP_PKEY\s0\fR\|(3), such as +\&\fBEVP_DigestSignInit\fR\|(3) and friends, all fetch the implementations +implicitly. Because these functions involve both an operation type (such as +\&\s-1\fBEVP_SIGNATURE\s0\fR\|(3)) and an \s-1\fBEVP_KEYMGMT\s0\fR\|(3) for the \s-1\fBEVP_PKEY\s0\fR\|(3), they try +the following: +.IP "1." 4 +Fetch the operation type implementation from any provider given a library +context and property string stored in the \fB\s-1EVP_PKEY_CTX\s0\fR. +.Sp +If the provider of the operation type implementation is different from the +provider of the \s-1\fBEVP_PKEY\s0\fR\|(3)'s \s-1\fBEVP_KEYMGMT\s0\fR\|(3) implementation, try to +fetch a \s-1\fBEVP_KEYMGMT\s0\fR\|(3) implementation in the same provider as the operation +type implementation and export the \s-1\fBEVP_PKEY\s0\fR\|(3) to it (effectively making a +temporary copy of the original key). +.Sp +If anything in this step fails, the next step is used as a fallback. +.IP "2." 4 +As a fallback, try to fetch the operation type implementation from the same +provider as the original \s-1\fBEVP_PKEY\s0\fR\|(3)'s \s-1\fBEVP_KEYMGMT\s0\fR\|(3), still using the +property string from the \fB\s-1EVP_PKEY_CTX\s0\fR. +.SS "Performance" +.IX Subsection "Performance" +If you perform the same operation many times then it is recommended to use +\&\*(L"Explicit fetching\*(R" to prefetch an algorithm once initially, +and then pass this created object to any operations that are currently +using \*(L"Implicit fetching\*(R". +See an example of Explicit fetching in \*(L"\s-1USING ALGORITHMS IN APPLICATIONS\*(R"\s0. +.PP +Prior to OpenSSL 3.0, constant method tables (such as \fBEVP_sha256()\fR) were used +directly to access methods. If you pass one of these convenience functions +to an operation the fixed methods are ignored, and only the name is used to +internally fetch methods from a provider. +.PP +If the prefetched object is not passed to operations, then any implicit +fetch will use the internally cached prefetched object, but it will +still be slower than passing the prefetched object directly. +.PP +Fetching via a provider offers more flexibility, but it is slower than the +old method, since it must search for the algorithm in all loaded providers, +and then populate the method table using provider supplied methods. +Internally OpenSSL caches similar algorithms on the first fetch +(so loading a digest caches all digests). +.PP +The following methods can be used for prefetching: +.IP "\fBEVP_MD_fetch\fR\|(3)" 4 +.IX Item "EVP_MD_fetch" +.PD 0 +.IP "\fBEVP_CIPHER_fetch\fR\|(3)" 4 +.IX Item "EVP_CIPHER_fetch" +.IP "\fBEVP_KDF_fetch\fR\|(3)" 4 +.IX Item "EVP_KDF_fetch" +.IP "\fBEVP_MAC_fetch\fR\|(3)" 4 +.IX Item "EVP_MAC_fetch" +.IP "\fBEVP_KEM_fetch\fR\|(3)" 4 +.IX Item "EVP_KEM_fetch" +.IP "\fBOSSL_ENCODER_fetch\fR\|(3)" 4 +.IX Item "OSSL_ENCODER_fetch" +.IP "\fBOSSL_DECODER_fetch\fR\|(3)" 4 +.IX Item "OSSL_DECODER_fetch" +.IP "\fBEVP_RAND_fetch\fR\|(3)" 4 +.IX Item "EVP_RAND_fetch" +.PD +.PP +The following methods are used internally when performing operations: +.IP "\fBEVP_KEYMGMT_fetch\fR\|(3)" 4 +.IX Item "EVP_KEYMGMT_fetch" +.PD 0 +.IP "\fBEVP_KEYEXCH_fetch\fR\|(3)" 4 +.IX Item "EVP_KEYEXCH_fetch" +.IP "\fBEVP_SIGNATURE_fetch\fR\|(3)" 4 +.IX Item "EVP_SIGNATURE_fetch" +.IP "\fBOSSL_STORE_LOADER_fetch\fR\|(3)" 4 +.IX Item "OSSL_STORE_LOADER_fetch" +.PD +.PP +See \fBOSSL_PROVIDER\-default\fR\|(7), <\fBOSSL_PROVIDER\-fips\fR\|(7)> and +<\fBOSSL_PROVIDER\-legacy\fR\|(7)>for a list of algorithm names that +can be fetched. +.SH "FETCHING EXAMPLES" +.IX Header "FETCHING EXAMPLES" +The following section provides a series of examples of fetching algorithm +implementations. +.PP +Fetch any available implementation of \s-1SHA2\-256\s0 in the default context. Note +that some algorithms have aliases. So \*(L"\s-1SHA256\*(R"\s0 and \*(L"\s-1SHA2\-256\*(R"\s0 are synonymous: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", NULL); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Fetch any available implementation of \s-1AES\-128\-CBC\s0 in the default context: +.PP +.Vb 3 +\& EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES\-128\-CBC", NULL); +\& ... +\& EVP_CIPHER_free(cipher); +.Ve +.PP +Fetch an implementation of \s-1SHA2\-256\s0 from the default provider in the default +context: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider=default"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Fetch an implementation of \s-1SHA2\-256\s0 that is not from the default provider in the +default context: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider!=default"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Fetch an implementation of \s-1SHA2\-256\s0 from the default provider in the specified +context: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(ctx, "SHA2\-256", "provider=default"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Load the legacy provider into the default context and then fetch an +implementation of \s-1WHIRLPOOL\s0 from it: +.PP +.Vb 2 +\& /* This only needs to be done once \- usually at application start up */ +\& OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy"); +\& +\& EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "provider=legacy"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Note that in the above example the property string \*(L"provider=legacy\*(R" is optional +since, assuming no other providers have been loaded, the only implementation of +the \*(L"whirlpool\*(R" algorithm is in the \*(L"legacy\*(R" provider. Also note that the +default provider should be explicitly loaded if it is required in addition to +other providers: +.PP +.Vb 3 +\& /* This only needs to be done once \- usually at application start up */ +\& OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy"); +\& OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default"); +\& +\& EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL); +\& EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA2\-256", NULL); +\& ... +\& EVP_MD_free(md_whirlpool); +\& EVP_MD_free(md_sha256); +.Ve +.SH "OPENSSL PROVIDERS" +.IX Header "OPENSSL PROVIDERS" +OpenSSL comes with a set of providers. +.PP +The algorithms available in each of these providers may vary due to build time +configuration options. The \fBopenssl\-list\fR\|(1) command can be used to list the +currently available algorithms. +.PP +The names of the algorithms shown from \fBopenssl\-list\fR\|(1) can be used as an +algorithm identifier to the appropriate fetching function. Also see the provider +specific manual pages linked below for further details about using the +algorithms available in each of the providers. +.PP +As well as the OpenSSL providers third parties can also implement providers. +For information on writing a provider see \fBprovider\fR\|(7). +.SS "Default provider" +.IX Subsection "Default provider" +The default provider is built in as part of the \fIlibcrypto\fR library and +contains all of the most commonly used algorithm implementations. Should it be +needed (if other providers are loaded and offer implementations of the same +algorithms), the property query string \*(L"provider=default\*(R" can be used as a +search criterion for these implementations. The default provider includes all +of the functionality in the base provider below. +.PP +If you don't load any providers at all then the \*(L"default\*(R" provider will be +automatically loaded. If you explicitly load any provider then the \*(L"default\*(R" +provider would also need to be explicitly loaded if it is required. +.PP +See \fBOSSL_PROVIDER\-default\fR\|(7). +.SS "Base provider" +.IX Subsection "Base provider" +The base provider is built in as part of the \fIlibcrypto\fR library and contains +algorithm implementations for encoding and decoding for OpenSSL keys. +Should it be needed (if other providers are loaded and offer +implementations of the same algorithms), the property query string +\&\*(L"provider=base\*(R" can be used as a search criterion for these implementations. +Some encoding and decoding algorithm implementations are not \s-1FIPS\s0 algorithm +implementations in themselves but support algorithms from the \s-1FIPS\s0 provider and +are allowed for use in \*(L"\s-1FIPS\s0 mode\*(R". The property query string \*(L"fips=yes\*(R" can be +used to select such algorithms. +.PP +See \fBOSSL_PROVIDER\-base\fR\|(7). +.SS "\s-1FIPS\s0 provider" +.IX Subsection "FIPS provider" +The \s-1FIPS\s0 provider is a dynamically loadable module, and must therefore +be loaded explicitly, either in code or through OpenSSL configuration +(see \fBconfig\fR\|(5)). It contains algorithm implementations that have been +validated according to the \s-1FIPS 140\-2\s0 standard. Should it be needed (if other +providers are loaded and offer implementations of the same algorithms), the +property query string \*(L"provider=fips\*(R" can be used as a search criterion for +these implementations. All approved algorithm implementations in the \s-1FIPS\s0 +provider can also be selected with the property \*(L"fips=yes\*(R". The \s-1FIPS\s0 provider +may also contain non-approved algorithm implementations and these can be +selected with the property \*(L"fips=no\*(R". +.PP +See \s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7) and \fBfips_module\fR\|(7). +.SS "Legacy provider" +.IX Subsection "Legacy provider" +The legacy provider is a dynamically loadable module, and must therefore +be loaded explicitly, either in code or through OpenSSL configuration +(see \fBconfig\fR\|(5)). It contains algorithm implementations that are considered +insecure, or are no longer in common use such as \s-1MD2\s0 or \s-1RC4.\s0 Should it be needed +(if other providers are loaded and offer implementations of the same algorithms), +the property \*(L"provider=legacy\*(R" can be used as a search criterion for these +implementations. +.PP +See \fBOSSL_PROVIDER\-legacy\fR\|(7). +.SS "Null provider" +.IX Subsection "Null provider" +The null provider is built in as part of the \fIlibcrypto\fR library. It contains +no algorithms in it at all. When fetching algorithms the default provider will +be automatically loaded if no other provider has been explicitly loaded. To +prevent that from happening you can explicitly load the null provider. +.PP +See \fBOSSL_PROVIDER\-null\fR\|(7). +.SH "USING ALGORITHMS IN APPLICATIONS" +.IX Header "USING ALGORITHMS IN APPLICATIONS" +Cryptographic algorithms are made available to applications through use of the +\&\*(L"\s-1EVP\*(R"\s0 APIs. Each of the various operations such as encryption, digesting, +message authentication codes, etc., have a set of \s-1EVP\s0 function calls that can +be invoked to use them. See the \fBevp\fR\|(7) page for further details. +.PP +Most of these follow a common pattern. A \*(L"context\*(R" object is first created. For +example for a digest operation you would use an \fB\s-1EVP_MD_CTX\s0\fR, and for an +encryption/decryption operation you would use an \fB\s-1EVP_CIPHER_CTX\s0\fR. The +operation is then initialised ready for use via an \*(L"init\*(R" function \- optionally +passing in a set of parameters (using the \s-1\fBOSSL_PARAM\s0\fR\|(3) type) to configure how +the operation should behave. Next data is fed into the operation in a series of +\&\*(L"update\*(R" calls. The operation is finalised using a \*(L"final\*(R" call which will +typically provide some kind of output. Finally the context is cleaned up and +freed. +.PP +The following shows a complete example for doing this process for digesting +data using \s-1SHA256.\s0 The process is similar for other operations such as +encryption/decryption, signatures, message authentication codes, etc. +.PP +.Vb 4 +\& #include <stdio.h> +\& #include <openssl/evp.h> +\& #include <openssl/bio.h> +\& #include <openssl/err.h> +\& +\& int main(void) +\& { +\& EVP_MD_CTX *ctx = NULL; +\& EVP_MD *sha256 = NULL; +\& const unsigned char msg[] = { +\& 0x00, 0x01, 0x02, 0x03 +\& }; +\& unsigned int len = 0; +\& unsigned char *outdigest = NULL; +\& int ret = 1; +\& +\& /* Create a context for the digest operation */ +\& ctx = EVP_MD_CTX_new(); +\& if (ctx == NULL) +\& goto err; +\& +\& /* +\& * Fetch the SHA256 algorithm implementation for doing the digest. We\*(Aqre +\& * using the "default" library context here (first NULL parameter), and +\& * we\*(Aqre not supplying any particular search criteria for our SHA256 +\& * implementation (second NULL parameter). Any SHA256 implementation will +\& * do. +\& * In a larger application this fetch would just be done once, and could +\& * be used for multiple calls to other operations such as EVP_DigestInit_ex(). +\& */ +\& sha256 = EVP_MD_fetch(NULL, "SHA256", NULL); +\& if (sha256 == NULL) +\& goto err; +\& +\& /* Initialise the digest operation */ +\& if (!EVP_DigestInit_ex(ctx, sha256, NULL)) +\& goto err; +\& +\& /* +\& * Pass the message to be digested. This can be passed in over multiple +\& * EVP_DigestUpdate calls if necessary +\& */ +\& if (!EVP_DigestUpdate(ctx, msg, sizeof(msg))) +\& goto err; +\& +\& /* Allocate the output buffer */ +\& outdigest = OPENSSL_malloc(EVP_MD_get_size(sha256)); +\& if (outdigest == NULL) +\& goto err; +\& +\& /* Now calculate the digest itself */ +\& if (!EVP_DigestFinal_ex(ctx, outdigest, &len)) +\& goto err; +\& +\& /* Print out the digest result */ +\& BIO_dump_fp(stdout, outdigest, len); +\& +\& ret = 0; +\& +\& err: +\& /* Clean up all the resources we allocated */ +\& OPENSSL_free(outdigest); +\& EVP_MD_free(sha256); +\& EVP_MD_CTX_free(ctx); +\& if (ret != 0) +\& ERR_print_errors_fp(stderr); +\& return ret; +\& } +.Ve +.SH "CONFIGURATION" +.IX Header "CONFIGURATION" +By default OpenSSL will load a configuration file when it is first used. This +will set up various configuration settings within the default library context. +Applications that create their own library contexts may optionally configure +them with a config file using the \fBOSSL_LIB_CTX_load_config\fR\|(3) function. +.PP +The configuration file can be used to automatically load providers and set up +default property query strings. +.PP +For information on the OpenSSL configuration file format see \fBconfig\fR\|(5). +.SH "ENCODING AND DECODING KEYS" +.IX Header "ENCODING AND DECODING KEYS" +Many algorithms require the use of a key. Keys can be generated dynamically +using the \s-1EVP\s0 APIs (for example see \fBEVP_PKEY_Q_keygen\fR\|(3)). However it is often +necessary to save or load keys (or their associated parameters) to or from some +external format such as \s-1PEM\s0 or \s-1DER\s0 (see \fBopenssl\-glossary\fR\|(7)). OpenSSL uses +encoders and decoders to perform this task. +.PP +Encoders and decoders are just algorithm implementations in the same way as +any other algorithm implementation in OpenSSL. They are implemented by +providers. The OpenSSL encoders and decoders are available in the default +provider. They are also duplicated in the base provider. +.PP +For information about encoders see \fBOSSL_ENCODER_CTX_new_for_pkey\fR\|(3). For +information about decoders see \fBOSSL_DECODER_CTX_new_for_pkey\fR\|(3). +.SH "LIBRARY CONVENTIONS" +.IX Header "LIBRARY CONVENTIONS" +Many OpenSSL functions that \*(L"get\*(R" or \*(L"set\*(R" a value follow a naming convention +using the numbers \fB0\fR and \fB1\fR, i.e. \*(L"get0\*(R", \*(L"get1\*(R", \*(L"set0\*(R" and \*(L"set1\*(R". This +can also apply to some functions that \*(L"add\*(R" a value to an existing set, i.e. +\&\*(L"add0\*(R" and \*(L"add1\*(R". +.PP +For example the functions: +.PP +.Vb 2 +\& int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev); +\& int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj); +.Ve +.PP +In the \fB0\fR version the ownership of the object is passed to (for an add or set) +or retained by (for a get) the parent object. For example after calling the +\&\fBX509_CRL_add0_revoked()\fR function above, ownership of the \fIrev\fR object is passed +to the \fIcrl\fR object. Therefore, after calling this function \fIrev\fR should not +be freed directly. It will be freed implicitly when \fIcrl\fR is freed. +.PP +In the \fB1\fR version the ownership of the object is not passed to or retained by +the parent object. Instead a copy or \*(L"up ref\*(R" of the object is performed. So +after calling the \fBX509_add1_trust_object()\fR function above the application will +still be responsible for freeing the \fIobj\fR value where appropriate. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\fR\|(1), \fBssl\fR\|(7), \fBevp\fR\|(7), \s-1\fBOSSL_LIB_CTX\s0\fR\|(3), \fBopenssl\-threads\fR\|(7), +\&\fBproperty\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7), \fBOSSL_PROVIDER\-base\fR\|(7), +\&\s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7), \fBOSSL_PROVIDER\-null\fR\|(7), +\&\fBopenssl\-glossary\fR\|(7), \fBprovider\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2000\-2023 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>. diff --git a/secure/lib/libcrypto/man/man7/ct.7 b/secure/lib/libcrypto/man/man7/ct.7 index 46e070fe722b..6b73b9cd7cb5 100644 --- a/secure/lib/libcrypto/man/man7/ct.7 +++ b/secure/lib/libcrypto/man/man7/ct.7 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .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 \{\ @@ -132,8 +130,8 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "CT 7" -.TH CT 7 "2022-06-21" "1.1.1p" "OpenSSL" +.IX Title "CT 7ossl" +.TH CT 7ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -179,7 +177,7 @@ The ct library was added in OpenSSL 1.1.0. .IX Header "COPYRIGHT" Copyright 2016\-2017 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +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>. diff --git a/secure/lib/libcrypto/man/man7/des_modes.7 b/secure/lib/libcrypto/man/man7/des_modes.7 index abf5e44467f1..2caeffd12c9c 100644 --- a/secure/lib/libcrypto/man/man7/des_modes.7 +++ b/secure/lib/libcrypto/man/man7/des_modes.7 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .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 \{\ @@ -132,8 +130,8 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "DES_MODES 7" -.TH DES_MODES 7 "2022-06-21" "1.1.1p" "OpenSSL" +.IX Title "DES_MODES 7ossl" +.TH DES_MODES 7ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -289,7 +287,7 @@ it to: .IX Header "COPYRIGHT" Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +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>. diff --git a/secure/lib/libcrypto/man/man7/evp.7 b/secure/lib/libcrypto/man/man7/evp.7 index 3cf105b08102..68d986344cf7 100644 --- a/secure/lib/libcrypto/man/man7/evp.7 +++ b/secure/lib/libcrypto/man/man7/evp.7 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .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 \{\ @@ -132,8 +130,8 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "EVP 7" -.TH EVP 7 "2022-06-21" "1.1.1p" "OpenSSL" +.IX Title "EVP 7ossl" +.TH EVP 7ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -166,10 +164,11 @@ The \fB\s-1EVP_PKEY\s0\fR\fI\s-1XXX\s0\fR functions provide a high-level interfa asymmetric algorithms. To create a new \s-1EVP_PKEY\s0 see \&\fBEVP_PKEY_new\fR\|(3). EVP_PKEYs can be associated with a private key of a particular algorithm by using the functions -described on the \fBEVP_PKEY_set1_RSA\fR\|(3) page, or +described on the \fBEVP_PKEY_fromdata\fR\|(3) page, or new keys can be generated using \fBEVP_PKEY_keygen\fR\|(3). -EVP_PKEYs can be compared using \fBEVP_PKEY_cmp\fR\|(3), or printed using -\&\fBEVP_PKEY_print_private\fR\|(3). +EVP_PKEYs can be compared using \fBEVP_PKEY_eq\fR\|(3), or printed using +\&\fBEVP_PKEY_print_private\fR\|(3). \fBEVP_PKEY_todata\fR\|(3) can be used to convert a +key back into an \s-1\fBOSSL_PARAM\s0\fR\|(3) array. .PP The \s-1EVP_PKEY\s0 functions support the full range of asymmetric algorithm operations: .IP "For key agreement see \fBEVP_PKEY_derive\fR\|(3)" 4 @@ -215,7 +214,8 @@ using the high-level interface. \&\fBEVP_VerifyInit\fR\|(3), \&\fBEVP_EncodeInit\fR\|(3), \&\fBEVP_PKEY_new\fR\|(3), -\&\fBEVP_PKEY_set1_RSA\fR\|(3), +\&\fBEVP_PKEY_fromdata\fR\|(3), +\&\fBEVP_PKEY_todata\fR\|(3), \&\fBEVP_PKEY_keygen\fR\|(3), \&\fBEVP_PKEY_print_private\fR\|(3), \&\fBEVP_PKEY_decrypt\fR\|(3), @@ -228,9 +228,9 @@ using the high-level interface. \&\fBENGINE_by_id\fR\|(3) .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +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>. diff --git a/secure/lib/libcrypto/man/man7/fips_module.7 b/secure/lib/libcrypto/man/man7/fips_module.7 new file mode 100644 index 000000000000..313d92e192b4 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/fips_module.7 @@ -0,0 +1,615 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "FIPS_MODULE 7ossl" +.TH FIPS_MODULE 7ossl "2023-09-19" "3.0.11" "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" +fips_module \- OpenSSL fips module guide +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +See the individual manual pages for details. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This guide details different ways that OpenSSL can be used in conjunction +with the \s-1FIPS\s0 module. Which is the correct approach to use will depend on your +own specific circumstances and what you are attempting to achieve. +.PP +For information related to installing the \s-1FIPS\s0 module see +<https://github.com/openssl/openssl/blob/master/README\-FIPS.md>. +.PP +Note that the old functions \fBFIPS_mode()\fR and \fBFIPS_mode_set()\fR are no longer +present so you must remove them from your application if you use them. +.PP +Applications written to use the OpenSSL 3.0 \s-1FIPS\s0 module should not use any +legacy APIs or features that avoid the \s-1FIPS\s0 module. Specifically this includes: +.IP "\(bu" 4 +Low level cryptographic APIs (use the high level APIs, such as \s-1EVP,\s0 instead) +.IP "\(bu" 4 +Engines +.IP "\(bu" 4 +Any functions that create or modify custom \*(L"\s-1METHODS\*(R"\s0 (for example +\&\fBEVP_MD_meth_new()\fR, \fBEVP_CIPHER_meth_new()\fR, \fBEVP_PKEY_meth_new()\fR, \fBRSA_meth_new()\fR, +\&\fBEC_KEY_METHOD_new()\fR, etc.) +.PP +All of the above APIs are deprecated in OpenSSL 3.0 \- so a simple rule is to +avoid using all deprecated functions. See \fBmigration_guide\fR\|(7) for a list of +deprecated functions. +.SS "Making all applications use the \s-1FIPS\s0 module by default" +.IX Subsection "Making all applications use the FIPS module by default" +One simple approach is to cause all applications that are using OpenSSL to only +use the \s-1FIPS\s0 module for cryptographic algorithms by default. +.PP +This approach can be done purely via configuration. As long as applications are +built and linked against OpenSSL 3.0 and do not override the loading of the +default config file or its settings then they can automatically start using the +\&\s-1FIPS\s0 module without the need for any further code changes. +.PP +To do this the default OpenSSL config file will have to be modified. The +location of this config file will depend on the platform, and any options that +were given during the build process. You can check the location of the config +file by running this command: +.PP +.Vb 2 +\& $ openssl version \-d +\& OPENSSLDIR: "/etc/ssl" +.Ve +.PP +Caution: Many Operating Systems install OpenSSL by default. It is a common error +to not have the correct version of OpenSSL in your \f(CW$PATH\fR. Check that you are +running an OpenSSL 3.0 version like this: +.PP +.Vb 2 +\& $ openssl version \-v +\& OpenSSL 3.0.0\-dev xx XXX xxxx (Library: OpenSSL 3.0.0\-dev xx XXX xxxx) +.Ve +.PP +The \fB\s-1OPENSSLDIR\s0\fR value above gives the directory name for where the default +config file is stored. So in this case the default config file will be called +\&\fI/etc/ssl/openssl.cnf\fR. +.PP +Edit the config file to add the following lines near the beginning: +.PP +.Vb 2 +\& config_diagnostics = 1 +\& openssl_conf = openssl_init +\& +\& .include /etc/ssl/fipsmodule.cnf +\& +\& [openssl_init] +\& providers = provider_sect +\& +\& [provider_sect] +\& fips = fips_sect +\& base = base_sect +\& +\& [base_sect] +\& activate = 1 +.Ve +.PP +Obviously the include file location above should match the path and name of the +\&\s-1FIPS\s0 module config file that you installed earlier. +See <https://github.com/openssl/openssl/blob/master/README\-FIPS.md>. +.PP +For \s-1FIPS\s0 usage, it is recommended that the \fBconfig_diagnostics\fR option is +enabled to prevent accidental use of non-FIPS validated algorithms via broken +or mistaken configuration. See \fBconfig\fR\|(5). +.PP +Any applications that use OpenSSL 3.0 and are started after these changes are +made will start using only the \s-1FIPS\s0 module unless those applications take +explicit steps to avoid this default behaviour. Note that this configuration +also activates the \*(L"base\*(R" provider. The base provider does not include any +cryptographic algorithms (and therefore does not impact the validation status of +any cryptographic operations), but does include other supporting algorithms that +may be required. It is designed to be used in conjunction with the \s-1FIPS\s0 module. +.PP +This approach has the primary advantage that it is simple, and no code changes +are required in applications in order to benefit from the \s-1FIPS\s0 module. There are +some disadvantages to this approach: +.IP "\(bu" 4 +You may not want all applications to use the \s-1FIPS\s0 module. +.Sp +It may be the case that some applications should and some should not use the +\&\s-1FIPS\s0 module. +.IP "\(bu" 4 +If applications take explicit steps to not load the default config file or +set different settings. +.Sp +This method will not work for these cases. +.IP "\(bu" 4 +The algorithms available in the \s-1FIPS\s0 module are a subset of the algorithms +that are available in the default OpenSSL Provider. +.Sp +If any applications attempt to use any algorithms that are not present, +then they will fail. +.IP "\(bu" 4 +Usage of certain deprecated APIs avoids the use of the \s-1FIPS\s0 module. +.Sp +If any applications use those APIs then the \s-1FIPS\s0 module will not be used. +.SS "Selectively making applications use the \s-1FIPS\s0 module by default" +.IX Subsection "Selectively making applications use the FIPS module by default" +A variation on the above approach is to do the same thing on an individual +application basis. The default OpenSSL config file depends on the compiled in +value for \fB\s-1OPENSSLDIR\s0\fR as described in the section above. However it is also +possible to override the config file to be used via the \fB\s-1OPENSSL_CONF\s0\fR +environment variable. For example the following, on Unix, will cause the +application to be executed with a non-standard config file location: +.PP +.Vb 1 +\& $ OPENSSL_CONF=/my/nondefault/openssl.cnf myapplication +.Ve +.PP +Using this mechanism you can control which config file is loaded (and hence +whether the \s-1FIPS\s0 module is loaded) on an application by application basis. +.PP +This removes the disadvantage listed above that you may not want all +applications to use the \s-1FIPS\s0 module. All the other advantages and disadvantages +still apply. +.SS "Programmatically loading the \s-1FIPS\s0 module (default library context)" +.IX Subsection "Programmatically loading the FIPS module (default library context)" +Applications may choose to load the \s-1FIPS\s0 provider explicitly rather than relying +on config to do this. The config file is still necessary in order to hold the +\&\s-1FIPS\s0 module config data (such as its self test status and integrity data). But +in this case we do not automatically activate the \s-1FIPS\s0 provider via that config +file. +.PP +To do things this way configure as per +\&\*(L"Making all applications use the \s-1FIPS\s0 module by default\*(R" above, but edit the +\&\fIfipsmodule.cnf\fR file to remove or comment out the line which says +\&\f(CW\*(C`activate = 1\*(C'\fR (note that setting this value to 0 is \fInot\fR sufficient). +This means all the required config information will be available to load the +\&\s-1FIPS\s0 module, but it is not automatically loaded when the application starts. The +\&\s-1FIPS\s0 provider can then be loaded programmatically like this: +.PP +.Vb 1 +\& #include <openssl/provider.h> +\& +\& int main(void) +\& { +\& OSSL_PROVIDER *fips; +\& OSSL_PROVIDER *base; +\& +\& fips = OSSL_PROVIDER_load(NULL, "fips"); +\& if (fips == NULL) { +\& printf("Failed to load FIPS provider\en"); +\& exit(EXIT_FAILURE); +\& } +\& base = OSSL_PROVIDER_load(NULL, "base"); +\& if (base == NULL) { +\& OSSL_PROVIDER_unload(fips); +\& printf("Failed to load base provider\en"); +\& exit(EXIT_FAILURE); +\& } +\& +\& /* Rest of application */ +\& +\& OSSL_PROVIDER_unload(base); +\& OSSL_PROVIDER_unload(fips); +\& exit(EXIT_SUCCESS); +\& } +.Ve +.PP +Note that this should be one of the first things that you do in your +application. If any OpenSSL functions get called that require the use of +cryptographic functions before this occurs then, if no provider has yet been +loaded, then the default provider will be automatically loaded. If you then +later explicitly load the \s-1FIPS\s0 provider then you will have both the \s-1FIPS\s0 and the +default provider loaded at the same time. It is undefined which implementation +of an algorithm will be used if multiple implementations are available and you +have not explicitly specified via a property query (see below) which one should +be used. +.PP +Also note that in this example we have additionally loaded the \*(L"base\*(R" provider. +This loads a sub-set of algorithms that are also available in the default +provider \- specifically non cryptographic ones which may be used in conjunction +with the \s-1FIPS\s0 provider. For example this contains algorithms for encoding and +decoding keys. If you decide not to load the default provider then you +will usually want to load the base provider instead. +.PP +In this example we are using the \*(L"default\*(R" library context. OpenSSL functions +operate within the scope of a library context. If no library context is +explicitly specified then the default library context is used. For further +details about library contexts see the \s-1\fBOSSL_LIB_CTX\s0\fR\|(3) man page. +.SS "Loading the \s-1FIPS\s0 module at the same time as other providers" +.IX Subsection "Loading the FIPS module at the same time as other providers" +It is possible to have the \s-1FIPS\s0 provider and other providers (such as the +default provider) all loaded at the same time into the same library context. You +can use a property query string during algorithm fetches to specify which +implementation you would like to use. +.PP +For example to fetch an implementation of \s-1SHA256\s0 which conforms to \s-1FIPS\s0 +standards you can specify the property query \f(CW\*(C`fips=yes\*(C'\fR like this: +.PP +.Vb 1 +\& EVP_MD *sha256; +\& +\& sha256 = EVP_MD_fetch(NULL, "SHA2\-256", "fips=yes"); +.Ve +.PP +If no property query is specified, or more than one implementation matches the +property query then it is undefined which implementation of a particular +algorithm will be returned. +.PP +This example shows an explicit request for an implementation of \s-1SHA256\s0 from the +default provider: +.PP +.Vb 1 +\& EVP_MD *sha256; +\& +\& sha256 = EVP_MD_fetch(NULL, "SHA2\-256", "provider=default"); +.Ve +.PP +It is also possible to set a default property query string. The following +example sets the default property query of \f(CW\*(C`fips=yes\*(C'\fR for all fetches within +the default library context: +.PP +.Vb 1 +\& EVP_set_default_properties(NULL, "fips=yes"); +.Ve +.PP +If a fetch function has both an explicit property query specified, and a +default property query is defined then the two queries are merged together and +both apply. The local property query overrides the default properties if the +same property name is specified in both. +.PP +There are two important built-in properties that you should be aware of: +.PP +The \*(L"provider\*(R" property enables you to specify which provider you want an +implementation to be fetched from, e.g. \f(CW\*(C`provider=default\*(C'\fR or \f(CW\*(C`provider=fips\*(C'\fR. +All algorithms implemented in a provider have this property set on them. +.PP +There is also the \f(CW\*(C`fips\*(C'\fR property. All \s-1FIPS\s0 algorithms match against the +property query \f(CW\*(C`fips=yes\*(C'\fR. There are also some non-cryptographic algorithms +available in the default and base providers that also have the \f(CW\*(C`fips=yes\*(C'\fR +property defined for them. These are the encoder and decoder algorithms that +can (for example) be used to write out a key generated in the \s-1FIPS\s0 provider to a +file. The encoder and decoder algorithms are not in the \s-1FIPS\s0 module itself but +are allowed to be used in conjunction with the \s-1FIPS\s0 algorithms. +.PP +It is possible to specify default properties within a config file. For example +the following config file automatically loads the default and \s-1FIPS\s0 providers and +sets the default property value to be \f(CW\*(C`fips=yes\*(C'\fR. Note that this config file +does not load the \*(L"base\*(R" provider. All supporting algorithms that are in \*(L"base\*(R" +are also in \*(L"default\*(R", so it is unnecessary in this case: +.PP +.Vb 2 +\& config_diagnostics = 1 +\& openssl_conf = openssl_init +\& +\& .include /etc/ssl/fipsmodule.cnf +\& +\& [openssl_init] +\& providers = provider_sect +\& alg_section = algorithm_sect +\& +\& [provider_sect] +\& fips = fips_sect +\& default = default_sect +\& +\& [default_sect] +\& activate = 1 +\& +\& [algorithm_sect] +\& default_properties = fips=yes +.Ve +.SS "Programmatically loading the \s-1FIPS\s0 module (nondefault library context)" +.IX Subsection "Programmatically loading the FIPS module (nondefault library context)" +In addition to using properties to separate usage of the \s-1FIPS\s0 module from other +usages this can also be achieved using library contexts. In this example we +create two library contexts. In one we assume the existence of a config file +called \fIopenssl\-fips.cnf\fR that automatically loads and configures the \s-1FIPS\s0 and +base providers. The other library context will just use the default provider. +.PP +.Vb 4 +\& OSSL_LIB_CTX *fips_libctx, *nonfips_libctx; +\& OSSL_PROVIDER *defctxnull = NULL; +\& EVP_MD *fipssha256 = NULL, *nonfipssha256 = NULL; +\& int ret = 1; +\& +\& /* +\& * Create two nondefault library contexts. One for fips usage and +\& * one for non\-fips usage +\& */ +\& fips_libctx = OSSL_LIB_CTX_new(); +\& nonfips_libctx = OSSL_LIB_CTX_new(); +\& if (fips_libctx == NULL || nonfips_libctx == NULL) +\& goto err; +\& +\& /* Prevent anything from using the default library context */ +\& defctxnull = OSSL_PROVIDER_load(NULL, "null"); +\& +\& /* +\& * Load config file for the FIPS library context. We assume that +\& * this config file will automatically activate the FIPS and base +\& * providers so we don\*(Aqt need to explicitly load them here. +\& */ +\& if (!OSSL_LIB_CTX_load_config(fips_libctx, "openssl\-fips.cnf")) +\& goto err; +\& +\& /* +\& * We don\*(Aqt need to do anything special to load the default +\& * provider into nonfips_libctx. This happens automatically if no +\& * other providers are loaded. +\& * Because we don\*(Aqt call OSSL_LIB_CTX_load_config() explicitly for +\& * nonfips_libctx it will just use the default config file. +\& */ +\& +\& /* As an example get some digests */ +\& +\& /* Get a FIPS validated digest */ +\& fipssha256 = EVP_MD_fetch(fips_libctx, "SHA2\-256", NULL); +\& if (fipssha256 == NULL) +\& goto err; +\& +\& /* Get a non\-FIPS validated digest */ +\& nonfipssha256 = EVP_MD_fetch(nonfips_libctx, "SHA2\-256", NULL); +\& if (nonfipssha256 == NULL) +\& goto err; +\& +\& /* Use the digests */ +\& +\& printf("Success\en"); +\& ret = 0; +\& +\& err: +\& EVP_MD_free(fipssha256); +\& EVP_MD_free(nonfipssha256); +\& OSSL_LIB_CTX_free(fips_libctx); +\& OSSL_LIB_CTX_free(nonfips_libctx); +\& OSSL_PROVIDER_unload(defctxnull); +\& +\& return ret; +.Ve +.PP +Note that we have made use of the special \*(L"null\*(R" provider here which we load +into the default library context. We could have chosen to use the default +library context for \s-1FIPS\s0 usage, and just create one additional library context +for other usages \- or vice versa. However if code has not been converted to use +library contexts then the default library context will be automatically used. +This could be the case for your own existing applications as well as certain +parts of OpenSSL itself. Not all parts of OpenSSL are library context aware. If +this happens then you could \*(L"accidentally\*(R" use the wrong library context for a +particular operation. To be sure this doesn't happen you can load the \*(L"null\*(R" +provider into the default library context. Because a provider has been +explicitly loaded, the default provider will not automatically load. This means +code using the default context by accident will fail because no algorithms will +be available. +.PP +See \*(L"Library Context\*(R" in \fBmigration_guide\fR\|(7) for additional information about the +Library Context. +.SS "Using Encoders and Decoders with the \s-1FIPS\s0 module" +.IX Subsection "Using Encoders and Decoders with the FIPS module" +Encoders and decoders are used to read and write keys or parameters from or to +some external format (for example a \s-1PEM\s0 file). If your application generates +keys or parameters that then need to be written into \s-1PEM\s0 or \s-1DER\s0 format +then it is likely that you will need to use an encoder to do this. Similarly +you need a decoder to read previously saved keys and parameters. In most cases +this will be invisible to you if you are using APIs that existed in +OpenSSL 1.1.1 or earlier such as \fBi2d_PrivateKey\fR\|(3). However the appropriate +encoder/decoder will need to be available in the library context associated with +the key or parameter object. The built-in OpenSSL encoders and decoders are +implemented in both the default and base providers and are not in the \s-1FIPS\s0 +module boundary. However since they are not cryptographic algorithms themselves +it is still possible to use them in conjunction with the \s-1FIPS\s0 module, and +therefore these encoders/decoders have the \f(CW\*(C`fips=yes\*(C'\fR property against them. +You should ensure that either the default or base provider is loaded into the +library context in this case. +.SS "Using the \s-1FIPS\s0 module in \s-1SSL/TLS\s0" +.IX Subsection "Using the FIPS module in SSL/TLS" +Writing an application that uses libssl in conjunction with the \s-1FIPS\s0 module is +much the same as writing a normal libssl application. If you are using global +properties and the default library context to specify usage of \s-1FIPS\s0 validated +algorithms then this will happen automatically for all cryptographic algorithms +in libssl. If you are using a nondefault library context to load the \s-1FIPS\s0 +provider then you can supply this to libssl using the function +\&\fBSSL_CTX_new_ex\fR\|(3). This works as a drop in replacement for the function +\&\fBSSL_CTX_new\fR\|(3) except it provides you with the capability to specify the +library context to be used. You can also use the same function to specify +libssl specific properties to use. +.PP +In this first example we create two \s-1SSL_CTX\s0 objects using two different library +contexts. +.PP +.Vb 11 +\& /* +\& * We assume that a nondefault library context with the FIPS +\& * provider loaded has been created called fips_libctx. +\& */ +\& SSL_CTX *fips_ssl_ctx = SSL_CTX_new_ex(fips_libctx, NULL, TLS_method()); +\& /* +\& * We assume that a nondefault library context with the default +\& * provider loaded has been created called non_fips_libctx. +\& */ +\& SSL_CTX *non_fips_ssl_ctx = SSL_CTX_new_ex(non_fips_libctx, NULL, +\& TLS_method()); +.Ve +.PP +In this second example we create two \s-1SSL_CTX\s0 objects using different properties +to specify \s-1FIPS\s0 usage: +.PP +.Vb 10 +\& /* +\& * The "fips=yes" property includes all FIPS approved algorithms +\& * as well as encoders from the default provider that are allowed +\& * to be used. The NULL below indicates that we are using the +\& * default library context. +\& */ +\& SSL_CTX *fips_ssl_ctx = SSL_CTX_new_ex(NULL, "fips=yes", TLS_method()); +\& /* +\& * The "provider!=fips" property allows algorithms from any +\& * provider except the FIPS provider +\& */ +\& SSL_CTX *non_fips_ssl_ctx = SSL_CTX_new_ex(NULL, "provider!=fips", +\& TLS_method()); +.Ve +.SS "Confirming that an algorithm is being provided by the \s-1FIPS\s0 module" +.IX Subsection "Confirming that an algorithm is being provided by the FIPS module" +A chain of links needs to be followed to go from an algorithm instance to the +provider that implements it. The process is similar for all algorithms. Here the +example of a digest is used. +.PP +To go from an \fB\s-1EVP_MD_CTX\s0\fR to an \fB\s-1EVP_MD\s0\fR, use \fBEVP_MD_CTX_md\fR\|(3) . +To go from the \fB\s-1EVP_MD\s0\fR to its \fB\s-1OSSL_PROVIDER\s0\fR, +use \fBEVP_MD_get0_provider\fR\|(3). +To extract the name from the \fB\s-1OSSL_PROVIDER\s0\fR, use +\&\fBOSSL_PROVIDER_get0_name\fR\|(3). +.SH "NOTES" +.IX Header "NOTES" +Some released versions of OpenSSL do not include a validated +\&\s-1FIPS\s0 provider. To determine which versions have undergone +the validation process, please refer to the +OpenSSL Downloads page <https://www.openssl.org/source/>. If you +require FIPS-approved functionality, it is essential to build your \s-1FIPS\s0 +provider using one of the validated versions listed there. Normally, +it is possible to utilize a \s-1FIPS\s0 provider constructed from one of the +validated versions alongside \fIlibcrypto\fR and \fIlibssl\fR compiled from any +release within the same major release series. This flexibility enables +you to address bug fixes and CVEs that fall outside the \s-1FIPS\s0 boundary. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBmigration_guide\fR\|(7), \fBcrypto\fR\|(7), \fBfips_config\fR\|(5), +<https://www.openssl.org/source/> +.SH "HISTORY" +.IX Header "HISTORY" +The \s-1FIPS\s0 module guide was created for use with the new \s-1FIPS\s0 provider +in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021\-2023 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>. diff --git a/secure/lib/libcrypto/man/man7/life_cycle-cipher.7 b/secure/lib/libcrypto/man/man7/life_cycle-cipher.7 new file mode 100644 index 000000000000..73e9ba528c9a --- /dev/null +++ b/secure/lib/libcrypto/man/man7/life_cycle-cipher.7 @@ -0,0 +1,281 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "LIFE_CYCLE-CIPHER 7ossl" +.TH LIFE_CYCLE-CIPHER 7ossl "2023-09-19" "3.0.11" "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" +life_cycle\-cipher \- The cipher algorithm life\-cycle +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +All symmetric ciphers (CIPHERs) go through a number of stages in their +life-cycle: +.IP "start" 4 +.IX Item "start" +This state represents the \s-1CIPHER\s0 before it has been allocated. It is the +starting state for any life-cycle transitions. +.IP "newed" 4 +.IX Item "newed" +This state represents the \s-1CIPHER\s0 after it has been allocated. +.IP "initialised" 4 +.IX Item "initialised" +These states represent the \s-1CIPHER\s0 when it is set up and capable of processing +input. There are three possible initialised states: +.RS 4 +.IP "initialised using EVP_CipherInit" 4 +.IX Item "initialised using EVP_CipherInit" +.PD 0 +.IP "initialised for decryption using EVP_DecryptInit" 4 +.IX Item "initialised for decryption using EVP_DecryptInit" +.IP "initialised for encryption using EVP_EncryptInit" 4 +.IX Item "initialised for encryption using EVP_EncryptInit" +.RE +.RS 4 +.RE +.IP "updated" 4 +.IX Item "updated" +.PD +These states represent the \s-1CIPHER\s0 when it is set up and capable of processing +additional input or generating output. The three possible states directly +correspond to those for initialised above. The three different streams should +not be mixed. +.IP "finaled" 4 +.IX Item "finaled" +This state represents the \s-1CIPHER\s0 when it has generated output. +.IP "freed" 4 +.IX Item "freed" +This state is entered when the \s-1CIPHER\s0 is freed. It is the terminal state +for all life-cycle transitions. +.SS "State Transition Diagram" +.IX Subsection "State Transition Diagram" +The usual life-cycle of a \s-1CIPHER\s0 is illustrated: + +---------------------------+ + | | + | start | + | | + +---------------------------+ + - - - - - - - - - - - - - + + | ' any of the initialised ' + | EVP_CIPHER_CTX_new ' updated or finaled states ' + v ' ' + +---------------------------+ + - - - - - - - - - - - - - + + | | | + | newed | | EVP_CIPHER_CTX_reset + | | <----+ + +---------------------------+ + | | | + +---------+ | +---------+ + EVP_DecryptInit | | EVP_CipherInit | EVP_EncryptInit + v v v + +---------------------------+ +---------------------------+ +---------------------------+ + | | | | | | + | initialised | | initialised | | initialised | + | for decryption | | | | for encryption | + +---------------------------+ +---------------------------+ +---------------------------+ + | | | + | EVP_DecryptUpdate | EVP_CipherUpdate EVP_EncryptUpdate | + | v | + | +---------------------------+ | + | | |--------------------+ | + | | updated | EVP_CipherUpdate | | + | | | <------------------+ | + v +---------------------------+ v + +---------------------------+ | +---------------------------+ + | |---------------------+ | | | + | updated | EVP_DecryptUpdate | | | updated |------+ + | for decryption | <-------------------+ | | for encryption | | + +---------------------------+ | +---------------------------+ | + | EVP_CipherFinal | | ^ | + +-------+ | +--------+ | | + EVP_DecryptFinal | | | EVP_EncryptFinal +-------------------+ + v v v EVP_EncryptUpdate + +---------------------------+ + | |-----------------------------+ + | finaled | | + | | <---------------------------+ + +---------------------------+ EVP_CIPHER_CTX_get_params + | (AEAD encryption) + | EVP_CIPHER_CTX_free + v + +---------------------------+ + | | + | freed | + | | + +---------------------------+ +.SS "Formal State Transitions" +.IX Subsection "Formal State Transitions" +This section defines all of the legal state transitions. +This is the canonical list. + Function Call ---------------------------------------------- Current State ----------------------------------------------- + start newed initialised updated finaled initialised updated initialised updated freed + decryption decryption encryption encryption + EVP_CIPHER_CTX_new newed + EVP_CipherInit initialised initialised initialised initialised initialised initialised initialised initialised + EVP_DecryptInit initialised initialised initialised initialised initialised initialised initialised initialised + decryption decryption decryption decryption decryption decryption decryption decryption + EVP_EncryptInit initialised initialised initialised initialised initialised initialised initialised initialised + encryption encryption encryption encryption encryption encryption encryption encryption + EVP_CipherUpdate updated updated + EVP_DecryptUpdate updated updated + decryption decryption + EVP_EncryptUpdate updated updated + encryption encryption + EVP_CipherFinal finaled + EVP_DecryptFinal finaled + EVP_EncryptFinal finaled + EVP_CIPHER_CTX_free freed freed freed freed freed freed freed freed freed + EVP_CIPHER_CTX_reset newed newed newed newed newed newed newed newed + EVP_CIPHER_CTX_get_params newed initialised updated initialised updated initialised updated + decryption decryption encryption encryption + EVP_CIPHER_CTX_set_params newed initialised updated initialised updated initialised updated + decryption decryption encryption encryption + EVP_CIPHER_CTX_gettable_params newed initialised updated initialised updated initialised updated + decryption decryption encryption encryption + EVP_CIPHER_CTX_settable_params newed initialised updated initialised updated initialised updated + decryption decryption encryption encryption +.SH "NOTES" +.IX Header "NOTES" +At some point the \s-1EVP\s0 layer will begin enforcing the transitions described +herein. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBEVP_EncryptInit\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021 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>. diff --git a/secure/lib/libcrypto/man/man7/life_cycle-digest.7 b/secure/lib/libcrypto/man/man7/life_cycle-digest.7 new file mode 100644 index 000000000000..e5f890fa0179 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/life_cycle-digest.7 @@ -0,0 +1,233 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "LIFE_CYCLE-DIGEST 7ossl" +.TH LIFE_CYCLE-DIGEST 7ossl "2023-09-19" "3.0.11" "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" +life_cycle\-digest \- The digest algorithm life\-cycle +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +All message digests (MDs) go through a number of stages in their life-cycle: +.IP "start" 4 +.IX Item "start" +This state represents the \s-1MD\s0 before it has been allocated. It is the +starting state for any life-cycle transitions. +.IP "newed" 4 +.IX Item "newed" +This state represents the \s-1MD\s0 after it has been allocated. +.IP "initialised" 4 +.IX Item "initialised" +This state represents the \s-1MD\s0 when it is set up and capable of processing +input. +.IP "updated" 4 +.IX Item "updated" +This state represents the \s-1MD\s0 when it is set up and capable of processing +additional input or generating output. +.IP "finaled" 4 +.IX Item "finaled" +This state represents the \s-1MD\s0 when it has generated output. +.IP "freed" 4 +.IX Item "freed" +This state is entered when the \s-1MD\s0 is freed. It is the terminal state +for all life-cycle transitions. +.SS "State Transition Diagram" +.IX Subsection "State Transition Diagram" +The usual life-cycle of a \s-1MD\s0 is illustrated: + +-------------------+ + | start | + +-------------------+ + | + | EVP_MD_CTX_new + v + +-------------------+ EVP_MD_CTX_reset + | newed | <------------------------------+ + +-------------------+ | + | | + | EVP_DigestInit | + v | + +-------------------+ | + +--> | initialised | <+ EVP_DigestInit | + | +-------------------+ | | + | | | EVP_DigestUpdate | + | | EVP_DigestUpdate | +------------------+ | + | v | v | | + | +------------------------------------------------+ | + EVP_DigestInit | | updated | --+ + | +------------------------------------------------+ | + | | | | + | | EVP_DigestFinal | EVP_DigestFinalXOF | + | v v | + | +------------------------------------------------+ | + +--- | finaled | --+ + +------------------------------------------------+ + | + | EVP_MD_CTX_free + v + +-------------------+ + | freed | + +-------------------+ +.SS "Formal State Transitions" +.IX Subsection "Formal State Transitions" +This section defines all of the legal state transitions. +This is the canonical list. + Function Call --------------------- Current State ---------------------- + start newed initialised updated finaled freed + EVP_MD_CTX_new newed + EVP_DigestInit initialised initialised initialised initialised + EVP_DigestUpdate updated updated + EVP_DigestFinal finaled + EVP_DigestFinalXOF finaled + EVP_MD_CTX_free freed freed freed freed freed + EVP_MD_CTX_reset newed newed newed newed + EVP_MD_CTX_get_params newed initialised updated + EVP_MD_CTX_set_params newed initialised updated + EVP_MD_CTX_gettable_params newed initialised updated + EVP_MD_CTX_settable_params newed initialised updated +.SH "NOTES" +.IX Header "NOTES" +At some point the \s-1EVP\s0 layer will begin enforcing the transitions described +herein. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \fBEVP_DigestInit\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021 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>. diff --git a/secure/lib/libcrypto/man/man7/life_cycle-kdf.7 b/secure/lib/libcrypto/man/man7/life_cycle-kdf.7 new file mode 100644 index 000000000000..5e94195059d7 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/life_cycle-kdf.7 @@ -0,0 +1,217 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "LIFE_CYCLE-KDF 7ossl" +.TH LIFE_CYCLE-KDF 7ossl "2023-09-19" "3.0.11" "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" +life_cycle\-kdf \- The KDF algorithm life\-cycle +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +All key derivation functions (KDFs) and pseudo random functions (PRFs) +go through a number of stages in their life-cycle: +.IP "start" 4 +.IX Item "start" +This state represents the \s-1KDF/PRF\s0 before it has been allocated. It is the +starting state for any life-cycle transitions. +.IP "newed" 4 +.IX Item "newed" +This state represents the \s-1KDF/PRF\s0 after it has been allocated. +.IP "deriving" 4 +.IX Item "deriving" +This state represents the \s-1KDF/PRF\s0 when it is set up and capable of generating +output. +.IP "freed" 4 +.IX Item "freed" +This state is entered when the \s-1KDF/PRF\s0 is freed. It is the terminal state +for all life-cycle transitions. +.SS "State Transition Diagram" +.IX Subsection "State Transition Diagram" +The usual life-cycle of a \s-1KDF/PRF\s0 is illustrated: + +-------------------+ + | start | + +-------------------+ + | + | EVP_KDF_CTX_new + v + +-------------------+ + | newed | <+ + +-------------------+ | + | | + | EVP_KDF_derive | + v | EVP_KDF_CTX_reset + EVP_KDF_derive +-------------------+ | + + - - - - - - - - | | | + ' | deriving | | + + - - - - - - - -> | | -+ + +-------------------+ + | + | EVP_KDF_CTX_free + v + +-------------------+ + | freed | + +-------------------+ +.SS "Formal State Transitions" +.IX Subsection "Formal State Transitions" +This section defines all of the legal state transitions. +This is the canonical list. + Function Call ------------- Current State ------------- + start newed deriving freed + EVP_KDF_CTX_new newed + EVP_KDF_derive deriving deriving + EVP_KDF_CTX_free freed freed freed + EVP_KDF_CTX_reset newed newed + EVP_KDF_CTX_get_params newed deriving + EVP_KDF_CTX_set_params newed deriving + EVP_KDF_CTX_gettable_params newed deriving + EVP_KDF_CTX_settable_params newed deriving +.SH "NOTES" +.IX Header "NOTES" +At some point the \s-1EVP\s0 layer will begin enforcing the transitions described +herein. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-kdf\fR\|(7), \s-1\fBEVP_KDF\s0\fR\|(3). +.SH "HISTORY" +.IX Header "HISTORY" +The provider \s-1KDF\s0 interface was introduced in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021 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>. diff --git a/secure/lib/libcrypto/man/man7/life_cycle-mac.7 b/secure/lib/libcrypto/man/man7/life_cycle-mac.7 new file mode 100644 index 000000000000..9a74f22e023c --- /dev/null +++ b/secure/lib/libcrypto/man/man7/life_cycle-mac.7 @@ -0,0 +1,236 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "LIFE_CYCLE-MAC 7ossl" +.TH LIFE_CYCLE-MAC 7ossl "2023-09-19" "3.0.11" "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" +life_cycle\-mac \- The MAC algorithm life\-cycle +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +All message authentication codes (MACs) +go through a number of stages in their life-cycle: +.IP "start" 4 +.IX Item "start" +This state represents the \s-1MAC\s0 before it has been allocated. It is the +starting state for any life-cycle transitions. +.IP "newed" 4 +.IX Item "newed" +This state represents the \s-1MAC\s0 after it has been allocated. +.IP "initialised" 4 +.IX Item "initialised" +This state represents the \s-1MAC\s0 when it is set up and capable of processing +input. +.IP "updated" 4 +.IX Item "updated" +This state represents the \s-1MAC\s0 when it is set up and capable of processing +additional input or generating output. +.IP "finaled" 4 +.IX Item "finaled" +This state represents the \s-1MAC\s0 when it has generated output. +.IP "freed" 4 +.IX Item "freed" +This state is entered when the \s-1MAC\s0 is freed. It is the terminal state +for all life-cycle transitions. +.SS "State Transition Diagram" +.IX Subsection "State Transition Diagram" +The usual life-cycle of a \s-1MAC\s0 is illustrated: + +-------------------+ + | start | + +-------------------+ + | + | EVP_MAC_CTX_new + v + +-------------------+ + | newed | + +-------------------+ + | + | EVP_MAC_init + v + +-------------------+ + +> | initialised | <+ + | +-------------------+ | + | | | + | | EVP_MAC_update | EVP_MAC_init + | v | + EVP_MAC_init | +-------------------+ | + | | updated | -+ + | +-------------------+ + | | | + | | EVP_MAC_final | EVP_MAC_finalXOF + | v v + | +-------------------+ + +- | finaled | + +-------------------+ + | + | EVP_MAC_CTX_free + v + +-------------------+ + | freed | + +-------------------+ +.SS "Formal State Transitions" +.IX Subsection "Formal State Transitions" +This section defines all of the legal state transitions. +This is the canonical list. + Function Call --------------------- Current State ---------------------- + start newed initialised updated finaled freed + EVP_MAC_CTX_new newed + EVP_MAC_init initialised initialised initialised initialised + EVP_MAC_update updated updated + EVP_MAC_final finaled + EVP_MAC_finalXOF finaled + EVP_MAC_CTX_free freed freed freed freed freed + EVP_MAC_CTX_get_params newed initialised updated + EVP_MAC_CTX_set_params newed initialised updated + EVP_MAC_CTX_gettable_params newed initialised updated + EVP_MAC_CTX_settable_params newed initialised updated +.SH "NOTES" +.IX Header "NOTES" +At some point the \s-1EVP\s0 layer will begin enforcing the transitions described +herein. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-mac\fR\|(7), \s-1\fBEVP_MAC\s0\fR\|(3). +.SH "HISTORY" +.IX Header "HISTORY" +The provider \s-1MAC\s0 interface was introduced in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021 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>. diff --git a/secure/lib/libcrypto/man/man7/life_cycle-pkey.7 b/secure/lib/libcrypto/man/man7/life_cycle-pkey.7 new file mode 100644 index 000000000000..ca028c5f2af8 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/life_cycle-pkey.7 @@ -0,0 +1,320 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "LIFE_CYCLE-PKEY 7ossl" +.TH LIFE_CYCLE-PKEY 7ossl "2023-09-19" "3.0.11" "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" +life_cycle\-pkey \- The PKEY algorithm life\-cycle +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +All public keys (PKEYs) go through a number of stages in their life-cycle: +.IP "start" 4 +.IX Item "start" +This state represents the \s-1PKEY\s0 before it has been allocated. It is the +starting state for any life-cycle transitions. +.IP "newed" 4 +.IX Item "newed" +This state represents the \s-1PKEY\s0 after it has been allocated. +.IP "decapsulate" 4 +.IX Item "decapsulate" +This state represents the \s-1PKEY\s0 when it is ready to perform a private key decapsulation +operation. +.IP "decrypt" 4 +.IX Item "decrypt" +This state represents the \s-1PKEY\s0 when it is ready to decrypt some ciphertext. +.IP "derive" 4 +.IX Item "derive" +This state represents the \s-1PKEY\s0 when it is ready to derive a shared secret. +.IP "digest sign" 4 +.IX Item "digest sign" +This state represents the \s-1PKEY\s0 when it is ready to perform a private key signature +operation. +.IP "encapsulate" 4 +.IX Item "encapsulate" +This state represents the \s-1PKEY\s0 when it is ready to perform a public key encapsulation +operation. +.IP "encrypt" 4 +.IX Item "encrypt" +This state represents the \s-1PKEY\s0 when it is ready to encrypt some plaintext. +.IP "key generation" 4 +.IX Item "key generation" +This state represents the \s-1PKEY\s0 when it is ready to generate a new public/private key. +.IP "parameter generation" 4 +.IX Item "parameter generation" +This state represents the \s-1PKEY\s0 when it is ready to generate key parameters. +.IP "verify" 4 +.IX Item "verify" +This state represents the \s-1PKEY\s0 when it is ready to verify a public key signature. +.IP "verify recover" 4 +.IX Item "verify recover" +This state represents the \s-1PKEY\s0 when it is ready to recover a public key signature data. +.IP "freed" 4 +.IX Item "freed" +This state is entered when the \s-1PKEY\s0 is freed. It is the terminal state +for all life-cycle transitions. +.SS "State Transition Diagram" +.IX Subsection "State Transition Diagram" +The usual life-cycle of a \s-1PKEY\s0 object is illustrated: + +-------------+ + | | + | start | + | | + EVP_PKEY_derive +-------------+ + +-------------+ EVP_PKEY_derive_set_peer | +-------------+ + | |----------------------------+ | +----------------------------| | + | derive | | | | EVP_PKEY_verify | verify | + | |<---------------------------+ | +--------------------------->| | + +-------------+ | +-------------+ + ^ | ^ + | EVP_PKEY_derive_init | EVP_PKEY_verify_init | + +---------------------------------------+ | +---------------------------------------+ + | | | + +-------------+ | | | +-------------+ + | |----------------------------+ | | | +----------------------------| | + | digest sign | EVP_PKEY_sign | | | | | EVP_PKEY_verify_recover | verify | + | |<---------------------------+ | | | +--------------------------->| recover | + +-------------+ | | | +-------------+ + ^ | | | ^ + | EVP_PKEY_sign_init | | | EVP_PKEY_verify_recover_init | + +---------------------------------+ | | | +---------------------------------+ + | | | | | + +-------------+ | | | | | +-------------+ + | |----------------------------+ | | | | | +----------------------------| | + | decapsulate | EVP_PKEY_decapsulate | | | | | | | EVP_PKEY_decrypt | decrypt | + | |<---------------------------+ | | v | | +--------------------------->| | + +-------------+ | +-------------+ | +-------------+ + ^ +---| |---+ ^ + | EVP_PKEY_decapsulate_init | | EVP_PKEY_decrypt_init | + +-------------------------------------| newed |-------------------------------------+ + | | + +---| |---+ + +-------------+ | +-------------+ | +-------------+ + | |----------------------------+ | | | | +----------------------------| | + | encapsulate | EVP_PKEY_encapsulate | | | | | | EVP_PKEY_encrypt | encrypt | + | |<---------------------------+ | | | | +--------------------------->| | + +-------------+ | | | | +-------------+ + ^ | | | | ^ + | EVP_PKEY_encapsulate_init | | | | EVP_PKEY_encrypt_init | + +---------------------------------+ | | +---------------------------------+ + | | + +---------------------------------------+ +---------------------------------------+ + | EVP_PKEY_paramgen_init EVP_PKEY_keygen_init | + v v + +-------------+ +-------------+ + | |----------------------------+ +----------------------------| | + | parameter | | | | key | + | generation |<---------------------------+ +--------------------------->| generation | + +-------------+ EVP_PKEY_paramgen EVP_PKEY_keygen +-------------+ + EVP_PKEY_gen EVP_PKEY_gen + + + + - - - - - + +-----------+ + ' ' EVP_PKEY_CTX_free | | + ' any state '------------------->| freed | + ' ' | | + + - - - - - + +-----------+ +.SS "Formal State Transitions" +.IX Subsection "Formal State Transitions" +This section defines all of the legal state transitions. +This is the canonical list. + Function Call ---------------------------------------------------------------------- Current State ---------------------------------------------------------------------- + start newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key freed + sign recover generation generation + EVP_PKEY_CTX_new newed + EVP_PKEY_CTX_new_id newed + EVP_PKEY_CTX_new_from_name newed + EVP_PKEY_CTX_new_from_pkey newed + EVP_PKEY_sign_init digest digest digest digest digest digest digest digest digest digest digest + sign sign sign sign sign sign sign sign sign sign sign + EVP_PKEY_sign digest + sign + EVP_PKEY_verify_init verify verify verify verify verify verify verify verify verify verify verify + EVP_PKEY_verify verify + EVP_PKEY_verify_recover_init verify verify verify verify verify verify verify verify verify verify verify + recover recover recover recover recover recover recover recover recover recover recover + EVP_PKEY_verify_recover verify + recover + EVP_PKEY_encrypt_init encrypt encrypt encrypt encrypt encrypt encrypt encrypt encrypt encrypt encrypt encrypt + EVP_PKEY_encrypt encrypt + EVP_PKEY_decrypt_init decrypt decrypt decrypt decrypt decrypt decrypt decrypt decrypt decrypt decrypt decrypt + EVP_PKEY_decrypt decrypt + EVP_PKEY_derive_init derive derive derive derive derive derive derive derive derive derive derive + EVP_PKEY_derive_set_peer derive + EVP_PKEY_derive derive + EVP_PKEY_encapsulate_init encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate + EVP_PKEY_encapsulate encapsulate + EVP_PKEY_decapsulate_init decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate + EVP_PKEY_decapsulate decapsulate + EVP_PKEY_paramgen_init parameter parameter parameter parameter parameter parameter parameter parameter parameter parameter parameter + generation generation generation generation generation generation generation generation generation generation generation + EVP_PKEY_paramgen parameter + generation + EVP_PKEY_keygen_init key key key key key key key key key key key + generation generation generation generation generation generation generation generation generation generation generation + EVP_PKEY_keygen key + generation + EVP_PKEY_gen parameter key + generation generation + EVP_PKEY_CTX_get_params newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key + sign recover generation generation + EVP_PKEY_CTX_set_params newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key + sign recover generation generation + EVP_PKEY_CTX_gettable_params newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key + sign recover generation generation + EVP_PKEY_CTX_settable_params newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key + sign recover generation generation + EVP_PKEY_CTX_free freed freed freed freed freed freed freed freed freed freed freed freed +.SH "NOTES" +.IX Header "NOTES" +At some point the \s-1EVP\s0 layer will begin enforcing the transitions described +herein. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_new\fR\|(3), +\&\fBEVP_PKEY_decapsulate\fR\|(3), \fBEVP_PKEY_decrypt\fR\|(3), \fBEVP_PKEY_encapsulate\fR\|(3), +\&\fBEVP_PKEY_encrypt\fR\|(3), \fBEVP_PKEY_derive\fR\|(3), \fBEVP_PKEY_keygen\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), \fBEVP_PKEY_verify\fR\|(3), \fBEVP_PKEY_verify_recover\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +The provider \s-1PKEY\s0 interface was introduced in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021\-2023 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>. diff --git a/secure/lib/libcrypto/man/man7/life_cycle-rand.7 b/secure/lib/libcrypto/man/man7/life_cycle-rand.7 new file mode 100644 index 000000000000..ce292e717451 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/life_cycle-rand.7 @@ -0,0 +1,229 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "LIFE_CYCLE-RAND 7ossl" +.TH LIFE_CYCLE-RAND 7ossl "2023-09-19" "3.0.11" "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" +life_cycle\-rand \- The RAND algorithm life\-cycle +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +All random number generator (RANDs) +go through a number of stages in their life-cycle: +.IP "start" 4 +.IX Item "start" +This state represents the \s-1RAND\s0 before it has been allocated. It is the +starting state for any life-cycle transitions. +.IP "newed" 4 +.IX Item "newed" +This state represents the \s-1RAND\s0 after it has been allocated but unable to +generate any output. +.IP "instantiated" 4 +.IX Item "instantiated" +This state represents the \s-1RAND\s0 when it is set up and capable of generating +output. +.IP "uninstantiated" 4 +.IX Item "uninstantiated" +This state represents the \s-1RAND\s0 when it has been shutdown and it is no longer +capable of generating output. +.IP "freed" 4 +.IX Item "freed" +This state is entered when the \s-1RAND\s0 is freed. It is the terminal state +for all life-cycle transitions. +.SS "State Transition Diagram" +.IX Subsection "State Transition Diagram" +The usual life-cycle of a \s-1RAND\s0 is illustrated: + +-------------------------+ + | start | + +-------------------------+ + | + | EVP_RAND_CTX_new + v + +-------------------------+ + | newed | + +-------------------------+ + | + | EVP_RAND_instantiate + v + EVP_RAND_generate +-------------------------+ + +-------------------- | | + | | instantiated | + +-------------------> | | <+ + +-------------------------+ ' + | ' + | EVP_RAND_uninstantiate ' EVP_RAND_instantiate + v ' + +-------------------------+ ' + | uninstantiated | -+ + +-------------------------+ + | + | EVP_RAND_CTX_free + v + +-------------------------+ + | freed | + +-------------------------+ +.SS "Formal State Transitions" +.IX Subsection "Formal State Transitions" +This section defines all of the legal state transitions. +This is the canonical list. + Function Call ------------------ Current State ------------------ + start newed instantiated uninstantiated freed + EVP_RAND_CTX_new newed + EVP_RAND_instantiate instantiated + EVP_RAND_generate instantiated + EVP_RAND_uninstantiate uninstantiated + EVP_RAND_CTX_free freed freed freed freed + EVP_RAND_CTX_get_params newed instantiated uninstantiated freed + EVP_RAND_CTX_set_params newed instantiated uninstantiated freed + EVP_RAND_CTX_gettable_params newed instantiated uninstantiated freed + EVP_RAND_CTX_settable_params newed instantiated uninstantiated freed +.SH "NOTES" +.IX Header "NOTES" +At some point the \s-1EVP\s0 layer will begin enforcing the transitions described +herein. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-rand\fR\|(7), \s-1\fBEVP_RAND\s0\fR\|(3). +.SH "HISTORY" +.IX Header "HISTORY" +The provider \s-1RAND\s0 interface was introduced in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021 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>. diff --git a/secure/lib/libcrypto/man/man7/migration_guide.7 b/secure/lib/libcrypto/man/man7/migration_guide.7 new file mode 100644 index 000000000000..642dc8f06499 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/migration_guide.7 @@ -0,0 +1,2148 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "MIGRATION_GUIDE 7ossl" +.TH MIGRATION_GUIDE 7ossl "2023-09-19" "3.0.11" "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" +migration_guide \- OpenSSL migration guide +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +See the individual manual pages for details. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This guide details the changes required to migrate to new versions of OpenSSL. +Currently this covers OpenSSL 3.0. For earlier versions refer to +<https://github.com/openssl/openssl/blob/master/CHANGES.md>. +For an overview of some of the key concepts introduced in OpenSSL 3.0 see +\&\fBcrypto\fR\|(7). +.SH "OPENSSL 3.0" +.IX Header "OPENSSL 3.0" +.SS "Main Changes from OpenSSL 1.1.1" +.IX Subsection "Main Changes from OpenSSL 1.1.1" +\fIMajor Release\fR +.IX Subsection "Major Release" +.PP +OpenSSL 3.0 is a major release and consequently any application that currently +uses an older version of OpenSSL will at the very least need to be recompiled in +order to work with the new version. It is the intention that the large majority +of applications will work unchanged with OpenSSL 3.0 if those applications +previously worked with OpenSSL 1.1.1. However this is not guaranteed and some +changes may be required in some cases. Changes may also be required if +applications need to take advantage of some of the new features available in +OpenSSL 3.0 such as the availability of the \s-1FIPS\s0 module. +.PP +\fILicense Change\fR +.IX Subsection "License Change" +.PP +In previous versions, OpenSSL was licensed under the dual OpenSSL and SSLeay +licenses <https://www.openssl.org/source/license-openssl-ssleay.txt> +(both licenses apply). From OpenSSL 3.0 this is replaced by the +Apache License v2 <https://www.openssl.org/source/apache-license-2.0.txt>. +.PP +\fIProviders and \s-1FIPS\s0 support\fR +.IX Subsection "Providers and FIPS support" +.PP +One of the key changes from OpenSSL 1.1.1 is the introduction of the Provider +concept. Providers collect together and make available algorithm implementations. +With OpenSSL 3.0 it is possible to specify, either programmatically or via a +config file, which providers you want to use for any given application. +OpenSSL 3.0 comes with 5 different providers as standard. Over time third +parties may distribute additional providers that can be plugged into OpenSSL. +All algorithm implementations available via providers are accessed through the +\&\*(L"high level\*(R" APIs (for example those functions prefixed with \f(CW\*(C`EVP\*(C'\fR). They cannot +be accessed using the \*(L"Low Level APIs\*(R". +.PP +One of the standard providers available is the \s-1FIPS\s0 provider. This makes +available \s-1FIPS\s0 validated cryptographic algorithms. +The \s-1FIPS\s0 provider is disabled by default and needs to be enabled explicitly +at configuration time using the \f(CW\*(C`enable\-fips\*(C'\fR option. If it is enabled, +the \s-1FIPS\s0 provider gets built and installed in addition to the other standard +providers. No separate installation procedure is necessary. +There is however a dedicated \f(CW\*(C`install_fips\*(C'\fR make target, which serves the +special purpose of installing only the \s-1FIPS\s0 provider into an existing +OpenSSL installation. +.PP +Not all algorithms may be available for the application at a particular moment. +If the application code uses any digest or cipher algorithm via the \s-1EVP\s0 interface, +the application should verify the result of the \fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_EncryptInit_ex\fR\|(3), and \fBEVP_DigestInit\fR\|(3) functions. In case when +the requested algorithm is not available, these functions will fail. +.PP +See also \*(L"Legacy Algorithms\*(R" for information on the legacy provider. +.PP +See also \*(L"Completing the installation of the \s-1FIPS\s0 Module\*(R" and +\&\*(L"Using the \s-1FIPS\s0 Module in applications\*(R". +.PP +\fILow Level APIs\fR +.IX Subsection "Low Level APIs" +.PP +OpenSSL has historically provided two sets of APIs for invoking cryptographic +algorithms: the \*(L"high level\*(R" APIs (such as the \f(CW\*(C`EVP\*(C'\fR APIs) and the \*(L"low level\*(R" +APIs. The high level APIs are typically designed to work across all algorithm +types. The \*(L"low level\*(R" APIs are targeted at a specific algorithm implementation. +For example, the \s-1EVP\s0 APIs provide the functions \fBEVP_EncryptInit_ex\fR\|(3), +\&\fBEVP_EncryptUpdate\fR\|(3) and \fBEVP_EncryptFinal\fR\|(3) to perform symmetric +encryption. Those functions can be used with the algorithms \s-1AES, CHACHA, 3DES\s0 etc. +On the other hand, to do \s-1AES\s0 encryption using the low level APIs you would have +to call \s-1AES\s0 specific functions such as \fBAES_set_encrypt_key\fR\|(3), +\&\fBAES_encrypt\fR\|(3), and so on. The functions for 3DES are different. +Use of the low level APIs has been informally discouraged by the OpenSSL +development team for a long time. However in OpenSSL 3.0 this is made more +formal. All such low level APIs have been deprecated. You may still use them in +your applications, but you may start to see deprecation warnings during +compilation (dependent on compiler support for this). Deprecated APIs may be +removed from future versions of OpenSSL so you are strongly encouraged to update +your code to use the high level APIs instead. +.PP +This is described in more detail in \*(L"Deprecation of Low Level Functions\*(R" +.PP +\fILegacy Algorithms\fR +.IX Subsection "Legacy Algorithms" +.PP +Some cryptographic algorithms such as \fB\s-1MD2\s0\fR and \fB\s-1DES\s0\fR that were available via +the \s-1EVP\s0 APIs are now considered legacy and their use is strongly discouraged. +These legacy \s-1EVP\s0 algorithms are still available in OpenSSL 3.0 but not by +default. If you want to use them then you must load the legacy provider. +This can be as simple as a config file change, or can be done programmatically. +See \fBOSSL_PROVIDER\-legacy\fR\|(7) for a complete list of algorithms. +Applications using the \s-1EVP\s0 APIs to access these algorithms should instead use +more modern algorithms. If that is not possible then these applications +should ensure that the legacy provider has been loaded. This can be achieved +either programmatically or via configuration. See \fBcrypto\fR\|(7) man page for +more information about providers. +.PP +\fIEngines and \*(L"\s-1METHOD\*(R"\s0 APIs\fR +.IX Subsection "Engines and METHOD APIs" +.PP +The refactoring to support Providers conflicts internally with the APIs used to +support engines, including the \s-1ENGINE API\s0 and any function that creates or +modifies custom \*(L"\s-1METHODS\*(R"\s0 (for example \fBEVP_MD_meth_new\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3), \fBEVP_PKEY_meth_new\fR\|(3), \fBRSA_meth_new\fR\|(3), +\&\fBEC_KEY_METHOD_new\fR\|(3), etc.). These functions are being deprecated in +OpenSSL 3.0, and users of these APIs should know that their use can likely +bypass provider selection and configuration, with unintended consequences. +This is particularly relevant for applications written to use the OpenSSL 3.0 +\&\s-1FIPS\s0 module, as detailed below. Authors and maintainers of external engines are +strongly encouraged to refactor their code transforming engines into providers +using the new Provider \s-1API\s0 and avoiding deprecated methods. +.PP +\fISupport of legacy engines\fR +.IX Subsection "Support of legacy engines" +.PP +If openssl is not built without engine support or deprecated \s-1API\s0 support, engines +will still work. However, their applicability will be limited. +.PP +New algorithms provided via engines will still work. +.PP +Engine-backed keys can be loaded via custom \fB\s-1OSSL_STORE\s0\fR implementation. +In this case the \fB\s-1EVP_PKEY\s0\fR objects created via \fBENGINE_load_private_key\fR\|(3) +will be considered legacy and will continue to work. +.PP +To ensure the future compatibility, the engines should be turned to providers. +To prefer the provider-based hardware offload, you can specify the default +properties to prefer your provider. +.PP +\fIVersioning Scheme\fR +.IX Subsection "Versioning Scheme" +.PP +The OpenSSL versioning scheme has changed with the OpenSSL 3.0 release. The new +versioning scheme has this format: +.PP +\&\s-1MAJOR.MINOR.PATCH\s0 +.PP +For OpenSSL 1.1.1 and below, different patch levels were indicated by a letter +at the end of the release version number. This will no longer be used and +instead the patch level is indicated by the final number in the version. A +change in the second (\s-1MINOR\s0) number indicates that new features may have been +added. OpenSSL versions with the same major number are \s-1API\s0 and \s-1ABI\s0 compatible. +If the major number changes then \s-1API\s0 and \s-1ABI\s0 compatibility is not guaranteed. +.PP +For more information, see \fBOpenSSL_version\fR\|(3). +.PP +\fIOther major new features\fR +.IX Subsection "Other major new features" +.PP +Certificate Management Protocol (\s-1CMP, RFC 4210\s0) +.IX Subsection "Certificate Management Protocol (CMP, RFC 4210)" +.PP +This also covers \s-1CRMF\s0 (\s-1RFC 4211\s0) and \s-1HTTP\s0 transfer (\s-1RFC 6712\s0) +See \fBopenssl\-cmp\fR\|(1) and \fBOSSL_CMP_exec_certreq\fR\|(3) as starting points. +.PP +\s-1HTTP\s0(S) client +.IX Subsection "HTTP(S) client" +.PP +A proper \s-1HTTP\s0(S) client that supports \s-1GET\s0 and \s-1POST,\s0 redirection, plain and +\&\s-1ASN\s0.1\-encoded contents, proxies, and timeouts. +.PP +Key Derivation Function \s-1API\s0 (\s-1EVP_KDF\s0) +.IX Subsection "Key Derivation Function API (EVP_KDF)" +.PP +This simplifies the process of adding new \s-1KDF\s0 and \s-1PRF\s0 implementations. +.PP +Previously \s-1KDF\s0 algorithms had been shoe-horned into using the \s-1EVP_PKEY\s0 object +which was not a logical mapping. +Existing applications that use \s-1KDF\s0 algorithms using \s-1EVP_PKEY\s0 +(scrypt, \s-1TLS1 PRF\s0 and \s-1HKDF\s0) may be slower as they use an \s-1EVP_KDF\s0 bridge +internally. +All new applications should use the new \s-1\fBEVP_KDF\s0\fR\|(3) interface. +See also \*(L"Key Derivation Function (\s-1KDF\s0)\*(R" in \fBOSSL_PROVIDER\-default\fR\|(7) and +\&\*(L"Key Derivation Function (\s-1KDF\s0)\*(R" in \s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7). +.PP +Message Authentication Code \s-1API\s0 (\s-1EVP_MAC\s0) +.IX Subsection "Message Authentication Code API (EVP_MAC)" +.PP +This simplifies the process of adding \s-1MAC\s0 implementations. +.PP +This includes a generic \s-1EVP_PKEY\s0 to \s-1EVP_MAC\s0 bridge, to facilitate the continued +use of MACs through raw private keys in functionality such as +\&\fBEVP_DigestSign\fR\|(3) and \fBEVP_DigestVerify\fR\|(3). +.PP +All new applications should use the new \s-1\fBEVP_MAC\s0\fR\|(3) interface. +See also \*(L"Message Authentication Code (\s-1MAC\s0)\*(R" in \fBOSSL_PROVIDER\-default\fR\|(7) +and \*(L"Message Authentication Code (\s-1MAC\s0)\*(R" in \s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7). +.PP +Algorithm Fetching +.IX Subsection "Algorithm Fetching" +.PP +Using calls to convenience functions such as \fBEVP_sha256()\fR and \fBEVP_aes_256_gcm()\fR may +incur a performance penalty when using providers. +Retrieving algorithms from providers involves searching for an algorithm by name. +This is much slower than directly accessing a method table. +It is recommended to prefetch algorithms if an algorithm is used many times. +See \*(L"Performance\*(R" in \fBcrypto\fR\|(7), \*(L"Explicit fetching\*(R" in \fBcrypto\fR\|(7) and \*(L"Implicit fetching\*(R" in \fBcrypto\fR\|(7). +.PP +Support for Linux Kernel \s-1TLS\s0 +.IX Subsection "Support for Linux Kernel TLS" +.PP +In order to use \s-1KTLS,\s0 support for it must be compiled in using the +\&\f(CW\*(C`enable\-ktls\*(C'\fR configuration option. It must also be enabled at run time using +the \fB\s-1SSL_OP_ENABLE_KTLS\s0\fR option. +.PP +New Algorithms +.IX Subsection "New Algorithms" +.IP "\(bu" 4 +\&\s-1KDF\s0 algorithms \*(L"\s-1SINGLE STEP\*(R"\s0 and \*(L"\s-1SSH\*(R"\s0 +.Sp +See \s-1\fBEVP_KDF\-SS\s0\fR\|(7) and \s-1\fBEVP_KDF\-SSHKDF\s0\fR\|(7) +.IP "\(bu" 4 +\&\s-1MAC\s0 Algorithms \*(L"\s-1GMAC\*(R"\s0 and \*(L"\s-1KMAC\*(R"\s0 +.Sp +See \s-1\fBEVP_MAC\-GMAC\s0\fR\|(7) and \s-1\fBEVP_MAC\-KMAC\s0\fR\|(7). +.IP "\(bu" 4 +\&\s-1KEM\s0 Algorithm \*(L"\s-1RSASVE\*(R"\s0 +.Sp +See \s-1\fBEVP_KEM\-RSA\s0\fR\|(7). +.IP "\(bu" 4 +Cipher Algorithm \*(L"AES-SIV\*(R" +.Sp +See \*(L"\s-1SIV\s0 Mode\*(R" in \fBEVP_EncryptInit\fR\|(3). +.IP "\(bu" 4 +\&\s-1AES\s0 Key Wrap inverse ciphers supported by \s-1EVP\s0 layer. +.Sp +The inverse ciphers use \s-1AES\s0 decryption for wrapping, and \s-1AES\s0 encryption for +unwrapping. The algorithms are: \*(L"\s-1AES\-128\-WRAP\-INV\*(R", \*(L"AES\-192\-WRAP\-INV\*(R", +\&\*(L"AES\-256\-WRAP\-INV\*(R", \*(L"AES\-128\-WRAP\-PAD\-INV\*(R", \*(L"AES\-192\-WRAP\-PAD\-INV\*(R"\s0 and +\&\*(L"\s-1AES\-256\-WRAP\-PAD\-INV\*(R".\s0 +.IP "\(bu" 4 +\&\s-1CTS\s0 ciphers added to \s-1EVP\s0 layer. +.Sp +The algorithms are \*(L"\s-1AES\-128\-CBC\-CTS\*(R", \*(L"AES\-192\-CBC\-CTS\*(R", \*(L"AES\-256\-CBC\-CTS\*(R", +\&\*(L"CAMELLIA\-128\-CBC\-CTS\*(R", \*(L"CAMELLIA\-192\-CBC\-CTS\*(R"\s0 and \*(L"\s-1CAMELLIA\-256\-CBC\-CTS\*(R". +CS1, CS2\s0 and \s-1CS3\s0 variants are supported. +.PP +\s-1CMS\s0 and PKCS#7 updates +.IX Subsection "CMS and PKCS#7 updates" +.IP "\(bu" 4 +Added CAdES-BES signature verification support. +.IP "\(bu" 4 +Added CAdES-BES signature scheme and attributes support (\s-1RFC 5126\s0) to \s-1CMS API.\s0 +.IP "\(bu" 4 +Added AuthEnvelopedData content type structure (\s-1RFC 5083\s0) using \s-1AES_GCM\s0 +.Sp +This uses the AES-GCM parameter (\s-1RFC 5084\s0) for the Cryptographic Message Syntax. +Its purpose is to support encryption and decryption of a digital envelope that +is both authenticated and encrypted using \s-1AES GCM\s0 mode. +.IP "\(bu" 4 +\&\fBPKCS7_get_octet_string\fR\|(3) and \fBPKCS7_type_is_other\fR\|(3) were made public. +.PP +PKCS#12 \s-1API\s0 updates +.IX Subsection "PKCS#12 API updates" +.PP +The default algorithms for pkcs12 creation with the \fBPKCS12_create()\fR function +were changed to more modern \s-1PBKDF2\s0 and \s-1AES\s0 based algorithms. The default +\&\s-1MAC\s0 iteration count was changed to \s-1PKCS12_DEFAULT_ITER\s0 to make it equal +with the password-based encryption iteration count. The default digest +algorithm for the \s-1MAC\s0 computation was changed to \s-1SHA\-256.\s0 The pkcs12 +application now supports \-legacy option that restores the previous +default algorithms to support interoperability with legacy systems. +.PP +Added enhanced PKCS#12 APIs which accept a library context \fB\s-1OSSL_LIB_CTX\s0\fR +and (where relevant) a property query. Other APIs which handle PKCS#7 and +PKCS#8 objects have also been enhanced where required. This includes: +.PP +\&\fBPKCS12_add_key_ex\fR\|(3), \fBPKCS12_add_safe_ex\fR\|(3), \fBPKCS12_add_safes_ex\fR\|(3), +\&\fBPKCS12_create_ex\fR\|(3), \fBPKCS12_decrypt_skey_ex\fR\|(3), \fBPKCS12_init_ex\fR\|(3), +\&\fBPKCS12_item_decrypt_d2i_ex\fR\|(3), \fBPKCS12_item_i2d_encrypt_ex\fR\|(3), +\&\fBPKCS12_key_gen_asc_ex\fR\|(3), \fBPKCS12_key_gen_uni_ex\fR\|(3), \fBPKCS12_key_gen_utf8_ex\fR\|(3), +\&\fBPKCS12_pack_p7encdata_ex\fR\|(3), \fBPKCS12_pbe_crypt_ex\fR\|(3), \fBPKCS12_PBE_keyivgen_ex\fR\|(3), +\&\fBPKCS12_SAFEBAG_create_pkcs8_encrypt_ex\fR\|(3), \fBPKCS5_pbe2_set_iv_ex\fR\|(3), +\&\fBPKCS5_pbe_set0_algor_ex\fR\|(3), \fBPKCS5_pbe_set_ex\fR\|(3), \fBPKCS5_pbkdf2_set_ex\fR\|(3), +\&\fBPKCS5_v2_PBE_keyivgen_ex\fR\|(3), \fBPKCS5_v2_scrypt_keyivgen_ex\fR\|(3), +\&\fBPKCS8_decrypt_ex\fR\|(3), \fBPKCS8_encrypt_ex\fR\|(3), \fBPKCS8_set0_pbe_ex\fR\|(3). +.PP +As part of this change the EVP_PBE_xxx APIs can also accept a library +context and property query and will call an extended version of the key/IV +derivation function which supports these parameters. This includes +\&\fBEVP_PBE_CipherInit_ex\fR\|(3), \fBEVP_PBE_find_ex\fR\|(3) and \fBEVP_PBE_scrypt_ex\fR\|(3). +.PP +PKCS#12 \s-1KDF\s0 versus \s-1FIPS\s0 +.IX Subsection "PKCS#12 KDF versus FIPS" +.PP +Unlike in 1.x.y, the \s-1PKCS12KDF\s0 algorithm used when a PKCS#12 structure +is created with a \s-1MAC\s0 that does not work with the \s-1FIPS\s0 provider as the \s-1PKCS12KDF\s0 +is not a \s-1FIPS\s0 approvable mechanism. +.PP +See \s-1\fBEVP_KDF\-PKCS12KDF\s0\fR\|(7), \fBPKCS12_create\fR\|(3), \fBopenssl\-pkcs12\fR\|(1), +\&\s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7). +.PP +Windows thread synchronization changes +.IX Subsection "Windows thread synchronization changes" +.PP +Windows thread synchronization uses read/write primitives (SRWLock) when +supported by the \s-1OS,\s0 otherwise CriticalSection continues to be used. +.PP +Trace \s-1API\s0 +.IX Subsection "Trace API" +.PP +A new generic trace \s-1API\s0 has been added which provides support for enabling +instrumentation through trace output. This feature is mainly intended as an aid +for developers and is disabled by default. To utilize it, OpenSSL needs to be +configured with the \f(CW\*(C`enable\-trace\*(C'\fR option. +.PP +If the tracing \s-1API\s0 is enabled, the application can activate trace output by +registering BIOs as trace channels for a number of tracing and debugging +categories. See \fBOSSL_trace_enabled\fR\|(3). +.PP +Key validation updates +.IX Subsection "Key validation updates" +.PP +\&\fBEVP_PKEY_public_check\fR\|(3) and \fBEVP_PKEY_param_check\fR\|(3) now work for +more key types. This includes \s-1RSA, DSA, ED25519, X25519, ED448\s0 and X448. +Previously (in 1.1.1) they would return \-2. For key types that do not have +parameters then \fBEVP_PKEY_param_check\fR\|(3) will always return 1. +.PP +\fIOther notable deprecations and changes\fR +.IX Subsection "Other notable deprecations and changes" +.PP +The function code part of an OpenSSL error code is no longer relevant +.IX Subsection "The function code part of an OpenSSL error code is no longer relevant" +.PP +This code is now always set to zero. Related functions are deprecated. +.PP +\s-1STACK\s0 and \s-1HASH\s0 macros have been cleaned up +.IX Subsection "STACK and HASH macros have been cleaned up" +.PP +The type-safe wrappers are declared everywhere and implemented once. +See \s-1\fBDEFINE_STACK_OF\s0\fR\|(3) and \s-1\fBDECLARE_LHASH_OF\s0\fR\|(3). +.PP +The \s-1RAND_DRBG\s0 subsystem has been removed +.IX Subsection "The RAND_DRBG subsystem has been removed" +.PP +The new \s-1\fBEVP_RAND\s0\fR\|(3) is a partial replacement: the \s-1DRBG\s0 callback framework is +absent. The \s-1RAND_DRBG API\s0 did not fit well into the new provider concept as +implemented by \s-1EVP_RAND\s0 and \s-1EVP_RAND_CTX.\s0 +.PP +Removed \fBFIPS_mode()\fR and \fBFIPS_mode_set()\fR +.IX Subsection "Removed FIPS_mode() and FIPS_mode_set()" +.PP +These functions are legacy APIs that are not applicable to the new provider +model. Applications should instead use +\&\fBEVP_default_properties_is_fips_enabled\fR\|(3) and +\&\fBEVP_default_properties_enable_fips\fR\|(3). +.PP +Key generation is slower +.IX Subsection "Key generation is slower" +.PP +The Miller-Rabin test now uses 64 rounds, which is used for all prime generation, +including \s-1RSA\s0 key generation. This affects the time for larger keys sizes. +.PP +The default key generation method for the regular 2\-prime \s-1RSA\s0 keys was changed +to the \s-1FIPS186\-4 B.3.6\s0 method (Generation of Probable Primes with Conditions +Based on Auxiliary Probable Primes). This method is slower than the original +method. +.PP +Change \s-1PBKDF2\s0 to conform to \s-1SP800\-132\s0 instead of the older \s-1PKCS5 RFC2898\s0 +.IX Subsection "Change PBKDF2 to conform to SP800-132 instead of the older PKCS5 RFC2898" +.PP +This checks that the salt length is at least 128 bits, the derived key length is +at least 112 bits, and that the iteration count is at least 1000. +For backwards compatibility these checks are disabled by default in the +default provider, but are enabled by default in the \s-1FIPS\s0 provider. +.PP +To enable or disable the checks see \fB\s-1OSSL_KDF_PARAM_PKCS5\s0\fR in +\&\s-1\fBEVP_KDF\-PBKDF2\s0\fR\|(7). The parameter can be set using \fBEVP_KDF_derive\fR\|(3). +.PP +Enforce a minimum \s-1DH\s0 modulus size of 512 bits +.IX Subsection "Enforce a minimum DH modulus size of 512 bits" +.PP +Smaller sizes now result in an error. +.PP +\s-1SM2\s0 key changes +.IX Subsection "SM2 key changes" +.PP +\&\s-1EC\s0 EVP_PKEYs with the \s-1SM2\s0 curve have been reworked to automatically become +\&\s-1EVP_PKEY_SM2\s0 rather than \s-1EVP_PKEY_EC.\s0 +.PP +Unlike in previous OpenSSL versions, this means that applications cannot +call \f(CW\*(C`EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)\*(C'\fR to get \s-1SM2\s0 computations. +.PP +Parameter and key generation is also reworked to make it possible +to generate \s-1EVP_PKEY_SM2\s0 parameters and keys. Applications must now generate +\&\s-1SM2\s0 keys directly and must not create an \s-1EVP_PKEY_EC\s0 key first. It is no longer +possible to import an \s-1SM2\s0 key with domain parameters other than the \s-1SM2\s0 elliptic +curve ones. +.PP +Validation of \s-1SM2\s0 keys has been separated from the validation of regular \s-1EC\s0 +keys, allowing to improve the \s-1SM2\s0 validation process to reject loaded private +keys that are not conforming to the \s-1SM2 ISO\s0 standard. +In particular, a private scalar \fIk\fR outside the range \fI1 <= k < n\-1\fR is +now correctly rejected. +.PP +\fBEVP_PKEY_set_alias_type()\fR method has been removed +.IX Subsection "EVP_PKEY_set_alias_type() method has been removed" +.PP +This function made a \fB\s-1EVP_PKEY\s0\fR object mutable after it had been set up. In +OpenSSL 3.0 it was decided that a provided key should not be able to change its +type, so this function has been removed. +.PP +Functions that return an internal key should be treated as read only +.IX Subsection "Functions that return an internal key should be treated as read only" +.PP +Functions such as \fBEVP_PKEY_get0_RSA\fR\|(3) behave slightly differently in +OpenSSL 3.0. Previously they returned a pointer to the low-level key used +internally by libcrypto. From OpenSSL 3.0 this key may now be held in a +provider. Calling these functions will only return a handle on the internal key +where the \s-1EVP_PKEY\s0 was constructed using this key in the first place, for +example using a function or macro such as \fBEVP_PKEY_assign_RSA\fR\|(3), +\&\fBEVP_PKEY_set1_RSA\fR\|(3), etc. +Where the \s-1EVP_PKEY\s0 holds a provider managed key, then these functions now return +a cached copy of the key. Changes to the internal provider key that take place +after the first time the cached key is accessed will not be reflected back in +the cached copy. Similarly any changes made to the cached copy by application +code will not be reflected back in the internal provider key. +.PP +For the above reasons the keys returned from these functions should typically be +treated as read-only. To emphasise this the value returned from +\&\fBEVP_PKEY_get0_RSA\fR\|(3), \fBEVP_PKEY_get0_DSA\fR\|(3), \fBEVP_PKEY_get0_EC_KEY\fR\|(3) and +\&\fBEVP_PKEY_get0_DH\fR\|(3) have been made const. This may break some existing code. +Applications broken by this change should be modified. The preferred solution is +to refactor the code to avoid the use of these deprecated functions. Failing +this the code should be modified to use a const pointer instead. +The \fBEVP_PKEY_get1_RSA\fR\|(3), \fBEVP_PKEY_get1_DSA\fR\|(3), \fBEVP_PKEY_get1_EC_KEY\fR\|(3) +and \fBEVP_PKEY_get1_DH\fR\|(3) functions continue to return a non-const pointer to +enable them to be \*(L"freed\*(R". However they should also be treated as read-only. +.PP +The public key check has moved from \fBEVP_PKEY_derive()\fR to \fBEVP_PKEY_derive_set_peer()\fR +.IX Subsection "The public key check has moved from EVP_PKEY_derive() to EVP_PKEY_derive_set_peer()" +.PP +This may mean result in an error in \fBEVP_PKEY_derive_set_peer\fR\|(3) rather than +during \fBEVP_PKEY_derive\fR\|(3). +To disable this check use EVP_PKEY_derive_set_peer_ex(dh, peer, 0). +.PP +The print format has cosmetic changes for some functions +.IX Subsection "The print format has cosmetic changes for some functions" +.PP +The output from numerous \*(L"printing\*(R" functions such as \fBX509_signature_print\fR\|(3), +\&\fBX509_print_ex\fR\|(3), \fBX509_CRL_print_ex\fR\|(3), and other similar functions has been +amended such that there may be cosmetic differences between the output +observed in 1.1.1 and 3.0. This also applies to the \fB\-text\fR output from the +\&\fBopenssl x509\fR and \fBopenssl crl\fR applications. +.PP +Interactive mode from the \fBopenssl\fR program has been removed +.IX Subsection "Interactive mode from the openssl program has been removed" +.PP +From now on, running it without arguments is equivalent to \fBopenssl help\fR. +.PP +The error return values from some control calls (ctrl) have changed +.IX Subsection "The error return values from some control calls (ctrl) have changed" +.PP +One significant change is that controls which used to return \-2 for +invalid inputs, now return \-1 indicating a generic error condition instead. +.PP +\s-1DH\s0 and \s-1DHX\s0 key types have different settable parameters +.IX Subsection "DH and DHX key types have different settable parameters" +.PP +Previously (in 1.1.1) these conflicting parameters were allowed, but will now +result in errors. See \s-1\fBEVP_PKEY\-DH\s0\fR\|(7) for further details. This affects the +behaviour of \fBopenssl\-genpkey\fR\|(1) for \s-1DH\s0 parameter generation. +.PP +\fBEVP_CIPHER_CTX_set_flags()\fR ordering change +.IX Subsection "EVP_CIPHER_CTX_set_flags() ordering change" +.PP +If using a cipher from a provider the \fB\s-1EVP_CIPH_FLAG_LENGTH_BITS\s0\fR flag can only +be set \fBafter\fR the cipher has been assigned to the cipher context. +See \*(L"\s-1FLAGS\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3) for more information. +.PP +Validation of operation context parameters +.IX Subsection "Validation of operation context parameters" +.PP +Due to move of the implementation of cryptographic operations to the +providers, validation of various operation parameters can be postponed until +the actual operation is executed where previously it happened immediately +when an operation parameter was set. +.PP +For example when setting an unsupported curve with +\&\fBEVP_PKEY_CTX_set_ec_paramgen_curve_nid()\fR this function call will not fail +but later keygen operations with the \s-1EVP_PKEY_CTX\s0 will fail. +.PP +Removal of function code from the error codes +.IX Subsection "Removal of function code from the error codes" +.PP +The function code part of the error code is now always set to 0. For that +reason the \s-1\fBERR_GET_FUNC\s0()\fR macro was removed. Applications must resolve +the error codes only using the library number and the reason code. +.PP +ChaCha20\-Poly1305 cipher does not allow a truncated \s-1IV\s0 length to be used +.IX Subsection "ChaCha20-Poly1305 cipher does not allow a truncated IV length to be used" +.PP +In OpenSSL 3.0 setting the \s-1IV\s0 length to any value other than 12 will result in an +error. +Prior to OpenSSL 3.0 the ivlen could be smaller that the required 12 byte length, +using EVP_CIPHER_CTX_ctrl(ctx, \s-1EVP_CRTL_AEAD_SET_IVLEN,\s0 ivlen, \s-1NULL\s0). This resulted +in an \s-1IV\s0 that had leading zero padding. +.SS "Installation and Compilation" +.IX Subsection "Installation and Compilation" +Please refer to the \s-1INSTALL\s0.md file in the top of the distribution for +instructions on how to build and install OpenSSL 3.0. Please also refer to the +various platform specific \s-1NOTES\s0 files for your specific platform. +.SS "Upgrading from OpenSSL 1.1.1" +.IX Subsection "Upgrading from OpenSSL 1.1.1" +Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1 should be relatively straight +forward in most cases. The most likely area where you will encounter problems +is if you have used low level APIs in your code (as discussed above). In that +case you are likely to start seeing deprecation warnings when compiling your +application. If this happens you have 3 options: +.IP "1." 4 +Ignore the warnings. They are just warnings. The deprecated functions are still present and you may still use them. However be aware that they may be removed from a future version of OpenSSL. +.IP "2." 4 +Suppress the warnings. Refer to your compiler documentation on how to do this. +.IP "3." 4 +Remove your usage of the low level APIs. In this case you will need to rewrite your code to use the high level APIs instead +.PP +\fIError code changes\fR +.IX Subsection "Error code changes" +.PP +As OpenSSL 3.0 provides a brand new Encoder/Decoder mechanism for working with +widely used file formats, application code that checks for particular error +reason codes on key loading failures might need an update. +.PP +Password-protected keys may deserve special attention. If only some errors +are treated as an indicator that the user should be asked about the password again, +it's worth testing these scenarios and processing the newly relevant codes. +.PP +There may be more cases to treat specially, depending on the calling application code. +.SS "Upgrading from OpenSSL 1.0.2" +.IX Subsection "Upgrading from OpenSSL 1.0.2" +Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 is likely to be significantly more +difficult. In addition to the issues discussed above in the section about +\&\*(L"Upgrading from OpenSSL 1.1.1\*(R", the main things to be aware of are: +.IP "1." 4 +The build and installation procedure has changed significantly. +.Sp +Check the file \s-1INSTALL\s0.md in the top of the installation for instructions on how +to build and install OpenSSL for your platform. Also read the various \s-1NOTES\s0 +files in the same directory, as applicable for your platform. +.IP "2." 4 +Many structures have been made opaque in OpenSSL 3.0. +.Sp +The structure definitions have been removed from the public header files and +moved to internal header files. In practice this means that you can no longer +stack allocate some structures. Instead they must be heap allocated through some +function call (typically those function names have a \f(CW\*(C`_new\*(C'\fR suffix to them). +Additionally you must use \*(L"setter\*(R" or \*(L"getter\*(R" functions to access the fields +within those structures. +.Sp +For example code that previously looked like this: +.Sp +.Vb 1 +\& EVP_MD_CTX md_ctx; +\& +\& /* This line will now generate compiler errors */ +\& EVP_MD_CTX_init(&md_ctx); +.Ve +.Sp +The code needs to be amended to look like this: +.Sp +.Vb 1 +\& EVP_MD_CTX *md_ctx; +\& +\& md_ctx = EVP_MD_CTX_new(); +\& ... +\& ... +\& EVP_MD_CTX_free(md_ctx); +.Ve +.IP "3." 4 +Support for TLSv1.3 has been added. +.Sp +This has a number of implications for \s-1SSL/TLS\s0 applications. See the +\&\s-1TLS1.3\s0 page <https://wiki.openssl.org/index.php/TLS1.3> for further details. +.PP +More details about the breaking changes between OpenSSL versions 1.0.2 and 1.1.0 +can be found on the +OpenSSL 1.1.0 Changes page <https://wiki.openssl.org/index.php/OpenSSL_1.1.0_Changes>. +.PP +\fIUpgrading from the OpenSSL 2.0 \s-1FIPS\s0 Object Module\fR +.IX Subsection "Upgrading from the OpenSSL 2.0 FIPS Object Module" +.PP +The OpenSSL 2.0 \s-1FIPS\s0 Object Module was a separate download that had to be built +separately and then integrated into your main OpenSSL 1.0.2 build. +In OpenSSL 3.0 the \s-1FIPS\s0 support is fully integrated into the mainline version of +OpenSSL and is no longer a separate download. For further information see +\&\*(L"Completing the installation of the \s-1FIPS\s0 Module\*(R". +.PP +The function calls \fBFIPS_mode()\fR and \fBFIPS_mode_set()\fR have been removed +from OpenSSL 3.0. You should rewrite your application to not use them. +See \fBfips_module\fR\|(7) and \s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7) for details. +.SS "Completing the installation of the \s-1FIPS\s0 Module" +.IX Subsection "Completing the installation of the FIPS Module" +The \s-1FIPS\s0 Module will be built and installed automatically if \s-1FIPS\s0 support has +been configured. The current documentation can be found in the +README-FIPS <https://github.com/openssl/openssl/blob/master/README-FIPS.md> file. +.SS "Programming" +.IX Subsection "Programming" +Applications written to work with OpenSSL 1.1.1 will mostly just work with +OpenSSL 3.0. However changes will be required if you want to take advantage of +some of the new features that OpenSSL 3.0 makes available. In order to do that +you need to understand some new concepts introduced in OpenSSL 3.0. +Read \*(L"Library contexts\*(R" in \fBcrypto\fR\|(7) for further information. +.PP +\fILibrary Context\fR +.IX Subsection "Library Context" +.PP +A library context allows different components of a complex application to each +use a different library context and have different providers loaded with +different configuration settings. +See \*(L"Library contexts\*(R" in \fBcrypto\fR\|(7) for further info. +.PP +If the user creates an \fB\s-1OSSL_LIB_CTX\s0\fR via \fBOSSL_LIB_CTX_new\fR\|(3) then many +functions may need to be changed to pass additional parameters to handle the +library context. +.PP +Using a Library Context \- Old functions that should be changed +.IX Subsection "Using a Library Context - Old functions that should be changed" +.PP +If a library context is needed then all EVP_* digest functions that return a +\&\fBconst \s-1EVP_MD\s0 *\fR such as \fBEVP_sha256()\fR should be replaced with a call to +\&\fBEVP_MD_fetch\fR\|(3). See \*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fBcrypto\fR\|(7). +.PP +If a library context is needed then all EVP_* cipher functions that return a +\&\fBconst \s-1EVP_CIPHER\s0 *\fR such as \fBEVP_aes_128_cbc()\fR should be replaced vith a call to +\&\fBEVP_CIPHER_fetch\fR\|(3). See \*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fBcrypto\fR\|(7). +.PP +Some functions can be passed an object that has already been set up with a library +context such as \fBd2i_X509\fR\|(3), \fBd2i_X509_CRL\fR\|(3), \fBd2i_X509_REQ\fR\|(3) and +\&\fBd2i_X509_PUBKEY\fR\|(3). If \s-1NULL\s0 is passed instead then the created object will be +set up with the default library context. Use \fBX509_new_ex\fR\|(3), +\&\fBX509_CRL_new_ex\fR\|(3), \fBX509_REQ_new_ex\fR\|(3) and \fBX509_PUBKEY_new_ex\fR\|(3) if a +library context is required. +.PP +All functions listed below with a \fI\s-1NAME\s0\fR have a replacement function \fINAME_ex\fR +that takes \fB\s-1OSSL_LIB_CTX\s0\fR as an additional argument. Functions that have other +mappings are listed along with the respective name. +.IP "\(bu" 4 +\&\fBASN1_item_new\fR\|(3), \fBASN1_item_d2i\fR\|(3), \fBASN1_item_d2i_fp\fR\|(3), +\&\fBASN1_item_d2i_bio\fR\|(3), \fBASN1_item_sign\fR\|(3) and \fBASN1_item_verify\fR\|(3) +.IP "\(bu" 4 +\&\fBBIO_new\fR\|(3) +.IP "\(bu" 4 +\&\fBb2i_RSA_PVK_bio()\fR and \fBi2b_PVK_bio()\fR +.IP "\(bu" 4 +\&\fBBN_CTX_new\fR\|(3) and \fBBN_CTX_secure_new\fR\|(3) +.IP "\(bu" 4 +\&\fBCMS_AuthEnvelopedData_create\fR\|(3), \fBCMS_ContentInfo_new\fR\|(3), \fBCMS_data_create\fR\|(3), +\&\fBCMS_digest_create\fR\|(3), \fBCMS_EncryptedData_encrypt\fR\|(3), \fBCMS_encrypt\fR\|(3), +\&\fBCMS_EnvelopedData_create\fR\|(3), \fBCMS_ReceiptRequest_create0\fR\|(3) and \fBCMS_sign\fR\|(3) +.IP "\(bu" 4 +\&\fBCONF_modules_load_file\fR\|(3) +.IP "\(bu" 4 +\&\fBCTLOG_new\fR\|(3), \fBCTLOG_new_from_base64\fR\|(3) and \fBCTLOG_STORE_new\fR\|(3) +.IP "\(bu" 4 +\&\fBCT_POLICY_EVAL_CTX_new\fR\|(3) +.IP "\(bu" 4 +\&\fBd2i_AutoPrivateKey\fR\|(3), \fBd2i_PrivateKey\fR\|(3) and \fBd2i_PUBKEY\fR\|(3) +.IP "\(bu" 4 +\&\fBd2i_PrivateKey_bio\fR\|(3) and \fBd2i_PrivateKey_fp\fR\|(3) +.Sp +Use \fBd2i_PrivateKey_ex_bio\fR\|(3) and \fBd2i_PrivateKey_ex_fp\fR\|(3) +.IP "\(bu" 4 +\&\fBEC_GROUP_new\fR\|(3) +.Sp +Use \fBEC_GROUP_new_by_curve_name_ex\fR\|(3) or \fBEC_GROUP_new_from_params\fR\|(3). +.IP "\(bu" 4 +\&\fBEVP_DigestSignInit\fR\|(3) and \fBEVP_DigestVerifyInit\fR\|(3) +.IP "\(bu" 4 +\&\fBEVP_PBE_CipherInit\fR\|(3), \fBEVP_PBE_find\fR\|(3) and \fBEVP_PBE_scrypt\fR\|(3) +.IP "\(bu" 4 +\&\fBPKCS5_PBE_keyivgen\fR\|(3) +.IP "\(bu" 4 +\&\s-1\fBEVP_PKCS82PKEY\s0\fR\|(3) +.IP "\(bu" 4 +\&\fBEVP_PKEY_CTX_new_id\fR\|(3) +.Sp +Use \fBEVP_PKEY_CTX_new_from_name\fR\|(3) +.IP "\(bu" 4 +\&\fBEVP_PKEY_derive_set_peer\fR\|(3), \fBEVP_PKEY_new_raw_private_key\fR\|(3) +and \fBEVP_PKEY_new_raw_public_key\fR\|(3) +.IP "\(bu" 4 +\&\fBEVP_SignFinal\fR\|(3) and \fBEVP_VerifyFinal\fR\|(3) +.IP "\(bu" 4 +\&\fBNCONF_new\fR\|(3) +.IP "\(bu" 4 +\&\fBOCSP_RESPID_match\fR\|(3) and \fBOCSP_RESPID_set_by_key\fR\|(3) +.IP "\(bu" 4 +\&\fBOPENSSL_thread_stop\fR\|(3) +.IP "\(bu" 4 +\&\fBOSSL_STORE_open\fR\|(3) +.IP "\(bu" 4 +\&\fBPEM_read_bio_Parameters\fR\|(3), \fBPEM_read_bio_PrivateKey\fR\|(3), \fBPEM_read_bio_PUBKEY\fR\|(3), +\&\fBPEM_read_PrivateKey\fR\|(3) and \fBPEM_read_PUBKEY\fR\|(3) +.IP "\(bu" 4 +\&\fBPEM_write_bio_PrivateKey\fR\|(3), \fBPEM_write_bio_PUBKEY\fR\|(3), \fBPEM_write_PrivateKey\fR\|(3) +and \fBPEM_write_PUBKEY\fR\|(3) +.IP "\(bu" 4 +\&\fBPEM_X509_INFO_read_bio\fR\|(3) and \fBPEM_X509_INFO_read\fR\|(3) +.IP "\(bu" 4 +\&\fBPKCS12_add_key\fR\|(3), \fBPKCS12_add_safe\fR\|(3), \fBPKCS12_add_safes\fR\|(3), +\&\fBPKCS12_create\fR\|(3), \fBPKCS12_decrypt_skey\fR\|(3), \fBPKCS12_init\fR\|(3), \fBPKCS12_item_decrypt_d2i\fR\|(3), +\&\fBPKCS12_item_i2d_encrypt\fR\|(3), \fBPKCS12_key_gen_asc\fR\|(3), \fBPKCS12_key_gen_uni\fR\|(3), +\&\fBPKCS12_key_gen_utf8\fR\|(3), \fBPKCS12_pack_p7encdata\fR\|(3), \fBPKCS12_pbe_crypt\fR\|(3), +\&\fBPKCS12_PBE_keyivgen\fR\|(3), \fBPKCS12_SAFEBAG_create_pkcs8_encrypt\fR\|(3) +.IP "\(bu" 4 +\&\fBPKCS5_pbe_set0_algor\fR\|(3), \fBPKCS5_pbe_set\fR\|(3), \fBPKCS5_pbe2_set_iv\fR\|(3), +\&\fBPKCS5_pbkdf2_set\fR\|(3) and \fBPKCS5_v2_scrypt_keyivgen\fR\|(3) +.IP "\(bu" 4 +\&\fBPKCS7_encrypt\fR\|(3), \fBPKCS7_new\fR\|(3) and \fBPKCS7_sign\fR\|(3) +.IP "\(bu" 4 +\&\fBPKCS8_decrypt\fR\|(3), \fBPKCS8_encrypt\fR\|(3) and \fBPKCS8_set0_pbe\fR\|(3) +.IP "\(bu" 4 +\&\fBRAND_bytes\fR\|(3) and \fBRAND_priv_bytes\fR\|(3) +.IP "\(bu" 4 +\&\fBSMIME_write_ASN1\fR\|(3) +.IP "\(bu" 4 +\&\fBSSL_load_client_CA_file\fR\|(3) +.IP "\(bu" 4 +\&\fBSSL_CTX_new\fR\|(3) +.IP "\(bu" 4 +\&\fBTS_RESP_CTX_new\fR\|(3) +.IP "\(bu" 4 +\&\fBX509_CRL_new\fR\|(3) +.IP "\(bu" 4 +\&\fBX509_load_cert_crl_file\fR\|(3) and \fBX509_load_cert_file\fR\|(3) +.IP "\(bu" 4 +\&\fBX509_LOOKUP_by_subject\fR\|(3) and \fBX509_LOOKUP_ctrl\fR\|(3) +.IP "\(bu" 4 +\&\fBX509_NAME_hash\fR\|(3) +.IP "\(bu" 4 +\&\fBX509_new\fR\|(3) +.IP "\(bu" 4 +\&\fBX509_REQ_new\fR\|(3) and \fBX509_REQ_verify\fR\|(3) +.IP "\(bu" 4 +\&\fBX509_STORE_CTX_new\fR\|(3), \fBX509_STORE_set_default_paths\fR\|(3), \fBX509_STORE_load_file\fR\|(3), +\&\fBX509_STORE_load_locations\fR\|(3) and \fBX509_STORE_load_store\fR\|(3) +.PP +New functions that use a Library context +.IX Subsection "New functions that use a Library context" +.PP +The following functions can be passed a library context if required. +Passing \s-1NULL\s0 will use the default library context. +.IP "\(bu" 4 +\&\fBBIO_new_from_core_bio\fR\|(3) +.IP "\(bu" 4 +\&\fBEVP_ASYM_CIPHER_fetch\fR\|(3) and \fBEVP_ASYM_CIPHER_do_all_provided\fR\|(3) +.IP "\(bu" 4 +\&\fBEVP_CIPHER_fetch\fR\|(3) and \fBEVP_CIPHER_do_all_provided\fR\|(3) +.IP "\(bu" 4 +\&\fBEVP_default_properties_enable_fips\fR\|(3) and +\&\fBEVP_default_properties_is_fips_enabled\fR\|(3) +.IP "\(bu" 4 +\&\fBEVP_KDF_fetch\fR\|(3) and \fBEVP_KDF_do_all_provided\fR\|(3) +.IP "\(bu" 4 +\&\fBEVP_KEM_fetch\fR\|(3) and \fBEVP_KEM_do_all_provided\fR\|(3) +.IP "\(bu" 4 +\&\fBEVP_KEYEXCH_fetch\fR\|(3) and \fBEVP_KEYEXCH_do_all_provided\fR\|(3) +.IP "\(bu" 4 +\&\fBEVP_KEYMGMT_fetch\fR\|(3) and \fBEVP_KEYMGMT_do_all_provided\fR\|(3) +.IP "\(bu" 4 +\&\fBEVP_MAC_fetch\fR\|(3) and \fBEVP_MAC_do_all_provided\fR\|(3) +.IP "\(bu" 4 +\&\fBEVP_MD_fetch\fR\|(3) and \fBEVP_MD_do_all_provided\fR\|(3) +.IP "\(bu" 4 +\&\fBEVP_PKEY_CTX_new_from_pkey\fR\|(3) +.IP "\(bu" 4 +\&\fBEVP_PKEY_Q_keygen\fR\|(3) +.IP "\(bu" 4 +\&\fBEVP_Q_mac\fR\|(3) and \fBEVP_Q_digest\fR\|(3) +.IP "\(bu" 4 +\&\s-1\fBEVP_RAND\s0\fR\|(3) and \fBEVP_RAND_do_all_provided\fR\|(3) +.IP "\(bu" 4 +\&\fBEVP_set_default_properties\fR\|(3) +.IP "\(bu" 4 +\&\fBEVP_SIGNATURE_fetch\fR\|(3) and \fBEVP_SIGNATURE_do_all_provided\fR\|(3) +.IP "\(bu" 4 +\&\fBOSSL_CMP_CTX_new\fR\|(3) and \fBOSSL_CMP_SRV_CTX_new\fR\|(3) +.IP "\(bu" 4 +\&\fBOSSL_CRMF_ENCRYPTEDVALUE_get1_encCert\fR\|(3) +.IP "\(bu" 4 +\&\fBOSSL_CRMF_MSG_create_popo\fR\|(3) and \fBOSSL_CRMF_MSGS_verify_popo\fR\|(3) +.IP "\(bu" 4 +\&\fBOSSL_CRMF_pbm_new\fR\|(3) and \fBOSSL_CRMF_pbmp_new\fR\|(3) +.IP "\(bu" 4 +\&\fBOSSL_DECODER_CTX_add_extra\fR\|(3) and \fBOSSL_DECODER_CTX_new_for_pkey\fR\|(3) +.IP "\(bu" 4 +\&\fBOSSL_DECODER_fetch\fR\|(3) and \fBOSSL_DECODER_do_all_provided\fR\|(3) +.IP "\(bu" 4 +\&\fBOSSL_ENCODER_CTX_add_extra\fR\|(3) +.IP "\(bu" 4 +\&\fBOSSL_ENCODER_fetch\fR\|(3) and \fBOSSL_ENCODER_do_all_provided\fR\|(3) +.IP "\(bu" 4 +\&\fBOSSL_LIB_CTX_free\fR\|(3), \fBOSSL_LIB_CTX_load_config\fR\|(3) and \fBOSSL_LIB_CTX_set0_default\fR\|(3) +.IP "\(bu" 4 +\&\fBOSSL_PROVIDER_add_builtin\fR\|(3), \fBOSSL_PROVIDER_available\fR\|(3), +\&\fBOSSL_PROVIDER_do_all\fR\|(3), \fBOSSL_PROVIDER_load\fR\|(3), +\&\fBOSSL_PROVIDER_set_default_search_path\fR\|(3) and \fBOSSL_PROVIDER_try_load\fR\|(3) +.IP "\(bu" 4 +\&\fBOSSL_SELF_TEST_get_callback\fR\|(3) and \fBOSSL_SELF_TEST_set_callback\fR\|(3) +.IP "\(bu" 4 +\&\fBOSSL_STORE_attach\fR\|(3) +.IP "\(bu" 4 +\&\fBOSSL_STORE_LOADER_fetch\fR\|(3) and \fBOSSL_STORE_LOADER_do_all_provided\fR\|(3) +.IP "\(bu" 4 +\&\fBRAND_get0_primary\fR\|(3), \fBRAND_get0_private\fR\|(3), \fBRAND_get0_public\fR\|(3), +\&\fBRAND_set_DRBG_type\fR\|(3) and \fBRAND_set_seed_source_type\fR\|(3) +.PP +\fIProviders\fR +.IX Subsection "Providers" +.PP +Providers are described in detail here \*(L"Providers\*(R" in \fBcrypto\fR\|(7). +See also \*(L"\s-1OPENSSL PROVIDERS\*(R"\s0 in \fBcrypto\fR\|(7). +.PP +\fIFetching algorithms and property queries\fR +.IX Subsection "Fetching algorithms and property queries" +.PP +Implicit and Explicit Fetching is described in detail here +\&\*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fBcrypto\fR\|(7). +.PP +\fIMapping \s-1EVP\s0 controls and flags to provider \s-1\f(BIOSSL_PARAM\s0\fI\|(3) parameters\fR +.IX Subsection "Mapping EVP controls and flags to provider OSSL_PARAM parameters" +.PP +The existing functions for controls (such as \fBEVP_CIPHER_CTX_ctrl\fR\|(3)) and +manipulating flags (such as \fBEVP_MD_CTX_set_flags\fR\|(3))internally use +\&\fB\s-1OSSL_PARAMS\s0\fR to pass information to/from provider objects. +See \s-1\fBOSSL_PARAM\s0\fR\|(3) for additional information related to parameters. +.PP +For ciphers see \*(L"\s-1CONTROLS\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3), \*(L"\s-1FLAGS\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3) and +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3). +.PP +For digests see \*(L"\s-1CONTROLS\*(R"\s0 in \fBEVP_DigestInit\fR\|(3), \*(L"\s-1FLAGS\*(R"\s0 in \fBEVP_DigestInit\fR\|(3) and +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \fBEVP_DigestInit\fR\|(3). +.PP +\fIDeprecation of Low Level Functions\fR +.IX Subsection "Deprecation of Low Level Functions" +.PP +A significant number of APIs have been deprecated in OpenSSL 3.0. +This section describes some common categories of deprecations. +See \*(L"Deprecated function mappings\*(R" for the list of deprecated functions +that refer to these categories. +.PP +Providers are a replacement for engines and low-level method overrides +.IX Subsection "Providers are a replacement for engines and low-level method overrides" +.PP +Any accessor that uses an \s-1ENGINE\s0 is deprecated (such as \fBEVP_PKEY_set1_engine()\fR). +Applications using engines should instead use providers. +.PP +Before providers were added algorithms were overridden by changing the methods +used by algorithms. All these methods such as \fBRSA_new_method()\fR and \fBRSA_meth_new()\fR +are now deprecated and can be replaced by using providers instead. +.PP +Deprecated i2d and d2i functions for low-level key types +.IX Subsection "Deprecated i2d and d2i functions for low-level key types" +.PP +Any i2d and d2i functions such as \fBd2i_DHparams()\fR that take a low-level key type +have been deprecated. Applications should instead use the \s-1\fBOSSL_DECODER\s0\fR\|(3) and +\&\s-1\fBOSSL_ENCODER\s0\fR\|(3) APIs to read and write files. +See \*(L"Migration\*(R" in \fBd2i_RSAPrivateKey\fR\|(3) for further details. +.PP +Deprecated low-level key object getters and setters +.IX Subsection "Deprecated low-level key object getters and setters" +.PP +Applications that set or get low-level key objects (such as \fBEVP_PKEY_set1_DH()\fR +or \fBEVP_PKEY_get0()\fR) should instead use the \s-1OSSL_ENCODER\s0 +(See \fBOSSL_ENCODER_to_bio\fR\|(3)) or \s-1OSSL_DECODER\s0 (See \fBOSSL_DECODER_from_bio\fR\|(3)) +APIs, or alternatively use \fBEVP_PKEY_fromdata\fR\|(3) or \fBEVP_PKEY_todata\fR\|(3). +.PP +Deprecated low-level key parameter getters +.IX Subsection "Deprecated low-level key parameter getters" +.PP +Functions that access low-level objects directly such as \fBRSA_get0_n\fR\|(3) are now +deprecated. Applications should use one of \fBEVP_PKEY_get_bn_param\fR\|(3), +\&\fBEVP_PKEY_get_int_param\fR\|(3), l<\fBEVP_PKEY_get_size_t_param\fR\|(3)>, +\&\fBEVP_PKEY_get_utf8_string_param\fR\|(3), \fBEVP_PKEY_get_octet_string_param\fR\|(3) or +\&\fBEVP_PKEY_get_params\fR\|(3) to access fields from an \s-1EVP_PKEY.\s0 +Gettable parameters are listed in \*(L"Common \s-1RSA\s0 parameters\*(R" in \s-1\fBEVP_PKEY\-RSA\s0\fR\|(7), +\&\*(L"\s-1DH\s0 parameters\*(R" in \s-1\fBEVP_PKEY\-DH\s0\fR\|(7), \*(L"\s-1DSA\s0 parameters\*(R" in \s-1\fBEVP_PKEY\-DSA\s0\fR\|(7), +\&\*(L"\s-1FFC\s0 parameters\*(R" in \s-1\fBEVP_PKEY\-FFC\s0\fR\|(7), \*(L"Common \s-1EC\s0 parameters\*(R" in \s-1\fBEVP_PKEY\-EC\s0\fR\|(7) and +\&\*(L"Common X25519, X448, \s-1ED25519\s0 and \s-1ED448\s0 parameters\*(R" in \s-1\fBEVP_PKEY\-X25519\s0\fR\|(7). +Applications may also use \fBEVP_PKEY_todata\fR\|(3) to return all fields. +.PP +Deprecated low-level key parameter setters +.IX Subsection "Deprecated low-level key parameter setters" +.PP +Functions that access low-level objects directly such as \fBRSA_set0_crt_params\fR\|(3) +are now deprecated. Applications should use \fBEVP_PKEY_fromdata\fR\|(3) to create +new keys from user provided key data. Keys should be immutable once they are +created, so if required the user may use \fBEVP_PKEY_todata\fR\|(3), \fBOSSL_PARAM_merge\fR\|(3), +and \fBEVP_PKEY_fromdata\fR\|(3) to create a modified key. +See \*(L"Examples\*(R" in \s-1\fBEVP_PKEY\-DH\s0\fR\|(7) for more information. +See \*(L"Deprecated low-level key generation functions\*(R" for information on +generating a key using parameters. +.PP +Deprecated low-level object creation +.IX Subsection "Deprecated low-level object creation" +.PP +Low-level objects were created using methods such as \fBRSA_new\fR\|(3), +\&\fBRSA_up_ref\fR\|(3) and \fBRSA_free\fR\|(3). Applications should instead use the +high-level \s-1EVP_PKEY\s0 APIs, e.g. \fBEVP_PKEY_new\fR\|(3), \fBEVP_PKEY_up_ref\fR\|(3) and +\&\fBEVP_PKEY_free\fR\|(3). +See also \fBEVP_PKEY_CTX_new_from_name\fR\|(3) and \fBEVP_PKEY_CTX_new_from_pkey\fR\|(3). +.PP +EVP_PKEYs may be created in a variety of ways: +See also \*(L"Deprecated low-level key generation functions\*(R", +\&\*(L"Deprecated low-level key reading and writing functions\*(R" and +\&\*(L"Deprecated low-level key parameter setters\*(R". +.PP +Deprecated low-level encryption functions +.IX Subsection "Deprecated low-level encryption functions" +.PP +Low-level encryption functions such as \fBAES_encrypt\fR\|(3) and \fBAES_decrypt\fR\|(3) +have been informally discouraged from use for a long time. Applications should +instead use the high level \s-1EVP\s0 APIs \fBEVP_EncryptInit_ex\fR\|(3), +\&\fBEVP_EncryptUpdate\fR\|(3), and \fBEVP_EncryptFinal_ex\fR\|(3) or +\&\fBEVP_DecryptInit_ex\fR\|(3), \fBEVP_DecryptUpdate\fR\|(3) and \fBEVP_DecryptFinal_ex\fR\|(3). +.PP +Deprecated low-level digest functions +.IX Subsection "Deprecated low-level digest functions" +.PP +Use of low-level digest functions such as \fBSHA1_Init\fR\|(3) have been +informally discouraged from use for a long time. Applications should instead +use the the high level \s-1EVP\s0 APIs \fBEVP_DigestInit_ex\fR\|(3), \fBEVP_DigestUpdate\fR\|(3) +and \fBEVP_DigestFinal_ex\fR\|(3), or the quick one-shot \fBEVP_Q_digest\fR\|(3). +.PP +Note that the functions \s-1\fBSHA1\s0\fR\|(3), \s-1\fBSHA224\s0\fR\|(3), \s-1\fBSHA256\s0\fR\|(3), \s-1\fBSHA384\s0\fR\|(3) +and \s-1\fBSHA512\s0\fR\|(3) have changed to macros that use \fBEVP_Q_digest\fR\|(3). +.PP +Deprecated low-level signing functions +.IX Subsection "Deprecated low-level signing functions" +.PP +Use of low-level signing functions such as \fBDSA_sign\fR\|(3) have been +informally discouraged for a long time. Instead applications should use +\&\fBEVP_DigestSign\fR\|(3) and \fBEVP_DigestVerify\fR\|(3). +See also \s-1\fBEVP_SIGNATURE\-RSA\s0\fR\|(7), \s-1\fBEVP_SIGNATURE\-DSA\s0\fR\|(7), +\&\s-1\fBEVP_SIGNATURE\-ECDSA\s0\fR\|(7) and \s-1\fBEVP_SIGNATURE\-ED25519\s0\fR\|(7). +.PP +Deprecated low-level \s-1MAC\s0 functions +.IX Subsection "Deprecated low-level MAC functions" +.PP +Low-level mac functions such as \fBCMAC_Init\fR\|(3) are deprecated. +Applications should instead use the new \s-1\fBEVP_MAC\s0\fR\|(3) interface, using +\&\fBEVP_MAC_CTX_new\fR\|(3), \fBEVP_MAC_CTX_free\fR\|(3), \fBEVP_MAC_init\fR\|(3), +\&\fBEVP_MAC_update\fR\|(3) and \fBEVP_MAC_final\fR\|(3) or the single-shot \s-1MAC\s0 function +\&\fBEVP_Q_mac\fR\|(3). +See \s-1\fBEVP_MAC\s0\fR\|(3), \s-1\fBEVP_MAC\-HMAC\s0\fR\|(7), \s-1\fBEVP_MAC\-CMAC\s0\fR\|(7), \s-1\fBEVP_MAC\-GMAC\s0\fR\|(7), +\&\s-1\fBEVP_MAC\-KMAC\s0\fR\|(7), \s-1\fBEVP_MAC\-BLAKE2\s0\fR\|(7), \fBEVP_MAC\-Poly1305\fR\|(7) and +\&\fBEVP_MAC\-Siphash\fR\|(7) for additional information. +.PP +Note that the one-shot method \s-1\fBHMAC\s0()\fR is still available for compatibility purposes, +but this can also be replaced by using \s-1EVP_Q_MAC\s0 if a library context is required. +.PP +Deprecated low-level validation functions +.IX Subsection "Deprecated low-level validation functions" +.PP +Low-level validation functions such as \fBDH_check\fR\|(3) have been informally +discouraged from use for a long time. Applications should instead use the high-level +\&\s-1EVP_PKEY\s0 APIs such as \fBEVP_PKEY_check\fR\|(3), \fBEVP_PKEY_param_check\fR\|(3), +\&\fBEVP_PKEY_param_check_quick\fR\|(3), \fBEVP_PKEY_public_check\fR\|(3), +\&\fBEVP_PKEY_public_check_quick\fR\|(3), \fBEVP_PKEY_private_check\fR\|(3), +and \fBEVP_PKEY_pairwise_check\fR\|(3). +.PP +Deprecated low-level key exchange functions +.IX Subsection "Deprecated low-level key exchange functions" +.PP +Many low-level functions have been informally discouraged from use for a long +time. Applications should instead use \fBEVP_PKEY_derive\fR\|(3). +See \s-1\fBEVP_KEYEXCH\-DH\s0\fR\|(7), \s-1\fBEVP_KEYEXCH\-ECDH\s0\fR\|(7) and \s-1\fBEVP_KEYEXCH\-X25519\s0\fR\|(7). +.PP +Deprecated low-level key generation functions +.IX Subsection "Deprecated low-level key generation functions" +.PP +Many low-level functions have been informally discouraged from use for a long +time. Applications should instead use \fBEVP_PKEY_keygen_init\fR\|(3) and +\&\fBEVP_PKEY_generate\fR\|(3) as described in \s-1\fBEVP_PKEY\-DSA\s0\fR\|(7), \s-1\fBEVP_PKEY\-DH\s0\fR\|(7), +\&\s-1\fBEVP_PKEY\-RSA\s0\fR\|(7), \s-1\fBEVP_PKEY\-EC\s0\fR\|(7) and \s-1\fBEVP_PKEY\-X25519\s0\fR\|(7). +The 'quick' one-shot function \fBEVP_PKEY_Q_keygen\fR\|(3) and macros for the most +common cases: <\fBEVP_RSA_gen\fR\|(3)> and \fBEVP_EC_gen\fR\|(3) may also be used. +.PP +Deprecated low-level key reading and writing functions +.IX Subsection "Deprecated low-level key reading and writing functions" +.PP +Use of low-level objects (such as \s-1DSA\s0) has been informally discouraged from use +for a long time. Functions to read and write these low-level objects (such as +\&\fBPEM_read_DSA_PUBKEY()\fR) should be replaced. Applications should instead use +\&\fBOSSL_ENCODER_to_bio\fR\|(3) and \fBOSSL_DECODER_from_bio\fR\|(3). +.PP +Deprecated low-level key printing functions +.IX Subsection "Deprecated low-level key printing functions" +.PP +Use of low-level objects (such as \s-1DSA\s0) has been informally discouraged from use +for a long time. Functions to print these low-level objects such as +\&\fBDSA_print()\fR should be replaced with the equivalent \s-1EVP_PKEY\s0 functions. +Application should use one of \fBEVP_PKEY_print_public\fR\|(3), +\&\fBEVP_PKEY_print_private\fR\|(3), \fBEVP_PKEY_print_params\fR\|(3), +\&\fBEVP_PKEY_print_public_fp\fR\|(3), \fBEVP_PKEY_print_private_fp\fR\|(3) or +\&\fBEVP_PKEY_print_params_fp\fR\|(3). Note that internally these use +\&\fBOSSL_ENCODER_to_bio\fR\|(3) and \fBOSSL_DECODER_from_bio\fR\|(3). +.PP +\fIDeprecated function mappings\fR +.IX Subsection "Deprecated function mappings" +.PP +The following functions have been deprecated in 3.0. +.IP "\(bu" 4 +\&\fBAES_bi_ige_encrypt()\fR and \fBAES_ige_encrypt()\fR +.Sp +There is no replacement for the \s-1IGE\s0 functions. New code should not use these modes. +These undocumented functions were never integrated into the \s-1EVP\s0 layer. +They implemented the \s-1AES\s0 Infinite Garble Extension (\s-1IGE\s0) mode and \s-1AES\s0 +Bi-directional \s-1IGE\s0 mode. These modes were never formally standardised and +usage of these functions is believed to be very small. In particular +\&\fBAES_bi_ige_encrypt()\fR has a known bug. It accepts 2 \s-1AES\s0 keys, but only one +is ever used. The security implications are believed to be minimal, but +this issue was never fixed for backwards compatibility reasons. +.IP "\(bu" 4 +\&\fBAES_encrypt()\fR, \fBAES_decrypt()\fR, \fBAES_set_encrypt_key()\fR, \fBAES_set_decrypt_key()\fR, +\&\fBAES_cbc_encrypt()\fR, \fBAES_cfb128_encrypt()\fR, \fBAES_cfb1_encrypt()\fR, \fBAES_cfb8_encrypt()\fR, +\&\fBAES_ecb_encrypt()\fR, \fBAES_ofb128_encrypt()\fR +.IP "\(bu" 4 +\&\fBAES_unwrap_key()\fR, \fBAES_wrap_key()\fR +.Sp +See \*(L"Deprecated low-level encryption functions\*(R" +.IP "\(bu" 4 +\&\fBAES_options()\fR +.Sp +There is no replacement. It returned a string indicating if the \s-1AES\s0 code was unrolled. +.IP "\(bu" 4 +\&\fBASN1_digest()\fR, \fBASN1_sign()\fR, \fBASN1_verify()\fR +.Sp +There are no replacements. These old functions are not used, and could be +disabled with the macro \s-1NO_ASN1_OLD\s0 since OpenSSL 0.9.7. +.IP "\(bu" 4 +\&\fBASN1_STRING_length_set()\fR +.Sp +Use \fBASN1_STRING_set\fR\|(3) or \fBASN1_STRING_set0\fR\|(3) instead. +This was a potentially unsafe function that could change the bounds of a +previously passed in pointer. +.IP "\(bu" 4 +\&\fBBF_encrypt()\fR, \fBBF_decrypt()\fR, \fBBF_set_key()\fR, \fBBF_cbc_encrypt()\fR, \fBBF_cfb64_encrypt()\fR, +\&\fBBF_ecb_encrypt()\fR, \fBBF_ofb64_encrypt()\fR +.Sp +See \*(L"Deprecated low-level encryption functions\*(R". +The Blowfish algorithm has been moved to the Legacy Provider. +.IP "\(bu" 4 +\&\fBBF_options()\fR +.Sp +There is no replacement. This option returned a constant string. +.IP "\(bu" 4 +\&\fBBIO_get_callback()\fR, \fBBIO_set_callback()\fR, \fBBIO_debug_callback()\fR +.Sp +Use the respective non-deprecated \fB_ex()\fR functions. +.IP "\(bu" 4 +\&\fBBN_is_prime_ex()\fR, \fBBN_is_prime_fasttest_ex()\fR +.Sp +Use \fBBN_check_prime\fR\|(3) which avoids possible misuse and always uses at least +64 rounds of the Miller-Rabin primality test. +.IP "\(bu" 4 +\&\fBBN_pseudo_rand()\fR, \fBBN_pseudo_rand_range()\fR +.Sp +Use \fBBN_rand\fR\|(3) and \fBBN_rand_range\fR\|(3). +.IP "\(bu" 4 +\&\fBBN_X931_derive_prime_ex()\fR, \fBBN_X931_generate_prime_ex()\fR, \fBBN_X931_generate_Xpq()\fR +.Sp +There are no replacements for these low-level functions. They were used internally +by \fBRSA_X931_derive_ex()\fR and \fBRSA_X931_generate_key_ex()\fR which are also deprecated. +Use \fBEVP_PKEY_keygen\fR\|(3) instead. +.IP "\(bu" 4 +\&\fBCamellia_encrypt()\fR, \fBCamellia_decrypt()\fR, \fBCamellia_set_key()\fR, +\&\fBCamellia_cbc_encrypt()\fR, \fBCamellia_cfb128_encrypt()\fR, \fBCamellia_cfb1_encrypt()\fR, +\&\fBCamellia_cfb8_encrypt()\fR, \fBCamellia_ctr128_encrypt()\fR, \fBCamellia_ecb_encrypt()\fR, +\&\fBCamellia_ofb128_encrypt()\fR +.Sp +See \*(L"Deprecated low-level encryption functions\*(R". +.IP "\(bu" 4 +\&\fBCAST_encrypt()\fR, \fBCAST_decrypt()\fR, \fBCAST_set_key()\fR, \fBCAST_cbc_encrypt()\fR, +\&\fBCAST_cfb64_encrypt()\fR, \fBCAST_ecb_encrypt()\fR, \fBCAST_ofb64_encrypt()\fR +.Sp +See \*(L"Deprecated low-level encryption functions\*(R". +The \s-1CAST\s0 algorithm has been moved to the Legacy Provider. +.IP "\(bu" 4 +\&\fBCMAC_CTX_new()\fR, \fBCMAC_CTX_cleanup()\fR, \fBCMAC_CTX_copy()\fR, \fBCMAC_CTX_free()\fR, +\&\fBCMAC_CTX_get0_cipher_ctx()\fR +.Sp +See \*(L"Deprecated low-level \s-1MAC\s0 functions\*(R". +.IP "\(bu" 4 +\&\fBCMAC_Init()\fR, \fBCMAC_Update()\fR, \fBCMAC_Final()\fR, \fBCMAC_resume()\fR +.Sp +See \*(L"Deprecated low-level \s-1MAC\s0 functions\*(R". +.IP "\(bu" 4 +\&\fBCRYPTO_mem_ctrl()\fR, \fBCRYPTO_mem_debug_free()\fR, \fBCRYPTO_mem_debug_malloc()\fR, +\&\fBCRYPTO_mem_debug_pop()\fR, \fBCRYPTO_mem_debug_push()\fR, \fBCRYPTO_mem_debug_realloc()\fR, +\&\fBCRYPTO_mem_leaks()\fR, \fBCRYPTO_mem_leaks_cb()\fR, \fBCRYPTO_mem_leaks_fp()\fR, +\&\fBCRYPTO_set_mem_debug()\fR +.Sp +Memory-leak checking has been deprecated in favor of more modern development +tools, such as compiler memory and leak sanitizers or Valgrind. +.IP "\(bu" 4 +\&\fBCRYPTO_cts128_encrypt_block()\fR, \fBCRYPTO_cts128_encrypt()\fR, +\&\fBCRYPTO_cts128_decrypt_block()\fR, \fBCRYPTO_cts128_decrypt()\fR, +\&\fBCRYPTO_nistcts128_encrypt_block()\fR, \fBCRYPTO_nistcts128_encrypt()\fR, +\&\fBCRYPTO_nistcts128_decrypt_block()\fR, \fBCRYPTO_nistcts128_decrypt()\fR +.Sp +Use the higher level functions \fBEVP_CipherInit_ex2()\fR, \fBEVP_CipherUpdate()\fR and +\&\fBEVP_CipherFinal_ex()\fR instead. +See the \*(L"cts_mode\*(R" parameter in +\&\*(L"Gettable and Settable \s-1EVP_CIPHER_CTX\s0 parameters\*(R" in \fBEVP_EncryptInit\fR\|(3). +See \*(L"\s-1EXAMPLES\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3) for a \s-1AES\-256\-CBC\-CTS\s0 example. +.IP "\(bu" 4 +\&\fBd2i_DHparams()\fR, \fBd2i_DHxparams()\fR, \fBd2i_DSAparams()\fR, \fBd2i_DSAPrivateKey()\fR, +\&\fBd2i_DSAPrivateKey_bio()\fR, \fBd2i_DSAPrivateKey_fp()\fR, \fBd2i_DSA_PUBKEY()\fR, +\&\fBd2i_DSA_PUBKEY_bio()\fR, \fBd2i_DSA_PUBKEY_fp()\fR, \fBd2i_DSAPublicKey()\fR, +\&\fBd2i_ECParameters()\fR, \fBd2i_ECPrivateKey()\fR, \fBd2i_ECPrivateKey_bio()\fR, +\&\fBd2i_ECPrivateKey_fp()\fR, \fBd2i_EC_PUBKEY()\fR, \fBd2i_EC_PUBKEY_bio()\fR, +\&\fBd2i_EC_PUBKEY_fp()\fR, \fBo2i_ECPublicKey()\fR, \fBd2i_RSAPrivateKey()\fR, +\&\fBd2i_RSAPrivateKey_bio()\fR, \fBd2i_RSAPrivateKey_fp()\fR, \fBd2i_RSA_PUBKEY()\fR, +\&\fBd2i_RSA_PUBKEY_bio()\fR, \fBd2i_RSA_PUBKEY_fp()\fR, \fBd2i_RSAPublicKey()\fR, +\&\fBd2i_RSAPublicKey_bio()\fR, \fBd2i_RSAPublicKey_fp()\fR +.Sp +See \*(L"Deprecated i2d and d2i functions for low-level key types\*(R" +.IP "\(bu" 4 +\&\fBDES_crypt()\fR, \fBDES_fcrypt()\fR, \fBDES_encrypt1()\fR, \fBDES_encrypt2()\fR, \fBDES_encrypt3()\fR, +\&\fBDES_decrypt3()\fR, \fBDES_ede3_cbc_encrypt()\fR, \fBDES_ede3_cfb64_encrypt()\fR, +\&\fBDES_ede3_cfb_encrypt()\fR,\fBDES_ede3_ofb64_encrypt()\fR, +\&\fBDES_ecb_encrypt()\fR, \fBDES_ecb3_encrypt()\fR, \fBDES_ofb64_encrypt()\fR, \fBDES_ofb_encrypt()\fR, +DES_cfb64_encrypt \fBDES_cfb_encrypt()\fR, \fBDES_cbc_encrypt()\fR, \fBDES_ncbc_encrypt()\fR, +\&\fBDES_pcbc_encrypt()\fR, \fBDES_xcbc_encrypt()\fR, \fBDES_cbc_cksum()\fR, \fBDES_quad_cksum()\fR, +\&\fBDES_check_key_parity()\fR, \fBDES_is_weak_key()\fR, \fBDES_key_sched()\fR, \fBDES_options()\fR, +\&\fBDES_random_key()\fR, \fBDES_set_key()\fR, \fBDES_set_key_checked()\fR, \fBDES_set_key_unchecked()\fR, +\&\fBDES_set_odd_parity()\fR, \fBDES_string_to_2keys()\fR, \fBDES_string_to_key()\fR +.Sp +See \*(L"Deprecated low-level encryption functions\*(R". +Algorithms for \*(L"DESX-CBC\*(R", \*(L"DES-ECB\*(R", \*(L"DES-CBC\*(R", \*(L"DES-OFB\*(R", \*(L"DES-CFB\*(R", +\&\*(L"\s-1DES\-CFB1\*(R"\s0 and \*(L"\s-1DES\-CFB8\*(R"\s0 have been moved to the Legacy Provider. +.IP "\(bu" 4 +\&\fBDH_bits()\fR, \fBDH_security_bits()\fR, \fBDH_size()\fR +.Sp +Use \fBEVP_PKEY_get_bits\fR\|(3), \fBEVP_PKEY_get_security_bits\fR\|(3) and +\&\fBEVP_PKEY_get_size\fR\|(3). +.IP "\(bu" 4 +\&\fBDH_check()\fR, \fBDH_check_ex()\fR, \fBDH_check_params()\fR, \fBDH_check_params_ex()\fR, +\&\fBDH_check_pub_key()\fR, \fBDH_check_pub_key_ex()\fR +.Sp +See \*(L"Deprecated low-level validation functions\*(R" +.IP "\(bu" 4 +\&\fBDH_clear_flags()\fR, \fBDH_test_flags()\fR, \fBDH_set_flags()\fR +.Sp +The \fB\s-1DH_FLAG_CACHE_MONT_P\s0\fR flag has been deprecated without replacement. +The \fB\s-1DH_FLAG_TYPE_DH\s0\fR and \fB\s-1DH_FLAG_TYPE_DHX\s0\fR have been deprecated. +Use \fBEVP_PKEY_is_a()\fR to determine the type of a key. +There is no replacement for setting these flags. +.IP "\(bu" 4 +\&\fBDH_compute_key()\fR \fBDH_compute_key_padded()\fR +.Sp +See \*(L"Deprecated low-level key exchange functions\*(R". +.IP "\(bu" 4 +\&\fBDH_new()\fR, \fBDH_new_by_nid()\fR, \fBDH_free()\fR, \fBDH_up_ref()\fR +.Sp +See \*(L"Deprecated low-level object creation\*(R" +.IP "\(bu" 4 +\&\fBDH_generate_key()\fR, \fBDH_generate_parameters_ex()\fR +.Sp +See \*(L"Deprecated low-level key generation functions\*(R". +.IP "\(bu" 4 +\&\fBDH_get0_pqg()\fR, \fBDH_get0_p()\fR, \fBDH_get0_q()\fR, \fBDH_get0_g()\fR, \fBDH_get0_key()\fR, +\&\fBDH_get0_priv_key()\fR, \fBDH_get0_pub_key()\fR, \fBDH_get_length()\fR, \fBDH_get_nid()\fR +.Sp +See \*(L"Deprecated low-level key parameter getters\*(R" +.IP "\(bu" 4 +\&\fBDH_get_1024_160()\fR, \fBDH_get_2048_224()\fR, \fBDH_get_2048_256()\fR +.Sp +Applications should instead set the \fB\s-1OSSL_PKEY_PARAM_GROUP_NAME\s0\fR as specified in +\&\*(L"\s-1DH\s0 parameters\*(R" in \s-1\fBEVP_PKEY\-DH\s0\fR\|(7)) to one of \*(L"dh_1024_160\*(R", \*(L"dh_2048_224\*(R" or +\&\*(L"dh_2048_256\*(R" when generating a \s-1DH\s0 key. +.IP "\(bu" 4 +\&\s-1\fBDH_KDF_X9_42\s0()\fR +.Sp +Applications should use \fBEVP_PKEY_CTX_set_dh_kdf_type\fR\|(3) instead. +.IP "\(bu" 4 +\&\fBDH_get_default_method()\fR, \fBDH_get0_engine()\fR, DH_meth_*(), \fBDH_new_method()\fR, +\&\fBDH_OpenSSL()\fR, \fBDH_get_ex_data()\fR, \fBDH_set_default_method()\fR, \fBDH_set_method()\fR, +\&\fBDH_set_ex_data()\fR +.Sp +See \*(L"Providers are a replacement for engines and low-level method overrides\*(R" +.IP "\(bu" 4 +\&\fBDHparams_print()\fR, \fBDHparams_print_fp()\fR +.Sp +See \*(L"Deprecated low-level key printing functions\*(R" +.IP "\(bu" 4 +\&\fBDH_set0_key()\fR, \fBDH_set0_pqg()\fR, \fBDH_set_length()\fR +.Sp +See \*(L"Deprecated low-level key parameter setters\*(R" +.IP "\(bu" 4 +\&\fBDSA_bits()\fR, \fBDSA_security_bits()\fR, \fBDSA_size()\fR +.Sp +Use \fBEVP_PKEY_get_bits\fR\|(3), \fBEVP_PKEY_get_security_bits\fR\|(3) and +\&\fBEVP_PKEY_get_size\fR\|(3). +.IP "\(bu" 4 +\&\fBDHparams_dup()\fR, \fBDSA_dup_DH()\fR +.Sp +There is no direct replacement. Applications may use \fBEVP_PKEY_copy_parameters\fR\|(3) +and \fBEVP_PKEY_dup\fR\|(3) instead. +.IP "\(bu" 4 +\&\fBDSA_generate_key()\fR, \fBDSA_generate_parameters_ex()\fR +.Sp +See \*(L"Deprecated low-level key generation functions\*(R". +.IP "\(bu" 4 +\&\fBDSA_get0_engine()\fR, \fBDSA_get_default_method()\fR, \fBDSA_get_ex_data()\fR, +\&\fBDSA_get_method()\fR, DSA_meth_*(), \fBDSA_new_method()\fR, \fBDSA_OpenSSL()\fR, +\&\fBDSA_set_default_method()\fR, \fBDSA_set_ex_data()\fR, \fBDSA_set_method()\fR +.Sp +See \*(L"Providers are a replacement for engines and low-level method overrides\*(R". +.IP "\(bu" 4 +\&\fBDSA_get0_p()\fR, \fBDSA_get0_q()\fR, \fBDSA_get0_g()\fR, \fBDSA_get0_pqg()\fR, \fBDSA_get0_key()\fR, +\&\fBDSA_get0_priv_key()\fR, \fBDSA_get0_pub_key()\fR +.Sp +See \*(L"Deprecated low-level key parameter getters\*(R". +.IP "\(bu" 4 +\&\fBDSA_new()\fR, \fBDSA_free()\fR, \fBDSA_up_ref()\fR +.Sp +See \*(L"Deprecated low-level object creation\*(R" +.IP "\(bu" 4 +\&\fBDSAparams_dup()\fR +.Sp +There is no direct replacement. Applications may use \fBEVP_PKEY_copy_parameters\fR\|(3) +and \fBEVP_PKEY_dup\fR\|(3) instead. +.IP "\(bu" 4 +\&\fBDSAparams_print()\fR, \fBDSAparams_print_fp()\fR, \fBDSA_print()\fR, \fBDSA_print_fp()\fR +.Sp +See \*(L"Deprecated low-level key printing functions\*(R" +.IP "\(bu" 4 +\&\fBDSA_set0_key()\fR, \fBDSA_set0_pqg()\fR +.Sp +See \*(L"Deprecated low-level key parameter setters\*(R" +.IP "\(bu" 4 +\&\fBDSA_set_flags()\fR, \fBDSA_clear_flags()\fR, \fBDSA_test_flags()\fR +.Sp +The \fB\s-1DSA_FLAG_CACHE_MONT_P\s0\fR flag has been deprecated without replacement. +.IP "\(bu" 4 +\&\fBDSA_sign()\fR, \fBDSA_do_sign()\fR, \fBDSA_sign_setup()\fR, \fBDSA_verify()\fR, \fBDSA_do_verify()\fR +.Sp +See \*(L"Deprecated low-level signing functions\*(R". +.IP "\(bu" 4 +\&\fBECDH_compute_key()\fR +.Sp +See \*(L"Deprecated low-level key exchange functions\*(R". +.IP "\(bu" 4 +\&\s-1\fBECDH_KDF_X9_62\s0()\fR +.Sp +Applications may either set this using the helper function +\&\fBEVP_PKEY_CTX_set_ecdh_kdf_type\fR\|(3) or by setting an \s-1\fBOSSL_PARAM\s0\fR\|(3) using the +\&\*(L"kdf-type\*(R" as shown in \*(L"\s-1EXAMPLES\*(R"\s0 in \s-1\fBEVP_KEYEXCH\-ECDH\s0\fR\|(7) +.IP "\(bu" 4 +\&\fBECDSA_sign()\fR, \fBECDSA_sign_ex()\fR, \fBECDSA_sign_setup()\fR, \fBECDSA_do_sign()\fR, +\&\fBECDSA_do_sign_ex()\fR, \fBECDSA_verify()\fR, \fBECDSA_do_verify()\fR +.Sp +See \*(L"Deprecated low-level signing functions\*(R". +.IP "\(bu" 4 +\&\fBECDSA_size()\fR +.Sp +Applications should use \fBEVP_PKEY_get_size\fR\|(3). +.IP "\(bu" 4 +\&\fBEC_GF2m_simple_method()\fR, \fBEC_GFp_mont_method()\fR, \fBEC_GFp_nist_method()\fR, +\&\fBEC_GFp_nistp224_method()\fR, \fBEC_GFp_nistp256_method()\fR, \fBEC_GFp_nistp521_method()\fR, +\&\fBEC_GFp_simple_method()\fR +.Sp +There are no replacements for these functions. Applications should rely on the +library automatically assigning a suitable method internally when an \s-1EC_GROUP\s0 +is constructed. +.IP "\(bu" 4 +\&\fBEC_GROUP_clear_free()\fR +.Sp +Use \fBEC_GROUP_free\fR\|(3) instead. +.IP "\(bu" 4 +\&\fBEC_GROUP_get_curve_GF2m()\fR, \fBEC_GROUP_get_curve_GFp()\fR, \fBEC_GROUP_set_curve_GF2m()\fR, +\&\fBEC_GROUP_set_curve_GFp()\fR +.Sp +Applications should use \fBEC_GROUP_get_curve\fR\|(3) and \fBEC_GROUP_set_curve\fR\|(3). +.IP "\(bu" 4 +\&\fBEC_GROUP_have_precompute_mult()\fR, \fBEC_GROUP_precompute_mult()\fR, +\&\fBEC_KEY_precompute_mult()\fR +.Sp +These functions are not widely used. Applications should instead switch to +named curves which OpenSSL has hardcoded lookup tables for. +.IP "\(bu" 4 +\&\fBEC_GROUP_new()\fR, \fBEC_GROUP_method_of()\fR, \fBEC_POINT_method_of()\fR +.Sp +\&\s-1EC_METHOD\s0 is now an internal-only concept and a suitable \s-1EC_METHOD\s0 is assigned +internally without application intervention. +Users of \fBEC_GROUP_new()\fR should switch to a different suitable constructor. +.IP "\(bu" 4 +\&\fBEC_KEY_can_sign()\fR +.Sp +Applications should use \fBEVP_PKEY_can_sign\fR\|(3) instead. +.IP "\(bu" 4 +\&\fBEC_KEY_check_key()\fR +.Sp +See \*(L"Deprecated low-level validation functions\*(R" +.IP "\(bu" 4 +\&\fBEC_KEY_set_flags()\fR, \fBEC_KEY_get_flags()\fR, \fBEC_KEY_clear_flags()\fR +.Sp +See \*(L"Common \s-1EC\s0 parameters\*(R" in \s-1\fBEVP_PKEY\-EC\s0\fR\|(7) which handles flags as separate +parameters for \fB\s-1OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT\s0\fR, +\&\fB\s-1OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE\s0\fR, \fB\s-1OSSL_PKEY_PARAM_EC_ENCODING\s0\fR, +\&\fB\s-1OSSL_PKEY_PARAM_USE_COFACTOR_ECDH\s0\fR and +\&\fB\s-1OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC\s0\fR. +See also \*(L"\s-1EXAMPLES\*(R"\s0 in \s-1\fBEVP_PKEY\-EC\s0\fR\|(7) +.IP "\(bu" 4 +\&\fBEC_KEY_dup()\fR, \fBEC_KEY_copy()\fR +.Sp +There is no direct replacement. Applications may use \fBEVP_PKEY_copy_parameters\fR\|(3) +and \fBEVP_PKEY_dup\fR\|(3) instead. +.IP "\(bu" 4 +\&\fBEC_KEY_decoded_from_explicit_params()\fR +.Sp +There is no replacement. +.IP "\(bu" 4 +\&\fBEC_KEY_generate_key()\fR +.Sp +See \*(L"Deprecated low-level key generation functions\*(R". +.IP "\(bu" 4 +\&\fBEC_KEY_get0_group()\fR, \fBEC_KEY_get0_private_key()\fR, \fBEC_KEY_get0_public_key()\fR, +\&\fBEC_KEY_get_conv_form()\fR, \fBEC_KEY_get_enc_flags()\fR +.Sp +See \*(L"Deprecated low-level key parameter getters\*(R". +.IP "\(bu" 4 +\&\fBEC_KEY_get0_engine()\fR, \fBEC_KEY_get_default_method()\fR, \fBEC_KEY_get_method()\fR, +\&\fBEC_KEY_new_method()\fR, \fBEC_KEY_get_ex_data()\fR, \fBEC_KEY_OpenSSL()\fR, +\&\fBEC_KEY_set_ex_data()\fR, \fBEC_KEY_set_default_method()\fR, EC_KEY_METHOD_*(), +\&\fBEC_KEY_set_method()\fR +.Sp +See \*(L"Providers are a replacement for engines and low-level method overrides\*(R" +.IP "\(bu" 4 +\&\fBEC_METHOD_get_field_type()\fR +.Sp +Use \fBEC_GROUP_get_field_type\fR\|(3) instead. +See \*(L"Providers are a replacement for engines and low-level method overrides\*(R" +.IP "\(bu" 4 +\&\fBEC_KEY_key2buf()\fR, \fBEC_KEY_oct2key()\fR, \fBEC_KEY_oct2priv()\fR, \fBEC_KEY_priv2buf()\fR, +\&\fBEC_KEY_priv2oct()\fR +.Sp +There are no replacements for these. +.IP "\(bu" 4 +\&\fBEC_KEY_new()\fR, \fBEC_KEY_new_by_curve_name()\fR, \fBEC_KEY_free()\fR, \fBEC_KEY_up_ref()\fR +.Sp +See \*(L"Deprecated low-level object creation\*(R" +.IP "\(bu" 4 +\&\fBEC_KEY_print()\fR, \fBEC_KEY_print_fp()\fR +.Sp +See \*(L"Deprecated low-level key printing functions\*(R" +.IP "\(bu" 4 +\&\fBEC_KEY_set_asn1_flag()\fR, \fBEC_KEY_set_conv_form()\fR, \fBEC_KEY_set_enc_flags()\fR +.Sp +See \*(L"Deprecated low-level key parameter setters\*(R". +.IP "\(bu" 4 +\&\fBEC_KEY_set_group()\fR, \fBEC_KEY_set_private_key()\fR, \fBEC_KEY_set_public_key()\fR, +\&\fBEC_KEY_set_public_key_affine_coordinates()\fR +.Sp +See \*(L"Deprecated low-level key parameter setters\*(R". +.IP "\(bu" 4 +\&\fBECParameters_print()\fR, \fBECParameters_print_fp()\fR, \fBECPKParameters_print()\fR, +\&\fBECPKParameters_print_fp()\fR +.Sp +See \*(L"Deprecated low-level key printing functions\*(R" +.IP "\(bu" 4 +\&\fBEC_POINT_bn2point()\fR, \fBEC_POINT_point2bn()\fR +.Sp +These functions were not particularly useful, since \s-1EC\s0 point serialization +formats are not individual big-endian integers. +.IP "\(bu" 4 +\&\fBEC_POINT_get_affine_coordinates_GF2m()\fR, \fBEC_POINT_get_affine_coordinates_GFp()\fR, +\&\fBEC_POINT_set_affine_coordinates_GF2m()\fR, \fBEC_POINT_set_affine_coordinates_GFp()\fR +.Sp +Applications should use \fBEC_POINT_get_affine_coordinates\fR\|(3) and +\&\fBEC_POINT_set_affine_coordinates\fR\|(3) instead. +.IP "\(bu" 4 +\&\fBEC_POINT_get_Jprojective_coordinates_GFp()\fR, \fBEC_POINT_set_Jprojective_coordinates_GFp()\fR +.Sp +These functions are not widely used. Applications should instead use the +\&\fBEC_POINT_set_affine_coordinates\fR\|(3) and \fBEC_POINT_get_affine_coordinates\fR\|(3) +functions. +.IP "\(bu" 4 +\&\fBEC_POINT_make_affine()\fR, \fBEC_POINTs_make_affine()\fR +.Sp +There is no replacement. These functions were not widely used, and OpenSSL +automatically performs this conversion when needed. +.IP "\(bu" 4 +\&\fBEC_POINT_set_compressed_coordinates_GF2m()\fR, \fBEC_POINT_set_compressed_coordinates_GFp()\fR +.Sp +Applications should use \fBEC_POINT_set_compressed_coordinates\fR\|(3) instead. +.IP "\(bu" 4 +\&\fBEC_POINTs_mul()\fR +.Sp +This function is not widely used. Applications should instead use the +\&\fBEC_POINT_mul\fR\|(3) function. +.IP "\(bu" 4 +\&\fBENGINE_*()\fR +.Sp +All engine functions are deprecated. An engine should be rewritten as a provider. +See \*(L"Providers are a replacement for engines and low-level method overrides\*(R". +.IP "\(bu" 4 +\&\fBERR_load_*()\fR, \fBERR_func_error_string()\fR, \fBERR_get_error_line()\fR, +\&\fBERR_get_error_line_data()\fR, \fBERR_get_state()\fR +.Sp +OpenSSL now loads error strings automatically so these functions are not needed. +.IP "\(bu" 4 +\&\fBERR_peek_error_line_data()\fR, \fBERR_peek_last_error_line_data()\fR +.Sp +The new functions are \fBERR_peek_error_func\fR\|(3), \fBERR_peek_last_error_func\fR\|(3), +\&\fBERR_peek_error_data\fR\|(3), \fBERR_peek_last_error_data\fR\|(3), \fBERR_get_error_all\fR\|(3), +\&\fBERR_peek_error_all\fR\|(3) and \fBERR_peek_last_error_all\fR\|(3). +Applications should use \fBERR_get_error_all\fR\|(3), or pick information +with ERR_peek functions and finish off with getting the error code by using +\&\fBERR_get_error\fR\|(3). +.IP "\(bu" 4 +\&\fBEVP_CIPHER_CTX_iv()\fR, \fBEVP_CIPHER_CTX_iv_noconst()\fR, \fBEVP_CIPHER_CTX_original_iv()\fR +.Sp +Applications should instead use \fBEVP_CIPHER_CTX_get_updated_iv\fR\|(3), +\&\fBEVP_CIPHER_CTX_get_updated_iv\fR\|(3) and \fBEVP_CIPHER_CTX_get_original_iv\fR\|(3) +respectively. +See \fBEVP_CIPHER_CTX_get_original_iv\fR\|(3) for further information. +.IP "\(bu" 4 +\&\fBEVP_CIPHER_meth_*()\fR, \fBEVP_MD_CTX_set_update_fn()\fR, \fBEVP_MD_CTX_update_fn()\fR, +\&\fBEVP_MD_meth_*()\fR +.Sp +See \*(L"Providers are a replacement for engines and low-level method overrides\*(R". +.IP "\(bu" 4 +\&\s-1\fBEVP_PKEY_CTRL_PKCS7_ENCRYPT\s0()\fR, \s-1\fBEVP_PKEY_CTRL_PKCS7_DECRYPT\s0()\fR, +\&\s-1\fBEVP_PKEY_CTRL_PKCS7_SIGN\s0()\fR, \s-1\fBEVP_PKEY_CTRL_CMS_ENCRYPT\s0()\fR, +\&\s-1\fBEVP_PKEY_CTRL_CMS_DECRYPT\s0()\fR, and \s-1\fBEVP_PKEY_CTRL_CMS_SIGN\s0()\fR +.Sp +These control operations are not invoked by the OpenSSL library anymore and +are replaced by direct checks of the key operation against the key type +when the operation is initialized. +.IP "\(bu" 4 +\&\fBEVP_PKEY_CTX_get0_dh_kdf_ukm()\fR, \fBEVP_PKEY_CTX_get0_ecdh_kdf_ukm()\fR +.Sp +See the \*(L"kdf-ukm\*(R" item in \*(L"\s-1DH\s0 key exchange parameters\*(R" in \s-1\fBEVP_KEYEXCH\-DH\s0\fR\|(7) and +\&\*(L"\s-1ECDH\s0 Key Exchange parameters\*(R" in \s-1\fBEVP_KEYEXCH\-ECDH\s0\fR\|(7). +These functions are obsolete and should not be required. +.IP "\(bu" 4 +\&\fBEVP_PKEY_CTX_set_rsa_keygen_pubexp()\fR +.Sp +Applications should use \fBEVP_PKEY_CTX_set1_rsa_keygen_pubexp\fR\|(3) instead. +.IP "\(bu" 4 +\&\fBEVP_PKEY_cmp()\fR, \fBEVP_PKEY_cmp_parameters()\fR +.Sp +Applications should use \fBEVP_PKEY_eq\fR\|(3) and \fBEVP_PKEY_parameters_eq\fR\|(3) instead. +See \fBEVP_PKEY_copy_parameters\fR\|(3) for further details. +.IP "\(bu" 4 +\&\fBEVP_PKEY_encrypt_old()\fR, \fBEVP_PKEY_decrypt_old()\fR, +.Sp +Applications should use \fBEVP_PKEY_encrypt_init\fR\|(3) and \fBEVP_PKEY_encrypt\fR\|(3) or +\&\fBEVP_PKEY_decrypt_init\fR\|(3) and \fBEVP_PKEY_decrypt\fR\|(3) instead. +.IP "\(bu" 4 +\&\fBEVP_PKEY_get0()\fR +.Sp +This function returns \s-1NULL\s0 if the key comes from a provider. +.IP "\(bu" 4 +\&\fBEVP_PKEY_get0_DH()\fR, \fBEVP_PKEY_get0_DSA()\fR, \fBEVP_PKEY_get0_EC_KEY()\fR, \fBEVP_PKEY_get0_RSA()\fR, +\&\fBEVP_PKEY_get1_DH()\fR, \fBEVP_PKEY_get1_DSA()\fR, EVP_PKEY_get1_EC_KEY and \fBEVP_PKEY_get1_RSA()\fR, +\&\fBEVP_PKEY_get0_hmac()\fR, \fBEVP_PKEY_get0_poly1305()\fR, \fBEVP_PKEY_get0_siphash()\fR +.Sp +See \*(L"Functions that return an internal key should be treated as read only\*(R". +.IP "\(bu" 4 +\&\fBEVP_PKEY_meth_*()\fR +.Sp +See \*(L"Providers are a replacement for engines and low-level method overrides\*(R". +.IP "\(bu" 4 +\&\fBEVP_PKEY_new_CMAC_key()\fR +.Sp +See \*(L"Deprecated low-level \s-1MAC\s0 functions\*(R". +.IP "\(bu" 4 +\&\fBEVP_PKEY_assign()\fR, \fBEVP_PKEY_set1_DH()\fR, \fBEVP_PKEY_set1_DSA()\fR, +\&\fBEVP_PKEY_set1_EC_KEY()\fR, \fBEVP_PKEY_set1_RSA()\fR +.Sp +See \*(L"Deprecated low-level key object getters and setters\*(R" +.IP "\(bu" 4 +\&\fBEVP_PKEY_set1_tls_encodedpoint()\fR \fBEVP_PKEY_get1_tls_encodedpoint()\fR +.Sp +These functions were previously used by libssl to set or get an encoded public +key into/from an \s-1EVP_PKEY\s0 object. With OpenSSL 3.0 these are replaced by the more +generic functions \fBEVP_PKEY_set1_encoded_public_key\fR\|(3) and +\&\fBEVP_PKEY_get1_encoded_public_key\fR\|(3). +The old versions have been converted to deprecated macros that just call the +new functions. +.IP "\(bu" 4 +\&\fBEVP_PKEY_set1_engine()\fR, \fBEVP_PKEY_get0_engine()\fR +.Sp +See \*(L"Providers are a replacement for engines and low-level method overrides\*(R". +.IP "\(bu" 4 +\&\fBEVP_PKEY_set_alias_type()\fR +.Sp +This function has been removed. There is no replacement. +See \*(L"\fBEVP_PKEY_set_alias_type()\fR method has been removed\*(R" +.IP "\(bu" 4 +\&\fBHMAC_Init_ex()\fR, \fBHMAC_Update()\fR, \fBHMAC_Final()\fR, \fBHMAC_size()\fR +.Sp +See \*(L"Deprecated low-level \s-1MAC\s0 functions\*(R". +.IP "\(bu" 4 +\&\fBHMAC_CTX_new()\fR, \fBHMAC_CTX_free()\fR, \fBHMAC_CTX_copy()\fR, \fBHMAC_CTX_reset()\fR, +\&\fBHMAC_CTX_set_flags()\fR, \fBHMAC_CTX_get_md()\fR +.Sp +See \*(L"Deprecated low-level \s-1MAC\s0 functions\*(R". +.IP "\(bu" 4 +\&\fBi2d_DHparams()\fR, \fBi2d_DHxparams()\fR +.Sp +See \*(L"Deprecated low-level key reading and writing functions\*(R" +and \*(L"Migration\*(R" in \fBd2i_RSAPrivateKey\fR\|(3) +.IP "\(bu" 4 +\&\fBi2d_DSAparams()\fR, \fBi2d_DSAPrivateKey()\fR, \fBi2d_DSAPrivateKey_bio()\fR, +\&\fBi2d_DSAPrivateKey_fp()\fR, \fBi2d_DSA_PUBKEY()\fR, \fBi2d_DSA_PUBKEY_bio()\fR, +\&\fBi2d_DSA_PUBKEY_fp()\fR, \fBi2d_DSAPublicKey()\fR +.Sp +See \*(L"Deprecated low-level key reading and writing functions\*(R" +and \*(L"Migration\*(R" in \fBd2i_RSAPrivateKey\fR\|(3) +.IP "\(bu" 4 +\&\fBi2d_ECParameters()\fR, \fBi2d_ECPrivateKey()\fR, \fBi2d_ECPrivateKey_bio()\fR, +\&\fBi2d_ECPrivateKey_fp()\fR, \fBi2d_EC_PUBKEY()\fR, \fBi2d_EC_PUBKEY_bio()\fR, +\&\fBi2d_EC_PUBKEY_fp()\fR, \fBi2o_ECPublicKey()\fR +.Sp +See \*(L"Deprecated low-level key reading and writing functions\*(R" +and \*(L"Migration\*(R" in \fBd2i_RSAPrivateKey\fR\|(3) +.IP "\(bu" 4 +\&\fBi2d_RSAPrivateKey()\fR, \fBi2d_RSAPrivateKey_bio()\fR, \fBi2d_RSAPrivateKey_fp()\fR, +\&\fBi2d_RSA_PUBKEY()\fR, \fBi2d_RSA_PUBKEY_bio()\fR, \fBi2d_RSA_PUBKEY_fp()\fR, +\&\fBi2d_RSAPublicKey()\fR, \fBi2d_RSAPublicKey_bio()\fR, \fBi2d_RSAPublicKey_fp()\fR +.Sp +See \*(L"Deprecated low-level key reading and writing functions\*(R" +and \*(L"Migration\*(R" in \fBd2i_RSAPrivateKey\fR\|(3) +.IP "\(bu" 4 +\&\fBIDEA_encrypt()\fR, \fBIDEA_set_decrypt_key()\fR, \fBIDEA_set_encrypt_key()\fR, +\&\fBIDEA_cbc_encrypt()\fR, \fBIDEA_cfb64_encrypt()\fR, \fBIDEA_ecb_encrypt()\fR, +\&\fBIDEA_ofb64_encrypt()\fR +.Sp +See \*(L"Deprecated low-level encryption functions\*(R". +\&\s-1IDEA\s0 has been moved to the Legacy Provider. +.IP "\(bu" 4 +\&\fBIDEA_options()\fR +.Sp +There is no replacement. This function returned a constant string. +.IP "\(bu" 4 +\&\s-1\fBMD2\s0()\fR, \fBMD2_Init()\fR, \fBMD2_Update()\fR, \fBMD2_Final()\fR +.Sp +See \*(L"Deprecated low-level encryption functions\*(R". +\&\s-1MD2\s0 has been moved to the Legacy Provider. +.IP "\(bu" 4 +\&\fBMD2_options()\fR +.Sp +There is no replacement. This function returned a constant string. +.IP "\(bu" 4 +\&\s-1\fBMD4\s0()\fR, \fBMD4_Init()\fR, \fBMD4_Update()\fR, \fBMD4_Final()\fR, \fBMD4_Transform()\fR +.Sp +See \*(L"Deprecated low-level encryption functions\*(R". +\&\s-1MD4\s0 has been moved to the Legacy Provider. +.IP "\(bu" 4 +\&\s-1\fBMDC2\s0()\fR, \fBMDC2_Init()\fR, \fBMDC2_Update()\fR, \fBMDC2_Final()\fR +.Sp +See \*(L"Deprecated low-level encryption functions\*(R". +\&\s-1MDC2\s0 has been moved to the Legacy Provider. +.IP "\(bu" 4 +\&\s-1\fBMD5\s0()\fR, \fBMD5_Init()\fR, \fBMD5_Update()\fR, \fBMD5_Final()\fR, \fBMD5_Transform()\fR +.Sp +See \*(L"Deprecated low-level encryption functions\*(R". +.IP "\(bu" 4 +\&\s-1\fBNCONF_WIN32\s0()\fR +.Sp +This undocumented function has no replacement. +See \*(L"\s-1HISTORY\*(R"\s0 in \fBconfig\fR\|(5) for more details. +.IP "\(bu" 4 +\&\fBOCSP_parse_url()\fR +.Sp +Use \fBOSSL_HTTP_parse_url\fR\|(3) instead. +.IP "\(bu" 4 +\&\fB\s-1OCSP_REQ_CTX\s0\fR type and \fBOCSP_REQ_CTX_*()\fR functions +.Sp +These methods were used to collect all necessary data to form a \s-1HTTP\s0 request, +and to perform the \s-1HTTP\s0 transfer with that request. With OpenSSL 3.0, the +type is \fB\s-1OSSL_HTTP_REQ_CTX\s0\fR, and the deprecated functions are replaced +with \fBOSSL_HTTP_REQ_CTX_*()\fR. See \s-1\fBOSSL_HTTP_REQ_CTX\s0\fR\|(3) for additional +details. +.IP "\(bu" 4 +\&\fBOPENSSL_fork_child()\fR, \fBOPENSSL_fork_parent()\fR, \fBOPENSSL_fork_prepare()\fR +.Sp +There is no replacement for these functions. These pthread fork support methods +were unused by OpenSSL. +.IP "\(bu" 4 +\&\fBOSSL_STORE_ctrl()\fR, \fBOSSL_STORE_do_all_loaders()\fR, \fBOSSL_STORE_LOADER_get0_engine()\fR, +\&\fBOSSL_STORE_LOADER_get0_scheme()\fR, \fBOSSL_STORE_LOADER_new()\fR, +\&\fBOSSL_STORE_LOADER_set_attach()\fR, \fBOSSL_STORE_LOADER_set_close()\fR, +\&\fBOSSL_STORE_LOADER_set_ctrl()\fR, \fBOSSL_STORE_LOADER_set_eof()\fR, +\&\fBOSSL_STORE_LOADER_set_error()\fR, \fBOSSL_STORE_LOADER_set_expect()\fR, +\&\fBOSSL_STORE_LOADER_set_find()\fR, \fBOSSL_STORE_LOADER_set_load()\fR, +\&\fBOSSL_STORE_LOADER_set_open()\fR, \fBOSSL_STORE_LOADER_set_open_ex()\fR, +\&\fBOSSL_STORE_register_loader()\fR, \fBOSSL_STORE_unregister_loader()\fR, +\&\fBOSSL_STORE_vctrl()\fR +.Sp +These functions helped applications and engines create loaders for +schemes they supported. These are all deprecated and discouraged in favour of +provider implementations, see \fBprovider\-storemgmt\fR\|(7). +.IP "\(bu" 4 +\&\fBPEM_read_DHparams()\fR, \fBPEM_read_bio_DHparams()\fR, +\&\fBPEM_read_DSAparams()\fR, \fBPEM_read_bio_DSAparams()\fR, +\&\fBPEM_read_DSAPrivateKey()\fR, \fBPEM_read_DSA_PUBKEY()\fR, +PEM_read_bio_DSAPrivateKey and \fBPEM_read_bio_DSA_PUBKEY()\fR, +\&\fBPEM_read_ECPKParameters()\fR, \fBPEM_read_ECPrivateKey()\fR, \fBPEM_read_EC_PUBKEY()\fR, +\&\fBPEM_read_bio_ECPKParameters()\fR, \fBPEM_read_bio_ECPrivateKey()\fR, \fBPEM_read_bio_EC_PUBKEY()\fR, +\&\fBPEM_read_RSAPrivateKey()\fR, \fBPEM_read_RSA_PUBKEY()\fR, \fBPEM_read_RSAPublicKey()\fR, +\&\fBPEM_read_bio_RSAPrivateKey()\fR, \fBPEM_read_bio_RSA_PUBKEY()\fR, \fBPEM_read_bio_RSAPublicKey()\fR, +\&\fBPEM_write_bio_DHparams()\fR, \fBPEM_write_bio_DHxparams()\fR, \fBPEM_write_DHparams()\fR, \fBPEM_write_DHxparams()\fR, +\&\fBPEM_write_DSAparams()\fR, \fBPEM_write_DSAPrivateKey()\fR, \fBPEM_write_DSA_PUBKEY()\fR, +\&\fBPEM_write_bio_DSAparams()\fR, \fBPEM_write_bio_DSAPrivateKey()\fR, \fBPEM_write_bio_DSA_PUBKEY()\fR, +\&\fBPEM_write_ECPKParameters()\fR, \fBPEM_write_ECPrivateKey()\fR, \fBPEM_write_EC_PUBKEY()\fR, +\&\fBPEM_write_bio_ECPKParameters()\fR, \fBPEM_write_bio_ECPrivateKey()\fR, \fBPEM_write_bio_EC_PUBKEY()\fR, +\&\fBPEM_write_RSAPrivateKey()\fR, \fBPEM_write_RSA_PUBKEY()\fR, \fBPEM_write_RSAPublicKey()\fR, +\&\fBPEM_write_bio_RSAPrivateKey()\fR, \fBPEM_write_bio_RSA_PUBKEY()\fR, +\&\fBPEM_write_bio_RSAPublicKey()\fR, +.Sp +See \*(L"Deprecated low-level key reading and writing functions\*(R" +.IP "\(bu" 4 +\&\s-1\fBPKCS1_MGF1\s0()\fR +.Sp +See \*(L"Deprecated low-level encryption functions\*(R". +.IP "\(bu" 4 +\&\fBRAND_get_rand_method()\fR, \fBRAND_set_rand_method()\fR, \fBRAND_OpenSSL()\fR, +\&\fBRAND_set_rand_engine()\fR +.Sp +Applications should instead use \fBRAND_set_DRBG_type\fR\|(3), +\&\s-1\fBEVP_RAND\s0\fR\|(3) and \s-1\fBEVP_RAND\s0\fR\|(7). +See \fBRAND_set_rand_method\fR\|(3) for more details. +.IP "\(bu" 4 +\&\fBRC2_encrypt()\fR, \fBRC2_decrypt()\fR, \fBRC2_set_key()\fR, \fBRC2_cbc_encrypt()\fR, \fBRC2_cfb64_encrypt()\fR, +\&\fBRC2_ecb_encrypt()\fR, \fBRC2_ofb64_encrypt()\fR, +\&\s-1\fBRC4\s0()\fR, \fBRC4_set_key()\fR, \fBRC4_options()\fR, +\&\fBRC5_32_encrypt()\fR, \fBRC5_32_set_key()\fR, \fBRC5_32_decrypt()\fR, \fBRC5_32_cbc_encrypt()\fR, +\&\fBRC5_32_cfb64_encrypt()\fR, \fBRC5_32_ecb_encrypt()\fR, \fBRC5_32_ofb64_encrypt()\fR +.Sp +See \*(L"Deprecated low-level encryption functions\*(R". +The Algorithms \*(L"\s-1RC2\*(R", \*(L"RC4\*(R"\s0 and \*(L"\s-1RC5\*(R"\s0 have been moved to the Legacy Provider. +.IP "\(bu" 4 +\&\s-1\fBRIPEMD160\s0()\fR, \fBRIPEMD160_Init()\fR, \fBRIPEMD160_Update()\fR, \fBRIPEMD160_Final()\fR, +\&\fBRIPEMD160_Transform()\fR +.Sp +See \*(L"Deprecated low-level digest functions\*(R". +The \s-1RIPE\s0 algorithm has been moved to the Legacy Provider. +.IP "\(bu" 4 +\&\fBRSA_bits()\fR, \fBRSA_security_bits()\fR, \fBRSA_size()\fR +.Sp +Use \fBEVP_PKEY_get_bits\fR\|(3), \fBEVP_PKEY_get_security_bits\fR\|(3) and +\&\fBEVP_PKEY_get_size\fR\|(3). +.IP "\(bu" 4 +\&\fBRSA_check_key()\fR, \fBRSA_check_key_ex()\fR +.Sp +See \*(L"Deprecated low-level validation functions\*(R" +.IP "\(bu" 4 +\&\fBRSA_clear_flags()\fR, \fBRSA_flags()\fR, \fBRSA_set_flags()\fR, \fBRSA_test_flags()\fR, +\&\fBRSA_setup_blinding()\fR, \fBRSA_blinding_off()\fR, \fBRSA_blinding_on()\fR +.Sp +All of these \s-1RSA\s0 flags have been deprecated without replacement: +.Sp +\&\fB\s-1RSA_FLAG_BLINDING\s0\fR, \fB\s-1RSA_FLAG_CACHE_PRIVATE\s0\fR, \fB\s-1RSA_FLAG_CACHE_PUBLIC\s0\fR, +\&\fB\s-1RSA_FLAG_EXT_PKEY\s0\fR, \fB\s-1RSA_FLAG_NO_BLINDING\s0\fR, \fB\s-1RSA_FLAG_THREAD_SAFE\s0\fR +\&\fB\s-1RSA_METHOD_FLAG_NO_CHECK\s0\fR +.IP "\(bu" 4 +\&\fBRSA_generate_key_ex()\fR, \fBRSA_generate_multi_prime_key()\fR +.Sp +See \*(L"Deprecated low-level key generation functions\*(R". +.IP "\(bu" 4 +\&\fBRSA_get0_engine()\fR +.Sp +See \*(L"Providers are a replacement for engines and low-level method overrides\*(R" +.IP "\(bu" 4 +\&\fBRSA_get0_crt_params()\fR, \fBRSA_get0_d()\fR, \fBRSA_get0_dmp1()\fR, \fBRSA_get0_dmq1()\fR, +\&\fBRSA_get0_e()\fR, \fBRSA_get0_factors()\fR, \fBRSA_get0_iqmp()\fR, \fBRSA_get0_key()\fR, +\&\fBRSA_get0_multi_prime_crt_params()\fR, \fBRSA_get0_multi_prime_factors()\fR, \fBRSA_get0_n()\fR, +\&\fBRSA_get0_p()\fR, \fBRSA_get0_pss_params()\fR, \fBRSA_get0_q()\fR, +\&\fBRSA_get_multi_prime_extra_count()\fR +.Sp +See \*(L"Deprecated low-level key parameter getters\*(R" +.IP "\(bu" 4 +\&\fBRSA_new()\fR, \fBRSA_free()\fR, \fBRSA_up_ref()\fR +.Sp +See \*(L"Deprecated low-level object creation\*(R". +.IP "\(bu" 4 +\&\fBRSA_get_default_method()\fR, RSA_get_ex_data and \fBRSA_get_method()\fR +.Sp +See \*(L"Providers are a replacement for engines and low-level method overrides\*(R". +.IP "\(bu" 4 +\&\fBRSA_get_version()\fR +.Sp +There is no replacement. +.IP "\(bu" 4 +\&\fBRSA_meth_*()\fR, \fBRSA_new_method()\fR, RSA_null_method and \fBRSA_PKCS1_OpenSSL()\fR +.Sp +See \*(L"Providers are a replacement for engines and low-level method overrides\*(R". +.IP "\(bu" 4 +\&\fBRSA_padding_add_*()\fR, \fBRSA_padding_check_*()\fR +.Sp +See \*(L"Deprecated low-level signing functions\*(R" and +\&\*(L"Deprecated low-level encryption functions\*(R". +.IP "\(bu" 4 +\&\fBRSA_print()\fR, \fBRSA_print_fp()\fR +.Sp +See \*(L"Deprecated low-level key printing functions\*(R" +.IP "\(bu" 4 +\&\fBRSA_public_encrypt()\fR, \fBRSA_private_decrypt()\fR +.Sp +See \*(L"Deprecated low-level encryption functions\*(R" +.IP "\(bu" 4 +\&\fBRSA_private_encrypt()\fR, \fBRSA_public_decrypt()\fR +.Sp +This is equivalent to doing sign and verify recover operations (with a padding +mode of none). See \*(L"Deprecated low-level signing functions\*(R". +.IP "\(bu" 4 +\&\fBRSAPrivateKey_dup()\fR, \fBRSAPublicKey_dup()\fR +.Sp +There is no direct replacement. Applications may use \fBEVP_PKEY_dup\fR\|(3). +.IP "\(bu" 4 +\&\fBRSAPublicKey_it()\fR, \fBRSAPrivateKey_it()\fR +.Sp +See \*(L"Deprecated low-level key reading and writing functions\*(R" +.IP "\(bu" 4 +\&\fBRSA_set0_crt_params()\fR, \fBRSA_set0_factors()\fR, \fBRSA_set0_key()\fR, +\&\fBRSA_set0_multi_prime_params()\fR +.Sp +See \*(L"Deprecated low-level key parameter setters\*(R". +.IP "\(bu" 4 +\&\fBRSA_set_default_method()\fR, \fBRSA_set_method()\fR, \fBRSA_set_ex_data()\fR +.Sp +See \*(L"Providers are a replacement for engines and low-level method overrides\*(R" +.IP "\(bu" 4 +\&\fBRSA_sign()\fR, \fBRSA_sign_ASN1_OCTET_STRING()\fR, \fBRSA_verify()\fR, +\&\fBRSA_verify_ASN1_OCTET_STRING()\fR, \fBRSA_verify_PKCS1_PSS()\fR, +\&\fBRSA_verify_PKCS1_PSS_mgf1()\fR +.Sp +See \*(L"Deprecated low-level signing functions\*(R". +.IP "\(bu" 4 +\&\fBRSA_X931_derive_ex()\fR, \fBRSA_X931_generate_key_ex()\fR, \fBRSA_X931_hash_id()\fR +.Sp +There are no replacements for these functions. +X931 padding can be set using \*(L"Signature Parameters\*(R" in \s-1\fBEVP_SIGNATURE\-RSA\s0\fR\|(7). +See \fB\s-1OSSL_SIGNATURE_PARAM_PAD_MODE\s0\fR. +.IP "\(bu" 4 +\&\fBSEED_encrypt()\fR, \fBSEED_decrypt()\fR, \fBSEED_set_key()\fR, \fBSEED_cbc_encrypt()\fR, +\&\fBSEED_cfb128_encrypt()\fR, \fBSEED_ecb_encrypt()\fR, \fBSEED_ofb128_encrypt()\fR +.Sp +See \*(L"Deprecated low-level encryption functions\*(R". +The \s-1SEED\s0 algorithm has been moved to the Legacy Provider. +.IP "\(bu" 4 +\&\fBSHA1_Init()\fR, \fBSHA1_Update()\fR, \fBSHA1_Final()\fR, \fBSHA1_Transform()\fR, +\&\fBSHA224_Init()\fR, \fBSHA224_Update()\fR, \fBSHA224_Final()\fR, +\&\fBSHA256_Init()\fR, \fBSHA256_Update()\fR, \fBSHA256_Final()\fR, \fBSHA256_Transform()\fR, +\&\fBSHA384_Init()\fR, \fBSHA384_Update()\fR, \fBSHA384_Final()\fR, +\&\fBSHA512_Init()\fR, \fBSHA512_Update()\fR, \fBSHA512_Final()\fR, \fBSHA512_Transform()\fR +.Sp +See \*(L"Deprecated low-level digest functions\*(R". +.IP "\(bu" 4 +\&\fBSRP_Calc_A()\fR, \fBSRP_Calc_B()\fR, \fBSRP_Calc_client_key()\fR, \fBSRP_Calc_server_key()\fR, +\&\fBSRP_Calc_u()\fR, \fBSRP_Calc_x()\fR, \fBSRP_check_known_gN_param()\fR, \fBSRP_create_verifier()\fR, +\&\fBSRP_create_verifier_BN()\fR, \fBSRP_get_default_gN()\fR, \fBSRP_user_pwd_free()\fR, \fBSRP_user_pwd_new()\fR, +\&\fBSRP_user_pwd_set0_sv()\fR, \fBSRP_user_pwd_set1_ids()\fR, \fBSRP_user_pwd_set_gN()\fR, +\&\fBSRP_VBASE_add0_user()\fR, \fBSRP_VBASE_free()\fR, \fBSRP_VBASE_get1_by_user()\fR, \fBSRP_VBASE_init()\fR, +\&\fBSRP_VBASE_new()\fR, \fBSRP_Verify_A_mod_N()\fR, \fBSRP_Verify_B_mod_N()\fR +.Sp +There are no replacements for the \s-1SRP\s0 functions. +.IP "\(bu" 4 +\&\fBSSL_CTX_set_tmp_dh_callback()\fR, \fBSSL_set_tmp_dh_callback()\fR, +\&\fBSSL_CTX_set_tmp_dh()\fR, \fBSSL_set_tmp_dh()\fR +.Sp +These are used to set the Diffie-Hellman (\s-1DH\s0) parameters that are to be used by +servers requiring ephemeral \s-1DH\s0 keys. Instead applications should consider using +the built-in \s-1DH\s0 parameters that are available by calling \fBSSL_CTX_set_dh_auto\fR\|(3) +or \fBSSL_set_dh_auto\fR\|(3). If custom parameters are necessary then applications can +use the alternative functions \fBSSL_CTX_set0_tmp_dh_pkey\fR\|(3) and +\&\fBSSL_set0_tmp_dh_pkey\fR\|(3). There is no direct replacement for the \*(L"callback\*(R" +functions. The callback was originally useful in order to have different +parameters for export and non-export ciphersuites. Export ciphersuites are no +longer supported by OpenSSL. Use of the callback functions should be replaced +by one of the other methods described above. +.IP "\(bu" 4 +\&\fBSSL_CTX_set_tlsext_ticket_key_cb()\fR +.Sp +Use the new \fBSSL_CTX_set_tlsext_ticket_key_evp_cb\fR\|(3) function instead. +.IP "\(bu" 4 +\&\s-1\fBWHIRLPOOL\s0()\fR, \fBWHIRLPOOL_Init()\fR, \fBWHIRLPOOL_Update()\fR, \fBWHIRLPOOL_Final()\fR, +\&\fBWHIRLPOOL_BitUpdate()\fR +.Sp +See \*(L"Deprecated low-level digest functions\*(R". +The Whirlpool algorithm has been moved to the Legacy Provider. +.IP "\(bu" 4 +\&\fBX509_certificate_type()\fR +.Sp +This was an undocumented function. Applications can use \fBX509_get0_pubkey\fR\|(3) +and \fBX509_get0_signature\fR\|(3) instead. +.IP "\(bu" 4 +\&\fBX509_http_nbio()\fR, \fBX509_CRL_http_nbio()\fR +.Sp +Use \fBX509_load_http\fR\|(3) and \fBX509_CRL_load_http\fR\|(3) instead. +.PP +\fI\s-1NID\s0 handling for provided keys and algorithms\fR +.IX Subsection "NID handling for provided keys and algorithms" +.PP +The following functions for \s-1NID\s0 (numeric id) handling have changed semantics. +.IP "\(bu" 4 +\&\fBEVP_PKEY_id()\fR, \fBEVP_PKEY_get_id()\fR +.Sp +This function was previously used to reliably return the \s-1NID\s0 of +an \s-1EVP_PKEY\s0 object, e.g., to look up the name of the algorithm of +such \s-1EVP_PKEY\s0 by calling \fBOBJ_nid2sn\fR\|(3). With the introduction +of \fBprovider\fR\|(7)s \fBEVP_PKEY_id()\fR or its new equivalent +\&\fBEVP_PKEY_get_id\fR\|(3) might now also return the value \-1 +(\fB\s-1EVP_PKEY_KEYMGMT\s0\fR) indicating the use of a provider to +implement the \s-1EVP_PKEY\s0 object. Therefore, the use of +\&\fBEVP_PKEY_get0_type_name\fR\|(3) is recommended for retrieving +the name of the \s-1EVP_PKEY\s0 algorithm. +.SS "Using the \s-1FIPS\s0 Module in applications" +.IX Subsection "Using the FIPS Module in applications" +See \fBfips_module\fR\|(7) and \s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7) for details. +.SS "OpenSSL command line application changes" +.IX Subsection "OpenSSL command line application changes" +\fINew applications\fR +.IX Subsection "New applications" +.PP +\&\fBopenssl kdf\fR uses the new \s-1\fBEVP_KDF\s0\fR\|(3) \s-1API.\s0 +\&\fBopenssl kdf\fR uses the new \s-1\fBEVP_MAC\s0\fR\|(3) \s-1API.\s0 +.PP +\fIAdded options\fR +.IX Subsection "Added options" +.PP +\&\fB\-provider_path\fR and \fB\-provider\fR are available to all apps and can be used +multiple times to load any providers, such as the 'legacy' provider or third +party providers. If used then the 'default' provider would also need to be +specified if required. The \fB\-provider_path\fR must be specified before the +\&\fB\-provider\fR option. +.PP +The \fBlist\fR app has many new options. See \fBopenssl\-list\fR\|(1) for more +information. +.PP +\&\fB\-crl_lastupdate\fR and \fB\-crl_nextupdate\fR used by \fBopenssl ca\fR allows +explicit setting of fields in the generated \s-1CRL.\s0 +.PP +\fIRemoved options\fR +.IX Subsection "Removed options" +.PP +Interactive mode is not longer available. +.PP +The \fB\-crypt\fR option used by \fBopenssl passwd\fR. +The \fB\-c\fR option used by \fBopenssl x509\fR, \fBopenssl dhparam\fR, +\&\fBopenssl dsaparam\fR, and \fBopenssl ecparam\fR. +.PP +\fIOther Changes\fR +.IX Subsection "Other Changes" +.PP +The output of Command line applications may have minor changes. +These are primarily changes in capitalisation and white space. However, in some +cases, there are additional differences. +For example, the \s-1DH\s0 parameters output from \fBopenssl dhparam\fR now lists 'P', +\&'Q', 'G' and 'pcounter' instead of 'prime', 'generator', 'subgroup order' and +\&'counter' respectively. +.PP +The \fBopenssl\fR commands that read keys, certificates, and CRLs now +automatically detect the \s-1PEM\s0 or \s-1DER\s0 format of the input files so it is not +necessary to explicitly specify the input format anymore. However if the +input format option is used the specified format will be required. +.PP +\&\fBopenssl speed\fR no longer uses low-level \s-1API\s0 calls. +This implies some of the performance numbers might not be comparable with the +previous releases due to higher overhead. This applies particularly to +measuring performance on smaller data chunks. +.PP +b<openssl dhparam>, \fBopenssl dsa\fR, \fBopenssl gendsa\fR, \fBopenssl dsaparam\fR, +\&\fBopenssl genrsa\fR and \fBopenssl rsa\fR have been modified to use \s-1PKEY\s0 APIs. +\&\fBopenssl genrsa\fR and \fBopenssl rsa\fR now write \s-1PKCS\s0 #8 keys by default. +.PP +\fIDefault settings\fR +.IX Subsection "Default settings" +.PP +\&\*(L"\s-1SHA256\*(R"\s0 is now the default digest for \s-1TS\s0 query used by \fBopenssl ts\fR. +.PP +\fIDeprecated apps\fR +.IX Subsection "Deprecated apps" +.PP +\&\fBopenssl rsautl\fR is deprecated, use \fBopenssl pkeyutl\fR instead. +\&\fBopenssl dhparam\fR, \fBopenssl dsa\fR, \fBopenssl gendsa\fR, \fBopenssl dsaparam\fR, +\&\fBopenssl genrsa\fR, \fBopenssl rsa\fR, \fBopenssl genrsa\fR and \fBopenssl rsa\fR are +now in maintenance mode and no new features will be added to them. +.SS "\s-1TLS\s0 Changes" +.IX Subsection "TLS Changes" +.IP "\(bu" 4 +\&\s-1TLS 1.3 FFDHE\s0 key exchange support added +.Sp +This uses \s-1DH\s0 safe prime named groups. +.IP "\(bu" 4 +Support for fully \*(L"pluggable\*(R" TLSv1.3 groups. +.Sp +This means that providers may supply their own group implementations (using +either the \*(L"key exchange\*(R" or the \*(L"key encapsulation\*(R" methods) which will +automatically be detected and used by libssl. +.IP "\(bu" 4 +\&\s-1SSL\s0 and \s-1SSL_CTX\s0 options are now 64 bit instead of 32 bit. +.Sp +The signatures of the functions to get and set options on \s-1SSL\s0 and +\&\s-1SSL_CTX\s0 objects changed from \*(L"unsigned long\*(R" to \*(L"uint64_t\*(R" type. +.Sp +This may require source code changes. For example it is no longer possible +to use the \fB\s-1SSL_OP_\s0\fR macro values in preprocessor \f(CW\*(C`#if\*(C'\fR conditions. +However it is still possible to test whether these macros are defined or not. +.Sp +See \fBSSL_CTX_get_options\fR\|(3), \fBSSL_CTX_set_options\fR\|(3), +\&\fBSSL_get_options\fR\|(3) and \fBSSL_set_options\fR\|(3). +.IP "\(bu" 4 +\&\fBSSL_set1_host()\fR and \fBSSL_add1_host()\fR Changes +.Sp +These functions now take \s-1IP\s0 literal addresses as well as actual hostnames. +.IP "\(bu" 4 +Added \s-1SSL\s0 option \s-1SSL_OP_CLEANSE_PLAINTEXT\s0 +.Sp +If the option is set, openssl cleanses (zeroizes) plaintext bytes from +internal buffers after delivering them to the application. Note, +the application is still responsible for cleansing other copies +(e.g.: data received by \fBSSL_read\fR\|(3)). +.IP "\(bu" 4 +Client-initiated renegotiation is disabled by default. +.Sp +To allow it, use the \fB\-client_renegotiation\fR option, +the \fB\s-1SSL_OP_ALLOW_CLIENT_RENEGOTIATION\s0\fR flag, or the \f(CW\*(C`ClientRenegotiation\*(C'\fR +config parameter as appropriate. +.IP "\(bu" 4 +Secure renegotiation is now required by default for \s-1TLS\s0 connections +.Sp +Support for \s-1RFC 5746\s0 secure renegotiation is now required by default for +\&\s-1SSL\s0 or \s-1TLS\s0 connections to succeed. Applications that require the ability +to connect to legacy peers will need to explicitly set +\&\s-1SSL_OP_LEGACY_SERVER_CONNECT.\s0 Accordingly, \s-1SSL_OP_LEGACY_SERVER_CONNECT\s0 +is no longer set as part of \s-1SSL_OP_ALL.\s0 +.IP "\(bu" 4 +Combining the Configure options no-ec and no-dh no longer disables TLSv1.3 +.Sp +Typically if OpenSSL has no \s-1EC\s0 or \s-1DH\s0 algorithms then it cannot support +connections with TLSv1.3. However OpenSSL now supports \*(L"pluggable\*(R" groups +through providers. Therefore third party providers may supply group +implementations even where there are no built-in ones. Attempting to create +\&\s-1TLS\s0 connections in such a build without also disabling TLSv1.3 at run time or +using third party provider groups may result in handshake failures. TLSv1.3 +can be disabled at compile time using the \*(L"no\-tls1_3\*(R" Configure option. +.IP "\(bu" 4 +\&\fBSSL_CTX_set_ciphersuites()\fR and \fBSSL_set_ciphersuites()\fR changes. +.Sp +The methods now ignore unknown ciphers. +.IP "\(bu" 4 +Security callback change. +.Sp +The security callback, which can be customised by application code, supports +the security operation \s-1SSL_SECOP_TMP_DH.\s0 This is defined to take an \s-1EVP_PKEY\s0 +in the \*(L"other\*(R" parameter. In most places this is what is passed. All these +places occur server side. However there was one client side call of this +security operation and it passed a \s-1DH\s0 object instead. This is incorrect +according to the definition of \s-1SSL_SECOP_TMP_DH,\s0 and is inconsistent with all +of the other locations. Therefore this client side call has been changed to +pass an \s-1EVP_PKEY\s0 instead. +.IP "\(bu" 4 +New \s-1SSL\s0 option \s-1SSL_OP_IGNORE_UNEXPECTED_EOF\s0 +.Sp +The \s-1SSL\s0 option \s-1SSL_OP_IGNORE_UNEXPECTED_EOF\s0 is introduced. If that option +is set, an unexpected \s-1EOF\s0 is ignored, it pretends a close notify was received +instead and so the returned error becomes \s-1SSL_ERROR_ZERO_RETURN.\s0 +.IP "\(bu" 4 +The security strength of \s-1SHA1\s0 and \s-1MD5\s0 based signatures in \s-1TLS\s0 has been reduced. +.Sp +This results in \s-1SSL 3, TLS 1.0, TLS 1.1\s0 and \s-1DTLS 1.0\s0 no longer +working at the default security level of 1 and instead requires security +level 0. The security level can be changed either using the cipher string +with \f(CW@SECLEVEL\fR, or calling \fBSSL_CTX_set_security_level\fR\|(3). This also means +that where the signature algorithms extension is missing from a ClientHello +then the handshake will fail in \s-1TLS 1.2\s0 at security level 1. This is because, +although this extension is optional, failing to provide one means that +OpenSSL will fallback to a default set of signature algorithms. This default +set requires the availability of \s-1SHA1.\s0 +.IP "\(bu" 4 +X509 certificates signed using \s-1SHA1\s0 are no longer allowed at security level 1 and above. +.Sp +In \s-1TLS/SSL\s0 the default security level is 1. It can be set either using the cipher +string with \f(CW@SECLEVEL\fR, or calling \fBSSL_CTX_set_security_level\fR\|(3). If the +leaf certificate is signed with \s-1SHA\-1,\s0 a call to \fBSSL_CTX_use_certificate\fR\|(3) +will fail if the security level is not lowered first. +Outside \s-1TLS/SSL,\s0 the default security level is \-1 (effectively 0). It can +be set using \fBX509_VERIFY_PARAM_set_auth_level\fR\|(3) or using the \fB\-auth_level\fR +options of the commands. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBfips_module\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The migration guide was created for OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021\-2023 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>. diff --git a/secure/lib/libcrypto/man/man7/openssl-core.h.7 b/secure/lib/libcrypto/man/man7/openssl-core.h.7 new file mode 100644 index 000000000000..130ee67440b9 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/openssl-core.h.7 @@ -0,0 +1,182 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "OPENSSL-CORE.H 7ossl" +.TH OPENSSL-CORE.H 7ossl "2023-09-19" "3.0.11" "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" +openssl/core.h \- OpenSSL Core types +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/core.h> +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fI<openssl/core.h>\fR header defines a number of public types that +are used to communicate between the OpenSSL libraries and +implementation providers. +These types are designed to minimise the need for intimate knowledge +of internal structures between the OpenSSL libraries and the providers. +.PP +The types are: +.IP "\s-1\fBOSSL_DISPATCH\s0\fR\|(3)" 4 +.IX Item "OSSL_DISPATCH" +.PD 0 +.IP "\s-1\fBOSSL_ITEM\s0\fR\|(3)" 4 +.IX Item "OSSL_ITEM" +.IP "\s-1\fBOSSL_ALGORITHM\s0\fR\|(3)" 4 +.IX Item "OSSL_ALGORITHM" +.IP "\s-1\fBOSSL_PARAM\s0\fR\|(3)" 4 +.IX Item "OSSL_PARAM" +.IP "\s-1\fBOSSL_CALLBACK\s0\fR\|(3)" 4 +.IX Item "OSSL_CALLBACK" +.IP "\s-1\fBOSSL_PASSPHRASE_CALLBACK\s0\fR\|(3)" 4 +.IX Item "OSSL_PASSPHRASE_CALLBACK" +.PD +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-core_dispatch.h\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The types described here were added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2019\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/openssl-core_dispatch.h.7 b/secure/lib/libcrypto/man/man7/openssl-core_dispatch.h.7 new file mode 100644 index 000000000000..35bd0fbbda06 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/openssl-core_dispatch.h.7 @@ -0,0 +1,180 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "OPENSSL-CORE_DISPATCH.H 7ossl" +.TH OPENSSL-CORE_DISPATCH.H 7ossl "2023-09-19" "3.0.11" "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" +openssl/core_dispatch.h +\&\- OpenSSL provider dispatch numbers and function types +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/core_dispatch.h> +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fI<openssl/core_dispatch.h>\fR header defines all the operation +numbers, dispatch numbers and provider interface function types +currently available. +.PP +The operation and dispatch numbers are represented with macros, which +are named as follows: +.IP "operation numbers" 4 +.IX Item "operation numbers" +These macros have the form \f(CW\*(C`OSSL_OP_\f(CIopname\f(CW\*(C'\fR. +.IP "dipatch numbers" 4 +.IX Item "dipatch numbers" +These macros have the form \f(CW\*(C`OSSL_FUNC_\f(CIopname\f(CW_\f(CIfuncname\f(CW\*(C'\fR, where +\&\f(CW\*(C`\f(CIopname\f(CW\*(C'\fR is the same as in the macro for the operation this +function belongs to. +.PP +With every dispatch number, there is an associated function type. +.PP +For further information, please see the \fBprovider\fR\|(7) +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The types and macros described here were added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020 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>. diff --git a/secure/lib/libcrypto/man/man7/openssl-core_names.h.7 b/secure/lib/libcrypto/man/man7/openssl-core_names.h.7 new file mode 100644 index 000000000000..63fec33d7e30 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/openssl-core_names.h.7 @@ -0,0 +1,178 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "OPENSSL-CORE_NAMES.H 7ossl" +.TH OPENSSL-CORE_NAMES.H 7ossl "2023-09-19" "3.0.11" "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" +openssl/core_names.h \- OpenSSL provider parameter names +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/core_names.h> +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fI<openssl/core_names.h>\fR header defines a multitude of macros +for \s-1\fBOSSL_PARAM\s0\fR\|(3) names, algorithm names and other known names used +with OpenSSL's providers, made available for practical purposes only. +.PP +Existing names are further described in the manuals for OpenSSL's +providers (see \*(L"\s-1SEE ALSO\*(R"\s0) and the manuals for each algorithm they +provide (listed in those provider manuals). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_PROVIDER\-default\fR\|(7), \s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7), +\&\fBOSSL_PROVIDER\-legacy\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The macros described here were added in OpenSSL 3.0. +.SH "CAVEATS" +.IX Header "CAVEATS" +\&\fIThis header file does not constitute a general registry of names\fR. +Providers that implement new algorithms are to be responsible for +their own parameter names. +.PP +However, authors of provider that implement their own variants of +algorithms that OpenSSL providers support will want to pay attention +to the names provided in this header to work in a compatible manner. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020 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>. diff --git a/secure/lib/libcrypto/man/man7/openssl-env.7 b/secure/lib/libcrypto/man/man7/openssl-env.7 new file mode 100644 index 000000000000..414ac2964ec0 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/openssl-env.7 @@ -0,0 +1,215 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "OPENSSL-ENV 7ossl" +.TH OPENSSL-ENV 7ossl "2023-09-19" "3.0.11" "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" +openssl\-env \- OpenSSL environment variables +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The OpenSSL libraries use environment variables to override the +compiled-in default paths for various data. +To avoid security risks, the environment is usually not consulted when +the executable is set-user-ID or set-group-ID. +.IP "\fB\s-1CTLOG_FILE\s0\fR" 4 +.IX Item "CTLOG_FILE" +Specifies the path to a certificate transparency log list. +See \fBCTLOG_STORE_new\fR\|(3). +.IP "\fB\s-1OPENSSL\s0\fR" 4 +.IX Item "OPENSSL" +Specifies the path to the \fBopenssl\fR executable. Used by +the \fBrehash\fR script (see \*(L"Script Configuration\*(R" in \fBopenssl\-rehash\fR\|(1)) +and by the \fB\s-1CA\s0.pl\fR script (see \*(L"\s-1NOTES\*(R"\s0 in \s-1\fBCA\s0.pl\fR\|(1) +.IP "\fB\s-1OPENSSL_CONF\s0\fR, \fB\s-1OPENSSL_CONF_INCLUDE\s0\fR" 4 +.IX Item "OPENSSL_CONF, OPENSSL_CONF_INCLUDE" +Specifies the path to a configuration file and the directory for +included files. +See \fBconfig\fR\|(5). +.IP "\fB\s-1OPENSSL_CONFIG\s0\fR" 4 +.IX Item "OPENSSL_CONFIG" +Specifies a configuration option and filename for the \fBreq\fR and \fBca\fR +commands invoked by the \fB\s-1CA\s0.pl\fR script. +See \s-1\fBCA\s0.pl\fR\|(1). +.IP "\fB\s-1OPENSSL_ENGINES\s0\fR" 4 +.IX Item "OPENSSL_ENGINES" +Specifies the directory from which dynamic engines are loaded. +See \fBopenssl\-engine\fR\|(1). +.IP "\fB\s-1OPENSSL_MALLOC_FD\s0\fR, \fB\s-1OPENSSL_MALLOC_FAILURES\s0\fR" 4 +.IX Item "OPENSSL_MALLOC_FD, OPENSSL_MALLOC_FAILURES" +If built with debugging, this allows memory allocation to fail. +See \fBOPENSSL_malloc\fR\|(3). +.IP "\fB\s-1OPENSSL_MODULES\s0\fR" 4 +.IX Item "OPENSSL_MODULES" +Specifies the directory from which cryptographic providers are loaded. +Equivalently, the generic \fB\-provider\-path\fR command-line option may be used. +.IP "\fB\s-1OPENSSL_WIN32_UTF8\s0\fR" 4 +.IX Item "OPENSSL_WIN32_UTF8" +If set, then \fBUI_OpenSSL\fR\|(3) returns \s-1UTF\-8\s0 encoded strings, rather than +ones encoded in the current code page, and +the \fBopenssl\fR\|(1) program also transcodes the command-line parameters +from the current code page to \s-1UTF\-8.\s0 +This environment variable is only checked on Microsoft Windows platforms. +.IP "\fB\s-1RANDFILE\s0\fR" 4 +.IX Item "RANDFILE" +The state file for the random number generator. +This should not be needed in normal use. +See \fBRAND_load_file\fR\|(3). +.IP "\fB\s-1SSL_CERT_DIR\s0\fR, \fB\s-1SSL_CERT_FILE\s0\fR" 4 +.IX Item "SSL_CERT_DIR, SSL_CERT_FILE" +Specify the default directory or file containing \s-1CA\s0 certificates. +See \fBSSL_CTX_load_verify_locations\fR\|(3). +.IP "\fB\s-1TSGET\s0\fR" 4 +.IX Item "TSGET" +Additional arguments for the \fBtsget\fR\|(1) command. +.IP "\fBOPENSSL_ia32cap\fR, \fBOPENSSL_sparcv9cap\fR, \fBOPENSSL_ppccap\fR, \fBOPENSSL_armcap\fR, \fBOPENSSL_s390xcap\fR" 4 +.IX Item "OPENSSL_ia32cap, OPENSSL_sparcv9cap, OPENSSL_ppccap, OPENSSL_armcap, OPENSSL_s390xcap" +OpenSSL supports a number of different algorithm implementations for +various machines and, by default, it determines which to use based on the +processor capabilities and run time feature enquiry. These environment +variables can be used to exert more control over this selection process. +See \fBOPENSSL_ia32cap\fR\|(3), \fBOPENSSL_s390xcap\fR\|(3). +.IP "\fB\s-1NO_PROXY\s0\fR, \fB\s-1HTTPS_PROXY\s0\fR, \fB\s-1HTTP_PROXY\s0\fR" 4 +.IX Item "NO_PROXY, HTTPS_PROXY, HTTP_PROXY" +Specify a proxy hostname. +See \fBOSSL_HTTP_parse_url\fR\|(3). +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2019\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/openssl-glossary.7 b/secure/lib/libcrypto/man/man7/openssl-glossary.7 new file mode 100644 index 000000000000..04183a5c672b --- /dev/null +++ b/secure/lib/libcrypto/man/man7/openssl-glossary.7 @@ -0,0 +1,337 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "OPENSSL-GLOSSARY 7ossl" +.TH OPENSSL-GLOSSARY 7ossl "2023-09-19" "3.0.11" "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" +openssl\-glossary \- An OpenSSL Glossary +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +.IP "Algorithm" 4 +.IX Item "Algorithm" +Cryptographic primitives such as the \s-1SHA256\s0 digest, or \s-1AES\s0 encryption are +referred to in OpenSSL as \*(L"algorithms\*(R". There can be more than one +implementation for any given algorithm available for use. +.Sp +\&\fBcrypto\fR\|(7) +.IP "\s-1ASN.1, ASN1\s0" 4 +.IX Item "ASN.1, ASN1" +\&\s-1ASN.1\s0 (\*(L"Abstract Syntax Notation One\*(R") is a notation for describing abstract +types and values. It is defined in the ITU-T documents X.680 to X.683: +.Sp +<https://www.itu.int/rec/T\-REC\-X.680>, +<https://www.itu.int/rec/T\-REC\-X.681>, +<https://www.itu.int/rec/T\-REC\-X.682>, +<https://www.itu.int/rec/T\-REC\-X.683> +.IP "Base Provider" 4 +.IX Item "Base Provider" +An OpenSSL Provider that contains encoders and decoders for OpenSSL keys. All +the algorithm implementations in the Base Provider are also available in the +Default Provider. +.Sp +\&\fBOSSL_PROVIDER\-base\fR\|(7) +.IP "Decoder" 4 +.IX Item "Decoder" +A decoder is a type of algorithm used for decoding keys and parameters from some +external format such as \s-1PEM\s0 or \s-1DER.\s0 +.Sp +\&\fBOSSL_DECODER_CTX_new_for_pkey\fR\|(3) +.IP "Default Provider" 4 +.IX Item "Default Provider" +An OpenSSL Provider that contains the most common OpenSSL algorithm +implementations. It is loaded by default if no other provider is available. All +the algorithm implementations in the Base Provider are also available in the +Default Provider. +.Sp +\&\fBOSSL_PROVIDER\-default\fR\|(7) +.ie n .IP "\s-1DER\s0 (""Distinguished Encoding Rules"")" 4 +.el .IP "\s-1DER\s0 (``Distinguished Encoding Rules'')" 4 +.IX Item "DER (Distinguished Encoding Rules)" +\&\s-1DER\s0 is a binary encoding of data, structured according to an \s-1ASN.1\s0 +specification. This is a common encoding used for cryptographic objects +such as private and public keys, certificates, CRLs, ... +.Sp +It is defined in ITU-T document X.690: +.Sp +<https://www.itu.int/rec/T\-REC\-X.690> +.IP "Encoder" 4 +.IX Item "Encoder" +An encoder is a type of algorithm used for encoding keys and parameters to some +external format such as \s-1PEM\s0 or \s-1DER.\s0 +.Sp +\&\fBOSSL_ENCODER_CTX_new_for_pkey\fR\|(3) +.IP "Explicit Fetching" 4 +.IX Item "Explicit Fetching" +Explicit Fetching is a type of Fetching (see Fetching). Explicit Fetching is +where a function call is made to obtain an algorithm object representing an +implementation such as \fBEVP_MD_fetch\fR\|(3) or \fBEVP_CIPHER_fetch\fR\|(3) +.IP "Fetching" 4 +.IX Item "Fetching" +Fetching is the process of looking through the available algorithm +implementations, applying selection criteria (via a property query string), and +finally choosing the implementation that will be used. +.Sp +Also see Explicit Fetching and Implicit Fetching. +.Sp +\&\fBcrypto\fR\|(7) +.IP "\s-1FIPS\s0 Provider" 4 +.IX Item "FIPS Provider" +An OpenSSL Provider that contains OpenSSL algorithm implementations that have +been validated according to the \s-1FIPS 140\-2\s0 standard. +.Sp +\&\s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7) +.IP "Implicit Fetching" 4 +.IX Item "Implicit Fetching" +Implicit Fetching is a type of Fetching (see Fetching). Implicit Fetching is +where an algorithm object with no associated implementation is used such as the +return value from \fBEVP_sha256\fR\|(3) or \fBEVP_aes_128_cbc\fR\|(3). With implicit +fetching an implementation is fetched automatically using default selection +criteria the first time the algorithm is used. +.IP "Legacy Provider" 4 +.IX Item "Legacy Provider" +An OpenSSL Provider that contains algorithm implementations that are considered +insecure or are no longer in common use. +.Sp +\&\fBOSSL_PROVIDER\-legacy\fR\|(7) +.IP "Library Context" 4 +.IX Item "Library Context" +A Library Context in OpenSSL is represented by the type \fB\s-1OSSL_LIB_CTX\s0\fR. It can +be thought of as a scope within which configuration options apply. If an +application does not explicitly create a library context then the \*(L"default\*(R" +one is used. Many OpenSSL functions can take a library context as an argument. +A \s-1NULL\s0 value can always be passed to indicate the default library context. +.Sp +\&\s-1\fBOSSL_LIB_CTX\s0\fR\|(3) +.IP "\s-1MSBLOB\s0" 4 +.IX Item "MSBLOB" +\&\s-1MSBLOB\s0 is a Microsoft specific binary format for \s-1RSA\s0 and \s-1DSA\s0 keys, both +private and public. This form is never passphrase protected. +.IP "Null Provider" 4 +.IX Item "Null Provider" +An OpenSSL Provider that contains no algorithm implementations. This can be +useful to prevent the default provider from being automatically loaded in a +library context. +.Sp +\&\fBOSSL_PROVIDER\-null\fR\|(7) +.IP "Operation" 4 +.IX Item "Operation" +An operation is a group of OpenSSL functions with a common purpose such as +encryption, or digesting. +.Sp +\&\fBcrypto\fR\|(7) +.ie n .IP "\s-1PEM\s0 (""Privacy Enhanced Message"")" 4 +.el .IP "\s-1PEM\s0 (``Privacy Enhanced Message'')" 4 +.IX Item "PEM (Privacy Enhanced Message)" +\&\s-1PEM\s0 is a format used for encoding of binary content into a mail and \s-1ASCII\s0 +friendly form. The content is a series of base64\-encoded lines, surrounded +by begin/end markers each on their own line. For example: +.Sp +.Vb 4 +\& \-\-\-\-\-BEGIN PRIVATE KEY\-\-\-\-\- +\& MIICdg.... +\& ... bhTQ== +\& \-\-\-\-\-END PRIVATE KEY\-\-\-\-\- +.Ve +.Sp +Optional header line(s) may appear after the begin line, and their existence +depends on the type of object being written or read. +.Sp +For all OpenSSL uses, the binary content is expected to be a \s-1DER\s0 encoded +structure. +.Sp +This is defined in \s-1IETF RFC 1421:\s0 +.Sp +<https://tools.ietf.org/html/rfc1421> +.IP "PKCS#8" 4 +.IX Item "PKCS#8" +PKCS#8 is a specification of \s-1ASN.1\s0 structures that OpenSSL uses for storing +or transmitting any private key in a key type agnostic manner. +There are two structures worth noting for OpenSSL use, one that contains the +key data in unencrypted form (known as \*(L"PrivateKeyInfo\*(R") and an encrypted +wrapper structure (known as \*(L"EncryptedPrivateKeyInfo\*(R"). +.Sp +This is specified in \s-1RFC 5208:\s0 +.Sp +<https://tools.ietf.org/html/rfc5208> +.IP "Property" 4 +.IX Item "Property" +A property is a way of classifying and selecting algorithm implementations. +A property is a key/value pair expressed as a string. For example all algorithm +implementations in the default provider have the property \*(L"provider=default\*(R". +An algorithm implementation can have multiple properties defined against it. +.Sp +Also see Property Query String. +.Sp +\&\fBproperty\fR\|(7) +.IP "Property Query String" 4 +.IX Item "Property Query String" +A property query string is a string containing a sequence of properties that +can be used to select an algorithm implementation. For example the query string +\&\*(L"provider=example,foo=bar\*(R" will select algorithms from the \*(L"example\*(R" provider +that have a \*(L"foo\*(R" property defined for them with a value of \*(L"bar\*(R". +.Sp +Property Query Strings are used during fetching. See Fetching. +.Sp +\&\fBproperty\fR\|(7) +.IP "Provider" 4 +.IX Item "Provider" +A provider in OpenSSL is a component that groups together algorithm +implementations. Providers can come from OpenSSL itself or from third parties. +.Sp +\&\fBprovider\fR\|(7) +.IP "\s-1PVK\s0" 4 +.IX Item "PVK" +\&\s-1PVK\s0 is a Microsoft specific binary format for \s-1RSA\s0 and \s-1DSA\s0 private keys. +This form may be passphrase protected. +.IP "SubjectPublicKeyInfo" 4 +.IX Item "SubjectPublicKeyInfo" +SubjectPublicKeyInfo is an \s-1ASN.1\s0 structure that OpenSSL uses for storing and +transmitting any public key in a key type agnostic manner. +.Sp +This is specified as part of the specification for certificates, \s-1RFC 5280:\s0 +.Sp +<https://tools.ietf.org/html/rfc5280> +.SH "HISTORY" +.IX Header "HISTORY" +This glossary was added in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2023 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>. diff --git a/secure/lib/libcrypto/man/man7/openssl-threads.7 b/secure/lib/libcrypto/man/man7/openssl-threads.7 new file mode 100644 index 000000000000..c699373765e3 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/openssl-threads.7 @@ -0,0 +1,234 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "OPENSSL-THREADS 7ossl" +.TH OPENSSL-THREADS 7ossl "2023-09-19" "3.0.11" "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" +openssl\-threads \- Overview of thread safety in OpenSSL +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +In this man page, we use the term \fBthread-safe\fR to indicate that an +object or function can be used by multiple threads at the same time. +.PP +OpenSSL can be built with or without threads support. The most important +use of this support is so that OpenSSL itself can use a single consistent +\&\s-1API,\s0 as shown in \*(L"\s-1EXAMPLES\*(R"\s0 in \fBCRYPTO_THREAD_run_once\fR\|(3). +Multi-platform applications can also use this \s-1API.\s0 +.PP +In particular, being configured for threads support does not imply that +all OpenSSL objects are thread-safe. +To emphasize: \fImost objects are not safe for simultaneous use\fR. +Exceptions to this should be documented on the specific manual pages, and +some general high-level guidance is given here. +.PP +One major use of the OpenSSL thread \s-1API\s0 is to implement reference counting. +Many objects within OpenSSL are reference-counted, so resources are not +released, until the last reference is removed. +References are often increased automatically (such as when an \fBX509\fR +certificate object is added into an \fBX509_STORE\fR trust store). +There is often an \fB\f(BIobject\fB_up_ref\fR() function that can be used to increase +the reference count. +Failure to match \fB\f(BIobject\fB_up_ref\fR() calls with the right number of +\&\fB\f(BIobject\fB_free\fR() calls is a common source of memory leaks when a program +exits. +.PP +Many objects have set and get \s-1API\s0's to set attributes in the object. +A \f(CW\*(C`set0\*(C'\fR passes ownership from the caller to the object and a +\&\f(CW\*(C`get0\*(C'\fR returns a pointer but the attribute ownership +remains with the object and a reference to it is returned. +A \f(CW\*(C`set1\*(C'\fR or \f(CW\*(C`get1\*(C'\fR function does not change the ownership, but instead +updates the attribute's reference count so that the object is shared +between the caller and the object; the caller must free the returned +attribute when finished. +Functions that involve attributes that have reference counts themselves, +but are named with just \f(CW\*(C`set\*(C'\fR or \f(CW\*(C`get\*(C'\fR are historical; and the documentation +must state how the references are handled. +Get methods are often thread-safe as long as the ownership requirements are +met and shared objects are not modified. +Set methods, or modifying shared objects, are generally not thread-safe +as discussed below. +.PP +Objects are thread-safe +as long as the \s-1API\s0's being invoked don't modify the object; in this +case the parameter is usually marked in the \s-1API\s0 as \f(CW\*(C`const\*(C'\fR. +Not all parameters are marked this way. +Note that a \f(CW\*(C`const\*(C'\fR declaration does not mean immutable; for example +\&\fBX509_cmp\fR\|(3) takes pointers to \f(CW\*(C`const\*(C'\fR objects, but the implementation +uses a C cast to remove that so it can lock objects, generate and cache +a \s-1DER\s0 encoding, and so on. +.PP +Another instance of thread-safety is when updates to an object's +internal state, such as cached values, are done with locks. +One example of this is the reference counting \s-1API\s0's described above. +.PP +In all cases, however, it is generally not safe for one thread to +mutate an object, such as setting elements of a private or public key, +while another thread is using that object, such as verifying a signature. +.PP +The same \s-1API\s0's can usually be used simultaneously on different objects +without interference. +For example, two threads can calculate a signature using two different +\&\fB\s-1EVP_PKEY_CTX\s0\fR objects. +.PP +For implicit global state or singletons, thread-safety depends on the facility. +The \fBCRYPTO_secure_malloc\fR\|(3) and related \s-1API\s0's have their own lock, +while \fBCRYPTO_malloc\fR\|(3) assumes the underlying platform allocation +will do any necessary locking. +Some \s-1API\s0's, such as \fBNCONF_load\fR\|(3) and related, or \fBOBJ_create\fR\|(3) +do no locking at all; this can be considered a bug. +.PP +A separate, although related, issue is modifying \*(L"factory\*(R" objects +when other objects have been created from that. +For example, an \fB\s-1SSL_CTX\s0\fR object created by \fBSSL_CTX_new\fR\|(3) is used +to create per-connection \fB\s-1SSL\s0\fR objects by calling \fBSSL_new\fR\|(3). +In this specific case, and probably for factory methods in general, it is +not safe to modify the factory object after it has been used to create +other objects. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBCRYPTO_THREAD_run_once\fR\|(3), +local system threads documentation. +.SH "BUGS" +.IX Header "BUGS" +This page is admittedly very incomplete. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2021 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>. diff --git a/secure/lib/libcrypto/man/man7/openssl_user_macros.7 b/secure/lib/libcrypto/man/man7/openssl_user_macros.7 new file mode 100644 index 000000000000..f6fba37c9154 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/openssl_user_macros.7 @@ -0,0 +1,231 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "OPENSSL_USER_MACROS 7ossl" +.TH OPENSSL_USER_MACROS 7ossl "2023-09-22" "3.0.11" "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" +openssl_user_macros, OPENSSL_API_COMPAT, OPENSSL_NO_DEPRECATED +\&\- User defined macros +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +User defined macros allow the programmer to control certain aspects of +what is exposed by the OpenSSL headers. +.PP +\&\fB\s-1NOTE:\s0\fR to be effective, a user defined macro \fImust be defined +before including any header file that depends on it\fR, either in the +compilation command (\f(CW\*(C`cc \-DMACRO=value\*(C'\fR) or by defining the macro in +source before including any headers. +.PP +Other manual pages may refer to this page when declarations depend on +user defined macros. +.SS "The macros" +.IX Subsection "The macros" +.IP "\fB\s-1OPENSSL_API_COMPAT\s0\fR" 4 +.IX Item "OPENSSL_API_COMPAT" +The value is a version number, given in one of the following two forms: +.RS 4 +.ie n .IP """0xMNNFF000L""" 4 +.el .IP "\f(CW0xMNNFF000L\fR" 4 +.IX Item "0xMNNFF000L" +This is the form supported for all versions up to 1.1.x, where \f(CW\*(C`M\*(C'\fR +represents the major number, \f(CW\*(C`NN\*(C'\fR represents the minor number, and +\&\f(CW\*(C`FF\*(C'\fR represents the fix number, as a hexadecimal number. For version +1.1.0, that's \f(CW\*(C`0x10100000L\*(C'\fR. +.Sp +Any version number may be given, but these numbers are +the current known major deprecation points, making them the most +meaningful: +.RS 4 +.ie n .IP """0x00908000L"" (version 0.9.8)" 4 +.el .IP "\f(CW0x00908000L\fR (version 0.9.8)" 4 +.IX Item "0x00908000L (version 0.9.8)" +.PD 0 +.ie n .IP """0x10000000L"" (version 1.0.0)" 4 +.el .IP "\f(CW0x10000000L\fR (version 1.0.0)" 4 +.IX Item "0x10000000L (version 1.0.0)" +.ie n .IP """0x10100000L"" (version 1.1.0)" 4 +.el .IP "\f(CW0x10100000L\fR (version 1.1.0)" 4 +.IX Item "0x10100000L (version 1.1.0)" +.RE +.RS 4 +.PD +.Sp +For convenience, higher numbers are accepted as well, as long as +feasible. For example, \f(CW\*(C`0x60000000L\*(C'\fR will work as expected. +However, it is recommended to start using the second form instead: +.RE +.ie n .IP """mmnnpp""" 4 +.el .IP "\f(CWmmnnpp\fR" 4 +.IX Item "mmnnpp" +This form is a simple decimal number calculated with this formula: +.Sp +\&\fImajor\fR * 10000 + \fIminor\fR * 100 + \fIpatch\fR +.Sp +where \fImajor\fR, \fIminor\fR and \fIpatch\fR are the desired major, +minor and patch components of the version number. For example: +.RS 4 +.IP "30000 corresponds to version 3.0.0" 4 +.IX Item "30000 corresponds to version 3.0.0" +.PD 0 +.IP "10002 corresponds to version 1.0.2" 4 +.IX Item "10002 corresponds to version 1.0.2" +.IP "420101 corresponds to version 42.1.1" 4 +.IX Item "420101 corresponds to version 42.1.1" +.RE +.RS 4 +.RE +.RE +.RS 4 +.PD +.Sp +If \fB\s-1OPENSSL_API_COMPAT\s0\fR is undefined, this default value is used in its +place: +\&\f(CW30000\fR +.RE +.IP "\fB\s-1OPENSSL_NO_DEPRECATED\s0\fR" 4 +.IX Item "OPENSSL_NO_DEPRECATED" +If this macro is defined, all deprecated public symbols in all OpenSSL +versions up to and including the version given by \fB\s-1OPENSSL_API_COMPAT\s0\fR +(or the default value given above, when \fB\s-1OPENSSL_API_COMPAT\s0\fR isn't defined) +will be hidden. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2018\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/ossl_store-file.7 b/secure/lib/libcrypto/man/man7/ossl_store-file.7 index 8a6e511420f2..937f7f9d7dd7 100644 --- a/secure/lib/libcrypto/man/man7/ossl_store-file.7 +++ b/secure/lib/libcrypto/man/man7/ossl_store-file.7 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .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 \{\ @@ -132,8 +130,8 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "OSSL_STORE-FILE 7" -.TH OSSL_STORE-FILE 7 "2022-06-21" "1.1.1p" "OpenSSL" +.IX Title "OSSL_STORE-FILE 7ossl" +.TH OSSL_STORE-FILE 7ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -170,7 +168,7 @@ only). .SH "NOTES" .IX Header "NOTES" When needed, the 'file' scheme loader will require a pass phrase by -using the \f(CW\*(C`UI_METHOD\*(C'\fR that was passed via \fBOSSL_STORE_open()\fR. +using the \fB\s-1UI_METHOD\s0\fR that was passed via \fBOSSL_STORE_open()\fR. This pass phrase is expected to be \s-1UTF\-8\s0 encoded, anything else will give an undefined result. The files made accessible through this loader are expected to be @@ -185,7 +183,7 @@ See \fBpassphrase\-encoding\fR\|(7) for more information. .IX Header "COPYRIGHT" Copyright 2018 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +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>. diff --git a/secure/lib/libcrypto/man/man7/ossl_store.7 b/secure/lib/libcrypto/man/man7/ossl_store.7 index c7cf78fda275..6a4d5c499cc9 100644 --- a/secure/lib/libcrypto/man/man7/ossl_store.7 +++ b/secure/lib/libcrypto/man/man7/ossl_store.7 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .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 \{\ @@ -132,8 +130,8 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "OSSL_STORE 7" -.TH OSSL_STORE 7 "2022-06-21" "1.1.1p" "OpenSSL" +.IX Title "OSSL_STORE 7ossl" +.TH OSSL_STORE 7ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -209,7 +207,7 @@ other encoding is undefined. .IX Header "COPYRIGHT" Copyright 2016\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +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>. diff --git a/secure/lib/libcrypto/man/man7/passphrase-encoding.7 b/secure/lib/libcrypto/man/man7/passphrase-encoding.7 index 5cb28c09f64b..2e0394073cee 100644 --- a/secure/lib/libcrypto/man/man7/passphrase-encoding.7 +++ b/secure/lib/libcrypto/man/man7/passphrase-encoding.7 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .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 \{\ @@ -132,14 +130,15 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "PASSPHRASE-ENCODING 7" -.TH PASSPHRASE-ENCODING 7 "2022-06-21" "1.1.1p" "OpenSSL" +.IX Title "PASSPHRASE-ENCODING 7ossl" +.TH PASSPHRASE-ENCODING 7ossl "2023-09-19" "3.0.11" "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" -passphrase\-encoding \&\- How diverse parts of OpenSSL treat pass phrases character encoding +passphrase\-encoding +\&\- How diverse parts of OpenSSL treat pass phrases character encoding .SH "DESCRIPTION" .IX Header "DESCRIPTION" In a modern world with all sorts of character encodings, the treatment of pass @@ -228,7 +227,7 @@ Also note that the sub-sections below discuss human readable pass phrases. This is particularly relevant for PKCS#12 objects, where human readable pass phrases are assumed. For other objects, it's as legitimate to use any byte sequence (such as a -sequence of bytes from `/dev/urandom` that's been saved away), which makes any +sequence of bytes from \fI/dev/urandom\fR that's been saved away), which makes any character encoding discussion irrelevant; in such cases, simply use the same byte sequence as it is. .SS "Creating new objects" @@ -238,7 +237,7 @@ encoded using \s-1UTF\-8.\s0 This is default on most modern Unixes, but may involve an effort on other platforms. Specifically for Windows, setting the environment variable -\&\f(CW\*(C`OPENSSL_WIN32_UTF8\*(C'\fR will have anything entered on [Windows] console prompt +\&\fB\s-1OPENSSL_WIN32_UTF8\s0\fR will have anything entered on [Windows] console prompt converted to \s-1UTF\-8\s0 (command line and separately prompted pass phrases alike). .SS "Opening existing objects" .IX Subsection "Opening existing objects" @@ -279,9 +278,9 @@ erroneous/non\-compliant encoding used by OpenSSL older than 1.1.0) \&\fBd2i_PKCS8PrivateKey_bio\fR\|(3) .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2018\-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +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>. diff --git a/secure/lib/libcrypto/man/man7/property.7 b/secure/lib/libcrypto/man/man7/property.7 new file mode 100644 index 000000000000..691741356a6e --- /dev/null +++ b/secure/lib/libcrypto/man/man7/property.7 @@ -0,0 +1,287 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "PROPERTY 7ossl" +.TH PROPERTY 7ossl "2023-09-19" "3.0.11" "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" +property \- Properties, a selection mechanism for algorithm implementations +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +As of OpenSSL 3.0, a new method has been introduced to decide which of +multiple implementations of an algorithm will be used. +The method is centered around the concept of properties. +Each implementation defines a number of properties and when an algorithm +is being selected, filters based on these properties can be used to +choose the most appropriate implementation of the algorithm. +.PP +Properties are like variables, they are referenced by name and have a value +assigned. +.SS "Property Names" +.IX Subsection "Property Names" +Property names fall into two categories: those reserved by the OpenSSL +project and user defined names. +A \fIreserved\fR property name consists of a single C\-style identifier +(except for leading underscores not being permitted), which begins +with a letter and can be followed by any number of letters, numbers +and underscores. +Property names are case-insensitive, but OpenSSL will only use lowercase +letters. +.PP +A \fIuser defined\fR property name is similar, but it \fBmust\fR consist of +two or more C\-style identifiers, separated by periods. +The last identifier in the name can be considered the 'true' property +name, which is prefixed by some sort of 'namespace'. +Providers for example could include their name in the prefix and use +property names like +.PP +.Vb 2 +\& <provider_name>.<property_name> +\& <provider_name>.<algorithm_name>.<property_name> +.Ve +.SS "Properties" +.IX Subsection "Properties" +A \fIproperty\fR is a \fIname=value\fR pair. +A \fIproperty definition\fR is a sequence of comma separated properties. +There can be any number of properties in a definition, however each name must +be unique. +For example: "\*(L" defines an empty property definition (i.e., no restriction); +\&\*(R"my.foo=bar" defines a property named \fImy.foo\fR which has a string value \fIbar\fR +and \*(L"iteration.count=3\*(R" defines a property named \fIiteration.count\fR which +has a numeric value of \fI3\fR. +The full syntax for property definitions appears below. +.SS "Implementations" +.IX Subsection "Implementations" +Each implementation of an algorithm can define any number of +properties. +For example, the default provider defines the property \fIprovider=default\fR +for all of its algorithms. +Likewise, OpenSSL's \s-1FIPS\s0 provider defines \fIprovider=fips\fR and the legacy +provider defines \fIprovider=legacy\fR for all of their algorithms. +.SS "Queries" +.IX Subsection "Queries" +A \fIproperty query clause\fR is a single conditional test. +For example, \*(L"fips=yes\*(R", \*(L"provider!=default\*(R" or \*(L"?iteration.count=3\*(R". +The first two represent mandatory clauses, such clauses \fBmust\fR match +for any algorithm to even be under consideration. +The third clause represents an optional clause. +Matching such clauses is not a requirement, but any additional optional +match counts in favor of the algorithm. +More details about that in the \fBLookups\fR section. +A \fIproperty query\fR is a sequence of comma separated property query clauses. +It is an error if a property name appears in more than one query clause. +The full syntax for property queries appears below, but the available syntactic +features are: +.IP "\(bu" 4 +\&\fB=\fR is an infix operator providing an equality test. +.IP "\(bu" 4 +\&\fB!=\fR is an infix operator providing an inequality test. +.IP "\(bu" 4 +\&\fB?\fR is a prefix operator that means that the following clause is optional +but preferred. +.IP "\(bu" 4 +\&\fB\-\fR is a prefix operator that means any global query clause involving the +following property name should be ignored. +.IP "\(bu" 4 +\&\fB\*(L"...\*(R"\fR is a quoted string. +The quotes are not included in the body of the string. +.IP "\(bu" 4 +\&\fB'...'\fR is a quoted string. +The quotes are not included in the body of the string. +.SS "Lookups" +.IX Subsection "Lookups" +When an algorithm is looked up, a property query is used to determine +the best matching algorithm. +All mandatory query clauses \fBmust\fR be present and the implementation +that additionally has the largest number of matching optional query +clauses will be used. +If there is more than one such optimal candidate, the result will be +chosen from amongst those in an indeterminate way. +Ordering of optional clauses is not significant. +.SS "Shortcut" +.IX Subsection "Shortcut" +In order to permit a more concise expression of boolean properties, there +is one short cut: a property name alone (e.g. \*(L"my.property\*(R") is +exactly equivalent to \*(L"my.property=yes\*(R" in both definitions and queries. +.SS "Global and Local" +.IX Subsection "Global and Local" +Two levels of property query are supported. +A context based property query that applies to all fetch operations and a local +property query. +Where both the context and local queries include a clause with the same name, +the local clause overrides the context clause. +.PP +It is possible for a local property query to remove a clause in the context +property query by preceding the property name with a '\-'. +For example, a context property query that contains \*(L"fips=yes\*(R" would normally +result in implementations that have \*(L"fips=yes\*(R". +.PP +However, if the setting of the \*(L"fips\*(R" property is irrelevant to the +operations being performed, the local property query can include the +clause \*(L"\-fips\*(R". +Note that the local property query could not use \*(L"fips=no\*(R" because that would +disallow any implementations with \*(L"fips=yes\*(R" rather than not caring about the +setting. +.SH "SYNTAX" +.IX Header "SYNTAX" +The lexical syntax in \s-1EBNF\s0 is given by: +.PP +.Vb 11 +\& Definition ::= PropertyName ( \*(Aq=\*(Aq Value )? +\& ( \*(Aq,\*(Aq PropertyName ( \*(Aq=\*(Aq Value )? )* +\& Query ::= PropertyQuery ( \*(Aq,\*(Aq PropertyQuery )* +\& PropertyQuery ::= \*(Aq\-\*(Aq PropertyName +\& | \*(Aq?\*(Aq? ( PropertyName (( \*(Aq=\*(Aq | \*(Aq!=\*(Aq ) Value)?) +\& Value ::= NumberLiteral | StringLiteral +\& StringLiteral ::= QuotedString | UnquotedString +\& QuotedString ::= \*(Aq"\*(Aq [^"]* \*(Aq"\*(Aq | "\*(Aq" [^\*(Aq]* "\*(Aq" +\& UnquotedString ::= [A\-Za\-z] [^{space},]+ +\& NumberLiteral ::= \*(Aq0\*(Aq ( [0\-7]* | \*(Aqx\*(Aq [0\-9A\-Fa\-f]+ ) | \*(Aq\-\*(Aq? [1\-9] [0\-9]+ +\& PropertyName ::= [A\-Za\-z] [A\-Za\-z0\-9_]* ( \*(Aq.\*(Aq [A\-Za\-z] [A\-Za\-z0\-9_]* )* +.Ve +.PP +The flavour of \s-1EBNF\s0 being used is defined by: +<https://www.w3.org/TR/2010/REC\-xquery\-20101214/#EBNFNotation>. +.SH "HISTORY" +.IX Header "HISTORY" +Properties were added in OpenSSL 3.0 +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2019\-2023 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>. diff --git a/secure/lib/libcrypto/man/man7/provider-asym_cipher.7 b/secure/lib/libcrypto/man/man7/provider-asym_cipher.7 new file mode 100644 index 000000000000..1c647936d89b --- /dev/null +++ b/secure/lib/libcrypto/man/man7/provider-asym_cipher.7 @@ -0,0 +1,391 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "PROVIDER-ASYM_CIPHER 7ossl" +.TH PROVIDER-ASYM_CIPHER 7ossl "2023-09-19" "3.0.11" "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" +provider\-asym_cipher \- The asym_cipher library <\-> provider functions +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 2 +\& #include <openssl/core_dispatch.h> +\& #include <openssl/core_names.h> +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Context management */ +\& void *OSSL_FUNC_asym_cipher_newctx(void *provctx); +\& void OSSL_FUNC_asym_cipher_freectx(void *ctx); +\& void *OSSL_FUNC_asym_cipher_dupctx(void *ctx); +\& +\& /* Encryption */ +\& int OSSL_FUNC_asym_cipher_encrypt_init(void *ctx, void *provkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_asym_cipher_encrypt(void *ctx, unsigned char *out, size_t *outlen, +\& size_t outsize, const unsigned char *in, +\& size_t inlen); +\& +\& /* Decryption */ +\& int OSSL_FUNC_asym_cipher_decrypt_init(void *ctx, void *provkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_asym_cipher_decrypt(void *ctx, unsigned char *out, size_t *outlen, +\& size_t outsize, const unsigned char *in, +\& size_t inlen); +\& +\& /* Asymmetric Cipher parameters */ +\& int OSSL_FUNC_asym_cipher_get_ctx_params(void *ctx, OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_asym_cipher_gettable_ctx_params(void *provctx); +\& int OSSL_FUNC_asym_cipher_set_ctx_params(void *ctx, const OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_asym_cipher_settable_ctx_params(void *provctx); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7) +for further information. +.PP +The asymmetric cipher (\s-1OSSL_OP_ASYM_CIPHER\s0) operation enables providers to +implement asymmetric cipher algorithms and make them available to applications +via the \s-1API\s0 functions \fBEVP_PKEY_encrypt\fR\|(3), +\&\fBEVP_PKEY_decrypt\fR\|(3) and +other related functions). +.PP +All \*(L"functions\*(R" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays via +\&\s-1\fBOSSL_ALGORITHM\s0\fR\|(3) arrays that are returned by the provider's +\&\fBprovider_query_operation()\fR function +(see \*(L"Provider Functions\*(R" in \fBprovider\-base\fR\|(7)). +.PP +All these \*(L"functions\*(R" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from an \s-1\fBOSSL_DISPATCH\s0\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the \*(L"function\*(R" \fBOSSL_FUNC_asym_cipher_newctx()\fR has these: +.PP +.Vb 3 +\& typedef void *(OSSL_FUNC_asym_cipher_newctx_fn)(void *provctx); +\& static ossl_inline OSSL_FUNC_asym_cipher_newctx_fn +\& OSSL_FUNC_asym_cipher_newctx(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 3 +\& OSSL_FUNC_asym_cipher_newctx OSSL_FUNC_ASYM_CIPHER_NEWCTX +\& OSSL_FUNC_asym_cipher_freectx OSSL_FUNC_ASYM_CIPHER_FREECTX +\& OSSL_FUNC_asym_cipher_dupctx OSSL_FUNC_ASYM_CIPHER_DUPCTX +\& +\& OSSL_FUNC_asym_cipher_encrypt_init OSSL_FUNC_ASYM_CIPHER_ENCRYPT_INIT +\& OSSL_FUNC_asym_cipher_encrypt OSSL_FUNC_ASYM_CIPHER_ENCRYPT +\& +\& OSSL_FUNC_asym_cipher_decrypt_init OSSL_FUNC_ASYM_CIPHER_DECRYPT_INIT +\& OSSL_FUNC_asym_cipher_decrypt OSSL_FUNC_ASYM_CIPHER_DECRYPT +\& +\& OSSL_FUNC_asym_cipher_get_ctx_params OSSL_FUNC_ASYM_CIPHER_GET_CTX_PARAMS +\& OSSL_FUNC_asym_cipher_gettable_ctx_params OSSL_FUNC_ASYM_CIPHER_GETTABLE_CTX_PARAMS +\& OSSL_FUNC_asym_cipher_set_ctx_params OSSL_FUNC_ASYM_CIPHER_SET_CTX_PARAMS +\& OSSL_FUNC_asym_cipher_settable_ctx_params OSSL_FUNC_ASYM_CIPHER_SETTABLE_CTX_PARAMS +.Ve +.PP +An asymmetric cipher algorithm implementation may not implement all of these +functions. +In order to be a consistent set of functions a provider must implement +OSSL_FUNC_asym_cipher_newctx and OSSL_FUNC_asym_cipher_freectx. +It must also implement both of OSSL_FUNC_asym_cipher_encrypt_init and +OSSL_FUNC_asym_cipher_encrypt, or both of OSSL_FUNC_asym_cipher_decrypt_init and +OSSL_FUNC_asym_cipher_decrypt. +OSSL_FUNC_asym_cipher_get_ctx_params is optional but if it is present then so must +OSSL_FUNC_asym_cipher_gettable_ctx_params. +Similarly, OSSL_FUNC_asym_cipher_set_ctx_params is optional but if it is present then +so must OSSL_FUNC_asym_cipher_settable_ctx_params. +.PP +An asymmetric cipher algorithm must also implement some mechanism for generating, +loading or importing keys via the key management (\s-1OSSL_OP_KEYMGMT\s0) operation. +See \fBprovider\-keymgmt\fR\|(7) for further details. +.SS "Context Management Functions" +.IX Subsection "Context Management Functions" +\&\fBOSSL_FUNC_asym_cipher_newctx()\fR should create and return a pointer to a provider side +structure for holding context information during an asymmetric cipher operation. +A pointer to this context will be passed back in a number of the other +asymmetric cipher operation function calls. +The parameter \fIprovctx\fR is the provider context generated during provider +initialisation (see \fBprovider\fR\|(7)). +.PP +\&\fBOSSL_FUNC_asym_cipher_freectx()\fR is passed a pointer to the provider side asymmetric +cipher context in the \fIctx\fR parameter. +This function should free any resources associated with that context. +.PP +\&\fBOSSL_FUNC_asym_cipher_dupctx()\fR should duplicate the provider side asymmetric cipher +context in the \fIctx\fR parameter and return the duplicate copy. +.SS "Encryption Functions" +.IX Subsection "Encryption Functions" +\&\fBOSSL_FUNC_asym_cipher_encrypt_init()\fR initialises a context for an asymmetric encryption +given a provider side asymmetric cipher context in the \fIctx\fR parameter, and a +pointer to a provider key object in the \fIprovkey\fR parameter. +The \fIparams\fR, if not \s-1NULL,\s0 should be set on the context in a manner similar to +using \fBOSSL_FUNC_asym_cipher_set_ctx_params()\fR. +The key object should have been previously generated, loaded or imported into +the provider using the key management (\s-1OSSL_OP_KEYMGMT\s0) operation (see \fBprovider\-keymgmt\fR\|(7)). +\&\fBOSSL_FUNC_asym_cipher_encrypt()\fR performs the actual encryption itself. +A previously initialised asymmetric cipher context is passed in the \fIctx\fR +parameter. +The data to be encrypted is pointed to by the \fIin\fR parameter which is \fIinlen\fR +bytes long. +Unless \fIout\fR is \s-1NULL,\s0 the encrypted data should be written to the location +pointed to by the \fIout\fR parameter and it should not exceed \fIoutsize\fR bytes in +length. +The length of the encrypted data should be written to \fI*outlen\fR. +If \fIout\fR is \s-1NULL\s0 then the maximum length of the encrypted data should be +written to \fI*outlen\fR. +.SS "Decryption Functions" +.IX Subsection "Decryption Functions" +\&\fBOSSL_FUNC_asym_cipher_decrypt_init()\fR initialises a context for an asymmetric decryption +given a provider side asymmetric cipher context in the \fIctx\fR parameter, and a +pointer to a provider key object in the \fIprovkey\fR parameter. +The \fIparams\fR, if not \s-1NULL,\s0 should be set on the context in a manner similar to +using \fBOSSL_FUNC_asym_cipher_set_ctx_params()\fR. +The key object should have been previously generated, loaded or imported into +the provider using the key management (\s-1OSSL_OP_KEYMGMT\s0) operation (see +\&\fBprovider\-keymgmt\fR\|(7)). +.PP +\&\fBOSSL_FUNC_asym_cipher_decrypt()\fR performs the actual decryption itself. +A previously initialised asymmetric cipher context is passed in the \fIctx\fR +parameter. +The data to be decrypted is pointed to by the \fIin\fR parameter which is \fIinlen\fR +bytes long. +Unless \fIout\fR is \s-1NULL,\s0 the decrypted data should be written to the location +pointed to by the \fIout\fR parameter and it should not exceed \fIoutsize\fR bytes in +length. +The length of the decrypted data should be written to \fI*outlen\fR. +If \fIout\fR is \s-1NULL\s0 then the maximum length of the decrypted data should be +written to \fI*outlen\fR. +.SS "Asymmetric Cipher Parameters" +.IX Subsection "Asymmetric Cipher Parameters" +See \s-1\fBOSSL_PARAM\s0\fR\|(3) for further details on the parameters structure used by +the \fBOSSL_FUNC_asym_cipher_get_ctx_params()\fR and \fBOSSL_FUNC_asym_cipher_set_ctx_params()\fR +functions. +.PP +\&\fBOSSL_FUNC_asym_cipher_get_ctx_params()\fR gets asymmetric cipher parameters associated +with the given provider side asymmetric cipher context \fIctx\fR and stores them in +\&\fIparams\fR. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_asym_cipher_set_ctx_params()\fR sets the asymmetric cipher parameters associated +with the given provider side asymmetric cipher context \fIctx\fR to \fIparams\fR. +Any parameter settings are additional to any that were previously set. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +Parameters currently recognised by built-in asymmetric cipher algorithms are as +follows. +Not all parameters are relevant to, or are understood by all asymmetric cipher +algorithms: +.ie n .IP """pad-mode"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_PAD_MODE\s0\fR) <\s-1UTF8\s0 string> \s-1OR\s0 <integer>" 4 +.el .IP "``pad-mode'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_PAD_MODE\s0\fR) <\s-1UTF8\s0 string> \s-1OR\s0 <integer>" 4 +.IX Item "pad-mode (OSSL_ASYM_CIPHER_PARAM_PAD_MODE) <UTF8 string> OR <integer>" +The type of padding to be used. The interpretation of this value will depend +on the algorithm in use. +.ie n .IP """digest"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST) <UTF8 string>" +Gets or sets the name of the \s-1OAEP\s0 digest algorithm used when \s-1OAEP\s0 padding is in +use. +.ie n .IP """digest"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_ASYM_CIPHER_PARAM_DIGEST) <UTF8 string>" +Gets or sets the name of the digest algorithm used by the algorithm (where +applicable). +.ie n .IP """digest-props"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest-props'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest-props (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS) <UTF8 string>" +Gets or sets the properties to use when fetching the \s-1OAEP\s0 digest algorithm. +.ie n .IP """digest-props"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_DIGEST_PROPS\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest-props'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_DIGEST_PROPS\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest-props (OSSL_ASYM_CIPHER_PARAM_DIGEST_PROPS) <UTF8 string>" +Gets or sets the properties to use when fetching the cipher digest algorithm. +.ie n .IP """mgf1\-digest"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``mgf1\-digest'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "mgf1-digest (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST) <UTF8 string>" +Gets or sets the name of the \s-1MGF1\s0 digest algorithm used when \s-1OAEP\s0 or \s-1PSS\s0 padding +is in use. +.ie n .IP """mgf1\-digest\-props"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST_PROPS\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``mgf1\-digest\-props'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST_PROPS\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "mgf1-digest-props (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST_PROPS) <UTF8 string>" +Gets or sets the properties to use when fetching the \s-1MGF1\s0 digest algorithm. +.ie n .IP """oaep-label"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL\s0\fR) <octet string ptr>" 4 +.el .IP "``oaep-label'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL\s0\fR) <octet string ptr>" 4 +.IX Item "oaep-label (OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL) <octet string ptr>" +Gets the \s-1OAEP\s0 label used when \s-1OAEP\s0 padding is in use. +.ie n .IP """oaep-label"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL\s0\fR) <octet string>" 4 +.el .IP "``oaep-label'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL\s0\fR) <octet string>" 4 +.IX Item "oaep-label (OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL) <octet string>" +Sets the \s-1OAEP\s0 label used when \s-1OAEP\s0 padding is in use. +.ie n .IP """tls-client-version"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION\s0\fR) <unsigned integer>" 4 +.el .IP "``tls-client-version'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION\s0\fR) <unsigned integer>" 4 +.IX Item "tls-client-version (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION) <unsigned integer>" +The \s-1TLS\s0 protocol version first requested by the client. +.ie n .IP """tls-negotiated-version"" (\fB\s-1OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION\s0\fR) <unsigned integer>" 4 +.el .IP "``tls-negotiated-version'' (\fB\s-1OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION\s0\fR) <unsigned integer>" 4 +.IX Item "tls-negotiated-version (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION) <unsigned integer>" +The negotiated \s-1TLS\s0 protocol version. +.PP +\&\fBOSSL_FUNC_asym_cipher_gettable_ctx_params()\fR and \fBOSSL_FUNC_asym_cipher_settable_ctx_params()\fR +get a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) array that describes the gettable and settable +parameters, i.e. parameters that can be used with \fBOSSL_FUNC_asym_cipherget_ctx_params()\fR +and \fBOSSL_FUNC_asym_cipher_set_ctx_params()\fR respectively. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_asym_cipher_newctx()\fR and \fBOSSL_FUNC_asym_cipher_dupctx()\fR should return the newly +created provider side asymmetric cipher context, or \s-1NULL\s0 on failure. +.PP +All other functions should return 1 for success or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The provider \s-1ASYM_CIPHER\s0 interface was introduced in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2019\-2023 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>. diff --git a/secure/lib/libcrypto/man/man7/provider-base.7 b/secure/lib/libcrypto/man/man7/provider-base.7 new file mode 100644 index 000000000000..89a9c99b6d9b --- /dev/null +++ b/secure/lib/libcrypto/man/man7/provider-base.7 @@ -0,0 +1,937 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "PROVIDER-BASE 7ossl" +.TH PROVIDER-BASE 7ossl "2023-09-19" "3.0.11" "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" +provider\-base +\&\- The basic OpenSSL library <\-> provider functions +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/core_dispatch.h> +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Functions offered by libcrypto to the providers */ +\& const OSSL_ITEM *core_gettable_params(const OSSL_CORE_HANDLE *handle); +\& int core_get_params(const OSSL_CORE_HANDLE *handle, OSSL_PARAM params[]); +\& +\& typedef void (*OSSL_thread_stop_handler_fn)(void *arg); +\& int core_thread_start(const OSSL_CORE_HANDLE *handle, +\& OSSL_thread_stop_handler_fn handfn, +\& void *arg); +\& +\& OPENSSL_CORE_CTX *core_get_libctx(const OSSL_CORE_HANDLE *handle); +\& void core_new_error(const OSSL_CORE_HANDLE *handle); +\& void core_set_error_debug(const OSSL_CORE_HANDLE *handle, +\& const char *file, int line, const char *func); +\& void core_vset_error(const OSSL_CORE_HANDLE *handle, +\& uint32_t reason, const char *fmt, va_list args); +\& +\& int core_obj_add_sigid(const OSSL_CORE_HANDLE *prov, const char *sign_name, +\& const char *digest_name, const char *pkey_name); +\& int core_obj_create(const OSSL_CORE_HANDLE *handle, const char *oid, +\& const char *sn, const char *ln); +\& +\& /* +\& * Some OpenSSL functionality is directly offered to providers via +\& * dispatch +\& */ +\& void *CRYPTO_malloc(size_t num, const char *file, int line); +\& void *CRYPTO_zalloc(size_t num, const char *file, int line); +\& void CRYPTO_free(void *ptr, const char *file, int line); +\& void CRYPTO_clear_free(void *ptr, size_t num, +\& const char *file, int line); +\& void *CRYPTO_realloc(void *addr, size_t num, +\& const char *file, int line); +\& void *CRYPTO_clear_realloc(void *addr, size_t old_num, size_t num, +\& const char *file, int line); +\& void *CRYPTO_secure_malloc(size_t num, const char *file, int line); +\& void *CRYPTO_secure_zalloc(size_t num, const char *file, int line); +\& void CRYPTO_secure_free(void *ptr, const char *file, int line); +\& void CRYPTO_secure_clear_free(void *ptr, size_t num, +\& const char *file, int line); +\& int CRYPTO_secure_allocated(const void *ptr); +\& void OPENSSL_cleanse(void *ptr, size_t len); +\& +\& unsigned char *OPENSSL_hexstr2buf(const char *str, long *buflen); +\& +\& OSSL_CORE_BIO *BIO_new_file(const char *filename, const char *mode); +\& OSSL_CORE_BIO *BIO_new_membuf(const void *buf, int len); +\& int BIO_read_ex(OSSL_CORE_BIO *bio, void *data, size_t data_len, +\& size_t *bytes_read); +\& int BIO_write_ex(OSSL_CORE_BIO *bio, const void *data, size_t data_len, +\& size_t *written); +\& int BIO_up_ref(OSSL_CORE_BIO *bio); +\& int BIO_free(OSSL_CORE_BIO *bio); +\& int BIO_vprintf(OSSL_CORE_BIO *bio, const char *format, va_list args); +\& int BIO_vsnprintf(char *buf, size_t n, const char *fmt, va_list args); +\& +\& void OSSL_SELF_TEST_set_callback(OSSL_LIB_CTX *libctx, OSSL_CALLBACK *cb, +\& void *cbarg); +\& +\& size_t get_entropy(const OSSL_CORE_HANDLE *handle, +\& unsigned char **pout, int entropy, +\& size_t min_len, size_t max_len); +\& void cleanup_entropy(const OSSL_CORE_HANDLE *handle, +\& unsigned char *buf, size_t len); +\& size_t get_nonce(const OSSL_CORE_HANDLE *handle, +\& unsigned char **pout, size_t min_len, size_t max_len, +\& const void *salt, size_t salt_len); +\& void cleanup_nonce(const OSSL_CORE_HANDLE *handle, +\& unsigned char *buf, size_t len); +\& +\& /* Functions for querying the providers in the application library context */ +\& int provider_register_child_cb(const OSSL_CORE_HANDLE *handle, +\& int (*create_cb)(const OSSL_CORE_HANDLE *provider, +\& void *cbdata), +\& int (*remove_cb)(const OSSL_CORE_HANDLE *provider, +\& void *cbdata), +\& int (*global_props_cb)(const char *props, void *cbdata), +\& void *cbdata); +\& void provider_deregister_child_cb(const OSSL_CORE_HANDLE *handle); +\& const char *provider_name(const OSSL_CORE_HANDLE *prov); +\& void *provider_get0_provider_ctx(const OSSL_CORE_HANDLE *prov); +\& const OSSL_DISPATCH *provider_get0_dispatch(const OSSL_CORE_HANDLE *prov); +\& int provider_up_ref(const OSSL_CORE_HANDLE *prov, int activate); +\& int provider_free(const OSSL_CORE_HANDLE *prov, int deactivate); +\& +\& /* Functions offered by the provider to libcrypto */ +\& void provider_teardown(void *provctx); +\& const OSSL_ITEM *provider_gettable_params(void *provctx); +\& int provider_get_params(void *provctx, OSSL_PARAM params[]); +\& const OSSL_ALGORITHM *provider_query_operation(void *provctx, +\& int operation_id, +\& const int *no_store); +\& void provider_unquery_operation(void *provctx, int operation_id, +\& const OSSL_ALGORITHM *algs); +\& const OSSL_ITEM *provider_get_reason_strings(void *provctx); +\& int provider_get_capabilities(void *provctx, const char *capability, +\& OSSL_CALLBACK *cb, void *arg); +\& int provider_self_test(void *provctx); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +All \*(L"functions\*(R" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays, in the call +of the provider initialization function. See \*(L"Provider\*(R" in \fBprovider\fR\|(7) +for a description of the initialization function. They are known as \*(L"upcalls\*(R". +.PP +All these \*(L"functions\*(R" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from a \s-1\fBOSSL_DISPATCH\s0\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the \*(L"function\*(R" \fBcore_gettable_params()\fR has these: +.PP +.Vb 4 +\& typedef OSSL_PARAM * +\& (OSSL_FUNC_core_gettable_params_fn)(const OSSL_CORE_HANDLE *handle); +\& static ossl_inline OSSL_NAME_core_gettable_params_fn +\& OSSL_FUNC_core_gettable_params(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +For \fIin\fR (the \s-1\fBOSSL_DISPATCH\s0\fR\|(3) array passed from \fIlibcrypto\fR to the +provider): +.PP +.Vb 10 +\& core_gettable_params OSSL_FUNC_CORE_GETTABLE_PARAMS +\& core_get_params OSSL_FUNC_CORE_GET_PARAMS +\& core_thread_start OSSL_FUNC_CORE_THREAD_START +\& core_get_libctx OSSL_FUNC_CORE_GET_LIBCTX +\& core_new_error OSSL_FUNC_CORE_NEW_ERROR +\& core_set_error_debug OSSL_FUNC_CORE_SET_ERROR_DEBUG +\& core_vset_error OSSL_FUNC_CORE_VSET_ERROR +\& core_obj_add_sigid OSSL_FUNC_CORE_OBJ_ADD_SIGID +\& core_obj_create OSSL_FUNC_CORE_OBJ_CREATE +\& CRYPTO_malloc OSSL_FUNC_CRYPTO_MALLOC +\& CRYPTO_zalloc OSSL_FUNC_CRYPTO_ZALLOC +\& CRYPTO_free OSSL_FUNC_CRYPTO_FREE +\& CRYPTO_clear_free OSSL_FUNC_CRYPTO_CLEAR_FREE +\& CRYPTO_realloc OSSL_FUNC_CRYPTO_REALLOC +\& CRYPTO_clear_realloc OSSL_FUNC_CRYPTO_CLEAR_REALLOC +\& CRYPTO_secure_malloc OSSL_FUNC_CRYPTO_SECURE_MALLOC +\& CRYPTO_secure_zalloc OSSL_FUNC_CRYPTO_SECURE_ZALLOC +\& CRYPTO_secure_free OSSL_FUNC_CRYPTO_SECURE_FREE +\& CRYPTO_secure_clear_free OSSL_FUNC_CRYPTO_SECURE_CLEAR_FREE +\& CRYPTO_secure_allocated OSSL_FUNC_CRYPTO_SECURE_ALLOCATED +\& BIO_new_file OSSL_FUNC_BIO_NEW_FILE +\& BIO_new_mem_buf OSSL_FUNC_BIO_NEW_MEMBUF +\& BIO_read_ex OSSL_FUNC_BIO_READ_EX +\& BIO_write_ex OSSL_FUNC_BIO_WRITE_EX +\& BIO_up_ref OSSL_FUNC_BIO_UP_REF +\& BIO_free OSSL_FUNC_BIO_FREE +\& BIO_vprintf OSSL_FUNC_BIO_VPRINTF +\& BIO_vsnprintf OSSL_FUNC_BIO_VSNPRINTF +\& BIO_puts OSSL_FUNC_BIO_PUTS +\& BIO_gets OSSL_FUNC_BIO_GETS +\& BIO_ctrl OSSL_FUNC_BIO_CTRL +\& OPENSSL_cleanse OSSL_FUNC_OPENSSL_CLEANSE +\& OSSL_SELF_TEST_set_callback OSSL_FUNC_SELF_TEST_CB +\& ossl_rand_get_entropy OSSL_FUNC_GET_ENTROPY +\& ossl_rand_cleanup_entropy OSSL_FUNC_CLEANUP_ENTROPY +\& ossl_rand_get_nonce OSSL_FUNC_GET_NONCE +\& ossl_rand_cleanup_nonce OSSL_FUNC_CLEANUP_NONCE +\& provider_register_child_cb OSSL_FUNC_PROVIDER_REGISTER_CHILD_CB +\& provider_deregister_child_cb OSSL_FUNC_PROVIDER_DEREGISTER_CHILD_CB +\& provider_name OSSL_FUNC_PROVIDER_NAME +\& provider_get0_provider_ctx OSSL_FUNC_PROVIDER_GET0_PROVIDER_CTX +\& provider_get0_dispatch OSSL_FUNC_PROVIDER_GET0_DISPATCH +\& provider_up_ref OSSL_FUNC_PROVIDER_UP_REF +\& provider_free OSSL_FUNC_PROVIDER_FREE +.Ve +.PP +For \fI*out\fR (the \s-1\fBOSSL_DISPATCH\s0\fR\|(3) array passed from the provider to +\&\fIlibcrypto\fR): +.PP +.Vb 8 +\& provider_teardown OSSL_FUNC_PROVIDER_TEARDOWN +\& provider_gettable_params OSSL_FUNC_PROVIDER_GETTABLE_PARAMS +\& provider_get_params OSSL_FUNC_PROVIDER_GET_PARAMS +\& provider_query_operation OSSL_FUNC_PROVIDER_QUERY_OPERATION +\& provider_unquery_operation OSSL_FUNC_PROVIDER_UNQUERY_OPERATION +\& provider_get_reason_strings OSSL_FUNC_PROVIDER_GET_REASON_STRINGS +\& provider_get_capabilities OSSL_FUNC_PROVIDER_GET_CAPABILITIES +\& provider_self_test OSSL_FUNC_PROVIDER_SELF_TEST +.Ve +.SS "Core functions" +.IX Subsection "Core functions" +\&\fBcore_gettable_params()\fR returns a constant array of descriptor +\&\s-1\fBOSSL_PARAM\s0\fR\|(3), for parameters that \fBcore_get_params()\fR can handle. +.PP +\&\fBcore_get_params()\fR retrieves parameters from the core for the given \fIhandle\fR. +See \*(L"Core parameters\*(R" below for a description of currently known +parameters. +.PP +The \fBcore_thread_start()\fR function informs the core that the provider has stated +an interest in the current thread. The core will inform the provider when the +thread eventually stops. It must be passed the \fIhandle\fR for this provider, as +well as a callback \fIhandfn\fR which will be called when the thread stops. The +callback will subsequently be called, with the supplied argument \fIarg\fR, from +the thread that is stopping and gets passed the provider context as an +argument. This may be useful to perform thread specific clean up such as +freeing thread local variables. +.PP +\&\fBcore_get_libctx()\fR retrieves the core context in which the library +object for the current provider is stored, accessible through the \fIhandle\fR. +This function is useful only for built-in providers such as the default +provider. Never cast this to \s-1OSSL_LIB_CTX\s0 in a provider that is not +built-in as the \s-1OSSL_LIB_CTX\s0 of the library loading the provider might be +a completely different structure than the \s-1OSSL_LIB_CTX\s0 of the library the +provider is linked to. Use \fBOSSL_LIB_CTX_new_child\fR\|(3) instead to obtain +a proper library context that is linked to the application library context. +.PP +\&\fBcore_new_error()\fR, \fBcore_set_error_debug()\fR and \fBcore_vset_error()\fR are +building blocks for reporting an error back to the core, with +reference to the \fIhandle\fR. +.IP "\fBcore_new_error()\fR" 4 +.IX Item "core_new_error()" +allocates a new thread specific error record. +.Sp +This corresponds to the OpenSSL function \fBERR_new\fR\|(3). +.IP "\fBcore_set_error_debug()\fR" 4 +.IX Item "core_set_error_debug()" +sets debugging information in the current thread specific error +record. +The debugging information includes the name of the file \fIfile\fR, the +line \fIline\fR and the function name \fIfunc\fR where the error occurred. +.Sp +This corresponds to the OpenSSL function \fBERR_set_debug\fR\|(3). +.IP "\fBcore_vset_error()\fR" 4 +.IX Item "core_vset_error()" +sets the \fIreason\fR for the error, along with any addition data. +The \fIreason\fR is a number defined by the provider and used to index +the reason strings table that's returned by +\&\fBprovider_get_reason_strings()\fR. +The additional data is given as a format string \fIfmt\fR and a set of +arguments \fIargs\fR, which are treated in the same manner as with +\&\fBBIO_vsnprintf()\fR. +\&\fIfile\fR and \fIline\fR may also be passed to indicate exactly where the +error occurred or was reported. +.Sp +This corresponds to the OpenSSL function \fBERR_vset_error\fR\|(3). +.PP +The \fBcore_obj_create()\fR function registers a new \s-1OID\s0 and associated short name +\&\fIsn\fR and long name \fIln\fR for the given \fIhandle\fR. It is similar to the OpenSSL +function \fBOBJ_create\fR\|(3) except that it returns 1 on success or 0 on failure. +It will treat as success the case where the \s-1OID\s0 already exists (even if the +short name \fIsn\fR or long name \fIln\fR provided as arguments differ from those +associated with the existing \s-1OID,\s0 in which case the new names are not +associated). +This function is not thread safe. +.PP +The \fBcore_obj_add_sigid()\fR function registers a new composite signature algorithm +(\fIsign_name\fR) consisting of an underlying signature algorithm (\fIpkey_name\fR) +and digest algorithm (\fIdigest_name\fR) for the given \fIhandle\fR. It assumes that +the OIDs for the composite signature algorithm as well as for the underlying +signature and digest algorithms are either already known to OpenSSL or have been +registered via a call to \fBcore_obj_create()\fR. It corresponds to the OpenSSL +function \fBOBJ_add_sigid\fR\|(3), except that the objects are identified by name +rather than a numeric \s-1NID.\s0 Any name (\s-1OID,\s0 short name or long name) can be used +to identify the object. It will treat as success the case where the composite +signature algorithm already exists (even if registered against a different +underlying signature or digest algorithm). For \fIdigest_name\fR, \s-1NULL\s0 or an +empty string is permissible for signature algorithms that do not need a digest +to operate correctly. The function returns 1 on success or 0 on failure. +This function is not thread safe. +.PP +\&\fBCRYPTO_malloc()\fR, \fBCRYPTO_zalloc()\fR, \fBCRYPTO_free()\fR, \fBCRYPTO_clear_free()\fR, +\&\fBCRYPTO_realloc()\fR, \fBCRYPTO_clear_realloc()\fR, \fBCRYPTO_secure_malloc()\fR, +\&\fBCRYPTO_secure_zalloc()\fR, \fBCRYPTO_secure_free()\fR, +\&\fBCRYPTO_secure_clear_free()\fR, \fBCRYPTO_secure_allocated()\fR, +\&\fBBIO_new_file()\fR, \fBBIO_new_mem_buf()\fR, \fBBIO_read_ex()\fR, \fBBIO_write_ex()\fR, \fBBIO_up_ref()\fR, +\&\fBBIO_free()\fR, \fBBIO_vprintf()\fR, \fBBIO_vsnprintf()\fR, \fBBIO_gets()\fR, \fBBIO_puts()\fR, +\&\fBBIO_ctrl()\fR, \fBOPENSSL_cleanse()\fR and +\&\fBOPENSSL_hexstr2buf()\fR correspond exactly to the public functions with +the same name. As a matter of fact, the pointers in the \s-1\fBOSSL_DISPATCH\s0\fR\|(3) +array are typically direct pointers to those public functions. Note that the \s-1BIO\s0 +functions take an \fB\s-1OSSL_CORE_BIO\s0\fR type rather than the standard \fB\s-1BIO\s0\fR +type. This is to ensure that a provider does not mix BIOs from the core +with BIOs used on the provider side (the two are not compatible). +\&\fBOSSL_SELF_TEST_set_callback()\fR is used to set an optional callback that can be +passed into a provider. This may be ignored by a provider. +.PP +\&\fBget_entropy()\fR retrieves seeding material from the operating system. +The seeding material will have at least \fIentropy\fR bytes of randomness and the +output will have at least \fImin_len\fR and at most \fImax_len\fR bytes. +The buffer address is stored in \fI*pout\fR and the buffer length is +returned to the caller. On error, zero is returned. +.PP +\&\fBcleanup_entropy()\fR is used to clean up and free the buffer returned by +\&\fBget_entropy()\fR. The entropy pointer returned by \fBget_entropy()\fR is passed in +\&\fBbuf\fR and its length in \fBlen\fR. +.PP +\&\fBget_nonce()\fR retrieves a nonce using the passed \fIsalt\fR parameter +of length \fIsalt_len\fR and operating system specific information. +The \fIsalt\fR should contain uniquely identifying information and this is +included, in an unspecified manner, as part of the output. +The output is stored in a buffer which contains at least \fImin_len\fR and at +most \fImax_len\fR bytes. The buffer address is stored in \fI*pout\fR and the +buffer length returned to the caller. On error, zero is returned. +.PP +\&\fBcleanup_nonce()\fR is used to clean up and free the buffer returned by +\&\fBget_nonce()\fR. The nonce pointer returned by \fBget_nonce()\fR is passed in +\&\fBbuf\fR and its length in \fBlen\fR. +.PP +\&\fBprovider_register_child_cb()\fR registers callbacks for being informed about the +loading and unloading of providers in the application's library context. +\&\fIhandle\fR is this provider's handle and \fIcbdata\fR is this provider's data +that will be passed back to the callbacks. It returns 1 on success or 0 +otherwise. These callbacks may be called while holding locks in libcrypto. In +order to avoid deadlocks the callback implementation must not be long running +and must not call other OpenSSL \s-1API\s0 functions or upcalls. +.PP +\&\fIcreate_cb\fR is a callback that will be called when a new provider is loaded +into the application's library context. It is also called for any providers that +are already loaded at the point that this callback is registered. The callback +is passed the handle being used for the new provider being loadded and this +provider's data in \fIcbdata\fR. It should return 1 on success or 0 on failure. +.PP +\&\fIremove_cb\fR is a callback that will be called when a new provider is unloaded +from the application's library context. It is passed the handle being used for +the provider being unloaded and this provider's data in \fIcbdata\fR. It should +return 1 on success or 0 on failure. +.PP +\&\fIglobal_props_cb\fR is a callback that will be called when the global properties +from the parent library context are changed. It should return 1 on success +or 0 on failure. +.PP +\&\fBprovider_deregister_child_cb()\fR unregisters callbacks previously registered via +\&\fBprovider_register_child_cb()\fR. If \fBprovider_register_child_cb()\fR has been called +then \fBprovider_deregister_child_cb()\fR should be called at or before the point that +this provider's teardown function is called. +.PP +\&\fBprovider_name()\fR returns a string giving the name of the provider identified by +\&\fIhandle\fR. +.PP +\&\fBprovider_get0_provider_ctx()\fR returns the provider context that is associated +with the provider identified by \fIprov\fR. +.PP +\&\fBprovider_get0_dispatch()\fR gets the dispatch table registered by the provider +identified by \fIprov\fR when it initialised. +.PP +\&\fBprovider_up_ref()\fR increments the reference count on the provider \fIprov\fR. If +\&\fIactivate\fR is nonzero then the provider is also loaded if it is not already +loaded. It returns 1 on success or 0 on failure. +.PP +\&\fBprovider_free()\fR decrements the reference count on the provider \fIprov\fR. If +\&\fIdeactivate\fR is nonzero then the provider is also unloaded if it is not +already loaded. It returns 1 on success or 0 on failure. +.SS "Provider functions" +.IX Subsection "Provider functions" +\&\fBprovider_teardown()\fR is called when a provider is shut down and removed +from the core's provider store. +It must free the passed \fIprovctx\fR. +.PP +\&\fBprovider_gettable_params()\fR should return a constant array of +descriptor \s-1\fBOSSL_PARAM\s0\fR\|(3), for parameters that \fBprovider_get_params()\fR +can handle. +.PP +\&\fBprovider_get_params()\fR should process the \s-1\fBOSSL_PARAM\s0\fR\|(3) array +\&\fIparams\fR, setting the values of the parameters it understands. +.PP +\&\fBprovider_query_operation()\fR should return a constant \s-1\fBOSSL_ALGORITHM\s0\fR\|(3) +that corresponds to the given \fIoperation_id\fR. +It should indicate if the core may store a reference to this array by +setting \fI*no_store\fR to 0 (core may store a reference) or 1 (core may +not store a reference). +.PP +\&\fBprovider_unquery_operation()\fR informs the provider that the result of a +\&\fBprovider_query_operation()\fR is no longer directly required and that the function +pointers have been copied. The \fIoperation_id\fR should match that passed to +\&\fBprovider_query_operation()\fR and \fIalgs\fR should be its return value. +.PP +\&\fBprovider_get_reason_strings()\fR should return a constant \s-1\fBOSSL_ITEM\s0\fR\|(3) +array that provides reason strings for reason codes the provider may +use when reporting errors using \fBcore_put_error()\fR. +.PP +The \fBprovider_get_capabilities()\fR function should call the callback \fIcb\fR passing +it a set of \s-1\fBOSSL_PARAM\s0\fR\|(3)s and the caller supplied argument \fIarg\fR. The +\&\s-1\fBOSSL_PARAM\s0\fR\|(3)s should provide details about the capability with the name given +in the \fIcapability\fR argument relevant for the provider context \fIprovctx\fR. If a +provider supports multiple capabilities with the given name then it may call the +callback multiple times (one for each capability). Capabilities can be useful for +describing the services that a provider can offer. For further details see the +\&\*(L"\s-1CAPABILITIES\*(R"\s0 section below. It should return 1 on success or 0 on error. +.PP +The \fBprovider_self_test()\fR function should perform known answer tests on a subset +of the algorithms that it uses, and may also verify the integrity of the +provider module. It should return 1 on success or 0 on error. It will return 1 +if this function is not used. +.PP +None of these functions are mandatory, but a provider is fairly +useless without at least \fBprovider_query_operation()\fR, and +\&\fBprovider_gettable_params()\fR is fairly useless if not accompanied by +\&\fBprovider_get_params()\fR. +.SS "Provider parameters" +.IX Subsection "Provider parameters" +\&\fBprovider_get_params()\fR can return the following provider parameters to the core: +.ie n .IP """name"" (\fB\s-1OSSL_PROV_PARAM_NAME\s0\fR) <\s-1UTF8\s0 ptr>" 4 +.el .IP "``name'' (\fB\s-1OSSL_PROV_PARAM_NAME\s0\fR) <\s-1UTF8\s0 ptr>" 4 +.IX Item "name (OSSL_PROV_PARAM_NAME) <UTF8 ptr>" +This points to a string that should give a unique name for the provider. +.ie n .IP """version"" (\fB\s-1OSSL_PROV_PARAM_VERSION\s0\fR) <\s-1UTF8\s0 ptr>" 4 +.el .IP "``version'' (\fB\s-1OSSL_PROV_PARAM_VERSION\s0\fR) <\s-1UTF8\s0 ptr>" 4 +.IX Item "version (OSSL_PROV_PARAM_VERSION) <UTF8 ptr>" +This points to a string that is a version number associated with this provider. +OpenSSL in-built providers use \s-1OPENSSL_VERSION_STR,\s0 but this may be different +for any third party provider. This string is for informational purposes only. +.ie n .IP """buildinfo"" (\fB\s-1OSSL_PROV_PARAM_BUILDINFO\s0\fR) <\s-1UTF8\s0 ptr>" 4 +.el .IP "``buildinfo'' (\fB\s-1OSSL_PROV_PARAM_BUILDINFO\s0\fR) <\s-1UTF8\s0 ptr>" 4 +.IX Item "buildinfo (OSSL_PROV_PARAM_BUILDINFO) <UTF8 ptr>" +This points to a string that is a build information associated with this provider. +OpenSSL in-built providers use \s-1OPENSSL_FULL_VERSION_STR,\s0 but this may be +different for any third party provider. +.ie n .IP """status"" (\fB\s-1OSSL_PROV_PARAM_STATUS\s0\fR) <unsigned integer>" 4 +.el .IP "``status'' (\fB\s-1OSSL_PROV_PARAM_STATUS\s0\fR) <unsigned integer>" 4 +.IX Item "status (OSSL_PROV_PARAM_STATUS) <unsigned integer>" +This returns 0 if the provider has entered an error state, otherwise it returns +1. +.PP +\&\fBprovider_gettable_params()\fR should return the above parameters. +.SS "Core parameters" +.IX Subsection "Core parameters" +\&\fBcore_get_params()\fR can retrieve the following core parameters for each provider: +.ie n .IP """openssl-version"" (\fB\s-1OSSL_PROV_PARAM_CORE_VERSION\s0\fR) <\s-1UTF8\s0 string ptr>" 4 +.el .IP "``openssl-version'' (\fB\s-1OSSL_PROV_PARAM_CORE_VERSION\s0\fR) <\s-1UTF8\s0 string ptr>" 4 +.IX Item "openssl-version (OSSL_PROV_PARAM_CORE_VERSION) <UTF8 string ptr>" +This points to the OpenSSL libraries' full version string, i.e. the string +expanded from the macro \fB\s-1OPENSSL_VERSION_STR\s0\fR. +.ie n .IP """provider-name"" (\fB\s-1OSSL_PROV_PARAM_CORE_PROV_NAME\s0\fR) <\s-1UTF8\s0 string ptr>" 4 +.el .IP "``provider-name'' (\fB\s-1OSSL_PROV_PARAM_CORE_PROV_NAME\s0\fR) <\s-1UTF8\s0 string ptr>" 4 +.IX Item "provider-name (OSSL_PROV_PARAM_CORE_PROV_NAME) <UTF8 string ptr>" +This points to the OpenSSL libraries' idea of what the calling provider is named. +.ie n .IP """module-filename"" (\fB\s-1OSSL_PROV_PARAM_CORE_MODULE_FILENAME\s0\fR) <\s-1UTF8\s0 string ptr>" 4 +.el .IP "``module-filename'' (\fB\s-1OSSL_PROV_PARAM_CORE_MODULE_FILENAME\s0\fR) <\s-1UTF8\s0 string ptr>" 4 +.IX Item "module-filename (OSSL_PROV_PARAM_CORE_MODULE_FILENAME) <UTF8 string ptr>" +This points to a string containing the full filename of the providers +module file. +.PP +Additionally, provider specific configuration parameters from the +config file are available, in dotted name form. +The dotted name form is a concatenation of section names and final +config command name separated by periods. +.PP +For example, let's say we have the following config example: +.PP +.Vb 2 +\& config_diagnostics = 1 +\& openssl_conf = openssl_init +\& +\& [openssl_init] +\& providers = providers_sect +\& +\& [providers_sect] +\& foo = foo_sect +\& +\& [foo_sect] +\& activate = 1 +\& data1 = 2 +\& data2 = str +\& more = foo_more +\& +\& [foo_more] +\& data3 = foo,bar +.Ve +.PP +The provider will have these additional parameters available: +.ie n .IP """activate""" 4 +.el .IP "``activate''" 4 +.IX Item "activate" +pointing at the string \*(L"1\*(R" +.ie n .IP """data1""" 4 +.el .IP "``data1''" 4 +.IX Item "data1" +pointing at the string \*(L"2\*(R" +.ie n .IP """data2""" 4 +.el .IP "``data2''" 4 +.IX Item "data2" +pointing at the string \*(L"str\*(R" +.ie n .IP """more.data3""" 4 +.el .IP "``more.data3''" 4 +.IX Item "more.data3" +pointing at the string \*(L"foo,bar\*(R" +.PP +For more information on handling parameters, see \s-1\fBOSSL_PARAM\s0\fR\|(3) as +\&\fBOSSL_PARAM_int\fR\|(3). +.SH "CAPABILITIES" +.IX Header "CAPABILITIES" +Capabilities describe some of the services that a provider can offer. +Applications can query the capabilities to discover those services. +.PP +\fI\*(L"TLS-GROUP\*(R" Capability\fR +.IX Subsection "TLS-GROUP Capability" +.PP +The \*(L"TLS-GROUP\*(R" capability can be queried by libssl to discover the list of +\&\s-1TLS\s0 groups that a provider can support. Each group supported can be used for +\&\fIkey exchange\fR (\s-1KEX\s0) or \fIkey encapsulation method\fR (\s-1KEM\s0) during a \s-1TLS\s0 +handshake. +\&\s-1TLS\s0 clients can advertise the list of \s-1TLS\s0 groups they support in the +supported_groups extension, and \s-1TLS\s0 servers can select a group from the offered +list that they also support. In this way a provider can add to the list of +groups that libssl already supports with additional ones. +.PP +Each \s-1TLS\s0 group that a provider supports should be described via the callback +passed in through the provider_get_capabilities function. Each group should have +the following details supplied (all are mandatory, except +\&\fB\s-1OSSL_CAPABILITY_TLS_GROUP_IS_KEM\s0\fR): +.ie n .IP """tls-group-name"" (\fB\s-1OSSL_CAPABILITY_TLS_GROUP_NAME\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``tls-group-name'' (\fB\s-1OSSL_CAPABILITY_TLS_GROUP_NAME\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "tls-group-name (OSSL_CAPABILITY_TLS_GROUP_NAME) <UTF8 string>" +The name of the group as given in the \s-1IANA TLS\s0 Supported Groups registry +<https://www.iana.org/assignments/tls\-parameters/tls\-parameters.xhtml#tls\-parameters\-8>. +.ie n .IP """tls-group-name-internal"" (\fB\s-1OSSL_CAPABILITY_TLS_GROUP_NAME_INTERNAL\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``tls-group-name-internal'' (\fB\s-1OSSL_CAPABILITY_TLS_GROUP_NAME_INTERNAL\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "tls-group-name-internal (OSSL_CAPABILITY_TLS_GROUP_NAME_INTERNAL) <UTF8 string>" +The name of the group as known by the provider. This could be the same as the +\&\*(L"tls-group-name\*(R", but does not have to be. +.ie n .IP """tls-group-id"" (\fB\s-1OSSL_CAPABILITY_TLS_GROUP_ID\s0\fR) <unsigned integer>" 4 +.el .IP "``tls-group-id'' (\fB\s-1OSSL_CAPABILITY_TLS_GROUP_ID\s0\fR) <unsigned integer>" 4 +.IX Item "tls-group-id (OSSL_CAPABILITY_TLS_GROUP_ID) <unsigned integer>" +The \s-1TLS\s0 group id value as given in the \s-1IANA TLS\s0 Supported Groups registry. +.ie n .IP """tls-group-alg"" (\fB\s-1OSSL_CAPABILITY_TLS_GROUP_ALG\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``tls-group-alg'' (\fB\s-1OSSL_CAPABILITY_TLS_GROUP_ALG\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "tls-group-alg (OSSL_CAPABILITY_TLS_GROUP_ALG) <UTF8 string>" +The name of a Key Management algorithm that the provider offers and that should +be used with this group. Keys created should be able to support \fIkey exchange\fR +or \fIkey encapsulation method\fR (\s-1KEM\s0), as implied by the optional +\&\fB\s-1OSSL_CAPABILITY_TLS_GROUP_IS_KEM\s0\fR flag. +The algorithm must support key and parameter generation as well as the +key/parameter generation parameter, \fB\s-1OSSL_PKEY_PARAM_GROUP_NAME\s0\fR. The group +name given via \*(L"tls-group-name-internal\*(R" above will be passed via +\&\fB\s-1OSSL_PKEY_PARAM_GROUP_NAME\s0\fR when libssl wishes to generate keys/parameters. +.ie n .IP """tls-group-sec-bits"" (\fB\s-1OSSL_CAPABILITY_TLS_GROUP_SECURITY_BITS\s0\fR) <unsigned integer>" 4 +.el .IP "``tls-group-sec-bits'' (\fB\s-1OSSL_CAPABILITY_TLS_GROUP_SECURITY_BITS\s0\fR) <unsigned integer>" 4 +.IX Item "tls-group-sec-bits (OSSL_CAPABILITY_TLS_GROUP_SECURITY_BITS) <unsigned integer>" +The number of bits of security offered by keys in this group. The number of bits +should be comparable with the ones given in table 2 and 3 of the \s-1NIST SP800\-57\s0 +document. +.ie n .IP """tls-group-is-kem"" (\fB\s-1OSSL_CAPABILITY_TLS_GROUP_IS_KEM\s0\fR) <unsigned integer>" 4 +.el .IP "``tls-group-is-kem'' (\fB\s-1OSSL_CAPABILITY_TLS_GROUP_IS_KEM\s0\fR) <unsigned integer>" 4 +.IX Item "tls-group-is-kem (OSSL_CAPABILITY_TLS_GROUP_IS_KEM) <unsigned integer>" +Boolean flag to describe if the group should be used in \fIkey exchange\fR (\s-1KEX\s0) +mode (0, default) or in \fIkey encapsulation method\fR (\s-1KEM\s0) mode (1). +.Sp +This parameter is optional: if not specified, \s-1KEX\s0 mode is assumed as the default +mode for the group. +.Sp +In \s-1KEX\s0 mode, in a typical Diffie-Hellman fashion, both sides execute \fIkeygen\fR +then \fIderive\fR against the peer public key. To operate in \s-1KEX\s0 mode, the group +implementation must support the provider functions as described in +\&\fBprovider\-keyexch\fR\|(7). +.Sp +In \s-1KEM\s0 mode, the client executes \fIkeygen\fR and sends its public key, the server +executes \fIencapsulate\fR using the client's public key and sends back the +resulting \fIciphertext\fR, finally the client executes \fIdecapsulate\fR to retrieve +the same \fIshared secret\fR generated by the server's \fIencapsulate\fR. To operate +in \s-1KEM\s0 mode, the group implementation must support the provider functions as +described in \fBprovider\-kem\fR\|(7). +.Sp +Both in \s-1KEX\s0 and \s-1KEM\s0 mode, the resulting \fIshared secret\fR is then used according +to the protocol specification. +.ie n .IP """tls-min-tls"" (\fB\s-1OSSL_CAPABILITY_TLS_GROUP_MIN_TLS\s0\fR) <integer>" 4 +.el .IP "``tls-min-tls'' (\fB\s-1OSSL_CAPABILITY_TLS_GROUP_MIN_TLS\s0\fR) <integer>" 4 +.IX Item "tls-min-tls (OSSL_CAPABILITY_TLS_GROUP_MIN_TLS) <integer>" +.PD 0 +.ie n .IP """tls-max-tls"" (\fB\s-1OSSL_CAPABILITY_TLS_GROUP_MAX_TLS\s0\fR) <integer>" 4 +.el .IP "``tls-max-tls'' (\fB\s-1OSSL_CAPABILITY_TLS_GROUP_MAX_TLS\s0\fR) <integer>" 4 +.IX Item "tls-max-tls (OSSL_CAPABILITY_TLS_GROUP_MAX_TLS) <integer>" +.ie n .IP """tls-min-dtls"" (\fB\s-1OSSL_CAPABILITY_TLS_GROUP_MIN_DTLS\s0\fR) <integer>" 4 +.el .IP "``tls-min-dtls'' (\fB\s-1OSSL_CAPABILITY_TLS_GROUP_MIN_DTLS\s0\fR) <integer>" 4 +.IX Item "tls-min-dtls (OSSL_CAPABILITY_TLS_GROUP_MIN_DTLS) <integer>" +.ie n .IP """tls-max-dtls"" (\fB\s-1OSSL_CAPABILITY_TLS_GROUP_MAX_DTLS\s0\fR) <integer>" 4 +.el .IP "``tls-max-dtls'' (\fB\s-1OSSL_CAPABILITY_TLS_GROUP_MAX_DTLS\s0\fR) <integer>" 4 +.IX Item "tls-max-dtls (OSSL_CAPABILITY_TLS_GROUP_MAX_DTLS) <integer>" +.PD +These parameters can be used to describe the minimum and maximum \s-1TLS\s0 and \s-1DTLS\s0 +versions supported by the group. The values equate to the on-the-wire encoding +of the various \s-1TLS\s0 versions. For example TLSv1.3 is 0x0304 (772 decimal), and +TLSv1.2 is 0x0303 (771 decimal). A 0 indicates that there is no defined minimum +or maximum. A \-1 indicates that the group should not be used in that protocol. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +This is an example of a simple provider made available as a +dynamically loadable module. +It implements the fictitious algorithm \f(CW\*(C`FOO\*(C'\fR for the fictitious +operation \f(CW\*(C`BAR\*(C'\fR. +.PP +.Vb 3 +\& #include <malloc.h> +\& #include <openssl/core.h> +\& #include <openssl/core_dispatch.h> +\& +\& /* Errors used in this provider */ +\& #define E_MALLOC 1 +\& +\& static const OSSL_ITEM reasons[] = { +\& { E_MALLOC, "memory allocation failure" }. +\& { 0, NULL } /* Termination */ +\& }; +\& +\& /* +\& * To ensure we get the function signature right, forward declare +\& * them using function types provided by openssl/core_dispatch.h +\& */ +\& OSSL_FUNC_bar_newctx_fn foo_newctx; +\& OSSL_FUNC_bar_freectx_fn foo_freectx; +\& OSSL_FUNC_bar_init_fn foo_init; +\& OSSL_FUNC_bar_update_fn foo_update; +\& OSSL_FUNC_bar_final_fn foo_final; +\& +\& OSSL_FUNC_provider_query_operation_fn p_query; +\& OSSL_FUNC_provider_get_reason_strings_fn p_reasons; +\& OSSL_FUNC_provider_teardown_fn p_teardown; +\& +\& OSSL_provider_init_fn OSSL_provider_init; +\& +\& OSSL_FUNC_core_put_error *c_put_error = NULL; +\& +\& /* Provider context */ +\& struct prov_ctx_st { +\& OSSL_CORE_HANDLE *handle; +\& } +\& +\& /* operation context for the algorithm FOO */ +\& struct foo_ctx_st { +\& struct prov_ctx_st *provctx; +\& int b; +\& }; +\& +\& static void *foo_newctx(void *provctx) +\& { +\& struct foo_ctx_st *fooctx = malloc(sizeof(*fooctx)); +\& +\& if (fooctx != NULL) +\& fooctx\->provctx = provctx; +\& else +\& c_put_error(provctx\->handle, E_MALLOC, _\|_FILE_\|_, _\|_LINE_\|_); +\& return fooctx; +\& } +\& +\& static void foo_freectx(void *fooctx) +\& { +\& free(fooctx); +\& } +\& +\& static int foo_init(void *vfooctx) +\& { +\& struct foo_ctx_st *fooctx = vfooctx; +\& +\& fooctx\->b = 0x33; +\& } +\& +\& static int foo_update(void *vfooctx, unsigned char *in, size_t inl) +\& { +\& struct foo_ctx_st *fooctx = vfooctx; +\& +\& /* did you expect something serious? */ +\& if (inl == 0) +\& return 1; +\& for (; inl\-\- > 0; in++) +\& *in ^= fooctx\->b; +\& return 1; +\& } +\& +\& static int foo_final(void *vfooctx) +\& { +\& struct foo_ctx_st *fooctx = vfooctx; +\& +\& fooctx\->b = 0x66; +\& } +\& +\& static const OSSL_DISPATCH foo_fns[] = { +\& { OSSL_FUNC_BAR_NEWCTX, (void (*)(void))foo_newctx }, +\& { OSSL_FUNC_BAR_FREECTX, (void (*)(void))foo_freectx }, +\& { OSSL_FUNC_BAR_INIT, (void (*)(void))foo_init }, +\& { OSSL_FUNC_BAR_UPDATE, (void (*)(void))foo_update }, +\& { OSSL_FUNC_BAR_FINAL, (void (*)(void))foo_final }, +\& { 0, NULL } +\& }; +\& +\& static const OSSL_ALGORITHM bars[] = { +\& { "FOO", "provider=chumbawamba", foo_fns }, +\& { NULL, NULL, NULL } +\& }; +\& +\& static const OSSL_ALGORITHM *p_query(void *provctx, int operation_id, +\& int *no_store) +\& { +\& switch (operation_id) { +\& case OSSL_OP_BAR: +\& return bars; +\& } +\& return NULL; +\& } +\& +\& static const OSSL_ITEM *p_reasons(void *provctx) +\& { +\& return reasons; +\& } +\& +\& static void p_teardown(void *provctx) +\& { +\& free(provctx); +\& } +\& +\& static const OSSL_DISPATCH prov_fns[] = { +\& { OSSL_FUNC_PROVIDER_TEARDOWN, (void (*)(void))p_teardown }, +\& { OSSL_FUNC_PROVIDER_QUERY_OPERATION, (void (*)(void))p_query }, +\& { OSSL_FUNC_PROVIDER_GET_REASON_STRINGS, (void (*)(void))p_reasons }, +\& { 0, NULL } +\& }; +\& +\& int OSSL_provider_init(const OSSL_CORE_HANDLE *handle, +\& const OSSL_DISPATCH *in, +\& const OSSL_DISPATCH **out, +\& void **provctx) +\& { +\& struct prov_ctx_st *pctx = NULL; +\& +\& for (; in\->function_id != 0; in++) +\& switch (in\->function_id) { +\& case OSSL_FUNC_CORE_PUT_ERROR: +\& c_put_error = OSSL_FUNC_core_put_error(in); +\& break; +\& } +\& +\& *out = prov_fns; +\& +\& if ((pctx = malloc(sizeof(*pctx))) == NULL) { +\& /* +\& * ALEA IACTA EST, if the core retrieves the reason table +\& * regardless, that string will be displayed, otherwise not. +\& */ +\& c_put_error(handle, E_MALLOC, _\|_FILE_\|_, _\|_LINE_\|_); +\& return 0; +\& } +\& pctx\->handle = handle; +\& return 1; +\& } +.Ve +.PP +This relies on a few things existing in \fIopenssl/core_dispatch.h\fR: +.PP +.Vb 1 +\& #define OSSL_OP_BAR 4711 +\& +\& #define OSSL_FUNC_BAR_NEWCTX 1 +\& typedef void *(OSSL_FUNC_bar_newctx_fn)(void *provctx); +\& static ossl_inline OSSL_FUNC_bar_newctx(const OSSL_DISPATCH *opf) +\& { return (OSSL_FUNC_bar_newctx_fn *)opf\->function; } +\& +\& #define OSSL_FUNC_BAR_FREECTX 2 +\& typedef void (OSSL_FUNC_bar_freectx_fn)(void *ctx); +\& static ossl_inline OSSL_FUNC_bar_freectx(const OSSL_DISPATCH *opf) +\& { return (OSSL_FUNC_bar_freectx_fn *)opf\->function; } +\& +\& #define OSSL_FUNC_BAR_INIT 3 +\& typedef void *(OSSL_FUNC_bar_init_fn)(void *ctx); +\& static ossl_inline OSSL_FUNC_bar_init(const OSSL_DISPATCH *opf) +\& { return (OSSL_FUNC_bar_init_fn *)opf\->function; } +\& +\& #define OSSL_FUNC_BAR_UPDATE 4 +\& typedef void *(OSSL_FUNC_bar_update_fn)(void *ctx, +\& unsigned char *in, size_t inl); +\& static ossl_inline OSSL_FUNC_bar_update(const OSSL_DISPATCH *opf) +\& { return (OSSL_FUNC_bar_update_fn *)opf\->function; } +\& +\& #define OSSL_FUNC_BAR_FINAL 5 +\& typedef void *(OSSL_FUNC_bar_final_fn)(void *ctx); +\& static ossl_inline OSSL_FUNC_bar_final(const OSSL_DISPATCH *opf) +\& { return (OSSL_FUNC_bar_final_fn *)opf\->function; } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The concept of providers and everything surrounding them was +introduced in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2019\-2023 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>. diff --git a/secure/lib/libcrypto/man/man7/provider-cipher.7 b/secure/lib/libcrypto/man/man7/provider-cipher.7 new file mode 100644 index 000000000000..ade5ddc28cdb --- /dev/null +++ b/secure/lib/libcrypto/man/man7/provider-cipher.7 @@ -0,0 +1,375 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "PROVIDER-CIPHER 7ossl" +.TH PROVIDER-CIPHER 7ossl "2023-09-19" "3.0.11" "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" +provider\-cipher \- The cipher library <\-> provider functions +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 2 +\& #include <openssl/core_dispatch.h> +\& #include <openssl/core_names.h> +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Context management */ +\& void *OSSL_FUNC_cipher_newctx(void *provctx); +\& void OSSL_FUNC_cipher_freectx(void *cctx); +\& void *OSSL_FUNC_cipher_dupctx(void *cctx); +\& +\& /* Encryption/decryption */ +\& int OSSL_FUNC_cipher_encrypt_init(void *cctx, const unsigned char *key, +\& size_t keylen, const unsigned char *iv, +\& size_t ivlen, const OSSL_PARAM params[]); +\& int OSSL_FUNC_cipher_decrypt_init(void *cctx, const unsigned char *key, +\& size_t keylen, const unsigned char *iv, +\& size_t ivlen, const OSSL_PARAM params[]); +\& int OSSL_FUNC_cipher_update(void *cctx, unsigned char *out, size_t *outl, +\& size_t outsize, const unsigned char *in, size_t inl); +\& int OSSL_FUNC_cipher_final(void *cctx, unsigned char *out, size_t *outl, +\& size_t outsize); +\& int OSSL_FUNC_cipher_cipher(void *cctx, unsigned char *out, size_t *outl, +\& size_t outsize, const unsigned char *in, size_t inl); +\& +\& /* Cipher parameter descriptors */ +\& const OSSL_PARAM *OSSL_FUNC_cipher_gettable_params(void *provctx); +\& +\& /* Cipher operation parameter descriptors */ +\& const OSSL_PARAM *OSSL_FUNC_cipher_gettable_ctx_params(void *cctx, +\& void *provctx); +\& const OSSL_PARAM *OSSL_FUNC_cipher_settable_ctx_params(void *cctx, +\& void *provctx); +\& +\& /* Cipher parameters */ +\& int OSSL_FUNC_cipher_get_params(OSSL_PARAM params[]); +\& +\& /* Cipher operation parameters */ +\& int OSSL_FUNC_cipher_get_ctx_params(void *cctx, OSSL_PARAM params[]); +\& int OSSL_FUNC_cipher_set_ctx_params(void *cctx, const OSSL_PARAM params[]); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7) +for further information. +.PP +The \s-1CIPHER\s0 operation enables providers to implement cipher algorithms and make +them available to applications via the \s-1API\s0 functions \fBEVP_EncryptInit_ex\fR\|(3), +\&\fBEVP_EncryptUpdate\fR\|(3) and \fBEVP_EncryptFinal\fR\|(3) (as well as the decrypt +equivalents and other related functions). +.PP +All \*(L"functions\*(R" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays via +\&\s-1\fBOSSL_ALGORITHM\s0\fR\|(3) arrays that are returned by the provider's +\&\fBprovider_query_operation()\fR function +(see \*(L"Provider Functions\*(R" in \fBprovider\-base\fR\|(7)). +.PP +All these \*(L"functions\*(R" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from an \s-1\fBOSSL_DISPATCH\s0\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the \*(L"function\*(R" \fBOSSL_FUNC_cipher_newctx()\fR has these: +.PP +.Vb 3 +\& typedef void *(OSSL_FUNC_cipher_newctx_fn)(void *provctx); +\& static ossl_inline OSSL_FUNC_cipher_newctx_fn +\& OSSL_FUNC_cipher_newctx(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 3 +\& OSSL_FUNC_cipher_newctx OSSL_FUNC_CIPHER_NEWCTX +\& OSSL_FUNC_cipher_freectx OSSL_FUNC_CIPHER_FREECTX +\& OSSL_FUNC_cipher_dupctx OSSL_FUNC_CIPHER_DUPCTX +\& +\& OSSL_FUNC_cipher_encrypt_init OSSL_FUNC_CIPHER_ENCRYPT_INIT +\& OSSL_FUNC_cipher_decrypt_init OSSL_FUNC_CIPHER_DECRYPT_INIT +\& OSSL_FUNC_cipher_update OSSL_FUNC_CIPHER_UPDATE +\& OSSL_FUNC_cipher_final OSSL_FUNC_CIPHER_FINAL +\& OSSL_FUNC_cipher_cipher OSSL_FUNC_CIPHER_CIPHER +\& +\& OSSL_FUNC_cipher_get_params OSSL_FUNC_CIPHER_GET_PARAMS +\& OSSL_FUNC_cipher_get_ctx_params OSSL_FUNC_CIPHER_GET_CTX_PARAMS +\& OSSL_FUNC_cipher_set_ctx_params OSSL_FUNC_CIPHER_SET_CTX_PARAMS +\& +\& OSSL_FUNC_cipher_gettable_params OSSL_FUNC_CIPHER_GETTABLE_PARAMS +\& OSSL_FUNC_cipher_gettable_ctx_params OSSL_FUNC_CIPHER_GETTABLE_CTX_PARAMS +\& OSSL_FUNC_cipher_settable_ctx_params OSSL_FUNC_CIPHER_SETTABLE_CTX_PARAMS +.Ve +.PP +A cipher algorithm implementation may not implement all of these functions. +In order to be a consistent set of functions there must at least be a complete +set of \*(L"encrypt\*(R" functions, or a complete set of \*(L"decrypt\*(R" functions, or a +single \*(L"cipher\*(R" function. +In all cases both the OSSL_FUNC_cipher_newctx and OSSL_FUNC_cipher_freectx functions must be +present. +All other functions are optional. +.SS "Context Management Functions" +.IX Subsection "Context Management Functions" +\&\fBOSSL_FUNC_cipher_newctx()\fR should create and return a pointer to a provider side +structure for holding context information during a cipher operation. +A pointer to this context will be passed back in a number of the other cipher +operation function calls. +The parameter \fIprovctx\fR is the provider context generated during provider +initialisation (see \fBprovider\fR\|(7)). +.PP +\&\fBOSSL_FUNC_cipher_freectx()\fR is passed a pointer to the provider side cipher context in +the \fIcctx\fR parameter. +This function should free any resources associated with that context. +.PP +\&\fBOSSL_FUNC_cipher_dupctx()\fR should duplicate the provider side cipher context in the +\&\fIcctx\fR parameter and return the duplicate copy. +.SS "Encryption/Decryption Functions" +.IX Subsection "Encryption/Decryption Functions" +\&\fBOSSL_FUNC_cipher_encrypt_init()\fR initialises a cipher operation for encryption given a +newly created provider side cipher context in the \fIcctx\fR parameter. +The key to be used is given in \fIkey\fR which is \fIkeylen\fR bytes long. +The \s-1IV\s0 to be used is given in \fIiv\fR which is \fIivlen\fR bytes long. +The \fIparams\fR, if not \s-1NULL,\s0 should be set on the context in a manner similar to +using \fBOSSL_FUNC_cipher_set_ctx_params()\fR. +.PP +\&\fBOSSL_FUNC_cipher_decrypt_init()\fR is the same as \fBOSSL_FUNC_cipher_encrypt_init()\fR except that it +initialises the context for a decryption operation. +.PP +\&\fBOSSL_FUNC_cipher_update()\fR is called to supply data to be encrypted/decrypted as part of +a previously initialised cipher operation. +The \fIcctx\fR parameter contains a pointer to a previously initialised provider +side context. +\&\fBOSSL_FUNC_cipher_update()\fR should encrypt/decrypt \fIinl\fR bytes of data at the location +pointed to by \fIin\fR. +The encrypted data should be stored in \fIout\fR and the amount of data written to +\&\fI*outl\fR which should not exceed \fIoutsize\fR bytes. +\&\fBOSSL_FUNC_cipher_update()\fR may be called multiple times for a single cipher operation. +It is the responsibility of the cipher implementation to handle input lengths +that are not multiples of the block length. +In such cases a cipher implementation will typically cache partial blocks of +input data until a complete block is obtained. +\&\fIout\fR may be the same location as \fIin\fR but it should not partially overlap. +The same expectations apply to \fIoutsize\fR as documented for +\&\fBEVP_EncryptUpdate\fR\|(3) and \fBEVP_DecryptUpdate\fR\|(3). +.PP +\&\fBOSSL_FUNC_cipher_final()\fR completes an encryption or decryption started through previous +\&\fBOSSL_FUNC_cipher_encrypt_init()\fR or \fBOSSL_FUNC_cipher_decrypt_init()\fR, and \fBOSSL_FUNC_cipher_update()\fR +calls. +The \fIcctx\fR parameter contains a pointer to the provider side context. +Any final encryption/decryption output should be written to \fIout\fR and the +amount of data written to \fI*outl\fR which should not exceed \fIoutsize\fR bytes. +The same expectations apply to \fIoutsize\fR as documented for +\&\fBEVP_EncryptFinal\fR\|(3) and \fBEVP_DecryptFinal\fR\|(3). +.PP +\&\fBOSSL_FUNC_cipher_cipher()\fR performs encryption/decryption using the provider side cipher +context in the \fIcctx\fR parameter that should have been previously initialised via +a call to \fBOSSL_FUNC_cipher_encrypt_init()\fR or \fBOSSL_FUNC_cipher_decrypt_init()\fR. +This should call the raw underlying cipher function without any padding. +This will be invoked in the provider as a result of the application calling +\&\fBEVP_Cipher\fR\|(3). +The application is responsible for ensuring that the input is a multiple of the +block length. +The data to be encrypted/decrypted will be in \fIin\fR, and it will be \fIinl\fR bytes +in length. +The output from the encryption/decryption should be stored in \fIout\fR and the +amount of data stored should be put in \fI*outl\fR which should be no more than +\&\fIoutsize\fR bytes. +.SS "Cipher Parameters" +.IX Subsection "Cipher Parameters" +See \s-1\fBOSSL_PARAM\s0\fR\|(3) for further details on the parameters structure used by +these functions. +.PP +\&\fBOSSL_FUNC_cipher_get_params()\fR gets details of the algorithm implementation +and stores them in \fIparams\fR. +.PP +\&\fBOSSL_FUNC_cipher_set_ctx_params()\fR sets cipher operation parameters for the +provider side cipher context \fIcctx\fR to \fIparams\fR. +Any parameter settings are additional to any that were previously set. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_cipher_get_ctx_params()\fR gets cipher operation details details from +the given provider side cipher context \fIcctx\fR and stores them in \fIparams\fR. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_cipher_gettable_params()\fR, \fBOSSL_FUNC_cipher_gettable_ctx_params()\fR, +and \fBOSSL_FUNC_cipher_settable_ctx_params()\fR all return constant \s-1\fBOSSL_PARAM\s0\fR\|(3) +arrays as descriptors of the parameters that \fBOSSL_FUNC_cipher_get_params()\fR, +\&\fBOSSL_FUNC_cipher_get_ctx_params()\fR, and \fBOSSL_FUNC_cipher_set_ctx_params()\fR +can handle, respectively. \fBOSSL_FUNC_cipher_gettable_ctx_params()\fR and +\&\fBOSSL_FUNC_cipher_settable_ctx_params()\fR will return the parameters associated +with the provider side context \fIcctx\fR in its current state if it is +not \s-1NULL.\s0 Otherwise, they return the parameters associated with the +provider side algorithm \fIprovctx\fR. +.PP +Parameters currently recognised by built-in ciphers are listed in +\&\*(L"\s-1PARAMETERS\*(R"\s0 in \fBEVP_EncryptInit\fR\|(3). +Not all parameters are relevant to, or are understood by all ciphers. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_cipher_newctx()\fR and \fBOSSL_FUNC_cipher_dupctx()\fR should return the newly created +provider side cipher context, or \s-1NULL\s0 on failure. +.PP +\&\fBOSSL_FUNC_cipher_encrypt_init()\fR, \fBOSSL_FUNC_cipher_decrypt_init()\fR, \fBOSSL_FUNC_cipher_update()\fR, +\&\fBOSSL_FUNC_cipher_final()\fR, \fBOSSL_FUNC_cipher_cipher()\fR, \fBOSSL_FUNC_cipher_get_params()\fR, +\&\fBOSSL_FUNC_cipher_get_ctx_params()\fR and \fBOSSL_FUNC_cipher_set_ctx_params()\fR should return 1 for +success or 0 on error. +.PP +\&\fBOSSL_FUNC_cipher_gettable_params()\fR, \fBOSSL_FUNC_cipher_gettable_ctx_params()\fR and +\&\fBOSSL_FUNC_cipher_settable_ctx_params()\fR should return a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) +array, or \s-1NULL\s0 if none is offered. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), \s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7), +\&\fBOSSL_PROVIDER\-legacy\fR\|(7), +\&\s-1\fBEVP_CIPHER\-AES\s0\fR\|(7), \s-1\fBEVP_CIPHER\-ARIA\s0\fR\|(7), \s-1\fBEVP_CIPHER\-BLOWFISH\s0\fR\|(7), +\&\s-1\fBEVP_CIPHER\-CAMELLIA\s0\fR\|(7), \s-1\fBEVP_CIPHER\-CAST\s0\fR\|(7), \s-1\fBEVP_CIPHER\-CHACHA\s0\fR\|(7), +\&\s-1\fBEVP_CIPHER\-DES\s0\fR\|(7), \s-1\fBEVP_CIPHER\-IDEA\s0\fR\|(7), \s-1\fBEVP_CIPHER\-RC2\s0\fR\|(7), +\&\s-1\fBEVP_CIPHER\-RC4\s0\fR\|(7), \s-1\fBEVP_CIPHER\-RC5\s0\fR\|(7), \s-1\fBEVP_CIPHER\-SEED\s0\fR\|(7), +\&\s-1\fBEVP_CIPHER\-SM4\s0\fR\|(7), \s-1\fBEVP_CIPHER\-NULL\s0\fR\|(7), +\&\fBlife_cycle\-cipher\fR\|(7), \fBEVP_EncryptInit\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +The provider \s-1CIPHER\s0 interface was introduced in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2019\-2023 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>. diff --git a/secure/lib/libcrypto/man/man7/provider-decoder.7 b/secure/lib/libcrypto/man/man7/provider-decoder.7 new file mode 100644 index 000000000000..fc37d6066958 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/provider-decoder.7 @@ -0,0 +1,419 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "PROVIDER-DECODER 7ossl" +.TH PROVIDER-DECODER 7ossl "2023-09-19" "3.0.11" "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" +provider\-decoder \- The OSSL_DECODER library <\-> provider functions +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/core_dispatch.h> +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Decoder parameter accessor and descriptor */ +\& const OSSL_PARAM *OSSL_FUNC_decoder_gettable_params(void *provctx); +\& int OSSL_FUNC_decoder_get_params(OSSL_PARAM params[]); +\& +\& /* Functions to construct / destruct / manipulate the decoder context */ +\& void *OSSL_FUNC_decoder_newctx(void *provctx); +\& void OSSL_FUNC_decoder_freectx(void *ctx); +\& const OSSL_PARAM *OSSL_FUNC_decoder_settable_ctx_params(void *provctx); +\& int OSSL_FUNC_decoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]); +\& +\& /* Functions to check selection support */ +\& int OSSL_FUNC_decoder_does_selection(void *provctx, int selection); +\& +\& /* Functions to decode object data */ +\& int OSSL_FUNC_decoder_decode(void *ctx, OSSL_CORE_BIO *in, +\& int selection, +\& OSSL_CALLBACK *data_cb, void *data_cbarg, +\& OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg); +\& +\& /* Functions to export a decoded object */ +\& int OSSL_FUNC_decoder_export_object(void *ctx, +\& const void *objref, size_t objref_sz, +\& OSSL_CALLBACK *export_cb, +\& void *export_cbarg); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fIThe term \*(L"decode\*(R" is used throughout this manual. This includes but is +not limited to deserialization as individual decoders can also do +decoding into intermediate data formats.\fR +.PP +The \s-1DECODER\s0 operation is a generic method to create a provider-native +object reference or intermediate decoded data from an encoded form +read from the given \fB\s-1OSSL_CORE_BIO\s0\fR. If the caller wants to decode +data from memory, it should provide a \fBBIO_s_mem\fR\|(3) \fB\s-1BIO\s0\fR. The decoded +data or object reference is passed along with eventual metadata +to the \fImetadata_cb\fR as \s-1\fBOSSL_PARAM\s0\fR\|(3) parameters. +.PP +The decoder doesn't need to know more about the \fB\s-1OSSL_CORE_BIO\s0\fR +pointer than being able to pass it to the appropriate \s-1BIO\s0 upcalls (see +\&\*(L"Core functions\*(R" in \fBprovider\-base\fR\|(7)). +.PP +The \s-1DECODER\s0 implementation may be part of a chain, where data is +passed from one to the next. For example, there may be an +implementation to decode an object from \s-1PEM\s0 to \s-1DER,\s0 and another one +that decodes \s-1DER\s0 to a provider-native object. +.PP +The last decoding step in the decoding chain is usually supposed to create +a provider-native object referenced by an object reference. To import +that object into a different provider the \fBOSSL_FUNC_decoder_export_object()\fR +can be called as the final step of the decoding process. +.PP +All \*(L"functions\*(R" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays via +\&\s-1\fBOSSL_ALGORITHM\s0\fR\|(3) arrays that are returned by the provider's +\&\fBprovider_query_operation()\fR function +(see \*(L"Provider Functions\*(R" in \fBprovider\-base\fR\|(7)). +.PP +All these \*(L"functions\*(R" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from an \s-1\fBOSSL_DISPATCH\s0\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the \*(L"function\*(R" \fBOSSL_FUNC_decoder_decode()\fR has these: +.PP +.Vb 7 +\& typedef int +\& (OSSL_FUNC_decoder_decode_fn)(void *ctx, OSSL_CORE_BIO *in, +\& int selection, +\& OSSL_CALLBACK *data_cb, void *data_cbarg, +\& OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg); +\& static ossl_inline OSSL_FUNC_decoder_decode_fn* +\& OSSL_FUNC_decoder_decode(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 2 +\& OSSL_FUNC_decoder_get_params OSSL_FUNC_DECODER_GET_PARAMS +\& OSSL_FUNC_decoder_gettable_params OSSL_FUNC_DECODER_GETTABLE_PARAMS +\& +\& OSSL_FUNC_decoder_newctx OSSL_FUNC_DECODER_NEWCTX +\& OSSL_FUNC_decoder_freectx OSSL_FUNC_DECODER_FREECTX +\& OSSL_FUNC_decoder_set_ctx_params OSSL_FUNC_DECODER_SET_CTX_PARAMS +\& OSSL_FUNC_decoder_settable_ctx_params OSSL_FUNC_DECODER_SETTABLE_CTX_PARAMS +\& +\& OSSL_FUNC_decoder_does_selection OSSL_FUNC_DECODER_DOES_SELECTION +\& +\& OSSL_FUNC_decoder_decode OSSL_FUNC_DECODER_DECODE +\& +\& OSSL_FUNC_decoder_export_object OSSL_FUNC_DECODER_EXPORT_OBJECT +.Ve +.SS "Names and properties" +.IX Subsection "Names and properties" +The name of an implementation should match the target type of object +it decodes. For example, an implementation that decodes an \s-1RSA\s0 key +should be named \*(L"\s-1RSA\*(R".\s0 Likewise, an implementation that decodes \s-1DER\s0 data +from \s-1PEM\s0 input should be named \*(L"\s-1DER\*(R".\s0 +.PP +Properties can be used to further specify details about an implementation: +.IP "input" 4 +.IX Item "input" +This property is used to specify what format of input the implementation +can decode. +.Sp +This property is \fImandatory\fR. +.Sp +OpenSSL providers recognize the following input types: +.RS 4 +.IP "pem" 4 +.IX Item "pem" +An implementation with that input type decodes \s-1PEM\s0 formatted data. +.IP "der" 4 +.IX Item "der" +An implementation with that input type decodes \s-1DER\s0 formatted data. +.IP "msblob" 4 +.IX Item "msblob" +An implementation with that input type decodes \s-1MSBLOB\s0 formatted data. +.IP "pvk" 4 +.IX Item "pvk" +An implementation with that input type decodes \s-1PVK\s0 formatted data. +.RE +.RS 4 +.RE +.IP "structure" 4 +.IX Item "structure" +This property is used to specify the structure that the decoded data is +expected to have. +.Sp +This property is \fIoptional\fR. +.Sp +Structures currently recognised by built-in decoders: +.RS 4 +.ie n .IP """type-specific""" 4 +.el .IP "``type-specific''" 4 +.IX Item "type-specific" +Type specific structure. +.ie n .IP """pkcs8""" 4 +.el .IP "``pkcs8''" 4 +.IX Item "pkcs8" +Structure according to the PKCS#8 specification. +.ie n .IP """SubjectPublicKeyInfo""" 4 +.el .IP "``SubjectPublicKeyInfo''" 4 +.IX Item "SubjectPublicKeyInfo" +Encoding of public keys according to the Subject Public Key Info of \s-1RFC 5280.\s0 +.RE +.RS 4 +.RE +.PP +The possible values of both these properties is open ended. A provider may +very well specify input types and structures that libcrypto doesn't know +anything about. +.SS "Subset selections" +.IX Subsection "Subset selections" +Sometimes, an object has more than one subset of data that is interesting to +treat separately or together. It's possible to specify what subsets are to +be decoded, with a set of bits \fIselection\fR that are passed in an \fBint\fR. +.PP +This set of bits depend entirely on what kind of provider-side object is +to be decoded. For example, those bits are assumed to be the same as those +used with \fBprovider\-keymgmt\fR\|(7) (see \*(L"Key Objects\*(R" in \fBprovider\-keymgmt\fR\|(7)) when +the object is an asymmetric keypair \- e.g., \fB\s-1OSSL_KEYMGMT_SELECT_PRIVATE_KEY\s0\fR +if the object to be decoded is supposed to contain private key components. +.PP +\&\fBOSSL_FUNC_decoder_does_selection()\fR should tell if a particular implementation +supports any of the combinations given by \fIselection\fR. +.SS "Context functions" +.IX Subsection "Context functions" +\&\fBOSSL_FUNC_decoder_newctx()\fR returns a context to be used with the rest of +the functions. +.PP +\&\fBOSSL_FUNC_decoder_freectx()\fR frees the given \fIctx\fR as created by +\&\fBOSSL_FUNC_decoder_newctx()\fR. +.PP +\&\fBOSSL_FUNC_decoder_set_ctx_params()\fR sets context data according to parameters +from \fIparams\fR that it recognises. Unrecognised parameters should be +ignored. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_decoder_settable_ctx_params()\fR returns a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) +array describing the parameters that \fBOSSL_FUNC_decoder_set_ctx_params()\fR +can handle. +.PP +See \s-1\fBOSSL_PARAM\s0\fR\|(3) for further details on the parameters structure used by +\&\fBOSSL_FUNC_decoder_set_ctx_params()\fR and \fBOSSL_FUNC_decoder_settable_ctx_params()\fR. +.SS "Export function" +.IX Subsection "Export function" +When a provider-native object is created by a decoder it would be unsuitable +for direct use with a foreign provider. The export function allows for +exporting the object into that foreign provider if the foreign provider +supports the type of the object and provides an import function. +.PP +\&\fBOSSL_FUNC_decoder_export_object()\fR should export the object of size \fIobjref_sz\fR +referenced by \fIobjref\fR as an \s-1\fBOSSL_PARAM\s0\fR\|(3) array and pass that into the +\&\fIexport_cb\fR as well as the given \fIexport_cbarg\fR. +.SS "Decoding functions" +.IX Subsection "Decoding functions" +\&\fBOSSL_FUNC_decoder_decode()\fR should decode the data as read from +the \fB\s-1OSSL_CORE_BIO\s0\fR \fIin\fR to produce decoded data or an object to be +passed as reference in an \s-1\fBOSSL_PARAM\s0\fR\|(3) array along with possible other +metadata that was decoded from the input. This \s-1\fBOSSL_PARAM\s0\fR\|(3) array is +then passed to the \fIdata_cb\fR callback. The \fIselection\fR bits, +if relevant, should determine what the input data should contain. +The decoding functions also take an \s-1\fBOSSL_PASSPHRASE_CALLBACK\s0\fR\|(3) function +pointer along with a pointer to application data \fIcbarg\fR, which should be +used when a pass phrase prompt is needed. +.PP +It's important to understand that the return value from this function is +interpreted as follows: +.IP "True (1)" 4 +.IX Item "True (1)" +This means \*(L"carry on the decoding process\*(R", and is meaningful even though +this function couldn't decode the input into anything, because there may be +another decoder implementation that can decode it into something. +.Sp +The \fIdata_cb\fR callback should never be called when this function can't +decode the input into anything. +.IP "False (0)" 4 +.IX Item "False (0)" +This means \*(L"stop the decoding process\*(R", and is meaningful when the input +could be decoded into some sort of object that this function understands, +but further treatment of that object results into errors that won't be +possible for some other decoder implementation to get a different result. +.PP +The conditions to stop the decoding process are at the discretion of the +implementation. +.SS "Decoder operation parameters" +.IX Subsection "Decoder operation parameters" +There are currently no operation parameters currently recognised by the +built-in decoders. +.PP +Parameters currently recognised by the built-in pass phrase callback: +.ie n .IP """info"" (\fB\s-1OSSL_PASSPHRASE_PARAM_INFO\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``info'' (\fB\s-1OSSL_PASSPHRASE_PARAM_INFO\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "info (OSSL_PASSPHRASE_PARAM_INFO) <UTF8 string>" +A string of information that will become part of the pass phrase +prompt. This could be used to give the user information on what kind +of object it's being prompted for. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_decoder_newctx()\fR returns a pointer to a context, or \s-1NULL\s0 on +failure. +.PP +\&\fBOSSL_FUNC_decoder_set_ctx_params()\fR returns 1, unless a recognised +parameter was invalid or caused an error, for which 0 is returned. +.PP +\&\fBOSSL_FUNC_decoder_settable_ctx_params()\fR returns a pointer to an array of +constant \s-1\fBOSSL_PARAM\s0\fR\|(3) elements. +.PP +\&\fBOSSL_FUNC_decoder_does_selection()\fR returns 1 if the decoder implementation +supports any of the \fIselection\fR bits, otherwise 0. +.PP +\&\fBOSSL_FUNC_decoder_decode()\fR returns 1 to signal that the decoding process +should continue, or 0 to signal that it should stop. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The \s-1DECODER\s0 interface was introduced in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2019\-2023 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>. diff --git a/secure/lib/libcrypto/man/man7/provider-digest.7 b/secure/lib/libcrypto/man/man7/provider-digest.7 new file mode 100644 index 000000000000..ecb25762cc4f --- /dev/null +++ b/secure/lib/libcrypto/man/man7/provider-digest.7 @@ -0,0 +1,404 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "PROVIDER-DIGEST 7ossl" +.TH PROVIDER-DIGEST 7ossl "2023-09-19" "3.0.11" "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" +provider\-digest \- The digest library <\-> provider functions +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 2 +\& #include <openssl/core_dispatch.h> +\& #include <openssl/core_names.h> +\& +\& /* +\& * Digests support the following function signatures in OSSL_DISPATCH arrays. +\& * (The function signatures are not actual functions). +\& */ +\& +\& /* Context management */ +\& void *OSSL_FUNC_digest_newctx(void *provctx); +\& void OSSL_FUNC_digest_freectx(void *dctx); +\& void *OSSL_FUNC_digest_dupctx(void *dctx); +\& +\& /* Digest generation */ +\& int OSSL_FUNC_digest_init(void *dctx, const OSSL_PARAM params[]); +\& int OSSL_FUNC_digest_update(void *dctx, const unsigned char *in, size_t inl); +\& int OSSL_FUNC_digest_final(void *dctx, unsigned char *out, size_t *outl, +\& size_t outsz); +\& int OSSL_FUNC_digest_digest(void *provctx, const unsigned char *in, size_t inl, +\& unsigned char *out, size_t *outl, size_t outsz); +\& +\& /* Digest parameter descriptors */ +\& const OSSL_PARAM *OSSL_FUNC_digest_gettable_params(void *provctx); +\& +\& /* Digest operation parameter descriptors */ +\& const OSSL_PARAM *OSSL_FUNC_digest_gettable_ctx_params(void *dctx, +\& void *provctx); +\& const OSSL_PARAM *OSSL_FUNC_digest_settable_ctx_params(void *dctx, +\& void *provctx); +\& +\& /* Digest parameters */ +\& int OSSL_FUNC_digest_get_params(OSSL_PARAM params[]); +\& +\& /* Digest operation parameters */ +\& int OSSL_FUNC_digest_set_ctx_params(void *dctx, const OSSL_PARAM params[]); +\& int OSSL_FUNC_digest_get_ctx_params(void *dctx, OSSL_PARAM params[]); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7) +for further information. +.PP +The \s-1DIGEST\s0 operation enables providers to implement digest algorithms and make +them available to applications via the \s-1API\s0 functions \fBEVP_DigestInit_ex\fR\|(3), +\&\fBEVP_DigestUpdate\fR\|(3) and \fBEVP_DigestFinal\fR\|(3) (and other related functions). +.PP +All \*(L"functions\*(R" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays via +\&\s-1\fBOSSL_ALGORITHM\s0\fR\|(3) arrays that are returned by the provider's +\&\fBprovider_query_operation()\fR function +(see \*(L"Provider Functions\*(R" in \fBprovider\-base\fR\|(7)). +.PP +All these \*(L"functions\*(R" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from an \s-1\fBOSSL_DISPATCH\s0\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the \*(L"function\*(R" \fBOSSL_FUNC_digest_newctx()\fR has these: +.PP +.Vb 3 +\& typedef void *(OSSL_FUNC_digest_newctx_fn)(void *provctx); +\& static ossl_inline OSSL_FUNC_digest_newctx_fn +\& OSSL_FUNC_digest_newctx(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 3 +\& OSSL_FUNC_digest_newctx OSSL_FUNC_DIGEST_NEWCTX +\& OSSL_FUNC_digest_freectx OSSL_FUNC_DIGEST_FREECTX +\& OSSL_FUNC_digest_dupctx OSSL_FUNC_DIGEST_DUPCTX +\& +\& OSSL_FUNC_digest_init OSSL_FUNC_DIGEST_INIT +\& OSSL_FUNC_digest_update OSSL_FUNC_DIGEST_UPDATE +\& OSSL_FUNC_digest_final OSSL_FUNC_DIGEST_FINAL +\& OSSL_FUNC_digest_digest OSSL_FUNC_DIGEST_DIGEST +\& +\& OSSL_FUNC_digest_get_params OSSL_FUNC_DIGEST_GET_PARAMS +\& OSSL_FUNC_digest_get_ctx_params OSSL_FUNC_DIGEST_GET_CTX_PARAMS +\& OSSL_FUNC_digest_set_ctx_params OSSL_FUNC_DIGEST_SET_CTX_PARAMS +\& +\& OSSL_FUNC_digest_gettable_params OSSL_FUNC_DIGEST_GETTABLE_PARAMS +\& OSSL_FUNC_digest_gettable_ctx_params OSSL_FUNC_DIGEST_GETTABLE_CTX_PARAMS +\& OSSL_FUNC_digest_settable_ctx_params OSSL_FUNC_DIGEST_SETTABLE_CTX_PARAMS +.Ve +.PP +A digest algorithm implementation may not implement all of these functions. +In order to be usable all or none of OSSL_FUNC_digest_newctx, OSSL_FUNC_digest_freectx, +OSSL_FUNC_digest_init, OSSL_FUNC_digest_update and OSSL_FUNC_digest_final should be implemented. +All other functions are optional. +.SS "Context Management Functions" +.IX Subsection "Context Management Functions" +\&\fBOSSL_FUNC_digest_newctx()\fR should create and return a pointer to a provider side +structure for holding context information during a digest operation. +A pointer to this context will be passed back in a number of the other digest +operation function calls. +The parameter \fIprovctx\fR is the provider context generated during provider +initialisation (see \fBprovider\fR\|(7)). +.PP +\&\fBOSSL_FUNC_digest_freectx()\fR is passed a pointer to the provider side digest context in +the \fIdctx\fR parameter. +This function should free any resources associated with that context. +.PP +\&\fBOSSL_FUNC_digest_dupctx()\fR should duplicate the provider side digest context in the +\&\fIdctx\fR parameter and return the duplicate copy. +.SS "Digest Generation Functions" +.IX Subsection "Digest Generation Functions" +\&\fBOSSL_FUNC_digest_init()\fR initialises a digest operation given a newly created +provider side digest context in the \fIdctx\fR parameter. +The \fIparams\fR, if not \s-1NULL,\s0 should be set on the context in a manner similar to +using \fBOSSL_FUNC_digest_set_ctx_params()\fR. +.PP +\&\fBOSSL_FUNC_digest_update()\fR is called to supply data to be digested as part of a +previously initialised digest operation. +The \fIdctx\fR parameter contains a pointer to a previously initialised provider +side context. +\&\fBOSSL_FUNC_digest_update()\fR should digest \fIinl\fR bytes of data at the location pointed to +by \fIin\fR. +\&\fBOSSL_FUNC_digest_update()\fR may be called multiple times for a single digest operation. +.PP +\&\fBOSSL_FUNC_digest_final()\fR generates a digest started through previous \fBOSSL_FUNC_digest_init()\fR +and \fBOSSL_FUNC_digest_update()\fR calls. +The \fIdctx\fR parameter contains a pointer to the provider side context. +The digest should be written to \fI*out\fR and the length of the digest to +\&\fI*outl\fR. +The digest should not exceed \fIoutsz\fR bytes. +.PP +\&\fBOSSL_FUNC_digest_digest()\fR is a \*(L"oneshot\*(R" digest function. +No provider side digest context is used. +Instead the provider context that was created during provider initialisation is +passed in the \fIprovctx\fR parameter (see \fBprovider\fR\|(7)). +\&\fIinl\fR bytes at \fIin\fR should be digested and the result should be stored at +\&\fIout\fR. The length of the digest should be stored in \fI*outl\fR which should not +exceed \fIoutsz\fR bytes. +.SS "Digest Parameters" +.IX Subsection "Digest Parameters" +See \s-1\fBOSSL_PARAM\s0\fR\|(3) for further details on the parameters structure used by +these functions. +.PP +\&\fBOSSL_FUNC_digest_get_params()\fR gets details of the algorithm implementation +and stores them in \fIparams\fR. +.PP +\&\fBOSSL_FUNC_digest_set_ctx_params()\fR sets digest operation parameters for the +provider side digest context \fIdctx\fR to \fIparams\fR. +Any parameter settings are additional to any that were previously set. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_digest_get_ctx_params()\fR gets digest operation details details from +the given provider side digest context \fIdctx\fR and stores them in \fIparams\fR. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_digest_gettable_params()\fR returns a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) array +containing descriptors of the parameters that \fBOSSL_FUNC_digest_get_params()\fR +can handle. +.PP +\&\fBOSSL_FUNC_digest_gettable_ctx_params()\fR and +\&\fBOSSL_FUNC_digest_settable_ctx_params()\fR both return constant +\&\s-1\fBOSSL_PARAM\s0\fR\|(3) arrays as descriptors of the parameters that +\&\fBOSSL_FUNC_digest_get_ctx_params()\fR and \fBOSSL_FUNC_digest_set_ctx_params()\fR +can handle, respectively. The array is based on the current state of +the provider side context if \fIdctx\fR is not \s-1NULL\s0 and on the provider +side algorithm \fIprovctx\fR otherwise. +.PP +Parameters currently recognised by built-in digests with this function +are as follows. Not all parameters are relevant to, or are understood +by all digests: +.ie n .IP """blocksize"" (\fB\s-1OSSL_DIGEST_PARAM_BLOCK_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``blocksize'' (\fB\s-1OSSL_DIGEST_PARAM_BLOCK_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "blocksize (OSSL_DIGEST_PARAM_BLOCK_SIZE) <unsigned integer>" +The digest block size. +The length of the \*(L"blocksize\*(R" parameter should not exceed that of a \fBsize_t\fR. +.ie n .IP """size"" (\fB\s-1OSSL_DIGEST_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``size'' (\fB\s-1OSSL_DIGEST_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "size (OSSL_DIGEST_PARAM_SIZE) <unsigned integer>" +The digest output size. +The length of the \*(L"size\*(R" parameter should not exceed that of a \fBsize_t\fR. +.ie n .IP """flags"" (\fB\s-1OSSL_DIGEST_PARAM_FLAGS\s0\fR) <unsigned integer>" 4 +.el .IP "``flags'' (\fB\s-1OSSL_DIGEST_PARAM_FLAGS\s0\fR) <unsigned integer>" 4 +.IX Item "flags (OSSL_DIGEST_PARAM_FLAGS) <unsigned integer>" +Diverse flags that describe exceptional behaviour for the digest: +.RS 4 +.IP "\fB\s-1EVP_MD_FLAG_ONESHOT\s0\fR" 4 +.IX Item "EVP_MD_FLAG_ONESHOT" +This digest method can only handle one block of input. +.IP "\fB\s-1EVP_MD_FLAG_XOF\s0\fR" 4 +.IX Item "EVP_MD_FLAG_XOF" +This digest method is an extensible-output function (\s-1XOF\s0) and supports +setting the \fB\s-1OSSL_DIGEST_PARAM_XOFLEN\s0\fR parameter. +.IP "\fB\s-1EVP_MD_FLAG_DIGALGID_NULL\s0\fR" 4 +.IX Item "EVP_MD_FLAG_DIGALGID_NULL" +When setting up a DigestAlgorithmIdentifier, this flag will have the +parameter set to \s-1NULL\s0 by default. Use this for PKCS#1. \fINote: if +combined with \s-1EVP_MD_FLAG_DIGALGID_ABSENT,\s0 the latter will override.\fR +.IP "\fB\s-1EVP_MD_FLAG_DIGALGID_ABSENT\s0\fR" 4 +.IX Item "EVP_MD_FLAG_DIGALGID_ABSENT" +When setting up a DigestAlgorithmIdentifier, this flag will have the +parameter be left absent by default. \fINote: if combined with +\&\s-1EVP_MD_FLAG_DIGALGID_NULL,\s0 the latter will be overridden.\fR +.IP "\fB\s-1EVP_MD_FLAG_DIGALGID_CUSTOM\s0\fR" 4 +.IX Item "EVP_MD_FLAG_DIGALGID_CUSTOM" +Custom DigestAlgorithmIdentifier handling via ctrl, with +\&\fB\s-1EVP_MD_FLAG_DIGALGID_ABSENT\s0\fR as default. \fINote: if combined with +\&\s-1EVP_MD_FLAG_DIGALGID_NULL,\s0 the latter will be overridden.\fR +Currently unused. +.RE +.RS 4 +.Sp +The length of the \*(L"flags\*(R" parameter should equal that of an +\&\fBunsigned long int\fR. +.RE +.SS "Digest Context Parameters" +.IX Subsection "Digest Context Parameters" +\&\fBOSSL_FUNC_digest_set_ctx_params()\fR sets digest parameters associated with the +given provider side digest context \fIdctx\fR to \fIparams\fR. +Any parameter settings are additional to any that were previously set. +See \s-1\fBOSSL_PARAM\s0\fR\|(3) for further details on the parameters structure. +.PP +\&\fBOSSL_FUNC_digest_get_ctx_params()\fR gets details of currently set parameters +values associated with the give provider side digest context \fIdctx\fR +and stores them in \fIparams\fR. +See \s-1\fBOSSL_PARAM\s0\fR\|(3) for further details on the parameters structure. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_digest_newctx()\fR and \fBOSSL_FUNC_digest_dupctx()\fR should return the newly created +provider side digest context, or \s-1NULL\s0 on failure. +.PP +\&\fBOSSL_FUNC_digest_init()\fR, \fBOSSL_FUNC_digest_update()\fR, \fBOSSL_FUNC_digest_final()\fR, \fBOSSL_FUNC_digest_digest()\fR, +\&\fBOSSL_FUNC_digest_set_params()\fR and \fBOSSL_FUNC_digest_get_params()\fR should return 1 for success or +0 on error. +.PP +\&\fBOSSL_FUNC_digest_size()\fR should return the digest size. +.PP +\&\fBOSSL_FUNC_digest_block_size()\fR should return the block size of the underlying digest +algorithm. +.SH "BUGS" +.IX Header "BUGS" +The \fBEVP_Q_digest()\fR, \fBEVP_Digest()\fR and \fBEVP_DigestFinal_ex()\fR \s-1API\s0 calls do not +expect the digest size to be larger than \s-1EVP_MAX_MD_SIZE.\s0 Any algorithm which +produces larger digests is unusable with those \s-1API\s0 calls. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), \s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7), +\&\fBOSSL_PROVIDER\-legacy\fR\|(7), +\&\fBEVP_MD\-common\fR\|(7), \s-1\fBEVP_MD\-BLAKE2\s0\fR\|(7), \s-1\fBEVP_MD\-MD2\s0\fR\|(7), +\&\s-1\fBEVP_MD\-MD4\s0\fR\|(7), \s-1\fBEVP_MD\-MD5\s0\fR\|(7), \s-1\fBEVP_MD\-MD5\-SHA1\s0\fR\|(7), +\&\s-1\fBEVP_MD\-MDC2\s0\fR\|(7), \s-1\fBEVP_MD\-RIPEMD160\s0\fR\|(7), \s-1\fBEVP_MD\-SHA1\s0\fR\|(7), +\&\s-1\fBEVP_MD\-SHA2\s0\fR\|(7), \s-1\fBEVP_MD\-SHA3\s0\fR\|(7), \s-1\fBEVP_MD\-SHAKE\s0\fR\|(7), +\&\s-1\fBEVP_MD\-SM3\s0\fR\|(7), \s-1\fBEVP_MD\-WHIRLPOOL\s0\fR\|(7), +\&\s-1\fBEVP_MD\-NULL\s0\fR\|(7), +\&\fBlife_cycle\-digest\fR\|(7), \fBEVP_DigestInit\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +The provider \s-1DIGEST\s0 interface was introduced in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2019\-2023 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>. diff --git a/secure/lib/libcrypto/man/man7/provider-encoder.7 b/secure/lib/libcrypto/man/man7/provider-encoder.7 new file mode 100644 index 000000000000..76d00e0ad3e9 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/provider-encoder.7 @@ -0,0 +1,428 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "PROVIDER-ENCODER 7ossl" +.TH PROVIDER-ENCODER 7ossl "2023-09-19" "3.0.11" "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" +provider\-encoder \- The OSSL_ENCODER library <\-> provider functions +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/core_dispatch.h> +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Encoder parameter accessor and descriptor */ +\& const OSSL_PARAM *OSSL_FUNC_encoder_gettable_params(void *provctx); +\& int OSSL_FUNC_encoder_get_params(OSSL_PARAM params[]); +\& +\& /* Functions to construct / destruct / manipulate the encoder context */ +\& void *OSSL_FUNC_encoder_newctx(void *provctx); +\& void OSSL_FUNC_encoder_freectx(void *ctx); +\& int OSSL_FUNC_encoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_encoder_settable_ctx_params(void *provctx); +\& +\& /* Functions to check selection support */ +\& int OSSL_FUNC_encoder_does_selection(void *provctx, int selection); +\& +\& /* Functions to encode object data */ +\& int OSSL_FUNC_encoder_encode(void *ctx, OSSL_CORE_BIO *out, +\& const void *obj_raw, +\& const OSSL_PARAM obj_abstract[], +\& int selection, +\& OSSL_PASSPHRASE_CALLBACK *cb, +\& void *cbarg); +\& +\& /* Functions to import and free a temporary object to be encoded */ +\& void *OSSL_FUNC_encoder_import_object(void *ctx, int selection, +\& const OSSL_PARAM params[]); +\& void OSSL_FUNC_encoder_free_object(void *obj); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fIWe use the wide term \*(L"encode\*(R" in this manual. This includes but is +not limited to serialization.\fR +.PP +The \s-1ENCODER\s0 operation is a generic method to encode a provider-native +object (\fIobj_raw\fR) or an object abstraction (\fIobject_abstract\fR, see +\&\fBprovider\-object\fR\|(7)) into an encoded form, and write the result to +the given \s-1OSSL_CORE_BIO.\s0 If the caller wants to get the encoded +stream to memory, it should provide a \fBBIO_s_mem\fR\|(3) \fB\s-1BIO\s0\fR. +.PP +The encoder doesn't need to know more about the \fB\s-1OSSL_CORE_BIO\s0\fR +pointer than being able to pass it to the appropriate \s-1BIO\s0 upcalls (see +\&\*(L"Core functions\*(R" in \fBprovider\-base\fR\|(7)). +.PP +The \s-1ENCODER\s0 implementation may be part of a chain, where data is +passed from one to the next. For example, there may be an +implementation to encode an object to \s-1DER\s0 (that object is assumed to +be provider-native and thereby passed via \fIobj_raw\fR), and another one +that encodes \s-1DER\s0 to \s-1PEM\s0 (that one would receive the \s-1DER\s0 encoding via +\&\fIobj_abstract\fR). +.PP +The encoding using the \s-1\fBOSSL_PARAM\s0\fR\|(3) array form allows a +encoder to be used for data that's been exported from another +provider, and thereby allow them to exist independently of each +other. +.PP +The encoding using a provider side object can only be safely used +with provider data coming from the same provider, for example keys +with the \s-1KEYMGMT\s0 provider. +.PP +All \*(L"functions\*(R" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays via +\&\s-1\fBOSSL_ALGORITHM\s0\fR\|(3) arrays that are returned by the provider's +\&\fBprovider_query_operation()\fR function +(see \*(L"Provider Functions\*(R" in \fBprovider\-base\fR\|(7)). +.PP +All these \*(L"functions\*(R" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from an \s-1\fBOSSL_DISPATCH\s0\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the \*(L"function\*(R" \fBOSSL_FUNC_encoder_encode()\fR has these: +.PP +.Vb 8 +\& typedef int +\& (OSSL_FUNC_encoder_encode_fn)(void *ctx, OSSL_CORE_BIO *out, +\& const void *obj_raw, +\& const OSSL_PARAM obj_abstract[], +\& int selection, +\& OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg); +\& static ossl_inline OSSL_FUNC_encoder_encode_fn +\& OSSL_FUNC_encoder_encode(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 2 +\& OSSL_FUNC_encoder_get_params OSSL_FUNC_ENCODER_GET_PARAMS +\& OSSL_FUNC_encoder_gettable_params OSSL_FUNC_ENCODER_GETTABLE_PARAMS +\& +\& OSSL_FUNC_encoder_newctx OSSL_FUNC_ENCODER_NEWCTX +\& OSSL_FUNC_encoder_freectx OSSL_FUNC_ENCODER_FREECTX +\& OSSL_FUNC_encoder_set_ctx_params OSSL_FUNC_ENCODER_SET_CTX_PARAMS +\& OSSL_FUNC_encoder_settable_ctx_params OSSL_FUNC_ENCODER_SETTABLE_CTX_PARAMS +\& +\& OSSL_FUNC_encoder_does_selection OSSL_FUNC_ENCODER_DOES_SELECTION +\& +\& OSSL_FUNC_encoder_encode OSSL_FUNC_ENCODER_ENCODE +\& +\& OSSL_FUNC_encoder_import_object OSSL_FUNC_ENCODER_IMPORT_OBJECT +\& OSSL_FUNC_encoder_free_object OSSL_FUNC_ENCODER_FREE_OBJECT +.Ve +.SS "Names and properties" +.IX Subsection "Names and properties" +The name of an implementation should match the type of object it handles. +For example, an implementation that encodes an \s-1RSA\s0 key should be named \*(L"\s-1RSA\*(R".\s0 +Likewise, an implementation that further encodes \s-1DER\s0 should be named \*(L"\s-1DER\*(R".\s0 +.PP +Properties can be used to further specify details about an implementation: +.IP "output" 4 +.IX Item "output" +This property is used to specify what type of output the implementation +produces. +.Sp +This property is \fImandatory\fR. +.Sp +OpenSSL providers recognize the following output types: +.RS 4 +.IP "text" 4 +.IX Item "text" +An implementation with that output type outputs human readable text, making +that implementation suitable for \f(CW\*(C`\-text\*(C'\fR output in diverse \fBopenssl\fR\|(1) +commands. +.IP "pem" 4 +.IX Item "pem" +An implementation with that output type outputs \s-1PEM\s0 formatted data. +.IP "der" 4 +.IX Item "der" +An implementation with that output type outputs \s-1DER\s0 formatted data. +.IP "msblob" 4 +.IX Item "msblob" +An implementation with that output type outputs \s-1MSBLOB\s0 formatted data. +.IP "pvk" 4 +.IX Item "pvk" +An implementation with that output type outputs \s-1PVK\s0 formatted data. +.RE +.RS 4 +.RE +.IP "structure" 4 +.IX Item "structure" +This property is used to specify the structure that is used for the encoded +object. An example could be \f(CW\*(C`pkcs8\*(C'\fR, to specify explicitly that an object +(presumably an asymmetric key pair, in this case) will be wrapped in a +PKCS#8 structure as part of the encoding. +.Sp +This property is \fIoptional\fR. +.PP +The possible values of both these properties is open ended. A provider may +very well specify output types and structures that libcrypto doesn't know +anything about. +.SS "Subset selections" +.IX Subsection "Subset selections" +Sometimes, an object has more than one subset of data that is interesting to +treat separately or together. It's possible to specify what subsets are to +be encoded, with a set of bits \fIselection\fR that are passed in an \fBint\fR. +.PP +This set of bits depend entirely on what kind of provider-side object is +passed. For example, those bits are assumed to be the same as those used +with \fBprovider\-keymgmt\fR\|(7) (see \*(L"Key Objects\*(R" in \fBprovider\-keymgmt\fR\|(7)) when +the object is an asymmetric keypair. +.PP +\&\s-1ENCODER\s0 implementations are free to regard the \fIselection\fR as a set of +hints, but must do so with care. In the end, the output must make sense, +and if there's a corresponding decoder, the resulting decoded object must +match the original object that was encoded. +.PP +\&\fBOSSL_FUNC_encoder_does_selection()\fR should tell if a particular implementation +supports any of the combinations given by \fIselection\fR. +.SS "Context functions" +.IX Subsection "Context functions" +\&\fBOSSL_FUNC_encoder_newctx()\fR returns a context to be used with the rest of +the functions. +.PP +\&\fBOSSL_FUNC_encoder_freectx()\fR frees the given \fIctx\fR, if it was created by +\&\fBOSSL_FUNC_encoder_newctx()\fR. +.PP +\&\fBOSSL_FUNC_encoder_set_ctx_params()\fR sets context data according to parameters +from \fIparams\fR that it recognises. Unrecognised parameters should be +ignored. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_encoder_settable_ctx_params()\fR returns a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) +array describing the parameters that \fBOSSL_FUNC_encoder_set_ctx_params()\fR +can handle. +.PP +See \s-1\fBOSSL_PARAM\s0\fR\|(3) for further details on the parameters structure used by +\&\fBOSSL_FUNC_encoder_set_ctx_params()\fR and \fBOSSL_FUNC_encoder_settable_ctx_params()\fR. +.SS "Import functions" +.IX Subsection "Import functions" +A provider-native object may be associated with a foreign provider, and may +therefore be unsuitable for direct use with a given \s-1ENCODER\s0 implementation. +Provided that the foreign provider's implementation to handle the object has +a function to export that object in \s-1\fBOSSL_PARAM\s0\fR\|(3) array form, the \s-1ENCODER\s0 +implementation should be able to import that array and create a suitable +object to be passed to \fBOSSL_FUNC_encoder_encode()\fR's \fIobj_raw\fR. +.PP +\&\fBOSSL_FUNC_encoder_import_object()\fR should import the subset of \fIparams\fR +given with \fIselection\fR to create a provider-native object that can be +passed as \fIobj_raw\fR to \fBOSSL_FUNC_encoder_encode()\fR. +.PP +\&\fBOSSL_FUNC_encoder_free_object()\fR should free the object that was created with +\&\fBOSSL_FUNC_encoder_import_object()\fR. +.SS "Encoding functions" +.IX Subsection "Encoding functions" +\&\fBOSSL_FUNC_encoder_encode()\fR should take a provider-native object (in +\&\fIobj_raw\fR) or an object abstraction (in \fIobj_abstract\fR), and should output +the object in encoded form to the \fB\s-1OSSL_CORE_BIO\s0\fR. The \fIselection\fR bits, +if relevant, should determine in greater detail what will be output. +The encoding functions also take an \s-1\fBOSSL_PASSPHRASE_CALLBACK\s0\fR\|(3) function +pointer along with a pointer to application data \fIcbarg\fR, which should be +used when a pass phrase prompt is needed. +.SS "Encoder operation parameters" +.IX Subsection "Encoder operation parameters" +Operation parameters currently recognised by built-in encoders are as +follows: +.ie n .IP """cipher"" (\fB\s-1OSSL_ENCODER_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``cipher'' (\fB\s-1OSSL_ENCODER_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "cipher (OSSL_ENCODER_PARAM_CIPHER) <UTF8 string>" +The name of the encryption cipher to be used when generating encrypted +encoding. This is used when encoding private keys, as well as +other objects that need protection. +.Sp +If this name is invalid for the encoding implementation, the +implementation should refuse to perform the encoding, i.e. +\&\fBOSSL_FUNC_encoder_encode_data()\fR and \fBOSSL_FUNC_encoder_encode_object()\fR +should return an error. +.ie n .IP """properties"" (\fB\s-1OSSL_ENCODER_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_ENCODER_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_ENCODER_PARAM_PROPERTIES) <UTF8 string>" +The properties to be queried when trying to fetch the algorithm given +with the \*(L"cipher\*(R" parameter. +This must be given together with the \*(L"cipher\*(R" parameter to be +considered valid. +.Sp +The encoding implementation isn't obligated to use this value. +However, it is recommended that implementations that do not handle +property strings return an error on receiving this parameter unless +its value \s-1NULL\s0 or the empty string. +.ie n .IP """save-parameters"" (\fB\s-1OSSL_ENCODER_PARAM_SAVE_PARAMETERS\s0\fR) <integer>" 4 +.el .IP "``save-parameters'' (\fB\s-1OSSL_ENCODER_PARAM_SAVE_PARAMETERS\s0\fR) <integer>" 4 +.IX Item "save-parameters (OSSL_ENCODER_PARAM_SAVE_PARAMETERS) <integer>" +If set to 0 disables saving of key domain parameters. Default is 1. +It currently has an effect only on \s-1DSA\s0 keys. +.PP +Parameters currently recognised by the built-in pass phrase callback: +.ie n .IP """info"" (\fB\s-1OSSL_PASSPHRASE_PARAM_INFO\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``info'' (\fB\s-1OSSL_PASSPHRASE_PARAM_INFO\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "info (OSSL_PASSPHRASE_PARAM_INFO) <UTF8 string>" +A string of information that will become part of the pass phrase +prompt. This could be used to give the user information on what kind +of object it's being prompted for. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_encoder_newctx()\fR returns a pointer to a context, or \s-1NULL\s0 on +failure. +.PP +\&\fBOSSL_FUNC_encoder_set_ctx_params()\fR returns 1, unless a recognised +parameter was invalid or caused an error, for which 0 is returned. +.PP +\&\fBOSSL_FUNC_encoder_settable_ctx_params()\fR returns a pointer to an array of +constant \s-1\fBOSSL_PARAM\s0\fR\|(3) elements. +.PP +\&\fBOSSL_FUNC_encoder_does_selection()\fR returns 1 if the encoder implementation +supports any of the \fIselection\fR bits, otherwise 0. +.PP +\&\fBOSSL_FUNC_encoder_encode()\fR returns 1 on success, or 0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The \s-1ENCODER\s0 interface was introduced in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2019\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/provider-kdf.7 b/secure/lib/libcrypto/man/man7/provider-kdf.7 new file mode 100644 index 000000000000..8a56362b13eb --- /dev/null +++ b/secure/lib/libcrypto/man/man7/provider-kdf.7 @@ -0,0 +1,480 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "PROVIDER-KDF 7ossl" +.TH PROVIDER-KDF 7ossl "2023-09-19" "3.0.11" "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" +provider\-kdf \- The KDF library <\-> provider functions +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 2 +\& #include <openssl/core_dispatch.h> +\& #include <openssl/core_names.h> +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Context management */ +\& void *OSSL_FUNC_kdf_newctx(void *provctx); +\& void OSSL_FUNC_kdf_freectx(void *kctx); +\& void *OSSL_FUNC_kdf_dupctx(void *src); +\& +\& /* Encryption/decryption */ +\& int OSSL_FUNC_kdf_reset(void *kctx); +\& int OSSL_FUNC_kdf_derive(void *kctx, unsigned char *key, size_t keylen, +\& const OSSL_PARAM params[]); +\& +\& /* KDF parameter descriptors */ +\& const OSSL_PARAM *OSSL_FUNC_kdf_gettable_params(void *provctx); +\& const OSSL_PARAM *OSSL_FUNC_kdf_gettable_ctx_params(void *kcxt, void *provctx); +\& const OSSL_PARAM *OSSL_FUNC_kdf_settable_ctx_params(void *kcxt, void *provctx); +\& +\& /* KDF parameters */ +\& int OSSL_FUNC_kdf_get_params(OSSL_PARAM params[]); +\& int OSSL_FUNC_kdf_get_ctx_params(void *kctx, OSSL_PARAM params[]); +\& int OSSL_FUNC_kdf_set_ctx_params(void *kctx, const OSSL_PARAM params[]); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7) +for further information. +.PP +The \s-1KDF\s0 operation enables providers to implement \s-1KDF\s0 algorithms and make +them available to applications via the \s-1API\s0 functions \fBEVP_KDF_CTX_reset\fR\|(3), +and \fBEVP_KDF_derive\fR\|(3). +.PP +All \*(L"functions\*(R" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays via +\&\s-1\fBOSSL_ALGORITHM\s0\fR\|(3) arrays that are returned by the provider's +\&\fBprovider_query_operation()\fR function +(see \*(L"Provider Functions\*(R" in \fBprovider\-base\fR\|(7)). +.PP +All these \*(L"functions\*(R" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from an \s-1\fBOSSL_DISPATCH\s0\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the \*(L"function\*(R" \fBOSSL_FUNC_kdf_newctx()\fR has these: +.PP +.Vb 3 +\& typedef void *(OSSL_FUNC_kdf_newctx_fn)(void *provctx); +\& static ossl_inline OSSL_FUNC_kdf_newctx_fn +\& OSSL_FUNC_kdf_newctx(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\s-1\fBOSSL_DISPATCH\s0\fR\|(3) array entries are identified by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 3 +\& OSSL_FUNC_kdf_newctx OSSL_FUNC_KDF_NEWCTX +\& OSSL_FUNC_kdf_freectx OSSL_FUNC_KDF_FREECTX +\& OSSL_FUNC_kdf_dupctx OSSL_FUNC_KDF_DUPCTX +\& +\& OSSL_FUNC_kdf_reset OSSL_FUNC_KDF_RESET +\& OSSL_FUNC_kdf_derive OSSL_FUNC_KDF_DERIVE +\& +\& OSSL_FUNC_kdf_get_params OSSL_FUNC_KDF_GET_PARAMS +\& OSSL_FUNC_kdf_get_ctx_params OSSL_FUNC_KDF_GET_CTX_PARAMS +\& OSSL_FUNC_kdf_set_ctx_params OSSL_FUNC_KDF_SET_CTX_PARAMS +\& +\& OSSL_FUNC_kdf_gettable_params OSSL_FUNC_KDF_GETTABLE_PARAMS +\& OSSL_FUNC_kdf_gettable_ctx_params OSSL_FUNC_KDF_GETTABLE_CTX_PARAMS +\& OSSL_FUNC_kdf_settable_ctx_params OSSL_FUNC_KDF_SETTABLE_CTX_PARAMS +.Ve +.PP +A \s-1KDF\s0 algorithm implementation may not implement all of these functions. +In order to be a consistent set of functions, at least the following functions +must be implemented: \fBOSSL_FUNC_kdf_newctx()\fR, \fBOSSL_FUNC_kdf_freectx()\fR, +\&\fBOSSL_FUNC_kdf_set_ctx_params()\fR, \fBOSSL_FUNC_kdf_derive()\fR. +All other functions are optional. +.SS "Context Management Functions" +.IX Subsection "Context Management Functions" +\&\fBOSSL_FUNC_kdf_newctx()\fR should create and return a pointer to a provider side +structure for holding context information during a \s-1KDF\s0 operation. +A pointer to this context will be passed back in a number of the other \s-1KDF\s0 +operation function calls. +The parameter \fIprovctx\fR is the provider context generated during provider +initialisation (see \fBprovider\fR\|(7)). +.PP +\&\fBOSSL_FUNC_kdf_freectx()\fR is passed a pointer to the provider side \s-1KDF\s0 context in +the \fIkctx\fR parameter. +If it receives \s-1NULL\s0 as \fIkctx\fR value, it should not do anything other than +return. +This function should free any resources associated with that context. +.PP +\&\fBOSSL_FUNC_kdf_dupctx()\fR should duplicate the provider side \s-1KDF\s0 context in the +\&\fIkctx\fR parameter and return the duplicate copy. +.SS "Encryption/Decryption Functions" +.IX Subsection "Encryption/Decryption Functions" +\&\fBOSSL_FUNC_kdf_reset()\fR initialises a \s-1KDF\s0 operation given a provider +side \s-1KDF\s0 context in the \fIkctx\fR parameter. +.PP +\&\fBOSSL_FUNC_kdf_derive()\fR performs the \s-1KDF\s0 operation after processing the +\&\fIparams\fR as per \fBOSSL_FUNC_kdf_set_ctx_params()\fR. +The \fIkctx\fR parameter contains a pointer to the provider side context. +The resulting key of the desired \fIkeylen\fR should be written to \fIkey\fR. +If the algorithm does not support the requested \fIkeylen\fR the function must +return error. +.SS "\s-1KDF\s0 Parameters" +.IX Subsection "KDF Parameters" +See \s-1\fBOSSL_PARAM\s0\fR\|(3) for further details on the parameters structure used by +these functions. +.PP +\&\fBOSSL_FUNC_kdf_get_params()\fR gets details of parameter values associated with the +provider algorithm and stores them in \fIparams\fR. +.PP +\&\fBOSSL_FUNC_kdf_set_ctx_params()\fR sets \s-1KDF\s0 parameters associated with the given +provider side \s-1KDF\s0 context \fIkctx\fR to \fIparams\fR. +Any parameter settings are additional to any that were previously set. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_kdf_get_ctx_params()\fR retrieves gettable parameter values associated +with the given provider side \s-1KDF\s0 context \fIkctx\fR and stores them in \fIparams\fR. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_kdf_gettable_params()\fR, \fBOSSL_FUNC_kdf_gettable_ctx_params()\fR, +and \fBOSSL_FUNC_kdf_settable_ctx_params()\fR all return constant \s-1\fBOSSL_PARAM\s0\fR\|(3) +arrays as descriptors of the parameters that \fBOSSL_FUNC_kdf_get_params()\fR, +\&\fBOSSL_FUNC_kdf_get_ctx_params()\fR, and \fBOSSL_FUNC_kdf_set_ctx_params()\fR +can handle, respectively. \fBOSSL_FUNC_kdf_gettable_ctx_params()\fR and +\&\fBOSSL_FUNC_kdf_settable_ctx_params()\fR will return the parameters associated +with the provider side context \fIkctx\fR in its current state if it is +not \s-1NULL.\s0 Otherwise, they return the parameters associated with the +provider side algorithm \fIprovctx\fR. +.PP +Parameters currently recognised by built-in KDFs are as follows. Not all +parameters are relevant to, or are understood by all KDFs: +.ie n .IP """size"" (\fB\s-1OSSL_KDF_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``size'' (\fB\s-1OSSL_KDF_PARAM_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "size (OSSL_KDF_PARAM_SIZE) <unsigned integer>" +Gets the output size from the associated \s-1KDF\s0 ctx. +If the algorithm produces a variable amount of output, \s-1SIZE_MAX\s0 should be +returned. +If the input parameters required to calculate the fixed output size have not yet +been supplied, 0 should be returned indicating an error. +.ie n .IP """key"" (\fB\s-1OSSL_KDF_PARAM_KEY\s0\fR) <octet string>" 4 +.el .IP "``key'' (\fB\s-1OSSL_KDF_PARAM_KEY\s0\fR) <octet string>" 4 +.IX Item "key (OSSL_KDF_PARAM_KEY) <octet string>" +Sets the key in the associated \s-1KDF\s0 ctx. +.ie n .IP """secret"" (\fB\s-1OSSL_KDF_PARAM_SECRET\s0\fR) <octet string>" 4 +.el .IP "``secret'' (\fB\s-1OSSL_KDF_PARAM_SECRET\s0\fR) <octet string>" 4 +.IX Item "secret (OSSL_KDF_PARAM_SECRET) <octet string>" +Sets the secret in the associated \s-1KDF\s0 ctx. +.ie n .IP """pass"" (\fB\s-1OSSL_KDF_PARAM_PASSWORD\s0\fR) <octet string>" 4 +.el .IP "``pass'' (\fB\s-1OSSL_KDF_PARAM_PASSWORD\s0\fR) <octet string>" 4 +.IX Item "pass (OSSL_KDF_PARAM_PASSWORD) <octet string>" +Sets the password in the associated \s-1KDF\s0 ctx. +.ie n .IP """cipher"" (\fB\s-1OSSL_KDF_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``cipher'' (\fB\s-1OSSL_KDF_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "cipher (OSSL_KDF_PARAM_CIPHER) <UTF8 string>" +.PD 0 +.ie n .IP """digest"" (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_KDF_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_KDF_PARAM_DIGEST) <UTF8 string>" +.ie n .IP """mac"" (\fB\s-1OSSL_KDF_PARAM_MAC\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``mac'' (\fB\s-1OSSL_KDF_PARAM_MAC\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "mac (OSSL_KDF_PARAM_MAC) <UTF8 string>" +.PD +Sets the name of the underlying cipher, digest or \s-1MAC\s0 to be used. +It must name a suitable algorithm for the \s-1KDF\s0 that's being used. +.ie n .IP """maclen"" (\fB\s-1OSSL_KDF_PARAM_MAC_SIZE\s0\fR) <octet string>" 4 +.el .IP "``maclen'' (\fB\s-1OSSL_KDF_PARAM_MAC_SIZE\s0\fR) <octet string>" 4 +.IX Item "maclen (OSSL_KDF_PARAM_MAC_SIZE) <octet string>" +Sets the length of the \s-1MAC\s0 in the associated \s-1KDF\s0 ctx. +.ie n .IP """properties"" (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_KDF_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>" +Sets the properties to be queried when trying to fetch the underlying algorithm. +This must be given together with the algorithm naming parameter to be +considered valid. +.ie n .IP """iter"" (\fB\s-1OSSL_KDF_PARAM_ITER\s0\fR) <unsigned integer>" 4 +.el .IP "``iter'' (\fB\s-1OSSL_KDF_PARAM_ITER\s0\fR) <unsigned integer>" 4 +.IX Item "iter (OSSL_KDF_PARAM_ITER) <unsigned integer>" +Sets the number of iterations in the associated \s-1KDF\s0 ctx. +.ie n .IP """mode"" (\fB\s-1OSSL_KDF_PARAM_MODE\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``mode'' (\fB\s-1OSSL_KDF_PARAM_MODE\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "mode (OSSL_KDF_PARAM_MODE) <UTF8 string>" +Sets the mode in the associated \s-1KDF\s0 ctx. +.ie n .IP """pkcs5"" (\fB\s-1OSSL_KDF_PARAM_PKCS5\s0\fR) <integer>" 4 +.el .IP "``pkcs5'' (\fB\s-1OSSL_KDF_PARAM_PKCS5\s0\fR) <integer>" 4 +.IX Item "pkcs5 (OSSL_KDF_PARAM_PKCS5) <integer>" +Enables or disables the \s-1SP800\-132\s0 compliance checks. +A mode of 0 enables the compliance checks. +.Sp +The checks performed are: +.RS 4 +.IP "\- the iteration count is at least 1000." 4 +.IX Item "- the iteration count is at least 1000." +.PD 0 +.IP "\- the salt length is at least 128 bits." 4 +.IX Item "- the salt length is at least 128 bits." +.IP "\- the derived key length is at least 112 bits." 4 +.IX Item "- the derived key length is at least 112 bits." +.RE +.RS 4 +.RE +.ie n .IP """ukm"" (\fB\s-1OSSL_KDF_PARAM_UKM\s0\fR) <octet string>" 4 +.el .IP "``ukm'' (\fB\s-1OSSL_KDF_PARAM_UKM\s0\fR) <octet string>" 4 +.IX Item "ukm (OSSL_KDF_PARAM_UKM) <octet string>" +.PD +Sets an optional random string that is provided by the sender called +\&\*(L"partyAInfo\*(R". In \s-1CMS\s0 this is the user keying material. +.ie n .IP """cekalg"" (\fB\s-1OSSL_KDF_PARAM_CEK_ALG\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``cekalg'' (\fB\s-1OSSL_KDF_PARAM_CEK_ALG\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "cekalg (OSSL_KDF_PARAM_CEK_ALG) <UTF8 string>" +Sets the \s-1CEK\s0 wrapping algorithm name in the associated \s-1KDF\s0 ctx. +.ie n .IP """n"" (\fB\s-1OSSL_KDF_PARAM_SCRYPT_N\s0\fR) <unsigned integer>" 4 +.el .IP "``n'' (\fB\s-1OSSL_KDF_PARAM_SCRYPT_N\s0\fR) <unsigned integer>" 4 +.IX Item "n (OSSL_KDF_PARAM_SCRYPT_N) <unsigned integer>" +Sets the scrypt work factor parameter N in the associated \s-1KDF\s0 ctx. +.ie n .IP """r"" (\fB\s-1OSSL_KDF_PARAM_SCRYPT_R\s0\fR) <unsigned integer>" 4 +.el .IP "``r'' (\fB\s-1OSSL_KDF_PARAM_SCRYPT_R\s0\fR) <unsigned integer>" 4 +.IX Item "r (OSSL_KDF_PARAM_SCRYPT_R) <unsigned integer>" +Sets the scrypt work factor parameter r in the associated \s-1KDF\s0 ctx. +.ie n .IP """p"" (\fB\s-1OSSL_KDF_PARAM_SCRYPT_P\s0\fR) <unsigned integer>" 4 +.el .IP "``p'' (\fB\s-1OSSL_KDF_PARAM_SCRYPT_P\s0\fR) <unsigned integer>" 4 +.IX Item "p (OSSL_KDF_PARAM_SCRYPT_P) <unsigned integer>" +Sets the scrypt work factor parameter p in the associated \s-1KDF\s0 ctx. +.ie n .IP """maxmem_bytes"" (\fB\s-1OSSL_KDF_PARAM_SCRYPT_MAXMEM\s0\fR) <unsigned integer>" 4 +.el .IP "``maxmem_bytes'' (\fB\s-1OSSL_KDF_PARAM_SCRYPT_MAXMEM\s0\fR) <unsigned integer>" 4 +.IX Item "maxmem_bytes (OSSL_KDF_PARAM_SCRYPT_MAXMEM) <unsigned integer>" +Sets the scrypt work factor parameter maxmem in the associated \s-1KDF\s0 ctx. +.ie n .IP """prefix"" (\fB\s-1OSSL_KDF_PARAM_PREFIX\s0\fR) <octet string>" 4 +.el .IP "``prefix'' (\fB\s-1OSSL_KDF_PARAM_PREFIX\s0\fR) <octet string>" 4 +.IX Item "prefix (OSSL_KDF_PARAM_PREFIX) <octet string>" +Sets the prefix string using by the \s-1TLS 1.3\s0 version of \s-1HKDF\s0 in the +associated \s-1KDF\s0 ctx. +.ie n .IP """label"" (\fB\s-1OSSL_KDF_PARAM_LABEL\s0\fR) <octet string>" 4 +.el .IP "``label'' (\fB\s-1OSSL_KDF_PARAM_LABEL\s0\fR) <octet string>" 4 +.IX Item "label (OSSL_KDF_PARAM_LABEL) <octet string>" +Sets the label string using by the \s-1TLS 1.3\s0 version of \s-1HKDF\s0 in the +associated \s-1KDF\s0 ctx. +.ie n .IP """data"" (\fB\s-1OSSL_KDF_PARAM_DATA\s0\fR) <octet string>" 4 +.el .IP "``data'' (\fB\s-1OSSL_KDF_PARAM_DATA\s0\fR) <octet string>" 4 +.IX Item "data (OSSL_KDF_PARAM_DATA) <octet string>" +Sets the context string using by the \s-1TLS 1.3\s0 version of \s-1HKDF\s0 in the +associated \s-1KDF\s0 ctx. +.ie n .IP """info"" (\fB\s-1OSSL_KDF_PARAM_INFO\s0\fR) <octet string>" 4 +.el .IP "``info'' (\fB\s-1OSSL_KDF_PARAM_INFO\s0\fR) <octet string>" 4 +.IX Item "info (OSSL_KDF_PARAM_INFO) <octet string>" +Sets the optional shared info in the associated \s-1KDF\s0 ctx. +.ie n .IP """seed"" (\fB\s-1OSSL_KDF_PARAM_SEED\s0\fR) <octet string>" 4 +.el .IP "``seed'' (\fB\s-1OSSL_KDF_PARAM_SEED\s0\fR) <octet string>" 4 +.IX Item "seed (OSSL_KDF_PARAM_SEED) <octet string>" +Sets the \s-1IV\s0 in the associated \s-1KDF\s0 ctx. +.ie n .IP """xcghash"" (\fB\s-1OSSL_KDF_PARAM_SSHKDF_XCGHASH\s0\fR) <octet string>" 4 +.el .IP "``xcghash'' (\fB\s-1OSSL_KDF_PARAM_SSHKDF_XCGHASH\s0\fR) <octet string>" 4 +.IX Item "xcghash (OSSL_KDF_PARAM_SSHKDF_XCGHASH) <octet string>" +Sets the xcghash in the associated \s-1KDF\s0 ctx. +.ie n .IP """session_id"" (\fB\s-1OSSL_KDF_PARAM_SSHKDF_SESSION_ID\s0\fR) <octet string>" 4 +.el .IP "``session_id'' (\fB\s-1OSSL_KDF_PARAM_SSHKDF_SESSION_ID\s0\fR) <octet string>" 4 +.IX Item "session_id (OSSL_KDF_PARAM_SSHKDF_SESSION_ID) <octet string>" +Sets the session \s-1ID\s0 in the associated \s-1KDF\s0 ctx. +.ie n .IP """type"" (\fB\s-1OSSL_KDF_PARAM_SSHKDF_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``type'' (\fB\s-1OSSL_KDF_PARAM_SSHKDF_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "type (OSSL_KDF_PARAM_SSHKDF_TYPE) <UTF8 string>" +Sets the \s-1SSH KDF\s0 type parameter in the associated \s-1KDF\s0 ctx. +There are six supported types: +.RS 4 +.IP "\s-1EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV\s0" 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV" +The Initial \s-1IV\s0 from client to server. +A single char of value 65 (\s-1ASCII\s0 char 'A'). +.IP "\s-1EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI\s0" 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI" +The Initial \s-1IV\s0 from server to client +A single char of value 66 (\s-1ASCII\s0 char 'B'). +.IP "\s-1EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV\s0" 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV" +The Encryption Key from client to server +A single char of value 67 (\s-1ASCII\s0 char 'C'). +.IP "\s-1EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI\s0" 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI" +The Encryption Key from server to client +A single char of value 68 (\s-1ASCII\s0 char 'D'). +.IP "\s-1EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV\s0" 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV" +The Integrity Key from client to server +A single char of value 69 (\s-1ASCII\s0 char 'E'). +.IP "\s-1EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI\s0" 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI" +The Integrity Key from client to server +A single char of value 70 (\s-1ASCII\s0 char 'F'). +.RE +.RS 4 +.RE +.ie n .IP """constant"" (\fB\s-1OSSL_KDF_PARAM_CONSTANT\s0\fR) <octet string>" 4 +.el .IP "``constant'' (\fB\s-1OSSL_KDF_PARAM_CONSTANT\s0\fR) <octet string>" 4 +.IX Item "constant (OSSL_KDF_PARAM_CONSTANT) <octet string>" +Sets the constant value in the associated \s-1KDF\s0 ctx. +.ie n .IP """id"" (\fB\s-1OSSL_KDF_PARAM_PKCS12_ID\s0\fR) <integer>" 4 +.el .IP "``id'' (\fB\s-1OSSL_KDF_PARAM_PKCS12_ID\s0\fR) <integer>" 4 +.IX Item "id (OSSL_KDF_PARAM_PKCS12_ID) <integer>" +Sets the intended usage of the output bits in the associated \s-1KDF\s0 ctx. +It is defined as per \s-1RFC 7292\s0 section B.3. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_kdf_newctx()\fR and \fBOSSL_FUNC_kdf_dupctx()\fR should return the newly created +provider side \s-1KDF\s0 context, or \s-1NULL\s0 on failure. +.PP +\&\fBOSSL_FUNC_kdf_derive()\fR, \fBOSSL_FUNC_kdf_get_params()\fR, +\&\fBOSSL_FUNC_kdf_get_ctx_params()\fR and \fBOSSL_FUNC_kdf_set_ctx_params()\fR should return 1 for +success or 0 on error. +.PP +\&\fBOSSL_FUNC_kdf_gettable_params()\fR, \fBOSSL_FUNC_kdf_gettable_ctx_params()\fR and +\&\fBOSSL_FUNC_kdf_settable_ctx_params()\fR should return a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) +array, or \s-1NULL\s0 if none is offered. +.SH "NOTES" +.IX Header "NOTES" +The \s-1KDF\s0 life-cycle is described in \fBlife_cycle\-kdf\fR\|(7). Providers should +ensure that the various transitions listed there are supported. At some point +the \s-1EVP\s0 layer will begin enforcing the listed transitions. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), \fBlife_cycle\-kdf\fR\|(7), \s-1\fBEVP_KDF\s0\fR\|(3). +.SH "HISTORY" +.IX Header "HISTORY" +The provider \s-1KDF\s0 interface was introduced in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2023 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>. diff --git a/secure/lib/libcrypto/man/man7/provider-kem.7 b/secure/lib/libcrypto/man/man7/provider-kem.7 new file mode 100644 index 000000000000..2a93622f1508 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/provider-kem.7 @@ -0,0 +1,339 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "PROVIDER-KEM 7ossl" +.TH PROVIDER-KEM 7ossl "2023-09-19" "3.0.11" "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" +provider\-kem \- The kem library <\-> provider functions +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 2 +\& #include <openssl/core_dispatch.h> +\& #include <openssl/core_names.h> +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Context management */ +\& void *OSSL_FUNC_kem_newctx(void *provctx); +\& void OSSL_FUNC_kem_freectx(void *ctx); +\& void *OSSL_FUNC_kem_dupctx(void *ctx); +\& +\& /* Encapsulation */ +\& int OSSL_FUNC_kem_encapsulate_init(void *ctx, void *provkey, const char *name, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_kem_encapsulate(void *ctx, unsigned char *out, size_t *outlen, +\& unsigned char *secret, size_t *secretlen); +\& +\& /* Decapsulation */ +\& int OSSL_FUNC_kem_decapsulate_init(void *ctx, void *provkey, const char *name); +\& int OSSL_FUNC_kem_decapsulate(void *ctx, unsigned char *out, size_t *outlen, +\& const unsigned char *in, size_t inlen); +\& +\& /* KEM parameters */ +\& int OSSL_FUNC_kem_get_ctx_params(void *ctx, OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_kem_gettable_ctx_params(void *ctx, void *provctx); +\& int OSSL_FUNC_kem_set_ctx_params(void *ctx, const OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_kem_settable_ctx_params(void *ctx, void *provctx); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7) +for further information. +.PP +The asymmetric kem (\s-1OSSL_OP_KEM\s0) operation enables providers to +implement asymmetric kem algorithms and make them available to applications +via the \s-1API\s0 functions \fBEVP_PKEY_encapsulate\fR\|(3), +\&\fBEVP_PKEY_decapsulate\fR\|(3) and other related functions. +.PP +All \*(L"functions\*(R" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays via +\&\s-1\fBOSSL_ALGORITHM\s0\fR\|(3) arrays that are returned by the provider's +\&\fBprovider_query_operation()\fR function +(see \*(L"Provider Functions\*(R" in \fBprovider\-base\fR\|(7)). +.PP +All these \*(L"functions\*(R" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from an \s-1\fBOSSL_DISPATCH\s0\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the \*(L"function\*(R" \fBOSSL_FUNC_kem_newctx()\fR has these: +.PP +.Vb 3 +\& typedef void *(OSSL_FUNC_kem_newctx_fn)(void *provctx); +\& static ossl_inline OSSL_FUNC_kem_newctx_fn +\& OSSL_FUNC_kem_newctx(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 3 +\& OSSL_FUNC_kem_newctx OSSL_FUNC_KEM_NEWCTX +\& OSSL_FUNC_kem_freectx OSSL_FUNC_KEM_FREECTX +\& OSSL_FUNC_kem_dupctx OSSL_FUNC_KEM_DUPCTX +\& +\& OSSL_FUNC_kem_encapsulate_init OSSL_FUNC_KEM_ENCAPSULATE_INIT +\& OSSL_FUNC_kem_encapsulate OSSL_FUNC_KEM_ENCAPSULATE +\& +\& OSSL_FUNC_kem_decapsulate_init OSSL_FUNC_KEM_DECAPSULATE_INIT +\& OSSL_FUNC_kem_decapsulate OSSL_FUNC_KEM_DECAPSULATE +\& +\& OSSL_FUNC_kem_get_ctx_params OSSL_FUNC_KEM_GET_CTX_PARAMS +\& OSSL_FUNC_kem_gettable_ctx_params OSSL_FUNC_KEM_GETTABLE_CTX_PARAMS +\& OSSL_FUNC_kem_set_ctx_params OSSL_FUNC_KEM_SET_CTX_PARAMS +\& OSSL_FUNC_kem_settable_ctx_params OSSL_FUNC_KEM_SETTABLE_CTX_PARAMS +.Ve +.PP +An asymmetric kem algorithm implementation may not implement all of these +functions. +In order to be a consistent set of functions a provider must implement +OSSL_FUNC_kem_newctx and OSSL_FUNC_kem_freectx. +It must also implement both of OSSL_FUNC_kem_encapsulate_init and +OSSL_FUNC_kem_encapsulate, or both of OSSL_FUNC_kem_decapsulate_init and +OSSL_FUNC_kem_decapsulate. +OSSL_FUNC_kem_get_ctx_params is optional but if it is present then so must +OSSL_FUNC_kem_gettable_ctx_params. +Similarly, OSSL_FUNC_kem_set_ctx_params is optional but if it is present then +so must OSSL_FUNC_kem_settable_ctx_params. +.PP +An asymmetric kem algorithm must also implement some mechanism for generating, +loading or importing keys via the key management (\s-1OSSL_OP_KEYMGMT\s0) operation. +See \fBprovider\-keymgmt\fR\|(7) for further details. +.SS "Context Management Functions" +.IX Subsection "Context Management Functions" +\&\fBOSSL_FUNC_kem_newctx()\fR should create and return a pointer to a provider side +structure for holding context information during an asymmetric kem operation. +A pointer to this context will be passed back in a number of the other +asymmetric kem operation function calls. +The parameter \fIprovctx\fR is the provider context generated during provider +initialisation (see \fBprovider\fR\|(7)). +.PP +\&\fBOSSL_FUNC_kem_freectx()\fR is passed a pointer to the provider side asymmetric +kem context in the \fIctx\fR parameter. +This function should free any resources associated with that context. +.PP +\&\fBOSSL_FUNC_kem_dupctx()\fR should duplicate the provider side asymmetric kem +context in the \fIctx\fR parameter and return the duplicate copy. +.SS "Asymmetric Key Encapsulation Functions" +.IX Subsection "Asymmetric Key Encapsulation Functions" +\&\fBOSSL_FUNC_kem_encapsulate_init()\fR initialises a context for an asymmetric +encapsulation given a provider side asymmetric kem context in the \fIctx\fR +parameter, a pointer to a provider key object in the \fIprovkey\fR parameter and +the \fIname\fR of the algorithm. +The \fIparams\fR, if not \s-1NULL,\s0 should be set on the context in a manner similar to +using \fBOSSL_FUNC_kem_set_ctx_params()\fR. +The key object should have been previously generated, loaded or imported into +the provider using the key management (\s-1OSSL_OP_KEYMGMT\s0) operation (see +\&\fBprovider\-keymgmt\fR\|(7)>. +.PP +\&\fBOSSL_FUNC_kem_encapsulate()\fR performs the actual encapsulation itself. +A previously initialised asymmetric kem context is passed in the \fIctx\fR +parameter. +Unless \fIout\fR is \s-1NULL,\s0 the data to be encapsulated is internally generated, +and returned into the buffer pointed to by the \fIsecret\fR parameter and the +encapsulated data should also be written to the location pointed to by the +\&\fIout\fR parameter. The length of the encapsulated data should be written to +\&\fI*outlen\fR and the length of the generated secret should be written to +\&\fI*secretlen\fR. +.PP +If \fIout\fR is \s-1NULL\s0 then the maximum length of the encapsulated data should be +written to \fI*outlen\fR, and the maximum length of the generated secret should be +written to \fI*secretlen\fR. +.SS "Decapsulation Functions" +.IX Subsection "Decapsulation Functions" +\&\fBOSSL_FUNC_kem_decapsulate_init()\fR initialises a context for an asymmetric +decapsulation given a provider side asymmetric kem context in the \fIctx\fR +parameter, a pointer to a provider key object in the \fIprovkey\fR parameter, and +a \fIname\fR of the algorithm. +The key object should have been previously generated, loaded or imported into +the provider using the key management (\s-1OSSL_OP_KEYMGMT\s0) operation (see +\&\fBprovider\-keymgmt\fR\|(7)>. +.PP +\&\fBOSSL_FUNC_kem_decapsulate()\fR performs the actual decapsulation itself. +A previously initialised asymmetric kem context is passed in the \fIctx\fR +parameter. +The data to be decapsulated is pointed to by the \fIin\fR parameter which is \fIinlen\fR +bytes long. +Unless \fIout\fR is \s-1NULL,\s0 the decapsulated data should be written to the location +pointed to by the \fIout\fR parameter. +The length of the decapsulated data should be written to \fI*outlen\fR. +If \fIout\fR is \s-1NULL\s0 then the maximum length of the decapsulated data should be +written to \fI*outlen\fR. +.SS "Asymmetric Key Encapsulation Parameters" +.IX Subsection "Asymmetric Key Encapsulation Parameters" +See \s-1\fBOSSL_PARAM\s0\fR\|(3) for further details on the parameters structure used by +the \fBOSSL_FUNC_kem_get_ctx_params()\fR and \fBOSSL_FUNC_kem_set_ctx_params()\fR +functions. +.PP +\&\fBOSSL_FUNC_kem_get_ctx_params()\fR gets asymmetric kem parameters associated +with the given provider side asymmetric kem context \fIctx\fR and stores them in +\&\fIparams\fR. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_kem_set_ctx_params()\fR sets the asymmetric kem parameters associated +with the given provider side asymmetric kem context \fIctx\fR to \fIparams\fR. +Any parameter settings are additional to any that were previously set. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +No parameters are currently recognised by built-in asymmetric kem algorithms. +.PP +\&\fBOSSL_FUNC_kem_gettable_ctx_params()\fR and \fBOSSL_FUNC_kem_settable_ctx_params()\fR +get a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) array that describes the gettable and settable +parameters, i.e. parameters that can be used with \fBOSSL_FUNC_kem_get_ctx_params()\fR +and \fBOSSL_FUNC_kem_set_ctx_params()\fR respectively. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_kem_newctx()\fR and \fBOSSL_FUNC_kem_dupctx()\fR should return the newly +created provider side asymmetric kem context, or \s-1NULL\s0 on failure. +.PP +All other functions should return 1 for success or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The provider \s-1KEM\s0 interface was introduced in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/provider-keyexch.7 b/secure/lib/libcrypto/man/man7/provider-keyexch.7 new file mode 100644 index 000000000000..0c9acd85eefd --- /dev/null +++ b/secure/lib/libcrypto/man/man7/provider-keyexch.7 @@ -0,0 +1,361 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "PROVIDER-KEYEXCH 7ossl" +.TH PROVIDER-KEYEXCH 7ossl "2023-09-19" "3.0.11" "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" +provider\-keyexch \- The keyexch library <\-> provider functions +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 2 +\& #include <openssl/core_dispatch.h> +\& #include <openssl/core_names.h> +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Context management */ +\& void *OSSL_FUNC_keyexch_newctx(void *provctx); +\& void OSSL_FUNC_keyexch_freectx(void *ctx); +\& void *OSSL_FUNC_keyexch_dupctx(void *ctx); +\& +\& /* Shared secret derivation */ +\& int OSSL_FUNC_keyexch_init(void *ctx, void *provkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_keyexch_set_peer(void *ctx, void *provkey); +\& int OSSL_FUNC_keyexch_derive(void *ctx, unsigned char *secret, size_t *secretlen, +\& size_t outlen); +\& +\& /* Key Exchange parameters */ +\& int OSSL_FUNC_keyexch_set_ctx_params(void *ctx, const OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_keyexch_settable_ctx_params(void *ctx, +\& void *provctx); +\& int OSSL_FUNC_keyexch_get_ctx_params(void *ctx, OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_keyexch_gettable_ctx_params(void *ctx, +\& void *provctx); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7) +for further information. +.PP +The key exchange (\s-1OSSL_OP_KEYEXCH\s0) operation enables providers to implement key +exchange algorithms and make them available to applications via +\&\fBEVP_PKEY_derive\fR\|(3) and +other related functions). +.PP +All \*(L"functions\*(R" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays via +\&\s-1\fBOSSL_ALGORITHM\s0\fR\|(3) arrays that are returned by the provider's +\&\fBprovider_query_operation()\fR function +(see \*(L"Provider Functions\*(R" in \fBprovider\-base\fR\|(7)). +.PP +All these \*(L"functions\*(R" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from an \s-1\fBOSSL_DISPATCH\s0\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the \*(L"function\*(R" \fBOSSL_FUNC_keyexch_newctx()\fR has these: +.PP +.Vb 3 +\& typedef void *(OSSL_FUNC_keyexch_newctx_fn)(void *provctx); +\& static ossl_inline OSSL_FUNC_keyexch_newctx_fn +\& OSSL_FUNC_keyexch_newctx(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 3 +\& OSSL_FUNC_keyexch_newctx OSSL_FUNC_KEYEXCH_NEWCTX +\& OSSL_FUNC_keyexch_freectx OSSL_FUNC_KEYEXCH_FREECTX +\& OSSL_FUNC_keyexch_dupctx OSSL_FUNC_KEYEXCH_DUPCTX +\& +\& OSSL_FUNC_keyexch_init OSSL_FUNC_KEYEXCH_INIT +\& OSSL_FUNC_keyexch_set_peer OSSL_FUNC_KEYEXCH_SET_PEER +\& OSSL_FUNC_keyexch_derive OSSL_FUNC_KEYEXCH_DERIVE +\& +\& OSSL_FUNC_keyexch_set_ctx_params OSSL_FUNC_KEYEXCH_SET_CTX_PARAMS +\& OSSL_FUNC_keyexch_settable_ctx_params OSSL_FUNC_KEYEXCH_SETTABLE_CTX_PARAMS +\& OSSL_FUNC_keyexch_get_ctx_params OSSL_FUNC_KEYEXCH_GET_CTX_PARAMS +\& OSSL_FUNC_keyexch_gettable_ctx_params OSSL_FUNC_KEYEXCH_GETTABLE_CTX_PARAMS +.Ve +.PP +A key exchange algorithm implementation may not implement all of these functions. +In order to be a consistent set of functions a provider must implement +OSSL_FUNC_keyexch_newctx, OSSL_FUNC_keyexch_freectx, OSSL_FUNC_keyexch_init and OSSL_FUNC_keyexch_derive. +All other functions are optional. +.PP +A key exchange algorithm must also implement some mechanism for generating, +loading or importing keys via the key management (\s-1OSSL_OP_KEYMGMT\s0) operation. +See \fBprovider\-keymgmt\fR\|(7) for further details. +.SS "Context Management Functions" +.IX Subsection "Context Management Functions" +\&\fBOSSL_FUNC_keyexch_newctx()\fR should create and return a pointer to a provider side +structure for holding context information during a key exchange operation. +A pointer to this context will be passed back in a number of the other key +exchange operation function calls. +The parameter \fIprovctx\fR is the provider context generated during provider +initialisation (see \fBprovider\fR\|(7)). +.PP +\&\fBOSSL_FUNC_keyexch_freectx()\fR is passed a pointer to the provider side key exchange +context in the \fIctx\fR parameter. +This function should free any resources associated with that context. +.PP +\&\fBOSSL_FUNC_keyexch_dupctx()\fR should duplicate the provider side key exchange context in +the \fIctx\fR parameter and return the duplicate copy. +.SS "Shared Secret Derivation Functions" +.IX Subsection "Shared Secret Derivation Functions" +\&\fBOSSL_FUNC_keyexch_init()\fR initialises a key exchange operation given a provider side key +exchange context in the \fIctx\fR parameter, and a pointer to a provider key object +in the \fIprovkey\fR parameter. +The \fIparams\fR, if not \s-1NULL,\s0 should be set on the context in a manner similar to +using \fBOSSL_FUNC_keyexch_set_params()\fR. +The key object should have been previously +generated, loaded or imported into the provider using the key management +(\s-1OSSL_OP_KEYMGMT\s0) operation (see \fBprovider\-keymgmt\fR\|(7)>. +.PP +\&\fBOSSL_FUNC_keyexch_set_peer()\fR is called to supply the peer's public key (in the +\&\fIprovkey\fR parameter) to be used when deriving the shared secret. +It is also passed a previously initialised key exchange context in the \fIctx\fR +parameter. +The key object should have been previously generated, loaded or imported into +the provider using the key management (\s-1OSSL_OP_KEYMGMT\s0) operation (see +\&\fBprovider\-keymgmt\fR\|(7)>. +.PP +\&\fBOSSL_FUNC_keyexch_derive()\fR performs the actual key exchange itself by deriving a shared +secret. +A previously initialised key exchange context is passed in the \fIctx\fR +parameter. +The derived secret should be written to the location \fIsecret\fR which should not +exceed \fIoutlen\fR bytes. +The length of the shared secret should be written to \fI*secretlen\fR. +If \fIsecret\fR is \s-1NULL\s0 then the maximum length of the shared secret should be +written to \fI*secretlen\fR. +.SS "Key Exchange Parameters Functions" +.IX Subsection "Key Exchange Parameters Functions" +\&\fBOSSL_FUNC_keyexch_set_ctx_params()\fR sets key exchange parameters associated with the +given provider side key exchange context \fIctx\fR to \fIparams\fR, +see \*(L"Common Key Exchange parameters\*(R". +Any parameter settings are additional to any that were previously set. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_keyexch_get_ctx_params()\fR gets key exchange parameters associated with the +given provider side key exchange context \fIctx\fR into \fIparams\fR, +see \*(L"Common Key Exchange parameters\*(R". +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_keyexch_settable_ctx_params()\fR yields a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) array that +describes the settable parameters, i.e. parameters that can be used with +\&\fBOP_signature_set_ctx_params()\fR. +If \fBOSSL_FUNC_keyexch_settable_ctx_params()\fR is present, \fBOSSL_FUNC_keyexch_set_ctx_params()\fR must +also be present, and vice versa. +Similarly, \fBOSSL_FUNC_keyexch_gettable_ctx_params()\fR yields a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) +array that describes the gettable parameters, i.e. parameters that can be +handled by \fBOP_signature_get_ctx_params()\fR. +If \fBOSSL_FUNC_keyexch_gettable_ctx_params()\fR is present, \fBOSSL_FUNC_keyexch_get_ctx_params()\fR must +also be present, and vice versa. +.PP +Notice that not all settable parameters are also gettable, and vice versa. +.SS "Common Key Exchange parameters" +.IX Subsection "Common Key Exchange parameters" +See \s-1\fBOSSL_PARAM\s0\fR\|(3) for further details on the parameters structure used by +the \fBOSSL_FUNC_keyexch_set_ctx_params()\fR and \fBOSSL_FUNC_keyexch_get_ctx_params()\fR functions. +.PP +Common parameters currently recognised by built-in key exchange algorithms are +as follows. +.ie n .IP """kdf-type"" (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``kdf-type'' (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "kdf-type (OSSL_EXCHANGE_PARAM_KDF_TYPE) <UTF8 string>" +Sets or gets the Key Derivation Function type to apply within the associated key +exchange ctx. +.ie n .IP """kdf-digest"" (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``kdf-digest'' (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "kdf-digest (OSSL_EXCHANGE_PARAM_KDF_DIGEST) <UTF8 string>" +Sets or gets the Digest algorithm to be used as part of the Key Derivation Function +associated with the given key exchange ctx. +.ie n .IP """kdf-digest-props"" (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``kdf-digest-props'' (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "kdf-digest-props (OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS) <UTF8 string>" +Sets properties to be used upon look up of the implementation for the selected +Digest algorithm for the Key Derivation Function associated with the given key +exchange ctx. +.ie n .IP """kdf-outlen"" (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_OUTLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``kdf-outlen'' (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_OUTLEN\s0\fR) <unsigned integer>" 4 +.IX Item "kdf-outlen (OSSL_EXCHANGE_PARAM_KDF_OUTLEN) <unsigned integer>" +Sets or gets the desired size for the output of the chosen Key Derivation Function +associated with the given key exchange ctx. +The length of the \*(L"kdf-outlen\*(R" parameter should not exceed that of a \fBsize_t\fR. +.ie n .IP """kdf-ukm"" (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_UKM\s0\fR) <octet string>" 4 +.el .IP "``kdf-ukm'' (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_UKM\s0\fR) <octet string>" 4 +.IX Item "kdf-ukm (OSSL_EXCHANGE_PARAM_KDF_UKM) <octet string>" +Sets the User Key Material to be used as part of the selected Key Derivation +Function associated with the given key exchange ctx. +.ie n .IP """kdf-ukm"" (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_UKM\s0\fR) <octet string ptr>" 4 +.el .IP "``kdf-ukm'' (\fB\s-1OSSL_EXCHANGE_PARAM_KDF_UKM\s0\fR) <octet string ptr>" 4 +.IX Item "kdf-ukm (OSSL_EXCHANGE_PARAM_KDF_UKM) <octet string ptr>" +Gets a pointer to the User Key Material to be used as part of the selected +Key Derivation Function associated with the given key exchange ctx. Providers +usually do not need to support this gettable parameter as its sole purpose +is to support functionality of the deprecated \fBEVP_PKEY_CTX_get0_ecdh_kdf_ukm()\fR +and \fBEVP_PKEY_CTX_get0_dh_kdf_ukm()\fR functions. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_keyexch_newctx()\fR and \fBOSSL_FUNC_keyexch_dupctx()\fR should return the newly created +provider side key exchange context, or \s-1NULL\s0 on failure. +.PP +\&\fBOSSL_FUNC_keyexch_init()\fR, \fBOSSL_FUNC_keyexch_set_peer()\fR, \fBOSSL_FUNC_keyexch_derive()\fR, +\&\fBOSSL_FUNC_keyexch_set_params()\fR, and \fBOSSL_FUNC_keyexch_get_params()\fR should return 1 for success +or 0 on error. +.PP +\&\fBOSSL_FUNC_keyexch_settable_ctx_params()\fR and \fBOSSL_FUNC_keyexch_gettable_ctx_params()\fR should +always return a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) array. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The provider \s-1KEYEXCH\s0 interface was introduced in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2019\-2022 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>. diff --git a/secure/lib/libcrypto/man/man7/provider-keymgmt.7 b/secure/lib/libcrypto/man/man7/provider-keymgmt.7 new file mode 100644 index 000000000000..56e06deb3e42 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/provider-keymgmt.7 @@ -0,0 +1,554 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "PROVIDER-KEYMGMT 7ossl" +.TH PROVIDER-KEYMGMT 7ossl "2023-09-19" "3.0.11" "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" +provider\-keymgmt \- The KEYMGMT library <\-> provider functions +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/core_dispatch.h> +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Key object (keydata) creation and destruction */ +\& void *OSSL_FUNC_keymgmt_new(void *provctx); +\& void OSSL_FUNC_keymgmt_free(void *keydata); +\& +\& /* Generation, a more complex constructor */ +\& void *OSSL_FUNC_keymgmt_gen_init(void *provctx, int selection, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_keymgmt_gen_set_template(void *genctx, void *template); +\& int OSSL_FUNC_keymgmt_gen_set_params(void *genctx, const OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_keymgmt_gen_settable_params(void *genctx, +\& void *provctx); +\& void *OSSL_FUNC_keymgmt_gen(void *genctx, OSSL_CALLBACK *cb, void *cbarg); +\& void OSSL_FUNC_keymgmt_gen_cleanup(void *genctx); +\& +\& /* Key loading by object reference, also a constructor */ +\& void *OSSL_FUNC_keymgmt_load(const void *reference, size_t *reference_sz); +\& +\& /* Key object information */ +\& int OSSL_FUNC_keymgmt_get_params(void *keydata, OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_keymgmt_gettable_params(void *provctx); +\& int OSSL_FUNC_keymgmt_set_params(void *keydata, const OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_keymgmt_settable_params(void *provctx); +\& +\& /* Key object content checks */ +\& int OSSL_FUNC_keymgmt_has(const void *keydata, int selection); +\& int OSSL_FUNC_keymgmt_match(const void *keydata1, const void *keydata2, +\& int selection); +\& +\& /* Discovery of supported operations */ +\& const char *OSSL_FUNC_keymgmt_query_operation_name(int operation_id); +\& +\& /* Key object import and export functions */ +\& int OSSL_FUNC_keymgmt_import(void *keydata, int selection, const OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types(int selection); +\& int OSSL_FUNC_keymgmt_export(void *keydata, int selection, +\& OSSL_CALLBACK *param_cb, void *cbarg); +\& const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types(int selection); +\& +\& /* Key object duplication, a constructor */ +\& void *OSSL_FUNC_keymgmt_dup(const void *keydata_from, int selection); +\& +\& /* Key object validation */ +\& int OSSL_FUNC_keymgmt_validate(const void *keydata, int selection, int checktype); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \s-1KEYMGMT\s0 operation doesn't have much public visibility in OpenSSL +libraries, it's rather an internal operation that's designed to work +in tandem with operations that use private/public key pairs. +.PP +Because the \s-1KEYMGMT\s0 operation shares knowledge with the operations it +works with in tandem, they must belong to the same provider. +The OpenSSL libraries will ensure that they do. +.PP +The primary responsibility of the \s-1KEYMGMT\s0 operation is to hold the +provider side key data for the OpenSSL library \s-1EVP_PKEY\s0 structure. +.PP +All \*(L"functions\*(R" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays via +\&\s-1\fBOSSL_ALGORITHM\s0\fR\|(3) arrays that are returned by the provider's +\&\fBprovider_query_operation()\fR function +(see \*(L"Provider Functions\*(R" in \fBprovider\-base\fR\|(7)). +.PP +All these \*(L"functions\*(R" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from a \s-1\fBOSSL_DISPATCH\s0\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the \*(L"function\*(R" \fBOSSL_FUNC_keymgmt_new()\fR has these: +.PP +.Vb 3 +\& typedef void *(OSSL_FUNC_keymgmt_new_fn)(void *provctx); +\& static ossl_inline OSSL_FUNC_keymgmt_new_fn +\& OSSL_FUNC_keymgmt_new(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 2 +\& OSSL_FUNC_keymgmt_new OSSL_FUNC_KEYMGMT_NEW +\& OSSL_FUNC_keymgmt_free OSSL_FUNC_KEYMGMT_FREE +\& +\& OSSL_FUNC_keymgmt_gen_init OSSL_FUNC_KEYMGMT_GEN_INIT +\& OSSL_FUNC_keymgmt_gen_set_template OSSL_FUNC_KEYMGMT_GEN_SET_TEMPLATE +\& OSSL_FUNC_keymgmt_gen_set_params OSSL_FUNC_KEYMGMT_GEN_SET_PARAMS +\& OSSL_FUNC_keymgmt_gen_settable_params OSSL_FUNC_KEYMGMT_GEN_SETTABLE_PARAMS +\& OSSL_FUNC_keymgmt_gen OSSL_FUNC_KEYMGMT_GEN +\& OSSL_FUNC_keymgmt_gen_cleanup OSSL_FUNC_KEYMGMT_GEN_CLEANUP +\& +\& OSSL_FUNC_keymgmt_load OSSL_FUNC_KEYMGMT_LOAD +\& +\& OSSL_FUNC_keymgmt_get_params OSSL_FUNC_KEYMGMT_GET_PARAMS +\& OSSL_FUNC_keymgmt_gettable_params OSSL_FUNC_KEYMGMT_GETTABLE_PARAMS +\& OSSL_FUNC_keymgmt_set_params OSSL_FUNC_KEYMGMT_SET_PARAMS +\& OSSL_FUNC_keymgmt_settable_params OSSL_FUNC_KEYMGMT_SETTABLE_PARAMS +\& +\& OSSL_FUNC_keymgmt_query_operation_name OSSL_FUNC_KEYMGMT_QUERY_OPERATION_NAME +\& +\& OSSL_FUNC_keymgmt_has OSSL_FUNC_KEYMGMT_HAS +\& OSSL_FUNC_keymgmt_validate OSSL_FUNC_KEYMGMT_VALIDATE +\& OSSL_FUNC_keymgmt_match OSSL_FUNC_KEYMGMT_MATCH +\& +\& OSSL_FUNC_keymgmt_import OSSL_FUNC_KEYMGMT_IMPORT +\& OSSL_FUNC_keymgmt_import_types OSSL_FUNC_KEYMGMT_IMPORT_TYPES +\& OSSL_FUNC_keymgmt_export OSSL_FUNC_KEYMGMT_EXPORT +\& OSSL_FUNC_keymgmt_export_types OSSL_FUNC_KEYMGMT_EXPORT_TYPES +\& +\& OSSL_FUNC_keymgmt_dup OSSL_FUNC_KEYMGMT_DUP +.Ve +.SS "Key Objects" +.IX Subsection "Key Objects" +A key object is a collection of data for an asymmetric key, and is +represented as \fIkeydata\fR in this manual. +.PP +The exact contents of a key object are defined by the provider, and it +is assumed that different operations in one and the same provider use +the exact same structure to represent this collection of data, so that +for example, a key object that has been created using the \s-1KEYMGMT\s0 +interface that we document here can be passed as is to other provider +operations, such as \fBOP_signature_sign_init()\fR (see +\&\fBprovider\-signature\fR\|(7)). +.PP +With some of the \s-1KEYMGMT\s0 functions, it's possible to select a specific +subset of data to handle, governed by the bits in a \fIselection\fR +indicator. The bits are: +.IP "\fB\s-1OSSL_KEYMGMT_SELECT_PRIVATE_KEY\s0\fR" 4 +.IX Item "OSSL_KEYMGMT_SELECT_PRIVATE_KEY" +Indicating that the private key data in a key object should be +considered. +.IP "\fB\s-1OSSL_KEYMGMT_SELECT_PUBLIC_KEY\s0\fR" 4 +.IX Item "OSSL_KEYMGMT_SELECT_PUBLIC_KEY" +Indicating that the public key data in a key object should be +considered. +.IP "\fB\s-1OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS\s0\fR" 4 +.IX Item "OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS" +Indicating that the domain parameters in a key object should be +considered. +.IP "\fB\s-1OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS\s0\fR" 4 +.IX Item "OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS" +Indicating that other parameters in a key object should be +considered. +.Sp +Other parameters are key parameters that don't fit any other +classification. In other words, this particular selector bit works as +a last resort bit bucket selector. +.PP +Some selector bits have also been combined for easier use: +.IP "\fB\s-1OSSL_KEYMGMT_SELECT_ALL_PARAMETERS\s0\fR" 4 +.IX Item "OSSL_KEYMGMT_SELECT_ALL_PARAMETERS" +Indicating that all key object parameters should be considered, +regardless of their more granular classification. +.Sp +This is a combination of \fB\s-1OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS\s0\fR and +\&\fB\s-1OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS\s0\fR. +.IP "\fB\s-1OSSL_KEYMGMT_SELECT_KEYPAIR\s0\fR" 4 +.IX Item "OSSL_KEYMGMT_SELECT_KEYPAIR" +Indicating that both the whole key pair in a key object should be +considered, i.e. the combination of public and private key. +.Sp +This is a combination of \fB\s-1OSSL_KEYMGMT_SELECT_PRIVATE_KEY\s0\fR and +\&\fB\s-1OSSL_KEYMGMT_SELECT_PUBLIC_KEY\s0\fR. +.IP "\fB\s-1OSSL_KEYMGMT_SELECT_ALL\s0\fR" 4 +.IX Item "OSSL_KEYMGMT_SELECT_ALL" +Indicating that everything in a key object should be considered. +.PP +The exact interpretation of those bits or how they combine is left to +each function where you can specify a selector. +.PP +It's left to the provider implementation to decide what is reasonable +to do with regards to received selector bits and how to do it. +Among others, an implementation of \fBOSSL_FUNC_keymgmt_match()\fR might opt +to not compare the private half if it has compared the public half, +since a match of one half implies a match of the other half. +.SS "Constructing and Destructing Functions" +.IX Subsection "Constructing and Destructing Functions" +\&\fBOSSL_FUNC_keymgmt_new()\fR should create a provider side key object. The +provider context \fIprovctx\fR is passed and may be incorporated in the +key object, but that is not mandatory. +.PP +\&\fBOSSL_FUNC_keymgmt_free()\fR should free the passed \fIkeydata\fR. +.PP +\&\fBOSSL_FUNC_keymgmt_gen_init()\fR, \fBOSSL_FUNC_keymgmt_gen_set_template()\fR, +\&\fBOSSL_FUNC_keymgmt_gen_set_params()\fR, \fBOSSL_FUNC_keymgmt_gen_settable_params()\fR, +\&\fBOSSL_FUNC_keymgmt_gen()\fR and \fBOSSL_FUNC_keymgmt_gen_cleanup()\fR work together as a +more elaborate context based key object constructor. +.PP +\&\fBOSSL_FUNC_keymgmt_gen_init()\fR should create the key object generation context +and initialize it with \fIselections\fR, which will determine what kind +of contents the key object to be generated should get. +The \fIparams\fR, if not \s-1NULL,\s0 should be set on the context in a manner similar to +using \fBOSSL_FUNC_keymgmt_set_params()\fR. +.PP +\&\fBOSSL_FUNC_keymgmt_gen_set_template()\fR should add \fItemplate\fR to the context +\&\fIgenctx\fR. The \fItemplate\fR is assumed to be a key object constructed +with the same \s-1KEYMGMT,\s0 and from which content that the implementation +chooses can be used as a template for the key object to be generated. +Typically, the generation of a \s-1DSA\s0 or \s-1DH\s0 key would get the domain +parameters from this \fItemplate\fR. +.PP +\&\fBOSSL_FUNC_keymgmt_gen_set_params()\fR should set additional parameters from +\&\fIparams\fR in the key object generation context \fIgenctx\fR. +.PP +\&\fBOSSL_FUNC_keymgmt_gen_settable_params()\fR should return a constant array of +descriptor \s-1\fBOSSL_PARAM\s0\fR\|(3), for parameters that \fBOSSL_FUNC_keymgmt_gen_set_params()\fR +can handle. +.PP +\&\fBOSSL_FUNC_keymgmt_gen()\fR should perform the key object generation itself, and +return the result. The callback \fIcb\fR should be called at regular +intervals with indications on how the key object generation +progresses. +.PP +\&\fBOSSL_FUNC_keymgmt_gen_cleanup()\fR should clean up and free the key object +generation context \fIgenctx\fR +.PP +\&\fBOSSL_FUNC_keymgmt_load()\fR creates a provider side key object based on a +\&\fIreference\fR object with a size of \fIreference_sz\fR bytes, that only the +provider knows how to interpret, but that may come from other operations. +Outside the provider, this reference is simply an array of bytes. +.PP +At least one of \fBOSSL_FUNC_keymgmt_new()\fR, \fBOSSL_FUNC_keymgmt_gen()\fR and +\&\fBOSSL_FUNC_keymgmt_load()\fR are mandatory, as well as \fBOSSL_FUNC_keymgmt_free()\fR and +\&\fBOSSL_FUNC_keymgmt_has()\fR. Additionally, if \fBOSSL_FUNC_keymgmt_gen()\fR is present, +\&\fBOSSL_FUNC_keymgmt_gen_init()\fR and \fBOSSL_FUNC_keymgmt_gen_cleanup()\fR must be +present as well. +.SS "Key Object Information Functions" +.IX Subsection "Key Object Information Functions" +\&\fBOSSL_FUNC_keymgmt_get_params()\fR should extract information data associated +with the given \fIkeydata\fR, see \*(L"Common Information Parameters\*(R". +.PP +\&\fBOSSL_FUNC_keymgmt_gettable_params()\fR should return a constant array of +descriptor \s-1\fBOSSL_PARAM\s0\fR\|(3), for parameters that \fBOSSL_FUNC_keymgmt_get_params()\fR +can handle. +.PP +If \fBOSSL_FUNC_keymgmt_gettable_params()\fR is present, \fBOSSL_FUNC_keymgmt_get_params()\fR +must also be present, and vice versa. +.PP +\&\fBOSSL_FUNC_keymgmt_set_params()\fR should update information data associated +with the given \fIkeydata\fR, see \*(L"Common Information Parameters\*(R". +.PP +\&\fBOSSL_FUNC_keymgmt_settable_params()\fR should return a constant array of +descriptor \s-1\fBOSSL_PARAM\s0\fR\|(3), for parameters that \fBOSSL_FUNC_keymgmt_set_params()\fR +can handle. +.PP +If \fBOSSL_FUNC_keymgmt_settable_params()\fR is present, \fBOSSL_FUNC_keymgmt_set_params()\fR +must also be present, and vice versa. +.SS "Key Object Checking Functions" +.IX Subsection "Key Object Checking Functions" +\&\fBOSSL_FUNC_keymgmt_query_operation_name()\fR should return the name of the +supported algorithm for the operation \fIoperation_id\fR. This is +similar to \fBprovider_query_operation()\fR (see \fBprovider\-base\fR\|(7)), +but only works as an advisory. If this function is not present, or +returns \s-1NULL,\s0 the caller is free to assume that there's an algorithm +from the same provider, of the same name as the one used to fetch the +keymgmt and try to use that. +.PP +\&\fBOSSL_FUNC_keymgmt_has()\fR should check whether the given \fIkeydata\fR contains the subsets +of data indicated by the \fIselector\fR. A combination of several +selector bits must consider all those subsets, not just one. An +implementation is, however, free to consider an empty subset of data +to still be a valid subset. For algorithms where some selection is +not meaningful such as \fB\s-1OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS\s0\fR for +\&\s-1RSA\s0 keys the function should just return 1 as the selected subset +is not really missing in the key. +.PP +\&\fBOSSL_FUNC_keymgmt_validate()\fR should check if the \fIkeydata\fR contains valid +data subsets indicated by \fIselection\fR. Some combined selections of +data subsets may cause validation of the combined data. +For example, the combination of \fB\s-1OSSL_KEYMGMT_SELECT_PRIVATE_KEY\s0\fR and +\&\fB\s-1OSSL_KEYMGMT_SELECT_PUBLIC_KEY\s0\fR (or \fB\s-1OSSL_KEYMGMT_SELECT_KEYPAIR\s0\fR +for short) is expected to check that the pairwise consistency of +\&\fIkeydata\fR is valid. The \fIchecktype\fR parameter controls what type of check is +performed on the subset of data. Two types of check are defined: +\&\fB\s-1OSSL_KEYMGMT_VALIDATE_FULL_CHECK\s0\fR and \fB\s-1OSSL_KEYMGMT_VALIDATE_QUICK_CHECK\s0\fR. +The interpretation of how much checking is performed in a full check versus a +quick check is key type specific. Some providers may have no distinction +between a full check and a quick check. For algorithms where some selection is +not meaningful such as \fB\s-1OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS\s0\fR for +\&\s-1RSA\s0 keys the function should just return 1 as there is nothing to validate for +that selection. +.PP +\&\fBOSSL_FUNC_keymgmt_match()\fR should check if the data subset indicated by +\&\fIselection\fR in \fIkeydata1\fR and \fIkeydata2\fR match. It is assumed that +the caller has ensured that \fIkeydata1\fR and \fIkeydata2\fR are both owned +by the implementation of this function. +.SS "Key Object Import, Export and Duplication Functions" +.IX Subsection "Key Object Import, Export and Duplication Functions" +\&\fBOSSL_FUNC_keymgmt_import()\fR should import data indicated by \fIselection\fR into +\&\fIkeydata\fR with values taken from the \s-1\fBOSSL_PARAM\s0\fR\|(3) array \fIparams\fR. +.PP +\&\fBOSSL_FUNC_keymgmt_export()\fR should extract values indicated by \fIselection\fR +from \fIkeydata\fR, create an \s-1\fBOSSL_PARAM\s0\fR\|(3) array with them and call +\&\fIparam_cb\fR with that array as well as the given \fIcbarg\fR. +.PP +\&\fBOSSL_FUNC_keymgmt_import_types()\fR should return a constant array of descriptor +\&\s-1\fBOSSL_PARAM\s0\fR\|(3) for data indicated by \fIselection\fR, for parameters that +\&\fBOSSL_FUNC_keymgmt_import()\fR can handle. +.PP +\&\fBOSSL_FUNC_keymgmt_export_types()\fR should return a constant array of descriptor +\&\s-1\fBOSSL_PARAM\s0\fR\|(3) for data indicated by \fIselection\fR, that the +\&\fBOSSL_FUNC_keymgmt_export()\fR callback can expect to receive. +.PP +\&\fBOSSL_FUNC_keymgmt_dup()\fR should duplicate data subsets indicated by +\&\fIselection\fR or the whole key data \fIkeydata_from\fR and create a new +provider side key object with the data. +.SS "Common Information Parameters" +.IX Subsection "Common Information Parameters" +See \s-1\fBOSSL_PARAM\s0\fR\|(3) for further details on the parameters structure. +.PP +Common information parameters currently recognised by all built-in +keymgmt algorithms are as follows: +.ie n .IP """bits"" (\fB\s-1OSSL_PKEY_PARAM_BITS\s0\fR) <integer>" 4 +.el .IP "``bits'' (\fB\s-1OSSL_PKEY_PARAM_BITS\s0\fR) <integer>" 4 +.IX Item "bits (OSSL_PKEY_PARAM_BITS) <integer>" +The value should be the cryptographic length of the cryptosystem to +which the key belongs, in bits. The definition of cryptographic +length is specific to the key cryptosystem. +.ie n .IP """max-size"" (\fB\s-1OSSL_PKEY_PARAM_MAX_SIZE\s0\fR) <integer>" 4 +.el .IP "``max-size'' (\fB\s-1OSSL_PKEY_PARAM_MAX_SIZE\s0\fR) <integer>" 4 +.IX Item "max-size (OSSL_PKEY_PARAM_MAX_SIZE) <integer>" +The value should be the maximum size that a caller should allocate to +safely store a signature (called \fIsig\fR in \fBprovider\-signature\fR\|(7)), +the result of asymmmetric encryption / decryption (\fIout\fR in +\&\fBprovider\-asym_cipher\fR\|(7), a derived secret (\fIsecret\fR in +\&\fBprovider\-keyexch\fR\|(7), and similar data). +.Sp +Because an \s-1EVP_KEYMGMT\s0 method is always tightly bound to another method +(signature, asymmetric cipher, key exchange, ...) and must be of the +same provider, this number only needs to be synchronised with the +dimensions handled in the rest of the same provider. +.ie n .IP """security-bits"" (\fB\s-1OSSL_PKEY_PARAM_SECURITY_BITS\s0\fR) <integer>" 4 +.el .IP "``security-bits'' (\fB\s-1OSSL_PKEY_PARAM_SECURITY_BITS\s0\fR) <integer>" 4 +.IX Item "security-bits (OSSL_PKEY_PARAM_SECURITY_BITS) <integer>" +The value should be the number of security bits of the given key. +Bits of security is defined in \s-1SP800\-57.\s0 +.ie n .IP """mandatory-digest"" (\fB\s-1OSSL_PKEY_PARAM_MANDATORY_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``mandatory-digest'' (\fB\s-1OSSL_PKEY_PARAM_MANDATORY_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "mandatory-digest (OSSL_PKEY_PARAM_MANDATORY_DIGEST) <UTF8 string>" +If there is a mandatory digest for performing a signature operation with +keys from this keymgmt, this parameter should get its name as value. +.Sp +When \fBEVP_PKEY_get_default_digest_name()\fR queries this parameter and it's +filled in by the implementation, its return value will be 2. +.Sp +If the keymgmt implementation fills in the value \f(CW""\fR or \f(CW"UNDEF"\fR, +\&\fBEVP_PKEY_get_default_digest_name\fR\|(3) will place the string \f(CW"UNDEF"\fR into +its argument \fImdname\fR. This signifies that no digest should be specified +with the corresponding signature operation. +.ie n .IP """default-digest"" (\fB\s-1OSSL_PKEY_PARAM_DEFAULT_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``default-digest'' (\fB\s-1OSSL_PKEY_PARAM_DEFAULT_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "default-digest (OSSL_PKEY_PARAM_DEFAULT_DIGEST) <UTF8 string>" +If there is a default digest for performing a signature operation with +keys from this keymgmt, this parameter should get its name as value. +.Sp +When \fBEVP_PKEY_get_default_digest_name\fR\|(3) queries this parameter and it's +filled in by the implementation, its return value will be 1. Note that if +\&\fB\s-1OSSL_PKEY_PARAM_MANDATORY_DIGEST\s0\fR is responded to as well, +\&\fBEVP_PKEY_get_default_digest_name\fR\|(3) ignores the response to this +parameter. +.Sp +If the keymgmt implementation fills in the value \f(CW""\fR or \f(CW"UNDEF"\fR, +\&\fBEVP_PKEY_get_default_digest_name\fR\|(3) will place the string \f(CW"UNDEF"\fR into +its argument \fImdname\fR. This signifies that no digest has to be specified +with the corresponding signature operation, but may be specified as an +option. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_keymgmt_new()\fR and \fBOSSL_FUNC_keymgmt_dup()\fR should return a valid +reference to the newly created provider side key object, or \s-1NULL\s0 on failure. +.PP +\&\fBOSSL_FUNC_keymgmt_import()\fR, \fBOSSL_FUNC_keymgmt_export()\fR, \fBOSSL_FUNC_keymgmt_get_params()\fR and +\&\fBOSSL_FUNC_keymgmt_set_params()\fR should return 1 for success or 0 on error. +.PP +\&\fBOSSL_FUNC_keymgmt_validate()\fR should return 1 on successful validation, or 0 on +failure. +.PP +\&\fBOSSL_FUNC_keymgmt_has()\fR should return 1 if all the selected data subsets are contained +in the given \fIkeydata\fR or 0 otherwise. +.PP +\&\fBOSSL_FUNC_keymgmt_query_operation_name()\fR should return a pointer to a string matching +the requested operation, or \s-1NULL\s0 if the same name used to fetch the keymgmt +applies. +.PP +\&\fBOSSL_FUNC_keymgmt_gettable_params()\fR and \fBOSSL_FUNC_keymgmt_settable_params()\fR +\&\fBOSSL_FUNC_keymgmt_import_types()\fR, \fBOSSL_FUNC_keymgmt_export_types()\fR +should +always return a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) array. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), +\&\s-1\fBEVP_PKEY\-X25519\s0\fR\|(7), \s-1\fBEVP_PKEY\-X448\s0\fR\|(7), \s-1\fBEVP_PKEY\-ED25519\s0\fR\|(7), +\&\s-1\fBEVP_PKEY\-ED448\s0\fR\|(7), \s-1\fBEVP_PKEY\-EC\s0\fR\|(7), \s-1\fBEVP_PKEY\-RSA\s0\fR\|(7), +\&\s-1\fBEVP_PKEY\-DSA\s0\fR\|(7), \s-1\fBEVP_PKEY\-DH\s0\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The \s-1KEYMGMT\s0 interface was introduced in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2019\-2023 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>. diff --git a/secure/lib/libcrypto/man/man7/provider-mac.7 b/secure/lib/libcrypto/man/man7/provider-mac.7 new file mode 100644 index 000000000000..be69d8099f4f --- /dev/null +++ b/secure/lib/libcrypto/man/man7/provider-mac.7 @@ -0,0 +1,361 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "PROVIDER-MAC 7ossl" +.TH PROVIDER-MAC 7ossl "2023-09-19" "3.0.11" "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" +provider\-mac \- The mac library <\-> provider functions +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 2 +\& #include <openssl/core_dispatch.h> +\& #include <openssl/core_names.h> +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Context management */ +\& void *OSSL_FUNC_mac_newctx(void *provctx); +\& void OSSL_FUNC_mac_freectx(void *mctx); +\& void *OSSL_FUNC_mac_dupctx(void *src); +\& +\& /* Encryption/decryption */ +\& int OSSL_FUNC_mac_init(void *mctx, unsigned char *key, size_t keylen, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_mac_update(void *mctx, const unsigned char *in, size_t inl); +\& int OSSL_FUNC_mac_final(void *mctx, unsigned char *out, size_t *outl, size_t outsize); +\& +\& /* MAC parameter descriptors */ +\& const OSSL_PARAM *OSSL_FUNC_mac_gettable_params(void *provctx); +\& const OSSL_PARAM *OSSL_FUNC_mac_gettable_ctx_params(void *mctx, void *provctx); +\& const OSSL_PARAM *OSSL_FUNC_mac_settable_ctx_params(void *mctx, void *provctx); +\& +\& /* MAC parameters */ +\& int OSSL_FUNC_mac_get_params(OSSL_PARAM params[]); +\& int OSSL_FUNC_mac_get_ctx_params(void *mctx, OSSL_PARAM params[]); +\& int OSSL_FUNC_mac_set_ctx_params(void *mctx, const OSSL_PARAM params[]); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7) +for further information. +.PP +The \s-1MAC\s0 operation enables providers to implement mac algorithms and make +them available to applications via the \s-1API\s0 functions \fBEVP_MAC_init\fR\|(3), +\&\fBEVP_MAC_update\fR\|(3) and \fBEVP_MAC_final\fR\|(3). +.PP +All \*(L"functions\*(R" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays via +\&\s-1\fBOSSL_ALGORITHM\s0\fR\|(3) arrays that are returned by the provider's +\&\fBprovider_query_operation()\fR function +(see \*(L"Provider Functions\*(R" in \fBprovider\-base\fR\|(7)). +.PP +All these \*(L"functions\*(R" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from an \s-1\fBOSSL_DISPATCH\s0\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the \*(L"function\*(R" \fBOSSL_FUNC_mac_newctx()\fR has these: +.PP +.Vb 3 +\& typedef void *(OSSL_FUNC_mac_newctx_fn)(void *provctx); +\& static ossl_inline OSSL_FUNC_mac_newctx_fn +\& OSSL_FUNC_mac_newctx(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 3 +\& OSSL_FUNC_mac_newctx OSSL_FUNC_MAC_NEWCTX +\& OSSL_FUNC_mac_freectx OSSL_FUNC_MAC_FREECTX +\& OSSL_FUNC_mac_dupctx OSSL_FUNC_MAC_DUPCTX +\& +\& OSSL_FUNC_mac_init OSSL_FUNC_MAC_INIT +\& OSSL_FUNC_mac_update OSSL_FUNC_MAC_UPDATE +\& OSSL_FUNC_mac_final OSSL_FUNC_MAC_FINAL +\& +\& OSSL_FUNC_mac_get_params OSSL_FUNC_MAC_GET_PARAMS +\& OSSL_FUNC_mac_get_ctx_params OSSL_FUNC_MAC_GET_CTX_PARAMS +\& OSSL_FUNC_mac_set_ctx_params OSSL_FUNC_MAC_SET_CTX_PARAMS +\& +\& OSSL_FUNC_mac_gettable_params OSSL_FUNC_MAC_GETTABLE_PARAMS +\& OSSL_FUNC_mac_gettable_ctx_params OSSL_FUNC_MAC_GETTABLE_CTX_PARAMS +\& OSSL_FUNC_mac_settable_ctx_params OSSL_FUNC_MAC_SETTABLE_CTX_PARAMS +.Ve +.PP +A mac algorithm implementation may not implement all of these functions. +In order to be a consistent set of functions, at least the following functions +must be implemented: \fBOSSL_FUNC_mac_newctx()\fR, \fBOSSL_FUNC_mac_freectx()\fR, \fBOSSL_FUNC_mac_init()\fR, +\&\fBOSSL_FUNC_mac_update()\fR, \fBOSSL_FUNC_mac_final()\fR. +All other functions are optional. +.SS "Context Management Functions" +.IX Subsection "Context Management Functions" +\&\fBOSSL_FUNC_mac_newctx()\fR should create and return a pointer to a provider side +structure for holding context information during a mac operation. +A pointer to this context will be passed back in a number of the other mac +operation function calls. +The parameter \fIprovctx\fR is the provider context generated during provider +initialisation (see \fBprovider\fR\|(7)). +.PP +\&\fBOSSL_FUNC_mac_freectx()\fR is passed a pointer to the provider side mac context in +the \fImctx\fR parameter. +If it receives \s-1NULL\s0 as \fImctx\fR value, it should not do anything other than +return. +This function should free any resources associated with that context. +.PP +\&\fBOSSL_FUNC_mac_dupctx()\fR should duplicate the provider side mac context in the +\&\fImctx\fR parameter and return the duplicate copy. +.SS "Encryption/Decryption Functions" +.IX Subsection "Encryption/Decryption Functions" +\&\fBOSSL_FUNC_mac_init()\fR initialises a mac operation given a newly created provider +side mac context in the \fImctx\fR parameter. The \fIparams\fR are set before setting +the \s-1MAC\s0 \fIkey\fR of \fIkeylen\fR bytes. +.PP +\&\fBOSSL_FUNC_mac_update()\fR is called to supply data for \s-1MAC\s0 computation of a previously +initialised mac operation. +The \fImctx\fR parameter contains a pointer to a previously initialised provider +side context. +\&\fBOSSL_FUNC_mac_update()\fR may be called multiple times for a single mac operation. +.PP +\&\fBOSSL_FUNC_mac_final()\fR completes the \s-1MAC\s0 computation started through previous +\&\fBOSSL_FUNC_mac_init()\fR and \fBOSSL_FUNC_mac_update()\fR calls. +The \fImctx\fR parameter contains a pointer to the provider side context. +The resulting \s-1MAC\s0 should be written to \fIout\fR and the amount of data written +to \fI*outl\fR, which should not exceed \fIoutsize\fR bytes. +The same expectations apply to \fIoutsize\fR as documented for +\&\fBEVP_MAC_final\fR\|(3). +.SS "Mac Parameters" +.IX Subsection "Mac Parameters" +See \s-1\fBOSSL_PARAM\s0\fR\|(3) for further details on the parameters structure used by +these functions. +.PP +\&\fBOSSL_FUNC_mac_get_params()\fR gets details of parameter values associated with the +provider algorithm and stores them in \fIparams\fR. +.PP +\&\fBOSSL_FUNC_mac_set_ctx_params()\fR sets mac parameters associated with the given +provider side mac context \fImctx\fR to \fIparams\fR. +Any parameter settings are additional to any that were previously set. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_mac_get_ctx_params()\fR gets details of currently set parameter values +associated with the given provider side mac context \fImctx\fR and stores them +in \fIparams\fR. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_mac_gettable_params()\fR, \fBOSSL_FUNC_mac_gettable_ctx_params()\fR, +and \fBOSSL_FUNC_mac_settable_ctx_params()\fR all return constant \s-1\fBOSSL_PARAM\s0\fR\|(3) +arrays as descriptors of the parameters that \fBOSSL_FUNC_mac_get_params()\fR, +\&\fBOSSL_FUNC_mac_get_ctx_params()\fR, and \fBOSSL_FUNC_mac_set_ctx_params()\fR +can handle, respectively. \fBOSSL_FUNC_mac_gettable_ctx_params()\fR and +\&\fBOSSL_FUNC_mac_settable_ctx_params()\fR will return the parameters associated +with the provider side context \fImctx\fR in its current state if it is +not \s-1NULL.\s0 Otherwise, they return the parameters associated with the +provider side algorithm \fIprovctx\fR. +.PP +All \s-1MAC\s0 implementations are expected to handle the following parameters: +.IP "with \fBOSSL_FUNC_set_ctx_params()\fR:" 4 +.IX Item "with OSSL_FUNC_set_ctx_params():" +.RS 4 +.PD 0 +.ie n .IP """key"" (\fB\s-1OSSL_MAC_PARAM_KEY\s0\fR) <octet string>" 4 +.el .IP "``key'' (\fB\s-1OSSL_MAC_PARAM_KEY\s0\fR) <octet string>" 4 +.IX Item "key (OSSL_MAC_PARAM_KEY) <octet string>" +.PD +Sets the key in the associated \s-1MAC\s0 ctx. This is identical to passing a \fIkey\fR +argument to the \fBOSSL_FUNC_mac_init()\fR function. +.RE +.RS 4 +.RE +.IP "with \fBOSSL_FUNC_get_params()\fR:" 4 +.IX Item "with OSSL_FUNC_get_params():" +.RS 4 +.PD 0 +.ie n .IP """size"" (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <integer>" 4 +.el .IP "``size'' (\fB\s-1OSSL_MAC_PARAM_SIZE\s0\fR) <integer>" 4 +.IX Item "size (OSSL_MAC_PARAM_SIZE) <integer>" +.PD +Can be used to get the default \s-1MAC\s0 size (which might be the only allowable +\&\s-1MAC\s0 size for the implementation). +.Sp +Note that some implementations allow setting the size that the resulting \s-1MAC\s0 +should have as well, see the documentation of the implementation. +.RE +.RS 4 +.ie n .IP """size"" (\fB\s-1OSSL_MAC_PARAM_BLOCK_SIZE\s0\fR) <integer>" 4 +.el .IP "``size'' (\fB\s-1OSSL_MAC_PARAM_BLOCK_SIZE\s0\fR) <integer>" 4 +.IX Item "size (OSSL_MAC_PARAM_BLOCK_SIZE) <integer>" +Can be used to get the \s-1MAC\s0 block size (if supported by the algorithm). +.RE +.RS 4 +.RE +.SH "NOTES" +.IX Header "NOTES" +The \s-1MAC\s0 life-cycle is described in \fBlife_cycle\-rand\fR\|(7). Providers should +ensure that the various transitions listed there are supported. At some point +the \s-1EVP\s0 layer will begin enforcing the listed transitions. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_mac_newctx()\fR and \fBOSSL_FUNC_mac_dupctx()\fR should return the newly created +provider side mac context, or \s-1NULL\s0 on failure. +.PP +\&\fBOSSL_FUNC_mac_init()\fR, \fBOSSL_FUNC_mac_update()\fR, \fBOSSL_FUNC_mac_final()\fR, \fBOSSL_FUNC_mac_get_params()\fR, +\&\fBOSSL_FUNC_mac_get_ctx_params()\fR and \fBOSSL_FUNC_mac_set_ctx_params()\fR should return 1 for +success or 0 on error. +.PP +\&\fBOSSL_FUNC_mac_gettable_params()\fR, \fBOSSL_FUNC_mac_gettable_ctx_params()\fR and +\&\fBOSSL_FUNC_mac_settable_ctx_params()\fR should return a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) +array, or \s-1NULL\s0 if none is offered. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), +\&\s-1\fBEVP_MAC\-BLAKE2\s0\fR\|(7), \s-1\fBEVP_MAC\-CMAC\s0\fR\|(7), \s-1\fBEVP_MAC\-GMAC\s0\fR\|(7), +\&\s-1\fBEVP_MAC\-HMAC\s0\fR\|(7), \s-1\fBEVP_MAC\-KMAC\s0\fR\|(7), \fBEVP_MAC\-Poly1305\fR\|(7), +\&\fBEVP_MAC\-Siphash\fR\|(7), +\&\fBlife_cycle\-mac\fR\|(7), \s-1\fBEVP_MAC\s0\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +The provider \s-1MAC\s0 interface was introduced in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2019\-2022 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>. diff --git a/secure/lib/libcrypto/man/man7/provider-object.7 b/secure/lib/libcrypto/man/man7/provider-object.7 new file mode 100644 index 000000000000..bc7e9327f135 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/provider-object.7 @@ -0,0 +1,290 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "PROVIDER-OBJECT 7ossl" +.TH PROVIDER-OBJECT 7ossl "2023-09-19" "3.0.11" "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" +provider\-object \- A specification for a provider\-native object abstraction +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 2 +\& #include <openssl/core_object.h> +\& #include <openssl/core_names.h> +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The provider-native object abstraction is a set of \s-1\fBOSSL_PARAM\s0\fR\|(3) keys and +values that can be used to pass provider-native objects to OpenSSL library +code or between different provider operation implementations with the help +of OpenSSL library code. +.PP +The intention is that certain provider-native operations can pass any sort +of object that belong with other operations, or with OpenSSL library code. +.PP +An object may be passed in the following manners: +.IP "1." 4 +\&\fIBy value\fR +.Sp +This means that the \fIobject data\fR is passed as an octet string or an \s-1UTF8\s0 +string, which can be handled in diverse ways by other provided implementations. +The encoding of the object depends on the context it's used in; for example, +\&\s-1\fBOSSL_DECODER\s0\fR\|(3) allows multiple encodings, depending on existing decoders. +If central OpenSSL library functionality is to handle the data directly, it +\&\fBmust\fR be encoded in \s-1DER\s0 for all object types except for \fB\s-1OSSL_OBJECT_NAME\s0\fR +(see \*(L"Parameter reference\*(R" below), where it's assumed to a plain \s-1UTF8\s0 string. +.IP "2." 4 +\&\fIBy reference\fR +.Sp +This means that the \fIobject data\fR isn't passed directly, an \fIobject +reference\fR is passed instead. It's an octet string that only the correct +provider understands correctly. +.PP +Objects \fIby value\fR can be used by anything that handles \s-1DER\s0 encoded +objects. +.PP +Objects \fIby reference\fR need a higher level of cooperation from the +implementation where the object originated (let's call it X) and its target +implementation (let's call it Y): +.IP "1." 4 +\&\fIAn object loading function in the target implementation\fR +.Sp +The target implementation (Y) may have a function that can take an \fIobject +reference\fR. This can only be used if the target implementation is from the +same provider as the one originating the object abstraction in question (X). +.Sp +The exact target implementation to use is determined from the \fIobject type\fR +and possibly the \fIobject data type\fR. +For example, when the OpenSSL library receives an object abstraction with the +\&\fIobject type\fR \fB\s-1OSSL_OBJECT_PKEY\s0\fR, it will fetch a \fBprovider\-keymgmt\fR\|(7) +using the \fIobject data type\fR as its key type (the second argument in +\&\fBEVP_KEYMGMT_fetch\fR\|(3)). +.IP "2." 4 +\&\fIAn object exporter in the originating implementation\fR +.Sp +The originating implementation (X) may have an exporter function. This +exporter function can be used to export the object in \s-1\fBOSSL_PARAM\s0\fR\|(3) form, +that can then be imported by the target implementation's imported function. +.Sp +This can be used when it's not possible to fetch the target implementation +(Y) from the same provider. +.SS "Parameter reference" +.IX Subsection "Parameter reference" +A provider-native object abstraction is an \s-1\fBOSSL_PARAM\s0\fR\|(3) with a selection +of the following parameters: +.ie n .IP """data"" (\fB\s-1OSSL_OBJECT_PARAM_DATA\s0\fR) <octet string> or <\s-1UTF8\s0 string>" 4 +.el .IP "``data'' (\fB\s-1OSSL_OBJECT_PARAM_DATA\s0\fR) <octet string> or <\s-1UTF8\s0 string>" 4 +.IX Item "data (OSSL_OBJECT_PARAM_DATA) <octet string> or <UTF8 string>" +The object data \fIpassed by value\fR. +.ie n .IP """reference"" (\fB\s-1OSSL_OBJECT_PARAM_REFERENCE\s0\fR) <octet string>" 4 +.el .IP "``reference'' (\fB\s-1OSSL_OBJECT_PARAM_REFERENCE\s0\fR) <octet string>" 4 +.IX Item "reference (OSSL_OBJECT_PARAM_REFERENCE) <octet string>" +The object data \fIpassed by reference\fR. +.ie n .IP """type"" (\fB\s-1OSSL_OBJECT_PARAM_TYPE\s0\fR) <integer>" 4 +.el .IP "``type'' (\fB\s-1OSSL_OBJECT_PARAM_TYPE\s0\fR) <integer>" 4 +.IX Item "type (OSSL_OBJECT_PARAM_TYPE) <integer>" +The \fIobject type\fR, a number that may have any of the following values (all +defined in \fI<openssl/core_object.h>\fR): +.RS 4 +.IP "\fB\s-1OSSL_OBJECT_NAME\s0\fR" 4 +.IX Item "OSSL_OBJECT_NAME" +The object data may only be \fIpassed by value\fR, and should be a \s-1UTF8\s0 +string. +.Sp +This is useful for \fBprovider\-storemgmt\fR\|(7) when a \s-1URI\s0 load results in new +URIs. +.IP "\fB\s-1OSSL_OBJECT_PKEY\s0\fR" 4 +.IX Item "OSSL_OBJECT_PKEY" +The object data is suitable as provider-native \fB\s-1EVP_PKEY\s0\fR key data. The +object data may be \fIpassed by value\fR or \fIpassed by reference\fR. +.IP "\fB\s-1OSSL_OBJECT_CERT\s0\fR" 4 +.IX Item "OSSL_OBJECT_CERT" +The object data is suitable as \fBX509\fR data. The object data for this +object type can only be \fIpassed by value\fR, and should be an octet string. +.Sp +Since there's no provider-native X.509 object, OpenSSL libraries that +receive this object abstraction are expected to convert the data to a +\&\fBX509\fR object with \fBd2i_X509()\fR. +.IP "\fB\s-1OSSL_OBJECT_CRL\s0\fR" 4 +.IX Item "OSSL_OBJECT_CRL" +The object data is suitable as \fBX509_CRL\fR data. The object data can +only be \fIpassed by value\fR, and should be an octet string. +.Sp +Since there's no provider-native X.509 \s-1CRL\s0 object, OpenSSL libraries that +receive this object abstraction are expected to convert the data to a +\&\fBX509_CRL\fR object with \fBd2i_X509_CRL()\fR. +.RE +.RS 4 +.RE +.ie n .IP """data-type"" (\fB\s-1OSSL_OBJECT_PARAM_DATA_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``data-type'' (\fB\s-1OSSL_OBJECT_PARAM_DATA_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "data-type (OSSL_OBJECT_PARAM_DATA_TYPE) <UTF8 string>" +The specific type of the object content. Legitimate values depend on the +object type; if it is \fB\s-1OSSL_OBJECT_PKEY\s0\fR, the data type is expected to be a +key type suitable for fetching a \fBprovider\-keymgmt\fR\|(7) that can handle the +data. +.ie n .IP """data-structure"" (\fB\s-1OSSL_OBJECT_PARAM_DATA_STRUCTURE\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``data-structure'' (\fB\s-1OSSL_OBJECT_PARAM_DATA_STRUCTURE\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "data-structure (OSSL_OBJECT_PARAM_DATA_STRUCTURE) <UTF8 string>" +The outermost structure of the object content. Legitimate values depend on +the object type. +.ie n .IP """desc"" (\fB\s-1OSSL_OBJECT_PARAM_DESC\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``desc'' (\fB\s-1OSSL_OBJECT_PARAM_DESC\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "desc (OSSL_OBJECT_PARAM_DESC) <UTF8 string>" +A human readable text that describes extra details on the object. +.PP +When a provider-native object abstraction is used, it \fImust\fR contain object +data in at least one form (object data \fIpassed by value\fR, i.e. the \*(L"data\*(R" +item, or object data \fIpassed by reference\fR, i.e. the \*(L"reference\*(R" item). +Both may be present at once, in which case the OpenSSL library code that +receives this will use the most optimal variant. +.PP +For objects with the object type \fB\s-1OSSL_OBJECT_NAME\s0\fR, that object type +\&\fImust\fR be given. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), \s-1\fBOSSL_DECODER\s0\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +The concept of providers and everything surrounding them was +introduced in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2023 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>. diff --git a/secure/lib/libcrypto/man/man7/provider-rand.7 b/secure/lib/libcrypto/man/man7/provider-rand.7 new file mode 100644 index 000000000000..68a3f5551101 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/provider-rand.7 @@ -0,0 +1,427 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "PROVIDER-RAND 7ossl" +.TH PROVIDER-RAND 7ossl "2023-09-19" "3.0.11" "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" +provider\-rand \- The random number generation library <\-> provider +functions +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 2 +\& #include <openssl/core_dispatch.h> +\& #include <openssl/core_names.h> +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Context management */ +\& void *OSSL_FUNC_rand_newctx(void *provctx, void *parent, +\& const OSSL_DISPATCH *parent_calls); +\& void OSSL_FUNC_rand_freectx(void *ctx); +\& +\& /* Random number generator functions: NIST */ +\& int OSSL_FUNC_rand_instantiate(void *ctx, unsigned int strength, +\& int prediction_resistance, +\& const unsigned char *pstr, size_t pstr_len, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_rand_uninstantiate(void *ctx); +\& int OSSL_FUNC_rand_generate(void *ctx, unsigned char *out, size_t outlen, +\& unsigned int strength, int prediction_resistance, +\& const unsigned char *addin, size_t addin_len); +\& int OSSL_FUNC_rand_reseed(void *ctx, int prediction_resistance, +\& const unsigned char *ent, size_t ent_len, +\& const unsigned char *addin, size_t addin_len); +\& +\& /* Random number generator functions: additional */ +\& size_t OSSL_FUNC_rand_nonce(void *ctx, unsigned char *out, size_t outlen, +\& int strength, size_t min_noncelen, +\& size_t max_noncelen); +\& size_t OSSL_FUNC_rand_get_seed(void *ctx, unsigned char **buffer, +\& int entropy, size_t min_len, size_t max_len, +\& int prediction_resistance, +\& const unsigned char *adin, size_t adin_len); +\& void OSSL_FUNC_rand_clear_seed(void *ctx, unsigned char *buffer, size_t b_len); +\& int OSSL_FUNC_rand_verify_zeroization(void *ctx); +\& +\& /* Context Locking */ +\& int OSSL_FUNC_rand_enable_locking(void *ctx); +\& int OSSL_FUNC_rand_lock(void *ctx); +\& void OSSL_FUNC_rand_unlock(void *ctx); +\& +\& /* RAND parameter descriptors */ +\& const OSSL_PARAM *OSSL_FUNC_rand_gettable_params(void *provctx); +\& const OSSL_PARAM *OSSL_FUNC_rand_gettable_ctx_params(void *ctx, void *provctx); +\& const OSSL_PARAM *OSSL_FUNC_rand_settable_ctx_params(void *ctx, void *provctx); +\& +\& /* RAND parameters */ +\& int OSSL_FUNC_rand_get_params(OSSL_PARAM params[]); +\& int OSSL_FUNC_rand_get_ctx_params(void *ctx, OSSL_PARAM params[]); +\& int OSSL_FUNC_rand_set_ctx_params(void *ctx, const OSSL_PARAM params[]); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7) +for further information. +.PP +The \s-1RAND\s0 operation enables providers to implement random number generation +algorithms and random number sources and make +them available to applications via the \s-1API\s0 function \s-1\fBEVP_RAND\s0\fR\|(3). +.SS "Context Management Functions" +.IX Subsection "Context Management Functions" +\&\fBOSSL_FUNC_rand_newctx()\fR should create and return a pointer to a provider side +structure for holding context information during a rand operation. +A pointer to this context will be passed back in a number of the other rand +operation function calls. +The parameter \fIprovctx\fR is the provider context generated during provider +initialisation (see \fBprovider\fR\|(7)). +The parameter \fIparent\fR specifies another rand instance to be used for +seeding purposes. If \s-1NULL\s0 and the specific instance supports it, the +operating system will be used for seeding. +The parameter \fIparent_calls\fR points to the dispatch table for \fIparent\fR. +Thus, the parent need not be from the same provider as the new instance. +.PP +\&\fBOSSL_FUNC_rand_freectx()\fR is passed a pointer to the provider side rand context in +the \fImctx\fR parameter. +If it receives \s-1NULL\s0 as \fIctx\fR value, it should not do anything other than +return. +This function should free any resources associated with that context. +.SS "Random Number Generator Functions: \s-1NIST\s0" +.IX Subsection "Random Number Generator Functions: NIST" +These functions correspond to those defined in \s-1NIST SP 800\-90A\s0 and \s-1SP 800\-90C.\s0 +.PP +\&\fBOSSL_FUNC_rand_instantiate()\fR is used to instantiate the \s-1DRBG\s0 \fIctx\fR at a requested +security \fIstrength\fR. In addition, \fIprediction_resistance\fR can be requested. +Additional input \fIaddin\fR of length \fIaddin_len\fR bytes can optionally +be provided. The parameters specified in \fIparams\fR configure the \s-1DRBG\s0 and these +should be processed before instantiation. +.PP +\&\fBOSSL_FUNC_rand_uninstantiate()\fR is used to uninstantiate the \s-1DRBG\s0 \fIctx\fR. After being +uninstantiated, a \s-1DRBG\s0 is unable to produce output until it is instantiated +anew. +.PP +\&\fBOSSL_FUNC_rand_generate()\fR is used to generate random bytes from the \s-1DRBG\s0 \fIctx\fR. +It will generate \fIoutlen\fR bytes placing them into the buffer pointed to by +\&\fIout\fR. The generated bytes will meet the specified security \fIstrength\fR and, +if \fIprediction_resistance\fR is true, the bytes will be produced after reseeding +from a live entropy source. Additional input \fIaddin\fR of length \fIaddin_len\fR +bytes can optionally be provided. +.SS "Random Number Generator Functions: Additional" +.IX Subsection "Random Number Generator Functions: Additional" +\&\fBOSSL_FUNC_rand_nonce()\fR is used to generate a nonce of the given \fIstrength\fR with a +length from \fImin_noncelen\fR to \fImax_noncelen\fR. If the output buffer \fIout\fR is +\&\s-1NULL,\s0 the length of the nonce should be returned. +.PP +\&\fBOSSL_FUNC_rand_get_seed()\fR is used by deterministic generators to obtain their +seeding material from their parent. The seed bytes will meet the specified +security level of \fIentropy\fR bits and there will be between \fImin_len\fR +and \fImax_len\fR inclusive bytes in total. If \fIprediction_resistance\fR is +true, the bytes will be produced from a live entropy source. Additional +input \fIaddin\fR of length \fIaddin_len\fR bytes can optionally be provided. +A pointer to the seed material is returned in \fI*buffer\fR and this must be +freed by a later call to \fBOSSL_FUNC_rand_clear_seed()\fR. +.PP +\&\fBOSSL_FUNC_rand_clear_seed()\fR frees a seed \fIbuffer\fR of length \fIb_len\fR bytes +which was previously allocated by \fBOSSL_FUNC_rand_get_seed()\fR. +.PP +\&\fBOSSL_FUNC_rand_verify_zeroization()\fR is used to determine if the internal state of the +\&\s-1DRBG\s0 is zero. This capability is mandated by \s-1NIST\s0 as part of the self +tests, it is unlikely to be useful in other circumstances. +.SS "Context Locking" +.IX Subsection "Context Locking" +When DRBGs are used by multiple threads, there must be locking employed to +ensure their proper operation. Because locking introduces an overhead, it +is disabled by default. +.PP +\&\fBOSSL_FUNC_rand_enable_locking()\fR allows locking to be turned on for a \s-1DRBG\s0 and all of +its parent DRBGs. From this call onwards, the \s-1DRBG\s0 can be used in a thread +safe manner. +.PP +\&\fBOSSL_FUNC_rand_lock()\fR is used to lock a \s-1DRBG.\s0 Once locked, exclusive access +is guaranteed. +.PP +\&\fBOSSL_FUNC_rand_unlock()\fR is used to unlock a \s-1DRBG.\s0 +.SS "Rand Parameters" +.IX Subsection "Rand Parameters" +See \s-1\fBOSSL_PARAM\s0\fR\|(3) for further details on the parameters structure used by +these functions. +.PP +\&\fBOSSL_FUNC_rand_get_params()\fR gets details of parameter values associated with the +provider algorithm and stores them in \fIparams\fR. +.PP +\&\fBOSSL_FUNC_rand_set_ctx_params()\fR sets rand parameters associated with the given +provider side rand context \fIctx\fR to \fIparams\fR. +Any parameter settings are additional to any that were previously set. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_rand_get_ctx_params()\fR gets details of currently set parameter values +associated with the given provider side rand context \fIctx\fR and stores them +in \fIparams\fR. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_rand_gettable_params()\fR, \fBOSSL_FUNC_rand_gettable_ctx_params()\fR, +and \fBOSSL_FUNC_rand_settable_ctx_params()\fR all return constant \s-1\fBOSSL_PARAM\s0\fR\|(3) +arrays as descriptors of the parameters that \fBOSSL_FUNC_rand_get_params()\fR, +\&\fBOSSL_FUNC_rand_get_ctx_params()\fR, and \fBOSSL_FUNC_rand_set_ctx_params()\fR +can handle, respectively. \fBOSSL_FUNC_rand_gettable_ctx_params()\fR +and \fBOSSL_FUNC_rand_settable_ctx_params()\fR will return the parameters +associated with the provider side context \fIctx\fR in its current state +if it is not \s-1NULL.\s0 Otherwise, they return the parameters associated +with the provider side algorithm \fIprovctx\fR. +.PP +Parameters currently recognised by built-in rands are as follows. Not all +parameters are relevant to, or are understood by all rands: +.ie n .IP """state"" (\fB\s-1OSSL_RAND_PARAM_STATE\s0\fR) <integer>" 4 +.el .IP "``state'' (\fB\s-1OSSL_RAND_PARAM_STATE\s0\fR) <integer>" 4 +.IX Item "state (OSSL_RAND_PARAM_STATE) <integer>" +Returns the state of the random number generator. +.ie n .IP """strength"" (\fB\s-1OSSL_RAND_PARAM_STRENGTH\s0\fR) <unsigned integer>" 4 +.el .IP "``strength'' (\fB\s-1OSSL_RAND_PARAM_STRENGTH\s0\fR) <unsigned integer>" 4 +.IX Item "strength (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>" +Returns the bit strength of the random number generator. +.PP +For rands that are also deterministic random bit generators (DRBGs), these +additional parameters are recognised. Not all +parameters are relevant to, or are understood by all \s-1DRBG\s0 rands: +.ie n .IP """reseed_requests"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_REQUESTS\s0\fR) <unsigned integer>" 4 +.el .IP "``reseed_requests'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_REQUESTS\s0\fR) <unsigned integer>" 4 +.IX Item "reseed_requests (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>" +Reads or set the number of generate requests before reseeding the +associated \s-1RAND\s0 ctx. +.ie n .IP """reseed_time_interval"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL\s0\fR) <integer>" 4 +.el .IP "``reseed_time_interval'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL\s0\fR) <integer>" 4 +.IX Item "reseed_time_interval (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <integer>" +Reads or set the number of elapsed seconds before reseeding the +associated \s-1RAND\s0 ctx. +.ie n .IP """max_request"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_REQUESTS\s0\fR) <unsigned integer>" 4 +.el .IP "``max_request'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_REQUESTS\s0\fR) <unsigned integer>" 4 +.IX Item "max_request (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>" +Specifies the maximum number of bytes that can be generated in a single +call to OSSL_FUNC_rand_generate. +.ie n .IP """min_entropylen"" (\fB\s-1OSSL_DRBG_PARAM_MIN_ENTROPYLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``min_entropylen'' (\fB\s-1OSSL_DRBG_PARAM_MIN_ENTROPYLEN\s0\fR) <unsigned integer>" 4 +.IX Item "min_entropylen (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>" +.PD 0 +.ie n .IP """max_entropylen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_ENTROPYLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``max_entropylen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_ENTROPYLEN\s0\fR) <unsigned integer>" 4 +.IX Item "max_entropylen (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>" +.PD +Specify the minimum and maximum number of bytes of random material that +can be used to seed the \s-1DRBG.\s0 +.ie n .IP """min_noncelen"" (\fB\s-1OSSL_DRBG_PARAM_MIN_NONCELEN\s0\fR) <unsigned integer>" 4 +.el .IP "``min_noncelen'' (\fB\s-1OSSL_DRBG_PARAM_MIN_NONCELEN\s0\fR) <unsigned integer>" 4 +.IX Item "min_noncelen (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>" +.PD 0 +.ie n .IP """max_noncelen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_NONCELEN\s0\fR) <unsigned integer>" 4 +.el .IP "``max_noncelen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_NONCELEN\s0\fR) <unsigned integer>" 4 +.IX Item "max_noncelen (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>" +.PD +Specify the minimum and maximum number of bytes of nonce that can be used to +instantiate the \s-1DRBG.\s0 +.ie n .IP """max_perslen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_PERSLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``max_perslen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_PERSLEN\s0\fR) <unsigned integer>" 4 +.IX Item "max_perslen (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>" +.PD 0 +.ie n .IP """max_adinlen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_ADINLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``max_adinlen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_ADINLEN\s0\fR) <unsigned integer>" 4 +.IX Item "max_adinlen (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>" +.PD +Specify the minimum and maximum number of bytes of personalisation string +that can be used with the \s-1DRBG.\s0 +.ie n .IP """reseed_counter"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_COUNTER\s0\fR) <unsigned integer>" 4 +.el .IP "``reseed_counter'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_COUNTER\s0\fR) <unsigned integer>" 4 +.IX Item "reseed_counter (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>" +Specifies the number of times the \s-1DRBG\s0 has been seeded or reseeded. +.ie n .IP """digest"" (\fB\s-1OSSL_DRBG_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_DRBG_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_DRBG_PARAM_DIGEST) <UTF8 string>" +.PD 0 +.ie n .IP """cipher"" (\fB\s-1OSSL_DRBG_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``cipher'' (\fB\s-1OSSL_DRBG_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "cipher (OSSL_DRBG_PARAM_CIPHER) <UTF8 string>" +.ie n .IP """mac"" (\fB\s-1OSSL_DRBG_PARAM_MAC\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``mac'' (\fB\s-1OSSL_DRBG_PARAM_MAC\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "mac (OSSL_DRBG_PARAM_MAC) <UTF8 string>" +.PD +Sets the name of the underlying cipher, digest or \s-1MAC\s0 to be used. +It must name a suitable algorithm for the \s-1DRBG\s0 that's being used. +.ie n .IP """properties"" (\fB\s-1OSSL_DRBG_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_DRBG_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_DRBG_PARAM_PROPERTIES) <UTF8 string>" +Sets the properties to be queried when trying to fetch an underlying algorithm. +This must be given together with the algorithm naming parameter to be +considered valid. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_rand_newctx()\fR should return the newly created +provider side rand context, or \s-1NULL\s0 on failure. +.PP +\&\fBOSSL_FUNC_rand_gettable_params()\fR, \fBOSSL_FUNC_rand_gettable_ctx_params()\fR and +\&\fBOSSL_FUNC_rand_settable_ctx_params()\fR should return a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) +array, or \s-1NULL\s0 if none is offered. +.PP +\&\fBOSSL_FUNC_rand_nonce()\fR returns the size of the generated nonce, or 0 on error. +.PP +\&\fBOSSL_FUNC_rand_get_seed()\fR returns the size of the generated seed, or 0 on +error. +.PP +All of the remaining functions should return 1 for success or 0 on error. +.SH "NOTES" +.IX Header "NOTES" +The \s-1RAND\s0 life-cycle is described in \fBlife_cycle\-rand\fR\|(7). Providers should +ensure that the various transitions listed there are supported. At some point +the \s-1EVP\s0 layer will begin enforcing the listed transitions. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), +\&\s-1\fBRAND\s0\fR\|(7), +\&\s-1\fBEVP_RAND\s0\fR\|(7), +\&\fBlife_cycle\-rand\fR\|(7), +\&\s-1\fBEVP_RAND\s0\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +The provider \s-1RAND\s0 interface was introduced in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2021 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>. diff --git a/secure/lib/libcrypto/man/man7/provider-signature.7 b/secure/lib/libcrypto/man/man7/provider-signature.7 new file mode 100644 index 000000000000..a103884360b7 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/provider-signature.7 @@ -0,0 +1,556 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "PROVIDER-SIGNATURE 7ossl" +.TH PROVIDER-SIGNATURE 7ossl "2023-09-19" "3.0.11" "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" +provider\-signature \- The signature library <\-> provider functions +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 2 +\& #include <openssl/core_dispatch.h> +\& #include <openssl/core_names.h> +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Context management */ +\& void *OSSL_FUNC_signature_newctx(void *provctx, const char *propq); +\& void OSSL_FUNC_signature_freectx(void *ctx); +\& void *OSSL_FUNC_signature_dupctx(void *ctx); +\& +\& /* Signing */ +\& int OSSL_FUNC_signature_sign_init(void *ctx, void *provkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_signature_sign(void *ctx, unsigned char *sig, size_t *siglen, +\& size_t sigsize, const unsigned char *tbs, size_t tbslen); +\& +\& /* Verifying */ +\& int OSSL_FUNC_signature_verify_init(void *ctx, void *provkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_signature_verify(void *ctx, const unsigned char *sig, size_t siglen, +\& const unsigned char *tbs, size_t tbslen); +\& +\& /* Verify Recover */ +\& int OSSL_FUNC_signature_verify_recover_init(void *ctx, void *provkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_signature_verify_recover(void *ctx, unsigned char *rout, +\& size_t *routlen, size_t routsize, +\& const unsigned char *sig, size_t siglen); +\& +\& /* Digest Sign */ +\& int OSSL_FUNC_signature_digest_sign_init(void *ctx, const char *mdname, +\& void *provkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_signature_digest_sign_update(void *ctx, const unsigned char *data, +\& size_t datalen); +\& int OSSL_FUNC_signature_digest_sign_final(void *ctx, unsigned char *sig, +\& size_t *siglen, size_t sigsize); +\& int OSSL_FUNC_signature_digest_sign(void *ctx, +\& unsigned char *sigret, size_t *siglen, +\& size_t sigsize, const unsigned char *tbs, +\& size_t tbslen); +\& +\& /* Digest Verify */ +\& int OSSL_FUNC_signature_digest_verify_init(void *ctx, const char *mdname, +\& void *provkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_signature_digest_verify_update(void *ctx, +\& const unsigned char *data, +\& size_t datalen); +\& int OSSL_FUNC_signature_digest_verify_final(void *ctx, const unsigned char *sig, +\& size_t siglen); +\& int OSSL_FUNC_signature_digest_verify(void *ctx, const unsigned char *sig, +\& size_t siglen, const unsigned char *tbs, +\& size_t tbslen); +\& +\& /* Signature parameters */ +\& int OSSL_FUNC_signature_get_ctx_params(void *ctx, OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_signature_gettable_ctx_params(void *ctx, +\& void *provctx); +\& int OSSL_FUNC_signature_set_ctx_params(void *ctx, const OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_signature_settable_ctx_params(void *ctx, +\& void *provctx); +\& /* MD parameters */ +\& int OSSL_FUNC_signature_get_ctx_md_params(void *ctx, OSSL_PARAM params[]); +\& const OSSL_PARAM * OSSL_FUNC_signature_gettable_ctx_md_params(void *ctx); +\& int OSSL_FUNC_signature_set_ctx_md_params(void *ctx, const OSSL_PARAM params[]); +\& const OSSL_PARAM * OSSL_FUNC_signature_settable_ctx_md_params(void *ctx); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7) +for further information. +.PP +The signature (\s-1OSSL_OP_SIGNATURE\s0) operation enables providers to implement +signature algorithms and make them available to applications via the \s-1API\s0 +functions \fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify\fR\|(3), +and \fBEVP_PKEY_verify_recover\fR\|(3) (as well +as other related functions). +.PP +All \*(L"functions\*(R" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays via +\&\s-1\fBOSSL_ALGORITHM\s0\fR\|(3) arrays that are returned by the provider's +\&\fBprovider_query_operation()\fR function +(see \*(L"Provider Functions\*(R" in \fBprovider\-base\fR\|(7)). +.PP +All these \*(L"functions\*(R" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from an \s-1\fBOSSL_DISPATCH\s0\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the \*(L"function\*(R" \fBOSSL_FUNC_signature_newctx()\fR has these: +.PP +.Vb 3 +\& typedef void *(OSSL_FUNC_signature_newctx_fn)(void *provctx, const char *propq); +\& static ossl_inline OSSL_FUNC_signature_newctx_fn +\& OSSL_FUNC_signature_newctx(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 3 +\& OSSL_FUNC_signature_newctx OSSL_FUNC_SIGNATURE_NEWCTX +\& OSSL_FUNC_signature_freectx OSSL_FUNC_SIGNATURE_FREECTX +\& OSSL_FUNC_signature_dupctx OSSL_FUNC_SIGNATURE_DUPCTX +\& +\& OSSL_FUNC_signature_sign_init OSSL_FUNC_SIGNATURE_SIGN_INIT +\& OSSL_FUNC_signature_sign OSSL_FUNC_SIGNATURE_SIGN +\& +\& OSSL_FUNC_signature_verify_init OSSL_FUNC_SIGNATURE_VERIFY_INIT +\& OSSL_FUNC_signature_verify OSSL_FUNC_SIGNATURE_VERIFY +\& +\& OSSL_FUNC_signature_verify_recover_init OSSL_FUNC_SIGNATURE_VERIFY_RECOVER_INIT +\& OSSL_FUNC_signature_verify_recover OSSL_FUNC_SIGNATURE_VERIFY_RECOVER +\& +\& OSSL_FUNC_signature_digest_sign_init OSSL_FUNC_SIGNATURE_DIGEST_SIGN_INIT +\& OSSL_FUNC_signature_digest_sign_update OSSL_FUNC_SIGNATURE_DIGEST_SIGN_UPDATE +\& OSSL_FUNC_signature_digest_sign_final OSSL_FUNC_SIGNATURE_DIGEST_SIGN_FINAL +\& OSSL_FUNC_signature_digest_sign OSSL_FUNC_SIGNATURE_DIGEST_SIGN +\& +\& OSSL_FUNC_signature_digest_verify_init OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_INIT +\& OSSL_FUNC_signature_digest_verify_update OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_UPDATE +\& OSSL_FUNC_signature_digest_verify_final OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_FINAL +\& OSSL_FUNC_signature_digest_verify OSSL_FUNC_SIGNATURE_DIGEST_VERIFY +\& +\& OSSL_FUNC_signature_get_ctx_params OSSL_FUNC_SIGNATURE_GET_CTX_PARAMS +\& OSSL_FUNC_signature_gettable_ctx_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_PARAMS +\& OSSL_FUNC_signature_set_ctx_params OSSL_FUNC_SIGNATURE_SET_CTX_PARAMS +\& OSSL_FUNC_signature_settable_ctx_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_PARAMS +\& +\& OSSL_FUNC_signature_get_ctx_md_params OSSL_FUNC_SIGNATURE_GET_CTX_MD_PARAMS +\& OSSL_FUNC_signature_gettable_ctx_md_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_MD_PARAMS +\& OSSL_FUNC_signature_set_ctx_md_params OSSL_FUNC_SIGNATURE_SET_CTX_MD_PARAMS +\& OSSL_FUNC_signature_settable_ctx_md_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_MD_PARAMS +.Ve +.PP +A signature algorithm implementation may not implement all of these functions. +In order to be a consistent set of functions we must have at least a set of +context functions (OSSL_FUNC_signature_newctx and OSSL_FUNC_signature_freectx) as well as a +set of \*(L"signature\*(R" functions, i.e. at least one of: +.IP "OSSL_FUNC_signature_sign_init and OSSL_FUNC_signature_sign" 4 +.IX Item "OSSL_FUNC_signature_sign_init and OSSL_FUNC_signature_sign" +.PD 0 +.IP "OSSL_FUNC_signature_verify_init and OSSL_FUNC_signature_verify" 4 +.IX Item "OSSL_FUNC_signature_verify_init and OSSL_FUNC_signature_verify" +.IP "OSSL_FUNC_signature_verify_recover_init and OSSL_FUNC_signature_verify_recover" 4 +.IX Item "OSSL_FUNC_signature_verify_recover_init and OSSL_FUNC_signature_verify_recover" +.IP "OSSL_FUNC_signature_digest_sign_init, OSSL_FUNC_signature_digest_sign_update and OSSL_FUNC_signature_digest_sign_final" 4 +.IX Item "OSSL_FUNC_signature_digest_sign_init, OSSL_FUNC_signature_digest_sign_update and OSSL_FUNC_signature_digest_sign_final" +.IP "OSSL_FUNC_signature_digest_verify_init, OSSL_FUNC_signature_digest_verify_update and OSSL_FUNC_signature_digest_verify_final" 4 +.IX Item "OSSL_FUNC_signature_digest_verify_init, OSSL_FUNC_signature_digest_verify_update and OSSL_FUNC_signature_digest_verify_final" +.IP "OSSL_FUNC_signature_digest_sign_init and OSSL_FUNC_signature_digest_sign" 4 +.IX Item "OSSL_FUNC_signature_digest_sign_init and OSSL_FUNC_signature_digest_sign" +.IP "OSSL_FUNC_signature_digest_verify_init and OSSL_FUNC_signature_digest_verify" 4 +.IX Item "OSSL_FUNC_signature_digest_verify_init and OSSL_FUNC_signature_digest_verify" +.PD +.PP +OSSL_FUNC_signature_set_ctx_params and OSSL_FUNC_signature_settable_ctx_params are optional, +but if one of them is present then the other one must also be present. The same +applies to OSSL_FUNC_signature_get_ctx_params and OSSL_FUNC_signature_gettable_ctx_params, as +well as the \*(L"md_params\*(R" functions. The OSSL_FUNC_signature_dupctx function is optional. +.PP +A signature algorithm must also implement some mechanism for generating, +loading or importing keys via the key management (\s-1OSSL_OP_KEYMGMT\s0) operation. +See \fBprovider\-keymgmt\fR\|(7) for further details. +.SS "Context Management Functions" +.IX Subsection "Context Management Functions" +\&\fBOSSL_FUNC_signature_newctx()\fR should create and return a pointer to a provider side +structure for holding context information during a signature operation. +A pointer to this context will be passed back in a number of the other signature +operation function calls. +The parameter \fIprovctx\fR is the provider context generated during provider +initialisation (see \fBprovider\fR\|(7)). The \fIpropq\fR parameter is a property query +string that may be (optionally) used by the provider during any \*(L"fetches\*(R" that +it may perform (if it performs any). +.PP +\&\fBOSSL_FUNC_signature_freectx()\fR is passed a pointer to the provider side signature +context in the \fIctx\fR parameter. +This function should free any resources associated with that context. +.PP +\&\fBOSSL_FUNC_signature_dupctx()\fR should duplicate the provider side signature context in +the \fIctx\fR parameter and return the duplicate copy. +.SS "Signing Functions" +.IX Subsection "Signing Functions" +\&\fBOSSL_FUNC_signature_sign_init()\fR initialises a context for signing given a provider side +signature context in the \fIctx\fR parameter, and a pointer to a provider key object +in the \fIprovkey\fR parameter. +The \fIparams\fR, if not \s-1NULL,\s0 should be set on the context in a manner similar to +using \fBOSSL_FUNC_signature_set_ctx_params()\fR. +The key object should have been previously generated, loaded or imported into +the provider using the key management (\s-1OSSL_OP_KEYMGMT\s0) operation (see +\&\fBprovider\-keymgmt\fR\|(7)>. +.PP +\&\fBOSSL_FUNC_signature_sign()\fR performs the actual signing itself. +A previously initialised signature context is passed in the \fIctx\fR +parameter. +The data to be signed is pointed to be the \fItbs\fR parameter which is \fItbslen\fR +bytes long. +Unless \fIsig\fR is \s-1NULL,\s0 the signature should be written to the location pointed +to by the \fIsig\fR parameter and it should not exceed \fIsigsize\fR bytes in length. +The length of the signature should be written to \fI*siglen\fR. +If \fIsig\fR is \s-1NULL\s0 then the maximum length of the signature should be written to +\&\fI*siglen\fR. +.SS "Verify Functions" +.IX Subsection "Verify Functions" +\&\fBOSSL_FUNC_signature_verify_init()\fR initialises a context for verifying a signature given +a provider side signature context in the \fIctx\fR parameter, and a pointer to a +provider key object in the \fIprovkey\fR parameter. +The \fIparams\fR, if not \s-1NULL,\s0 should be set on the context in a manner similar to +using \fBOSSL_FUNC_signature_set_ctx_params()\fR. +The key object should have been previously generated, loaded or imported into +the provider using the key management (\s-1OSSL_OP_KEYMGMT\s0) operation (see +\&\fBprovider\-keymgmt\fR\|(7)>. +.PP +\&\fBOSSL_FUNC_signature_verify()\fR performs the actual verification itself. +A previously initialised signature context is passed in the \fIctx\fR parameter. +The data that the signature covers is pointed to be the \fItbs\fR parameter which +is \fItbslen\fR bytes long. +The signature is pointed to by the \fIsig\fR parameter which is \fIsiglen\fR bytes +long. +.SS "Verify Recover Functions" +.IX Subsection "Verify Recover Functions" +\&\fBOSSL_FUNC_signature_verify_recover_init()\fR initialises a context for recovering the +signed data given a provider side signature context in the \fIctx\fR parameter, and +a pointer to a provider key object in the \fIprovkey\fR parameter. +The \fIparams\fR, if not \s-1NULL,\s0 should be set on the context in a manner similar to +using \fBOSSL_FUNC_signature_set_ctx_params()\fR. +The key object should have been previously generated, loaded or imported into +the provider using the key management (\s-1OSSL_OP_KEYMGMT\s0) operation (see +\&\fBprovider\-keymgmt\fR\|(7)>. +.PP +\&\fBOSSL_FUNC_signature_verify_recover()\fR performs the actual verify recover itself. +A previously initialised signature context is passed in the \fIctx\fR parameter. +The signature is pointed to by the \fIsig\fR parameter which is \fIsiglen\fR bytes +long. +Unless \fIrout\fR is \s-1NULL,\s0 the recovered data should be written to the location +pointed to by \fIrout\fR which should not exceed \fIroutsize\fR bytes in length. +The length of the recovered data should be written to \fI*routlen\fR. +If \fIrout\fR is \s-1NULL\s0 then the maximum size of the output buffer is written to +the \fIroutlen\fR parameter. +.SS "Digest Sign Functions" +.IX Subsection "Digest Sign Functions" +\&\fBOSSL_FUNC_signature_digeset_sign_init()\fR initialises a context for signing given a +provider side signature context in the \fIctx\fR parameter, and a pointer to a +provider key object in the \fIprovkey\fR parameter. +The \fIparams\fR, if not \s-1NULL,\s0 should be set on the context in a manner similar to +using \fBOSSL_FUNC_signature_set_ctx_params()\fR and +\&\fBOSSL_FUNC_signature_set_ctx_md_params()\fR. +The key object should have been +previously generated, loaded or imported into the provider using the +key management (\s-1OSSL_OP_KEYMGMT\s0) operation (see \fBprovider\-keymgmt\fR\|(7)>. +The name of the digest to be used will be in the \fImdname\fR parameter. +.PP +\&\fBOSSL_FUNC_signature_digest_sign_update()\fR provides data to be signed in the \fIdata\fR +parameter which should be of length \fIdatalen\fR. A previously initialised +signature context is passed in the \fIctx\fR parameter. This function may be called +multiple times to cumulatively add data to be signed. +.PP +\&\fBOSSL_FUNC_signature_digest_sign_final()\fR finalises a signature operation previously +started through \fBOSSL_FUNC_signature_digest_sign_init()\fR and +\&\fBOSSL_FUNC_signature_digest_sign_update()\fR calls. Once finalised no more data will be +added through \fBOSSL_FUNC_signature_digest_sign_update()\fR. A previously initialised +signature context is passed in the \fIctx\fR parameter. Unless \fIsig\fR is \s-1NULL,\s0 the +signature should be written to the location pointed to by the \fIsig\fR parameter +and it should not exceed \fIsigsize\fR bytes in length. The length of the signature +should be written to \fI*siglen\fR. If \fIsig\fR is \s-1NULL\s0 then the maximum length of +the signature should be written to \fI*siglen\fR. +.PP +\&\fBOSSL_FUNC_signature_digest_sign()\fR implements a \*(L"one shot\*(R" digest sign operation +previously started through \fBOSSL_FUNC_signature_digeset_sign_init()\fR. A previously +initialised signature context is passed in the \fIctx\fR parameter. The data to be +signed is in \fItbs\fR which should be \fItbslen\fR bytes long. Unless \fIsig\fR is \s-1NULL,\s0 +the signature should be written to the location pointed to by the \fIsig\fR +parameter and it should not exceed \fIsigsize\fR bytes in length. The length of the +signature should be written to \fI*siglen\fR. If \fIsig\fR is \s-1NULL\s0 then the maximum +length of the signature should be written to \fI*siglen\fR. +.SS "Digest Verify Functions" +.IX Subsection "Digest Verify Functions" +\&\fBOSSL_FUNC_signature_digeset_verify_init()\fR initialises a context for verifying given a +provider side verification context in the \fIctx\fR parameter, and a pointer to a +provider key object in the \fIprovkey\fR parameter. +The \fIparams\fR, if not \s-1NULL,\s0 should be set on the context in a manner similar to +\&\fBOSSL_FUNC_signature_set_ctx_params()\fR and +\&\fBOSSL_FUNC_signature_set_ctx_md_params()\fR. +The key object should have been +previously generated, loaded or imported into the provider using the +key management (\s-1OSSL_OP_KEYMGMT\s0) operation (see \fBprovider\-keymgmt\fR\|(7)>. +The name of the digest to be used will be in the \fImdname\fR parameter. +.PP +\&\fBOSSL_FUNC_signature_digest_verify_update()\fR provides data to be verified in the \fIdata\fR +parameter which should be of length \fIdatalen\fR. A previously initialised +verification context is passed in the \fIctx\fR parameter. This function may be +called multiple times to cumulatively add data to be verified. +.PP +\&\fBOSSL_FUNC_signature_digest_verify_final()\fR finalises a verification operation previously +started through \fBOSSL_FUNC_signature_digest_verify_init()\fR and +\&\fBOSSL_FUNC_signature_digest_verify_update()\fR calls. Once finalised no more data will be +added through \fBOSSL_FUNC_signature_digest_verify_update()\fR. A previously initialised +verification context is passed in the \fIctx\fR parameter. The signature to be +verified is in \fIsig\fR which is \fIsiglen\fR bytes long. +.PP +\&\fBOSSL_FUNC_signature_digest_verify()\fR implements a \*(L"one shot\*(R" digest verify operation +previously started through \fBOSSL_FUNC_signature_digeset_verify_init()\fR. A previously +initialised verification context is passed in the \fIctx\fR parameter. The data to be +verified is in \fItbs\fR which should be \fItbslen\fR bytes long. The signature to be +verified is in \fIsig\fR which is \fIsiglen\fR bytes long. +.SS "Signature parameters" +.IX Subsection "Signature parameters" +See \s-1\fBOSSL_PARAM\s0\fR\|(3) for further details on the parameters structure used by +the \fBOSSL_FUNC_signature_get_ctx_params()\fR and \fBOSSL_FUNC_signature_set_ctx_params()\fR functions. +.PP +\&\fBOSSL_FUNC_signature_get_ctx_params()\fR gets signature parameters associated with the +given provider side signature context \fIctx\fR and stored them in \fIparams\fR. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_signature_set_ctx_params()\fR sets the signature parameters associated with the +given provider side signature context \fIctx\fR to \fIparams\fR. +Any parameter settings are additional to any that were previously set. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +Common parameters currently recognised by built-in signature algorithms are as +follows. +.ie n .IP """digest"" (\fB\s-1OSSL_SIGNATURE_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_SIGNATURE_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_SIGNATURE_PARAM_DIGEST) <UTF8 string>" +Get or sets the name of the digest algorithm used for the input to the +signature functions. It is required in order to calculate the \*(L"algorithm-id\*(R". +.ie n .IP """properties"" (\fB\s-1OSSL_SIGNATURE_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``properties'' (\fB\s-1OSSL_SIGNATURE_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "properties (OSSL_SIGNATURE_PARAM_PROPERTIES) <UTF8 string>" +Sets the name of the property query associated with the \*(L"digest\*(R" algorithm. +\&\s-1NULL\s0 is used if this optional value is not set. +.ie n .IP """digest-size"" (\fB\s-1OSSL_SIGNATURE_PARAM_DIGEST_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``digest-size'' (\fB\s-1OSSL_SIGNATURE_PARAM_DIGEST_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "digest-size (OSSL_SIGNATURE_PARAM_DIGEST_SIZE) <unsigned integer>" +Gets or sets the output size of the digest algorithm used for the input to the +signature functions. +The length of the \*(L"digest-size\*(R" parameter should not exceed that of a \fBsize_t\fR. +.ie n .IP """algorithm-id"" (\fB\s-1OSSL_SIGNATURE_PARAM_ALGORITHM_ID\s0\fR) <octet string>" 4 +.el .IP "``algorithm-id'' (\fB\s-1OSSL_SIGNATURE_PARAM_ALGORITHM_ID\s0\fR) <octet string>" 4 +.IX Item "algorithm-id (OSSL_SIGNATURE_PARAM_ALGORITHM_ID) <octet string>" +Gets the \s-1DER\s0 encoded AlgorithmIdentifier that corresponds to the combination of +signature algorithm and digest algorithm for the signature operation. +.ie n .IP """kat"" (\fB\s-1OSSL_SIGNATURE_PARAM_KAT\s0\fR) <unsigned integer>" 4 +.el .IP "``kat'' (\fB\s-1OSSL_SIGNATURE_PARAM_KAT\s0\fR) <unsigned integer>" 4 +.IX Item "kat (OSSL_SIGNATURE_PARAM_KAT) <unsigned integer>" +Sets a flag to modify the sign operation to return an error if the initial +calculated signature is invalid. +In the normal mode of operation \- new random values are chosen until the +signature operation succeeds. +By default it retries until a signature is calculated. +Setting the value to 0 causes the sign operation to retry, +otherwise the sign operation is only tried once and returns whether or not it +was successful. +Known answer tests can be performed if the random generator is overridden to +supply known values that either pass or fail. +.PP +\&\fBOSSL_FUNC_signature_gettable_ctx_params()\fR and \fBOSSL_FUNC_signature_settable_ctx_params()\fR get a +constant \s-1\fBOSSL_PARAM\s0\fR\|(3) array that describes the gettable and settable parameters, +i.e. parameters that can be used with \fBOSSL_FUNC_signature_get_ctx_params()\fR and +\&\fBOSSL_FUNC_signature_set_ctx_params()\fR respectively. +.SS "\s-1MD\s0 parameters" +.IX Subsection "MD parameters" +See \s-1\fBOSSL_PARAM\s0\fR\|(3) for further details on the parameters structure used by +the \fBOSSL_FUNC_signature_get_md_ctx_params()\fR and \fBOSSL_FUNC_signature_set_md_ctx_params()\fR +functions. +.PP +\&\fBOSSL_FUNC_signature_get_md_ctx_params()\fR gets digest parameters associated with the +given provider side digest signature context \fIctx\fR and stores them in \fIparams\fR. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_signature_set_ms_ctx_params()\fR sets the digest parameters associated with the +given provider side digest signature context \fIctx\fR to \fIparams\fR. +Any parameter settings are additional to any that were previously set. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +Parameters currently recognised by built-in signature algorithms are the same +as those for built-in digest algorithms. See +\&\*(L"Digest Parameters\*(R" in \fBprovider\-digest\fR\|(7) for further information. +.PP +\&\fBOSSL_FUNC_signature_gettable_md_ctx_params()\fR and \fBOSSL_FUNC_signature_settable_md_ctx_params()\fR +get a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) array that describes the gettable and settable +digest parameters, i.e. parameters that can be used with +\&\fBOSSL_FUNC_signature_get_md_ctx_params()\fR and \fBOSSL_FUNC_signature_set_md_ctx_params()\fR +respectively. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_signature_newctx()\fR and \fBOSSL_FUNC_signature_dupctx()\fR should return the newly created +provider side signature context, or \s-1NULL\s0 on failure. +.PP +\&\fBOSSL_FUNC_signature_gettable_ctx_params()\fR, \fBOSSL_FUNC_signature_settable_ctx_params()\fR, +\&\fBOSSL_FUNC_signature_gettable_md_ctx_params()\fR and \fBOSSL_FUNC_signature_settable_md_ctx_params()\fR, +return the gettable or settable parameters in a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) array. +.PP +All other functions should return 1 for success or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The provider \s-1SIGNATURE\s0 interface was introduced in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2019\-2023 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>. diff --git a/secure/lib/libcrypto/man/man7/provider-storemgmt.7 b/secure/lib/libcrypto/man/man7/provider-storemgmt.7 new file mode 100644 index 000000000000..11ccf5ec4fbb --- /dev/null +++ b/secure/lib/libcrypto/man/man7/provider-storemgmt.7 @@ -0,0 +1,330 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "PROVIDER-STOREMGMT 7ossl" +.TH PROVIDER-STOREMGMT 7ossl "2023-09-19" "3.0.11" "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" +provider\-storemgmt \- The OSSL_STORE library <\-> provider functions +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/core_dispatch.h> +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& void *OSSL_FUNC_store_open(void *provctx, const char *uri); +\& void *OSSL_FUNC_store_attach(void *provctx, OSSL_CORE_BIO *bio); +\& const OSSL_PARAM *store_settable_ctx_params(void *provctx); +\& int OSSL_FUNC_store_set_ctx_params(void *loaderctx, const OSSL_PARAM[]); +\& int OSSL_FUNC_store_load(void *loaderctx, +\& OSSL_CALLBACK *object_cb, void *object_cbarg, +\& OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg); +\& int OSSL_FUNC_store_eof(void *loaderctx); +\& int OSSL_FUNC_store_close(void *loaderctx); +\& +\& int OSSL_FUNC_store_export_object +\& (void *loaderctx, const void *objref, size_t objref_sz, +\& OSSL_CALLBACK *export_cb, void *export_cbarg); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \s-1STORE\s0 operation is the provider side of the \fBossl_store\fR\|(7) \s-1API.\s0 +.PP +The primary responsibility of the \s-1STORE\s0 operation is to load all sorts +of objects from a container indicated by \s-1URI.\s0 These objects are given +to the OpenSSL library in provider-native object abstraction form (see +\&\fBprovider\-object\fR\|(7)). The OpenSSL library is then responsible for +passing on that abstraction to suitable provided functions. +.PP +Examples of functions that the OpenSSL library can pass the abstraction to +include \fBOSSL_FUNC_keymgmt_load()\fR (\fBprovider\-keymgmt\fR\|(7)), +\&\fBOSSL_FUNC_store_export_object()\fR (which exports the object in parameterized +form). +.PP +All \*(L"functions\*(R" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays via +\&\s-1\fBOSSL_ALGORITHM\s0\fR\|(3) arrays that are returned by the provider's +\&\fBprovider_query_operation()\fR function +(see \*(L"Provider Functions\*(R" in \fBprovider\-base\fR\|(7)). +.PP +All these \*(L"functions\*(R" have a corresponding function type definition named +\&\fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the function pointer +from a \s-1\fBOSSL_DISPATCH\s0\fR\|(3) element named \fBOSSL_get_{name}\fR. +For example, the \*(L"function\*(R" \fBOSSL_FUNC_store_attach()\fR has these: +.PP +.Vb 4 +\& typedef void *(OSSL_FUNC_store_attach_fn)(void *provctx, +\& OSSL_CORE_BIO * bio); +\& static ossl_inline OSSL_FUNC_store_attach_fn +\& OSSL_FUNC_store_attach(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays are indexed by numbers that are provided as macros +in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 8 +\& OSSL_FUNC_store_open OSSL_FUNC_STORE_OPEN +\& OSSL_FUNC_store_attach OSSL_FUNC_STORE_ATTACH +\& OSSL_FUNC_store_settable_ctx_params OSSL_FUNC_STORE_SETTABLE_CTX_PARAMS +\& OSSL_FUNC_store_set_ctx_params OSSL_FUNC_STORE_SET_CTX_PARAMS +\& OSSL_FUNC_store_load OSSL_FUNC_STORE_LOAD +\& OSSL_FUNC_store_eof OSSL_FUNC_STORE_EOF +\& OSSL_FUNC_store_close OSSL_FUNC_STORE_CLOSE +\& OSSL_FUNC_store_export_object OSSL_FUNC_STORE_EXPORT_OBJECT +.Ve +.SS "Functions" +.IX Subsection "Functions" +\&\fBOSSL_FUNC_store_open()\fR should create a provider side context with data based +on the input \fIuri\fR. The implementation is entirely responsible for the +interpretation of the \s-1URI.\s0 +.PP +\&\fBOSSL_FUNC_store_attach()\fR should create a provider side context with the core +\&\fB\s-1BIO\s0\fR \fIbio\fR attached. This is an alternative to using a \s-1URI\s0 to find storage, +supporting \fBOSSL_STORE_attach\fR\|(3). +.PP +\&\fBOSSL_FUNC_store_settable_ctx_params()\fR should return a constant array of +descriptor \s-1\fBOSSL_PARAM\s0\fR\|(3), for parameters that \fBOSSL_FUNC_store_set_ctx_params()\fR +can handle. +.PP +\&\fBOSSL_FUNC_store_set_ctx_params()\fR should set additional parameters, such as what +kind of data to expect, search criteria, and so on. More on those below, in +\&\*(L"Load Parameters\*(R". Whether unrecognised parameters are an error or simply +ignored is at the implementation's discretion. +Passing \s-1NULL\s0 for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_store_load()\fR loads the next object from the \s-1URI\s0 opened by +\&\fBOSSL_FUNC_store_open()\fR, creates an object abstraction for it (see +\&\fBprovider\-object\fR\|(7)), and calls \fIobject_cb\fR with it as well as +\&\fIobject_cbarg\fR. \fIobject_cb\fR will then interpret the object abstraction +and do what it can to wrap it or decode it into an OpenSSL structure. In +case a passphrase needs to be prompted to unlock an object, \fIpw_cb\fR should +be called. +.PP +\&\fBOSSL_FUNC_store_eof()\fR indicates if the end of the set of objects from the +\&\s-1URI\s0 has been reached. When that happens, there's no point trying to do any +further loading. +.PP +\&\fBOSSL_FUNC_store_close()\fR frees the provider side context \fIctx\fR. +.PP +When a provider-native object is created by a store manager it would be unsuitable +for direct use with a foreign provider. The export function allows for +exporting the object to that foreign provider if the foreign provider +supports the type of the object and provides an import function. +.PP +\&\fBOSSL_FUNC_store_export_object()\fR should export the object of size \fIobjref_sz\fR +referenced by \fIobjref\fR as an \s-1\fBOSSL_PARAM\s0\fR\|(3) array and pass that to the +\&\fIexport_cb\fR as well as the given \fIexport_cbarg\fR. +.SS "Load Parameters" +.IX Subsection "Load Parameters" +.ie n .IP """expect"" (\fB\s-1OSSL_STORE_PARAM_EXPECT\s0\fR) <integer>" 4 +.el .IP "``expect'' (\fB\s-1OSSL_STORE_PARAM_EXPECT\s0\fR) <integer>" 4 +.IX Item "expect (OSSL_STORE_PARAM_EXPECT) <integer>" +Is a hint of what type of data the OpenSSL library expects to get. +This is only useful for optimization, as the library will check that the +object types match the expectation too. +.Sp +The number that can be given through this parameter is found in +\&\fI<openssl/store.h>\fR, with the macros having names starting with +\&\f(CW\*(C`OSSL_STORE_INFO_\*(C'\fR. These are further described in +\&\*(L"\s-1SUPPORTED OBJECTS\*(R"\s0 in \s-1\fBOSSL_STORE_INFO\s0\fR\|(3). +.ie n .IP """subject"" (\fB\s-1OSSL_STORE_PARAM_SUBJECT\s0\fR) <octet string>" 4 +.el .IP "``subject'' (\fB\s-1OSSL_STORE_PARAM_SUBJECT\s0\fR) <octet string>" 4 +.IX Item "subject (OSSL_STORE_PARAM_SUBJECT) <octet string>" +Indicates that the caller wants to search for an object with the given +subject associated. This can be used to select specific certificates +by subject. +.Sp +The contents of the octet string is expected to be in \s-1DER\s0 form. +.ie n .IP """issuer"" (\fB\s-1OSSL_STORE_PARAM_ISSUER\s0\fR) <octet string>" 4 +.el .IP "``issuer'' (\fB\s-1OSSL_STORE_PARAM_ISSUER\s0\fR) <octet string>" 4 +.IX Item "issuer (OSSL_STORE_PARAM_ISSUER) <octet string>" +Indicates that the caller wants to search for an object with the given +issuer associated. This can be used to select specific certificates +by issuer. +.Sp +The contents of the octet string is expected to be in \s-1DER\s0 form. +.ie n .IP """serial"" (\fB\s-1OSSL_STORE_PARAM_SERIAL\s0\fR) <integer>" 4 +.el .IP "``serial'' (\fB\s-1OSSL_STORE_PARAM_SERIAL\s0\fR) <integer>" 4 +.IX Item "serial (OSSL_STORE_PARAM_SERIAL) <integer>" +Indicates that the caller wants to search for an object with the given +serial number associated. +.ie n .IP """digest"" (\fB\s-1OSSL_STORE_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``digest'' (\fB\s-1OSSL_STORE_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "digest (OSSL_STORE_PARAM_DIGEST) <UTF8 string>" +.PD 0 +.ie n .IP """fingerprint"" (\fB\s-1OSSL_STORE_PARAM_FINGERPRINT\s0\fR) <octet string>" 4 +.el .IP "``fingerprint'' (\fB\s-1OSSL_STORE_PARAM_FINGERPRINT\s0\fR) <octet string>" 4 +.IX Item "fingerprint (OSSL_STORE_PARAM_FINGERPRINT) <octet string>" +.PD +Indicates that the caller wants to search for an object with the given +fingerprint, computed with the given digest. +.ie n .IP """alias"" (\fB\s-1OSSL_STORE_PARAM_ALIAS\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``alias'' (\fB\s-1OSSL_STORE_PARAM_ALIAS\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "alias (OSSL_STORE_PARAM_ALIAS) <UTF8 string>" +Indicates that the caller wants to search for an object with the given +alias (some call it a \*(L"friendly name\*(R"). +.ie n .IP """properties"" (\fB\s-1OSSL_STORE_PARAM_PROPERTIES\s0) <utf8 string\fR" 4 +.el .IP "``properties'' (\fB\s-1OSSL_STORE_PARAM_PROPERTIES\s0) <utf8 string\fR" 4 +.IX Item "properties (OSSL_STORE_PARAM_PROPERTIES) <utf8 string" +Property string to use when querying for algorithms such as the \fB\s-1OSSL_DECODER\s0\fR +decoder implementations. +.ie n .IP """input-type"" (\fB\s-1OSSL_STORE_PARAM_INPUT_TYPE\s0) <utf8 string\fR" 4 +.el .IP "``input-type'' (\fB\s-1OSSL_STORE_PARAM_INPUT_TYPE\s0) <utf8 string\fR" 4 +.IX Item "input-type (OSSL_STORE_PARAM_INPUT_TYPE) <utf8 string" +Type of the input format as a hint to use when decoding the objects in the +store. +.PP +Several of these search criteria may be combined. For example, to +search for a certificate by issuer+serial, both the \*(L"issuer\*(R" and the +\&\*(L"serial\*(R" parameters will be given. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The \s-1STORE\s0 interface was introduced in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2020\-2022 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>. diff --git a/secure/lib/libcrypto/man/man7/provider.7 b/secure/lib/libcrypto/man/man7/provider.7 new file mode 100644 index 000000000000..23a4ea979ce5 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/provider.7 @@ -0,0 +1,375 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" 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 >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 +.\" 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 "PROVIDER 7ossl" +.TH PROVIDER 7ossl "2023-09-19" "3.0.11" "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" +provider \- OpenSSL operation implementation providers +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +#include <openssl/provider.h> +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +.SS "General" +.IX Subsection "General" +This page contains information useful to provider authors. +.PP +A \fIprovider\fR, in OpenSSL terms, is a unit of code that provides one +or more implementations for various operations for diverse algorithms +that one might want to perform. +.PP +An \fIoperation\fR is something one wants to do, such as encryption and +decryption, key derivation, \s-1MAC\s0 calculation, signing and verification, +etc. +.PP +An \fIalgorithm\fR is a named method to perform an operation. +Very often, the algorithms revolve around cryptographic operations, +but may also revolve around other types of operation, such as managing +certain types of objects. +.PP +See \fBcrypto\fR\|(7) for further details. +.SS "Provider" +.IX Subsection "Provider" +A \fIprovider\fR offers an initialization function, as a set of base +functions in the form of an \s-1\fBOSSL_DISPATCH\s0\fR\|(3) array, and by extension, +a set of \s-1\fBOSSL_ALGORITHM\s0\fR\|(3)s (see \fBopenssl\-core.h\fR\|(7)). +It may be a dynamically loadable module, or may be built-in, in +OpenSSL libraries or in the application. +If it's a dynamically loadable module, the initialization function +must be named \f(CW\*(C`OSSL_provider_init\*(C'\fR and must be exported. +If it's built-in, the initialization function may have any name. +.PP +The initialization function must have the following signature: +.PP +.Vb 3 +\& int NAME(const OSSL_CORE_HANDLE *handle, +\& const OSSL_DISPATCH *in, const OSSL_DISPATCH **out, +\& void **provctx); +.Ve +.PP +\&\fIhandle\fR is the OpenSSL library object for the provider, and works +as a handle for everything the OpenSSL libraries need to know about +the provider. +For the provider itself, it is passed to some of the functions given in the +dispatch array \fIin\fR. +.PP +\&\fIin\fR is a dispatch array of base functions offered by the OpenSSL +libraries, and the available functions are further described in +\&\fBprovider\-base\fR\|(7). +.PP +\&\fI*out\fR must be assigned a dispatch array of base functions that the +provider offers to the OpenSSL libraries. +The functions that may be offered are further described in +\&\fBprovider\-base\fR\|(7), and they are the central means of communication +between the OpenSSL libraries and the provider. +.PP +\&\fI*provctx\fR should be assigned a provider specific context to allow +the provider multiple simultaneous uses. +This pointer will be passed to various operation functions offered by +the provider. +.PP +Note that the provider will not be made available for applications to use until +the initialization function has completed and returned successfully. +.PP +One of the functions the provider offers to the OpenSSL libraries is +the central mechanism for the OpenSSL libraries to get access to +operation implementations for diverse algorithms. +Its referred to with the number \fB\s-1OSSL_FUNC_PROVIDER_QUERY_OPERATION\s0\fR +and has the following signature: +.PP +.Vb 3 +\& const OSSL_ALGORITHM *provider_query_operation(void *provctx, +\& int operation_id, +\& const int *no_store); +.Ve +.PP +\&\fIprovctx\fR is the provider specific context that was passed back by +the initialization function. +.PP +\&\fIoperation_id\fR is an operation identity (see \*(L"Operations\*(R" below). +.PP +\&\fIno_store\fR is a flag back to the OpenSSL libraries which, when +nonzero, signifies that the OpenSSL libraries will not store a +reference to the returned data in their internal store of +implementations. +.PP +The returned \s-1\fBOSSL_ALGORITHM\s0\fR\|(3) is the foundation of any OpenSSL +library \s-1API\s0 that uses providers for their implementation, most +commonly in the \fIfetching\fR type of functions +(see \*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fBcrypto\fR\|(7)). +.SS "Operations" +.IX Subsection "Operations" +Operations are referred to with numbers, via macros with names +starting with \f(CW\*(C`OSSL_OP_\*(C'\fR. +.PP +With each operation comes a set of defined function types that a +provider may or may not offer, depending on its needs. +.PP +Currently available operations are: +.IP "Digests" 4 +.IX Item "Digests" +In the OpenSSL libraries, the corresponding method object is +\&\fB\s-1EVP_MD\s0\fR. +The number for this operation is \fB\s-1OSSL_OP_DIGEST\s0\fR. +The functions the provider can offer are described in +\&\fBprovider\-digest\fR\|(7). +.IP "Symmetric ciphers" 4 +.IX Item "Symmetric ciphers" +In the OpenSSL libraries, the corresponding method object is +\&\fB\s-1EVP_CIPHER\s0\fR. +The number for this operation is \fB\s-1OSSL_OP_CIPHER\s0\fR. +The functions the provider can offer are described in +\&\fBprovider\-cipher\fR\|(7). +.IP "Message Authentication Code (\s-1MAC\s0)" 4 +.IX Item "Message Authentication Code (MAC)" +In the OpenSSL libraries, the corresponding method object is +\&\fB\s-1EVP_MAC\s0\fR. +The number for this operation is \fB\s-1OSSL_OP_MAC\s0\fR. +The functions the provider can offer are described in +\&\fBprovider\-mac\fR\|(7). +.IP "Key Derivation Function (\s-1KDF\s0)" 4 +.IX Item "Key Derivation Function (KDF)" +In the OpenSSL libraries, the corresponding method object is +\&\fB\s-1EVP_KDF\s0\fR. +The number for this operation is \fB\s-1OSSL_OP_KDF\s0\fR. +The functions the provider can offer are described in +\&\fBprovider\-kdf\fR\|(7). +.IP "Key Exchange" 4 +.IX Item "Key Exchange" +In the OpenSSL libraries, the corresponding method object is +\&\fB\s-1EVP_KEYEXCH\s0\fR. +The number for this operation is \fB\s-1OSSL_OP_KEYEXCH\s0\fR. +The functions the provider can offer are described in +\&\fBprovider\-keyexch\fR\|(7). +.IP "Asymmetric Ciphers" 4 +.IX Item "Asymmetric Ciphers" +In the OpenSSL libraries, the corresponding method object is +\&\fB\s-1EVP_ASYM_CIPHER\s0\fR. +The number for this operation is \fB\s-1OSSL_OP_ASYM_CIPHER\s0\fR. +The functions the provider can offer are described in +\&\fBprovider\-asym_cipher\fR\|(7). +.IP "Asymmetric Key Encapsulation" 4 +.IX Item "Asymmetric Key Encapsulation" +In the OpenSSL libraries, the corresponding method object is \fB\s-1EVP_KEM\s0\fR. +The number for this operation is \fB\s-1OSSL_OP_KEM\s0\fR. +The functions the provider can offer are described in \fBprovider\-kem\fR\|(7). +.IP "Encoding" 4 +.IX Item "Encoding" +In the OpenSSL libraries, the corresponding method object is +\&\fB\s-1OSSL_ENCODER\s0\fR. +The number for this operation is \fB\s-1OSSL_OP_ENCODER\s0\fR. +The functions the provider can offer are described in +\&\fBprovider\-encoder\fR\|(7). +.IP "Decoding" 4 +.IX Item "Decoding" +In the OpenSSL libraries, the corresponding method object is +\&\fB\s-1OSSL_DECODER\s0\fR. +The number for this operation is \fB\s-1OSSL_OP_DECODER\s0\fR. +The functions the provider can offer are described in +\&\fBprovider\-decoder\fR\|(7). +.IP "Random Number Generation" 4 +.IX Item "Random Number Generation" +The number for this operation is \fB\s-1OSSL_OP_RAND\s0\fR. +The functions the provider can offer for random number generation are described +in \fBprovider\-rand\fR\|(7). +.IP "Key Management" 4 +.IX Item "Key Management" +The number for this operation is \fB\s-1OSSL_OP_KEYMGMT\s0\fR. +The functions the provider can offer for key management are described in +\&\fBprovider\-keymgmt\fR\|(7). +.IP "Signing and Signature Verification" 4 +.IX Item "Signing and Signature Verification" +The number for this operation is \fB\s-1OSSL_OP_SIGNATURE\s0\fR. +The functions the provider can offer for digital signatures are described in +\&\fBprovider\-signature\fR\|(7). +.IP "Store Management" 4 +.IX Item "Store Management" +The number for this operation is \fB\s-1OSSL_OP_STORE\s0\fR. +The functions the provider can offer for store management are described in +\&\fBprovider\-storemgmt\fR\|(7). +.PP +\fIAlgorithm naming\fR +.IX Subsection "Algorithm naming" +.PP +Algorithm names are case insensitive. Any particular algorithm can have multiple +aliases associated with it. The canonical OpenSSL naming scheme follows this +format: +.PP +ALGNAME[\s-1VERSION\s0?][\-SUBNAME[\s-1VERSION\s0?]?][\-SIZE?][\-MODE?] +.PP +\&\s-1VERSION\s0 is only present if there are multiple versions of an algorithm (e.g. +\&\s-1MD2, MD4, MD5\s0). It may be omitted if there is only one version. +.PP +\&\s-1SUBNAME\s0 may be present where multiple algorithms are combined together, +e.g. \s-1MD5\-SHA1.\s0 +.PP +\&\s-1SIZE\s0 is only present if multiple versions of an algorithm exist with different +sizes (e.g. \s-1AES\-128\-CBC, AES\-256\-CBC\s0) +.PP +\&\s-1MODE\s0 is only present where applicable. +.PP +Other aliases may exist for example where standards bodies or common practice +use alternative names or names that OpenSSL has used historically. +.SH "OPENSSL PROVIDERS" +.IX Header "OPENSSL PROVIDERS" +OpenSSL provides a number of its own providers. These are the default, base, +fips, legacy and null providers. See \fBcrypto\fR\|(7) for an overview of these +providers. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_DigestInit_ex\fR\|(3), \fBEVP_EncryptInit_ex\fR\|(3), +\&\s-1\fBOSSL_LIB_CTX\s0\fR\|(3), +\&\fBEVP_set_default_properties\fR\|(3), +\&\fBEVP_MD_fetch\fR\|(3), +\&\fBEVP_CIPHER_fetch\fR\|(3), +\&\fBEVP_KEYMGMT_fetch\fR\|(3), +\&\fBopenssl\-core.h\fR\|(7), +\&\fBprovider\-base\fR\|(7), +\&\fBprovider\-digest\fR\|(7), +\&\fBprovider\-cipher\fR\|(7), +\&\fBprovider\-keyexch\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The concept of providers and everything surrounding them was +introduced in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2019\-2022 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>. diff --git a/secure/lib/libcrypto/man/man7/proxy-certificates.7 b/secure/lib/libcrypto/man/man7/proxy-certificates.7 index 25edc2b74c6e..7eae21849f5b 100644 --- a/secure/lib/libcrypto/man/man7/proxy-certificates.7 +++ b/secure/lib/libcrypto/man/man7/proxy-certificates.7 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .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 \{\ @@ -132,8 +130,8 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "PROXY-CERTIFICATES 7" -.TH PROXY-CERTIFICATES 7 "2022-06-21" "1.1.1p" "OpenSSL" +.IX Title "PROXY-CERTIFICATES 7ossl" +.TH PROXY-CERTIFICATES 7ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -181,27 +179,25 @@ See \*(L"\s-1NOTES\*(R"\s0 for a discussion on this requirement. Creating proxy certificates can be done using the \fBopenssl\-x509\fR\|(1) command, with some extra extensions: .PP -.Vb 3 -\& [ v3_proxy ] +.Vb 7 +\& [ proxy ] \& # A proxy certificate MUST NEVER be a CA certificate. -\& basicConstraints=CA:FALSE -\& +\& basicConstraints = CA:FALSE \& # Usual authority key ID -\& authorityKeyIdentifier=keyid,issuer:always -\& +\& authorityKeyIdentifier = keyid,issuer:always \& # The extension which marks this certificate as a proxy -\& proxyCertInfo=critical,language:id\-ppl\-anyLanguage,pathlen:1,policy:text:AB +\& proxyCertInfo = critical,language:id\-ppl\-anyLanguage,pathlen:1,policy:text:AB .Ve .PP It's also possible to specify the proxy extension in a separate section: .PP .Vb 1 -\& proxyCertInfo=critical,@proxy_ext +\& proxyCertInfo = critical,@proxy_ext \& \& [ proxy_ext ] -\& language=id\-ppl\-anyLanguage -\& pathlen=0 -\& policy=text:BC +\& language = id\-ppl\-anyLanguage +\& pathlen = 0 +\& policy = text:BC .Ve .PP The policy value has a specific syntax, \fIsyntag\fR:\fIstring\fR, where the @@ -226,11 +222,11 @@ colons between each byte (every second hex digit): .IX Item "file" indicates that the text of the policy should be taken from a file. The string is then a filename. This is useful for policies that are -large (more than a few lines, e.g. \s-1XML\s0 documents). +more than a few lines, such as \s-1XML\s0 or other markup. .PP -\&\fI\s-1NOTE:\s0 The proxy policy value is what determines the rights granted -to the process during the proxy certificate. It's up to the -application to interpret and combine these policies.\fR +Note that the proxy policy value is what determines the rights granted +to the process during the proxy certificate, and it is up to the +application to interpret and combine these policies.> .PP With a proxy extension, creating a proxy certificate is a matter of two commands: @@ -238,25 +234,25 @@ two commands: .Vb 3 \& openssl req \-new \-config proxy.cnf \e \& \-out proxy.req \-keyout proxy.key \e -\& \-subj "/DC=org/DC=openssl/DC=users/CN=proxy 1" +\& \-subj "/DC=org/DC=openssl/DC=users/CN=proxy" \& \& openssl x509 \-req \-CAcreateserial \-in proxy.req \-out proxy.crt \e \& \-CA user.crt \-CAkey user.key \-days 7 \e -\& \-extfile proxy.cnf \-extensions v3_proxy1 +\& \-extfile proxy.cnf \-extensions proxy .Ve .PP You can also create a proxy certificate using another proxy -certificate as issuer (note: using a different configuration -section for the proxy extensions): +certificate as issuer. Note that this example uses a different +configuration section for the proxy extensions: .PP .Vb 3 \& openssl req \-new \-config proxy.cnf \e \& \-out proxy2.req \-keyout proxy2.key \e -\& \-subj "/DC=org/DC=openssl/DC=users/CN=proxy 1/CN=proxy 2" +\& \-subj "/DC=org/DC=openssl/DC=users/CN=proxy/CN=proxy 2" \& \& openssl x509 \-req \-CAcreateserial \-in proxy2.req \-out proxy2.crt \e \& \-CA proxy.crt \-CAkey proxy.key \-days 7 \e -\& \-extfile proxy.cnf \-extensions v3_proxy2 +\& \-extfile proxy.cnf \-extensions proxy_2 .Ve .SS "Using proxy certs in applications" .IX Subsection "Using proxy certs in applications" @@ -334,7 +330,7 @@ The following skeleton code can be used as a starting point: \& * bottom. You get the CA root first, followed by the \& * possible chain of intermediate CAs, followed by the EE \& * certificate, followed by the possible proxy -\& * certificates. +\& * certificates. \& */ \& X509 *xs = X509_STORE_CTX_get_current_cert(ctx); \& @@ -353,7 +349,7 @@ The following skeleton code can be used as a starting point: \& * by pulling them from some database. If there \& * are none to be found, clear all rights (making \& * this and any subsequent proxy certificate void -\& * of any rights). +\& * of any rights). \& */ \& memset(rights\->rights, 0, sizeof(rights\->rights)); \& break; @@ -470,7 +466,7 @@ the same as the issuer, with one commonName added on. \&\s-1RFC 3820\s0 <https://tools.ietf.org/html/rfc3820> .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019\-2021 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 diff --git a/secure/lib/libcrypto/man/man7/ssl.7 b/secure/lib/libcrypto/man/man7/ssl.7 index 7529c29813bc..054e78e2452a 100644 --- a/secure/lib/libcrypto/man/man7/ssl.7 +++ b/secure/lib/libcrypto/man/man7/ssl.7 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .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 \{\ @@ -132,8 +130,8 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "SSL 7" -.TH SSL 7 "2022-06-21" "1.1.1p" "OpenSSL" +.IX Title "SSL 7ossl" +.TH SSL 7ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -145,9 +143,11 @@ ssl \- OpenSSL SSL/TLS library See the individual manual pages for details. .SH "DESCRIPTION" .IX Header "DESCRIPTION" -The OpenSSL \fBssl\fR library implements the Secure Sockets Layer (\s-1SSL\s0 v2/v3) and -Transport Layer Security (\s-1TLS\s0 v1) protocols. It provides a rich \s-1API\s0 which is -documented here. +The OpenSSL \fBssl\fR library implements several versions of the +Secure Sockets Layer, Transport Layer Security, and Datagram Transport Layer +Security protocols. +This page gives a brief overview of the extensive \s-1API\s0 and data types +provided by the library. .PP An \fB\s-1SSL_CTX\s0\fR object is created as a framework to establish \&\s-1TLS/SSL\s0 enabled connections (see \fBSSL_CTX_new\fR\|(3)). @@ -169,8 +169,7 @@ used to read and write data on the \s-1TLS/SSL\s0 connection. \&\s-1TLS/SSL\s0 connection. .SH "DATA STRUCTURES" .IX Header "DATA STRUCTURES" -Currently the OpenSSL \fBssl\fR library functions deals with the following data -structures: +Here are some of the main data structures in the library. .IP "\fB\s-1SSL_METHOD\s0\fR (\s-1SSL\s0 Method)" 4 .IX Item "SSL_METHOD (SSL Method)" This is a dispatch structure describing the internal \fBssl\fR library @@ -201,714 +200,28 @@ links to mostly all other structures. .IX Header "HEADER FILES" Currently the OpenSSL \fBssl\fR library provides the following C header files containing the prototypes for the data structures and functions: -.IP "\fBssl.h\fR" 4 -.IX Item "ssl.h" +.IP "\fI<openssl/ssl.h>\fR" 4 +.IX Item "<openssl/ssl.h>" This is the common header file for the \s-1SSL/TLS API.\s0 Include it into your program to make the \s-1API\s0 of the \fBssl\fR library available. It internally includes both more private \s-1SSL\s0 headers and headers from the \fBcrypto\fR library. Whenever you need hard-core details on the internals of the \s-1SSL API,\s0 look inside this header file. -.IP "\fBssl2.h\fR" 4 -.IX Item "ssl2.h" +This file also includes the others listed below. +.IP "\fI<openssl/ssl2.h>\fR" 4 +.IX Item "<openssl/ssl2.h>" Unused. Present for backwards compatibility only. -.IP "\fBssl3.h\fR" 4 -.IX Item "ssl3.h" +.IP "\fI<openssl/ssl3.h>\fR" 4 +.IX Item "<openssl/ssl3.h>" This is the sub header file dealing with the SSLv3 protocol only. -\&\fIUsually you don't have to include it explicitly because -it's already included by ssl.h\fR. -.IP "\fBtls1.h\fR" 4 -.IX Item "tls1.h" +.IP "\fI<openssl/tls1.h>\fR" 4 +.IX Item "<openssl/tls1.h>" This is the sub header file dealing with the TLSv1 protocol only. -\&\fIUsually you don't have to include it explicitly because -it's already included by ssl.h\fR. -.SH "API FUNCTIONS" -.IX Header "API FUNCTIONS" -Currently the OpenSSL \fBssl\fR library exports 214 \s-1API\s0 functions. -They are documented in the following: -.SS "Dealing with Protocol Methods" -.IX Subsection "Dealing with Protocol Methods" -Here we document the various \s-1API\s0 functions which deal with the \s-1SSL/TLS\s0 -protocol methods defined in \fB\s-1SSL_METHOD\s0\fR structures. -.IP "const \s-1SSL_METHOD\s0 *\fBTLS_method\fR(void);" 4 -.IX Item "const SSL_METHOD *TLS_method(void);" -Constructor for the \fIversion-flexible\fR \s-1SSL_METHOD\s0 structure for clients, -servers or both. -See \fBSSL_CTX_new\fR\|(3) for details. -.IP "const \s-1SSL_METHOD\s0 *\fBTLS_client_method\fR(void);" 4 -.IX Item "const SSL_METHOD *TLS_client_method(void);" -Constructor for the \fIversion-flexible\fR \s-1SSL_METHOD\s0 structure for clients. -Must be used to support the TLSv1.3 protocol. -.IP "const \s-1SSL_METHOD\s0 *\fBTLS_server_method\fR(void);" 4 -.IX Item "const SSL_METHOD *TLS_server_method(void);" -Constructor for the \fIversion-flexible\fR \s-1SSL_METHOD\s0 structure for servers. -Must be used to support the TLSv1.3 protocol. -.IP "const \s-1SSL_METHOD\s0 *\fBTLSv1_2_method\fR(void);" 4 -.IX Item "const SSL_METHOD *TLSv1_2_method(void);" -Constructor for the TLSv1.2 \s-1SSL_METHOD\s0 structure for clients, servers or both. -.IP "const \s-1SSL_METHOD\s0 *\fBTLSv1_2_client_method\fR(void);" 4 -.IX Item "const SSL_METHOD *TLSv1_2_client_method(void);" -Constructor for the TLSv1.2 \s-1SSL_METHOD\s0 structure for clients. -.IP "const \s-1SSL_METHOD\s0 *\fBTLSv1_2_server_method\fR(void);" 4 -.IX Item "const SSL_METHOD *TLSv1_2_server_method(void);" -Constructor for the TLSv1.2 \s-1SSL_METHOD\s0 structure for servers. -.IP "const \s-1SSL_METHOD\s0 *\fBTLSv1_1_method\fR(void);" 4 -.IX Item "const SSL_METHOD *TLSv1_1_method(void);" -Constructor for the TLSv1.1 \s-1SSL_METHOD\s0 structure for clients, servers or both. -.IP "const \s-1SSL_METHOD\s0 *\fBTLSv1_1_client_method\fR(void);" 4 -.IX Item "const SSL_METHOD *TLSv1_1_client_method(void);" -Constructor for the TLSv1.1 \s-1SSL_METHOD\s0 structure for clients. -.IP "const \s-1SSL_METHOD\s0 *\fBTLSv1_1_server_method\fR(void);" 4 -.IX Item "const SSL_METHOD *TLSv1_1_server_method(void);" -Constructor for the TLSv1.1 \s-1SSL_METHOD\s0 structure for servers. -.IP "const \s-1SSL_METHOD\s0 *\fBTLSv1_method\fR(void);" 4 -.IX Item "const SSL_METHOD *TLSv1_method(void);" -Constructor for the TLSv1 \s-1SSL_METHOD\s0 structure for clients, servers or both. -.IP "const \s-1SSL_METHOD\s0 *\fBTLSv1_client_method\fR(void);" 4 -.IX Item "const SSL_METHOD *TLSv1_client_method(void);" -Constructor for the TLSv1 \s-1SSL_METHOD\s0 structure for clients. -.IP "const \s-1SSL_METHOD\s0 *\fBTLSv1_server_method\fR(void);" 4 -.IX Item "const SSL_METHOD *TLSv1_server_method(void);" -Constructor for the TLSv1 \s-1SSL_METHOD\s0 structure for servers. -.IP "const \s-1SSL_METHOD\s0 *\fBSSLv3_method\fR(void);" 4 -.IX Item "const SSL_METHOD *SSLv3_method(void);" -Constructor for the SSLv3 \s-1SSL_METHOD\s0 structure for clients, servers or both. -.IP "const \s-1SSL_METHOD\s0 *\fBSSLv3_client_method\fR(void);" 4 -.IX Item "const SSL_METHOD *SSLv3_client_method(void);" -Constructor for the SSLv3 \s-1SSL_METHOD\s0 structure for clients. -.IP "const \s-1SSL_METHOD\s0 *\fBSSLv3_server_method\fR(void);" 4 -.IX Item "const SSL_METHOD *SSLv3_server_method(void);" -Constructor for the SSLv3 \s-1SSL_METHOD\s0 structure for servers. -.SS "Dealing with Ciphers" -.IX Subsection "Dealing with Ciphers" -Here we document the various \s-1API\s0 functions which deal with the \s-1SSL/TLS\s0 -ciphers defined in \fB\s-1SSL_CIPHER\s0\fR structures. -.IP "char *\fBSSL_CIPHER_description\fR(\s-1SSL_CIPHER\s0 *cipher, char *buf, int len);" 4 -.IX Item "char *SSL_CIPHER_description(SSL_CIPHER *cipher, char *buf, int len);" -Write a string to \fIbuf\fR (with a maximum size of \fIlen\fR) containing a human -readable description of \fIcipher\fR. Returns \fIbuf\fR. -.IP "int \fBSSL_CIPHER_get_bits\fR(\s-1SSL_CIPHER\s0 *cipher, int *alg_bits);" 4 -.IX Item "int SSL_CIPHER_get_bits(SSL_CIPHER *cipher, int *alg_bits);" -Determine the number of bits in \fIcipher\fR. Because of export crippled ciphers -there are two bits: The bits the algorithm supports in general (stored to -\&\fIalg_bits\fR) and the bits which are actually used (the return value). -.IP "const char *\fBSSL_CIPHER_get_name\fR(\s-1SSL_CIPHER\s0 *cipher);" 4 -.IX Item "const char *SSL_CIPHER_get_name(SSL_CIPHER *cipher);" -Return the internal name of \fIcipher\fR as a string. These are the various -strings defined by the \fISSL3_TXT_xxx\fR and \fITLS1_TXT_xxx\fR -definitions in the header files. -.IP "const char *\fBSSL_CIPHER_get_version\fR(\s-1SSL_CIPHER\s0 *cipher);" 4 -.IX Item "const char *SSL_CIPHER_get_version(SSL_CIPHER *cipher);" -Returns a string like "\f(CW\*(C`SSLv3\*(C'\fR\*(L" or \*(R"\f(CW\*(C`TLSv1.2\*(C'\fR" which indicates the -\&\s-1SSL/TLS\s0 protocol version to which \fIcipher\fR belongs (i.e. where it was defined -in the specification the first time). -.SS "Dealing with Protocol Contexts" -.IX Subsection "Dealing with Protocol Contexts" -Here we document the various \s-1API\s0 functions which deal with the \s-1SSL/TLS\s0 -protocol context defined in the \fB\s-1SSL_CTX\s0\fR structure. -.IP "int \fBSSL_CTX_add_client_CA\fR(\s-1SSL_CTX\s0 *ctx, X509 *x);" 4 -.IX Item "int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *x);" -.PD 0 -.IP "long \fBSSL_CTX_add_extra_chain_cert\fR(\s-1SSL_CTX\s0 *ctx, X509 *x509);" 4 -.IX Item "long SSL_CTX_add_extra_chain_cert(SSL_CTX *ctx, X509 *x509);" -.IP "int \fBSSL_CTX_add_session\fR(\s-1SSL_CTX\s0 *ctx, \s-1SSL_SESSION\s0 *c);" 4 -.IX Item "int SSL_CTX_add_session(SSL_CTX *ctx, SSL_SESSION *c);" -.IP "int \fBSSL_CTX_check_private_key\fR(const \s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "int SSL_CTX_check_private_key(const SSL_CTX *ctx);" -.IP "long \fBSSL_CTX_ctrl\fR(\s-1SSL_CTX\s0 *ctx, int cmd, long larg, char *parg);" 4 -.IX Item "long SSL_CTX_ctrl(SSL_CTX *ctx, int cmd, long larg, char *parg);" -.IP "void \fBSSL_CTX_flush_sessions\fR(\s-1SSL_CTX\s0 *s, long t);" 4 -.IX Item "void SSL_CTX_flush_sessions(SSL_CTX *s, long t);" -.IP "void \fBSSL_CTX_free\fR(\s-1SSL_CTX\s0 *a);" 4 -.IX Item "void SSL_CTX_free(SSL_CTX *a);" -.IP "char *\fBSSL_CTX_get_app_data\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "char *SSL_CTX_get_app_data(SSL_CTX *ctx);" -.IP "X509_STORE *\fBSSL_CTX_get_cert_store\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "X509_STORE *SSL_CTX_get_cert_store(SSL_CTX *ctx);" -.IP "\s-1STACK\s0 *\fBSSL_CTX_get_ciphers\fR(const \s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "STACK *SSL_CTX_get_ciphers(const SSL_CTX *ctx);" -.IP "\s-1STACK\s0 *\fBSSL_CTX_get_client_CA_list\fR(const \s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "STACK *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx);" -.IP "int (*\fBSSL_CTX_get_client_cert_cb\fR(\s-1SSL_CTX\s0 *ctx))(\s-1SSL\s0 *ssl, X509 **x509, \s-1EVP_PKEY\s0 **pkey);" 4 -.IX Item "int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey);" -.IP "void \fBSSL_CTX_get_default_read_ahead\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "void SSL_CTX_get_default_read_ahead(SSL_CTX *ctx);" -.IP "char *\fBSSL_CTX_get_ex_data\fR(const \s-1SSL_CTX\s0 *s, int idx);" 4 -.IX Item "char *SSL_CTX_get_ex_data(const SSL_CTX *s, int idx);" -.IP "int \fBSSL_CTX_get_ex_new_index\fR(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))" 4 -.IX Item "int SSL_CTX_get_ex_new_index(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))" -.IP "void (*\fBSSL_CTX_get_info_callback\fR(\s-1SSL_CTX\s0 *ctx))(\s-1SSL\s0 *ssl, int cb, int ret);" 4 -.IX Item "void (*SSL_CTX_get_info_callback(SSL_CTX *ctx))(SSL *ssl, int cb, int ret);" -.IP "int \fBSSL_CTX_get_quiet_shutdown\fR(const \s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "int SSL_CTX_get_quiet_shutdown(const SSL_CTX *ctx);" -.IP "void \fBSSL_CTX_get_read_ahead\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "void SSL_CTX_get_read_ahead(SSL_CTX *ctx);" -.IP "int \fBSSL_CTX_get_session_cache_mode\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "int SSL_CTX_get_session_cache_mode(SSL_CTX *ctx);" -.IP "long \fBSSL_CTX_get_timeout\fR(const \s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "long SSL_CTX_get_timeout(const SSL_CTX *ctx);" -.IP "int (*\fBSSL_CTX_get_verify_callback\fR(const \s-1SSL_CTX\s0 *ctx))(int ok, X509_STORE_CTX *ctx);" 4 -.IX Item "int (*SSL_CTX_get_verify_callback(const SSL_CTX *ctx))(int ok, X509_STORE_CTX *ctx);" -.IP "int \fBSSL_CTX_get_verify_mode\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "int SSL_CTX_get_verify_mode(SSL_CTX *ctx);" -.IP "int \fBSSL_CTX_load_verify_locations\fR(\s-1SSL_CTX\s0 *ctx, const char *CAfile, const char *CApath);" 4 -.IX Item "int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile, const char *CApath);" -.IP "\s-1SSL_CTX\s0 *\fBSSL_CTX_new\fR(const \s-1SSL_METHOD\s0 *meth);" 4 -.IX Item "SSL_CTX *SSL_CTX_new(const SSL_METHOD *meth);" -.IP "int SSL_CTX_up_ref(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "int SSL_CTX_up_ref(SSL_CTX *ctx);" -.IP "int \fBSSL_CTX_remove_session\fR(\s-1SSL_CTX\s0 *ctx, \s-1SSL_SESSION\s0 *c);" 4 -.IX Item "int SSL_CTX_remove_session(SSL_CTX *ctx, SSL_SESSION *c);" -.IP "int \fBSSL_CTX_sess_accept\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "int SSL_CTX_sess_accept(SSL_CTX *ctx);" -.IP "int \fBSSL_CTX_sess_accept_good\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "int SSL_CTX_sess_accept_good(SSL_CTX *ctx);" -.IP "int \fBSSL_CTX_sess_accept_renegotiate\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "int SSL_CTX_sess_accept_renegotiate(SSL_CTX *ctx);" -.IP "int \fBSSL_CTX_sess_cache_full\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "int SSL_CTX_sess_cache_full(SSL_CTX *ctx);" -.IP "int \fBSSL_CTX_sess_cb_hits\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "int SSL_CTX_sess_cb_hits(SSL_CTX *ctx);" -.IP "int \fBSSL_CTX_sess_connect\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "int SSL_CTX_sess_connect(SSL_CTX *ctx);" -.IP "int \fBSSL_CTX_sess_connect_good\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "int SSL_CTX_sess_connect_good(SSL_CTX *ctx);" -.IP "int \fBSSL_CTX_sess_connect_renegotiate\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "int SSL_CTX_sess_connect_renegotiate(SSL_CTX *ctx);" -.IP "int \fBSSL_CTX_sess_get_cache_size\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "int SSL_CTX_sess_get_cache_size(SSL_CTX *ctx);" -.IP "\s-1SSL_SESSION\s0 *(*\fBSSL_CTX_sess_get_get_cb\fR(\s-1SSL_CTX\s0 *ctx))(\s-1SSL\s0 *ssl, unsigned char *data, int len, int *copy);" 4 -.IX Item "SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(SSL *ssl, unsigned char *data, int len, int *copy);" -.IP "int (*\fBSSL_CTX_sess_get_new_cb\fR(\s-1SSL_CTX\s0 *ctx)(\s-1SSL\s0 *ssl, \s-1SSL_SESSION\s0 *sess);" 4 -.IX Item "int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx)(SSL *ssl, SSL_SESSION *sess);" -.IP "void (*\fBSSL_CTX_sess_get_remove_cb\fR(\s-1SSL_CTX\s0 *ctx)(\s-1SSL_CTX\s0 *ctx, \s-1SSL_SESSION\s0 *sess);" 4 -.IX Item "void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx)(SSL_CTX *ctx, SSL_SESSION *sess);" -.IP "int \fBSSL_CTX_sess_hits\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "int SSL_CTX_sess_hits(SSL_CTX *ctx);" -.IP "int \fBSSL_CTX_sess_misses\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "int SSL_CTX_sess_misses(SSL_CTX *ctx);" -.IP "int \fBSSL_CTX_sess_number\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "int SSL_CTX_sess_number(SSL_CTX *ctx);" -.IP "void \fBSSL_CTX_sess_set_cache_size\fR(\s-1SSL_CTX\s0 *ctx, t);" 4 -.IX Item "void SSL_CTX_sess_set_cache_size(SSL_CTX *ctx, t);" -.IP "void \fBSSL_CTX_sess_set_get_cb\fR(\s-1SSL_CTX\s0 *ctx, \s-1SSL_SESSION\s0 *(*cb)(\s-1SSL\s0 *ssl, unsigned char *data, int len, int *copy));" 4 -.IX Item "void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx, SSL_SESSION *(*cb)(SSL *ssl, unsigned char *data, int len, int *copy));" -.IP "void \fBSSL_CTX_sess_set_new_cb\fR(\s-1SSL_CTX\s0 *ctx, int (*cb)(\s-1SSL\s0 *ssl, \s-1SSL_SESSION\s0 *sess));" 4 -.IX Item "void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx, int (*cb)(SSL *ssl, SSL_SESSION *sess));" -.IP "void \fBSSL_CTX_sess_set_remove_cb\fR(\s-1SSL_CTX\s0 *ctx, void (*cb)(\s-1SSL_CTX\s0 *ctx, \s-1SSL_SESSION\s0 *sess));" 4 -.IX Item "void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx, void (*cb)(SSL_CTX *ctx, SSL_SESSION *sess));" -.IP "int \fBSSL_CTX_sess_timeouts\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "int SSL_CTX_sess_timeouts(SSL_CTX *ctx);" -.IP "\s-1LHASH\s0 *\fBSSL_CTX_sessions\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "LHASH *SSL_CTX_sessions(SSL_CTX *ctx);" -.IP "int \fBSSL_CTX_set_app_data\fR(\s-1SSL_CTX\s0 *ctx, void *arg);" 4 -.IX Item "int SSL_CTX_set_app_data(SSL_CTX *ctx, void *arg);" -.IP "void \fBSSL_CTX_set_cert_store\fR(\s-1SSL_CTX\s0 *ctx, X509_STORE *cs);" 4 -.IX Item "void SSL_CTX_set_cert_store(SSL_CTX *ctx, X509_STORE *cs);" -.IP "void \fBSSL_CTX_set1_cert_store\fR(\s-1SSL_CTX\s0 *ctx, X509_STORE *cs);" 4 -.IX Item "void SSL_CTX_set1_cert_store(SSL_CTX *ctx, X509_STORE *cs);" -.IP "void \fBSSL_CTX_set_cert_verify_cb\fR(\s-1SSL_CTX\s0 *ctx, int (*cb)(), char *arg)" 4 -.IX Item "void SSL_CTX_set_cert_verify_cb(SSL_CTX *ctx, int (*cb)(), char *arg)" -.IP "int \fBSSL_CTX_set_cipher_list\fR(\s-1SSL_CTX\s0 *ctx, char *str);" 4 -.IX Item "int SSL_CTX_set_cipher_list(SSL_CTX *ctx, char *str);" -.IP "void \fBSSL_CTX_set_client_CA_list\fR(\s-1SSL_CTX\s0 *ctx, \s-1STACK\s0 *list);" 4 -.IX Item "void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK *list);" -.IP "void \fBSSL_CTX_set_client_cert_cb\fR(\s-1SSL_CTX\s0 *ctx, int (*cb)(\s-1SSL\s0 *ssl, X509 **x509, \s-1EVP_PKEY\s0 **pkey));" 4 -.IX Item "void SSL_CTX_set_client_cert_cb(SSL_CTX *ctx, int (*cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey));" -.IP "int \fBSSL_CTX_set_ct_validation_callback\fR(\s-1SSL_CTX\s0 *ctx, ssl_ct_validation_cb callback, void *arg);" 4 -.IX Item "int SSL_CTX_set_ct_validation_callback(SSL_CTX *ctx, ssl_ct_validation_cb callback, void *arg);" -.IP "void \fBSSL_CTX_set_default_passwd_cb\fR(\s-1SSL_CTX\s0 *ctx, int (*cb);(void))" 4 -.IX Item "void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, int (*cb);(void))" -.IP "void \fBSSL_CTX_set_default_read_ahead\fR(\s-1SSL_CTX\s0 *ctx, int m);" 4 -.IX Item "void SSL_CTX_set_default_read_ahead(SSL_CTX *ctx, int m);" -.IP "int \fBSSL_CTX_set_default_verify_paths\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "int SSL_CTX_set_default_verify_paths(SSL_CTX *ctx);" -.PD -Use the default paths to locate trusted \s-1CA\s0 certificates. There is one default -directory path and one default file path. Both are set via this call. -.IP "int \fBSSL_CTX_set_default_verify_dir\fR(\s-1SSL_CTX\s0 *ctx)" 4 -.IX Item "int SSL_CTX_set_default_verify_dir(SSL_CTX *ctx)" -Use the default directory path to locate trusted \s-1CA\s0 certificates. -.IP "int \fBSSL_CTX_set_default_verify_file\fR(\s-1SSL_CTX\s0 *ctx)" 4 -.IX Item "int SSL_CTX_set_default_verify_file(SSL_CTX *ctx)" -Use the file path to locate trusted \s-1CA\s0 certificates. -.IP "int \fBSSL_CTX_set_ex_data\fR(\s-1SSL_CTX\s0 *s, int idx, char *arg);" 4 -.IX Item "int SSL_CTX_set_ex_data(SSL_CTX *s, int idx, char *arg);" -.PD 0 -.IP "void \fBSSL_CTX_set_info_callback\fR(\s-1SSL_CTX\s0 *ctx, void (*cb)(\s-1SSL\s0 *ssl, int cb, int ret));" 4 -.IX Item "void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*cb)(SSL *ssl, int cb, int ret));" -.IP "void \fBSSL_CTX_set_msg_callback\fR(\s-1SSL_CTX\s0 *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, \s-1SSL\s0 *ssl, void *arg));" 4 -.IX Item "void SSL_CTX_set_msg_callback(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));" -.IP "void \fBSSL_CTX_set_msg_callback_arg\fR(\s-1SSL_CTX\s0 *ctx, void *arg);" 4 -.IX Item "void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg);" -.IP "unsigned long \fBSSL_CTX_clear_options\fR(\s-1SSL_CTX\s0 *ctx, unsigned long op);" 4 -.IX Item "unsigned long SSL_CTX_clear_options(SSL_CTX *ctx, unsigned long op);" -.IP "unsigned long \fBSSL_CTX_get_options\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "unsigned long SSL_CTX_get_options(SSL_CTX *ctx);" -.IP "unsigned long \fBSSL_CTX_set_options\fR(\s-1SSL_CTX\s0 *ctx, unsigned long op);" 4 -.IX Item "unsigned long SSL_CTX_set_options(SSL_CTX *ctx, unsigned long op);" -.IP "void \fBSSL_CTX_set_quiet_shutdown\fR(\s-1SSL_CTX\s0 *ctx, int mode);" 4 -.IX Item "void SSL_CTX_set_quiet_shutdown(SSL_CTX *ctx, int mode);" -.IP "void \fBSSL_CTX_set_read_ahead\fR(\s-1SSL_CTX\s0 *ctx, int m);" 4 -.IX Item "void SSL_CTX_set_read_ahead(SSL_CTX *ctx, int m);" -.IP "void \fBSSL_CTX_set_session_cache_mode\fR(\s-1SSL_CTX\s0 *ctx, int mode);" 4 -.IX Item "void SSL_CTX_set_session_cache_mode(SSL_CTX *ctx, int mode);" -.IP "int \fBSSL_CTX_set_ssl_version\fR(\s-1SSL_CTX\s0 *ctx, const \s-1SSL_METHOD\s0 *meth);" 4 -.IX Item "int SSL_CTX_set_ssl_version(SSL_CTX *ctx, const SSL_METHOD *meth);" -.IP "void \fBSSL_CTX_set_timeout\fR(\s-1SSL_CTX\s0 *ctx, long t);" 4 -.IX Item "void SSL_CTX_set_timeout(SSL_CTX *ctx, long t);" -.IP "long \fBSSL_CTX_set_tmp_dh\fR(SSL_CTX* ctx, \s-1DH\s0 *dh);" 4 -.IX Item "long SSL_CTX_set_tmp_dh(SSL_CTX* ctx, DH *dh);" -.IP "long \fBSSL_CTX_set_tmp_dh_callback\fR(\s-1SSL_CTX\s0 *ctx, \s-1DH\s0 *(*cb)(void));" 4 -.IX Item "long SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx, DH *(*cb)(void));" -.IP "void \fBSSL_CTX_set_verify\fR(\s-1SSL_CTX\s0 *ctx, int mode, int (*cb);(void))" 4 -.IX Item "void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, int (*cb);(void))" -.IP "int \fBSSL_CTX_use_PrivateKey\fR(\s-1SSL_CTX\s0 *ctx, \s-1EVP_PKEY\s0 *pkey);" 4 -.IX Item "int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey);" -.IP "int \fBSSL_CTX_use_PrivateKey_ASN1\fR(int type, \s-1SSL_CTX\s0 *ctx, unsigned char *d, long len);" 4 -.IX Item "int SSL_CTX_use_PrivateKey_ASN1(int type, SSL_CTX *ctx, unsigned char *d, long len);" -.IP "int \fBSSL_CTX_use_PrivateKey_file\fR(\s-1SSL_CTX\s0 *ctx, const char *file, int type);" 4 -.IX Item "int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type);" -.IP "int \fBSSL_CTX_use_RSAPrivateKey\fR(\s-1SSL_CTX\s0 *ctx, \s-1RSA\s0 *rsa);" 4 -.IX Item "int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa);" -.IP "int \fBSSL_CTX_use_RSAPrivateKey_ASN1\fR(\s-1SSL_CTX\s0 *ctx, unsigned char *d, long len);" 4 -.IX Item "int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len);" -.IP "int \fBSSL_CTX_use_RSAPrivateKey_file\fR(\s-1SSL_CTX\s0 *ctx, const char *file, int type);" 4 -.IX Item "int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type);" -.IP "int \fBSSL_CTX_use_certificate\fR(\s-1SSL_CTX\s0 *ctx, X509 *x);" 4 -.IX Item "int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x);" -.IP "int \fBSSL_CTX_use_certificate_ASN1\fR(\s-1SSL_CTX\s0 *ctx, int len, unsigned char *d);" 4 -.IX Item "int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d);" -.IP "int \fBSSL_CTX_use_certificate_file\fR(\s-1SSL_CTX\s0 *ctx, const char *file, int type);" 4 -.IX Item "int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type);" -.IP "int \fBSSL_CTX_use_cert_and_key\fR(\s-1SSL_CTX\s0 *ctx, X509 *x, \s-1EVP_PKEY\s0 *pkey, \s-1STACK_OF\s0(X509) *chain, int override);" 4 -.IX Item "int SSL_CTX_use_cert_and_key(SSL_CTX *ctx, X509 *x, EVP_PKEY *pkey, STACK_OF(X509) *chain, int override);" -.IP "X509 *\fBSSL_CTX_get0_certificate\fR(const \s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "X509 *SSL_CTX_get0_certificate(const SSL_CTX *ctx);" -.IP "\s-1EVP_PKEY\s0 *\fBSSL_CTX_get0_privatekey\fR(const \s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "EVP_PKEY *SSL_CTX_get0_privatekey(const SSL_CTX *ctx);" -.IP "void \fBSSL_CTX_set_psk_client_callback\fR(\s-1SSL_CTX\s0 *ctx, unsigned int (*callback)(\s-1SSL\s0 *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len));" 4 -.IX Item "void SSL_CTX_set_psk_client_callback(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len));" -.IP "int \fBSSL_CTX_use_psk_identity_hint\fR(\s-1SSL_CTX\s0 *ctx, const char *hint);" 4 -.IX Item "int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint);" -.IP "void \fBSSL_CTX_set_psk_server_callback\fR(\s-1SSL_CTX\s0 *ctx, unsigned int (*callback)(\s-1SSL\s0 *ssl, const char *identity, unsigned char *psk, int max_psk_len));" 4 -.IX Item "void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len));" -.PD -.SS "Dealing with Sessions" -.IX Subsection "Dealing with Sessions" -Here we document the various \s-1API\s0 functions which deal with the \s-1SSL/TLS\s0 -sessions defined in the \fB\s-1SSL_SESSION\s0\fR structures. -.IP "int \fBSSL_SESSION_cmp\fR(const \s-1SSL_SESSION\s0 *a, const \s-1SSL_SESSION\s0 *b);" 4 -.IX Item "int SSL_SESSION_cmp(const SSL_SESSION *a, const SSL_SESSION *b);" -.PD 0 -.IP "void \fBSSL_SESSION_free\fR(\s-1SSL_SESSION\s0 *ss);" 4 -.IX Item "void SSL_SESSION_free(SSL_SESSION *ss);" -.IP "char *\fBSSL_SESSION_get_app_data\fR(\s-1SSL_SESSION\s0 *s);" 4 -.IX Item "char *SSL_SESSION_get_app_data(SSL_SESSION *s);" -.IP "char *\fBSSL_SESSION_get_ex_data\fR(const \s-1SSL_SESSION\s0 *s, int idx);" 4 -.IX Item "char *SSL_SESSION_get_ex_data(const SSL_SESSION *s, int idx);" -.IP "int \fBSSL_SESSION_get_ex_new_index\fR(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))" 4 -.IX Item "int SSL_SESSION_get_ex_new_index(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))" -.IP "long \fBSSL_SESSION_get_time\fR(const \s-1SSL_SESSION\s0 *s);" 4 -.IX Item "long SSL_SESSION_get_time(const SSL_SESSION *s);" -.IP "long \fBSSL_SESSION_get_timeout\fR(const \s-1SSL_SESSION\s0 *s);" 4 -.IX Item "long SSL_SESSION_get_timeout(const SSL_SESSION *s);" -.IP "unsigned long \fBSSL_SESSION_hash\fR(const \s-1SSL_SESSION\s0 *a);" 4 -.IX Item "unsigned long SSL_SESSION_hash(const SSL_SESSION *a);" -.IP "\s-1SSL_SESSION\s0 *\fBSSL_SESSION_new\fR(void);" 4 -.IX Item "SSL_SESSION *SSL_SESSION_new(void);" -.IP "int \fBSSL_SESSION_print\fR(\s-1BIO\s0 *bp, const \s-1SSL_SESSION\s0 *x);" 4 -.IX Item "int SSL_SESSION_print(BIO *bp, const SSL_SESSION *x);" -.IP "int \fBSSL_SESSION_print_fp\fR(\s-1FILE\s0 *fp, const \s-1SSL_SESSION\s0 *x);" 4 -.IX Item "int SSL_SESSION_print_fp(FILE *fp, const SSL_SESSION *x);" -.IP "int \fBSSL_SESSION_set_app_data\fR(\s-1SSL_SESSION\s0 *s, char *a);" 4 -.IX Item "int SSL_SESSION_set_app_data(SSL_SESSION *s, char *a);" -.IP "int \fBSSL_SESSION_set_ex_data\fR(\s-1SSL_SESSION\s0 *s, int idx, char *arg);" 4 -.IX Item "int SSL_SESSION_set_ex_data(SSL_SESSION *s, int idx, char *arg);" -.IP "long \fBSSL_SESSION_set_time\fR(\s-1SSL_SESSION\s0 *s, long t);" 4 -.IX Item "long SSL_SESSION_set_time(SSL_SESSION *s, long t);" -.IP "long \fBSSL_SESSION_set_timeout\fR(\s-1SSL_SESSION\s0 *s, long t);" 4 -.IX Item "long SSL_SESSION_set_timeout(SSL_SESSION *s, long t);" -.PD -.SS "Dealing with Connections" -.IX Subsection "Dealing with Connections" -Here we document the various \s-1API\s0 functions which deal with the \s-1SSL/TLS\s0 -connection defined in the \fB\s-1SSL\s0\fR structure. -.IP "int \fBSSL_accept\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_accept(SSL *ssl);" -.PD 0 -.IP "int \fBSSL_add_dir_cert_subjects_to_stack\fR(\s-1STACK\s0 *stack, const char *dir);" 4 -.IX Item "int SSL_add_dir_cert_subjects_to_stack(STACK *stack, const char *dir);" -.IP "int \fBSSL_add_file_cert_subjects_to_stack\fR(\s-1STACK\s0 *stack, const char *file);" 4 -.IX Item "int SSL_add_file_cert_subjects_to_stack(STACK *stack, const char *file);" -.IP "int \fBSSL_add_client_CA\fR(\s-1SSL\s0 *ssl, X509 *x);" 4 -.IX Item "int SSL_add_client_CA(SSL *ssl, X509 *x);" -.IP "char *\fBSSL_alert_desc_string\fR(int value);" 4 -.IX Item "char *SSL_alert_desc_string(int value);" -.IP "char *\fBSSL_alert_desc_string_long\fR(int value);" 4 -.IX Item "char *SSL_alert_desc_string_long(int value);" -.IP "char *\fBSSL_alert_type_string\fR(int value);" 4 -.IX Item "char *SSL_alert_type_string(int value);" -.IP "char *\fBSSL_alert_type_string_long\fR(int value);" 4 -.IX Item "char *SSL_alert_type_string_long(int value);" -.IP "int \fBSSL_check_private_key\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_check_private_key(const SSL *ssl);" -.IP "void \fBSSL_clear\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "void SSL_clear(SSL *ssl);" -.IP "long \fBSSL_clear_num_renegotiations\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "long SSL_clear_num_renegotiations(SSL *ssl);" -.IP "int \fBSSL_connect\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_connect(SSL *ssl);" -.IP "int \fBSSL_copy_session_id\fR(\s-1SSL\s0 *t, const \s-1SSL\s0 *f);" 4 -.IX Item "int SSL_copy_session_id(SSL *t, const SSL *f);" -.PD -Sets the session details for \fBt\fR to be the same as in \fBf\fR. Returns 1 on -success or 0 on failure. -.IP "long \fBSSL_ctrl\fR(\s-1SSL\s0 *ssl, int cmd, long larg, char *parg);" 4 -.IX Item "long SSL_ctrl(SSL *ssl, int cmd, long larg, char *parg);" -.PD 0 -.IP "int \fBSSL_do_handshake\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_do_handshake(SSL *ssl);" -.IP "\s-1SSL\s0 *\fBSSL_dup\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "SSL *SSL_dup(SSL *ssl);" -.PD -\&\fBSSL_dup()\fR allows applications to configure an \s-1SSL\s0 handle for use -in multiple \s-1SSL\s0 connections, and then duplicate it prior to initiating -each connection with the duplicated handle. -Use of \fBSSL_dup()\fR avoids the need to repeat the configuration of the -handles for each connection. -.Sp -For \fBSSL_dup()\fR to work, the connection \s-1MUST\s0 be in its initial state -and \s-1MUST NOT\s0 have not yet have started the \s-1SSL\s0 handshake. -For connections that are not in their initial state \fBSSL_dup()\fR just -increments an internal reference count and returns the \fIsame\fR -handle. -It may be possible to use \fBSSL_clear\fR\|(3) to recycle an \s-1SSL\s0 handle -that is not in its initial state for re-use, but this is best -avoided. -Instead, save and restore the session, if desired, and construct a -fresh handle for each connection. -.IP "\s-1STACK\s0 *\fBSSL_dup_CA_list\fR(\s-1STACK\s0 *sk);" 4 -.IX Item "STACK *SSL_dup_CA_list(STACK *sk);" -.PD 0 -.IP "void \fBSSL_free\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "void SSL_free(SSL *ssl);" -.IP "\s-1SSL_CTX\s0 *\fBSSL_get_SSL_CTX\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "SSL_CTX *SSL_get_SSL_CTX(const SSL *ssl);" -.IP "char *\fBSSL_get_app_data\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "char *SSL_get_app_data(SSL *ssl);" -.IP "X509 *\fBSSL_get_certificate\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "X509 *SSL_get_certificate(const SSL *ssl);" -.IP "const char *\fBSSL_get_cipher\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "const char *SSL_get_cipher(const SSL *ssl);" -.IP "int \fBSSL_is_dtls\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_is_dtls(const SSL *ssl);" -.IP "int \fBSSL_get_cipher_bits\fR(const \s-1SSL\s0 *ssl, int *alg_bits);" 4 -.IX Item "int SSL_get_cipher_bits(const SSL *ssl, int *alg_bits);" -.IP "char *\fBSSL_get_cipher_list\fR(const \s-1SSL\s0 *ssl, int n);" 4 -.IX Item "char *SSL_get_cipher_list(const SSL *ssl, int n);" -.IP "char *\fBSSL_get_cipher_name\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "char *SSL_get_cipher_name(const SSL *ssl);" -.IP "char *\fBSSL_get_cipher_version\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "char *SSL_get_cipher_version(const SSL *ssl);" -.IP "\s-1STACK\s0 *\fBSSL_get_ciphers\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "STACK *SSL_get_ciphers(const SSL *ssl);" -.IP "\s-1STACK\s0 *\fBSSL_get_client_CA_list\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "STACK *SSL_get_client_CA_list(const SSL *ssl);" -.IP "\s-1SSL_CIPHER\s0 *\fBSSL_get_current_cipher\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "SSL_CIPHER *SSL_get_current_cipher(SSL *ssl);" -.IP "long \fBSSL_get_default_timeout\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "long SSL_get_default_timeout(const SSL *ssl);" -.IP "int \fBSSL_get_error\fR(const \s-1SSL\s0 *ssl, int i);" 4 -.IX Item "int SSL_get_error(const SSL *ssl, int i);" -.IP "char *\fBSSL_get_ex_data\fR(const \s-1SSL\s0 *ssl, int idx);" 4 -.IX Item "char *SSL_get_ex_data(const SSL *ssl, int idx);" -.IP "int \fBSSL_get_ex_data_X509_STORE_CTX_idx\fR(void);" 4 -.IX Item "int SSL_get_ex_data_X509_STORE_CTX_idx(void);" -.IP "int \fBSSL_get_ex_new_index\fR(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))" 4 -.IX Item "int SSL_get_ex_new_index(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))" -.IP "int \fBSSL_get_fd\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_get_fd(const SSL *ssl);" -.IP "void (*\fBSSL_get_info_callback\fR(const \s-1SSL\s0 *ssl);)()" 4 -.IX Item "void (*SSL_get_info_callback(const SSL *ssl);)()" -.IP "int \fBSSL_get_key_update_type\fR(\s-1SSL\s0 *s);" 4 -.IX Item "int SSL_get_key_update_type(SSL *s);" -.IP "\s-1STACK\s0 *\fBSSL_get_peer_cert_chain\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "STACK *SSL_get_peer_cert_chain(const SSL *ssl);" -.IP "X509 *\fBSSL_get_peer_certificate\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "X509 *SSL_get_peer_certificate(const SSL *ssl);" -.IP "const \s-1STACK_OF\s0(\s-1SCT\s0) *\fBSSL_get0_peer_scts\fR(\s-1SSL\s0 *s);" 4 -.IX Item "const STACK_OF(SCT) *SSL_get0_peer_scts(SSL *s);" -.IP "\s-1EVP_PKEY\s0 *\fBSSL_get_privatekey\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "EVP_PKEY *SSL_get_privatekey(const SSL *ssl);" -.IP "int \fBSSL_get_quiet_shutdown\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_get_quiet_shutdown(const SSL *ssl);" -.IP "\s-1BIO\s0 *\fBSSL_get_rbio\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "BIO *SSL_get_rbio(const SSL *ssl);" -.IP "int \fBSSL_get_read_ahead\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_get_read_ahead(const SSL *ssl);" -.IP "\s-1SSL_SESSION\s0 *\fBSSL_get_session\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "SSL_SESSION *SSL_get_session(const SSL *ssl);" -.IP "char *\fBSSL_get_shared_ciphers\fR(const \s-1SSL\s0 *ssl, char *buf, int size);" 4 -.IX Item "char *SSL_get_shared_ciphers(const SSL *ssl, char *buf, int size);" -.IP "int \fBSSL_get_shutdown\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_get_shutdown(const SSL *ssl);" -.IP "const \s-1SSL_METHOD\s0 *\fBSSL_get_ssl_method\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "const SSL_METHOD *SSL_get_ssl_method(SSL *ssl);" -.IP "int \fBSSL_get_state\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_get_state(const SSL *ssl);" -.IP "long \fBSSL_get_time\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "long SSL_get_time(const SSL *ssl);" -.IP "long \fBSSL_get_timeout\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "long SSL_get_timeout(const SSL *ssl);" -.IP "int (*\fBSSL_get_verify_callback\fR(const \s-1SSL\s0 *ssl))(int, X509_STORE_CTX *)" 4 -.IX Item "int (*SSL_get_verify_callback(const SSL *ssl))(int, X509_STORE_CTX *)" -.IP "int \fBSSL_get_verify_mode\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_get_verify_mode(const SSL *ssl);" -.IP "long \fBSSL_get_verify_result\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "long SSL_get_verify_result(const SSL *ssl);" -.IP "char *\fBSSL_get_version\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "char *SSL_get_version(const SSL *ssl);" -.IP "\s-1BIO\s0 *\fBSSL_get_wbio\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "BIO *SSL_get_wbio(const SSL *ssl);" -.IP "int \fBSSL_in_accept_init\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_in_accept_init(SSL *ssl);" -.IP "int \fBSSL_in_before\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_in_before(SSL *ssl);" -.IP "int \fBSSL_in_connect_init\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_in_connect_init(SSL *ssl);" -.IP "int \fBSSL_in_init\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_in_init(SSL *ssl);" -.IP "int \fBSSL_is_init_finished\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_is_init_finished(SSL *ssl);" -.IP "int \fBSSL_key_update\fR(\s-1SSL\s0 *s, int updatetype);" 4 -.IX Item "int SSL_key_update(SSL *s, int updatetype);" -.IP "\s-1STACK\s0 *\fBSSL_load_client_CA_file\fR(const char *file);" 4 -.IX Item "STACK *SSL_load_client_CA_file(const char *file);" -.IP "\s-1SSL\s0 *\fBSSL_new\fR(\s-1SSL_CTX\s0 *ctx);" 4 -.IX Item "SSL *SSL_new(SSL_CTX *ctx);" -.IP "int SSL_up_ref(\s-1SSL\s0 *s);" 4 -.IX Item "int SSL_up_ref(SSL *s);" -.IP "long \fBSSL_num_renegotiations\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "long SSL_num_renegotiations(SSL *ssl);" -.IP "int \fBSSL_peek\fR(\s-1SSL\s0 *ssl, void *buf, int num);" 4 -.IX Item "int SSL_peek(SSL *ssl, void *buf, int num);" -.IP "int \fBSSL_pending\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_pending(const SSL *ssl);" -.IP "int \fBSSL_read\fR(\s-1SSL\s0 *ssl, void *buf, int num);" 4 -.IX Item "int SSL_read(SSL *ssl, void *buf, int num);" -.IP "int \fBSSL_renegotiate\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_renegotiate(SSL *ssl);" -.IP "char *\fBSSL_rstate_string\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "char *SSL_rstate_string(SSL *ssl);" -.IP "char *\fBSSL_rstate_string_long\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "char *SSL_rstate_string_long(SSL *ssl);" -.IP "long \fBSSL_session_reused\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "long SSL_session_reused(SSL *ssl);" -.IP "void \fBSSL_set_accept_state\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "void SSL_set_accept_state(SSL *ssl);" -.IP "void \fBSSL_set_app_data\fR(\s-1SSL\s0 *ssl, char *arg);" 4 -.IX Item "void SSL_set_app_data(SSL *ssl, char *arg);" -.IP "void \fBSSL_set_bio\fR(\s-1SSL\s0 *ssl, \s-1BIO\s0 *rbio, \s-1BIO\s0 *wbio);" 4 -.IX Item "void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio);" -.IP "int \fBSSL_set_cipher_list\fR(\s-1SSL\s0 *ssl, char *str);" 4 -.IX Item "int SSL_set_cipher_list(SSL *ssl, char *str);" -.IP "void \fBSSL_set_client_CA_list\fR(\s-1SSL\s0 *ssl, \s-1STACK\s0 *list);" 4 -.IX Item "void SSL_set_client_CA_list(SSL *ssl, STACK *list);" -.IP "void \fBSSL_set_connect_state\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "void SSL_set_connect_state(SSL *ssl);" -.IP "int \fBSSL_set_ct_validation_callback\fR(\s-1SSL\s0 *ssl, ssl_ct_validation_cb callback, void *arg);" 4 -.IX Item "int SSL_set_ct_validation_callback(SSL *ssl, ssl_ct_validation_cb callback, void *arg);" -.IP "int \fBSSL_set_ex_data\fR(\s-1SSL\s0 *ssl, int idx, char *arg);" 4 -.IX Item "int SSL_set_ex_data(SSL *ssl, int idx, char *arg);" -.IP "int \fBSSL_set_fd\fR(\s-1SSL\s0 *ssl, int fd);" 4 -.IX Item "int SSL_set_fd(SSL *ssl, int fd);" -.IP "void \fBSSL_set_info_callback\fR(\s-1SSL\s0 *ssl, void (*cb);(void))" 4 -.IX Item "void SSL_set_info_callback(SSL *ssl, void (*cb);(void))" -.IP "void \fBSSL_set_msg_callback\fR(\s-1SSL\s0 *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, \s-1SSL\s0 *ssl, void *arg));" 4 -.IX Item "void SSL_set_msg_callback(SSL *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));" -.IP "void \fBSSL_set_msg_callback_arg\fR(\s-1SSL\s0 *ctx, void *arg);" 4 -.IX Item "void SSL_set_msg_callback_arg(SSL *ctx, void *arg);" -.IP "unsigned long \fBSSL_clear_options\fR(\s-1SSL\s0 *ssl, unsigned long op);" 4 -.IX Item "unsigned long SSL_clear_options(SSL *ssl, unsigned long op);" -.IP "unsigned long \fBSSL_get_options\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "unsigned long SSL_get_options(SSL *ssl);" -.IP "unsigned long \fBSSL_set_options\fR(\s-1SSL\s0 *ssl, unsigned long op);" 4 -.IX Item "unsigned long SSL_set_options(SSL *ssl, unsigned long op);" -.IP "void \fBSSL_set_quiet_shutdown\fR(\s-1SSL\s0 *ssl, int mode);" 4 -.IX Item "void SSL_set_quiet_shutdown(SSL *ssl, int mode);" -.IP "void \fBSSL_set_read_ahead\fR(\s-1SSL\s0 *ssl, int yes);" 4 -.IX Item "void SSL_set_read_ahead(SSL *ssl, int yes);" -.IP "int \fBSSL_set_rfd\fR(\s-1SSL\s0 *ssl, int fd);" 4 -.IX Item "int SSL_set_rfd(SSL *ssl, int fd);" -.IP "int \fBSSL_set_session\fR(\s-1SSL\s0 *ssl, \s-1SSL_SESSION\s0 *session);" 4 -.IX Item "int SSL_set_session(SSL *ssl, SSL_SESSION *session);" -.IP "void \fBSSL_set_shutdown\fR(\s-1SSL\s0 *ssl, int mode);" 4 -.IX Item "void SSL_set_shutdown(SSL *ssl, int mode);" -.IP "int \fBSSL_set_ssl_method\fR(\s-1SSL\s0 *ssl, const \s-1SSL_METHOD\s0 *meth);" 4 -.IX Item "int SSL_set_ssl_method(SSL *ssl, const SSL_METHOD *meth);" -.IP "void \fBSSL_set_time\fR(\s-1SSL\s0 *ssl, long t);" 4 -.IX Item "void SSL_set_time(SSL *ssl, long t);" -.IP "void \fBSSL_set_timeout\fR(\s-1SSL\s0 *ssl, long t);" 4 -.IX Item "void SSL_set_timeout(SSL *ssl, long t);" -.IP "void \fBSSL_set_verify\fR(\s-1SSL\s0 *ssl, int mode, int (*callback);(void))" 4 -.IX Item "void SSL_set_verify(SSL *ssl, int mode, int (*callback);(void))" -.IP "void \fBSSL_set_verify_result\fR(\s-1SSL\s0 *ssl, long arg);" 4 -.IX Item "void SSL_set_verify_result(SSL *ssl, long arg);" -.IP "int \fBSSL_set_wfd\fR(\s-1SSL\s0 *ssl, int fd);" 4 -.IX Item "int SSL_set_wfd(SSL *ssl, int fd);" -.IP "int \fBSSL_shutdown\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_shutdown(SSL *ssl);" -.IP "\s-1OSSL_HANDSHAKE_STATE\s0 \fBSSL_get_state\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "OSSL_HANDSHAKE_STATE SSL_get_state(const SSL *ssl);" -.PD -Returns the current handshake state. -.IP "char *\fBSSL_state_string\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "char *SSL_state_string(const SSL *ssl);" -.PD 0 -.IP "char *\fBSSL_state_string_long\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "char *SSL_state_string_long(const SSL *ssl);" -.IP "long \fBSSL_total_renegotiations\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "long SSL_total_renegotiations(SSL *ssl);" -.IP "int \fBSSL_use_PrivateKey\fR(\s-1SSL\s0 *ssl, \s-1EVP_PKEY\s0 *pkey);" 4 -.IX Item "int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey);" -.IP "int \fBSSL_use_PrivateKey_ASN1\fR(int type, \s-1SSL\s0 *ssl, unsigned char *d, long len);" 4 -.IX Item "int SSL_use_PrivateKey_ASN1(int type, SSL *ssl, unsigned char *d, long len);" -.IP "int \fBSSL_use_PrivateKey_file\fR(\s-1SSL\s0 *ssl, const char *file, int type);" 4 -.IX Item "int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type);" -.IP "int \fBSSL_use_RSAPrivateKey\fR(\s-1SSL\s0 *ssl, \s-1RSA\s0 *rsa);" 4 -.IX Item "int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa);" -.IP "int \fBSSL_use_RSAPrivateKey_ASN1\fR(\s-1SSL\s0 *ssl, unsigned char *d, long len);" 4 -.IX Item "int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len);" -.IP "int \fBSSL_use_RSAPrivateKey_file\fR(\s-1SSL\s0 *ssl, const char *file, int type);" 4 -.IX Item "int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type);" -.IP "int \fBSSL_use_certificate\fR(\s-1SSL\s0 *ssl, X509 *x);" 4 -.IX Item "int SSL_use_certificate(SSL *ssl, X509 *x);" -.IP "int \fBSSL_use_certificate_ASN1\fR(\s-1SSL\s0 *ssl, int len, unsigned char *d);" 4 -.IX Item "int SSL_use_certificate_ASN1(SSL *ssl, int len, unsigned char *d);" -.IP "int \fBSSL_use_certificate_file\fR(\s-1SSL\s0 *ssl, const char *file, int type);" 4 -.IX Item "int SSL_use_certificate_file(SSL *ssl, const char *file, int type);" -.IP "int \fBSSL_use_cert_and_key\fR(\s-1SSL\s0 *ssl, X509 *x, \s-1EVP_PKEY\s0 *pkey, \s-1STACK_OF\s0(X509) *chain, int override);" 4 -.IX Item "int SSL_use_cert_and_key(SSL *ssl, X509 *x, EVP_PKEY *pkey, STACK_OF(X509) *chain, int override);" -.IP "int \fBSSL_version\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_version(const SSL *ssl);" -.IP "int \fBSSL_want\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_want(const SSL *ssl);" -.IP "int \fBSSL_want_nothing\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_want_nothing(const SSL *ssl);" -.IP "int \fBSSL_want_read\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_want_read(const SSL *ssl);" -.IP "int \fBSSL_want_write\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_want_write(const SSL *ssl);" -.IP "int \fBSSL_want_x509_lookup\fR(const \s-1SSL\s0 *ssl);" 4 -.IX Item "int SSL_want_x509_lookup(const SSL *ssl);" -.IP "int \fBSSL_write\fR(\s-1SSL\s0 *ssl, const void *buf, int num);" 4 -.IX Item "int SSL_write(SSL *ssl, const void *buf, int num);" -.IP "void \fBSSL_set_psk_client_callback\fR(\s-1SSL\s0 *ssl, unsigned int (*callback)(\s-1SSL\s0 *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len));" 4 -.IX Item "void SSL_set_psk_client_callback(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len));" -.IP "int \fBSSL_use_psk_identity_hint\fR(\s-1SSL\s0 *ssl, const char *hint);" 4 -.IX Item "int SSL_use_psk_identity_hint(SSL *ssl, const char *hint);" -.IP "void \fBSSL_set_psk_server_callback\fR(\s-1SSL\s0 *ssl, unsigned int (*callback)(\s-1SSL\s0 *ssl, const char *identity, unsigned char *psk, int max_psk_len));" 4 -.IX Item "void SSL_set_psk_server_callback(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len));" -.IP "const char *\fBSSL_get_psk_identity_hint\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "const char *SSL_get_psk_identity_hint(SSL *ssl);" -.IP "const char *\fBSSL_get_psk_identity\fR(\s-1SSL\s0 *ssl);" 4 -.IX Item "const char *SSL_get_psk_identity(SSL *ssl);" -.PD -.SH "RETURN VALUES" -.IX Header "RETURN VALUES" -See the individual manual pages for details. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -\&\fBopenssl\fR\|(1), \fBcrypto\fR\|(7), -\&\fBCRYPTO_get_ex_new_index\fR\|(3), -\&\fBSSL_accept\fR\|(3), \fBSSL_clear\fR\|(3), -\&\fBSSL_connect\fR\|(3), -\&\fBSSL_CIPHER_get_name\fR\|(3), -\&\fBSSL_COMP_add_compression_method\fR\|(3), -\&\fBSSL_CTX_add_extra_chain_cert\fR\|(3), -\&\fBSSL_CTX_add_session\fR\|(3), -\&\fBSSL_CTX_ctrl\fR\|(3), -\&\fBSSL_CTX_flush_sessions\fR\|(3), -\&\fBSSL_CTX_get_verify_mode\fR\|(3), -\&\fBSSL_CTX_load_verify_locations\fR\|(3) -\&\fBSSL_CTX_new\fR\|(3), -\&\fBSSL_CTX_sess_number\fR\|(3), -\&\fBSSL_CTX_sess_set_cache_size\fR\|(3), -\&\fBSSL_CTX_sess_set_get_cb\fR\|(3), -\&\fBSSL_CTX_sessions\fR\|(3), -\&\fBSSL_CTX_set_cert_store\fR\|(3), -\&\fBSSL_CTX_set_cert_verify_callback\fR\|(3), -\&\fBSSL_CTX_set_cipher_list\fR\|(3), -\&\fBSSL_CTX_set_client_CA_list\fR\|(3), -\&\fBSSL_CTX_set_client_cert_cb\fR\|(3), -\&\fBSSL_CTX_set_default_passwd_cb\fR\|(3), -\&\fBSSL_CTX_set_generate_session_id\fR\|(3), -\&\fBSSL_CTX_set_info_callback\fR\|(3), -\&\fBSSL_CTX_set_max_cert_list\fR\|(3), -\&\fBSSL_CTX_set_mode\fR\|(3), -\&\fBSSL_CTX_set_msg_callback\fR\|(3), -\&\fBSSL_CTX_set_options\fR\|(3), -\&\fBSSL_CTX_set_quiet_shutdown\fR\|(3), -\&\fBSSL_CTX_set_read_ahead\fR\|(3), -\&\fBSSL_CTX_set_security_level\fR\|(3), -\&\fBSSL_CTX_set_session_cache_mode\fR\|(3), -\&\fBSSL_CTX_set_session_id_context\fR\|(3), -\&\fBSSL_CTX_set_ssl_version\fR\|(3), -\&\fBSSL_CTX_set_timeout\fR\|(3), -\&\fBSSL_CTX_set_tmp_dh_callback\fR\|(3), -\&\fBSSL_CTX_set_verify\fR\|(3), -\&\fBSSL_CTX_use_certificate\fR\|(3), -\&\fBSSL_alert_type_string\fR\|(3), -\&\fBSSL_do_handshake\fR\|(3), -\&\fBSSL_enable_ct\fR\|(3), -\&\fBSSL_get_SSL_CTX\fR\|(3), -\&\fBSSL_get_ciphers\fR\|(3), -\&\fBSSL_get_client_CA_list\fR\|(3), -\&\fBSSL_get_default_timeout\fR\|(3), -\&\fBSSL_get_error\fR\|(3), -\&\fBSSL_get_ex_data_X509_STORE_CTX_idx\fR\|(3), -\&\fBSSL_get_fd\fR\|(3), -\&\fBSSL_get_peer_cert_chain\fR\|(3), -\&\fBSSL_get_rbio\fR\|(3), -\&\fBSSL_get_session\fR\|(3), -\&\fBSSL_get_verify_result\fR\|(3), -\&\fBSSL_get_version\fR\|(3), -\&\fBSSL_load_client_CA_file\fR\|(3), -\&\fBSSL_new\fR\|(3), -\&\fBSSL_pending\fR\|(3), -\&\fBSSL_read_ex\fR\|(3), -\&\fBSSL_read\fR\|(3), -\&\fBSSL_rstate_string\fR\|(3), -\&\fBSSL_session_reused\fR\|(3), -\&\fBSSL_set_bio\fR\|(3), -\&\fBSSL_set_connect_state\fR\|(3), -\&\fBSSL_set_fd\fR\|(3), -\&\fBSSL_set_session\fR\|(3), -\&\fBSSL_set_shutdown\fR\|(3), -\&\fBSSL_shutdown\fR\|(3), -\&\fBSSL_state_string\fR\|(3), -\&\fBSSL_want\fR\|(3), -\&\fBSSL_write_ex\fR\|(3), -\&\fBSSL_write\fR\|(3), -\&\fBSSL_SESSION_free\fR\|(3), -\&\fBSSL_SESSION_get_time\fR\|(3), -\&\fBd2i_SSL_SESSION\fR\|(3), -\&\fBSSL_CTX_set_psk_client_callback\fR\|(3), -\&\fBSSL_CTX_use_psk_identity_hint\fR\|(3), -\&\fBSSL_get_psk_identity\fR\|(3), -\&\fBDTLSv1_listen\fR\|(3) -.SH "HISTORY" -.IX Header "HISTORY" -\&\fBSSLv2_client_method\fR, \fBSSLv2_server_method\fR and \fBSSLv2_method\fR were removed -in OpenSSL 1.1.0. -.PP -The return type of \fBSSL_copy_session_id\fR was changed from void to int in -OpenSSL 1.1.0. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +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>. diff --git a/secure/lib/libcrypto/man/man7/x509.7 b/secure/lib/libcrypto/man/man7/x509.7 index 37fb163c5109..5a5967daf3da 100644 --- a/secure/lib/libcrypto/man/man7/x509.7 +++ b/secure/lib/libcrypto/man/man7/x509.7 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .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 \{\ @@ -132,8 +130,8 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "X509 7" -.TH X509 7 "2022-06-21" "1.1.1p" "OpenSSL" +.IX Title "X509 7ossl" +.TH X509 7ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -188,19 +186,19 @@ functions handle PKCS#10 certificate requests. \&\fBX509_NAME_add_entry_by_NID\fR\|(3), \&\fBX509_NAME_print_ex\fR\|(3), \&\fBX509_NAME_new\fR\|(3), +\&\fBPEM_X509_INFO_read\fR\|(3), \&\fBd2i_X509\fR\|(3), \&\fBd2i_X509_ALGOR\fR\|(3), \&\fBd2i_X509_CRL\fR\|(3), \&\fBd2i_X509_NAME\fR\|(3), \&\fBd2i_X509_REQ\fR\|(3), \&\fBd2i_X509_SIG\fR\|(3), -\&\fBX509v3\fR\|(3), \&\fBcrypto\fR\|(7) .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2003\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +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>. |