| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | EVP_KEYMGMT,
|
|---|
| 6 | EVP_KEYMGMT_fetch,
|
|---|
| 7 | EVP_KEYMGMT_up_ref,
|
|---|
| 8 | EVP_KEYMGMT_free,
|
|---|
| 9 | EVP_KEYMGMT_get0_provider,
|
|---|
| 10 | EVP_KEYMGMT_is_a,
|
|---|
| 11 | EVP_KEYMGMT_get0_description,
|
|---|
| 12 | EVP_KEYMGMT_get0_name,
|
|---|
| 13 | EVP_KEYMGMT_do_all_provided,
|
|---|
| 14 | EVP_KEYMGMT_names_do_all,
|
|---|
| 15 | EVP_KEYMGMT_gettable_params,
|
|---|
| 16 | EVP_KEYMGMT_settable_params,
|
|---|
| 17 | EVP_KEYMGMT_gen_settable_params
|
|---|
| 18 | - EVP key management routines
|
|---|
| 19 |
|
|---|
| 20 | =head1 SYNOPSIS
|
|---|
| 21 |
|
|---|
| 22 | #include <openssl/evp.h>
|
|---|
| 23 |
|
|---|
| 24 | typedef struct evp_keymgmt_st EVP_KEYMGMT;
|
|---|
| 25 |
|
|---|
| 26 | EVP_KEYMGMT *EVP_KEYMGMT_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,
|
|---|
| 27 | const char *properties);
|
|---|
| 28 | int EVP_KEYMGMT_up_ref(EVP_KEYMGMT *keymgmt);
|
|---|
| 29 | void EVP_KEYMGMT_free(EVP_KEYMGMT *keymgmt);
|
|---|
| 30 | const OSSL_PROVIDER *EVP_KEYMGMT_get0_provider(const EVP_KEYMGMT *keymgmt);
|
|---|
| 31 | int EVP_KEYMGMT_is_a(const EVP_KEYMGMT *keymgmt, const char *name);
|
|---|
| 32 | const char *EVP_KEYMGMT_get0_name(const EVP_KEYMGMT *keymgmt);
|
|---|
| 33 | const char *EVP_KEYMGMT_get0_description(const EVP_KEYMGMT *keymgmt);
|
|---|
| 34 |
|
|---|
| 35 | void EVP_KEYMGMT_do_all_provided(OSSL_LIB_CTX *libctx,
|
|---|
| 36 | void (*fn)(EVP_KEYMGMT *keymgmt, void *arg),
|
|---|
| 37 | void *arg);
|
|---|
| 38 | int EVP_KEYMGMT_names_do_all(const EVP_KEYMGMT *keymgmt,
|
|---|
| 39 | void (*fn)(const char *name, void *data),
|
|---|
| 40 | void *data);
|
|---|
| 41 | const OSSL_PARAM *EVP_KEYMGMT_gettable_params(const EVP_KEYMGMT *keymgmt);
|
|---|
| 42 | const OSSL_PARAM *EVP_KEYMGMT_settable_params(const EVP_KEYMGMT *keymgmt);
|
|---|
| 43 | const OSSL_PARAM *EVP_KEYMGMT_gen_settable_params(const EVP_KEYMGMT *keymgmt);
|
|---|
| 44 |
|
|---|
| 45 | =head1 DESCRIPTION
|
|---|
| 46 |
|
|---|
| 47 | B<EVP_KEYMGMT> is a method object that represents key management
|
|---|
| 48 | implementations for different cryptographic algorithms.
|
|---|
| 49 | This method object provides functionality to have providers import key
|
|---|
| 50 | material from the outside, as well as export key material to the
|
|---|
| 51 | outside.
|
|---|
| 52 | Most of the functionality can only be used internally and has no
|
|---|
| 53 | public interface, this object is simply passed into other functions
|
|---|
| 54 | when needed.
|
|---|
| 55 |
|
|---|
| 56 | EVP_KEYMGMT_fetch() looks for an algorithm within the provider that
|
|---|
| 57 | has been loaded into the B<OSSL_LIB_CTX> given by I<ctx>, having the
|
|---|
| 58 | name given by I<algorithm> and the properties given by I<properties>.
|
|---|
| 59 |
|
|---|
| 60 | EVP_KEYMGMT_up_ref() increments the reference count for the given
|
|---|
| 61 | B<EVP_KEYMGMT> I<keymgmt>.
|
|---|
| 62 |
|
|---|
| 63 | EVP_KEYMGMT_free() decrements the reference count for the given
|
|---|
| 64 | B<EVP_KEYMGMT> I<keymgmt>, and when the count reaches zero, frees it.
|
|---|
| 65 |
|
|---|
| 66 | EVP_KEYMGMT_get0_provider() returns the provider that has this particular
|
|---|
| 67 | implementation.
|
|---|
| 68 |
|
|---|
| 69 | EVP_KEYMGMT_is_a() checks if I<keymgmt> is an implementation of an
|
|---|
| 70 | algorithm that's identifiable with I<name>.
|
|---|
| 71 |
|
|---|
| 72 | EVP_KEYMGMT_get0_name() returns the algorithm name from the provided
|
|---|
| 73 | implementation for the given I<keymgmt>. Note that the I<keymgmt> may have
|
|---|
| 74 | multiple synonyms associated with it. In this case the first name from the
|
|---|
| 75 | algorithm definition is returned. Ownership of the returned string is
|
|---|
| 76 | retained by the I<keymgmt> object and should not be freed by the caller.
|
|---|
| 77 |
|
|---|
| 78 | EVP_KEYMGMT_names_do_all() traverses all names for the I<keymgmt>, and
|
|---|
| 79 | calls I<fn> with each name and I<data>.
|
|---|
| 80 |
|
|---|
| 81 | EVP_KEYMGMT_get0_description() returns a description of the I<keymgmt>, meant
|
|---|
| 82 | for display and human consumption. The description is at the discretion
|
|---|
| 83 | of the I<keymgmt> implementation.
|
|---|
| 84 |
|
|---|
| 85 | EVP_KEYMGMT_do_all_provided() traverses all key keymgmt implementations by
|
|---|
| 86 | all activated providers in the library context I<libctx>, and for each
|
|---|
| 87 | of the implementations, calls I<fn> with the implementation method and
|
|---|
| 88 | I<data> as arguments.
|
|---|
| 89 |
|
|---|
| 90 | EVP_KEYMGMT_gettable_params() and EVP_KEYMGMT_settable_params() return a
|
|---|
| 91 | constant B<OSSL_PARAM> array that describes the names and types of key
|
|---|
| 92 | parameters that can be retrieved or set.
|
|---|
| 93 | EVP_KEYMGMT_gettable_params() is used by L<EVP_PKEY_gettable_params(3)>.
|
|---|
| 94 | See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as a parameter descriptor.
|
|---|
| 95 |
|
|---|
| 96 | EVP_KEYMGMT_gen_settable_params() returns a constant B<OSSL_PARAM> array that
|
|---|
| 97 | describes the names and types of key generation parameters that can be set via
|
|---|
| 98 | L<EVP_PKEY_CTX_set_params(3)>.
|
|---|
| 99 |
|
|---|
| 100 | =head1 NOTES
|
|---|
| 101 |
|
|---|
| 102 | EVP_KEYMGMT_fetch() may be called implicitly by other fetching
|
|---|
| 103 | functions, using the same library context and properties.
|
|---|
| 104 | Any other API that uses keys will typically do this.
|
|---|
| 105 |
|
|---|
| 106 | =head1 RETURN VALUES
|
|---|
| 107 |
|
|---|
| 108 | EVP_KEYMGMT_fetch() returns a pointer to the key management
|
|---|
| 109 | implementation represented by an EVP_KEYMGMT object, or NULL on
|
|---|
| 110 | error.
|
|---|
| 111 |
|
|---|
| 112 | EVP_KEYMGMT_up_ref() returns 1 on success, or 0 on error.
|
|---|
| 113 |
|
|---|
| 114 | EVP_KEYMGMT_names_do_all() returns 1 if the callback was called for all
|
|---|
| 115 | names. A return value of 0 means that the callback was not called for any names.
|
|---|
| 116 |
|
|---|
| 117 | EVP_KEYMGMT_free() doesn't return any value.
|
|---|
| 118 |
|
|---|
| 119 | EVP_KEYMGMT_get0_provider() returns a pointer to a provider object, or NULL
|
|---|
| 120 | on error.
|
|---|
| 121 |
|
|---|
| 122 | EVP_KEYMGMT_is_a() returns 1 of I<keymgmt> was identifiable,
|
|---|
| 123 | otherwise 0.
|
|---|
| 124 |
|
|---|
| 125 | EVP_KEYMGMT_get0_name() returns the algorithm name, or NULL on error.
|
|---|
| 126 |
|
|---|
| 127 | EVP_KEYMGMT_get0_description() returns a pointer to a decription, or NULL if
|
|---|
| 128 | there isn't one.
|
|---|
| 129 |
|
|---|
| 130 | EVP_KEYMGMT_gettable_params(), EVP_KEYMGMT_settable_params() and
|
|---|
| 131 | EVP_KEYMGMT_gen_settable_params() return a constant B<OSSL_PARAM> array or
|
|---|
| 132 | NULL on error.
|
|---|
| 133 |
|
|---|
| 134 | =head1 SEE ALSO
|
|---|
| 135 |
|
|---|
| 136 | L<EVP_MD_fetch(3)>, L<OSSL_LIB_CTX(3)>
|
|---|
| 137 |
|
|---|
| 138 | =head1 HISTORY
|
|---|
| 139 |
|
|---|
| 140 | The functions described here were added in OpenSSL 3.0.
|
|---|
| 141 |
|
|---|
| 142 | =head1 COPYRIGHT
|
|---|
| 143 |
|
|---|
| 144 | Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 145 |
|
|---|
| 146 | Licensed under the Apache License 2.0 (the "License"). You may not use
|
|---|
| 147 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 148 | in the file LICENSE in the source distribution or at
|
|---|
| 149 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 150 |
|
|---|
| 151 | =cut
|
|---|
