diff --git a/doc/man7/provider-base.pod b/doc/man7/provider-base.pod index a52c718e19..aefaa4082d 100644 --- a/doc/man7/provider-base.pod +++ b/doc/man7/provider-base.pod @@ -16,15 +16,15 @@ provider-base */ /* Functions offered by libcrypto to the providers */ - const OSSL_ITEM *core_gettable_params(const OSSL_PROVIDER *prov); - int core_get_params(const OSSL_PROVIDER *prov, OSSL_PARAM params[]); - int core_thread_start(const OSSL_PROVIDER *prov, + const OSSL_ITEM *core_gettable_params(const OSSL_CORE_HANDLE *handle); + int core_get_params(const OSSL_CORE_HANDLE *handle, OSSL_PARAM params[]); + int core_thread_start(const OSSL_CORE_HANDLE *handle, OSSL_thread_stop_handler_fn handfn); - OPENSSL_CTX *core_get_library_context(const OSSL_PROVIDER *prov); - void core_new_error(const OSSL_PROVIDER *prov); - void core_set_error_debug(const OSSL_PROVIDER *prov, + OPENSSL_CORE_CTX *core_get_library_context(const OSSL_CORE_HANDLE *handle); + void core_new_error(const OSSL_CORE_HANDLE *handle); + void core_set_error_debug(const OSSL_CORE_HANDLE *handle, const char *file, int line, const char *func); - void core_vset_error(const OSSL_PROVIDER *prov, + void core_vset_error(const OSSL_CORE_HANDLE *handle, uint32_t reason, const char *fmt, va_list args); /* @@ -52,7 +52,19 @@ provider-base const char *file, int line); int CRYPTO_secure_allocated(const void *ptr); void OPENSSL_cleanse(void *ptr, size_t len); - unsigned char *OPENSSL_hexstr2buf(const char *str, long *len); + + OSSL_CORE_BIO * BIO_new_file(const char *filename, const char *mode) + OSSL_CORE_BIO * BIO_new_membuf(const void *buf, int len) + int BIO_read_ex(OSSL_CORE_BIO *bio, void *data, size_t data_len, + size_t *bytes_read)) + int BIO_write_ex(OSSL_CORE_BIO *bio, const void *data, size_t data_len, + size_t *written) + int BIO_free(OSSL_CORE_BIO *bio)) + int BIO_vprintf(OSSL_CORE_BIO *bio, const char *format, va_list args) + int BIO_vsnprintf(char *buf, size_t n, const char *fmt, va_list args) + + void self_test_cb(OPENSSL_CORE_CTX *ctx, OSSL_CALLBACK **cb, void **cbarg) + /* Functions offered by the provider to libcrypto */ void provider_teardown(void *provctx); @@ -76,8 +88,8 @@ function pointer from a B element named B. For example, the "function" core_gettable_params() has these: - typedef OSSL_ITEM * - (OSSL_core_gettable_params_fn)(const OSSL_PROVIDER *prov); + typedef OSSL_PARAM * + (OSSL_core_gettable_params_fn)(const OSSL_CORE_HANDLE *handle); static ossl_inline OSSL_NAME_core_gettable_params_fn OSSL_get_core_gettable_params(const OSSL_DISPATCH *opf); @@ -114,7 +126,6 @@ provider): BIO_free OSSL_FUNC_BIO_FREE BIO_vprintf OSSL_FUNC_BIO_VPRINTF OPENSSL_cleanse OSSL_FUNC_OPENSSL_CLEANSE - OPENSSL_hexstr2buf OSSL_FUNC_OPENSSL_HEXSTR2BUF OSSL_SELF_TEST_set_callback OSSL_FUNC_SELF_TEST_CB For I<*out> (the B array passed from the provider to @@ -131,20 +142,20 @@ F): core_gettable_params() returns a constant array of descriptor B, for parameters that core_get_params() can handle. -core_get_params() retrieves I parameters from the core. +core_get_params() retrieves parameters from the core for the given I. See L below for a description of currently known parameters. =for comment core_thread_start() TBA -core_get_library_context() retrieves the library context in which the -B object I is stored. +core_get_library_context() retrieves the library context in which the library +object for the current provider is stored, accessible through the I. This may sometimes be useful if the provider wishes to store a reference to its context in the same library context. core_new_error(), core_set_error_debug() and core_set_error() are building blocks for reporting an error back to the core, with -reference to the provider object I. +reference to the I. =over 4 @@ -188,7 +199,10 @@ BIO_new_file(), BIO_new_mem_buf(), BIO_read_ex(), BIO_free(), BIO_vprintf(), OPENSSL_cleanse(), and OPENSSL_hexstr2buf() correspond exactly to the public functions with the same name. As a matter of fact, the pointers in the B array are -direct pointers to those public functions. +direct pointers to those public functions. Note that the BIO functions take an +B type rather than the standard B type. This is to ensure +that a provider does not mix BIOs from the core with BIOs used on the provider +side (the two are not compatible). OSSL_SELF_TEST_set_callback() is used to set an optional callback that can be passed into a provider. This may be ignored by a provider. @@ -327,7 +341,7 @@ operation C. /* Provider context */ struct prov_ctx_st { - OSSL_PROVIDER *prov; + OSSL_CORE_HANDLE *handle; } /* operation context for the algorithm FOO */ @@ -343,7 +357,7 @@ operation C. if (fooctx != NULL) fooctx->provctx = provctx; else - c_put_error(provctx->prov, E_MALLOC, __FILE__, __LINE__); + c_put_error(provctx->handle, E_MALLOC, __FILE__, __LINE__); return fooctx; } @@ -419,7 +433,7 @@ operation C. { 0, NULL } }; - int OSSL_provider_init(const OSSL_PROVIDER *provider, + int OSSL_provider_init(const OSSL_CORE_HANDLE *handle, const OSSL_DISPATCH *in, const OSSL_DISPATCH **out, void **provctx) @@ -440,9 +454,10 @@ operation C. * ALEA IACTA EST, if the core retrieves the reason table * regardless, that string will be displayed, otherwise not. */ - c_put_error(provider, E_MALLOC, __FILE__, __LINE__); + c_put_error(handle, E_MALLOC, __FILE__, __LINE__); return 0; } + pctx->handle = handle; return 1; } diff --git a/doc/man7/provider-serializer.pod b/doc/man7/provider-serializer.pod index dfc803128f..ad3b5fdd65 100644 --- a/doc/man7/provider-serializer.pod +++ b/doc/man7/provider-serializer.pod @@ -28,10 +28,10 @@ Future development will also include deserializing functions. /* Functions to serialize object data */ int OP_serializer_serialize_data(void *ctx, const OSSL_PARAM *data, - BIO *out, + OSSL_CORE_BIO *out, OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg); - int OP_serializer_serialize_object(void *ctx, void *obj, BIO *out, + int OP_serializer_serialize_object(void *ctx, void *obj, OSSL_CORE_BIO *out, OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg); @@ -39,11 +39,11 @@ Future development will also include deserializing functions. The SERIALIZER is a generic method to serialize any set of object data in L array form, or any provider side object into -serialized form, and write it to the given BIO. If the caller wants +serialized form, and write it to the given OSSL_CORE_BIO. If the caller wants to get the serialized stream to memory, it should provide a L. -The serializer doesn't need to know more about the B pointer than +The serializer doesn't need to know more about the B pointer than being able to pass it to the appropriate BIO upcalls (see L). @@ -71,7 +71,7 @@ For example, the "function" OP_serializer_serialize_data() has these: typedef int (OSSL_OP_serializer_serialize_data_fn)(void *provctx, const OSSL_PARAM params[], - BIO *out); + OSSL_CORE_BIO *out); static ossl_inline OSSL_OP_serializer_serialize_data_fn OSSL_get_OP_serializer_serialize_data(const OSSL_DISPATCH *opf); @@ -180,11 +180,11 @@ by OP_serializer_set_ctx_params() and OP_serializer_settable_ctx_params(). OP_serializer_serialize_data() should take an array of B, I, and if it contains the data necessary for the object type that the implementation handles, it should output the object in -serialized form to the B. +serialized form to the B. OP_serializer_serialize_object() should take a pointer to an object that it knows intimately, and output that object in serialized form to -the B. The caller I ensure that this function is called +the B. The caller I ensure that this function is called with a pointer that the provider of this function is familiar with. It is not suitable to use with object pointers coming from other providers. diff --git a/doc/man7/provider.pod b/doc/man7/provider.pod index f7f6bbe9cd..581c33b9a4 100644 --- a/doc/man7/provider.pod +++ b/doc/man7/provider.pod @@ -42,16 +42,15 @@ If it's built-in, the initialization function may have any name. The initialization function must have the following signature: - int NAME(const OSSL_PROVIDER *provider, + int NAME(const OSSL_CORE_HANDLE *handle, const OSSL_DISPATCH *in, const OSSL_DISPATCH **out, void **provctx); -I is the OpenSSL library object for the provider, and works +I is the OpenSSL library object for the provider, and works as a handle for everything the OpenSSL libraries need to know about the provider. -For the provider itself, it may hold some interesting information, -and is also passed to some of the functions given in the dispatch -array I. +For the provider itself, it is passed to some of the functions given in the +dispatch array I. I is a dispatch array of base functions offered by the OpenSSL libraries, and the available functions are further described in @@ -288,6 +287,13 @@ Should it be needed (if other providers are loaded and offer implementations of the same algorithms), the property "provider=legacy" can be used as a search criterion for these implementations. +=head2 Null provider + +The null provider is built in as part of the F library. It contains +no algorithms in it at all. When fetching algorithms the default provider will +be automatically loaded if no other provider has been explicitly loaded. To +prevent that from happening you can explicitly load the null provider. + =head1 EXAMPLES =head2 Fetching