]>
Commit | Line | Data |
---|---|---|
d30e4c5b DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
d45a97f4 MC |
5 | EVP_PKEY_new, |
6 | EVP_PKEY_up_ref, | |
7 | EVP_PKEY_free, | |
d8652be0 | 8 | EVP_PKEY_new_raw_private_key_ex, |
f929439f | 9 | EVP_PKEY_new_raw_private_key, |
d8652be0 | 10 | EVP_PKEY_new_raw_public_key_ex, |
f929439f | 11 | EVP_PKEY_new_raw_public_key, |
d8652be0 | 12 | EVP_PKEY_new_CMAC_key_ex, |
d45a97f4 | 13 | EVP_PKEY_new_CMAC_key, |
edb77a4d MC |
14 | EVP_PKEY_new_mac_key, |
15 | EVP_PKEY_get_raw_private_key, | |
16 | EVP_PKEY_get_raw_public_key | |
17 | - public/private key allocation and raw key handling functions | |
d30e4c5b DSH |
18 | |
19 | =head1 SYNOPSIS | |
20 | ||
21 | #include <openssl/evp.h> | |
22 | ||
23 | EVP_PKEY *EVP_PKEY_new(void); | |
c5ebfcab | 24 | int EVP_PKEY_up_ref(EVP_PKEY *key); |
d30e4c5b DSH |
25 | void EVP_PKEY_free(EVP_PKEY *key); |
26 | ||
b4250010 | 27 | EVP_PKEY *EVP_PKEY_new_raw_private_key_ex(OSSL_LIB_CTX *libctx, |
d8652be0 MC |
28 | const char *keytype, |
29 | const char *propq, | |
30 | const unsigned char *key, | |
31 | size_t keylen); | |
f929439f MC |
32 | EVP_PKEY *EVP_PKEY_new_raw_private_key(int type, ENGINE *e, |
33 | const unsigned char *key, size_t keylen); | |
b4250010 | 34 | EVP_PKEY *EVP_PKEY_new_raw_public_key_ex(OSSL_LIB_CTX *libctx, |
d8652be0 MC |
35 | const char *keytype, |
36 | const char *propq, | |
37 | const unsigned char *key, | |
38 | size_t keylen); | |
f929439f MC |
39 | EVP_PKEY *EVP_PKEY_new_raw_public_key(int type, ENGINE *e, |
40 | const unsigned char *key, size_t keylen); | |
d8652be0 MC |
41 | EVP_PKEY *EVP_PKEY_new_CMAC_key_ex(const unsigned char *priv, size_t len, |
42 | const char *cipher_name, | |
b4250010 | 43 | OSSL_LIB_CTX *libctx, const char *propq); |
d45a97f4 MC |
44 | EVP_PKEY *EVP_PKEY_new_CMAC_key(ENGINE *e, const unsigned char *priv, |
45 | size_t len, const EVP_CIPHER *cipher); | |
46 | EVP_PKEY *EVP_PKEY_new_mac_key(int type, ENGINE *e, const unsigned char *key, | |
47 | int keylen); | |
d30e4c5b | 48 | |
edb77a4d MC |
49 | int EVP_PKEY_get_raw_private_key(const EVP_PKEY *pkey, unsigned char *priv, |
50 | size_t *len); | |
51 | int EVP_PKEY_get_raw_public_key(const EVP_PKEY *pkey, unsigned char *pub, | |
52 | size_t *len); | |
53 | ||
d30e4c5b DSH |
54 | =head1 DESCRIPTION |
55 | ||
0c497e96 | 56 | The EVP_PKEY_new() function allocates an empty B<EVP_PKEY> structure which is |
edb77a4d MC |
57 | used by OpenSSL to store public and private keys. The reference count is set to |
58 | B<1>. | |
d30e4c5b | 59 | |
2106b047 | 60 | EVP_PKEY_up_ref() increments the reference count of I<key>. |
0c497e96 | 61 | |
2106b047 MC |
62 | EVP_PKEY_free() decrements the reference count of I<key> and, if the reference |
63 | count is zero, frees it up. If I<key> is NULL, nothing is done. | |
d30e4c5b | 64 | |
d8652be0 | 65 | EVP_PKEY_new_raw_private_key_ex() allocates a new B<EVP_PKEY>. Unless |
2b1bc78a MC |
66 | an engine should be used for the key type, a provider for the key is found using |
67 | the library context I<libctx> and the property query string I<propq>. The | |
68 | I<keytype> argument indicates what kind of key this is. The value should be a | |
69 | string for a public key algorithm that supports raw private keys, i.e one of | |
70 | "POLY1305", "SIPHASH", "X25519", "ED25519", "X448" or "ED448". Note that you may | |
71 | also use "HMAC" which is not a public key algorithm but is treated as such by | |
72 | some OpenSSL APIs. You are encouraged to use the EVP_MAC APIs instead for HMAC | |
73 | (see L<EVP_MAC(3)>). I<key> points to the raw private key data for this | |
74 | B<EVP_PKEY> which should be of length I<keylen>. The length should be | |
75 | appropriate for the type of the key. The public key data will be automatically | |
76 | derived from the given private key data (if appropriate for the algorithm type). | |
77 | ||
78 | EVP_PKEY_new_raw_private_key() does the same as | |
d8652be0 | 79 | EVP_PKEY_new_raw_private_key_ex() except that the default library |
2106b047 MC |
80 | context and default property query are used instead. If I<e> is non-NULL then |
81 | the new B<EVP_PKEY> structure is associated with the engine I<e>. The I<type> | |
2b1bc78a MC |
82 | argument indicates what kind of key this is. The value should be a NID for a |
83 | public key algorithm that supports raw private keys, i.e. one of | |
84 | B<EVP_PKEY_POLY1305>, B<EVP_PKEY_SIPHASH>, B<EVP_PKEY_X25519>, | |
85 | B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>. As for | |
d8652be0 | 86 | EVP_PKEY_new_raw_private_key_ex() you may also use B<EVP_PKEY_HMAC>. |
2b1bc78a | 87 | |
d8652be0 MC |
88 | EVP_PKEY_new_raw_public_key_ex() works in the same way as |
89 | EVP_PKEY_new_raw_private_key_ex() except that I<key> points to the raw | |
2b1bc78a MC |
90 | public key data. The B<EVP_PKEY> structure will be initialised without any |
91 | private key information. Algorithm types that support raw public keys are | |
92 | "X25519", "ED25519", "X448" or "ED448". | |
d45a97f4 | 93 | |
f929439f | 94 | EVP_PKEY_new_raw_public_key() works in the same way as |
2106b047 | 95 | EVP_PKEY_new_raw_private_key() except that I<key> points to the raw public key |
f929439f MC |
96 | data. The B<EVP_PKEY> structure will be initialised without any private key |
97 | information. Algorithm types that support raw public keys are | |
98 | B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>. | |
d45a97f4 | 99 | |
d8652be0 | 100 | EVP_PKEY_new_CMAC_key_ex() works in the same way as |
2106b047 MC |
101 | EVP_PKEY_new_raw_private_key() except it is only for the B<EVP_PKEY_CMAC> |
102 | algorithm type. In addition to the raw private key data, it also takes a cipher | |
103 | algorithm to be used during creation of a CMAC in the I<cipher> argument. The | |
104 | cipher should be a standard encryption only cipher. For example AEAD and XTS | |
52ae0f8f MC |
105 | ciphers should not be used. Finally it also takes a library context I<libctx> |
106 | and property query I<propq> which are used when fetching any cryptographic | |
107 | algorithms which may be NULL to use the default values. | |
2106b047 | 108 | |
d8652be0 | 109 | EVP_PKEY_new_CMAC_key() is the same as EVP_PKEY_new_CMAC_key_ex() |
2106b047 | 110 | except that the default values are used for I<libctx> and I<propq>. |
d45a97f4 | 111 | |
f929439f MC |
112 | EVP_PKEY_new_mac_key() works in the same way as EVP_PKEY_new_raw_private_key(). |
113 | New applications should use EVP_PKEY_new_raw_private_key() instead. | |
d45a97f4 | 114 | |
2106b047 MC |
115 | EVP_PKEY_get_raw_private_key() fills the buffer provided by I<priv> with raw |
116 | private key data. The size of the I<priv> buffer should be in I<*len> on entry | |
117 | to the function, and on exit I<*len> is updated with the number of bytes | |
118 | actually written. If the buffer I<priv> is NULL then I<*len> is populated with | |
f529fc7d MC |
119 | the number of bytes required to hold the key. The calling application is |
120 | responsible for ensuring that the buffer is large enough to receive the private | |
121 | key data. This function only works for algorithms that support raw private keys. | |
122 | Currently this is: B<EVP_PKEY_HMAC>, B<EVP_PKEY_POLY1305>, B<EVP_PKEY_SIPHASH>, | |
123 | B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>. | |
edb77a4d | 124 | |
2106b047 MC |
125 | EVP_PKEY_get_raw_public_key() fills the buffer provided by I<pub> with raw |
126 | public key data. The size of the I<pub> buffer should be in I<*len> on entry | |
127 | to the function, and on exit I<*len> is updated with the number of bytes | |
128 | actually written. If the buffer I<pub> is NULL then I<*len> is populated with | |
f529fc7d MC |
129 | the number of bytes required to hold the key. The calling application is |
130 | responsible for ensuring that the buffer is large enough to receive the public | |
131 | key data. This function only works for algorithms that support raw public keys. | |
132 | Currently this is: B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or | |
133 | B<EVP_PKEY_ED448>. | |
edb77a4d | 134 | |
d30e4c5b DSH |
135 | =head1 NOTES |
136 | ||
0c497e96 DSH |
137 | The B<EVP_PKEY> structure is used by various OpenSSL functions which require a |
138 | general private key without reference to any particular algorithm. | |
d30e4c5b | 139 | |
edb77a4d MC |
140 | The structure returned by EVP_PKEY_new() is empty. To add a private or public |
141 | key to this empty structure use the appropriate functions described in | |
6e4618a0 RS |
142 | L<EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_set1_DSA(3)>, L<EVP_PKEY_set1_DH(3)> or |
143 | L<EVP_PKEY_set1_EC_KEY(3)>. | |
d30e4c5b DSH |
144 | |
145 | =head1 RETURN VALUES | |
146 | ||
f929439f | 147 | EVP_PKEY_new(), EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(), |
d45a97f4 MC |
148 | EVP_PKEY_new_CMAC_key() and EVP_PKEY_new_mac_key() return either the newly |
149 | allocated B<EVP_PKEY> structure or B<NULL> if an error occurred. | |
d30e4c5b | 150 | |
edb77a4d MC |
151 | EVP_PKEY_up_ref(), EVP_PKEY_get_raw_private_key() and |
152 | EVP_PKEY_get_raw_public_key() return 1 for success and 0 for failure. | |
d30e4c5b DSH |
153 | |
154 | =head1 SEE ALSO | |
155 | ||
6e4618a0 RS |
156 | L<EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_set1_DSA(3)>, L<EVP_PKEY_set1_DH(3)> or |
157 | L<EVP_PKEY_set1_EC_KEY(3)> | |
d30e4c5b DSH |
158 | |
159 | =head1 HISTORY | |
160 | ||
fc5ecadd DMSP |
161 | The |
162 | EVP_PKEY_new() and EVP_PKEY_free() functions exist in all versions of OpenSSL. | |
0c497e96 | 163 | |
fc5ecadd DMSP |
164 | The EVP_PKEY_up_ref() function was added in OpenSSL 1.1.0. |
165 | ||
166 | The | |
edb77a4d MC |
167 | EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(), |
168 | EVP_PKEY_new_CMAC_key(), EVP_PKEY_new_raw_private_key() and | |
fc5ecadd | 169 | EVP_PKEY_get_raw_public_key() functions were added in OpenSSL 1.1.1. |
d30e4c5b | 170 | |
d8652be0 MC |
171 | The EVP_PKEY_new_raw_private_key_ex(), |
172 | EVP_PKEY_new_raw_public_key_ex() and | |
173 | EVP_PKEY_new_CMAC_key_ex() functions were added in OpenSSL 3.0. | |
2b1bc78a | 174 | |
e2f92610 RS |
175 | =head1 COPYRIGHT |
176 | ||
33388b44 | 177 | Copyright 2002-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 178 | |
4746f25a | 179 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
180 | this file except in compliance with the License. You can obtain a copy |
181 | in the file LICENSE in the source distribution or at | |
182 | L<https://www.openssl.org/source/license.html>. | |
183 | ||
184 | =cut |