/* Key object import and export functions */
int OSSL_FUNC_keymgmt_import(void *keydata, int selection, const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types(int selection);
+ const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types_ex(void *provctx, int selection);
int OSSL_FUNC_keymgmt_export(void *keydata, int selection,
OSSL_CALLBACK *param_cb, void *cbarg);
const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types(int selection);
+ const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types_ex(void *provctx, int selection);
/* Key object duplication, a constructor */
void *OSSL_FUNC_keymgmt_dup(const void *keydata_from, int selection);
provider side key data for the OpenSSL library EVP_PKEY structure.
All "functions" mentioned here are passed as function pointers between
-F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
-B<OSSL_ALGORITHM> arrays that are returned by the provider's
+F<libcrypto> and the provider in L<OSSL_DISPATCH(3)> arrays via
+L<OSSL_ALGORITHM(3)> arrays that are returned by the provider's
provider_query_operation() function
(see L<provider-base(7)/Provider Functions>).
All these "functions" have a corresponding function type definition
named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
-function pointer from a B<OSSL_DISPATCH> element named
+function pointer from a L<OSSL_DISPATCH(3)> element named
B<OSSL_FUNC_{name}>.
For example, the "function" OSSL_FUNC_keymgmt_new() has these:
static ossl_inline OSSL_FUNC_keymgmt_new_fn
OSSL_FUNC_keymgmt_new(const OSSL_DISPATCH *opf);
-B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
+L<OSSL_DISPATCH(3)> arrays are indexed by numbers that are provided as
macros in L<openssl-core_dispatch.h(7)>, as follows:
OSSL_FUNC_keymgmt_new OSSL_FUNC_KEYMGMT_NEW
OSSL_FUNC_keymgmt_import OSSL_FUNC_KEYMGMT_IMPORT
OSSL_FUNC_keymgmt_import_types OSSL_FUNC_KEYMGMT_IMPORT_TYPES
+ OSSL_FUNC_keymgmt_import_types_ex OSSL_FUNC_KEYMGMT_IMPORT_TYPES_EX
OSSL_FUNC_keymgmt_export OSSL_FUNC_KEYMGMT_EXPORT
OSSL_FUNC_keymgmt_export_types OSSL_FUNC_KEYMGMT_EXPORT_TYPES
+ OSSL_FUNC_keymgmt_export_types_ex OSSL_FUNC_KEYMGMT_EXPORT_TYPES_EX
OSSL_FUNC_keymgmt_dup OSSL_FUNC_KEYMGMT_DUP
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 L<OSSL_PARAM(3)>, for parameters that OSSL_FUNC_keymgmt_gen_set_params()
can handle.
OSSL_FUNC_keymgmt_gen() should perform the key object generation itself, and
with the given I<keydata>, see L</Common Information Parameters>.
OSSL_FUNC_keymgmt_gettable_params() should return a constant array of
-descriptor B<OSSL_PARAM>, for parameters that OSSL_FUNC_keymgmt_get_params()
+descriptor L<OSSL_PARAM(3)>, for parameters that OSSL_FUNC_keymgmt_get_params()
can handle.
If OSSL_FUNC_keymgmt_gettable_params() is present, OSSL_FUNC_keymgmt_get_params()
with the given I<keydata>, see L</Common Information Parameters>.
OSSL_FUNC_keymgmt_settable_params() should return a constant array of
-descriptor B<OSSL_PARAM>, for parameters that OSSL_FUNC_keymgmt_set_params()
+descriptor L<OSSL_PARAM(3)>, for parameters that OSSL_FUNC_keymgmt_set_params()
can handle.
If OSSL_FUNC_keymgmt_settable_params() is present, OSSL_FUNC_keymgmt_set_params()
=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>.
+I<keydata> with values taken from the
L<OSSL_PARAM(3)> array I<params>.
OSSL_FUNC_keymgmt_export() should extract values indicated by I<selection>
-from I<keydata>, create an B<OSSL_PARAM> array with them and call
+from I<keydata>, create an L<OSSL_PARAM(3)> array with them and call
I<param_cb> with that array as well as the given I<cbarg>.
-OSSL_FUNC_keymgmt_import_types() should return a constant array of descriptor
-B<OSSL_PARAM> for data indicated by I<selection>, for parameters that
+OSSL_FUNC_keymgmt_import_types() and OSSL_FUNC_keymgmt_import_types_ex()
+should return a constant array of descriptor
+L<OSSL_PARAM(3)> for data indicated by I<selection>, for parameters that
OSSL_FUNC_keymgmt_import() can handle.
-
-OSSL_FUNC_keymgmt_export_types() should return a constant array of descriptor
-B<OSSL_PARAM> for data indicated by I<selection>, that the
+Either OSSL_FUNC_keymgmt_import_types() or OSSL_FUNC_keymgmt_import_types_ex(),
+must be implemented, if OSSL_FUNC_keymgmt_import_types_ex() is implemented, then
+it is preferred over OSSL_FUNC_keymgmt_import_types().
+Providers that are supposed to be backward compatible with OpenSSL 3.0 or 3.1
+must continue to implement OSSL_FUNC_keymgmt_import_types().
+
+OSSL_FUNC_keymgmt_export_types() and OSSL_FUNC_keymgmt_export_types_ex()
+should return a constant array of descriptor
+L<OSSL_PARAM(3)> for data indicated by I<selection>, that the
OSSL_FUNC_keymgmt_export() callback can expect to receive.
+Either OSSL_FUNC_keymgmt_export_types() or OSSL_FUNC_keymgmt_export_types_ex(),
+must be implemented, if OSSL_FUNC_keymgmt_export_types_ex() is implemented, then
+it is preferred over OSSL_FUNC_keymgmt_export_types().
+Providers that are supposed to be backward compatible with OpenSSL 3.0 or 3.1
+must continue to implement OSSL_FUNC_keymgmt_export_types().
OSSL_FUNC_keymgmt_dup() should duplicate data subsets indicated by
I<selection> or the whole key data I<keydata_from> and create a new
The value should be the maximum size that a caller should allocate to
safely store a signature (called I<sig> in L<provider-signature(7)>),
-the result of asymmmetric encryption / decryption (I<out> in
+the result of asymmetric encryption / decryption (I<out> in
L<provider-asym_cipher(7)>, a derived secret (I<secret> in
L<provider-keyexch(7)>, and similar data).
+Providers need to implement this parameter
+in order to properly support various use cases such as CMS signing.
+
Because an EVP_KEYMGMT method is always tightly bound to another method
(signature, asymmetric cipher, key exchange, ...) and must be of the
same provider, this number only needs to be synchronised with the
The value should be the number of security bits of the given key.
Bits of security is defined in SP800-57.
+=item "mandatory-digest" (B<OSSL_PKEY_PARAM_MANDATORY_DIGEST>) <UTF8 string>
+
+If there is a mandatory digest for performing a signature operation with
+keys from this keymgmt, this parameter should get its name as value.
+
+When EVP_PKEY_get_default_digest_name() queries this parameter and it's
+filled in by the implementation, its return value will be 2.
+
+If the keymgmt implementation fills in the value C<""> or C<"UNDEF">,
+L<EVP_PKEY_get_default_digest_name(3)> will place the string C<"UNDEF"> into
+its argument I<mdname>. This signifies that no digest should be specified
+with the corresponding signature operation.
+
+=item "default-digest" (B<OSSL_PKEY_PARAM_DEFAULT_DIGEST>) <UTF8 string>
+
+If there is a default digest for performing a signature operation with
+keys from this keymgmt, this parameter should get its name as value.
+
+When L<EVP_PKEY_get_default_digest_name(3)> queries this parameter and it's
+filled in by the implementation, its return value will be 1. Note that if
+B<OSSL_PKEY_PARAM_MANDATORY_DIGEST> is responded to as well,
+L<EVP_PKEY_get_default_digest_name(3)> ignores the response to this
+parameter.
+
+If the keymgmt implementation fills in the value C<""> or C<"UNDEF">,
+L<EVP_PKEY_get_default_digest_name(3)> will place the string C<"UNDEF"> into
+its argument I<mdname>. This signifies that no digest has to be specified
+with the corresponding signature operation, but may be specified as an
+option.
+
=back
=head1 RETURN VALUES
applies.
OSSL_FUNC_keymgmt_gettable_params() and OSSL_FUNC_keymgmt_settable_params()
-OSSL_FUNC_keymgmt_import_types(), OSSL_FUNC_keymgmt_export_types()
+OSSL_FUNC_keymgmt_import_types(), OSSL_FUNC_keymgmt_import_types_ex(),
+OSSL_FUNC_keymgmt_export_types(), OSSL_FUNC_keymgmt_export_types_ex()
should
-always return a constant B<OSSL_PARAM> array.
+always return a constant L<OSSL_PARAM(3)> array.
=head1 SEE ALSO
+L<EVP_PKEY_get_size(3)>,
+L<EVP_PKEY_get_bits(3)>,
+L<EVP_PKEY_get_security_bits(3)>,
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)>,
The KEYMGMT interface was introduced in OpenSSL 3.0.
+Functions OSSL_FUNC_keymgmt_import_types_ex(), and OSSL_FUNC_keymgmt_export_types_ex()
+were added with OpenSSL 3.2.
+
=head1 COPYRIGHT
-Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
projects / openssl.git / blobdiff