]>
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, | |
f929439f MC |
8 | EVP_PKEY_new_raw_private_key, |
9 | EVP_PKEY_new_raw_public_key, | |
d45a97f4 MC |
10 | EVP_PKEY_new_CMAC_key, |
11 | EVP_PKEY_new_mac_key | |
12 | - public/private key allocation functions | |
d30e4c5b DSH |
13 | |
14 | =head1 SYNOPSIS | |
15 | ||
16 | #include <openssl/evp.h> | |
17 | ||
18 | EVP_PKEY *EVP_PKEY_new(void); | |
c5ebfcab | 19 | int EVP_PKEY_up_ref(EVP_PKEY *key); |
d30e4c5b DSH |
20 | void EVP_PKEY_free(EVP_PKEY *key); |
21 | ||
f929439f MC |
22 | EVP_PKEY *EVP_PKEY_new_raw_private_key(int type, ENGINE *e, |
23 | const unsigned char *key, size_t keylen); | |
24 | EVP_PKEY *EVP_PKEY_new_raw_public_key(int type, ENGINE *e, | |
25 | const unsigned char *key, size_t keylen); | |
d45a97f4 MC |
26 | EVP_PKEY *EVP_PKEY_new_CMAC_key(ENGINE *e, const unsigned char *priv, |
27 | size_t len, const EVP_CIPHER *cipher); | |
28 | EVP_PKEY *EVP_PKEY_new_mac_key(int type, ENGINE *e, const unsigned char *key, | |
29 | int keylen); | |
d30e4c5b DSH |
30 | |
31 | =head1 DESCRIPTION | |
32 | ||
0c497e96 DSH |
33 | The EVP_PKEY_new() function allocates an empty B<EVP_PKEY> structure which is |
34 | used by OpenSSL to store private keys. The reference count is set to B<1>. | |
d30e4c5b | 35 | |
0c497e96 DSH |
36 | EVP_PKEY_up_ref() increments the reference count of B<key>. |
37 | ||
38 | EVP_PKEY_free() decrements the reference count of B<key> and, if the reference | |
39 | count is zero, frees it up. If B<key> is NULL, nothing is done. | |
d30e4c5b | 40 | |
f929439f MC |
41 | EVP_PKEY_new_raw_private_key() allocates a new B<EVP_PKEY>. If B<e> is non-NULL |
42 | then the new B<EVP_PKEY> structure is associated with the engine B<e>. The | |
43 | B<type> argument indicates what kind of key this is. The value should be a NID | |
44 | for a public key algorithm that supports raw private keys, i.e. one of | |
d45a97f4 MC |
45 | B<EVP_PKEY_HMAC>, B<EVP_PKEY_POLY1305>, B<EVP_PKEY_SIPHASH>, B<EVP_PKEY_X25519>, |
46 | B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>. B<key> points to the | |
47 | raw private key data for this B<EVP_PKEY> which should be of length B<keylen>. | |
48 | The length should be appropriate for the type of the key. The public key data | |
49 | will be automatically derived from the given private key data (if appropriate | |
50 | for the algorithm type). | |
51 | ||
f929439f MC |
52 | EVP_PKEY_new_raw_public_key() works in the same way as |
53 | EVP_PKEY_new_raw_private_key() except that B<key> points to the raw public key | |
54 | data. The B<EVP_PKEY> structure will be initialised without any private key | |
55 | information. Algorithm types that support raw public keys are | |
56 | B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>. | |
d45a97f4 | 57 | |
f929439f | 58 | EVP_PKEY_new_CMAC_key() works in the same way as EVP_PKEY_new_raw_private_key() |
d45a97f4 MC |
59 | except it is only for the B<EVP_PKEY_CMAC> algorithm type. In addition to the |
60 | raw private key data, it also takes a cipher algorithm to be used during | |
61 | creation of a CMAC in the B<cipher> argument. | |
62 | ||
f929439f MC |
63 | EVP_PKEY_new_mac_key() works in the same way as EVP_PKEY_new_raw_private_key(). |
64 | New applications should use EVP_PKEY_new_raw_private_key() instead. | |
d45a97f4 | 65 | |
d30e4c5b DSH |
66 | =head1 NOTES |
67 | ||
0c497e96 DSH |
68 | The B<EVP_PKEY> structure is used by various OpenSSL functions which require a |
69 | general private key without reference to any particular algorithm. | |
d30e4c5b | 70 | |
0c497e96 DSH |
71 | The structure returned by EVP_PKEY_new() is empty. To add a private key to this |
72 | empty structure the functions described in L<EVP_PKEY_set1_RSA(3)> should be | |
73 | used. | |
d30e4c5b DSH |
74 | |
75 | =head1 RETURN VALUES | |
76 | ||
f929439f | 77 | EVP_PKEY_new(), EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(), |
d45a97f4 MC |
78 | EVP_PKEY_new_CMAC_key() and EVP_PKEY_new_mac_key() return either the newly |
79 | allocated B<EVP_PKEY> structure or B<NULL> if an error occurred. | |
d30e4c5b | 80 | |
c5ebfcab | 81 | EVP_PKEY_up_ref() returns 1 for success and 0 for failure. |
d30e4c5b DSH |
82 | |
83 | =head1 SEE ALSO | |
84 | ||
9b86974e | 85 | L<EVP_PKEY_set1_RSA(3)> |
d30e4c5b DSH |
86 | |
87 | =head1 HISTORY | |
88 | ||
0c497e96 DSH |
89 | EVP_PKEY_new() and EVP_PKEY_free() exist in all versions of OpenSSL. |
90 | ||
f929439f MC |
91 | EVP_PKEY_up_ref() was first added to OpenSSL 1.1.0. |
92 | EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key() and | |
93 | EVP_PKEY_new_CMAC_key() were first added to OpenSSL 1.1.1. | |
d30e4c5b | 94 | |
e2f92610 RS |
95 | =head1 COPYRIGHT |
96 | ||
b0edda11 | 97 | Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
98 | |
99 | Licensed under the OpenSSL license (the "License"). You may not use | |
100 | this file except in compliance with the License. You can obtain a copy | |
101 | in the file LICENSE in the source distribution or at | |
102 | L<https://www.openssl.org/source/license.html>. | |
103 | ||
104 | =cut |