void OSSL_FUNC_keymgmt_free(void *keydata);
/* Generation, a more complex constructor */
- void *OSSL_FUNC_keymgmt_gen_init(void *provctx, int selection);
+ void *OSSL_FUNC_keymgmt_gen_init(void *provctx, int selection,
+ const OSSL_PARAM params[]);
int OSSL_FUNC_keymgmt_gen_set_template(void *genctx, void *template);
int OSSL_FUNC_keymgmt_gen_set_params(void *genctx, const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_keymgmt_gen_settable_params(void *genctx,
OSSL_CALLBACK *param_cb, void *cbarg);
const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types(int selection);
- /* Key object copy */
- int OSSL_FUNC_keymgmt_copy(void *keydata_to, const void *keydata_from, int selection);
+ /* Key object duplication, a constructor */
+ void *OSSL_FUNC_keymgmt_dup(const void *keydata_from, int selection);
/* Key object validation */
int OSSL_FUNC_keymgmt_validate(const void *keydata, int selection, int checktype);
(see L<provider-base(7)/Provider Functions>).
All these "functions" have a corresponding function type definition
-named B<OSSL_{name}_fn>, and a helper function to retrieve the
+named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
function pointer from a B<OSSL_DISPATCH> element named
B<OSSL_FUNC_{name}>.
For example, the "function" OSSL_FUNC_keymgmt_new() has these:
OSSL_FUNC_keymgmt_export OSSL_FUNC_KEYMGMT_EXPORT
OSSL_FUNC_keymgmt_export_types OSSL_FUNC_KEYMGMT_EXPORT_TYPES
- OSSL_FUNC_keymgmt_copy OSSL_FUNC_KEYMGMT_COPY
+ OSSL_FUNC_keymgmt_dup OSSL_FUNC_KEYMGMT_DUP
=head2 Key Objects
regardless of their more granular classification.
=for comment This should used by EVP functions such as
-EVP_PKEY_copy_parameters() and EVP_PKEY_cmp_parameters()
+EVP_PKEY_copy_parameters() and EVP_PKEY_parameters_eq()
This is a combination of B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> and
B<OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS>.
The exact interpretation of those bits or how they combine is left to
each function where you can specify a selector.
-=for comment One might think that a combination of bits means that all
-the selected data subsets must be considered, but then you have to
-consider that when comparing key objects (future function), an
-implementation might opt to not compare the private key if it has
-compared the public key, since a match of one half implies a match of
-the other half.
+It's left to the provider implementation to decide what is reasonable
+to do with regards to received selector bits and how to do it.
+Among others, an implementation of OSSL_FUNC_keymgmt_match() might opt
+to not compare the private half if it has compared the public half,
+since a match of one half implies a match of the other half.
=head2 Constructing and Destructing Functions
OSSL_FUNC_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.
+The I<params>, if not NULL, should be set on the context in a manner similar to
+using OSSL_FUNC_keymgmt_set_params().
OSSL_FUNC_keymgmt_gen_set_template() should add I<template> to the context
I<genctx>. The I<template> is assumed to be a key object constructed
I<params> in the key object generation context I<genctx>.
OSSL_FUNC_keymgmt_gen_settable_params() should return a constant array of
-descriptor B<OSSL_PARAM>, for parameters that OSSL_FUNC_keymgmt_gen_set_params()
+descriptor B<OSSL_PARAM>, for parameters that OSSL_FUNC_keymgmt_gen_set_params()
can handle.
OSSL_FUNC_keymgmt_gen() should perform the key object generation itself, and
Outside the provider, this reference is simply an array of bytes.
At least one of OSSL_FUNC_keymgmt_new(), OSSL_FUNC_keymgmt_gen() and
-OSSL_FUNC_keymgmt_load() are mandatory, as well as OSSL_FUNC_keymgmt_free().
-Additionally, if OSSL_FUNC_keymgmt_gen() is present, OSSL_FUNC_keymgmt_gen_init()
-and OSSL_FUNC_keymgmt_gen_cleanup() must be present as well.
+OSSL_FUNC_keymgmt_load() are mandatory, as well as OSSL_FUNC_keymgmt_free() and
+OSSL_FUNC_keymgmt_has(). Additionally, if OSSL_FUNC_keymgmt_gen() is present,
+OSSL_FUNC_keymgmt_gen_init() and OSSL_FUNC_keymgmt_gen_cleanup() must be
+present as well.
=head2 Key Object Information Functions
of data indicated by the I<selector>. A combination of several
selector bits must consider all those subsets, not just one. An
implementation is, however, free to consider an empty subset of data
-to still be a valid subset.
+to still be a valid subset. For algorithms where some selection is
+not meaningful such as B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> for
+RSA keys the function should just return 1 as the selected subset
+is not really missing in the key.
OSSL_FUNC_keymgmt_validate() should check if the I<keydata> contains valid
data subsets indicated by I<selection>. Some combined selections of
B<OSSL_KEYMGMT_VALIDATE_FULL_CHECK> and B<OSSL_KEYMGMT_VALIDATE_QUICK_CHECK>.
The interpretation of how much checking is performed in a full check versus a
quick check is key type specific. Some providers may have no distinction
-between a full check and a quick check.
+between a full check and a quick check. For algorithms where some selection is
+not meaningful such as B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> for
+RSA keys the function should just return 1 as there is nothing to validate for
+that selection.
OSSL_FUNC_keymgmt_match() should check if the data subset indicated by
I<selection> in I<keydata1> and I<keydata2> match. It is assumed that
the caller has ensured that I<keydata1> and I<keydata2> are both owned
by the implementation of this function.
-=head2 Key Object Import, Export and Copy Functions
+=head2 Key Object Import, Export and Duplication Functions
OSSL_FUNC_keymgmt_import() should import data indicated by I<selection> into
I<keydata> with values taken from the B<OSSL_PARAM> array I<params>.
B<OSSL_PARAM> for data indicated by I<selection>, that the
OSSL_FUNC_keymgmt_export() callback can expect to receive.
-OSSL_FUNC_keymgmt_copy() should copy data subsets indicated by I<selection>
-from I<keydata_from> to I<keydata_to>. It is assumed that the caller
-has ensured that I<keydata_to> and I<keydata_from> are both owned by
-the implementation of this function.
+OSSL_FUNC_keymgmt_dup() should duplicate data subsets indicated by
+I<selection> or the whole key data I<keydata_from> and create a new
+provider side key object with the data.
=head2 Common Information Parameters
=head1 RETURN VALUES
-OSSL_FUNC_keymgmt_new() should return a valid reference to the newly created provider
-side key object, or NULL on failure.
+OSSL_FUNC_keymgmt_new() and OSSL_FUNC_keymgmt_dup() should return a valid
+reference to the newly created provider side key object, or NULL on failure.
OSSL_FUNC_keymgmt_import(), OSSL_FUNC_keymgmt_export(), OSSL_FUNC_keymgmt_get_params() and
OSSL_FUNC_keymgmt_set_params() should return 1 for success or 0 on error.
projects / openssl.git / blobdiff