]>
Commit | Line | Data |
---|---|---|
3795b2a3 MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
0a737e16 MC |
5 | EVP_PKEY_set1_encoded_public_key, EVP_PKEY_get1_encoded_public_key, |
6 | EVP_PKEY_set1_tls_encodedpoint, EVP_PKEY_get1_tls_encodedpoint | |
3795b2a3 MC |
7 | - functions to set and get public key data within an EVP_PKEY |
8 | ||
9 | =head1 SYNOPSIS | |
10 | ||
11 | #include <openssl/evp.h> | |
12 | ||
13 | int EVP_PKEY_set1_encoded_public_key(EVP_PKEY *pkey, | |
14 | const unsigned char *pub, size_t publen); | |
15 | ||
16 | size_t EVP_PKEY_get1_encoded_public_key(EVP_PKEY *pkey, unsigned char **ppub); | |
17 | ||
0a737e16 MC |
18 | Deprecated since OpenSSL 3.0, can be hidden entirely by defining |
19 | B<OPENSSL_API_COMPAT> with a suitable version value, see | |
20 | L<openssl_user_macros(7)>: | |
3795b2a3 | 21 | |
0a737e16 MC |
22 | int EVP_PKEY_set1_tls_encodedpoint(EVP_PKEY *pkey, |
23 | const unsigned char *pt, size_t ptlen); | |
24 | ||
25 | size_t EVP_PKEY_get1_tls_encodedpoint(EVP_PKEY *pkey, unsigned char **ppt); | |
3795b2a3 MC |
26 | |
27 | =head1 DESCRIPTION | |
28 | ||
29 | EVP_PKEY_set1_encoded_public_key() can be used to set the public key value | |
30 | within an existing EVP_PKEY object. For the built-in OpenSSL algorithms this | |
31 | currently only works for those that support key exchange. Parameters are not | |
32 | set as part of this operation, so typically an application will create an | |
33 | EVP_PKEY first, set the parameters on it, and then call this function. | |
34 | For example setting the parameters might be done using | |
35 | L<EVP_PKEY_copy_parameters(3)>. | |
36 | ||
37 | The format for the encoded public key will depend on the algorithm in use. For | |
38 | DH it should be encoded as a positive integer in big-endian form. For EC is | |
39 | should be a point conforming to Sec. 2.3.4 of the SECG SEC 1 ("Elliptic | |
40 | Curve Cryptography") standard. For X25519 and X448 it should be encoded in a | |
41 | format as defined by RFC7748. | |
42 | ||
43 | The key to be updated is supplied in B<pkey>. The buffer containing the encoded | |
44 | key is pointed to be B<pub>. The length of the buffer is supplied in B<publen>. | |
45 | ||
46 | EVP_PKEY_get1_encoded_public_key() does the equivalent operation except that | |
47 | the encoded public key is returned to the application. The key containing the | |
48 | public key data is supplied in B<pkey>. A buffer containing the encoded key will | |
49 | be allocated and stored in B<*ppub>. The length of the encoded public key is | |
50 | returned by the function. The application is responsible for freeing the | |
51 | allocated buffer. | |
52 | ||
0a737e16 MC |
53 | The macro EVP_PKEY_set1_tls_encodedpoint() is deprecated and simply calls |
54 | EVP_PKEY_set1_encoded_public_key() with all the same arguments. New applications | |
55 | should use EVP_PKEY_set1_encoded_public_key() instead. | |
56 | ||
57 | The macro EVP_PKEY_get1_tls_encodedpoint() is deprecated and simply calls | |
58 | EVP_PKEY_get1_encoded_public_key() with all the same arguments. New applications | |
59 | should use EVP_PKEY_get1_encoded_public_key() instead. | |
60 | ||
61 | ||
3795b2a3 MC |
62 | =head1 RETURN VALUES |
63 | ||
64 | EVP_PKEY_set1_encoded_public_key() returns 1 for success and 0 or a negative | |
65 | value for failure. | |
66 | ||
67 | EVP_PKEY_get1_encoded_public_key() return 1 | |
68 | ||
69 | =head1 EXAMPLES | |
70 | ||
71 | See L<EVP_PKEY_derive_init(3)> and L<EVP_PKEY_derive(3)> for information about | |
72 | performing a key exchange operation. | |
73 | ||
74 | =head2 Set up a peer's EVP_PKEY ready for a key exchange operation | |
75 | ||
76 | #include <openssl/evp.h> | |
0a737e16 | 77 | |
3795b2a3 MC |
78 | int exchange(EVP_PKEY *ourkey, unsigned char *peer_pub, size_t peer_pub_len) |
79 | { | |
80 | EVP_PKEY *peerkey = EVP_PKEY_new(); | |
81 | ||
82 | if (peerkey == NULL || EVP_PKEY_copy_parameters(peerkey, ourkey) <= 0) | |
83 | return 0; | |
84 | ||
85 | if (EVP_PKEY_set1_encoded_public_key(peerkey, peer_pub, | |
86 | peer_pub_len) <= 0) | |
87 | return 0; | |
0a737e16 | 88 | |
3795b2a3 | 89 | /* Do the key exchange here */ |
0a737e16 | 90 | |
3795b2a3 | 91 | EVP_PKEY_free(peerkey); |
0a737e16 | 92 | |
3795b2a3 MC |
93 | return 1; |
94 | } | |
95 | ||
96 | =head2 Get an encoded public key to send to a peer | |
97 | ||
98 | #include <openssl/evp.h> | |
99 | ||
100 | int get_encoded_pub_key(EVP_PKEY *ourkey) | |
101 | { | |
102 | unsigned char *pubkey; | |
103 | size_t pubkey_len; | |
104 | ||
105 | pubkey_len = EVP_PKEY_get1_encoded_public_key(ourkey, &pubkey); | |
106 | if (pubkey_len == 0) | |
107 | return 0; | |
108 | ||
109 | /* | |
110 | * Send the encoded public key stored in the buffer at "pubkey" and of | |
111 | * length pubkey_len, to the peer. | |
112 | */ | |
113 | ||
114 | OPENSSL_free(pubkey); | |
115 | return 1; | |
116 | } | |
117 | ||
118 | =head1 SEE ALSO | |
119 | ||
0a737e16 | 120 | L<EVP_PKEY_new(3)>, L<EVP_PKEY_copy_parameters(3)>, |
3795b2a3 MC |
121 | L<EVP_PKEY_derive_init(3)>, L<EVP_PKEY_derive(3)>, |
122 | L<EVP_PKEY-DH(7)>, L<EVP_PKEY-EC(7)>, L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)> | |
123 | ||
124 | =head1 HISTORY | |
125 | ||
0a737e16 MC |
126 | EVP_PKEY_set1_encoded_public_key() and EVP_PKEY_get1_encoded_public_key() were |
127 | added in OpenSSL 3.0. | |
128 | ||
129 | EVP_PKEY_set1_tls_encodedpoint() and EVP_PKEY_get1_tls_encodedpoint() were | |
130 | deprecated in OpenSSL 3.0. | |
3795b2a3 MC |
131 | |
132 | =head1 COPYRIGHT | |
133 | ||
134 | Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. | |
135 | ||
136 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
137 | this file except in compliance with the License. You can obtain a copy | |
138 | in the file LICENSE in the source distribution or at | |
139 | L<https://www.openssl.org/source/license.html>. | |
140 | ||
141 | =cut | |
142 |