diff options
author | Dr. Matthias St. Pierre <matthias.st.pierre@ncp-e.com> | 2020-06-21 01:19:16 +0200 |
---|---|---|
committer | Dr. Matthias St. Pierre <matthias.st.pierre@ncp-e.com> | 2020-06-24 22:01:22 +0200 |
commit | 363b1e5daea4a01889e6ff27148018be63d33b9b (patch) | |
tree | 9e6f5fe3be912b433fa848c44df11a15d0aa2921 /doc | |
parent | 23c48d94d4d34eedc15fa65e0fa0e38a6137e09f (diff) |
Make the naming scheme for dispatched functions more consistent
The new naming scheme consistently usese the `OSSL_FUNC_` prefix for all
functions which are dispatched between the core and providers.
This change includes in particular all up- and downcalls, i.e., the
dispatched functions passed from core to provider and vice versa.
- OSSL_core_ -> OSSL_FUNC_core_
- OSSL_provider_ -> OSSL_FUNC_core_
For operations and their function dispatch tables, the following convention
is used:
Type | Name (evp_generic_fetch(3)) |
---------------------|-----------------------------------|
operation | OSSL_OP_FOO |
function id | OSSL_FUNC_FOO_FUNCTION_NAME |
function "name" | OSSL_FUNC_foo_function_name |
function typedef | OSSL_FUNC_foo_function_name_fn |
function ptr getter | OSSL_FUNC_foo_function_name |
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/12222)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/internal/man3/evp_generic_fetch.pod | 59 | ||||
-rw-r--r-- | doc/man3/EVP_RAND.pod | 2 | ||||
-rw-r--r-- | doc/man7/provider-asym_cipher.pod | 106 | ||||
-rw-r--r-- | doc/man7/provider-base.pod | 56 | ||||
-rw-r--r-- | doc/man7/provider-cipher.pod | 136 | ||||
-rw-r--r-- | doc/man7/provider-digest.pod | 118 | ||||
-rw-r--r-- | doc/man7/provider-keyexch.pod | 88 | ||||
-rw-r--r-- | doc/man7/provider-keymgmt.pod | 182 | ||||
-rw-r--r-- | doc/man7/provider-mac.pod | 102 | ||||
-rw-r--r-- | doc/man7/provider-rand.pod | 106 | ||||
-rw-r--r-- | doc/man7/provider-serializer.pod | 72 | ||||
-rw-r--r-- | doc/man7/provider-signature.pod | 228 |
12 files changed, 629 insertions, 626 deletions
diff --git a/doc/internal/man3/evp_generic_fetch.pod b/doc/internal/man3/evp_generic_fetch.pod index 4d2f6bdd69..34f157e353 100644 --- a/doc/internal/man3/evp_generic_fetch.pod +++ b/doc/internal/man3/evp_generic_fetch.pod @@ -80,20 +80,21 @@ B<EVP_FOO>. To begin with, let's assume something like this in F<include/openssl/core_dispatch.h>: - #define OSSL_OP_FOO 100 - - #define OSSL_OP_FOO_NEWCTX_FUNC 2001 - #define OSSL_OP_FOO_INIT 2002 - #define OSSL_OP_FOO_OPERATE 2003 - #define OSSL_OP_FOO_CLEANCTX_FUNC 2004 - #define OSSL_OP_FOO_FREECTX_FUNC 2005 - OSSL_CORE_MAKE_FUNC(void *,OP_foo_newctx,(void)) - OSSL_CORE_MAKE_FUNC(int,OP_foo_init,(void *vctx)) - OSSL_CORE_MAKE_FUNC(int,OP_foo_operate,(void *vctx, - unsigned char *out, size_t *out_l, - unsigned char *in, size_t in_l)) - OSSL_CORE_MAKE_FUNC(void,OP_foo_cleanctx,(void *vctx)) - OSSL_CORE_MAKE_FUNC(void,OP_foo_freectx,(void *vctx)) + #define OSSL_OP_FOO 100 + + #define OSSL_FUNC_FOO_NEWCTX_FUNC 2001 + #define OSSL_FUNC_FOO_INIT 2002 + #define OSSL_FUNC_FOO_OPERATE 2003 + #define OSSL_FUNC_FOO_CLEANCTX_FUNC 2004 + #define OSSL_FUNC_FOO_FREECTX_FUNC 2005 + + OSSL_CORE_MAKE_FUNC(void *, foo_newctx, (void)) + OSSL_CORE_MAKE_FUNC(int, foo_init, (void *vctx)) + OSSL_CORE_MAKE_FUNC(int, foo_operate, (void *vctx, + unsigned char *out, size_t *out_l, + unsigned char *in, size_t in_l)) + OSSL_CORE_MAKE_FUNC(void, foo_cleanctx, (void *vctx)) + OSSL_CORE_MAKE_FUNC(void, foo_freectx, (void *vctx)) And here's the implementation of the FOO method fetcher: @@ -102,11 +103,11 @@ And here's the implementation of the FOO method fetcher: OSSL_PROVIDER *prov; int name_id; CRYPTO_REF_COUNT refcnt; - OSSL_OP_foo_newctx_fn *newctx; - OSSL_OP_foo_init_fn *init; - OSSL_OP_foo_operate_fn *operate; - OSSL_OP_foo_cleanctx_fn *cleanctx; - OSSL_OP_foo_freectx_fn *freectx; + OSSL_FUNC_foo_newctx_fn *newctx; + OSSL_FUNC_foo_init_fn *init; + OSSL_FUNC_foo_operate_fn *operate; + OSSL_FUNC_foo_cleanctx_fn *cleanctx; + OSSL_FUNC_foo_freectx_fn *freectx; }; /* @@ -127,20 +128,20 @@ And here's the implementation of the FOO method fetcher: for (; fns->function_id != 0; fns++) { switch (fns->function_id) { - case OSSL_OP_FOO_NEWCTX_FUNC: - foo->newctx = OSSL_get_OP_foo_newctx(fns); + case OSSL_FUNC_FOO_NEWCTX: + foo->newctx = OSSL_FUNC_foo_newctx(fns); break; - case OSSL_OP_FOO_INIT: - foo->init = OSSL_get_OP_foo_init(fns); + case OSSL_FUNC_FOO_INIT: + foo->init = OSSL_FUNC_foo_init(fns); break; - case OSSL_OP_FOO_OPERATE: - foo->operate = OSSL_get_OP_foo_operate(fns); + case OSSL_FUNC_FOO_OPERATE: + foo->operate = OSSL_FUNC_foo_operate(fns); break; - case OSSL_OP_FOO_CLEANCTX_FUNC: - foo->cleanctx = OSSL_get_OP_foo_cleanctx(fns); + case OSSL_FUNC_FOO_CLEANCTX: + foo->cleanctx = OSSL_FUNC_foo_cleanctx(fns); break; - case OSSL_OP_FOO_FREECTX_FUNC: - foo->freectx = OSSL_get_OP_foo_freectx(fns); + case OSSL_FUNC_FOO_FREECTX: + foo->freectx = OSSL_FUNC_foo_freectx(fns); break; } } diff --git a/doc/man3/EVP_RAND.pod b/doc/man3/EVP_RAND.pod index c32217543e..c79f5e6548 100644 --- a/doc/man3/EVP_RAND.pod +++ b/doc/man3/EVP_RAND.pod @@ -275,7 +275,7 @@ associated RAND ctx. =item "max_request" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer> Specifies the maximum number of bytes that can be generated in a single -call to OP_rand_generate. +call to OSSL_FUNC_rand_generate. =item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer> diff --git a/doc/man7/provider-asym_cipher.pod b/doc/man7/provider-asym_cipher.pod index 5a911f9a0e..fa56391a04 100644 --- a/doc/man7/provider-asym_cipher.pod +++ b/doc/man7/provider-asym_cipher.pod @@ -18,27 +18,27 @@ provider-asym_cipher - The asym_cipher library E<lt>-E<gt> provider functions */ /* Context management */ - void *OP_asym_cipher_newctx(void *provctx); - void OP_asym_cipher_freectx(void *ctx); - void *OP_asym_cipher_dupctx(void *ctx); + void *OSSL_FUNC_asym_cipher_newctx(void *provctx); + void OSSL_FUNC_asym_cipher_freectx(void *ctx); + void *OSSL_FUNC_asym_cipher_dupctx(void *ctx); /* Encryption */ - int OP_asym_cipher_encrypt_init(void *ctx, void *provkey); - int OP_asym_cipher_encrypt(void *ctx, unsigned char *out, size_t *outlen, - size_t outsize, const unsigned char *in, - size_t inlen); + int OSSL_FUNC_asym_cipher_encrypt_init(void *ctx, void *provkey); + int OSSL_FUNC_asym_cipher_encrypt(void *ctx, unsigned char *out, size_t *outlen, + size_t outsize, const unsigned char *in, + size_t inlen); /* Decryption */ - int OP_asym_cipher_decrypt_init(void *ctx, void *provkey); - int OP_asym_cipher_decrypt(void *ctx, unsigned char *out, size_t *outlen, - size_t outsize, const unsigned char *in, - size_t inlen); + int OSSL_FUNC_asym_cipher_decrypt_init(void *ctx, void *provkey); + int OSSL_FUNC_asym_cipher_decrypt(void *ctx, unsigned char *out, size_t *outlen, + size_t outsize, const unsigned char *in, + size_t inlen); /* Asymmetric Cipher parameters */ - int OP_asym_cipher_get_ctx_params(void *ctx, OSSL_PARAM params[]); - const OSSL_PARAM *OP_asym_cipher_gettable_ctx_params(void); - int OP_asym_cipher_set_ctx_params(void *ctx, const OSSL_PARAM params[]); - const OSSL_PARAM *OP_asym_cipher_settable_ctx_params(void); + int OSSL_FUNC_asym_cipher_get_ctx_params(void *ctx, OSSL_PARAM params[]); + const OSSL_PARAM *OSSL_FUNC_asym_cipher_gettable_ctx_params(void); + int OSSL_FUNC_asym_cipher_set_ctx_params(void *ctx, const OSSL_PARAM params[]); + const OSSL_PARAM *OSSL_FUNC_asym_cipher_settable_ctx_params(void); =head1 DESCRIPTION @@ -60,42 +60,42 @@ provider_query_operation() function All these "functions" have a corresponding function type definition named B<OSSL_{name}_fn>, and a helper function to retrieve the function pointer from an B<OSSL_DISPATCH> element named -B<OSSL_get_{name}>. -For example, the "function" OP_asym_cipher_newctx() has these: +B<OSSL_FUNC_{name}>. +For example, the "function" OSSL_FUNC_asym_cipher_newctx() has these: - typedef void *(OSSL_OP_asym_cipher_newctx_fn)(void *provctx); - static ossl_inline OSSL_OP_asym_cipher_newctx_fn - OSSL_get_OP_asym_cipher_newctx(const OSSL_DISPATCH *opf); + typedef void *(OSSL_FUNC_asym_cipher_newctx_fn)(void *provctx); + static ossl_inline OSSL_FUNC_asym_cipher_newctx_fn + OSSL_FUNC_asym_cipher_newctx(const OSSL_DISPATCH *opf); B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as macros in L<openssl-core_dispatch.h(7)>, as follows: - OP_asym_cipher_newctx OSSL_FUNC_ASYM_CIPHER_NEWCTX - OP_asym_cipher_freectx OSSL_FUNC_ASYM_CIPHER_FREECTX - OP_asym_cipher_dupctx OSSL_FUNC_ASYM_CIPHER_DUPCTX + OSSL_FUNC_asym_cipher_newctx OSSL_FUNC_ASYM_CIPHER_NEWCTX + OSSL_FUNC_asym_cipher_freectx OSSL_FUNC_ASYM_CIPHER_FREECTX + OSSL_FUNC_asym_cipher_dupctx OSSL_FUNC_ASYM_CIPHER_DUPCTX - OP_asym_cipher_encrypt_init OSSL_FUNC_ASYM_CIPHER_ENCRYPT_INIT - OP_asym_cipher_encrypt OSSL_FUNC_ASYM_CIPHER_ENCRYPT + OSSL_FUNC_asym_cipher_encrypt_init OSSL_FUNC_ASYM_CIPHER_ENCRYPT_INIT + OSSL_FUNC_asym_cipher_encrypt OSSL_FUNC_ASYM_CIPHER_ENCRYPT - OP_asym_cipher_decrypt_init OSSL_FUNC_ASYM_CIPHER_DECRYPT_INIT - OP_asym_cipher_decrypt OSSL_FUNC_ASYM_CIPHER_DECRYPT + OSSL_FUNC_asym_cipher_decrypt_init OSSL_FUNC_ASYM_CIPHER_DECRYPT_INIT + OSSL_FUNC_asym_cipher_decrypt OSSL_FUNC_ASYM_CIPHER_DECRYPT - OP_asym_cipher_get_ctx_params OSSL_FUNC_ASYM_CIPHER_GET_CTX_PARAMS - OP_asym_cipher_gettable_ctx_params OSSL_FUNC_ASYM_CIPHER_GETTABLE_CTX_PARAMS - OP_asym_cipher_set_ctx_params OSSL_FUNC_ASYM_CIPHER_SET_CTX_PARAMS - OP_asym_cipher_settable_ctx_params OSSL_FUNC_ASYM_CIPHER_SETTABLE_CTX_PARAMS + OSSL_FUNC_asym_cipher_get_ctx_params OSSL_FUNC_ASYM_CIPHER_GET_CTX_PARAMS + OSSL_FUNC_asym_cipher_gettable_ctx_params OSSL_FUNC_ASYM_CIPHER_GETTABLE_CTX_PARAMS + OSSL_FUNC_asym_cipher_set_ctx_params OSSL_FUNC_ASYM_CIPHER_SET_CTX_PARAMS + OSSL_FUNC_asym_cipher_settable_ctx_params OSSL_FUNC_ASYM_CIPHER_SETTABLE_CTX_PARAMS An asymmetric cipher algorithm implementation may not implement all of these functions. In order to be a consistent set of functions a provider must implement -OP_asym_cipher_newctx and OP_asym_cipher_freectx. -It must also implement both of OP_asym_cipher_encrypt_init and -OP_asym_cipher_encrypt, or both of OP_asym_cipher_decrypt_init and -OP_asym_cipher_decrypt. -OP_asym_cipher_get_ctx_params is optional but if it is present then so must -OP_asym_cipher_gettable_ctx_params. -Similarly, OP_asym_cipher_set_ctx_params is optional but if it is present then -so must OP_asym_cipher_settable_ctx_params. +OSSL_FUNC_asym_cipher_newctx and OSSL_FUNC_asym_cipher_freectx. +It must also implement both of OSSL_FUNC_asym_cipher_encrypt_init and +OSSL_FUNC_asym_cipher_encrypt, or both of OSSL_FUNC_asym_cipher_decrypt_init and +OSSL_FUNC_asym_cipher_decrypt. +OSSL_FUNC_asym_cipher_get_ctx_params is optional but if it is present then so must +OSSL_FUNC_asym_cipher_gettable_ctx_params. +Similarly, OSSL_FUNC_asym_cipher_set_ctx_params is optional but if it is present then +so must OSSL_FUNC_asym_cipher_settable_ctx_params. An asymmetric cipher algorithm must also implement some mechanism for generating, loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation. @@ -103,30 +103,30 @@ See L<provider-keymgmt(7)> for further details. =head2 Context Management Functions -OP_asym_cipher_newctx() should create and return a pointer to a provider side +OSSL_FUNC_asym_cipher_newctx() should create and return a pointer to a provider side structure for holding context information during an asymmetric cipher operation. A pointer to this context will be passed back in a number of the other asymmetric cipher operation function calls. The parameter I<provctx> is the provider context generated during provider initialisation (see L<provider(7)>). -OP_asym_cipher_freectx() is passed a pointer to the provider side asymmetric +OSSL_FUNC_asym_cipher_freectx() is passed a pointer to the provider side asymmetric cipher context in the I<ctx> parameter. This function should free any resources associated with that context. -OP_asym_cipher_dupctx() should duplicate the provider side asymmetric cipher +OSSL_FUNC_asym_cipher_dupctx() should duplicate the provider side asymmetric cipher context in the I<ctx> parameter and return the duplicate copy. =head2 Encryption Functions -OP_asym_cipher_encrypt_init() initialises a context for an asymmetric encryption +OSSL_FUNC_asym_cipher_encrypt_init() initialises a context for an asymmetric encryption given a provider side asymmetric cipher context in the I<ctx> parameter, and a pointer to a provider key object in the I<provkey> parameter. The key object should have been previously generated, loaded or imported into the provider using the key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>. -OP_asym_cipher_encrypt() performs the actual encryption itself. +OSSL_FUNC_asym_cipher_encrypt() performs the actual encryption itself. A previously initialised asymmetric cipher context is passed in the I<ctx> parameter. The data to be encrypted is pointed to by the I<in> parameter which is I<inlen> @@ -140,14 +140,14 @@ written to I<*outlen>. =head2 Decryption Functions -OP_asym_cipher_decrypt_init() initialises a context for an asymmetric decryption +OSSL_FUNC_asym_cipher_decrypt_init() initialises a context for an asymmetric decryption given a provider side asymmetric cipher context in the I<ctx> parameter, and a pointer to a provider key object in the I<provkey> parameter. The key object should have been previously generated, loaded or imported into the provider using the key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>. -OP_asym_cipher_decrypt() performs the actual decryption itself. +OSSL_FUNC_asym_cipher_decrypt() performs the actual decryption itself. A previously initialised asymmetric cipher context is passed in the I<ctx> parameter. The data to be decrypted is pointed to by the I<in> parameter which is I<inlen> @@ -162,13 +162,13 @@ written to I<*outlen>. =head2 Asymmetric Cipher Parameters See L<OSSL_PARAM(3)> for further details on the parameters structure used by -the OP_asym_cipher_get_ctx_params() and OP_asym_cipher_set_ctx_params() +the OSSL_FUNC_asym_cipher_get_ctx_params() and OSSL_FUNC_asym_cipher_set_ctx_params() functions. -OP_asym_cipher_get_ctx_params() gets asymmetric cipher parameters associated +OSSL_FUNC_asym_cipher_get_ctx_params() gets asymmetric cipher parameters associated with the given provider side asymmetric cipher context I<ctx> and stores them in I<params>. -OP_asym_cipher_set_ctx_params() sets the asymmetric cipher parameters associated +OSSL_FUNC_asym_cipher_set_ctx_params() sets the asymmetric cipher parameters associated with the given provider side asymmetric cipher context I<ctx> to I<params>. Any parameter settings are additional to any that were previously set. @@ -226,15 +226,15 @@ B<RSA_PKCS1_WITH_TLS_PADDING> on the page L<EVP_PKEY_CTX_set_rsa_padding(3)>. =back -OP_asym_cipher_gettable_ctx_params() and OP_asym_cipher_settable_ctx_params() +OSSL_FUNC_asym_cipher_gettable_ctx_params() and OSSL_FUNC_asym_cipher_settable_ctx_params() get a constant B<OSSL_PARAM> array that describes the gettable and settable -parameters, i.e. parameters that can be used with OP_asym_cipherget_ctx_params() -and OP_asym_cipher_set_ctx_params() respectively. +parameters, i.e. parameters that can be used with OSSL_FUNC_asym_cipherget_ctx_params() +and OSSL_FUNC_asym_cipher_set_ctx_params() respectively. See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor. =head1 RETURN VALUES -OP_asym_cipher_newctx() and OP_asym_cipher_dupctx() should return the newly +OSSL_FUNC_asym_cipher_newctx() and OSSL_FUNC_asym_cipher_dupctx() should return the newly created provider side asymmetric cipher context, or NULL on failure. All other functions should return 1 for success or 0 on error. diff --git a/doc/man7/provider-base.pod b/doc/man7/provider-base.pod index d6a510c2dc..35e9f6f614 100644 --- a/doc/man7/provider-base.pod +++ b/doc/man7/provider-base.pod @@ -87,13 +87,13 @@ for a description of the initialization function. All these "functions" have a corresponding function type definition named B<OSSL_{name}_fn>, and a helper function to retrieve the function pointer from a B<OSSL_DISPATCH> element named -B<OSSL_get_{name}>. +B<OSSL_FUNC_{name}>. For example, the "function" core_gettable_params() has these: typedef OSSL_PARAM * - (OSSL_core_gettable_params_fn)(const OSSL_CORE_HANDLE *handle); + (OSSL_FUNC_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); + OSSL_FUNC_core_gettable_params(const OSSL_DISPATCH *opf); B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as macros in L<openssl-core_dispatch.h(7)>, as follows: @@ -433,19 +433,19 @@ operation C<BAR>. * To ensure we get the function signature right, forward declare * them using function types provided by openssl/core_dispatch.h */ - OSSL_OP_bar_newctx_fn foo_newctx; - OSSL_OP_bar_freectx_fn foo_freectx; - OSSL_OP_bar_init_fn foo_init; - OSSL_OP_bar_update_fn foo_update; - OSSL_OP_bar_final_fn foo_final; + OSSL_FUNC_bar_newctx_fn foo_newctx; + OSSL_FUNC_bar_freectx_fn foo_freectx; + OSSL_FUNC_bar_init_fn foo_init; + OSSL_FUNC_bar_update_fn foo_update; + OSSL_FUNC_bar_final_fn foo_final; - OSSL_provider_query_operation_fn p_query; - OSSL_provider_get_reason_strings_fn p_reasons; - OSSL_provider_teardown_fn p_teardown; + OSSL_FUNC_provider_query_operation_fn p_query; + OSSL_FUNC_provider_get_reason_strings_fn p_reasons; + OSSL_FUNC_provider_teardown_fn p_teardown; OSSL_provider_init_fn OSSL_provider_init; - OSSL_core_put_error *c_put_error = NULL; + OSSL_FUNC_core_put_error *c_put_error = NULL; /* Provider context */ struct prov_ctx_st { @@ -551,7 +551,7 @@ operation C<BAR>. for (; in->function_id != 0; in++) switch (in->function_id) { case OSSL_FUNC_CORE_PUT_ERROR: - c_put_error = OSSL_get_core_put_error(in); + c_put_error = OSSL_FUNC_core_put_error(in); break; } @@ -574,30 +574,30 @@ This relies on a few things existing in F<openssl/core_dispatch.h>: #define OSSL_OP_BAR 4711 #define OSSL_FUNC_BAR_NEWCTX 1 - typedef void *(OSSL_OP_bar_newctx_fn)(void *provctx); - static ossl_inline OSSL_get_bar_newctx(const OSSL_DISPATCH *opf) - { return (OSSL_OP_bar_newctx_fn *)opf->function; } + typedef void *(OSSL_FUNC_bar_newctx_fn)(void *provctx); + static ossl_inline OSSL_FUNC_bar_newctx(const OSSL_DISPATCH *opf) + { return (OSSL_FUNC_bar_newctx_fn *)opf->function; } #define OSSL_FUNC_BAR_FREECTX 2 - typedef void (OSSL_OP_bar_freectx_fn)(void *ctx); - static ossl_inline OSSL_get_bar_newctx(const OSSL_DISPATCH *opf) - { return (OSSL_OP_bar_freectx_fn *)opf->function; } + typedef void (OSSL_FUNC_bar_freectx_fn)(void *ctx); + static ossl_inline OSSL_FUNC_bar_newctx(const OSSL_DISPATCH *opf) + { return (OSSL_FUNC_bar_freectx_fn *)opf->function; } #define OSSL_FUNC_BAR_INIT 3 - typedef void *(OSSL_OP_bar_init_fn)(void *ctx); - static ossl_inline OSSL_get_bar_init(const OSSL_DISPATCH *opf) - { return (OSSL_OP_bar_init_fn *)opf->function; } + typedef void *(OSSL_FUNC_bar_init_fn)(void *ctx); + static ossl_inline OSSL_FUNC_bar_init(const OSSL_DISPATCH *opf) + { return (OSSL_FUNC_bar_init_fn *)opf->function; } #define OSSL_FUNC_BAR_UPDATE 4 - typedef void *(OSSL_OP_bar_update_fn)(void *ctx, + typedef void *(OSSL_FUNC_bar_update_fn)(void *ctx, unsigned char *in, size_t inl); - static ossl_inline OSSL_get_bar_update(const OSSL_DISPATCH *opf) - { return (OSSL_OP_bar_update_fn *)opf->function; } + static ossl_inline OSSL_FUNC_bar_update(const OSSL_DISPATCH *opf) + { return (OSSL_FUNC_bar_update_fn *)opf->function; } #define OSSL_FUNC_BAR_FINAL 5 - typedef void *(OSSL_OP_bar_final_fn)(void *ctx); - static ossl_inline OSSL_get_bar_final(const OSSL_DISPATCH *opf) - { return (OSSL_OP_bar_final_fn *)opf->function; } + typedef void *(OSSL_FUNC_bar_final_fn)(void *ctx); + static ossl_inline OSSL_FUNC_bar_final(const OSSL_DISPATCH *opf) + { return (OSSL_FUNC_bar_final_fn *)opf->function; } =head1 SEE ALSO diff --git a/doc/man7/provider-cipher.pod b/doc/man7/provider-cipher.pod index c3b1b77fe4..bb8df17514 100644 --- a/doc/man7/provider-cipher.pod +++ b/doc/man7/provider-cipher.pod @@ -18,37 +18,37 @@ provider-cipher - The cipher library E<lt>-E<gt> provider functions */ /* Context management */ - void *OP_cipher_newctx(void *provctx); - void OP_cipher_freectx(void *cctx); - void *OP_cipher_dupctx(void *cctx); + void *OSSL_FUNC_cipher_newctx(void *provctx); + void OSSL_FUNC_cipher_freectx(void *cctx); + void *OSSL_FUNC_cipher_dupctx(void *cctx); /* Encryption/decryption */ - int OP_cipher_encrypt_init(void *cctx, const unsigned char *key, - size_t keylen, const unsigned char *iv, - size_t ivlen); - int OP_cipher_decrypt_init(void *cctx, const unsigned char *key, - size_t keylen, const unsigned char *iv, - size_t ivlen); - int OP_cipher_update(void *cctx, unsigned char *out, size_t *outl, - size_t outsize, const unsigned char *in, size_t inl); - int OP_cipher_final(void *cctx, unsigned char *out, size_t *outl, - size_t outsize); - int OP_cipher_cipher(void *cctx, unsigned char *out, size_t *outl, - size_t outsize, const unsigned char *in, size_t inl); + int OSSL_FUNC_cipher_encrypt_init(void *cctx, const unsigned char *key, + size_t keylen, const unsigned char *iv, + size_t ivlen); + int OSSL_FUNC_cipher_decrypt_init(void *cctx, const unsigned char *key, + size_t keylen, const unsigned char *iv, + size_t ivlen); + int OSSL_FUNC_cipher_update(void *cctx, unsigned char *out, size_t *outl, + size_t outsize, const unsigned char *in, size_t inl); + int OSSL_FUNC_cipher_final(void *cctx, unsigned char *out, size_t *outl, + size_t outsize); + int OSSL_FUNC_cipher_cipher(void *cctx, unsigned char *out, size_t *outl, + size_t outsize, const unsigned char *in, size_t inl); /* Cipher parameter descriptors */ - const OSSL_PARAM *OP_cipher_gettable_params(void); + const OSSL_PARAM *OSSL_FUNC_cipher_gettable_params(void); /* Cipher operation parameter descriptors */ - const OSSL_PARAM *OP_cipher_gettable_ctx_params(void); - const OSSL_PARAM *OP_cipher_settable_ctx_params(void); + const OSSL_PARAM *OSSL_FUNC_cipher_gettable_ctx_params(void); + const OSSL_PARAM *OSSL_FUNC_cipher_settable_ctx_params(void); /* Cipher parameters */ - int OP_cipher_get_params(OSSL_PARAM params[]); + int OSSL_FUNC_cipher_get_params(OSSL_PARAM params[]); /* Cipher operation parameters */ - int OP_cipher_get_ctx_params(void *cctx, OSSL_PARAM params[]); - int OP_cipher_set_ctx_params(void *cctx, const OSSL_PARAM params[]); + int OSSL_FUNC_cipher_get_ctx_params(void *cctx, OSSL_PARAM params[]); + int OSSL_FUNC_cipher_set_ctx_params(void *cctx, const OSSL_PARAM params[]); =head1 DESCRIPTION @@ -69,77 +69,77 @@ provider_query_operation() function All these "functions" have a corresponding function type definition named B<OSSL_{name}_fn>, and a helper function to retrieve the function pointer from an B<OSSL_DISPATCH> element named -B<OSSL_get_{name}>. -For example, the "function" OP_cipher_newctx() has these: +B<OSSL_FUNC_{name}>. +For example, the "function" OSSL_FUNC_cipher_newctx() has these: - typedef void *(OSSL_OP_cipher_newctx_fn)(void *provctx); - static ossl_inline OSSL_OP_cipher_newctx_fn - OSSL_get_OP_cipher_newctx(const OSSL_DISPATCH *opf); + typedef void *(OSSL_OSSL_FUNC_cipher_newctx_fn)(void *provctx); + static ossl_inline OSSL_OSSL_FUNC_cipher_newctx_fn + OSSL_FUNC_cipher_newctx(const OSSL_DISPATCH *opf); B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as macros in L<openssl-core_dispatch.h(7)>, as follows: - OP_cipher_newctx OSSL_FUNC_CIPHER_NEWCTX - OP_cipher_freectx OSSL_FUNC_CIPHER_FREECTX - OP_cipher_dupctx OSSL_FUNC_CIPHER_DUPCTX + OSSL_FUNC_cipher_newctx OSSL_FUNC_CIPHER_NEWCTX + OSSL_FUNC_cipher_freectx OSSL_FUNC_CIPHER_FREECTX + OSSL_FUNC_cipher_dupctx OSSL_FUNC_CIPHER_DUPCTX - OP_cipher_encrypt_init OSSL_FUNC_CIPHER_ENCRYPT_INIT - OP_cipher_decrypt_init OSSL_FUNC_CIPHER_DECRYPT_INIT - OP_cipher_update OSSL_FUNC_CIPHER_UPDATE - OP_cipher_final OSSL_FUNC_CIPHER_FINAL - OP_cipher_cipher OSSL_FUNC_CIPHER_CIPHER + OSSL_FUNC_cipher_encrypt_init OSSL_FUNC_CIPHER_ENCRYPT_INIT + OSSL_FUNC_cipher_decrypt_init OSSL_FUNC_CIPHER_DECRYPT_INIT + OSSL_FUNC_cipher_update OSSL_FUNC_CIPHER_UPDATE + OSSL_FUNC_cipher_final OSSL_FUNC_CIPHER_FINAL + OSSL_FUNC_cipher_cipher OSSL_FUNC_CIPHER_CIPHER - OP_cipher_get_params OSSL_FUNC_CIPHER_GET_PARAMS - OP_cipher_get_ctx_params OSSL_FUNC_CIPHER_GET_CTX_PARAMS - OP_cipher_set_ctx_params OSSL_FUNC_CIPHER_SET_CTX_PARAMS + OSSL_FUNC_cipher_get_params OSSL_FUNC_CIPHER_GET_PARAMS + OSSL_FUNC_cipher_get_ctx_params OSSL_FUNC_CIPHER_GET_CTX_PARAMS + OSSL_FUNC_cipher_set_ctx_params OSSL_FUNC_CIPHER_SET_CTX_PARAMS - OP_cipher_gettable_params OSSL_FUNC_CIPHER_GETTABLE_PARAMS - OP_cipher_gettable_ctx_params OSSL_FUNC_CIPHER_GETTABLE_CTX_PARAMS - OP_cipher_settable_ctx_params OSSL_FUNC_CIPHER_SETTABLE_CTX_PARAMS + OSSL_FUNC_cipher_gettable_params OSSL_FUNC_CIPHER_GETTABLE_PARAMS + OSSL_FUNC_cipher_gettable_ctx_params OSSL_FUNC_CIPHER_GETTABLE_CTX_PARAMS + OSSL_FUNC_cipher_settable_ctx_params OSSL_FUNC_CIPHER_SETTABLE_CTX_PARAMS A cipher algorithm implementation may not implement all of these functions. In order to be a consistent set of functions there must at least be a complete set of "encrypt" functions, or a complete set of "decrypt" functions, or a single "cipher" function. -In all cases both the OP_cipher_newctx and OP_cipher_freectx functions must be +In all cases both the OSSL_FUNC_cipher_newctx and OSSL_FUNC_cipher_freectx functions must be present. All other functions are optional. =head2 Context Management Functions -OP_cipher_newctx() should create and return a pointer to a provider side +OSSL_FUNC_cipher_newctx() should create and return a pointer to a provider side structure for holding context information during a cipher operation. A pointer to this context will be passed back in a number of the other cipher operation function calls. The parameter I<provctx> is the provider context generated during provider initialisation (see L<provider(7)>). -OP_cipher_freectx() is passed a pointer to the provider side cipher context in +OSSL_FUNC_cipher_freectx() is passed a pointer to the provider side cipher context in the I<cctx> parameter. This function should free any resources associated with that context. -OP_cipher_dupctx() should duplicate the provider side cipher context in the +OSSL_FUNC_cipher_dupctx() should duplicate the provider side cipher context in the I<cctx> parameter and return the duplicate copy. =head2 Encryption/Decryption Functions -OP_cipher_encrypt_init() initialises a cipher operation for encryption given a +OSSL_FUNC_cipher_encrypt_init() initialises a cipher operation for encryption given a newly created provider side cipher context in the I<cctx> parameter. The key to be used is given in I<key> which is I<keylen> bytes long. The IV to be used is given in I<iv> which is I<ivlen> bytes long. -OP_cipher_decrypt_init() is the same as OP_cipher_encrypt_init() except that it +OSSL_FUNC_cipher_decrypt_init() is the same as OSSL_FUNC_cipher_encrypt_init() except that it initialises the context for a decryption operation. -OP_cipher_update() is called to supply data to be encrypted/decrypted as part of +OSSL_FUNC_cipher_update() is called to supply data to be encrypted/decrypted as part of a previously initialised cipher operation. The I<cctx> parameter contains a pointer to a previously initialised provider side context. -OP_cipher_update() should encrypt/decrypt I<inl> bytes of data at the location +OSSL_FUNC_cipher_update() should encrypt/decrypt I<inl> bytes of data at the location pointed to by I<in>. The encrypted data should be stored in I<out> and the amount of data written to I<*outl> which should not exceed I<outsize> bytes. -OP_cipher_update() may be called multiple times for a single cipher operation. +OSSL_FUNC_cipher_update() may be called multiple times for a single cipher operation. It is the responsibility of the cipher implementation to handle input lengths that are not multiples of the block length. In such cases a cipher implementation will typically cache partial blocks of @@ -148,8 +148,8 @@ I<out> may be the same location as I<in> but it should not partially overlap. The same expectations apply to I<outsize> as documented for L<EVP_EncryptUpdate(3)> and L<EVP_DecryptUpdate(3)>. -OP_cipher_final() completes an encryption or decryption started through previous -OP_cipher_encrypt_init() or OP_cipher_decrypt_init(), and OP_cipher_update() +OSSL_FUNC_cipher_final() completes an encryption or decryption started through previous +OSSL_FUNC_cipher_encrypt_init() or OSSL_FUNC_cipher_decrypt_init(), and OSSL_FUNC_cipher_update() calls. The I<cctx> parameter contains a pointer to the provider side context. Any final encryption/decryption output should be written to I<out> and the @@ -157,9 +157,9 @@ amount of data written to I<*outl> which should not exceed I<outsize> bytes. The same expectations apply to I<outsize> as documented for L<EVP_EncryptFinal(3)> and L<EVP_DecryptFinal(3)>. -OP_cipher_cipher() performs encryption/decryption using the provider side cipher +OSSL_FUNC_cipher_cipher() performs encryption/decryption using the provider side cipher context in the I<cctx> parameter that should have been previously initialised via -a call to OP_cipher_encrypt_init() or OP_cipher_decrypt_init(). +a call to OSSL_FUNC_cipher_encrypt_init() or OSSL_FUNC_cipher_decrypt_init(). This should call the raw underlying cipher function without any padding. This will be invoked in the provider as a result of the application calling L<EVP_Cipher(3)>. @@ -176,20 +176,20 @@ I<outsize> bytes. See L<OSSL_PARAM(3)> for further details on the parameters structure used by these functions. -OP_cipher_get_params() gets details of the algorithm implementation +OSSL_FUNC_cipher_get_params() gets details of the algorithm implementation and stores them in I<params>. -OP_cipher_set_ctx_params() sets cipher operation parameters for the +OSSL_FUNC_cipher_set_ctx_params() sets cipher operation parameters for the provider side cipher context I<cctx> to I<params>. Any parameter settings are additional to any that were previously set. -OP_cipher_get_ctx_params() gets cipher operation details details from +OSSL_FUNC_cipher_get_ctx_params() gets cipher operation details details from the given provider side cipher context I<cctx> and stores them in I<params>. -OP_cipher_gettable_params(), OP_cipher_gettable_ctx_params(), and -OP_cipher_settable_ctx_params() all return constant B<OSSL_PARAM> arrays -as descriptors of the parameters that OP_cipher_get_params(), -OP_cipher_get_ctx_params(), and OP_cipher_set_ctx_params() can handle, +OSSL_FUNC_cipher_gettable_params(), OSSL_FUNC_cipher_gettable_ctx_params(), and +OSSL_FUNC_cipher_settable_ctx_params() all return constant B<OSSL_PARAM> arrays +as descriptors of the parameters that OSSL_FUNC_cipher_get_params(), +OSSL_FUNC_cipher_get_ctx_params(), and OSSL_FUNC_cipher_set_ctx_params() can handle, respectively. Parameters currently recognised by built-in ciphers are as follows. Not all @@ -286,7 +286,7 @@ output buffers are always the same memory location. AEAD IVs in TLSv1.2 consist of an implicit "fixed" part and an explicit part that varies with every record. Setting a TLS fixed IV changes a cipher to encrypt/decrypt TLS records. -TLS records are encrypted/decrypted using a single OP_cipher_cipher call per +TLS records are encrypted/decrypted using a single OSSL_FUNC_cipher_cipher call per record. For a record decryption the first bytes of the input buffer will be the explicit part of the IV and the final bytes of the input buffer will be the AEAD tag. @@ -307,7 +307,7 @@ write that to the output buffer, and finally add the tag onto the end of the output buffer. Whether encrypting or decrypting the value written to I<*outl> in the -OP_cipher_cipher call should be the length of the payload excluding the explicit +OSSL_FUNC_cipher_cipher call should be the length of the payload excluding the explicit IV length and the tag length. =item "ivlen" (B<OSSL_CIPHER_PARAM_AEAD_IVLEN>) <unsigned integer> @@ -414,16 +414,16 @@ Gets the result of running the "tls1multi_aad" operation. =head1 RETURN VALUES -OP_cipher_newctx() and OP_cipher_dupctx() should return the newly created +OSSL_FUNC_cipher_newctx() and OSSL_FUNC_cipher_dupctx() should return the newly created provider side cipher context, or NULL on failure. -OP_cipher_encrypt_init(), OP_cipher_decrypt_init(), OP_cipher_update(), -OP_cipher_final(), OP_cipher_cipher(), OP_cipher_get_params(), -OP_cipher_get_ctx_params() and OP_cipher_set_ctx_params() should return 1 for +OSSL_FUNC_cipher_encrypt_init(), OSSL_FUNC_cipher_decrypt_init(), OSSL_FUNC_cipher_update(), +OSSL_FUNC_cipher_final(), OSSL_FUNC_cipher_cipher(), OSSL_FUNC_cipher_get_params(), +OSSL_FUNC_cipher_get_ctx_params() and OSSL_FUNC_cipher_set_ctx_params() should return 1 for success or 0 on error. -OP_cipher_gettable_params(), OP_cipher_gettable_ctx_params() and -OP_cipher_settable_ctx_params() should return a constant B<OSSL_PARAM> +OSSL_FUNC_cipher_gettable_params(), OSSL_FUNC_cipher_gettable_ctx_params() and +OSSL_FUNC_cipher_settable_ctx_params() should return a constant B<OSSL_PARAM> array, or NULL if none is offered. =head1 SEE ALSO diff --git a/doc/man7/provider-digest.pod b/doc/man7/provider-digest.pod index 4164e34bbe..c350148471 100644 --- a/doc/man7/provider-digest.pod +++ b/doc/man7/provider-digest.pod @@ -17,31 +17,31 @@ provider-digest - The digest library E<lt>-E<gt> provider functions */ /* Context management */ - void *OP_digest_newctx(void *provctx); |