diff options
author | Richard Levitte <levitte@openssl.org> | 2019-10-26 13:00:56 +0200 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2020-03-12 10:43:58 +0100 |
commit | 1a5632e0dcc5cdc2b3440694cb50e04994bb1391 (patch) | |
tree | 66fdd6c32a5e57a60e2afcc2377bf058ced1d711 /doc | |
parent | 1c725f463edf0a5b33a2a93e9a43a9ab682af7db (diff) |
CORE: Add the key object generator libcrypto<->provider interface
We introduce these dispatched functions:
- OP_keymgmt_gen_init() to initialize the key object generation.
- OP_keymgmt_gen_set_template() to set a template for key object
generation. The template is another key object, for example one
with domain parameters.
- OP_keymgmt_gen_set_params() to set other key object generation
parameters.
- OP_keymgmt_gen_settable_params() to find out what settable
parameters there are.
- OP_keymgmt_gen() to perform the key object generation.
- OP_keymgmt_gen_cleanup() to clean up the key object generation.
Internal function for easy and consistent use of these ddispatched
functions are added.
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/10289)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man7/provider-keymgmt.pod | 53 |
1 files changed, 48 insertions, 5 deletions
diff --git a/doc/man7/provider-keymgmt.pod b/doc/man7/provider-keymgmt.pod index 0a2768b5db..59e538dbac 100644 --- a/doc/man7/provider-keymgmt.pod +++ b/doc/man7/provider-keymgmt.pod @@ -18,6 +18,13 @@ provider-keymgmt - The KEYMGMT library E<lt>-E<gt> provider functions void *OP_keymgmt_new(void *provctx); void OP_keymgmt_free(void *keydata); + void *OP_keymgmt_gen_init(void *provctx, int selection); + int OP_keymgmt_gen_set_template(void *genctx, void *template); + int OP_keymgmt_gen_set_params(void *genctx, const OSSL_PARAM params[]); + const OSSL_PARAM *OP_keymgmt_gen_settable_params(void *provctx); + void *OP_keymgmt_gen(void *genctx, OSSL_CALLBACK *cb, void *cbarg); + void OP_keymgmt_gen_cleanup(void *genctx); + /* Key object information */ int OP_keymgmt_get_params(void *keydata, OSSL_PARAM params[]); const OSSL_PARAM *OP_keymgmt_gettable_params(void); @@ -80,6 +87,13 @@ macros in L<openssl-core_numbers.h(7)>, as follows: OP_keymgmt_new OSSL_FUNC_KEYMGMT_NEW OP_keymgmt_free OSSL_FUNC_KEYMGMT_FREE + OP_keymgmt_gen_init OSSL_FUNC_KEYMGMT_GEN_INIT + OP_keymgmt_gen_set_template OSSL_FUNC_KEYMGMT_GEN_SET_TEMPLATE + OP_keymgmt_gen_set_params OSSL_FUNC_KEYMGMT_GEN_SET_PARAMS + OP_keymgmt_gen_settable_params OSSL_FUNC_KEYMGMT_GEN_SETTABLE_PARAMS + OP_keymgmt_gen OSSL_FUNC_KEYMGMT_GEN + OP_keymgmt_gen_cleanup OSSL_FUNC_KEYMGMT_GEN_CLEANUP + OP_keymgmt_get_params OSSL_FUNC_KEYMGMT_GET_PARAMS OP_keymgmt_gettable_params OSSL_FUNC_KEYMGMT_GETTABLE_PARAMS OP_keymgmt_set_params OSSL_FUNC_KEYMGMT_SET_PARAMS @@ -193,12 +207,41 @@ key object, but that is not mandatory. OP_keymgmt_free() should free the passed I<keydata>. -The constructor and destructor are mandatory, a KEYMGMT implementation -without them will not be accepted. +OP_keymgmt_gen_init(), OP_keymgmt_gen_set_template(), +OP_keymgmt_gen_set_params(), OP_keymgmt_gen_settable_params(), +OP_keymgmt_gen() and OP_keymgmt_gen_cleanup() work together as a more +elaborate context based key object constructor. + +OP_keymgmt_gen_init() should create the key object generation context +and initialize it with I<selections>, which will determine what kind +of contents the key object to be generated should get. + +OP_keymgmt_gen_set_template() should add I<template> to the context +I<genctx>. The I<template> is assumed to be a key object constructed +with the same KEYMGMT, and from which content that the implementation +chooses can be used as a template for the key object to be generated. +Typically, the generation of a DSA or DH key would get the domain +parameters from this I<template>. + +OP_keymgmt_gen_set_params() should set additional parameters from +I<params> in the key object generation context I<genctx>. + +OP_keymgmt_gen_settable_params() should return a constant array of +descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_gen_set_params() +can handle. + +OP_keymgmt_gen() should perform the key object generation itself, and +return the result. The callback I<cb> should be called at regular +intervals with indications on how the key object generation +progresses. + +OP_keymgmt_gen_cleanup() should clean up and free the key object +generation context I<genctx> -=for comment when new constructors appear, it's sufficient if only one -of them is present. The remark above will have to change to reflect -that. +At least one of OP_keymgmt_new() and OP_keymgmt_gen() are mandatory, +as well as OP_keymgmt_free(). Additionally, if OP_keymgmt_gen() is +present, OP_keymgmt_gen_init() and OP_keymgmt_gen_cleanup() must be +present as well. =head2 Key Object Information Functions |