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