diff options
author | Richard Levitte <levitte@openssl.org> | 2019-07-05 00:31:42 +0200 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2019-07-22 06:17:38 +0200 |
commit | a94a3e0d91378b5c478f687a0dbc51914d4ed497 (patch) | |
tree | a649885fc1d6560a2928c610d9adaaf4ec6dbfcc /doc/man3 | |
parent | 7312ef3fc4a7d391272f3ba8075eabf81a229ad2 (diff) |
Add basic EVP_KEYMGMT API and libcrypto <-> provider interface
The idea with the key management "operation" is to support the
following set of functionality:
- Key domain parameter generation
- Key domain parameter import
- Key domain parameter export
- Key generation
- Key import
- Key export
- Key loading (HSM / hidden key support)
With that set of function, we can support handling domain parameters
on one provider, key handling on another, and key usage on a third,
with transparent export / import of applicable data. Of course, if a
provider doesn't offer export / import functionality, then all
operations surrounding a key must be performed with the same
provider.
This method also avoids having to do anything special with legacy
assignment of libcrypto key structures, i.e. EVP_PKEY_assign_RSA().
They will simply be used as keys to be exported from whenever they are
used with provider based operations.
This change only adds the EVP_KEYMGMT API and the libcrypto <->
provider interface. Further changes will integrate them into existing
libcrypto functionality.
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9312)
Diffstat (limited to 'doc/man3')
-rw-r--r-- | doc/man3/EVP_KEYMGMT.pod | 84 |
1 files changed, 84 insertions, 0 deletions
diff --git a/doc/man3/EVP_KEYMGMT.pod b/doc/man3/EVP_KEYMGMT.pod new file mode 100644 index 0000000000..ab209da768 --- /dev/null +++ b/doc/man3/EVP_KEYMGMT.pod @@ -0,0 +1,84 @@ +=pod + +=head1 NAME + +EVP_KEYMGMT, +EVP_KEYMGMT_fetch, +EVP_KEYMGMT_up_ref, +EVP_KEYMGMT_free, +EVP_KEYMGMT_provider +- EVP key management routines + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + typedef struct evp_keymgmt_st EVP_KEYMGMT; + + EVP_KEYMGMT *EVP_KEYMGMT_fetch(OPENSSL_CTX *ctx, const char *algorithm, + const char *properties); + int EVP_KEYMGMT_up_ref(EVP_KEYMGMT *keymgmt); + void EVP_KEYMGMT_free(EVP_KEYMGMT *keymgmt); + const OSSL_PROVIDER *EVP_KEYMGMT_provider(const EVP_KEYMGMT *keymgmt); + +=head1 DESCRIPTION + +B<EVP_KEYMGMT> is a method object that represents key management +implementations for different cryptographic algorithms. +This method object provides functionality to have providers import key +material from the outside, as well as export key material to the +outside. +Most of the functionality can only be used internally and has no +public interface, this object is simply passed into other functions +when needed. + +EVP_KEYMGMT_fetch() looks for an algorithm within the provider that +has been loaded into the B<OPENSSL_CTX> given by I<ctx>, having the +name given by I<algorithm> and the properties given by I<properties>. + +EVP_KEYMGMT_up_ref() increments the reference count for the given +B<EVP_KEYMGMT> I<keymgmt>. + +EVP_KEYMGMT_free() decrements the reference count for the given +B<EVP_KEYMGMT> I<keymgmt>, and when the count reaches zero, frees it. + +EVP_KEYMGMT_provider() returns the provider that has this particular +implementation. + +=head1 NOTES + +EVP_KEYMGMT_fetch() may be called implicitly by other fetching +functions, using the same library context and properties. +Any other API that uses keys will typically do this. + +=head1 RETURN VALUES + +EVP_KEYMGMT_fetch() returns a pointer to the key management +implementation represented by an EVP_KEYMGMT object, or NULL on +error. + +EVP_KEYMGMT_up_ref() returns 1 on success, or 0 on error. + +EVP_KEYMGMT_free() doesn't return any value. + +EVP_KEYMGMT_provider() returns a pointer to a provider object, or NULL +on error. + +=head1 SEE ALSO + +L<EVP_MD_fetch(3)>, L<OPENSSL_CTX(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2019 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 +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut |