]>
Commit | Line | Data |
---|---|---|
a94a3e0d RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_KEYMGMT, | |
6 | EVP_KEYMGMT_fetch, | |
7 | EVP_KEYMGMT_up_ref, | |
8 | EVP_KEYMGMT_free, | |
251e610c RL |
9 | EVP_KEYMGMT_provider, |
10 | EVP_KEYMGMT_is_a, | |
506cb0f6 | 11 | EVP_KEYMGMT_number, |
3f96b687 | 12 | EVP_KEYMGMT_get0_first_name, |
251e610c | 13 | EVP_KEYMGMT_do_all_provided, |
e3efe7a5 SL |
14 | EVP_KEYMGMT_names_do_all, |
15 | EVP_KEYMGMT_gettable_params, | |
16 | EVP_KEYMGMT_settable_params, | |
17 | EVP_KEYMGMT_gen_settable_params | |
a94a3e0d RL |
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(OPENSSL_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_provider(const EVP_KEYMGMT *keymgmt); | |
251e610c | 31 | int EVP_KEYMGMT_is_a(const EVP_KEYMGMT *keymgmt, const char *name); |
506cb0f6 | 32 | int EVP_KEYMGMT_number(const EVP_KEYMGMT *keymgmt); |
3f96b687 MC |
33 | const char *EVP_KEYMGMT_get0_first_name(const EVP_KEYMGMT *keymgmt); |
34 | ||
251e610c RL |
35 | void EVP_KEYMGMT_do_all_provided(OPENSSL_CTX *libctx, |
36 | void (*fn)(EVP_KEYMGMT *keymgmt, void *arg), | |
37 | void *arg); | |
f651c727 RL |
38 | void EVP_KEYMGMT_names_do_all(const EVP_KEYMGMT *keymgmt, |
39 | void (*fn)(const char *name, void *data), | |
40 | void *data); | |
e3efe7a5 SL |
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); | |
a94a3e0d RL |
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<OPENSSL_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_provider() returns the provider that has this particular | |
67 | implementation. | |
68 | ||
251e610c RL |
69 | EVP_KEYMGMT_is_a() checks if I<keymgmt> is an implementation of an |
70 | algorithm that's identifiable with I<name>. | |
71 | ||
506cb0f6 RL |
72 | EVP_KEYMGMT_number() returns the internal dynamic number assigned to |
73 | the I<keymgmt>. | |
74 | ||
3f96b687 MC |
75 | EVP_KEYMGMT_get0_first_name() returns the first algorithm name that is found for |
76 | the given I<keymgmt>. Note that the I<keymgmt> may have multiple synonyms | |
77 | associated with it. In this case it is undefined which one will be returned. | |
78 | Ownership of the returned string is retained by the I<keymgmt> object and should | |
79 | not be freed by the caller. | |
80 | ||
f651c727 RL |
81 | EVP_KEYMGMT_names_do_all() traverses all names for the I<keymgmt>, and |
82 | calls I<fn> with each name and I<data>. | |
83 | ||
251e610c RL |
84 | EVP_KEYMGMT_do_all_provided() traverses all key keymgmt implementations by |
85 | all activated providers in the library context I<libctx>, and for each | |
86 | of the implementations, calls I<fn> with the implementation method and | |
87 | I<data> as arguments. | |
88 | ||
e3efe7a5 SL |
89 | EVP_KEYMGMT_gettable_params() and EVP_KEYMGMT_settable_params() return a |
90 | constant B<OSSL_PARAM> array that describes the names and types of key | |
91 | parameters that can be retrieved or set. | |
92 | EVP_KEYMGMT_gettable_params() is used by L<EVP_PKEY_gettable_params(3)>. | |
93 | See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as a parameter descriptor. | |
94 | ||
95 | EVP_KEYMGMT_gen_settable_params() returns a constant B<OSSL_PARAM> array that | |
96 | describes the names and types of key generation parameters that can be set via | |
97 | L<EVP_PKEY_CTX_set_params(3)>. | |
98 | ||
a94a3e0d RL |
99 | =head1 NOTES |
100 | ||
101 | EVP_KEYMGMT_fetch() may be called implicitly by other fetching | |
102 | functions, using the same library context and properties. | |
103 | Any other API that uses keys will typically do this. | |
104 | ||
105 | =head1 RETURN VALUES | |
106 | ||
107 | EVP_KEYMGMT_fetch() returns a pointer to the key management | |
108 | implementation represented by an EVP_KEYMGMT object, or NULL on | |
109 | error. | |
110 | ||
111 | EVP_KEYMGMT_up_ref() returns 1 on success, or 0 on error. | |
112 | ||
113 | EVP_KEYMGMT_free() doesn't return any value. | |
114 | ||
115 | EVP_KEYMGMT_provider() returns a pointer to a provider object, or NULL | |
116 | on error. | |
117 | ||
251e610c RL |
118 | EVP_KEYMGMT_is_a() returns 1 of I<keymgmt> was identifiable, |
119 | otherwise 0. | |
120 | ||
506cb0f6 RL |
121 | EVP_KEYMGMT_number() returns an integer. |
122 | ||
3f96b687 MC |
123 | EVP_KEYMGMT_get0_first_name() returns the name that is found or NULL on error. |
124 | ||
e3efe7a5 SL |
125 | EVP_KEYMGMT_gettable_params(), EVP_KEYMGMT_settable_params() and |
126 | EVP_KEYMGMT_gen_settable_params() return a constant B<OSSL_PARAM> array or | |
127 | NULL on error. | |
128 | ||
a94a3e0d RL |
129 | =head1 SEE ALSO |
130 | ||
131 | L<EVP_MD_fetch(3)>, L<OPENSSL_CTX(3)> | |
132 | ||
133 | =head1 HISTORY | |
134 | ||
135 | The functions described here were added in OpenSSL 3.0. | |
136 | ||
137 | =head1 COPYRIGHT | |
138 | ||
e3efe7a5 | 139 | Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved. |
a94a3e0d RL |
140 | |
141 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
142 | this file except in compliance with the License. You can obtain a copy | |
143 | in the file LICENSE in the source distribution or at | |
144 | L<https://www.openssl.org/source/license.html>. | |
145 | ||
146 | =cut |