diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man7/provider-base.7')
| -rw-r--r-- | secure/lib/libcrypto/man/man7/provider-base.7 | 531 |
1 files changed, 298 insertions, 233 deletions
diff --git a/secure/lib/libcrypto/man/man7/provider-base.7 b/secure/lib/libcrypto/man/man7/provider-base.7 index 89a9c99b6d9b..a7a3f1e008a1 100644 --- a/secure/lib/libcrypto/man/man7/provider-base.7 +++ b/secure/lib/libcrypto/man/man7/provider-base.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,78 +52,18 @@ . \} .\} .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" +.TH PROVIDER-BASE 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\-base \&\- The basic OpenSSL library <\-> provider functions -.SH "SYNOPSIS" +.SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& #include <openssl/core_dispatch.h> @@ -211,13 +135,23 @@ provider\-base \& size_t get_entropy(const OSSL_CORE_HANDLE *handle, \& unsigned char **pout, int entropy, \& size_t min_len, size_t max_len); +\& size_t get_user_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); +\& void cleanup_user_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); +\& size_t get_user_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); +\& void cleanup_user_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, @@ -248,18 +182,18 @@ provider\-base \& OSSL_CALLBACK *cb, void *arg); \& int provider_self_test(void *provctx); .Ve -.SH "DESCRIPTION" +.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". +All "functions" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays, in the call +of the provider initialization function. See "Provider" in \fBprovider\fR\|(7) +for a description of the initialization function. They are known as "upcalls". .PP -All these \*(L"functions\*(R" have a corresponding function type definition +All these "functions" 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 +function pointer from a \fBOSSL_DISPATCH\fR\|(3) element named \&\fBOSSL_FUNC_{name}\fR. -For example, the \*(L"function\*(R" \fBcore_gettable_params()\fR has these: +For example, the "function" \fBcore_gettable_params()\fR has these: .PP .Vb 4 \& typedef OSSL_PARAM * @@ -268,10 +202,10 @@ For example, the \*(L"function\*(R" \fBcore_gettable_params()\fR has these: \& 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 +\&\fBOSSL_DISPATCH\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 +For \fIin\fR (the \fBOSSL_DISPATCH\fR\|(3) array passed from \fIlibcrypto\fR to the provider): .PP .Vb 10 @@ -309,9 +243,13 @@ provider): \& 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_get_user_entropy OSSL_FUNC_GET_USER_ENTROPY \& ossl_rand_cleanup_entropy OSSL_FUNC_CLEANUP_ENTROPY +\& ossl_rand_cleanup_user_entropy OSSL_FUNC_CLEANUP_USER_ENTROPY \& ossl_rand_get_nonce OSSL_FUNC_GET_NONCE +\& ossl_rand_get_user_nonce OSSL_FUNC_GET_USER_NONCE \& ossl_rand_cleanup_nonce OSSL_FUNC_CLEANUP_NONCE +\& ossl_rand_cleanup_user_nonce OSSL_FUNC_CLEANUP_USER_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 @@ -321,7 +259,7 @@ provider): \& 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 +For \fI*out\fR (the \fBOSSL_DISPATCH\fR\|(3) array passed from the provider to \&\fIlibcrypto\fR): .PP .Vb 8 @@ -337,10 +275,10 @@ For \fI*out\fR (the \s-1\fBOSSL_DISPATCH\s0\fR\|(3) array passed from the provid .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. +\&\fBOSSL_PARAM\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 +See "Core parameters" below for a description of currently known parameters. .PP The \fBcore_thread_start()\fR function informs the core that the provider has stated @@ -355,21 +293,21 @@ freeing thread local variables. \&\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. Never cast this to OSSL_LIB_CTX in a provider that is not +built-in as the OSSL_LIB_CTX of the library loading the provider might be +a completely different structure than the OSSL_LIB_CTX 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 +.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 +.IP \fBcore_set_error_debug()\fR 4 .IX Item "core_set_error_debug()" sets debugging information in the current thread specific error record. @@ -377,7 +315,7 @@ 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 +.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 @@ -391,14 +329,13 @@ 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 +The \fBcore_obj_create()\fR function registers a new OID 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 +It will treat as success the case where the OID 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 with the existing OID, 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) @@ -407,13 +344,12 @@ 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 +rather than a numeric NID. Any name (OID, 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 +underlying signature or digest algorithm). For \fIdigest_name\fR, NULL 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, @@ -423,9 +359,9 @@ This function is not thread safe. \&\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 +the same name. As a matter of fact, the pointers in the \fBOSSL_DISPATCH\fR\|(3) +array are typically direct pointers to those public functions. Note that the BIO +functions take an \fBOSSL_CORE_BIO\fR type rather than the standard \fBBIO\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 @@ -437,9 +373,17 @@ 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 +\&\fBget_user_entropy()\fR is the same as \fBget_entropy()\fR except that it will +attempt to gather seed material via the seed source specified by a call to +\&\fBRAND_set_seed_source_type\fR\|(3) or via "Random Configuration" in \fBconfig\fR\|(5). +.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. +\&\fBget_entropy()\fR. The entropy pointer returned by \fBget_entropy()\fR +is passed in \fBbuf\fR and its length in \fBlen\fR. +.PP +\&\fBcleanup_user_entropy()\fR is used to clean up and free the buffer returned by +\&\fBget_user_entropy()\fR. The entropy pointer returned by \fBget_user_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. @@ -449,9 +393,17 @@ 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 +\&\fBget_user_nonce()\fR is the same as \fBget_nonce()\fR except that it will attempt +to gather seed material via the seed source specified by a call to +\&\fBRAND_set_seed_source_type\fR\|(3) or via "Random Configuration" in \fBconfig\fR\|(5). +.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. +\&\fBget_nonce()\fR. The nonce pointer returned by \fBget_nonce()\fR +is passed in \fBbuf\fR and its length in \fBlen\fR. +.PP +\&\fBcleanup_user_nonce()\fR is used to clean up and free the buffer returned by +\&\fBget_user_nonce()\fR. The nonce pointer returned by \fBget_user_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. @@ -459,7 +411,7 @@ loading and unloading of providers in the application's library context. 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. +and must not call other OpenSSL API 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 @@ -504,13 +456,13 @@ 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 +descriptor \fBOSSL_PARAM\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 +\&\fBprovider_get_params()\fR should process the \fBOSSL_PARAM\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) +\&\fBprovider_query_operation()\fR should return a constant \fBOSSL_ALGORITHM\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 @@ -521,18 +473,18 @@ not store a reference). 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) +\&\fBprovider_get_reason_strings()\fR should return a constant \fBOSSL_ITEM\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 +it a set of \fBOSSL_PARAM\fR\|(3)s and the caller supplied argument \fIarg\fR. The +\&\fBOSSL_PARAM\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. +"CAPABILITIES" 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 @@ -546,25 +498,21 @@ useless without at least \fBprovider_query_operation()\fR, and .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>" +.IP """name"" (\fBOSSL_PROV_PARAM_NAME\fR) <UTF8 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>" +.IP """version"" (\fBOSSL_PROV_PARAM_VERSION\fR) <UTF8 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 +OpenSSL in-built providers use OPENSSL_VERSION_STR, 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>" +.IP """buildinfo"" (\fBOSSL_PROV_PARAM_BUILDINFO\fR) <UTF8 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 +OpenSSL in-built providers use OPENSSL_FULL_VERSION_STR, 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>" +.IP """status"" (\fBOSSL_PROV_PARAM_STATUS\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 @@ -572,18 +520,15 @@ This returns 0 if the provider has entered an error state, otherwise it returns .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>" +.IP """openssl-version"" (\fBOSSL_PROV_PARAM_CORE_VERSION\fR) <UTF8 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>" +expanded from the macro \fBOPENSSL_VERSION_STR\fR. +.IP """provider-name"" (\fBOSSL_PROV_PARAM_CORE_PROV_NAME\fR) <UTF8 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>" +.IP """module-filename"" (\fBOSSL_PROV_PARAM_CORE_MODULE_FILENAME\fR) <UTF8 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 @@ -615,120 +560,234 @@ For example, let's say we have the following config example: .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 +.IP """activate""" 4 +.IX Item """activate""" +pointing at the string "1" +.IP """data1""" 4 +.IX Item """data1""" +pointing at the string "2" +.IP """data2""" 4 +.IX Item """data2""" +pointing at the string "str" +.IP """more.data3""" 4 +.IX Item """more.data3""" +pointing at the string "foo,bar" +.PP +For more information on handling parameters, see \fBOSSL_PARAM\fR\|(3) as \&\fBOSSL_PARAM_int\fR\|(3). -.SH "CAPABILITIES" +.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" +\fI"TLS-GROUP" 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 +The "TLS-GROUP" capability can be queried by libssl to discover the list of +TLS groups that a provider can support. Each group supported can be used for +\&\fIkey exchange\fR (KEX) or \fIkey encapsulation method\fR (KEM) during a TLS 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 +TLS clients can advertise the list of TLS groups they support in the +supported_groups extension, and TLS 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 +Each TLS 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 +\&\fBOSSL_CAPABILITY_TLS_GROUP_IS_KEM\fR): +.IP """tls-group-name"" (\fBOSSL_CAPABILITY_TLS_GROUP_NAME\fR) <UTF8 string>" 4 +.IX Item """tls-group-name"" (OSSL_CAPABILITY_TLS_GROUP_NAME) <UTF8 string>" +The name of the group as given in the IANA TLS 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>" +.IP """tls-group-name-internal"" (\fBOSSL_CAPABILITY_TLS_GROUP_NAME_INTERNAL\fR) <UTF8 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>" +"tls-group-name", but does not have to be. +.IP """tls-group-id"" (\fBOSSL_CAPABILITY_TLS_GROUP_ID\fR) <unsigned integer>" 4 +.IX Item """tls-group-id"" (OSSL_CAPABILITY_TLS_GROUP_ID) <unsigned integer>" +The TLS group id value as given in the IANA TLS Supported Groups registry. +.Sp +It is possible to register the same group id 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 for a particular group id will be used. +.IP """tls-group-alg"" (\fBOSSL_CAPABILITY_TLS_GROUP_ALG\fR) <UTF8 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. +or \fIkey encapsulation method\fR (KEM), as implied by the optional +\&\fBOSSL_CAPABILITY_TLS_GROUP_IS_KEM\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>" +key/parameter generation parameter, \fBOSSL_PKEY_PARAM_GROUP_NAME\fR. The group +name given via "tls-group-name-internal" above will be passed via +\&\fBOSSL_PKEY_PARAM_GROUP_NAME\fR when libssl wishes to generate keys/parameters. +.IP """tls-group-sec-bits"" (\fBOSSL_CAPABILITY_TLS_GROUP_SECURITY_BITS\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 +should be comparable with the ones given in table 2 and 3 of the NIST SP800\-57 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). +.IP """tls-group-is-kem"" (\fBOSSL_CAPABILITY_TLS_GROUP_IS_KEM\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 (KEX) +mode (0, default) or in \fIkey encapsulation method\fR (KEM) mode (1). .Sp -This parameter is optional: if not specified, \s-1KEX\s0 mode is assumed as the default +This parameter is optional: if not specified, KEX 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 +In KEX mode, in a typical Diffie-Hellman fashion, both sides execute \fIkeygen\fR +then \fIderive\fR against the peer public key. To operate in KEX 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 +In KEM 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 +in KEM 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 +Both in KEX and KEM 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>" +.IP """tls-min-tls"" (\fBOSSL_CAPABILITY_TLS_GROUP_MIN_TLS\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>" +.IP """tls-max-tls"" (\fBOSSL_CAPABILITY_TLS_GROUP_MAX_TLS\fR) <integer>" 4 +.IX Item """tls-max-tls"" (OSSL_CAPABILITY_TLS_GROUP_MAX_TLS) <integer>" +.IP """tls-min-dtls"" (\fBOSSL_CAPABILITY_TLS_GROUP_MIN_DTLS\fR) <integer>" 4 +.IX Item """tls-min-dtls"" (OSSL_CAPABILITY_TLS_GROUP_MIN_DTLS) <integer>" +.IP """tls-max-dtls"" (\fBOSSL_CAPABILITY_TLS_GROUP_MAX_DTLS\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 +These parameters can be used to describe the minimum and maximum TLS and DTLS 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 +of the various TLS 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" +.PP +\fI"TLS-SIGALG" Capability\fR +.IX Subsection """TLS-SIGALG"" Capability" +.PP +The "TLS-SIGALG" capability can be queried by libssl to discover the list of +TLS signature algorithms that a provider can support. Each signature supported +can be used for client\- or server-authentication in addition to the built-in +signature algorithms. +TLS1.3 clients can advertise the list of TLS signature algorithms they support +in the signature_algorithms extension, and TLS servers can select an algorithm +from the offered list that they also support. In this way a provider can add +to the list of signature algorithms that libssl already supports with +additional ones. +.PP +Each TLS signature algorithm that a provider supports should be described via +the callback passed in through the provider_get_capabilities function. Each +algorithm can have the following details supplied: +.IP """iana-name"" (\fBOSSL_CAPABILITY_TLS_SIGALG_IANA_NAME\fR) <UTF8 string>" 4 +.IX Item """iana-name"" (OSSL_CAPABILITY_TLS_SIGALG_IANA_NAME) <UTF8 string>" +The name of the signature algorithm as given in the IANA TLS Signature Scheme +registry as "Description": +<https://www.iana.org/assignments/tls\-parameters/tls\-parameters.xhtml#tls\-signaturescheme>. +This value must be supplied. +.IP """iana-code-point"" (\fBOSSL_CAPABILITY_TLS_SIGALG_CODE_POINT\fR) <unsigned integer>" 4 +.IX Item """iana-code-point"" (OSSL_CAPABILITY_TLS_SIGALG_CODE_POINT) <unsigned integer>" +The TLS algorithm ID value as given in the IANA TLS SignatureScheme registry. +This value must be supplied. +.Sp +It is possible to register the same code point 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 for a particular code point will be used. +.IP """sigalg-name"" (\fBOSSL_CAPABILITY_TLS_SIGALG_NAME\fR) <UTF8 string>" 4 +.IX Item """sigalg-name"" (OSSL_CAPABILITY_TLS_SIGALG_NAME) <UTF8 string>" +A name for the full (possibly composite hash-and-signature) signature +algorithm. +The provider may, but is not obligated to, provide a signature implementation +with this name; if it doesn't, this is assumed to be a composite of a pure +signature algorithm and a hash algorithm, which must be given with the +parameters "sig-name" and "hash-name". +This value must be supplied. +.IP """sigalg-oid"" (\fBOSSL_CAPABILITY_TLS_SIGALG_OID\fR) <UTF8 string>" 4 +.IX Item """sigalg-oid"" (OSSL_CAPABILITY_TLS_SIGALG_OID) <UTF8 string>" +The OID of the "sigalg-name" algorithm in canonical numeric text form. If +this parameter is given, \fBOBJ_create()\fR will be used to create an OBJ and +a NID for this OID, using the "sigalg-name" parameter for its (short) name. +Otherwise, it's assumed to already exist in the object database, possibly +done by the provider with the \fBcore_obj_create()\fR upcall. +This value is optional. +.IP """sig-name"" (\fBOSSL_CAPABILITY_TLS_SIGALG_SIG_NAME\fR) <UTF8 string>" 4 +.IX Item """sig-name"" (OSSL_CAPABILITY_TLS_SIGALG_SIG_NAME) <UTF8 string>" +The name of the pure signature algorithm that is part of a composite +"sigalg-name". If "sigalg-name" is implemented by the provider, this +parameter is redundant and must not be given. +This value is optional. +.IP """sig-oid"" (\fBOSSL_CAPABILITY_TLS_SIGALG_SIG_OID\fR) <UTF8 string>" 4 +.IX Item """sig-oid"" (OSSL_CAPABILITY_TLS_SIGALG_SIG_OID) <UTF8 string>" +The OID of the "sig-name" algorithm in canonical numeric text form. If +this parameter is given, \fBOBJ_create()\fR will be used to create an OBJ and +a NID for this OID, using the "sig-name" parameter for its (short) name. +Otherwise, it is assumed to already exist in the object database. This +can be done by the provider using the \fBcore_obj_create()\fR upcall. +This value is optional. +.IP """hash-name"" (\fBOSSL_CAPABILITY_TLS_SIGALG_HASH_NAME\fR) <UTF8 string>" 4 +.IX Item """hash-name"" (OSSL_CAPABILITY_TLS_SIGALG_HASH_NAME) <UTF8 string>" +The name of the hash algorithm that is part of a composite "sigalg-name". +If "sigalg-name" is implemented by the provider, this parameter is redundant +and must not be given. +This value is optional. +.IP """hash-oid"" (\fBOSSL_CAPABILITY_TLS_SIGALG_HASH_OID\fR) <UTF8 string>" 4 +.IX Item """hash-oid"" (OSSL_CAPABILITY_TLS_SIGALG_HASH_OID) <UTF8 string>" +The OID of the "hash-name" algorithm in canonical numeric text form. If +this parameter is given, \fBOBJ_create()\fR will be used to create an OBJ and +a NID for this OID, using the "hash-name" parameter for its (short) name. +Otherwise, it's assumed to already exist in the object database, possibly +done by the provider with the \fBcore_obj_create()\fR upcall. +This value is optional. +.IP """key-type"" (\fBOSSL_CAPABILITY_TLS_SIGALG_KEYTYPE\fR) <UTF8 string>" 4 +.IX Item """key-type"" (OSSL_CAPABILITY_TLS_SIGALG_KEYTYPE) <UTF8 string>" +The key type of the public key of applicable certificates. If this parameter +isn't present, it's assumed to be the same as "sig-name" if that's present, +otherwise "sigalg-name". +This value is optional. +.IP """key-type-oid"" (\fBOSSL_CAPABILITY_TLS_SIGALG_KEYTYPE_OID\fR) <UTF8 string>" 4 +.IX Item """key-type-oid"" (OSSL_CAPABILITY_TLS_SIGALG_KEYTYPE_OID) <UTF8 string>" +The OID of the "key-type" in canonical numeric text form. If +this parameter is given, \fBOBJ_create()\fR will be used to create an OBJ and +a NID for this OID, using the "key-type" parameter for its (short) name. +Otherwise, it's assumed to already exist in the object database, possibly +done by the provider with the \fBcore_obj_create()\fR upcall. +This value is optional. +.IP """sec-bits"" (\fBOSSL_CAPABILITY_TLS_SIGALG_SECURITY_BITS\fR) <unsigned integer>" 4 +.IX Item """sec-bits"" (OSSL_CAPABILITY_TLS_SIGALG_SECURITY_BITS) <unsigned integer>" +The number of bits of security offered by keys of this algorithm. The number +of bits should be comparable with the ones given in table 2 and 3 of the NIST +SP800\-57 document. This number is used to determine the security strength of +the algorithm if no digest algorithm has been registered that otherwise +defines the security strength. If the signature algorithm implements its own +digest internally, this value needs to be set to properly reflect the overall +security strength. +This value must be supplied. +.IP """tls-min-tls"" (\fBOSSL_CAPABILITY_TLS_SIGALG_MIN_TLS\fR) <integer>" 4 +.IX Item """tls-min-tls"" (OSSL_CAPABILITY_TLS_SIGALG_MIN_TLS) <integer>" +.PD 0 +.IP """tls-max-tls"" (\fBOSSL_CAPABILITY_TLS_SIGALG_MAX_TLS\fR) <integer>" 4 +.IX Item """tls-max-tls"" (OSSL_CAPABILITY_TLS_SIGALG_MAX_TLS) <integer>" +.IP """tls-min-dtls"" (\fBOSSL_CAPABILITY_TLS_SIGALG_MIN_DTLS\fR) <integer>" 4 +.IX Item """tls-min-dtls"" (OSSL_CAPABILITY_TLS_SIGALG_MIN_DTLS) <integer>" +.IP """tls-max-dtls"" (\fBOSSL_CAPABILITY_TLS_SIGALG_MAX_DTLS\fR) <integer>" 4 +.IX Item """tls-max-dtls"" (OSSL_CAPABILITY_TLS_SIGALG_MAX_DTLS) <integer>" +.PD +These parameters can be used to describe the minimum and maximum TLS and DTLS +versions supported by the signature algorithm. The values equate to the +on-the-wire encoding of the various TLS 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 in either the min or max field +indicates that the signature algorithm should not be used in that protocol. +Presently, provider signature algorithms are used only with TLS 1.3, if +that's enclosed in the specified range. +.SH NOTES +.IX Header "NOTES" +The \fBcore_obj_create()\fR and \fBcore_obj_add_sigid()\fR functions were not thread safe +in OpenSSL 3.0. +.SH EXAMPLES .IX Header "EXAMPLES" This is an example of a simple provider made available as a dynamically loadable module. @@ -745,7 +804,7 @@ operation \f(CW\*(C`BAR\*(C'\fR. \& \& static const OSSL_ITEM reasons[] = { \& { E_MALLOC, "memory allocation failure" }. -\& { 0, NULL } /* Termination */ +\& OSSL_DISPATCH_END \& }; \& \& /* @@ -825,7 +884,7 @@ operation \f(CW\*(C`BAR\*(C'\fR. \& { 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 } +\& OSSL_DISPATCH_END \& }; \& \& static const OSSL_ALGORITHM bars[] = { @@ -857,7 +916,7 @@ operation \f(CW\*(C`BAR\*(C'\fR. \& { 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 } +\& OSSL_DISPATCH_END \& }; \& \& int OSSL_provider_init(const OSSL_CORE_HANDLE *handle, @@ -923,15 +982,21 @@ This relies on a few things existing in \fIopenssl/core_dispatch.h\fR: .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBprovider\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" +.PP +Definitions for +\&\fBOSSL_CAPABILITY_TLS_SIGALG_MIN_DTLS\fR +and +\&\fBOSSL_CAPABILITY_TLS_SIGALG_MAX_DTLS\fR +were added in OpenSSL 3.5. +.SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2019\-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019\-2025 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>. |