]>
Commit | Line | Data |
---|---|---|
d30e4c5b DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY, | |
6 | EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY, | |
2872dbe1 | 7 | EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY, |
d30e4c5b | 8 | EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, EVP_PKEY_assign_EC_KEY, |
c952780c RS |
9 | EVP_PKEY_get0_hmac, |
10 | EVP_PKEY_type, EVP_PKEY_id, EVP_PKEY_base_id | |
11 | - EVP_PKEY assignment functions | |
d30e4c5b DSH |
12 | |
13 | =head1 SYNOPSIS | |
14 | ||
15 | #include <openssl/evp.h> | |
16 | ||
17 | int EVP_PKEY_set1_RSA(EVP_PKEY *pkey,RSA *key); | |
18 | int EVP_PKEY_set1_DSA(EVP_PKEY *pkey,DSA *key); | |
19 | int EVP_PKEY_set1_DH(EVP_PKEY *pkey,DH *key); | |
20 | int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey,EC_KEY *key); | |
21 | ||
22 | RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey); | |
23 | DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey); | |
24 | DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey); | |
25 | EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey); | |
26 | ||
ebad0b0b | 27 | const unsigned char *EVP_PKEY_get0_hmac(const EVP_PKEY *pkey, size_t *len); |
2872dbe1 DSH |
28 | RSA *EVP_PKEY_get0_RSA(EVP_PKEY *pkey); |
29 | DSA *EVP_PKEY_get0_DSA(EVP_PKEY *pkey); | |
30 | DH *EVP_PKEY_get0_DH(EVP_PKEY *pkey); | |
31 | EC_KEY *EVP_PKEY_get0_EC_KEY(EVP_PKEY *pkey); | |
32 | ||
d30e4c5b DSH |
33 | int EVP_PKEY_assign_RSA(EVP_PKEY *pkey,RSA *key); |
34 | int EVP_PKEY_assign_DSA(EVP_PKEY *pkey,DSA *key); | |
35 | int EVP_PKEY_assign_DH(EVP_PKEY *pkey,DH *key); | |
36 | int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey,EC_KEY *key); | |
37 | ||
b36a2efd DSH |
38 | int EVP_PKEY_id(const EVP_PKEY *pkey); |
39 | int EVP_PKEY_base_id(const EVP_PKEY *pkey); | |
d30e4c5b DSH |
40 | int EVP_PKEY_type(int type); |
41 | ||
42 | =head1 DESCRIPTION | |
43 | ||
44 | EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and | |
45 | EVP_PKEY_set1_EC_KEY() set the key referenced by B<pkey> to B<key>. | |
46 | ||
47 | EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and | |
48 | EVP_PKEY_get1_EC_KEY() return the referenced key in B<pkey> or | |
49 | B<NULL> if the key is not of the correct type. | |
50 | ||
ebad0b0b NM |
51 | EVP_PKEY_get0_hmac(), EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), |
52 | EVP_PKEY_get0_DH() and EVP_PKEY_get0_EC_KEY() also return the | |
53 | referenced key in B<pkey> or B<NULL> if the key is not of the | |
54 | correct type but the reference count of the returned key is | |
55 | B<not> incremented and so must not be freed up after use. | |
2872dbe1 | 56 | |
2dd8cb3b | 57 | EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() |
d30e4c5b DSH |
58 | and EVP_PKEY_assign_EC_KEY() also set the referenced key to B<key> |
59 | however these use the supplied B<key> internally and so B<key> | |
60 | will be freed when the parent B<pkey> is freed. | |
61 | ||
b36a2efd DSH |
62 | EVP_PKEY_base_id() returns the type of B<pkey>. For example |
63 | an RSA key will return B<EVP_PKEY_RSA>. | |
64 | ||
65 | EVP_PKEY_id() returns the actual OID associated with B<pkey>. Historically keys | |
66 | using the same algorithm could use different OIDs. For example an RSA key could | |
67 | use the OIDs corresponding to the NIDs B<NID_rsaEncryption> (equivalent to | |
d1beebdf | 68 | B<EVP_PKEY_RSA>) or B<NID_rsa> (equivalent to B<EVP_PKEY_RSA2>). The use of |
b36a2efd DSH |
69 | alternative non-standard OIDs is now rare so B<EVP_PKEY_RSA2> et al are not |
70 | often seen in practice. | |
71 | ||
72 | EVP_PKEY_type() returns the underlying type of the NID B<type>. For example | |
73 | EVP_PKEY_type(EVP_PKEY_RSA2) will return B<EVP_PKEY_RSA>. | |
d30e4c5b DSH |
74 | |
75 | =head1 NOTES | |
76 | ||
77 | In accordance with the OpenSSL naming convention the key obtained | |
78 | from or assigned to the B<pkey> using the B<1> functions must be | |
79 | freed as well as B<pkey>. | |
80 | ||
2dd8cb3b MC |
81 | EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() |
82 | and EVP_PKEY_assign_EC_KEY() are implemented as macros. | |
d30e4c5b | 83 | |
b36a2efd DSH |
84 | Most applications wishing to know a key type will simply call |
85 | EVP_PKEY_base_id() and will not care about the actual type: | |
86 | which will be identical in almost all cases. | |
87 | ||
88 | Previous versions of this document suggested using EVP_PKEY_type(pkey->type) | |
89 | to determine the type of a key. Since B<EVP_PKEY> is now opaque this | |
90 | is no longer possible: the equivalent is EVP_PKEY_base_id(pkey). | |
91 | ||
d30e4c5b DSH |
92 | =head1 RETURN VALUES |
93 | ||
94 | EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and | |
95 | EVP_PKEY_set1_EC_KEY() return 1 for success or 0 for failure. | |
96 | ||
97 | EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and | |
b36a2efd | 98 | EVP_PKEY_get1_EC_KEY() return the referenced key or B<NULL> if |
d30e4c5b DSH |
99 | an error occurred. |
100 | ||
2dd8cb3b | 101 | EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() |
d30e4c5b DSH |
102 | and EVP_PKEY_assign_EC_KEY() return 1 for success and 0 for failure. |
103 | ||
b36a2efd DSH |
104 | EVP_PKEY_base_id(), EVP_PKEY_id() and EVP_PKEY_type() return a key |
105 | type or B<NID_undef> (equivalently B<EVP_PKEY_NONE>) on error. | |
106 | ||
d30e4c5b DSH |
107 | =head1 SEE ALSO |
108 | ||
9b86974e | 109 | L<EVP_PKEY_new(3)> |
d30e4c5b | 110 | |
e2f92610 RS |
111 | =head1 COPYRIGHT |
112 | ||
113 | Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. | |
114 | ||
115 | Licensed under the OpenSSL license (the "License"). You may not use | |
116 | this file except in compliance with the License. You can obtain a copy | |
117 | in the file LICENSE in the source distribution or at | |
118 | L<https://www.openssl.org/source/license.html>. | |
119 | ||
120 | =cut |