xref: /freebsd/crypto/openssl/doc/man3/EVP_PKEY_set1_RSA.pod (revision 5ca8e32633c4ffbbcd6762e5888b6a4ba0708c6c) 
1=pod
2
3=head1 NAME
4
5EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY,
6EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY,
7EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY,
8EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH,
9EVP_PKEY_assign_EC_KEY, EVP_PKEY_assign_POLY1305, EVP_PKEY_assign_SIPHASH,
10EVP_PKEY_get0_hmac, EVP_PKEY_get0_poly1305, EVP_PKEY_get0_siphash,
11EVP_PKEY_get0, EVP_PKEY_type, EVP_PKEY_get_id, EVP_PKEY_get_base_id,
12EVP_PKEY_set1_engine, EVP_PKEY_get0_engine,
13EVP_PKEY_id, EVP_PKEY_base_id -
14EVP_PKEY assignment functions
15
16=head1 SYNOPSIS
17
18 #include <openssl/evp.h>
19
20 int EVP_PKEY_get_id(const EVP_PKEY *pkey);
21 int EVP_PKEY_get_base_id(const EVP_PKEY *pkey);
22 int EVP_PKEY_type(int type);
23
24 #define EVP_PKEY_id EVP_PKEY_get_id
25 #define EVP_PKEY_base_id EVP_PKEY_get_base_id
26
27The following functions have been deprecated since OpenSSL 3.0, and can be
28hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
29see L<openssl_user_macros(7)>:
30
31 int EVP_PKEY_set1_RSA(EVP_PKEY *pkey, RSA *key);
32 int EVP_PKEY_set1_DSA(EVP_PKEY *pkey, DSA *key);
33 int EVP_PKEY_set1_DH(EVP_PKEY *pkey, DH *key);
34 int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey, EC_KEY *key);
35
36 RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey);
37 DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey);
38 DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey);
39 EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey);
40
41 const unsigned char *EVP_PKEY_get0_hmac(const EVP_PKEY *pkey, size_t *len);
42 const unsigned char *EVP_PKEY_get0_poly1305(const EVP_PKEY *pkey, size_t *len);
43 const unsigned char *EVP_PKEY_get0_siphash(const EVP_PKEY *pkey, size_t *len);
44 const RSA *EVP_PKEY_get0_RSA(const EVP_PKEY *pkey);
45 const DSA *EVP_PKEY_get0_DSA(const EVP_PKEY *pkey);
46 const DH *EVP_PKEY_get0_DH(const EVP_PKEY *pkey);
47 const EC_KEY *EVP_PKEY_get0_EC_KEY(const EVP_PKEY *pkey);
48 void *EVP_PKEY_get0(const EVP_PKEY *pkey);
49
50 int EVP_PKEY_assign_RSA(EVP_PKEY *pkey, RSA *key);
51 int EVP_PKEY_assign_DSA(EVP_PKEY *pkey, DSA *key);
52 int EVP_PKEY_assign_DH(EVP_PKEY *pkey, DH *key);
53 int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey, EC_KEY *key);
54 int EVP_PKEY_assign_POLY1305(EVP_PKEY *pkey, ASN1_OCTET_STRING *key);
55 int EVP_PKEY_assign_SIPHASH(EVP_PKEY *pkey, ASN1_OCTET_STRING *key);
56
57 ENGINE *EVP_PKEY_get0_engine(const EVP_PKEY *pkey);
58 int EVP_PKEY_set1_engine(EVP_PKEY *pkey, ENGINE *engine);
59
60=head1 DESCRIPTION
61
62EVP_PKEY_get_base_id() returns the type of I<pkey>. For example
63an RSA key will return B<EVP_PKEY_RSA>.
64
65EVP_PKEY_get_id() returns the actual NID associated with I<pkey>
66only if the I<pkey> type isn't implemented just in a L<provider(7)>.
67Historically keys using the same algorithm could use different NIDs.
68For example an RSA key could use the NIDs corresponding to
69the NIDs B<NID_rsaEncryption> (equivalent to B<EVP_PKEY_RSA>) or
70B<NID_rsa> (equivalent to B<EVP_PKEY_RSA2>). The use of
71alternative non-standard NIDs is now rare so B<EVP_PKEY_RSA2> et al are not
72often seen in practice.
73EVP_PKEY_get_id() returns -1 (B<EVP_PKEY_KEYMGMT>) if the I<pkey> is
74only implemented in a L<provider(7)>.
75
76EVP_PKEY_type() returns the underlying type of the NID I<type>. For example
77EVP_PKEY_type(EVP_PKEY_RSA2) will return B<EVP_PKEY_RSA>.
78
79EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
80EVP_PKEY_set1_EC_KEY() set the key referenced by I<pkey> to I<key>. These
81functions are deprecated. Applications should instead use
82L<EVP_PKEY_fromdata(3)>.
83
84EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(),
85EVP_PKEY_assign_EC_KEY(), EVP_PKEY_assign_POLY1305() and
86EVP_PKEY_assign_SIPHASH() set the referenced key to I<key> however these use
87the supplied I<key> internally and so I<key> will be freed when the parent
88I<pkey> is freed. These macros are deprecated. Applications should instead read
89an EVP_PKEY directly using the OSSL_DECODER APIs (see
90L<OSSL_DECODER_CTX_new_for_pkey(3)>), or construct an EVP_PKEY from data using
91L<EVP_PKEY_fromdata(3)>.
92
93EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
94EVP_PKEY_get1_EC_KEY() return the referenced key in I<pkey> or NULL if the
95key is not of the correct type. The returned key must be freed after use.
96These functions are deprecated. Applications should instead use the EVP_PKEY
97directly where possible. If access to the low level key parameters is required
98then applications should use L<EVP_PKEY_get_params(3)> and other similar
99functions. To write an EVP_PKEY out use the OSSL_ENCODER APIs (see
100L<OSSL_ENCODER_CTX_new_for_pkey(3)>).
101
102EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash(),
103EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_DH() and
104EVP_PKEY_get0_EC_KEY() return the referenced key in I<pkey> or NULL if the
105key is not of the correct type. The reference count of the returned key is
106B<not> incremented and so the key must not be freed after use. These functions
107are deprecated. Applications should instead use the EVP_PKEY directly where
108possible. If access to the low level key parameters is required then
109applications should use L<EVP_PKEY_get_params(3)> and other similar functions.
110To write an EVP_PKEY out use the OSSL_ENCODER APIs (see
111L<OSSL_ENCODER_CTX_new_for_pkey(3)>). EVP_PKEY_get0() returns a pointer to the
112legacy key or NULL if the key is not legacy.
113
114Note that if an EVP_PKEY was not constructed using one of the deprecated
115functions such as EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH()
116or EVP_PKEY_set1_EC_KEY(), or via the similarly named B<EVP_PKEY_assign> macros
117described above then the internal key will be managed by a provider (see
118L<provider(7)>). In that case the key returned by EVP_PKEY_get1_RSA(),
119EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH(), EVP_PKEY_get1_EC_KEY(),
120EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash(),
121EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_DH() or
122EVP_PKEY_get0_EC_KEY() will be a cached copy of the provider's key. Subsequent
123updates to the provider's key will not be reflected back in the cached copy, and
124updates made by an application to the returned key will not be reflected back in
125the provider's key. Subsequent calls to EVP_PKEY_get1_RSA(),
126EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and EVP_PKEY_get1_EC_KEY() will always
127return the cached copy returned by the first call.
128
129EVP_PKEY_get0_engine() returns a reference to the ENGINE handling I<pkey>. This
130function is deprecated. Applications should use providers instead of engines
131(see L<provider(7)> for details).
132
133EVP_PKEY_set1_engine() sets the ENGINE handling I<pkey> to I<engine>. It
134must be called after the key algorithm and components are set up.
135If I<engine> does not include an B<EVP_PKEY_METHOD> for I<pkey> an
136error occurs. This function is deprecated. Applications should use providers
137instead of engines (see L<provider(7)> for details).
138
139=head1 WARNINGS
140
141The following functions are only reliable with B<EVP_PKEY>s that have
142been assigned an internal key with EVP_PKEY_assign_*():
143
144EVP_PKEY_get_id(), EVP_PKEY_get_base_id(), EVP_PKEY_type()
145
146For EVP_PKEY key type checking purposes, L<EVP_PKEY_is_a(3)> is more generic.
147
148For purposes of retrieving the name of the B<EVP_PKEY> the function
149L<EVP_PKEY_get0_type_name(3)> is more generally useful.
150
151The keys returned from the functions EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(),
152EVP_PKEY_get0_DH() and EVP_PKEY_get0_EC_KEY() were changed to have a "const"
153return type in OpenSSL 3.0. As described above the keys returned may be cached
154copies of the key held in a provider. Due to this, and unlike in earlier
155versions of OpenSSL, they should be considered read-only copies of the key.
156Updates to these keys will not be reflected back in the provider side key. The
157EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
158EVP_PKEY_get1_EC_KEY() functions were not changed to have a "const" return type
159in order that applications can "free" the return value. However applications
160should still consider them as read-only copies.
161
162=head1 NOTES
163
164In accordance with the OpenSSL naming convention the key obtained
165from or assigned to the I<pkey> using the B<1> functions must be
166freed as well as I<pkey>.
167
168EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(),
169EVP_PKEY_assign_EC_KEY(), EVP_PKEY_assign_POLY1305()
170and EVP_PKEY_assign_SIPHASH() are implemented as macros.
171
172EVP_PKEY_assign_EC_KEY() looks at the curve name id to determine if
173the passed B<EC_KEY> is an L<SM2(7)> key, and will set the B<EVP_PKEY>
174type to B<EVP_PKEY_SM2> in that case, instead of B<EVP_PKEY_EC>.
175
176Most applications wishing to know a key type will simply call
177EVP_PKEY_get_base_id() and will not care about the actual type:
178which will be identical in almost all cases.
179
180Previous versions of this document suggested using EVP_PKEY_type(pkey->type)
181to determine the type of a key. Since B<EVP_PKEY> is now opaque this
182is no longer possible: the equivalent is EVP_PKEY_get_base_id(pkey).
183
184EVP_PKEY_set1_engine() is typically used by an ENGINE returning an HSM
185key as part of its routine to load a private key.
186
187=head1 RETURN VALUES
188
189EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
190EVP_PKEY_set1_EC_KEY() return 1 for success or 0 for failure.
191
192EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
193EVP_PKEY_get1_EC_KEY() return the referenced key or NULL if
194an error occurred.
195
196EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(),
197EVP_PKEY_assign_EC_KEY(), EVP_PKEY_assign_POLY1305()
198and EVP_PKEY_assign_SIPHASH() return 1 for success and 0 for failure.
199
200EVP_PKEY_get_base_id(), EVP_PKEY_get_id() and EVP_PKEY_type() return a key
201type or B<NID_undef> (equivalently B<EVP_PKEY_NONE>) on error.
202
203EVP_PKEY_set1_engine() returns 1 for success and 0 for failure.
204
205=head1 SEE ALSO
206
207L<EVP_PKEY_new(3)>, L<SM2(7)>
208
209=head1 HISTORY
210
211The EVP_PKEY_id() and EVP_PKEY_base_id() functions were renamed to
212include C<get> in their names in OpenSSL 3.0, respectively. The old names
213are kept as non-deprecated alias macros.
214
215EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY,
216EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY,
217EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY,
218EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH,
219EVP_PKEY_assign_EC_KEY, EVP_PKEY_assign_POLY1305, EVP_PKEY_assign_SIPHASH,
220EVP_PKEY_get0_hmac, EVP_PKEY_get0_poly1305, EVP_PKEY_get0_siphash,
221EVP_PKEY_set1_engine and EVP_PKEY_get0_engine were deprecated in OpenSSL 3.0.
222
223The return value from EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH,
224EVP_PKEY_get0_EC_KEY were made const in OpenSSL 3.0.
225
226The function EVP_PKEY_set_alias_type() was previously documented on this page.
227It was removed in OpenSSL 3.0.
228
229=head1 COPYRIGHT
230
231Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved.
232
233Licensed under the Apache License 2.0 (the "License").  You may not use
234this file except in compliance with the License.  You can obtain a copy
235in the file LICENSE in the source distribution or at
236L<https://www.openssl.org/source/license.html>.
237
238=cut
239