diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man7/provider.7')
| -rw-r--r-- | secure/lib/libcrypto/man/man7/provider.7 | 215 |
1 files changed, 81 insertions, 134 deletions
diff --git a/secure/lib/libcrypto/man/man7/provider.7 b/secure/lib/libcrypto/man/man7/provider.7 index 23a4ea979ce5..1870b49e57d9 100644 --- a/secure/lib/libcrypto/man/man7/provider.7 +++ b/secure/lib/libcrypto/man/man7/provider.7 @@ -1,4 +1,5 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== @@ -15,29 +16,12 @@ .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' +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .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\} @@ -68,82 +52,22 @@ . \} .\} .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" +.TH PROVIDER 7ossl 2025-07-01 3.5.1 OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh -.SH "NAME" +.SH NAME provider \- OpenSSL operation implementation providers -.SH "SYNOPSIS" +.SH SYNOPSIS .IX Header "SYNOPSIS" #include <openssl/provider.h> -.SH "DESCRIPTION" +.SH DESCRIPTION .IX Header "DESCRIPTION" -.SS "General" +.SS General .IX Subsection "General" This page contains information useful to provider authors. .PP @@ -152,7 +76,7 @@ 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, +decryption, key derivation, MAC calculation, signing and verification, etc. .PP An \fIalgorithm\fR is a named method to perform an operation. @@ -161,11 +85,11 @@ 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" +.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)). +functions in the form of an \fBOSSL_DISPATCH\fR\|(3) array, and by extension, +a set of \fBOSSL_ALGORITHM\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 @@ -207,7 +131,7 @@ the initialization function has completed and returned successfully. 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 +Its referred to with the number \fBOSSL_FUNC_PROVIDER_QUERY_OPERATION\fR and has the following signature: .PP .Vb 3 @@ -219,18 +143,18 @@ and has the following signature: \&\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). +\&\fIoperation_id\fR is an operation identity (see "Operations" 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 +The returned \fBOSSL_ALGORITHM\fR\|(3) is the foundation of any OpenSSL +library API 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" +(see "ALGORITHM FETCHING" 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. @@ -239,85 +163,85 @@ 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 +.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. +\&\fBEVP_MD\fR. +The number for this operation is \fBOSSL_OP_DIGEST\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. +\&\fBEVP_CIPHER\fR. +The number for this operation is \fBOSSL_OP_CIPHER\fR. The functions the provider can offer are described in \&\fBprovider\-cipher\fR\|(7). -.IP "Message Authentication Code (\s-1MAC\s0)" 4 +.IP "Message Authentication Code (MAC)" 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. +\&\fBEVP_MAC\fR. +The number for this operation is \fBOSSL_OP_MAC\fR. The functions the provider can offer are described in \&\fBprovider\-mac\fR\|(7). -.IP "Key Derivation Function (\s-1KDF\s0)" 4 +.IP "Key Derivation Function (KDF)" 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. +\&\fBEVP_KDF\fR. +The number for this operation is \fBOSSL_OP_KDF\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. +\&\fBEVP_KEYEXCH\fR. +The number for this operation is \fBOSSL_OP_KEYEXCH\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. +\&\fBEVP_ASYM_CIPHER\fR. +The number for this operation is \fBOSSL_OP_ASYM_CIPHER\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. +In the OpenSSL libraries, the corresponding method object is \fBEVP_KEM\fR. +The number for this operation is \fBOSSL_OP_KEM\fR. The functions the provider can offer are described in \fBprovider\-kem\fR\|(7). -.IP "Encoding" 4 +.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. +\&\fBOSSL_ENCODER\fR. +The number for this operation is \fBOSSL_OP_ENCODER\fR. The functions the provider can offer are described in \&\fBprovider\-encoder\fR\|(7). -.IP "Decoding" 4 +.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. +\&\fBOSSL_DECODER\fR. +The number for this operation is \fBOSSL_OP_DECODER\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 number for this operation is \fBOSSL_OP_RAND\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 number for this operation is \fBOSSL_OP_KEYMGMT\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 number for this operation is \fBOSSL_OP_SIGNATURE\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 number for this operation is \fBOSSL_OP_STORE\fR. The functions the provider can offer for store management are described in \&\fBprovider\-storemgmt\fR\|(7). .PP @@ -328,21 +252,44 @@ 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?] +ALGNAME[VERSION?][\-SUBNAME[VERSION?]?][\-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. +VERSION is only present if there are multiple versions of an algorithm (e.g. +MD2, MD4, MD5). 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 +SUBNAME may be present where multiple algorithms are combined together, +e.g. MD5\-SHA1. .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) +SIZE is only present if multiple versions of an algorithm exist with different +sizes (e.g. AES\-128\-CBC, AES\-256\-CBC) .PP -\&\s-1MODE\s0 is only present where applicable. +MODE 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. +.PP +\fIProvider dependencies\fR +.IX Subsection "Provider dependencies" +.PP +Providers may depend for their proper operation on the availability of +(functionality implemented in) other providers. As there is no mechanism to +express such dependencies towards the OpenSSL core, provider authors must +take care that such dependencies are either completely avoided or made visible +to users, e.g., by documentation and/or defensive programming, e.g., +outputting error messages if required external dependencies are not available, +e.g., when no provider implementing the required functionality has been +activated. In particular, provider initialization should not depend on other +providers already having been initialized. +.PP +\fINote on naming clashes\fR +.IX Subsection "Note on naming clashes" +.PP +It is possible to register the same algorithm name from within different +providers. Users should note that if no property query is specified, or +more than one implementation matches the property query then it is +unspecified which implementation of a particular algorithm will be returned. +Such naming clashes may also occur if algorithms only differ in +capitalization as "Algorithm naming" is case insensitive. .SH "OPENSSL PROVIDERS" .IX Header "OPENSSL PROVIDERS" OpenSSL provides a number of its own providers. These are the default, base, @@ -351,7 +298,7 @@ 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), +\&\fBOSSL_LIB_CTX\fR\|(3), \&\fBEVP_set_default_properties\fR\|(3), \&\fBEVP_MD_fetch\fR\|(3), \&\fBEVP_CIPHER_fetch\fR\|(3), @@ -361,15 +308,15 @@ providers. \&\fBprovider\-digest\fR\|(7), \&\fBprovider\-cipher\fR\|(7), \&\fBprovider\-keyexch\fR\|(7) -.SH "HISTORY" +.SH HISTORY .IX Header "HISTORY" The concept of providers and everything surrounding them was introduced in OpenSSL 3.0. -.SH "COPYRIGHT" +.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 +Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy -in the file \s-1LICENSE\s0 in the source distribution or at +in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>. |