| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "PROVIDER-BASE 7SSL" |
| 58 |
.TH PROVIDER-BASE 7SSL 2026-04-07 3.6.2 OpenSSL |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
provider\-base |
| 65 |
\&\- The basic OpenSSL library <\-> provider functions |
| 66 |
.SH SYNOPSIS |
| 67 |
.IX Header "SYNOPSIS" |
| 68 |
.Vb 1 |
| 69 |
\& #include <openssl/core_dispatch.h> |
| 70 |
\& |
| 71 |
\& /* |
| 72 |
\& * None of these are actual functions, but are displayed like this for |
| 73 |
\& * the function signatures for functions that are offered as function |
| 74 |
\& * pointers in OSSL_DISPATCH arrays. |
| 75 |
\& */ |
| 76 |
\& |
| 77 |
\& /* Functions offered by libcrypto to the providers */ |
| 78 |
\& const OSSL_ITEM *core_gettable_params(const OSSL_CORE_HANDLE *handle); |
| 79 |
\& int core_get_params(const OSSL_CORE_HANDLE *handle, OSSL_PARAM params[]); |
| 80 |
\& |
| 81 |
\& typedef void (*OSSL_thread_stop_handler_fn)(void *arg); |
| 82 |
\& int core_thread_start(const OSSL_CORE_HANDLE *handle, |
| 83 |
\& OSSL_thread_stop_handler_fn handfn, |
| 84 |
\& void *arg); |
| 85 |
\& |
| 86 |
\& OPENSSL_CORE_CTX *core_get_libctx(const OSSL_CORE_HANDLE *handle); |
| 87 |
\& void core_new_error(const OSSL_CORE_HANDLE *handle); |
| 88 |
\& void core_set_error_debug(const OSSL_CORE_HANDLE *handle, |
| 89 |
\& const char *file, int line, const char *func); |
| 90 |
\& void core_vset_error(const OSSL_CORE_HANDLE *handle, |
| 91 |
\& uint32_t reason, const char *fmt, va_list args); |
| 92 |
\& |
| 93 |
\& int core_obj_add_sigid(const OSSL_CORE_HANDLE *prov, const char *sign_name, |
| 94 |
\& const char *digest_name, const char *pkey_name); |
| 95 |
\& int core_obj_create(const OSSL_CORE_HANDLE *handle, const char *oid, |
| 96 |
\& const char *sn, const char *ln); |
| 97 |
\& |
| 98 |
\& /* |
| 99 |
\& * Some OpenSSL functionality is directly offered to providers via |
| 100 |
\& * dispatch |
| 101 |
\& */ |
| 102 |
\& void *CRYPTO_malloc(size_t num, const char *file, int line); |
| 103 |
\& void *CRYPTO_zalloc(size_t num, const char *file, int line); |
| 104 |
\& void CRYPTO_free(void *ptr, const char *file, int line); |
| 105 |
\& void CRYPTO_clear_free(void *ptr, size_t num, |
| 106 |
\& const char *file, int line); |
| 107 |
\& void *CRYPTO_realloc(void *addr, size_t num, |
| 108 |
\& const char *file, int line); |
| 109 |
\& void *CRYPTO_clear_realloc(void *addr, size_t old_num, size_t num, |
| 110 |
\& const char *file, int line); |
| 111 |
\& void *CRYPTO_secure_malloc(size_t num, const char *file, int line); |
| 112 |
\& void *CRYPTO_secure_zalloc(size_t num, const char *file, int line); |
| 113 |
\& void CRYPTO_secure_free(void *ptr, const char *file, int line); |
| 114 |
\& void CRYPTO_secure_clear_free(void *ptr, size_t num, |
| 115 |
\& const char *file, int line); |
| 116 |
\& int CRYPTO_secure_allocated(const void *ptr); |
| 117 |
\& void OPENSSL_cleanse(void *ptr, size_t len); |
| 118 |
\& |
| 119 |
\& unsigned char *OPENSSL_hexstr2buf(const char *str, long *buflen); |
| 120 |
\& |
| 121 |
\& OSSL_CORE_BIO *BIO_new_file(const char *filename, const char *mode); |
| 122 |
\& OSSL_CORE_BIO *BIO_new_membuf(const void *buf, int len); |
| 123 |
\& int BIO_read_ex(OSSL_CORE_BIO *bio, void *data, size_t data_len, |
| 124 |
\& size_t *bytes_read); |
| 125 |
\& int BIO_write_ex(OSSL_CORE_BIO *bio, const void *data, size_t data_len, |
| 126 |
\& size_t *written); |
| 127 |
\& int BIO_up_ref(OSSL_CORE_BIO *bio); |
| 128 |
\& int BIO_free(OSSL_CORE_BIO *bio); |
| 129 |
\& int BIO_vprintf(OSSL_CORE_BIO *bio, const char *format, va_list args); |
| 130 |
\& int BIO_vsnprintf(char *buf, size_t n, const char *fmt, va_list args); |
| 131 |
\& |
| 132 |
\& void OSSL_SELF_TEST_set_callback(OSSL_LIB_CTX *libctx, OSSL_CALLBACK *cb, |
| 133 |
\& void *cbarg); |
| 134 |
\& |
| 135 |
\& size_t get_entropy(const OSSL_CORE_HANDLE *handle, |
| 136 |
\& unsigned char **pout, int entropy, |
| 137 |
\& size_t min_len, size_t max_len); |
| 138 |
\& size_t get_user_entropy(const OSSL_CORE_HANDLE *handle, |
| 139 |
\& unsigned char **pout, int entropy, |
| 140 |
\& size_t min_len, size_t max_len); |
| 141 |
\& void cleanup_entropy(const OSSL_CORE_HANDLE *handle, |
| 142 |
\& unsigned char *buf, size_t len); |
| 143 |
\& void cleanup_user_entropy(const OSSL_CORE_HANDLE *handle, |
| 144 |
\& unsigned char *buf, size_t len); |
| 145 |
\& size_t get_nonce(const OSSL_CORE_HANDLE *handle, |
| 146 |
\& unsigned char **pout, size_t min_len, size_t max_len, |
| 147 |
\& const void *salt, size_t salt_len); |
| 148 |
\& size_t get_user_nonce(const OSSL_CORE_HANDLE *handle, |
| 149 |
\& unsigned char **pout, size_t min_len, size_t max_len, |
| 150 |
\& const void *salt, size_t salt_len); |
| 151 |
\& void cleanup_nonce(const OSSL_CORE_HANDLE *handle, |
| 152 |
\& unsigned char *buf, size_t len); |
| 153 |
\& void cleanup_user_nonce(const OSSL_CORE_HANDLE *handle, |
| 154 |
\& unsigned char *buf, size_t len); |
| 155 |
\& |
| 156 |
\& /* Functions for querying the providers in the application library context */ |
| 157 |
\& int provider_register_child_cb(const OSSL_CORE_HANDLE *handle, |
| 158 |
\& int (*create_cb)(const OSSL_CORE_HANDLE *provider, |
| 159 |
\& void *cbdata), |
| 160 |
\& int (*remove_cb)(const OSSL_CORE_HANDLE *provider, |
| 161 |
\& void *cbdata), |
| 162 |
\& int (*global_props_cb)(const char *props, void *cbdata), |
| 163 |
\& void *cbdata); |
| 164 |
\& void provider_deregister_child_cb(const OSSL_CORE_HANDLE *handle); |
| 165 |
\& const char *provider_name(const OSSL_CORE_HANDLE *prov); |
| 166 |
\& void *provider_get0_provider_ctx(const OSSL_CORE_HANDLE *prov); |
| 167 |
\& const OSSL_DISPATCH *provider_get0_dispatch(const OSSL_CORE_HANDLE *prov); |
| 168 |
\& int provider_up_ref(const OSSL_CORE_HANDLE *prov, int activate); |
| 169 |
\& int provider_free(const OSSL_CORE_HANDLE *prov, int deactivate); |
| 170 |
\& |
| 171 |
\& /* Functions offered by the provider to libcrypto */ |
| 172 |
\& void provider_teardown(void *provctx); |
| 173 |
\& const OSSL_ITEM *provider_gettable_params(void *provctx); |
| 174 |
\& int provider_get_params(void *provctx, OSSL_PARAM params[]); |
| 175 |
\& const OSSL_ALGORITHM *provider_query_operation(void *provctx, |
| 176 |
\& int operation_id, |
| 177 |
\& const int *no_store); |
| 178 |
\& void provider_unquery_operation(void *provctx, int operation_id, |
| 179 |
\& const OSSL_ALGORITHM *algs); |
| 180 |
\& const OSSL_ITEM *provider_get_reason_strings(void *provctx); |
| 181 |
\& int provider_get_capabilities(void *provctx, const char *capability, |
| 182 |
\& OSSL_CALLBACK *cb, void *arg); |
| 183 |
\& int provider_self_test(void *provctx); |
| 184 |
.Ve |
| 185 |
.SH DESCRIPTION |
| 186 |
.IX Header "DESCRIPTION" |
| 187 |
All "functions" mentioned here are passed as function pointers between |
| 188 |
\&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays, in the call |
| 189 |
of the provider initialization function. See "Provider" in \fBprovider\fR\|(7) |
| 190 |
for a description of the initialization function. They are known as "upcalls". |
| 191 |
.PP |
| 192 |
All these "functions" have a corresponding function type definition |
| 193 |
named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the |
| 194 |
function pointer from a \fBOSSL_DISPATCH\fR\|(3) element named |
| 195 |
\&\fBOSSL_FUNC_{name}\fR. |
| 196 |
For example, the "function" \fBcore_gettable_params()\fR has these: |
| 197 |
.PP |
| 198 |
.Vb 4 |
| 199 |
\& typedef OSSL_PARAM * |
| 200 |
\& (OSSL_FUNC_core_gettable_params_fn)(const OSSL_CORE_HANDLE *handle); |
| 201 |
\& static ossl_inline OSSL_NAME_core_gettable_params_fn |
| 202 |
\& OSSL_FUNC_core_gettable_params(const OSSL_DISPATCH *opf); |
| 203 |
.Ve |
| 204 |
.PP |
| 205 |
\&\fBOSSL_DISPATCH\fR\|(3) array entries contain a \fIfunction_id\fR field that |
| 206 |
identifies the function. The \fIfunction_id\fR numbers are provided as |
| 207 |
macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: |
| 208 |
.PP |
| 209 |
For \fIin\fR (the \fBOSSL_DISPATCH\fR\|(3) array passed from \fIlibcrypto\fR to the |
| 210 |
provider): |
| 211 |
.PP |
| 212 |
.Vb 10 |
| 213 |
\& core_gettable_params OSSL_FUNC_CORE_GETTABLE_PARAMS |
| 214 |
\& core_get_params OSSL_FUNC_CORE_GET_PARAMS |
| 215 |
\& core_thread_start OSSL_FUNC_CORE_THREAD_START |
| 216 |
\& core_get_libctx OSSL_FUNC_CORE_GET_LIBCTX |
| 217 |
\& core_new_error OSSL_FUNC_CORE_NEW_ERROR |
| 218 |
\& core_set_error_debug OSSL_FUNC_CORE_SET_ERROR_DEBUG |
| 219 |
\& core_vset_error OSSL_FUNC_CORE_VSET_ERROR |
| 220 |
\& core_set_error_mark OSSL_FUNC_CORE_SET_ERROR_MARK |
| 221 |
\& core_clear_last_error_mark OSSL_FUNC_CORE_CLEAR_LAST_ERROR_MARK |
| 222 |
\& core_pop_error_to_mark OSSL_FUNC_CORE_POP_ERROR_TO_MARK |
| 223 |
\& core_count_to_mark OSSL_FUNC_CORE_COUNT_TO_MARK |
| 224 |
\& core_obj_add_sigid OSSL_FUNC_CORE_OBJ_ADD_SIGID |
| 225 |
\& core_obj_create OSSL_FUNC_CORE_OBJ_CREATE |
| 226 |
\& CRYPTO_malloc OSSL_FUNC_CRYPTO_MALLOC |
| 227 |
\& CRYPTO_zalloc OSSL_FUNC_CRYPTO_ZALLOC |
| 228 |
\& CRYPTO_free OSSL_FUNC_CRYPTO_FREE |
| 229 |
\& CRYPTO_clear_free OSSL_FUNC_CRYPTO_CLEAR_FREE |
| 230 |
\& CRYPTO_realloc OSSL_FUNC_CRYPTO_REALLOC |
| 231 |
\& CRYPTO_clear_realloc OSSL_FUNC_CRYPTO_CLEAR_REALLOC |
| 232 |
\& CRYPTO_secure_malloc OSSL_FUNC_CRYPTO_SECURE_MALLOC |
| 233 |
\& CRYPTO_secure_zalloc OSSL_FUNC_CRYPTO_SECURE_ZALLOC |
| 234 |
\& CRYPTO_secure_free OSSL_FUNC_CRYPTO_SECURE_FREE |
| 235 |
\& CRYPTO_secure_clear_free OSSL_FUNC_CRYPTO_SECURE_CLEAR_FREE |
| 236 |
\& CRYPTO_secure_allocated OSSL_FUNC_CRYPTO_SECURE_ALLOCATED |
| 237 |
\& BIO_new_file OSSL_FUNC_BIO_NEW_FILE |
| 238 |
\& BIO_new_mem_buf OSSL_FUNC_BIO_NEW_MEMBUF |
| 239 |
\& BIO_read_ex OSSL_FUNC_BIO_READ_EX |
| 240 |
\& BIO_write_ex OSSL_FUNC_BIO_WRITE_EX |
| 241 |
\& BIO_up_ref OSSL_FUNC_BIO_UP_REF |
| 242 |
\& BIO_free OSSL_FUNC_BIO_FREE |
| 243 |
\& BIO_vprintf OSSL_FUNC_BIO_VPRINTF |
| 244 |
\& BIO_vsnprintf OSSL_FUNC_BIO_VSNPRINTF |
| 245 |
\& BIO_puts OSSL_FUNC_BIO_PUTS |
| 246 |
\& BIO_gets OSSL_FUNC_BIO_GETS |
| 247 |
\& BIO_ctrl OSSL_FUNC_BIO_CTRL |
| 248 |
\& OPENSSL_cleanse OSSL_FUNC_OPENSSL_CLEANSE |
| 249 |
\& OSSL_SELF_TEST_set_callback OSSL_FUNC_SELF_TEST_CB |
| 250 |
\& ossl_rand_get_entropy OSSL_FUNC_GET_ENTROPY |
| 251 |
\& ossl_rand_get_user_entropy OSSL_FUNC_GET_USER_ENTROPY |
| 252 |
\& ossl_rand_cleanup_entropy OSSL_FUNC_CLEANUP_ENTROPY |
| 253 |
\& ossl_rand_cleanup_user_entropy OSSL_FUNC_CLEANUP_USER_ENTROPY |
| 254 |
\& ossl_rand_get_nonce OSSL_FUNC_GET_NONCE |
| 255 |
\& ossl_rand_get_user_nonce OSSL_FUNC_GET_USER_NONCE |
| 256 |
\& ossl_rand_cleanup_nonce OSSL_FUNC_CLEANUP_NONCE |
| 257 |
\& ossl_rand_cleanup_user_nonce OSSL_FUNC_CLEANUP_USER_NONCE |
| 258 |
\& provider_register_child_cb OSSL_FUNC_PROVIDER_REGISTER_CHILD_CB |
| 259 |
\& provider_deregister_child_cb OSSL_FUNC_PROVIDER_DEREGISTER_CHILD_CB |
| 260 |
\& provider_name OSSL_FUNC_PROVIDER_NAME |
| 261 |
\& provider_get0_provider_ctx OSSL_FUNC_PROVIDER_GET0_PROVIDER_CTX |
| 262 |
\& provider_get0_dispatch OSSL_FUNC_PROVIDER_GET0_DISPATCH |
| 263 |
\& provider_up_ref OSSL_FUNC_PROVIDER_UP_REF |
| 264 |
\& provider_free OSSL_FUNC_PROVIDER_FREE |
| 265 |
.Ve |
| 266 |
.PP |
| 267 |
For \fI*out\fR (the \fBOSSL_DISPATCH\fR\|(3) array passed from the provider to |
| 268 |
\&\fIlibcrypto\fR): |
| 269 |
.PP |
| 270 |
.Vb 8 |
| 271 |
\& provider_teardown OSSL_FUNC_PROVIDER_TEARDOWN |
| 272 |
\& provider_gettable_params OSSL_FUNC_PROVIDER_GETTABLE_PARAMS |
| 273 |
\& provider_get_params OSSL_FUNC_PROVIDER_GET_PARAMS |
| 274 |
\& provider_query_operation OSSL_FUNC_PROVIDER_QUERY_OPERATION |
| 275 |
\& provider_unquery_operation OSSL_FUNC_PROVIDER_UNQUERY_OPERATION |
| 276 |
\& provider_get_reason_strings OSSL_FUNC_PROVIDER_GET_REASON_STRINGS |
| 277 |
\& provider_get_capabilities OSSL_FUNC_PROVIDER_GET_CAPABILITIES |
| 278 |
\& provider_self_test OSSL_FUNC_PROVIDER_SELF_TEST |
| 279 |
.Ve |
| 280 |
.SS "Core functions" |
| 281 |
.IX Subsection "Core functions" |
| 282 |
\&\fBcore_gettable_params()\fR returns a constant array of descriptor |
| 283 |
\&\fBOSSL_PARAM\fR\|(3), for parameters that \fBcore_get_params()\fR can handle. |
| 284 |
.PP |
| 285 |
\&\fBcore_get_params()\fR retrieves parameters from the core for the given \fIhandle\fR. |
| 286 |
See "Core parameters" below for a description of currently known |
| 287 |
parameters. |
| 288 |
.PP |
| 289 |
The \fBcore_thread_start()\fR function informs the core that the provider has stated |
| 290 |
an interest in the current thread. The core will inform the provider when the |
| 291 |
thread eventually stops. It must be passed the \fIhandle\fR for this provider, as |
| 292 |
well as a callback \fIhandfn\fR which will be called when the thread stops. The |
| 293 |
callback will subsequently be called, with the supplied argument \fIarg\fR, from |
| 294 |
the thread that is stopping and gets passed the provider context as an |
| 295 |
argument. This may be useful to perform thread specific clean up such as |
| 296 |
freeing thread local variables. |
| 297 |
.PP |
| 298 |
\&\fBcore_get_libctx()\fR retrieves the core context in which the library |
| 299 |
object for the current provider is stored, accessible through the \fIhandle\fR. |
| 300 |
This function is useful only for built-in providers such as the default |
| 301 |
provider. Never cast this to OSSL_LIB_CTX in a provider that is not |
| 302 |
built-in as the OSSL_LIB_CTX of the library loading the provider might be |
| 303 |
a completely different structure than the OSSL_LIB_CTX of the library the |
| 304 |
provider is linked to. Use \fBOSSL_LIB_CTX_new_child\fR\|(3) instead to obtain |
| 305 |
a proper library context that is linked to the application library context. |
| 306 |
.PP |
| 307 |
\&\fBcore_new_error()\fR, \fBcore_set_error_debug()\fR and \fBcore_vset_error()\fR are |
| 308 |
building blocks for reporting an error back to the core, with |
| 309 |
reference to the \fIhandle\fR. |
| 310 |
.IP \fBcore_new_error()\fR 4 |
| 311 |
.IX Item "core_new_error()" |
| 312 |
allocates a new thread specific error record. |
| 313 |
.Sp |
| 314 |
This corresponds to the OpenSSL function \fBERR_new\fR\|(3). |
| 315 |
.IP \fBcore_set_error_debug()\fR 4 |
| 316 |
.IX Item "core_set_error_debug()" |
| 317 |
sets debugging information in the current thread specific error |
| 318 |
record. |
| 319 |
The debugging information includes the name of the file \fIfile\fR, the |
| 320 |
line \fIline\fR and the function name \fIfunc\fR where the error occurred. |
| 321 |
.Sp |
| 322 |
This corresponds to the OpenSSL function \fBERR_set_debug\fR\|(3). |
| 323 |
.IP \fBcore_vset_error()\fR 4 |
| 324 |
.IX Item "core_vset_error()" |
| 325 |
sets the \fIreason\fR for the error, along with any addition data. |
| 326 |
The \fIreason\fR is a number defined by the provider and used to index |
| 327 |
the reason strings table that's returned by |
| 328 |
\&\fBprovider_get_reason_strings()\fR. |
| 329 |
The additional data is given as a format string \fIfmt\fR and a set of |
| 330 |
arguments \fIargs\fR, which are treated in the same manner as with |
| 331 |
\&\fBBIO_vsnprintf()\fR. |
| 332 |
\&\fIfile\fR and \fIline\fR may also be passed to indicate exactly where the |
| 333 |
error occurred or was reported. |
| 334 |
.Sp |
| 335 |
This corresponds to the OpenSSL function \fBERR_vset_error\fR\|(3). |
| 336 |
.IP \fBcore_set_error_mark()\fR 4 |
| 337 |
.IX Item "core_set_error_mark()" |
| 338 |
sets a mark on the current topmost error record if there is one. |
| 339 |
.Sp |
| 340 |
This corresponds to the OpenSSL function \fBERR_set_mark\fR\|(3). |
| 341 |
.IP \fBcore_clear_last_error_mark()\fR 4 |
| 342 |
.IX Item "core_clear_last_error_mark()" |
| 343 |
removes the last mark added if there is one. |
| 344 |
.Sp |
| 345 |
This corresponds to the OpenSSL function \fBERR_clear_last_mark\fR\|(3). |
| 346 |
.IP \fBcore_pop_error_to_mark()\fR 4 |
| 347 |
.IX Item "core_pop_error_to_mark()" |
| 348 |
pops the top of the error stack until a mark is found. The mark is then removed. |
| 349 |
If there is no mark, the whole stack is removed. |
| 350 |
.Sp |
| 351 |
This corresponds to the OpenSSL function \fBERR_pop_to_mark\fR\|(3). |
| 352 |
.IP \fBcore_count_to_mark()\fR 4 |
| 353 |
.IX Item "core_count_to_mark()" |
| 354 |
returns the number of entries on the error stack above the most recently |
| 355 |
marked entry, not including that entry. If there is no mark in the error stack, |
| 356 |
the number of entries in the error stack is returned. |
| 357 |
.Sp |
| 358 |
This corresponds to the OpenSSL function \fBERR_count_to_mark\fR\|(3). |
| 359 |
.PP |
| 360 |
The \fBcore_obj_create()\fR function registers a new OID and associated short name |
| 361 |
\&\fIsn\fR and long name \fIln\fR for the given \fIhandle\fR. It is similar to the OpenSSL |
| 362 |
function \fBOBJ_create\fR\|(3) except that it returns 1 on success or 0 on failure. |
| 363 |
It will treat as success the case where the OID already exists (even if the |
| 364 |
short name \fIsn\fR or long name \fIln\fR provided as arguments differ from those |
| 365 |
associated with the existing OID, in which case the new names are not |
| 366 |
associated). |
| 367 |
.PP |
| 368 |
The \fBcore_obj_add_sigid()\fR function registers a new composite signature algorithm |
| 369 |
(\fIsign_name\fR) consisting of an underlying signature algorithm (\fIpkey_name\fR) |
| 370 |
and digest algorithm (\fIdigest_name\fR) for the given \fIhandle\fR. It assumes that |
| 371 |
the OIDs for the composite signature algorithm as well as for the underlying |
| 372 |
signature and digest algorithms are either already known to OpenSSL or have been |
| 373 |
registered via a call to \fBcore_obj_create()\fR. It corresponds to the OpenSSL |
| 374 |
function \fBOBJ_add_sigid\fR\|(3), except that the objects are identified by name |
| 375 |
rather than a numeric NID. Any name (OID, short name or long name) can be used |
| 376 |
to identify the object. It will treat as success the case where the composite |
| 377 |
signature algorithm already exists (even if registered against a different |
| 378 |
underlying signature or digest algorithm). For \fIdigest_name\fR, NULL or an |
| 379 |
empty string is permissible for signature algorithms that do not need a digest |
| 380 |
to operate correctly. The function returns 1 on success or 0 on failure. |
| 381 |
.PP |
| 382 |
\&\fBCRYPTO_malloc()\fR, \fBCRYPTO_zalloc()\fR, \fBCRYPTO_free()\fR, \fBCRYPTO_clear_free()\fR, |
| 383 |
\&\fBCRYPTO_realloc()\fR, \fBCRYPTO_clear_realloc()\fR, \fBCRYPTO_secure_malloc()\fR, |
| 384 |
\&\fBCRYPTO_secure_zalloc()\fR, \fBCRYPTO_secure_free()\fR, |
| 385 |
\&\fBCRYPTO_secure_clear_free()\fR, \fBCRYPTO_secure_allocated()\fR, |
| 386 |
\&\fBBIO_new_file()\fR, \fBBIO_new_mem_buf()\fR, \fBBIO_read_ex()\fR, \fBBIO_write_ex()\fR, \fBBIO_up_ref()\fR, |
| 387 |
\&\fBBIO_free()\fR, \fBBIO_vprintf()\fR, \fBBIO_vsnprintf()\fR, \fBBIO_gets()\fR, \fBBIO_puts()\fR, |
| 388 |
\&\fBBIO_ctrl()\fR, \fBOPENSSL_cleanse()\fR and |
| 389 |
\&\fBOPENSSL_hexstr2buf()\fR correspond exactly to the public functions with |
| 390 |
the same name. As a matter of fact, the pointers in the \fBOSSL_DISPATCH\fR\|(3) |
| 391 |
array are typically direct pointers to those public functions. Note that the BIO |
| 392 |
functions take an \fBOSSL_CORE_BIO\fR type rather than the standard \fBBIO\fR |
| 393 |
type. This is to ensure that a provider does not mix BIOs from the core |
| 394 |
with BIOs used on the provider side (the two are not compatible). |
| 395 |
\&\fBOSSL_SELF_TEST_set_callback()\fR is used to set an optional callback that can be |
| 396 |
passed into a provider. This may be ignored by a provider. |
| 397 |
.PP |
| 398 |
\&\fBget_entropy()\fR retrieves seeding material from the operating system. |
| 399 |
The seeding material will have at least \fIentropy\fR bytes of randomness and the |
| 400 |
output will have at least \fImin_len\fR and at most \fImax_len\fR bytes. |
| 401 |
The buffer address is stored in \fI*pout\fR and the buffer length is |
| 402 |
returned to the caller. On error, zero is returned. |
| 403 |
.PP |
| 404 |
\&\fBget_user_entropy()\fR is the same as \fBget_entropy()\fR except that it will |
| 405 |
attempt to gather seed material via the seed source specified by a call to |
| 406 |
\&\fBRAND_set_seed_source_type\fR\|(3) or via "Random Configuration" in \fBconfig\fR\|(5). |
| 407 |
.PP |
| 408 |
\&\fBcleanup_entropy()\fR is used to clean up and free the buffer returned by |
| 409 |
\&\fBget_entropy()\fR. The entropy pointer returned by \fBget_entropy()\fR |
| 410 |
is passed in \fBbuf\fR and its length in \fBlen\fR. |
| 411 |
.PP |
| 412 |
\&\fBcleanup_user_entropy()\fR is used to clean up and free the buffer returned by |
| 413 |
\&\fBget_user_entropy()\fR. The entropy pointer returned by \fBget_user_entropy()\fR |
| 414 |
is passed in \fBbuf\fR and its length in \fBlen\fR. |
| 415 |
.PP |
| 416 |
\&\fBget_nonce()\fR retrieves a nonce using the passed \fIsalt\fR parameter |
| 417 |
of length \fIsalt_len\fR and operating system specific information. |
| 418 |
The \fIsalt\fR should contain uniquely identifying information and this is |
| 419 |
included, in an unspecified manner, as part of the output. |
| 420 |
The output is stored in a buffer which contains at least \fImin_len\fR and at |
| 421 |
most \fImax_len\fR bytes. The buffer address is stored in \fI*pout\fR and the |
| 422 |
buffer length returned to the caller. On error, zero is returned. |
| 423 |
.PP |
| 424 |
\&\fBget_user_nonce()\fR is the same as \fBget_nonce()\fR except that it will attempt |
| 425 |
to gather seed material via the seed source specified by a call to |
| 426 |
\&\fBRAND_set_seed_source_type\fR\|(3) or via "Random Configuration" in \fBconfig\fR\|(5). |
| 427 |
.PP |
| 428 |
\&\fBcleanup_nonce()\fR is used to clean up and free the buffer returned by |
| 429 |
\&\fBget_nonce()\fR. The nonce pointer returned by \fBget_nonce()\fR |
| 430 |
is passed in \fBbuf\fR and its length in \fBlen\fR. |
| 431 |
.PP |
| 432 |
\&\fBcleanup_user_nonce()\fR is used to clean up and free the buffer returned by |
| 433 |
\&\fBget_user_nonce()\fR. The nonce pointer returned by \fBget_user_nonce()\fR |
| 434 |
is passed in \fBbuf\fR and its length in \fBlen\fR. |
| 435 |
.PP |
| 436 |
\&\fBprovider_register_child_cb()\fR registers callbacks for being informed about the |
| 437 |
loading and unloading of providers in the application's library context. |
| 438 |
\&\fIhandle\fR is this provider's handle and \fIcbdata\fR is this provider's data |
| 439 |
that will be passed back to the callbacks. It returns 1 on success or 0 |
| 440 |
otherwise. These callbacks may be called while holding locks in libcrypto. In |
| 441 |
order to avoid deadlocks the callback implementation must not be long running |
| 442 |
and must not call other OpenSSL API functions or upcalls. |
| 443 |
.PP |
| 444 |
\&\fIcreate_cb\fR is a callback that will be called when a new provider is loaded |
| 445 |
into the application's library context. It is also called for any providers that |
| 446 |
are already loaded at the point that this callback is registered. The callback |
| 447 |
is passed the handle being used for the new provider being loadded and this |
| 448 |
provider's data in \fIcbdata\fR. It should return 1 on success or 0 on failure. |
| 449 |
.PP |
| 450 |
\&\fIremove_cb\fR is a callback that will be called when a new provider is unloaded |
| 451 |
from the application's library context. It is passed the handle being used for |
| 452 |
the provider being unloaded and this provider's data in \fIcbdata\fR. It should |
| 453 |
return 1 on success or 0 on failure. |
| 454 |
.PP |
| 455 |
\&\fIglobal_props_cb\fR is a callback that will be called when the global properties |
| 456 |
from the parent library context are changed. It should return 1 on success |
| 457 |
or 0 on failure. |
| 458 |
.PP |
| 459 |
\&\fBprovider_deregister_child_cb()\fR unregisters callbacks previously registered via |
| 460 |
\&\fBprovider_register_child_cb()\fR. If \fBprovider_register_child_cb()\fR has been called |
| 461 |
then \fBprovider_deregister_child_cb()\fR should be called at or before the point that |
| 462 |
this provider's teardown function is called. |
| 463 |
.PP |
| 464 |
\&\fBprovider_name()\fR returns a string giving the name of the provider identified by |
| 465 |
\&\fIhandle\fR. |
| 466 |
.PP |
| 467 |
\&\fBprovider_get0_provider_ctx()\fR returns the provider context that is associated |
| 468 |
with the provider identified by \fIprov\fR. |
| 469 |
.PP |
| 470 |
\&\fBprovider_get0_dispatch()\fR gets the dispatch table registered by the provider |
| 471 |
identified by \fIprov\fR when it initialised. |
| 472 |
.PP |
| 473 |
\&\fBprovider_up_ref()\fR increments the reference count on the provider \fIprov\fR. If |
| 474 |
\&\fIactivate\fR is nonzero then the provider is also loaded if it is not already |
| 475 |
loaded. It returns 1 on success or 0 on failure. |
| 476 |
.PP |
| 477 |
\&\fBprovider_free()\fR decrements the reference count on the provider \fIprov\fR. If |
| 478 |
\&\fIdeactivate\fR is nonzero then the provider is also unloaded if it is not |
| 479 |
already loaded. It returns 1 on success or 0 on failure. |
| 480 |
.SS "Provider functions" |
| 481 |
.IX Subsection "Provider functions" |
| 482 |
\&\fBprovider_teardown()\fR is called when a provider is shut down and removed |
| 483 |
from the core's provider store. |
| 484 |
It must free the passed \fIprovctx\fR. |
| 485 |
.PP |
| 486 |
\&\fBprovider_gettable_params()\fR should return a constant array of |
| 487 |
descriptor \fBOSSL_PARAM\fR\|(3), for parameters that \fBprovider_get_params()\fR |
| 488 |
can handle. |
| 489 |
.PP |
| 490 |
\&\fBprovider_get_params()\fR should process the \fBOSSL_PARAM\fR\|(3) array |
| 491 |
\&\fIparams\fR, setting the values of the parameters it understands. |
| 492 |
.PP |
| 493 |
\&\fBprovider_query_operation()\fR should return a constant \fBOSSL_ALGORITHM\fR\|(3) |
| 494 |
that corresponds to the given \fIoperation_id\fR. |
| 495 |
It should indicate if the core may store a reference to this array by |
| 496 |
setting \fI*no_store\fR to 0 (core may store a reference) or 1 (core may |
| 497 |
not store a reference). |
| 498 |
.PP |
| 499 |
\&\fBprovider_unquery_operation()\fR informs the provider that the result of a |
| 500 |
\&\fBprovider_query_operation()\fR is no longer directly required and that the function |
| 501 |
pointers have been copied. The \fIoperation_id\fR should match that passed to |
| 502 |
\&\fBprovider_query_operation()\fR and \fIalgs\fR should be its return value. |
| 503 |
.PP |
| 504 |
\&\fBprovider_get_reason_strings()\fR should return a constant \fBOSSL_ITEM\fR\|(3) |
| 505 |
array that provides reason strings for reason codes the provider may |
| 506 |
use when reporting errors using \fBcore_put_error()\fR. |
| 507 |
.PP |
| 508 |
The \fBprovider_get_capabilities()\fR function should call the callback \fIcb\fR passing |
| 509 |
it a set of \fBOSSL_PARAM\fR\|(3)s and the caller supplied argument \fIarg\fR. The |
| 510 |
\&\fBOSSL_PARAM\fR\|(3)s should provide details about the capability with the name given |
| 511 |
in the \fIcapability\fR argument relevant for the provider context \fIprovctx\fR. If a |
| 512 |
provider supports multiple capabilities with the given name then it may call the |
| 513 |
callback multiple times (one for each capability). Capabilities can be useful for |
| 514 |
describing the services that a provider can offer. For further details see the |
| 515 |
"CAPABILITIES" section below. It should return 1 on success or 0 on error. |
| 516 |
.PP |
| 517 |
The \fBprovider_self_test()\fR function should perform known answer tests on a subset |
| 518 |
of the algorithms that it uses, and may also verify the integrity of the |
| 519 |
provider module. It should return 1 on success or 0 on error. It will return 1 |
| 520 |
if this function is not used. |
| 521 |
.PP |
| 522 |
None of these functions are mandatory, but a provider is fairly |
| 523 |
useless without at least \fBprovider_query_operation()\fR, and |
| 524 |
\&\fBprovider_gettable_params()\fR is fairly useless if not accompanied by |
| 525 |
\&\fBprovider_get_params()\fR. |
| 526 |
.SS "Provider parameters" |
| 527 |
.IX Subsection "Provider parameters" |
| 528 |
\&\fBprovider_get_params()\fR can return the following provider parameters to the core: |
| 529 |
.IP """name"" (\fBOSSL_PROV_PARAM_NAME\fR) <UTF8 ptr>" 4 |
| 530 |
.IX Item """name"" (OSSL_PROV_PARAM_NAME) <UTF8 ptr>" |
| 531 |
This points to a string that should give a unique name for the provider. |
| 532 |
.IP """version"" (\fBOSSL_PROV_PARAM_VERSION\fR) <UTF8 ptr>" 4 |
| 533 |
.IX Item """version"" (OSSL_PROV_PARAM_VERSION) <UTF8 ptr>" |
| 534 |
This points to a string that is a version number associated with this provider. |
| 535 |
OpenSSL in-built providers use OPENSSL_VERSION_STR, but this may be different |
| 536 |
for any third party provider. This string is for informational purposes only. |
| 537 |
.IP """buildinfo"" (\fBOSSL_PROV_PARAM_BUILDINFO\fR) <UTF8 ptr>" 4 |
| 538 |
.IX Item """buildinfo"" (OSSL_PROV_PARAM_BUILDINFO) <UTF8 ptr>" |
| 539 |
This points to a string that is a build information associated with this provider. |
| 540 |
OpenSSL in-built providers use OPENSSL_FULL_VERSION_STR, but this may be |
| 541 |
different for any third party provider. |
| 542 |
.IP """status"" (\fBOSSL_PROV_PARAM_STATUS\fR) <signed integer>" 4 |
| 543 |
.IX Item """status"" (OSSL_PROV_PARAM_STATUS) <signed integer>" |
| 544 |
This returns 0 if the provider has entered an error state, otherwise it returns |
| 545 |
1. |
| 546 |
.PP |
| 547 |
\&\fBprovider_gettable_params()\fR should return the above parameters. |
| 548 |
.SS "Core parameters" |
| 549 |
.IX Subsection "Core parameters" |
| 550 |
\&\fBcore_get_params()\fR can retrieve the following core parameters for each provider: |
| 551 |
.IP """openssl-version"" (\fBOSSL_PROV_PARAM_CORE_VERSION\fR) <UTF8 string ptr>" 4 |
| 552 |
.IX Item """openssl-version"" (OSSL_PROV_PARAM_CORE_VERSION) <UTF8 string ptr>" |
| 553 |
This points to the OpenSSL libraries' full version string, i.e. the string |
| 554 |
expanded from the macro \fBOPENSSL_VERSION_STR\fR. |
| 555 |
.IP """provider-name"" (\fBOSSL_PROV_PARAM_CORE_PROV_NAME\fR) <UTF8 string ptr>" 4 |
| 556 |
.IX Item """provider-name"" (OSSL_PROV_PARAM_CORE_PROV_NAME) <UTF8 string ptr>" |
| 557 |
This points to the OpenSSL libraries' idea of what the calling provider is named. |
| 558 |
.IP """module-filename"" (\fBOSSL_PROV_PARAM_CORE_MODULE_FILENAME\fR) <UTF8 string ptr>" 4 |
| 559 |
.IX Item """module-filename"" (OSSL_PROV_PARAM_CORE_MODULE_FILENAME) <UTF8 string ptr>" |
| 560 |
This points to a string containing the full filename of the providers |
| 561 |
module file. |
| 562 |
.PP |
| 563 |
Additionally, provider specific configuration parameters from the |
| 564 |
config file are available, in dotted name form. |
| 565 |
The dotted name form is a concatenation of section names and final |
| 566 |
config command name separated by periods. |
| 567 |
.PP |
| 568 |
For example, let's say we have the following config example: |
| 569 |
.PP |
| 570 |
.Vb 2 |
| 571 |
\& config_diagnostics = 1 |
| 572 |
\& openssl_conf = openssl_init |
| 573 |
\& |
| 574 |
\& [openssl_init] |
| 575 |
\& providers = providers_sect |
| 576 |
\& |
| 577 |
\& [providers_sect] |
| 578 |
\& foo = foo_sect |
| 579 |
\& |
| 580 |
\& [foo_sect] |
| 581 |
\& activate = 1 |
| 582 |
\& data1 = 2 |
| 583 |
\& data2 = str |
| 584 |
\& more = foo_more |
| 585 |
\& |
| 586 |
\& [foo_more] |
| 587 |
\& data3 = foo,bar |
| 588 |
.Ve |
| 589 |
.PP |
| 590 |
The provider will have these additional parameters available: |
| 591 |
.IP """activate""" 4 |
| 592 |
.IX Item """activate""" |
| 593 |
pointing at the string "1" |
| 594 |
.IP """data1""" 4 |
| 595 |
.IX Item """data1""" |
| 596 |
pointing at the string "2" |
| 597 |
.IP """data2""" 4 |
| 598 |
.IX Item """data2""" |
| 599 |
pointing at the string "str" |
| 600 |
.IP """more.data3""" 4 |
| 601 |
.IX Item """more.data3""" |
| 602 |
pointing at the string "foo,bar" |
| 603 |
.PP |
| 604 |
For more information on handling parameters, see \fBOSSL_PARAM\fR\|(3) as |
| 605 |
\&\fBOSSL_PARAM_int\fR\|(3). |
| 606 |
.SH CAPABILITIES |
| 607 |
.IX Header "CAPABILITIES" |
| 608 |
Capabilities describe some of the services that a provider can offer. |
| 609 |
Applications can query the capabilities to discover those services. |
| 610 |
.PP |
| 611 |
\fI"TLS-GROUP" Capability\fR |
| 612 |
.IX Subsection """TLS-GROUP"" Capability" |
| 613 |
.PP |
| 614 |
The "TLS-GROUP" capability can be queried by libssl to discover the list of |
| 615 |
TLS groups that a provider can support. Each group supported can be used for |
| 616 |
\&\fIkey exchange\fR (KEX) or \fIkey encapsulation method\fR (KEM) during a TLS |
| 617 |
handshake. |
| 618 |
TLS clients can advertise the list of TLS groups they support in the |
| 619 |
supported_groups extension, and TLS servers can select a group from the offered |
| 620 |
list that they also support. In this way a provider can add to the list of |
| 621 |
groups that libssl already supports with additional ones. |
| 622 |
.PP |
| 623 |
Each TLS group that a provider supports should be described via the callback |
| 624 |
passed in through the provider_get_capabilities function. Each group should have |
| 625 |
the following details supplied (all are mandatory, except |
| 626 |
\&\fBOSSL_CAPABILITY_TLS_GROUP_IS_KEM\fR): |
| 627 |
.IP """tls-group-name"" (\fBOSSL_CAPABILITY_TLS_GROUP_NAME\fR) <UTF8 string>" 4 |
| 628 |
.IX Item """tls-group-name"" (OSSL_CAPABILITY_TLS_GROUP_NAME) <UTF8 string>" |
| 629 |
The name of the group as given in the IANA TLS Supported Groups registry |
| 630 |
<https://www.iana.org/assignments/tls\-parameters/tls\-parameters.xhtml#tls\-parameters\-8>. |
| 631 |
.IP """tls-group-name-internal"" (\fBOSSL_CAPABILITY_TLS_GROUP_NAME_INTERNAL\fR) <UTF8 string>" 4 |
| 632 |
.IX Item """tls-group-name-internal"" (OSSL_CAPABILITY_TLS_GROUP_NAME_INTERNAL) <UTF8 string>" |
| 633 |
The name of the group as known by the provider. This could be the same as the |
| 634 |
"tls-group-name", but does not have to be. |
| 635 |
.IP """tls-group-id"" (\fBOSSL_CAPABILITY_TLS_GROUP_ID\fR) <unsigned integer>" 4 |
| 636 |
.IX Item """tls-group-id"" (OSSL_CAPABILITY_TLS_GROUP_ID) <unsigned integer>" |
| 637 |
The TLS group id value as given in the IANA TLS Supported Groups registry. |
| 638 |
.Sp |
| 639 |
It is possible to register the same group id from within different |
| 640 |
providers. Users should note that if no property query is specified, or |
| 641 |
more than one implementation matches the property query then it is |
| 642 |
unspecified which implementation for a particular group id will be used. |
| 643 |
.IP """tls-group-alg"" (\fBOSSL_CAPABILITY_TLS_GROUP_ALG\fR) <UTF8 string>" 4 |
| 644 |
.IX Item """tls-group-alg"" (OSSL_CAPABILITY_TLS_GROUP_ALG) <UTF8 string>" |
| 645 |
The name of a Key Management algorithm that the provider offers and that should |
| 646 |
be used with this group. Keys created should be able to support \fIkey exchange\fR |
| 647 |
or \fIkey encapsulation method\fR (KEM), as implied by the optional |
| 648 |
\&\fBOSSL_CAPABILITY_TLS_GROUP_IS_KEM\fR flag. |
| 649 |
The algorithm must support key and parameter generation as well as the |
| 650 |
key/parameter generation parameter, \fBOSSL_PKEY_PARAM_GROUP_NAME\fR. The group |
| 651 |
name given via "tls-group-name-internal" above will be passed via |
| 652 |
\&\fBOSSL_PKEY_PARAM_GROUP_NAME\fR when libssl wishes to generate keys/parameters. |
| 653 |
.IP """tls-group-sec-bits"" (\fBOSSL_CAPABILITY_TLS_GROUP_SECURITY_BITS\fR) <unsigned integer>" 4 |
| 654 |
.IX Item """tls-group-sec-bits"" (OSSL_CAPABILITY_TLS_GROUP_SECURITY_BITS) <unsigned integer>" |
| 655 |
The number of bits of security offered by keys in this group. The number of bits |
| 656 |
should be comparable with the ones given in table 2 and 3 of the NIST SP800\-57 |
| 657 |
document. |
| 658 |
.IP """tls-group-is-kem"" (\fBOSSL_CAPABILITY_TLS_GROUP_IS_KEM\fR) <unsigned integer>" 4 |
| 659 |
.IX Item """tls-group-is-kem"" (OSSL_CAPABILITY_TLS_GROUP_IS_KEM) <unsigned integer>" |
| 660 |
Boolean flag to describe if the group should be used in \fIkey exchange\fR (KEX) |
| 661 |
mode (0, default) or in \fIkey encapsulation method\fR (KEM) mode (1). |
| 662 |
.Sp |
| 663 |
This parameter is optional: if not specified, KEX mode is assumed as the default |
| 664 |
mode for the group. |
| 665 |
.Sp |
| 666 |
In KEX mode, in a typical Diffie-Hellman fashion, both sides execute \fIkeygen\fR |
| 667 |
then \fIderive\fR against the peer public key. To operate in KEX mode, the group |
| 668 |
implementation must support the provider functions as described in |
| 669 |
\&\fBprovider\-keyexch\fR\|(7). |
| 670 |
.Sp |
| 671 |
In KEM mode, the client executes \fIkeygen\fR and sends its public key, the server |
| 672 |
executes \fIencapsulate\fR using the client's public key and sends back the |
| 673 |
resulting \fIciphertext\fR, finally the client executes \fIdecapsulate\fR to retrieve |
| 674 |
the same \fIshared secret\fR generated by the server's \fIencapsulate\fR. To operate |
| 675 |
in KEM mode, the group implementation must support the provider functions as |
| 676 |
described in \fBprovider\-kem\fR\|(7). |
| 677 |
.Sp |
| 678 |
Both in KEX and KEM mode, the resulting \fIshared secret\fR is then used according |
| 679 |
to the protocol specification. |
| 680 |
.IP """tls-min-tls"" (\fBOSSL_CAPABILITY_TLS_GROUP_MIN_TLS\fR) <integer>" 4 |
| 681 |
.IX Item """tls-min-tls"" (OSSL_CAPABILITY_TLS_GROUP_MIN_TLS) <integer>" |
| 682 |
.PD 0 |
| 683 |
.IP """tls-max-tls"" (\fBOSSL_CAPABILITY_TLS_GROUP_MAX_TLS\fR) <integer>" 4 |
| 684 |
.IX Item """tls-max-tls"" (OSSL_CAPABILITY_TLS_GROUP_MAX_TLS) <integer>" |
| 685 |
.IP """tls-min-dtls"" (\fBOSSL_CAPABILITY_TLS_GROUP_MIN_DTLS\fR) <integer>" 4 |
| 686 |
.IX Item """tls-min-dtls"" (OSSL_CAPABILITY_TLS_GROUP_MIN_DTLS) <integer>" |
| 687 |
.IP """tls-max-dtls"" (\fBOSSL_CAPABILITY_TLS_GROUP_MAX_DTLS\fR) <integer>" 4 |
| 688 |
.IX Item """tls-max-dtls"" (OSSL_CAPABILITY_TLS_GROUP_MAX_DTLS) <integer>" |
| 689 |
.PD |
| 690 |
These parameters can be used to describe the minimum and maximum TLS and DTLS |
| 691 |
versions supported by the group. The values equate to the on-the-wire encoding |
| 692 |
of the various TLS versions. For example TLSv1.3 is 0x0304 (772 decimal), and |
| 693 |
TLSv1.2 is 0x0303 (771 decimal). A 0 indicates that there is no defined minimum |
| 694 |
or maximum. A \-1 indicates that the group should not be used in that protocol. |
| 695 |
.PP |
| 696 |
\fI"TLS-SIGALG" Capability\fR |
| 697 |
.IX Subsection """TLS-SIGALG"" Capability" |
| 698 |
.PP |
| 699 |
The "TLS-SIGALG" capability can be queried by libssl to discover the list of |
| 700 |
TLS signature algorithms that a provider can support. Each signature supported |
| 701 |
can be used for client\- or server-authentication in addition to the built-in |
| 702 |
signature algorithms. |
| 703 |
TLS1.3 clients can advertise the list of TLS signature algorithms they support |
| 704 |
in the signature_algorithms extension, and TLS servers can select an algorithm |
| 705 |
from the offered list that they also support. In this way a provider can add |
| 706 |
to the list of signature algorithms that libssl already supports with |
| 707 |
additional ones. |
| 708 |
.PP |
| 709 |
Each TLS signature algorithm that a provider supports should be described via |
| 710 |
the callback passed in through the provider_get_capabilities function. Each |
| 711 |
algorithm can have the following details supplied: |
| 712 |
.IP """iana-name"" (\fBOSSL_CAPABILITY_TLS_SIGALG_IANA_NAME\fR) <UTF8 string>" 4 |
| 713 |
.IX Item """iana-name"" (OSSL_CAPABILITY_TLS_SIGALG_IANA_NAME) <UTF8 string>" |
| 714 |
The name of the signature algorithm as given in the IANA TLS Signature Scheme |
| 715 |
registry as "Description": |
| 716 |
<https://www.iana.org/assignments/tls\-parameters/tls\-parameters.xhtml#tls\-signaturescheme>. |
| 717 |
This value must be supplied. |
| 718 |
.IP """iana-code-point"" (\fBOSSL_CAPABILITY_TLS_SIGALG_CODE_POINT\fR) <unsigned integer>" 4 |
| 719 |
.IX Item """iana-code-point"" (OSSL_CAPABILITY_TLS_SIGALG_CODE_POINT) <unsigned integer>" |
| 720 |
The TLS algorithm ID value as given in the IANA TLS SignatureScheme registry. |
| 721 |
This value must be supplied. |
| 722 |
.Sp |
| 723 |
It is possible to register the same code point from within different |
| 724 |
providers. Users should note that if no property query is specified, or |
| 725 |
more than one implementation matches the property query then it is |
| 726 |
unspecified which implementation for a particular code point will be used. |
| 727 |
.IP """sigalg-name"" (\fBOSSL_CAPABILITY_TLS_SIGALG_NAME\fR) <UTF8 string>" 4 |
| 728 |
.IX Item """sigalg-name"" (OSSL_CAPABILITY_TLS_SIGALG_NAME) <UTF8 string>" |
| 729 |
A name for the full (possibly composite hash-and-signature) signature |
| 730 |
algorithm. |
| 731 |
The provider may, but is not obligated to, provide a signature implementation |
| 732 |
with this name; if it doesn't, this is assumed to be a composite of a pure |
| 733 |
signature algorithm and a hash algorithm, which must be given with the |
| 734 |
parameters "sig-name" and "hash-name". |
| 735 |
This value must be supplied. |
| 736 |
.IP """sigalg-oid"" (\fBOSSL_CAPABILITY_TLS_SIGALG_OID\fR) <UTF8 string>" 4 |
| 737 |
.IX Item """sigalg-oid"" (OSSL_CAPABILITY_TLS_SIGALG_OID) <UTF8 string>" |
| 738 |
The OID of the "sigalg-name" algorithm in canonical numeric text form. If |
| 739 |
this parameter is given, \fBOBJ_create()\fR will be used to create an OBJ and |
| 740 |
a NID for this OID, using the "sigalg-name" parameter for its (short) name. |
| 741 |
Otherwise, it's assumed to already exist in the object database, possibly |
| 742 |
done by the provider with the \fBcore_obj_create()\fR upcall. |
| 743 |
This value is optional. |
| 744 |
.IP """sig-name"" (\fBOSSL_CAPABILITY_TLS_SIGALG_SIG_NAME\fR) <UTF8 string>" 4 |
| 745 |
.IX Item """sig-name"" (OSSL_CAPABILITY_TLS_SIGALG_SIG_NAME) <UTF8 string>" |
| 746 |
The name of the pure signature algorithm that is part of a composite |
| 747 |
"sigalg-name". If "sigalg-name" is implemented by the provider, this |
| 748 |
parameter is redundant and must not be given. |
| 749 |
This value is optional. |
| 750 |
.IP """sig-oid"" (\fBOSSL_CAPABILITY_TLS_SIGALG_SIG_OID\fR) <UTF8 string>" 4 |
| 751 |
.IX Item """sig-oid"" (OSSL_CAPABILITY_TLS_SIGALG_SIG_OID) <UTF8 string>" |
| 752 |
The OID of the "sig-name" algorithm in canonical numeric text form. If |
| 753 |
this parameter is given, \fBOBJ_create()\fR will be used to create an OBJ and |
| 754 |
a NID for this OID, using the "sig-name" parameter for its (short) name. |
| 755 |
Otherwise, it is assumed to already exist in the object database. This |
| 756 |
can be done by the provider using the \fBcore_obj_create()\fR upcall. |
| 757 |
This value is optional. |
| 758 |
.IP """hash-name"" (\fBOSSL_CAPABILITY_TLS_SIGALG_HASH_NAME\fR) <UTF8 string>" 4 |
| 759 |
.IX Item """hash-name"" (OSSL_CAPABILITY_TLS_SIGALG_HASH_NAME) <UTF8 string>" |
| 760 |
The name of the hash algorithm that is part of a composite "sigalg-name". |
| 761 |
If "sigalg-name" is implemented by the provider, this parameter is redundant |
| 762 |
and must not be given. |
| 763 |
This value is optional. |
| 764 |
.IP """hash-oid"" (\fBOSSL_CAPABILITY_TLS_SIGALG_HASH_OID\fR) <UTF8 string>" 4 |
| 765 |
.IX Item """hash-oid"" (OSSL_CAPABILITY_TLS_SIGALG_HASH_OID) <UTF8 string>" |
| 766 |
The OID of the "hash-name" algorithm in canonical numeric text form. If |
| 767 |
this parameter is given, \fBOBJ_create()\fR will be used to create an OBJ and |
| 768 |
a NID for this OID, using the "hash-name" parameter for its (short) name. |
| 769 |
Otherwise, it's assumed to already exist in the object database, possibly |
| 770 |
done by the provider with the \fBcore_obj_create()\fR upcall. |
| 771 |
This value is optional. |
| 772 |
.IP """key-type"" (\fBOSSL_CAPABILITY_TLS_SIGALG_KEYTYPE\fR) <UTF8 string>" 4 |
| 773 |
.IX Item """key-type"" (OSSL_CAPABILITY_TLS_SIGALG_KEYTYPE) <UTF8 string>" |
| 774 |
The key type of the public key of applicable certificates. If this parameter |
| 775 |
isn't present, it's assumed to be the same as "sig-name" if that's present, |
| 776 |
otherwise "sigalg-name". |
| 777 |
This value is optional. |
| 778 |
.IP """key-type-oid"" (\fBOSSL_CAPABILITY_TLS_SIGALG_KEYTYPE_OID\fR) <UTF8 string>" 4 |
| 779 |
.IX Item """key-type-oid"" (OSSL_CAPABILITY_TLS_SIGALG_KEYTYPE_OID) <UTF8 string>" |
| 780 |
The OID of the "key-type" in canonical numeric text form. If |
| 781 |
this parameter is given, \fBOBJ_create()\fR will be used to create an OBJ and |
| 782 |
a NID for this OID, using the "key-type" parameter for its (short) name. |
| 783 |
Otherwise, it's assumed to already exist in the object database, possibly |
| 784 |
done by the provider with the \fBcore_obj_create()\fR upcall. |
| 785 |
This value is optional. |
| 786 |
.IP """sec-bits"" (\fBOSSL_CAPABILITY_TLS_SIGALG_SECURITY_BITS\fR) <unsigned integer>" 4 |
| 787 |
.IX Item """sec-bits"" (OSSL_CAPABILITY_TLS_SIGALG_SECURITY_BITS) <unsigned integer>" |
| 788 |
The number of bits of security offered by keys of this algorithm. The number |
| 789 |
of bits should be comparable with the ones given in table 2 and 3 of the NIST |
| 790 |
SP800\-57 document. This number is used to determine the security strength of |
| 791 |
the algorithm if no digest algorithm has been registered that otherwise |
| 792 |
defines the security strength. If the signature algorithm implements its own |
| 793 |
digest internally, this value needs to be set to properly reflect the overall |
| 794 |
security strength. |
| 795 |
This value must be supplied. |
| 796 |
.IP """tls-min-tls"" (\fBOSSL_CAPABILITY_TLS_SIGALG_MIN_TLS\fR) <integer>" 4 |
| 797 |
.IX Item """tls-min-tls"" (OSSL_CAPABILITY_TLS_SIGALG_MIN_TLS) <integer>" |
| 798 |
.PD 0 |
| 799 |
.IP """tls-max-tls"" (\fBOSSL_CAPABILITY_TLS_SIGALG_MAX_TLS\fR) <integer>" 4 |
| 800 |
.IX Item """tls-max-tls"" (OSSL_CAPABILITY_TLS_SIGALG_MAX_TLS) <integer>" |
| 801 |
.IP """tls-min-dtls"" (\fBOSSL_CAPABILITY_TLS_SIGALG_MIN_DTLS\fR) <integer>" 4 |
| 802 |
.IX Item """tls-min-dtls"" (OSSL_CAPABILITY_TLS_SIGALG_MIN_DTLS) <integer>" |
| 803 |
.IP """tls-max-dtls"" (\fBOSSL_CAPABILITY_TLS_SIGALG_MAX_DTLS\fR) <integer>" 4 |
| 804 |
.IX Item """tls-max-dtls"" (OSSL_CAPABILITY_TLS_SIGALG_MAX_DTLS) <integer>" |
| 805 |
.PD |
| 806 |
These parameters can be used to describe the minimum and maximum TLS and DTLS |
| 807 |
versions supported by the signature algorithm. The values equate to the |
| 808 |
on-the-wire encoding of the various TLS versions. For example TLSv1.3 is |
| 809 |
0x0304 (772 decimal), and TLSv1.2 is 0x0303 (771 decimal). A 0 indicates that |
| 810 |
there is no defined minimum or maximum. A \-1 in either the min or max field |
| 811 |
indicates that the signature algorithm should not be used in that protocol. |
| 812 |
Presently, provider signature algorithms are used only with TLS 1.3, if |
| 813 |
that's enclosed in the specified range. |
| 814 |
.SH NOTES |
| 815 |
.IX Header "NOTES" |
| 816 |
The \fBcore_obj_create()\fR and \fBcore_obj_add_sigid()\fR functions were not thread safe |
| 817 |
in OpenSSL 3.0. |
| 818 |
.SH EXAMPLES |
| 819 |
.IX Header "EXAMPLES" |
| 820 |
This is an example of a simple provider made available as a |
| 821 |
dynamically loadable module. |
| 822 |
It implements the fictitious algorithm \f(CW\*(C`FOO\*(C'\fR for the fictitious |
| 823 |
operation \f(CW\*(C`BAR\*(C'\fR. |
| 824 |
.PP |
| 825 |
.Vb 3 |
| 826 |
\& #include <malloc.h> |
| 827 |
\& #include <openssl/core.h> |
| 828 |
\& #include <openssl/core_dispatch.h> |
| 829 |
\& |
| 830 |
\& /* Errors used in this provider */ |
| 831 |
\& #define E_MALLOC 1 |
| 832 |
\& |
| 833 |
\& static const OSSL_ITEM reasons[] = { |
| 834 |
\& { E_MALLOC, "memory allocation failure" }. |
| 835 |
\& OSSL_DISPATCH_END |
| 836 |
\& }; |
| 837 |
\& |
| 838 |
\& /* |
| 839 |
\& * To ensure we get the function signature right, forward declare |
| 840 |
\& * them using function types provided by openssl/core_dispatch.h |
| 841 |
\& */ |
| 842 |
\& OSSL_FUNC_bar_newctx_fn foo_newctx; |
| 843 |
\& OSSL_FUNC_bar_freectx_fn foo_freectx; |
| 844 |
\& OSSL_FUNC_bar_init_fn foo_init; |
| 845 |
\& OSSL_FUNC_bar_update_fn foo_update; |
| 846 |
\& OSSL_FUNC_bar_final_fn foo_final; |
| 847 |
\& |
| 848 |
\& OSSL_FUNC_provider_query_operation_fn p_query; |
| 849 |
\& OSSL_FUNC_provider_get_reason_strings_fn p_reasons; |
| 850 |
\& OSSL_FUNC_provider_teardown_fn p_teardown; |
| 851 |
\& |
| 852 |
\& OSSL_provider_init_fn OSSL_provider_init; |
| 853 |
\& |
| 854 |
\& OSSL_FUNC_core_put_error *c_put_error = NULL; |
| 855 |
\& |
| 856 |
\& /* Provider context */ |
| 857 |
\& struct prov_ctx_st { |
| 858 |
\& OSSL_CORE_HANDLE *handle; |
| 859 |
\& } |
| 860 |
\& |
| 861 |
\& /* operation context for the algorithm FOO */ |
| 862 |
\& struct foo_ctx_st { |
| 863 |
\& struct prov_ctx_st *provctx; |
| 864 |
\& int b; |
| 865 |
\& }; |
| 866 |
\& |
| 867 |
\& static void *foo_newctx(void *provctx) |
| 868 |
\& { |
| 869 |
\& struct foo_ctx_st *fooctx = malloc(sizeof(*fooctx)); |
| 870 |
\& |
| 871 |
\& if (fooctx != NULL) |
| 872 |
\& fooctx\->provctx = provctx; |
| 873 |
\& else |
| 874 |
\& c_put_error(provctx\->handle, E_MALLOC, _\|_FILE_\|_, _\|_LINE_\|_); |
| 875 |
\& return fooctx; |
| 876 |
\& } |
| 877 |
\& |
| 878 |
\& static void foo_freectx(void *fooctx) |
| 879 |
\& { |
| 880 |
\& free(fooctx); |
| 881 |
\& } |
| 882 |
\& |
| 883 |
\& static int foo_init(void *vfooctx) |
| 884 |
\& { |
| 885 |
\& struct foo_ctx_st *fooctx = vfooctx; |
| 886 |
\& |
| 887 |
\& fooctx\->b = 0x33; |
| 888 |
\& } |
| 889 |
\& |
| 890 |
\& static int foo_update(void *vfooctx, unsigned char *in, size_t inl) |
| 891 |
\& { |
| 892 |
\& struct foo_ctx_st *fooctx = vfooctx; |
| 893 |
\& |
| 894 |
\& /* did you expect something serious? */ |
| 895 |
\& if (inl == 0) |
| 896 |
\& return 1; |
| 897 |
\& for (; inl\-\- > 0; in++) |
| 898 |
\& *in ^= fooctx\->b; |
| 899 |
\& return 1; |
| 900 |
\& } |
| 901 |
\& |
| 902 |
\& static int foo_final(void *vfooctx) |
| 903 |
\& { |
| 904 |
\& struct foo_ctx_st *fooctx = vfooctx; |
| 905 |
\& |
| 906 |
\& fooctx\->b = 0x66; |
| 907 |
\& } |
| 908 |
\& |
| 909 |
\& static const OSSL_DISPATCH foo_fns[] = { |
| 910 |
\& { OSSL_FUNC_BAR_NEWCTX, (void (*)(void))foo_newctx }, |
| 911 |
\& { OSSL_FUNC_BAR_FREECTX, (void (*)(void))foo_freectx }, |
| 912 |
\& { OSSL_FUNC_BAR_INIT, (void (*)(void))foo_init }, |
| 913 |
\& { OSSL_FUNC_BAR_UPDATE, (void (*)(void))foo_update }, |
| 914 |
\& { OSSL_FUNC_BAR_FINAL, (void (*)(void))foo_final }, |
| 915 |
\& OSSL_DISPATCH_END |
| 916 |
\& }; |
| 917 |
\& |
| 918 |
\& static const OSSL_ALGORITHM bars[] = { |
| 919 |
\& { "FOO", "provider=chumbawamba", foo_fns }, |
| 920 |
\& { NULL, NULL, NULL } |
| 921 |
\& }; |
| 922 |
\& |
| 923 |
\& static const OSSL_ALGORITHM *p_query(void *provctx, int operation_id, |
| 924 |
\& int *no_store) |
| 925 |
\& { |
| 926 |
\& switch (operation_id) { |
| 927 |
\& case OSSL_OP_BAR: |
| 928 |
\& return bars; |
| 929 |
\& } |
| 930 |
\& return NULL; |
| 931 |
\& } |
| 932 |
\& |
| 933 |
\& static const OSSL_ITEM *p_reasons(void *provctx) |
| 934 |
\& { |
| 935 |
\& return reasons; |
| 936 |
\& } |
| 937 |
\& |
| 938 |
\& static void p_teardown(void *provctx) |
| 939 |
\& { |
| 940 |
\& free(provctx); |
| 941 |
\& } |
| 942 |
\& |
| 943 |
\& static const OSSL_DISPATCH prov_fns[] = { |
| 944 |
\& { OSSL_FUNC_PROVIDER_TEARDOWN, (void (*)(void))p_teardown }, |
| 945 |
\& { OSSL_FUNC_PROVIDER_QUERY_OPERATION, (void (*)(void))p_query }, |
| 946 |
\& { OSSL_FUNC_PROVIDER_GET_REASON_STRINGS, (void (*)(void))p_reasons }, |
| 947 |
\& OSSL_DISPATCH_END |
| 948 |
\& }; |
| 949 |
\& |
| 950 |
\& int OSSL_provider_init(const OSSL_CORE_HANDLE *handle, |
| 951 |
\& const OSSL_DISPATCH *in, |
| 952 |
\& const OSSL_DISPATCH **out, |
| 953 |
\& void **provctx) |
| 954 |
\& { |
| 955 |
\& struct prov_ctx_st *pctx = NULL; |
| 956 |
\& |
| 957 |
\& for (; in\->function_id != 0; in++) |
| 958 |
\& switch (in\->function_id) { |
| 959 |
\& case OSSL_FUNC_CORE_PUT_ERROR: |
| 960 |
\& c_put_error = OSSL_FUNC_core_put_error(in); |
| 961 |
\& break; |
| 962 |
\& } |
| 963 |
\& |
| 964 |
\& *out = prov_fns; |
| 965 |
\& |
| 966 |
\& if ((pctx = malloc(sizeof(*pctx))) == NULL) { |
| 967 |
\& /* |
| 968 |
\& * ALEA IACTA EST, if the core retrieves the reason table |
| 969 |
\& * regardless, that string will be displayed, otherwise not. |
| 970 |
\& */ |
| 971 |
\& c_put_error(handle, E_MALLOC, _\|_FILE_\|_, _\|_LINE_\|_); |
| 972 |
\& return 0; |
| 973 |
\& } |
| 974 |
\& pctx\->handle = handle; |
| 975 |
\& return 1; |
| 976 |
\& } |
| 977 |
.Ve |
| 978 |
.PP |
| 979 |
This relies on a few things existing in \fIopenssl/core_dispatch.h\fR: |
| 980 |
.PP |
| 981 |
.Vb 1 |
| 982 |
\& #define OSSL_OP_BAR 4711 |
| 983 |
\& |
| 984 |
\& #define OSSL_FUNC_BAR_NEWCTX 1 |
| 985 |
\& typedef void *(OSSL_FUNC_bar_newctx_fn)(void *provctx); |
| 986 |
\& static ossl_inline OSSL_FUNC_bar_newctx(const OSSL_DISPATCH *opf) |
| 987 |
\& { return (OSSL_FUNC_bar_newctx_fn *)opf\->function; } |
| 988 |
\& |
| 989 |
\& #define OSSL_FUNC_BAR_FREECTX 2 |
| 990 |
\& typedef void (OSSL_FUNC_bar_freectx_fn)(void *ctx); |
| 991 |
\& static ossl_inline OSSL_FUNC_bar_freectx(const OSSL_DISPATCH *opf) |
| 992 |
\& { return (OSSL_FUNC_bar_freectx_fn *)opf\->function; } |
| 993 |
\& |
| 994 |
\& #define OSSL_FUNC_BAR_INIT 3 |
| 995 |
\& typedef void *(OSSL_FUNC_bar_init_fn)(void *ctx); |
| 996 |
\& static ossl_inline OSSL_FUNC_bar_init(const OSSL_DISPATCH *opf) |
| 997 |
\& { return (OSSL_FUNC_bar_init_fn *)opf\->function; } |
| 998 |
\& |
| 999 |
\& #define OSSL_FUNC_BAR_UPDATE 4 |
| 1000 |
\& typedef void *(OSSL_FUNC_bar_update_fn)(void *ctx, |
| 1001 |
\& unsigned char *in, size_t inl); |
| 1002 |
\& static ossl_inline OSSL_FUNC_bar_update(const OSSL_DISPATCH *opf) |
| 1003 |
\& { return (OSSL_FUNC_bar_update_fn *)opf\->function; } |
| 1004 |
\& |
| 1005 |
\& #define OSSL_FUNC_BAR_FINAL 5 |
| 1006 |
\& typedef void *(OSSL_FUNC_bar_final_fn)(void *ctx); |
| 1007 |
\& static ossl_inline OSSL_FUNC_bar_final(const OSSL_DISPATCH *opf) |
| 1008 |
\& { return (OSSL_FUNC_bar_final_fn *)opf\->function; } |
| 1009 |
.Ve |
| 1010 |
.SH "SEE ALSO" |
| 1011 |
.IX Header "SEE ALSO" |
| 1012 |
\&\fBprovider\fR\|(7) |
| 1013 |
.SH HISTORY |
| 1014 |
.IX Header "HISTORY" |
| 1015 |
The concept of providers and everything surrounding them was |
| 1016 |
introduced in OpenSSL 3.0. |
| 1017 |
.PP |
| 1018 |
Definitions for |
| 1019 |
\&\fBOSSL_CAPABILITY_TLS_SIGALG_MIN_DTLS\fR |
| 1020 |
and |
| 1021 |
\&\fBOSSL_CAPABILITY_TLS_SIGALG_MAX_DTLS\fR |
| 1022 |
were added in OpenSSL 3.5. |
| 1023 |
.SH COPYRIGHT |
| 1024 |
.IX Header "COPYRIGHT" |
| 1025 |
Copyright 2019\-2026 The OpenSSL Project Authors. All Rights Reserved. |
| 1026 |
.PP |
| 1027 |
Licensed under the Apache License 2.0 (the "License"). You may not use |
| 1028 |
this file except in compliance with the License. You can obtain a copy |
| 1029 |
in the file LICENSE in the source distribution or at |
| 1030 |
<https://www.openssl.org/source/license.html>. |