]>
Commit | Line | Data |
---|---|---|
d30e4c5b DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
68e91251 | 5 | EVP_PKEY, |
d45a97f4 MC |
6 | EVP_PKEY_new, |
7 | EVP_PKEY_up_ref, | |
2145ba5e | 8 | EVP_PKEY_dup, |
d45a97f4 | 9 | EVP_PKEY_free, |
d8652be0 | 10 | EVP_PKEY_new_raw_private_key_ex, |
f929439f | 11 | EVP_PKEY_new_raw_private_key, |
d8652be0 | 12 | EVP_PKEY_new_raw_public_key_ex, |
f929439f | 13 | EVP_PKEY_new_raw_public_key, |
d45a97f4 | 14 | EVP_PKEY_new_CMAC_key, |
edb77a4d MC |
15 | EVP_PKEY_new_mac_key, |
16 | EVP_PKEY_get_raw_private_key, | |
17 | EVP_PKEY_get_raw_public_key | |
18 | - public/private key allocation and raw key handling functions | |
d30e4c5b DSH |
19 | |
20 | =head1 SYNOPSIS | |
21 | ||
22 | #include <openssl/evp.h> | |
23 | ||
68e91251 RL |
24 | typedef evp_pkey_st EVP_PKEY; |
25 | ||
d30e4c5b | 26 | EVP_PKEY *EVP_PKEY_new(void); |
c5ebfcab | 27 | int EVP_PKEY_up_ref(EVP_PKEY *key); |
2145ba5e | 28 | EVP_PKEY *EVP_PKEY_dup(EVP_PKEY *key); |
d30e4c5b DSH |
29 | void EVP_PKEY_free(EVP_PKEY *key); |
30 | ||
b4250010 | 31 | EVP_PKEY *EVP_PKEY_new_raw_private_key_ex(OSSL_LIB_CTX *libctx, |
d8652be0 MC |
32 | const char *keytype, |
33 | const char *propq, | |
34 | const unsigned char *key, | |
35 | size_t keylen); | |
f929439f MC |
36 | EVP_PKEY *EVP_PKEY_new_raw_private_key(int type, ENGINE *e, |
37 | const unsigned char *key, size_t keylen); | |
b4250010 | 38 | EVP_PKEY *EVP_PKEY_new_raw_public_key_ex(OSSL_LIB_CTX *libctx, |
d8652be0 MC |
39 | const char *keytype, |
40 | const char *propq, | |
41 | const unsigned char *key, | |
42 | size_t keylen); | |
f929439f MC |
43 | EVP_PKEY *EVP_PKEY_new_raw_public_key(int type, ENGINE *e, |
44 | const unsigned char *key, size_t keylen); | |
d45a97f4 MC |
45 | EVP_PKEY *EVP_PKEY_new_mac_key(int type, ENGINE *e, const unsigned char *key, |
46 | int keylen); | |
d30e4c5b | 47 | |
edb77a4d MC |
48 | int EVP_PKEY_get_raw_private_key(const EVP_PKEY *pkey, unsigned char *priv, |
49 | size_t *len); | |
50 | int EVP_PKEY_get_raw_public_key(const EVP_PKEY *pkey, unsigned char *pub, | |
51 | size_t *len); | |
52 | ||
3dbf8243 MC |
53 | The following function has been deprecated since OpenSSL 3.0, and can be |
54 | hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, | |
55 | see L<openssl_user_macros(7)>: | |
a3d267f1 RS |
56 | |
57 | EVP_PKEY *EVP_PKEY_new_CMAC_key(ENGINE *e, const unsigned char *priv, | |
58 | size_t len, const EVP_CIPHER *cipher); | |
59 | ||
d30e4c5b DSH |
60 | =head1 DESCRIPTION |
61 | ||
68e91251 RL |
62 | B<EVP_PKEY> is a generic structure to hold diverse types of asymmetric keys |
63 | (also known as "key pairs"), and can be used for diverse operations, like | |
64 | signing, verifying signatures, key derivation, etc. The asymmetric keys | |
e304aa87 | 65 | themselves are often referred to as the "internal key", and are handled by |
68e91251 RL |
66 | backends, such as providers (through L<EVP_KEYMGMT(3)>) or B<ENGINE>s. |
67 | ||
68 | Conceptually, an B<EVP_PKEY> internal key may hold a private key, a public | |
69 | key, or both (a keypair), and along with those, key parameters if the key type | |
70 | requires them. The presence of these components determine what operations can | |
71 | be made; for example, signing normally requires the presence of a private key, | |
72 | and verifying normally requires the presence of a public key. | |
73 | ||
74 | =for comment ED signature require both the private and public key... | |
75 | ||
76 | B<EVP_PKEY> has also been used for MAC algorithm that were conceived as | |
77 | producing signatures, although not being public key algorithms; "POLY1305", | |
78 | "SIPHASH", "HMAC", "CMAC". This usage is considered legacy and is discouraged | |
79 | in favor of the L<EVP_MAC(3)> API. | |
80 | ||
0c497e96 | 81 | The EVP_PKEY_new() function allocates an empty B<EVP_PKEY> structure which is |
edb77a4d MC |
82 | used by OpenSSL to store public and private keys. The reference count is set to |
83 | B<1>. | |
d30e4c5b | 84 | |
2106b047 | 85 | EVP_PKEY_up_ref() increments the reference count of I<key>. |
0c497e96 | 86 | |
2145ba5e TM |
87 | EVP_PKEY_dup() duplicates the I<key>. The I<key> must not be ENGINE based or |
88 | a raw key, otherwise the duplication will fail. | |
89 | ||
2106b047 MC |
90 | EVP_PKEY_free() decrements the reference count of I<key> and, if the reference |
91 | count is zero, frees it up. If I<key> is NULL, nothing is done. | |
d30e4c5b | 92 | |
68e91251 RL |
93 | EVP_PKEY_new_raw_private_key_ex() allocates a new B<EVP_PKEY>. Unless an |
94 | engine should be used for the key type, a provider for the key is found using | |
2b1bc78a MC |
95 | the library context I<libctx> and the property query string I<propq>. The |
96 | I<keytype> argument indicates what kind of key this is. The value should be a | |
97 | string for a public key algorithm that supports raw private keys, i.e one of | |
68e91251 RL |
98 | "X25519", "ED25519", "X448" or "ED448". I<key> points to the raw private key |
99 | data for this B<EVP_PKEY> which should be of length I<keylen>. The length | |
100 | should be appropriate for the type of the key. The public key data will be | |
101 | automatically derived from the given private key data (if appropriate for the | |
102 | algorithm type). | |
2b1bc78a MC |
103 | |
104 | EVP_PKEY_new_raw_private_key() does the same as | |
68e91251 RL |
105 | EVP_PKEY_new_raw_private_key_ex() except that the default library context and |
106 | default property query are used instead. If I<e> is non-NULL then the new | |
107 | B<EVP_PKEY> structure is associated with the engine I<e>. The I<type> argument | |
108 | indicates what kind of key this is. The value should be a NID for a public key | |
109 | algorithm that supports raw private keys, i.e. one of B<EVP_PKEY_X25519>, | |
110 | B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>. | |
111 | ||
112 | EVP_PKEY_new_raw_private_key_ex() and EVP_PKEY_new_raw_private_key() may also | |
113 | be used with most MACs implemented as public key algorithms, so key types such | |
114 | as "HMAC", "POLY1305", "SIPHASH", or their NID form B<EVP_PKEY_POLY1305>, | |
115 | B<EVP_PKEY_SIPHASH>, B<EVP_PKEY_HMAC> are also accepted. This usage is, | |
116 | as mentioned above, discouraged in favor of the L<EVP_MAC(3)> API. | |
2b1bc78a | 117 | |
d8652be0 MC |
118 | EVP_PKEY_new_raw_public_key_ex() works in the same way as |
119 | EVP_PKEY_new_raw_private_key_ex() except that I<key> points to the raw | |
2b1bc78a MC |
120 | public key data. The B<EVP_PKEY> structure will be initialised without any |
121 | private key information. Algorithm types that support raw public keys are | |
122 | "X25519", "ED25519", "X448" or "ED448". | |
d45a97f4 | 123 | |
f929439f | 124 | EVP_PKEY_new_raw_public_key() works in the same way as |
2106b047 | 125 | EVP_PKEY_new_raw_private_key() except that I<key> points to the raw public key |
f929439f MC |
126 | data. The B<EVP_PKEY> structure will be initialised without any private key |
127 | information. Algorithm types that support raw public keys are | |
128 | B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>. | |
d45a97f4 | 129 | |
f929439f MC |
130 | EVP_PKEY_new_mac_key() works in the same way as EVP_PKEY_new_raw_private_key(). |
131 | New applications should use EVP_PKEY_new_raw_private_key() instead. | |
d45a97f4 | 132 | |
2106b047 MC |
133 | EVP_PKEY_get_raw_private_key() fills the buffer provided by I<priv> with raw |
134 | private key data. The size of the I<priv> buffer should be in I<*len> on entry | |
135 | to the function, and on exit I<*len> is updated with the number of bytes | |
136 | actually written. If the buffer I<priv> is NULL then I<*len> is populated with | |
f529fc7d MC |
137 | the number of bytes required to hold the key. The calling application is |
138 | responsible for ensuring that the buffer is large enough to receive the private | |
139 | key data. This function only works for algorithms that support raw private keys. | |
140 | Currently this is: B<EVP_PKEY_HMAC>, B<EVP_PKEY_POLY1305>, B<EVP_PKEY_SIPHASH>, | |
141 | B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>. | |
edb77a4d | 142 | |
2106b047 MC |
143 | EVP_PKEY_get_raw_public_key() fills the buffer provided by I<pub> with raw |
144 | public key data. The size of the I<pub> buffer should be in I<*len> on entry | |
145 | to the function, and on exit I<*len> is updated with the number of bytes | |
146 | actually written. If the buffer I<pub> is NULL then I<*len> is populated with | |
f529fc7d MC |
147 | the number of bytes required to hold the key. The calling application is |
148 | responsible for ensuring that the buffer is large enough to receive the public | |
149 | key data. This function only works for algorithms that support raw public keys. | |
150 | Currently this is: B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or | |
151 | B<EVP_PKEY_ED448>. | |
edb77a4d | 152 | |
a3d267f1 RS |
153 | EVP_PKEY_new_CMAC_key() works in the same way as EVP_PKEY_new_raw_private_key() |
154 | except it is only for the B<EVP_PKEY_CMAC> algorithm type. In addition to the | |
155 | raw private key data, it also takes a cipher algorithm to be used during | |
156 | creation of a CMAC in the B<cipher> argument. The cipher should be a standard | |
157 | encryption-only cipher. For example AEAD and XTS ciphers should not be used. | |
158 | ||
159 | Applications should use the L<EVP_MAC(3)> API instead | |
160 | and set the B<OSSL_MAC_PARAM_CIPHER> parameter on the B<EVP_MAC_CTX> object | |
161 | with the name of the cipher being used. | |
162 | ||
d30e4c5b DSH |
163 | =head1 NOTES |
164 | ||
0c497e96 DSH |
165 | The B<EVP_PKEY> structure is used by various OpenSSL functions which require a |
166 | general private key without reference to any particular algorithm. | |
d30e4c5b | 167 | |
edb77a4d MC |
168 | The structure returned by EVP_PKEY_new() is empty. To add a private or public |
169 | key to this empty structure use the appropriate functions described in | |
6e4618a0 RS |
170 | L<EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_set1_DSA(3)>, L<EVP_PKEY_set1_DH(3)> or |
171 | L<EVP_PKEY_set1_EC_KEY(3)>. | |
d30e4c5b DSH |
172 | |
173 | =head1 RETURN VALUES | |
174 | ||
f929439f | 175 | EVP_PKEY_new(), EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(), |
d45a97f4 | 176 | EVP_PKEY_new_CMAC_key() and EVP_PKEY_new_mac_key() return either the newly |
2145ba5e TM |
177 | allocated B<EVP_PKEY> structure or NULL if an error occurred. |
178 | ||
179 | EVP_PKEY_dup() returns the key duplicate or NULL if an error occurred. | |
d30e4c5b | 180 | |
edb77a4d MC |
181 | EVP_PKEY_up_ref(), EVP_PKEY_get_raw_private_key() and |
182 | EVP_PKEY_get_raw_public_key() return 1 for success and 0 for failure. | |
d30e4c5b DSH |
183 | |
184 | =head1 SEE ALSO | |
185 | ||
6e4618a0 RS |
186 | L<EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_set1_DSA(3)>, L<EVP_PKEY_set1_DH(3)> or |
187 | L<EVP_PKEY_set1_EC_KEY(3)> | |
d30e4c5b DSH |
188 | |
189 | =head1 HISTORY | |
190 | ||
fc5ecadd DMSP |
191 | The |
192 | EVP_PKEY_new() and EVP_PKEY_free() functions exist in all versions of OpenSSL. | |
0c497e96 | 193 | |
fc5ecadd DMSP |
194 | The EVP_PKEY_up_ref() function was added in OpenSSL 1.1.0. |
195 | ||
196 | The | |
edb77a4d MC |
197 | EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(), |
198 | EVP_PKEY_new_CMAC_key(), EVP_PKEY_new_raw_private_key() and | |
fc5ecadd | 199 | EVP_PKEY_get_raw_public_key() functions were added in OpenSSL 1.1.1. |
d30e4c5b | 200 | |
2145ba5e | 201 | The EVP_PKEY_dup(), EVP_PKEY_new_raw_private_key_ex(), and |
a3d267f1 RS |
202 | EVP_PKEY_new_raw_public_key_ex() |
203 | functions were added in OpenSSL 3.0. | |
204 | ||
205 | The EVP_PKEY_new_CMAC_key() was deprecated in OpenSSL 3.0. | |
2b1bc78a | 206 | |
68e91251 RL |
207 | The documentation of B<EVP_PKEY> was amended in OpenSSL 3.0 to allow there to |
208 | be the private part of the keypair without the public part, where this was | |
209 | previously implied to be disallowed. | |
210 | ||
e2f92610 RS |
211 | =head1 COPYRIGHT |
212 | ||
fecb3aae | 213 | Copyright 2002-2022 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 214 | |
4746f25a | 215 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
216 | this file except in compliance with the License. You can obtain a copy |
217 | in the file LICENSE in the source distribution or at | |
218 | L<https://www.openssl.org/source/license.html>. | |
219 | ||
220 | =cut |