diff options
Diffstat (limited to 'doc/man7/provider-keyexch.pod')
| -rw-r--r-- | doc/man7/provider-keyexch.pod | 88 |
1 files changed, 44 insertions, 44 deletions
diff --git a/doc/man7/provider-keyexch.pod b/doc/man7/provider-keyexch.pod index 2dcde351e6..f69979aa13 100644 --- a/doc/man7/provider-keyexch.pod +++ b/doc/man7/provider-keyexch.pod @@ -18,21 +18,21 @@ provider-keyexch - The keyexch library E<lt>-E<gt> provider functions */ /* Context management */ - void *OP_keyexch_newctx(void *provctx); - void OP_keyexch_freectx(void *ctx); - void *OP_keyexch_dupctx(void *ctx); + void *OSSL_FUNC_keyexch_newctx(void *provctx); + void OSSL_FUNC_keyexch_freectx(void *ctx); + void *OSSL_FUNC_keyexch_dupctx(void *ctx); /* Shared secret derivation */ - int OP_keyexch_init(void *ctx, void *provkey); - int OP_keyexch_set_peer(void *ctx, void *provkey); - int OP_keyexch_derive(void *ctx, unsigned char *secret, size_t *secretlen, - size_t outlen); + int OSSL_FUNC_keyexch_init(void *ctx, void *provkey); + int OSSL_FUNC_keyexch_set_peer(void *ctx, void *provkey); + int OSSL_FUNC_keyexch_derive(void *ctx, unsigned char *secret, size_t *secretlen, + size_t outlen); /* Key Exchange parameters */ - int OP_keyexch_set_ctx_params(void *ctx, const OSSL_PARAM params[]); - const OSSL_PARAM *OP_keyexch_settable_ctx_params(void); - int OP_keyexch_get_ctx_params(void *ctx, OSSL_PARAM params[]); - const OSSL_PARAM *OP_keyexch_gettable_ctx_params(void); + int OSSL_FUNC_keyexch_set_ctx_params(void *ctx, const OSSL_PARAM params[]); + const OSSL_PARAM *OSSL_FUNC_keyexch_settable_ctx_params(void); + int OSSL_FUNC_keyexch_get_ctx_params(void *ctx, OSSL_PARAM params[]); + const OSSL_PARAM *OSSL_FUNC_keyexch_gettable_ctx_params(void); =head1 DESCRIPTION @@ -53,32 +53,32 @@ 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_keyexch_newctx() has these: +B<OSSL_FUNC_{name}>. +For example, the "function" OSSL_FUNC_keyexch_newctx() has these: - typedef void *(OSSL_OP_keyexch_newctx_fn)(void *provctx); - static ossl_inline OSSL_OP_keyexch_newctx_fn - OSSL_get_OP_keyexch_newctx(const OSSL_DISPATCH *opf); + typedef void *(OSSL_FUNC_keyexch_newctx_fn)(void *provctx); + static ossl_inline OSSL_FUNC_keyexch_newctx_fn + OSSL_FUNC_keyexch_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_keyexch_newctx OSSL_FUNC_KEYEXCH_NEWCTX - OP_keyexch_freectx OSSL_FUNC_KEYEXCH_FREECTX - OP_keyexch_dupctx OSSL_FUNC_KEYEXCH_DUPCTX + OSSL_FUNC_keyexch_newctx OSSL_FUNC_KEYEXCH_NEWCTX + OSSL_FUNC_keyexch_freectx OSSL_FUNC_KEYEXCH_FREECTX + OSSL_FUNC_keyexch_dupctx OSSL_FUNC_KEYEXCH_DUPCTX - OP_keyexch_init OSSL_FUNC_KEYEXCH_INIT - OP_keyexch_set_peer OSSL_FUNC_KEYEXCH_SET_PEER - OP_keyexch_derive OSSL_FUNC_KEYEXCH_DERIVE + OSSL_FUNC_keyexch_init OSSL_FUNC_KEYEXCH_INIT + OSSL_FUNC_keyexch_set_peer OSSL_FUNC_KEYEXCH_SET_PEER + OSSL_FUNC_keyexch_derive OSSL_FUNC_KEYEXCH_DERIVE - OP_keyexch_set_ctx_params OSSL_FUNC_KEYEXCH_SET_CTX_PARAMS - OP_keyexch_settable_ctx_params OSSL_FUNC_KEYEXCH_SETTABLE_CTX_PARAMS - OP_keyexch_get_ctx_params OSSL_FUNC_KEYEXCH_GET_CTX_PARAMS - OP_keyexch_gettable_ctx_params OSSL_FUNC_KEYEXCH_GETTABLE_CTX_PARAMS + OSSL_FUNC_keyexch_set_ctx_params OSSL_FUNC_KEYEXCH_SET_CTX_PARAMS + OSSL_FUNC_keyexch_settable_ctx_params OSSL_FUNC_KEYEXCH_SETTABLE_CTX_PARAMS + OSSL_FUNC_keyexch_get_ctx_params OSSL_FUNC_KEYEXCH_GET_CTX_PARAMS + OSSL_FUNC_keyexch_gettable_ctx_params OSSL_FUNC_KEYEXCH_GETTABLE_CTX_PARAMS A key exchange algorithm implementation may not implement all of these functions. In order to be a consistent set of functions a provider must implement -OP_keyexch_newctx, OP_keyexch_freectx, OP_keyexch_init and OP_keyexch_derive. +OSSL_FUNC_keyexch_newctx, OSSL_FUNC_keyexch_freectx, OSSL_FUNC_keyexch_init and OSSL_FUNC_keyexch_derive. All other functions are optional. A key exchange algorithm must also implement some mechanism for generating, @@ -87,29 +87,29 @@ See L<provider-keymgmt(7)> for further details. =head2 Context Management Functions -OP_keyexch_newctx() should create and return a pointer to a provider side +OSSL_FUNC_keyexch_newctx() should create and return a pointer to a provider side structure for holding context information during a key exchange operation. A pointer to this context will be passed back in a number of the other key exchange operation function calls. The parameter I<provctx> is the provider context generated during provider initialisation (see L<provider(7)>). -OP_keyexch_freectx() is passed a pointer to the provider side key exchange +OSSL_FUNC_keyexch_freectx() is passed a pointer to the provider side key exchange context in the I<ctx> parameter. This function should free any resources associated with that context. -OP_keyexch_dupctx() should duplicate the provider side key exchange context in +OSSL_FUNC_keyexch_dupctx() should duplicate the provider side key exchange context in the I<ctx> parameter and return the duplicate copy. =head2 Shared Secret Derivation Functions -OP_keyexch_init() initialises a key exchange operation given a provider side key +OSSL_FUNC_keyexch_init() initialises a key exchange operation given a provider side key exchange 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_keyexch_set_peer() is called to supply the peer's public key (in the +OSSL_FUNC_keyexch_set_peer() is called to supply the peer's public key (in the I<provkey> parameter) to be used when deriving the shared secret. It is also passed a previously initialised key exchange context in the I<ctx> parameter. @@ -117,7 +117,7 @@ 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_keyexch_derive() performs the actual key exchange itself by deriving a shared +OSSL_FUNC_keyexch_derive() performs the actual key exchange itself by deriving a shared secret. A previously initialised key exchange context is passed in the I<ctx> parameter. @@ -129,24 +129,24 @@ written to I<*secretlen>. =head2 Key Exchange Parameters Functions -OP_keyexch_set_ctx_params() sets key exchange parameters associated with the +OSSL_FUNC_keyexch_set_ctx_params() sets key exchange parameters associated with the given provider side key exchange context I<ctx> to I<params>, see L</Common Key Exchange parameters>. Any parameter settings are additional to any that were previously set. -OP_keyexch_get_ctx_params() gets key exchange parameters associated with the +OSSL_FUNC_keyexch_get_ctx_params() gets key exchange parameters associated with the given provider side key exchange context I<ctx> into I<params>, see L</Common Key Exchange parameters>. -OP_keyexch_settable_ctx_params() yields a constant B<OSSL_PARAM> array that +OSSL_FUNC_keyexch_settable_ctx_params() yields a constant B<OSSL_PARAM> array that describes the settable parameters, i.e. parameters that can be used with OP_signature_set_ctx_params(). -If OP_keyexch_settable_ctx_params() is present, OP_keyexch_set_ctx_params() must +If OSSL_FUNC_keyexch_settable_ctx_params() is present, OSSL_FUNC_keyexch_set_ctx_params() must also be present, and vice versa. -Similarly, OP_keyexch_gettable_ctx_params() yields a constant B<OSSL_PARAM> +Similarly, OSSL_FUNC_keyexch_gettable_ctx_params() yields a constant B<OSSL_PARAM> array that describes the gettable parameters, i.e. parameters that can be handled by OP_signature_get_ctx_params(). -If OP_keyexch_gettable_ctx_params() is present, OP_keyexch_get_ctx_params() must +If OSSL_FUNC_keyexch_gettable_ctx_params() is present, OSSL_FUNC_keyexch_get_ctx_params() must also be present, and vice versa. See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor. @@ -155,7 +155,7 @@ Notice that not all settable parameters are also gettable, and vice versa. =head2 Common Key Exchange parameters See L<OSSL_PARAM(3)> for further details on the parameters structure used by -the OP_keyexch_set_ctx_params() and OP_keyexch_get_ctx_params() functions. +the OSSL_FUNC_keyexch_set_ctx_params() and OSSL_FUNC_keyexch_get_ctx_params() functions. Common parameters currently recognised by built-in key exchange algorithms are as follows. @@ -177,14 +177,14 @@ possible secret size. =head1 RETURN VALUES -OP_keyexch_newctx() and OP_keyexch_dupctx() should return the newly created +OSSL_FUNC_keyexch_newctx() and OSSL_FUNC_keyexch_dupctx() should return the newly created provider side key exchange context, or NULL on failure. -OP_keyexch_init(), OP_keyexch_set_peer(), OP_keyexch_derive(), -OP_keyexch_set_params(), and OP_keyexch_get_params() should return 1 for success +OSSL_FUNC_keyexch_init(), OSSL_FUNC_keyexch_set_peer(), OSSL_FUNC_keyexch_derive(), +OSSL_FUNC_keyexch_set_params(), and OSSL_FUNC_keyexch_get_params() should return 1 for success or 0 on error. -OP_keyexch_settable_ctx_params() and OP_keyexch_gettable_ctx_params() should +OSSL_FUNC_keyexch_settable_ctx_params() and OSSL_FUNC_keyexch_gettable_ctx_params() should always return a constant B<OSSL_PARAM> array. =head1 SEE ALSO |