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);
/* Key object content checks */
int OP_keymgmt_has(void *keydata, int selection);
+ int OP_keymgmt_match(const void *keydata1, const void *keydata2,
+ int selection);
/* Discovery of supported operations */
const char *OP_keymgmt_query_operation_name(int operation_id);
OSSL_CALLBACK *param_cb, void *cbarg);
const OSSL_PARAM *OP_keymgmt_export_types(int selection);
+ /* Key object copy */
+ int OP_keymgmt_copy(void *keydata_to, const void *keydata_from, int selection);
+
/* Key object validation */
int OP_keymgmt_validate(void *keydata, int selection);
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
OP_keymgmt_has OSSL_FUNC_KEYMGMT_HAS
OP_keymgmt_validate OSSL_FUNC_KEYMGMT_VALIDATE
+ OP_keymgmt_match OSSL_FUNC_KEYMGMT_MATCH
OP_keymgmt_import OSSL_FUNC_KEYMGMT_IMPORT
OP_keymgmt_import_types OSSL_FUNC_KEYMGMT_IMPORT_TYPES
OP_keymgmt_export OSSL_FUNC_KEYMGMT_EXPORT
OP_keymgmt_export_types OSSL_FUNC_KEYMGMT_EXPORT_TYPES
+ OP_keymgmt_copy OSSL_FUNC_KEYMGMT_COPY
=head2 Key Objects
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.
-=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.
+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>
+
+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
OP_keymgmt_get_params() should extract information data associated
-with the given I<keydata>, see L</Information Parameters>.
+with the given I<keydata>, see L</Common Information Parameters>.
OP_keymgmt_gettable_params() should return a constant array of
descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_get_params()
must also be present, and vice versa.
OP_keymgmt_set_params() should update information data associated
-with the given I<keydata>, see L</Information Parameters>.
+with the given I<keydata>, see L</Common Information Parameters>.
OP_keymgmt_settable_params() should return a constant array of
descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_set_params()
for short) is expected to check that the pairwise consistency of
I<keydata> is valid.
-=head2 Key Object Import and Export Functions
+OP_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
OP_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
OP_keymgmt_export() callback can expect to receive.
-=head2 Built-in RSA Import/Export Types
-
-The following Import/Export types are available for the built-in RSA algorithm:
-
-=over 4
-
-=item "n" (B<OSSL_PKEY_PARAM_RSA_N>) <integer>
-
-The RSA "n" value.
-
-=item "e" (B<OSSL_PKEY_PARAM_RSA_E>) <integer>
-
-The RSA "e" value.
-
-=item "d" (B<OSSL_PKEY_PARAM_RSA_D>) <integer>
-
-The RSA "d" value.
-
-=item "rsa-factor" (B<OSSL_PKEY_PARAM_RSA_FACTOR>) <integer>
-
-An RSA factor. In 2 prime RSA these are often known as "p" or "q". This value
-may be repeated up to 10 times in a single key.
-
-=item "rsa-exponent" (B<OSSL_PKEY_PARAM_RSA_EXPONENT>) <integer>
-
-An RSA CRT (Chinese Remainder Theorem) exponent. This value may be repeated up
-to 10 times in a single key.
-
-=item "rsa-coefficient" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT>) <integer>
-
-An RSA CRT (Chinese Remainder Theorem) coefficient. This value may be repeated
-up to 9 times in a single key.
-
-=back
-
-=head2 Built-in DSA and Diffie-Hellman Import/Export Types
+OP_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.
-The following Import/Export types are available for the built-in DSA and
-Diffie-Hellman algorithms:
-
-=over 4
-
-=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <integer> or <octet string>
-
-The public key value.
-
-=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <integer> or <octet string>
-
-The private key value.
-
-=item "p" (B<OSSL_PKEY_PARAM_FFC_P>) <integer>
-
-A DSA or Diffie-Hellman "p" value.
-
-=item "q" (B<OSSL_PKEY_PARAM_FFC_Q>) <integer>
-
-A DSA or Diffie-Hellman "q" value.
-
-=item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <integer>
-
-A DSA or Diffie-Hellman "g" value.
-
-=back
-
-=head2 Built-in X25519, X448, ED25519 and ED448 Import/Export Types
-
-The following Import/Export types are available for the built-in X25519, X448,
-ED25519 and X448 algorithms:
-
-=over 4
-
-=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>
-
-The public key value.
-
-=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <octet string>
-
-The private key value.
-
-=back
-
-=head2 Information Parameters
+=head2 Common Information Parameters
See L<OSSL_PARAM(3)> for further details on the parameters structure.
-Parameters currently recognised by built-in keymgmt algorithms
-are as follows.
-Not all parameters are relevant to, or are understood by all keymgmt
-algorithms:
+Common information parameters currently recognised by all built-in
+keymgmt algorithms are as follows:
=over 4
The value should be the number of security bits of the given key.
Bits of security is defined in SP800-57.
-=item "use-cofactor-flag" (B<OSSL_PKEY_PARAM_USE_COFACTOR_FLAG>,
-B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH>) <integer>
-
-The value should be either 1 or 0, to respectively enable or disable
-use of the cofactor in operations using this key.
-
-In the context of a key that can be used to perform an Elliptic Curve
-Diffie-Hellman key exchange, this parameter can be used to mark a requirement
-for using the Cofactor Diffie-Hellman (CDH) variant of the key exchange
-algorithm.
-
-See also L<provider-keyexch(7)> for the related
-B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE> parameter that can be set on a
-per-operation basis.
-
=back
=head1 RETURN VALUES
=head1 SEE ALSO
-L<provider(7)>
+L<provider(7)>,
+L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>, L<EVP_PKEY-ED25519(7)>,
+L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-EC(7)>, L<EVP_PKEY-RSA(7)>,
+L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>
=head1 HISTORY
projects / openssl.git / blobdiff