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