summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/RSA_pkey_ctx_ctrl.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/RSA_pkey_ctx_ctrl.3')
-rw-r--r--src/lib/libcrypto/man/RSA_pkey_ctx_ctrl.3402
1 files changed, 0 insertions, 402 deletions
diff --git a/src/lib/libcrypto/man/RSA_pkey_ctx_ctrl.3 b/src/lib/libcrypto/man/RSA_pkey_ctx_ctrl.3
deleted file mode 100644
index 3d4e79cc47..0000000000
--- a/src/lib/libcrypto/man/RSA_pkey_ctx_ctrl.3
+++ /dev/null
@@ -1,402 +0,0 @@
1.\" $OpenBSD: RSA_pkey_ctx_ctrl.3,v 1.8 2024/12/06 14:27:49 schwarze Exp $
2.\" full merge up to:
3.\" OpenSSL man3/EVP_PKEY_CTX_ctrl.pod 99d63d46 Oct 26 13:56:48 2016 -0400
4.\" OpenSSL man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod
5.\" 87103969 Oct 1 14:11:57 2018 -0700
6.\" selective merge up to:
7.\" OpenSSL man3/EVP_PKEY_CTX_ctrl.pod df75c2b f Dec 9 01:02:36 2018 +0100
8.\"
9.\" This file was written by Dr. Stephen Henson <steve@openssl.org>
10.\" and Antoine Salon <asalon@vmware.com>.
11.\" Copyright (c) 2006, 2009, 2013, 2014, 2015, 2017, 2018 The OpenSSL Project.
12.\" All rights reserved.
13.\"
14.\" Redistribution and use in source and binary forms, with or without
15.\" modification, are permitted provided that the following conditions
16.\" are met:
17.\"
18.\" 1. Redistributions of source code must retain the above copyright
19.\" notice, this list of conditions and the following disclaimer.
20.\"
21.\" 2. Redistributions in binary form must reproduce the above copyright
22.\" notice, this list of conditions and the following disclaimer in
23.\" the documentation and/or other materials provided with the
24.\" distribution.
25.\"
26.\" 3. All advertising materials mentioning features or use of this
27.\" software must display the following acknowledgment:
28.\" "This product includes software developed by the OpenSSL Project
29.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
30.\"
31.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
32.\" endorse or promote products derived from this software without
33.\" prior written permission. For written permission, please contact
34.\" openssl-core@openssl.org.
35.\"
36.\" 5. Products derived from this software may not be called "OpenSSL"
37.\" nor may "OpenSSL" appear in their names without prior written
38.\" permission of the OpenSSL Project.
39.\"
40.\" 6. Redistributions of any form whatsoever must retain the following
41.\" acknowledgment:
42.\" "This product includes software developed by the OpenSSL Project
43.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
44.\"
45.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
46.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
47.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
48.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
49.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
50.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
51.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
52.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
53.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
54.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
55.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
56.\" OF THE POSSIBILITY OF SUCH DAMAGE.
57.\"
58.Dd $Mdocdate: December 6 2024 $
59.Dt RSA_PKEY_CTX_CTRL 3
60.Os
61.Sh NAME
62.Nm RSA_pkey_ctx_ctrl ,
63.Nm EVP_PKEY_CTX_set_rsa_padding ,
64.Nm EVP_PKEY_CTX_get_rsa_padding ,
65.Nm EVP_PKEY_CTX_set_rsa_keygen_bits ,
66.Nm EVP_PKEY_CTX_set_rsa_keygen_pubexp ,
67.Nm EVP_PKEY_CTX_set_rsa_mgf1_md ,
68.Nm EVP_PKEY_CTX_get_rsa_mgf1_md ,
69.Nm EVP_PKEY_CTX_set_rsa_oaep_md ,
70.Nm EVP_PKEY_CTX_get_rsa_oaep_md ,
71.Nm EVP_PKEY_CTX_set0_rsa_oaep_label ,
72.Nm EVP_PKEY_CTX_get0_rsa_oaep_label ,
73.Nm EVP_PKEY_CTX_set_rsa_pss_saltlen ,
74.Nm EVP_PKEY_CTX_get_rsa_pss_saltlen ,
75.Nm EVP_PKEY_CTX_set_rsa_pss_keygen_md ,
76.Nm EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md ,
77.Nm EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen
78.Nd RSA private key control operations
79.Sh SYNOPSIS
80.In openssl/rsa.h
81.Ft int
82.Fo RSA_pkey_ctx_ctrl
83.Fa "EVP_PKEY_CTX *ctx"
84.Fa "int optype"
85.Fa "int cmd"
86.Fa "int p1"
87.Fa "void *p2"
88.Fc
89.Ft int
90.Fo EVP_PKEY_CTX_set_rsa_padding
91.Fa "EVP_PKEY_CTX *ctx"
92.Fa "int pad"
93.Fc
94.Ft int
95.Fo EVP_PKEY_CTX_get_rsa_padding
96.Fa "EVP_PKEY_CTX *ctx"
97.Fa "int *ppad"
98.Fc
99.Ft int
100.Fo EVP_PKEY_CTX_set_rsa_keygen_bits
101.Fa "EVP_PKEY_CTX *ctx"
102.Fa "int mbits"
103.Fc
104.Ft int
105.Fo EVP_PKEY_CTX_set_rsa_keygen_pubexp
106.Fa "EVP_PKEY_CTX *ctx"
107.Fa "BIGNUM *pubexp"
108.Fc
109.Ft int
110.Fo EVP_PKEY_CTX_set_rsa_mgf1_md
111.Fa "EVP_PKEY_CTX *ctx"
112.Fa "const EVP_MD *md"
113.Fc
114.Ft int
115.Fo EVP_PKEY_CTX_get_rsa_mgf1_md
116.Fa "EVP_PKEY_CTX *ctx"
117.Fa "const EVP_MD **pmd"
118.Fc
119.Ft int
120.Fo EVP_PKEY_CTX_set_rsa_oaep_md
121.Fa "EVP_PKEY_CTX *ctx"
122.Fa "const EVP_MD *md"
123.Fc
124.Ft int
125.Fo EVP_PKEY_CTX_get_rsa_oaep_md
126.Fa "EVP_PKEY_CTX *ctx"
127.Fa "const EVP_MD **pmd"
128.Fc
129.Ft int
130.Fo EVP_PKEY_CTX_set0_rsa_oaep_label
131.Fa "EVP_PKEY_CTX *ctx"
132.Fa "unsigned char *label"
133.Fa "int len"
134.Fc
135.Ft int
136.Fo EVP_PKEY_CTX_get0_rsa_oaep_label
137.Fa "EVP_PKEY_CTX *ctx"
138.Fa "unsigned char **plabel"
139.Fc
140.Ft int
141.Fo EVP_PKEY_CTX_set_rsa_pss_saltlen
142.Fa "EVP_PKEY_CTX *ctx"
143.Fa "int len"
144.Fc
145.Ft int
146.Fo EVP_PKEY_CTX_get_rsa_pss_saltlen
147.Fa "EVP_PKEY_CTX *ctx"
148.Fa "int *plen"
149.Fc
150.Ft int
151.Fo EVP_PKEY_CTX_set_rsa_pss_keygen_md
152.Fa "EVP_PKEY_CTX *pctx"
153.Fa "const EVP_MD *md"
154.Fc
155.Ft int
156.Fo EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md
157.Fa "EVP_PKEY_CTX *pctx"
158.Fa "const EVP_MD *md"
159.Fc
160.Ft int
161.Fo EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen
162.Fa "EVP_PKEY_CTX *pctx"
163.Fa "int saltlen"
164.Fc
165.Sh DESCRIPTION
166The function
167.Fn RSA_pkey_ctx_ctrl
168is a shallow wrapper around
169.Xr EVP_PKEY_CTX_ctrl 3
170which only succeeds if
171.Fa ctx
172matches either
173.Dv EVP_PKEY_RSA
174or
175.Dv EVP_PKEY_RSA_PSS .
176.Pp
177All the remaining "functions" are implemented as macros.
178.Pp
179The
180.Fn EVP_PKEY_CTX_set_rsa_padding
181macro sets the RSA padding mode for
182.Fa ctx .
183The
184.Fa pad
185parameter can take the value
186.Dv RSA_PKCS1_PADDING
187for PKCS#1 padding,
188.Dv RSA_NO_PADDING
189for no padding,
190.Dv RSA_PKCS1_OAEP_PADDING
191for OAEP padding (encrypt and decrypt only),
192.Dv RSA_X931_PADDING
193for X9.31 padding (signature operations only) and
194.Dv RSA_PKCS1_PSS_PADDING
195(sign and verify only).
196Only the last one can be used with keys of the type
197.Dv EVP_PKEY_RSA_PSS .
198.Pp
199Two RSA padding modes behave differently if
200.Xr EVP_PKEY_CTX_set_signature_md 3
201is used.
202If this macro is called for PKCS#1 padding, the plaintext buffer is an
203actual digest value and is encapsulated in a
204.Vt DigestInfo
205structure according to PKCS#1 when signing and this structure is
206expected (and stripped off) when verifying.
207If this control is not used with RSA and PKCS#1 padding then the
208supplied data is used directly and not encapsulated.
209In the case of X9.31 padding for RSA the algorithm identifier byte is
210added or checked and removed if this control is called.
211If it is not called then the first byte of the plaintext buffer is
212expected to be the algorithm identifier byte.
213.Pp
214The
215.Fn EVP_PKEY_CTX_get_rsa_padding
216macro retrieves the RSA padding mode for
217.Fa ctx .
218.Pp
219The
220.Fn EVP_PKEY_CTX_set_rsa_keygen_bits
221macro sets the RSA key length for RSA or RSA-PSS key generation to
222.Fa mbits .
223The smallest supported value is 512 bits.
224If not specified, 1024 bits is used.
225.Pp
226The
227.Fn EVP_PKEY_CTX_set_rsa_keygen_pubexp
228macro sets the public exponent value for RSA or RSA-PSS key generation to
229.Fa pubexp .
230Currently, it should be an odd integer.
231The
232.Fa pubexp
233pointer is used internally by this function, so it should not be modified
234or freed after the call.
235If this macro is not called, then 65537 is used.
236.Pp
237The
238.Fn EVP_PKEY_CTX_set_rsa_mgf1_md
239macro sets the MGF1 digest for RSA padding schemes to
240.Fa md .
241Unless explicitly specified, the signing digest is used.
242The padding mode must have been set to
243.Dv RSA_PKCS1_OAEP_PADDING
244or
245.Dv RSA_PKCS1_PSS_PADDING .
246If the key is of the type
247.Dv EVP_PKEY_RSA_PSS
248and has usage restrictions, an error occurs if an attempt is made
249to set the digest to anything other than the restricted value.
250.Pp
251The
252.Fn EVP_PKEY_CTX_get_rsa_mgf1_md
253macro retrieves the MGF1 digest for
254.Fa ctx .
255Unless explicitly specified, the signing digest is used.
256The padding mode must have been set to
257.Dv RSA_PKCS1_OAEP_PADDING
258or
259.Dv RSA_PKCS1_PSS_PADDING .
260.Ss Optimal asymmetric encryption padding
261The following macros require that the padding mode was set to
262.Dv RSA_PKCS1_OAEP_PADDING .
263.Pp
264The
265.Fn EVP_PKEY_CTX_set_rsa_oaep_md
266macro sets the message digest type used in RSA OAEP to
267.Fa md .
268.Pp
269The
270.Fn EVP_PKEY_CTX_get_rsa_oaep_md
271macro gets the message digest type used in RSA OAEP to
272.Pf * Fa pmd .
273.Pp
274The
275.Fn EVP_PKEY_CTX_set0_rsa_oaep_label
276macro sets the RSA OAEP label to
277.Fa label
278and its length to
279.Fa len .
280If
281.Fa label
282is
283.Dv NULL
284or
285.Fa len
286is 0, the label is cleared.
287The library takes ownership of the label so the caller should not
288free the original memory pointed to by
289.Fa label .
290.Pp
291The
292.Fn EVP_PKEY_CTX_get0_rsa_oaep_label
293macro gets the RSA OAEP label to
294.Pf * Fa plabel .
295The return value is the label length.
296The resulting pointer is owned by the library and should not be
297freed by the caller.
298.Ss Probabilistic signature scheme
299The following macros require that the padding mode was set to
300.Dv RSA_PKCS1_PSS_PADDING .
301.Pp
302The
303.Fn EVP_PKEY_CTX_set_rsa_pss_saltlen
304macro sets the RSA PSS salt length to
305.Fa len .
306Three special values are supported:
307.Dv RSA_PSS_SALTLEN_DIGEST
308sets the salt length to the digest length.
309.Dv RSA_PSS_SALTLEN_MAX
310sets the salt length to the maximum permissible value.
311When signing,
312.Dv RSA_PSS_SALTLEN_AUTO
313sets the salt length to the maximum permissible value.
314When verifying,
315.Dv RSA_PSS_SALTLEN_AUTO
316causes the salt length to be automatically determined based on the
317PSS block structure.
318If this macro is not called, a salt length value of
319.Dv RSA_PSS_SALTLEN_AUTO
320is used by default.
321.Pp
322If the key has usage restrictions and an attempt is made to set the
323salt length below the minimum value, an error occurs.
324Also, if the key has usage restrictions,
325.Dv RSA_PSS_SALTLEN_AUTO
326is not supported for verification.
327.Pp
328The
329.Fn EVP_PKEY_CTX_get_rsa_pss_saltlen
330macro retrieves the RSA PSS salt length for
331.Fa ctx .
332.Pp
333Optional parameter restrictions can be specified when generating a PSS
334key.
335If any restrictions are set using the macros described below,
336then all parameters are restricted.
337For example, setting a minimum salt length also restricts the digest and
338MGF1 algorithms.
339If any restrictions are in place, then they are reflected in the
340corresponding parameters of the public key when (for example) a
341certificate request is signed.
342.Pp
343.Fn EVP_PKEY_CTX_set_rsa_pss_keygen_md
344restricts the digest algorithm the generated key can use to
345.Fa md .
346.Pp
347.Fn EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md
348restricts the MGF1 algorithm the generated key can use to
349.Fa md .
350.Pp
351.Fn EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen
352restricts the minimum salt length to
353.Fa saltlen .
354.Sh RETURN VALUES
355These functions return a positive value for success or 0 or a negative
356value for failure.
357In particular, a return value of -2 indicates the operation is not
358supported by the public key algorithm.
359.Sh SEE ALSO
360.Xr EVP_DigestInit 3 ,
361.Xr EVP_PKEY_CTX_ctrl 3 ,
362.Xr EVP_PKEY_CTX_new 3 ,
363.Xr EVP_PKEY_decrypt 3 ,
364.Xr EVP_PKEY_derive 3 ,
365.Xr EVP_PKEY_encrypt 3 ,
366.Xr EVP_PKEY_get_default_digest_nid 3 ,
367.Xr EVP_PKEY_keygen 3 ,
368.Xr EVP_PKEY_sign 3 ,
369.Xr EVP_PKEY_verify 3 ,
370.Xr EVP_PKEY_verify_recover 3
371.Sh HISTORY
372The functions
373.Fn EVP_PKEY_CTX_set_rsa_padding ,
374.Fn EVP_PKEY_CTX_set_rsa_keygen_bits ,
375.Fn EVP_PKEY_CTX_set_rsa_keygen_pubexp ,
376and
377.Fn EVP_PKEY_CTX_set_rsa_pss_saltlen
378first appeared in OpenSSL 1.0.0 and have been available since
379.Ox 4.9 .
380.Pp
381The functions
382.Fn EVP_PKEY_CTX_get_rsa_padding ,
383.Fn EVP_PKEY_CTX_set_rsa_mgf1_md ,
384.Fn EVP_PKEY_CTX_get_rsa_mgf1_md ,
385and
386.Fn EVP_PKEY_CTX_get_rsa_pss_saltlen
387first appeared in OpenSSL 1.0.1 and have been available since
388.Ox 5.3 .
389.Pp
390The functions
391.Fn EVP_PKEY_CTX_set_rsa_oaep_md ,
392.Fn EVP_PKEY_CTX_get_rsa_oaep_md ,
393.Fn EVP_PKEY_CTX_set0_rsa_oaep_label ,
394and
395.Fn EVP_PKEY_CTX_get0_rsa_oaep_label
396first appeared in OpenSSL 1.0.2 and have been available since
397.Ox 6.7 .
398.Pp
399The function
400.Fn RSA_pkey_ctx_ctrl
401first appeared in OpenSSL 1.1.1 and has been available since
402.Ox 6.7 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-06 16:16:47 +0000