summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/RSA_meth_new.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/RSA_meth_new.3')
-rw-r--r--src/lib/libcrypto/man/RSA_meth_new.3606
1 files changed, 0 insertions, 606 deletions
diff --git a/src/lib/libcrypto/man/RSA_meth_new.3 b/src/lib/libcrypto/man/RSA_meth_new.3
deleted file mode 100644
index a3a5c549e5..0000000000
--- a/src/lib/libcrypto/man/RSA_meth_new.3
+++ /dev/null
@@ -1,606 +0,0 @@
1.\" $OpenBSD: RSA_meth_new.3,v 1.6 2025/01/05 15:40:42 tb Exp $
2.\" full merge up to: OpenSSL a970b14f Jul 31 18:58:40 2017 -0400
3.\" selective merge up to: OpenSSL 24907560 Sep 17 07:47:42 2018 +1000
4.\"
5.\" This file is a derived work.
6.\" The changes are covered by the following Copyright and license:
7.\"
8.\" Copyright (c) 2018, 2019 Ingo Schwarze <schwarze@openbsd.org>
9.\"
10.\" Permission to use, copy, modify, and distribute this software for any
11.\" purpose with or without fee is hereby granted, provided that the above
12.\" copyright notice and this permission notice appear in all copies.
13.\"
14.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
15.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
16.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
17.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
18.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
19.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
20.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
21.\"
22.\" The original file was written by Richard Levitte <levitte@openssl.org>.
23.\" Copyright (c) 2016 The OpenSSL Project. All rights reserved.
24.\"
25.\" Redistribution and use in source and binary forms, with or without
26.\" modification, are permitted provided that the following conditions
27.\" are met:
28.\"
29.\" 1. Redistributions of source code must retain the above copyright
30.\" notice, this list of conditions and the following disclaimer.
31.\"
32.\" 2. Redistributions in binary form must reproduce the above copyright
33.\" notice, this list of conditions and the following disclaimer in
34.\" the documentation and/or other materials provided with the
35.\" distribution.
36.\"
37.\" 3. All advertising materials mentioning features or use of this
38.\" software must display the following acknowledgment:
39.\" "This product includes software developed by the OpenSSL Project
40.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
41.\"
42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
43.\" endorse or promote products derived from this software without
44.\" prior written permission. For written permission, please contact
45.\" openssl-core@openssl.org.
46.\"
47.\" 5. Products derived from this software may not be called "OpenSSL"
48.\" nor may "OpenSSL" appear in their names without prior written
49.\" permission of the OpenSSL Project.
50.\"
51.\" 6. Redistributions of any form whatsoever must retain the following
52.\" acknowledgment:
53.\" "This product includes software developed by the OpenSSL Project
54.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
55.\"
56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
59.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
67.\" OF THE POSSIBILITY OF SUCH DAMAGE.
68.\"
69.Dd $Mdocdate: January 5 2025 $
70.Dt RSA_METH_NEW 3
71.Os
72.Sh NAME
73.Nm RSA_meth_new ,
74.Nm RSA_meth_dup ,
75.Nm RSA_meth_free ,
76.Nm RSA_meth_get0_name ,
77.Nm RSA_meth_set1_name ,
78.Nm RSA_meth_get_flags ,
79.Nm RSA_meth_set_flags ,
80.Nm RSA_meth_get0_app_data ,
81.Nm RSA_meth_set0_app_data ,
82.Nm RSA_meth_get_init ,
83.Nm RSA_meth_set_init ,
84.Nm RSA_meth_get_finish ,
85.Nm RSA_meth_set_finish ,
86.Nm RSA_meth_get_pub_enc ,
87.Nm RSA_meth_set_pub_enc ,
88.Nm RSA_meth_get_pub_dec ,
89.Nm RSA_meth_set_pub_dec ,
90.Nm RSA_meth_get_priv_enc ,
91.Nm RSA_meth_set_priv_enc ,
92.Nm RSA_meth_get_priv_dec ,
93.Nm RSA_meth_set_priv_dec ,
94.Nm RSA_meth_get_sign ,
95.Nm RSA_meth_set_sign ,
96.Nm RSA_meth_get_verify ,
97.Nm RSA_meth_set_verify ,
98.Nm RSA_meth_get_mod_exp ,
99.Nm RSA_meth_set_mod_exp ,
100.Nm RSA_meth_get_bn_mod_exp ,
101.Nm RSA_meth_set_bn_mod_exp ,
102.Nm RSA_meth_get_keygen ,
103.Nm RSA_meth_set_keygen
104.Nd build up RSA methods
105.Sh SYNOPSIS
106.In openssl/rsa.h
107.Ft RSA_METHOD *
108.Fo RSA_meth_new
109.Fa "const char *name"
110.Fa "int flags"
111.Fc
112.Ft RSA_METHOD *
113.Fo RSA_meth_dup
114.Fa "const RSA_METHOD *meth"
115.Fc
116.Ft void
117.Fo RSA_meth_free
118.Fa "RSA_METHOD *meth"
119.Fc
120.Ft const char *
121.Fo RSA_meth_get0_name
122.Fa "const RSA_METHOD *meth"
123.Fc
124.Ft int
125.Fo RSA_meth_set1_name
126.Fa "RSA_METHOD *meth"
127.Fa "const char *name"
128.Fc
129.Ft int
130.Fo RSA_meth_get_flags
131.Fa "const RSA_METHOD *meth"
132.Fc
133.Ft int
134.Fo RSA_meth_set_flags
135.Fa "RSA_METHOD *meth"
136.Fa "int flags"
137.Fc
138.Ft void *
139.Fo RSA_meth_get0_app_data
140.Fa "const RSA_METHOD *meth"
141.Fc
142.Ft int
143.Fo RSA_meth_set0_app_data
144.Fa "RSA_METHOD *meth"
145.Fa "void *app_data"
146.Fc
147.Ft int
148.Fo "(*RSA_meth_get_init(const RSA_METHOD *meth))"
149.Fa "RSA *rsa"
150.Fc
151.Ft int
152.Fo "RSA_meth_set_init"
153.Fa "RSA_METHOD *meth"
154.Fa "int (*init)(RSA *rsa)"
155.Fc
156.Ft int
157.Fo "(*RSA_meth_get_finish(const RSA_METHOD *meth))"
158.Fa "RSA *rsa"
159.Fc
160.Ft int
161.Fo RSA_meth_set_finish
162.Fa "RSA_METHOD *meth"
163.Fa "int (*finish)(RSA *rsa)"
164.Fc
165.Ft int
166.Fo "(*RSA_meth_get_pub_enc(const RSA_METHOD *meth))"
167.Fa "int flen"
168.Fa "const unsigned char *from"
169.Fa "unsigned char *to"
170.Fa "RSA *rsa"
171.Fa "int padding"
172.Fc
173.Ft int
174.Fo RSA_meth_set_pub_enc
175.Fa "RSA_METHOD *meth"
176.Fa "int (*pub_enc)(int flen, const unsigned char *from,\
177 unsigned char *to, RSA *rsa, int padding)"
178.Fc
179.Ft int
180.Fo "(*RSA_meth_get_pub_dec(const RSA_METHOD *meth))"
181.Fa "int flen"
182.Fa "const unsigned char *from"
183.Fa "unsigned char *to"
184.Fa "RSA *rsa"
185.Fa "int padding"
186.Fc
187.Ft int
188.Fo RSA_meth_set_pub_dec
189.Fa "RSA_METHOD *meth"
190.Fa "int (*pub_dec)(int flen, const unsigned char *from,\
191 unsigned char *to, RSA *rsa, int padding)"
192.Fc
193.Ft int
194.Fo "(*RSA_meth_get_priv_enc(const RSA_METHOD *meth))"
195.Fa "int flen"
196.Fa "const unsigned char *from"
197.Fa "unsigned char *to"
198.Fa "RSA *rsa"
199.Fa "int padding"
200.Fc
201.Ft int
202.Fo RSA_meth_set_priv_enc
203.Fa "RSA_METHOD *meth"
204.Fa "int (*priv_enc)(int flen, const unsigned char *from,\
205 unsigned char *to, RSA *rsa, int padding)"
206.Fc
207.Ft int
208.Fo "(*RSA_meth_get_priv_dec(const RSA_METHOD *meth))"
209.Fa "int flen"
210.Fa "const unsigned char *from"
211.Fa "unsigned char *to"
212.Fa "RSA *rsa"
213.Fa "int padding"
214.Fc
215.Ft int
216.Fo RSA_meth_set_priv_dec
217.Fa "RSA_METHOD *meth"
218.Fa "int (*priv_dec)(int flen, const unsigned char *from,\
219 unsigned char *to, RSA *rsa, int padding)"
220.Fc
221.Ft int
222.Fo "(*RSA_meth_get_sign(const RSA_METHOD *meth))"
223.Fa "int type"
224.Fa "const unsigned char *m"
225.Fa "unsigned int m_length"
226.Fa "unsigned char *sigret"
227.Fa "unsigned int *siglen"
228.Fa "const RSA *rsa"
229.Fc
230.Ft int
231.Fo RSA_meth_set_sign
232.Fa "RSA_METHOD *rsa"
233.Fa "int (*sign)(int type, const unsigned char *m, unsigned int m_length,\
234 unsigned char *sigret, unsigned int *siglen, const RSA *rsa)"
235.Fc
236.Ft int
237.Fo "(*RSA_meth_get_verify(const RSA_METHOD *meth))"
238.Fa "int dtype"
239.Fa "const unsigned char *m"
240.Fa "unsigned int m_length"
241.Fa "const unsigned char *sigbuf"
242.Fa "unsigned int siglen"
243.Fa "const RSA *rsa"
244.Fc
245.Ft int
246.Fo RSA_meth_set_verify
247.Fa "RSA_METHOD *rsa"
248.Fa "int (*verify)(int dtype, const unsigned char *m,\
249 unsigned int m_length, const unsigned char *sigbuf,\
250 unsigned int siglen, const RSA *rsa)"
251.Fc
252.Ft int
253.Fo "(*RSA_meth_get_mod_exp(const RSA_METHOD *meth))"
254.Fa "BIGNUM *r0"
255.Fa "const BIGNUM *i"
256.Fa "RSA *rsa"
257.Fa "BN_CTX *ctx"
258.Fc
259.Ft int
260.Fo RSA_meth_set_mod_exp
261.Fa "RSA_METHOD *meth"
262.Fa "int (*mod_exp)(BIGNUM *r0, const BIGNUM *i, RSA *rsa, BN_CTX *ctx)"
263.Fc
264.Ft int
265.Fo "(*RSA_meth_get_bn_mod_exp(const RSA_METHOD *meth))"
266.Fa "BIGNUM *r"
267.Fa "const BIGNUM *a"
268.Fa "const BIGNUM *p"
269.Fa "const BIGNUM *m"
270.Fa "BN_CTX *ctx"
271.Fa "BN_MONT_CTX *m_ctx"
272.Fc
273.Ft int
274.Fo RSA_meth_set_bn_mod_exp
275.Fa "RSA_METHOD *meth"
276.Fa "int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,\
277 const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx)"
278.Fc
279.Ft int
280.Fo "(*RSA_meth_get_keygen(const RSA_METHOD *meth))"
281.Fa "RSA *rsa"
282.Fa "int bits"
283.Fa "BIGNUM *e"
284.Fa "BN_GENCB *cb"
285.Fc
286.Ft int
287.Fo RSA_meth_set_keygen
288.Fa "RSA_METHOD *meth"
289.Fa "int (*keygen)(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb)"
290.Fc
291.Sh DESCRIPTION
292The
293.Vt RSA_METHOD
294structure holds function pointers for custom RSA implementations.
295.Pp
296.Fn RSA_meth_new
297creates a new
298.Vt RSA_METHOD
299structure.
300A copy of the NUL-terminated
301.Fa name
302is stored in the new
303.Vt RSA_METHOD
304object.
305Any new
306.Vt RSA
307object constructed from this
308.Vt RSA_METHOD
309will have the given
310.Fa flags
311set by default, as if they were set with
312.Xr RSA_set_flags 3 .
313.Pp
314.Fn RSA_meth_dup
315creates a deep copy of
316.Fa meth ,
317except that a pointer stored into it with
318.Fn RSA_meth_set0_app_data
319is copied as a pointer without creating a copy of its content.
320This might be useful for creating a new
321.Vt RSA_METHOD
322based on an existing one, but with some differences.
323.Pp
324.Fn RSA_meth_free
325destroys
326.Fa meth
327and frees any memory associated with it,
328except that memory pointed to by a pointer set with
329.Fn RSA_meth_set0_app_data
330is not freed.
331If
332.Fa meth
333is
334.Dv NULL ,
335no action occurs.
336.Pp
337.Fn RSA_meth_get0_name
338returns an internal pointer to the name of
339.Fa meth .
340.Fn RSA_meth_set1_name
341stores a copy of the NUL-terminated
342.Fa name
343in the
344.Vt RSA_METHOD
345object after freeing the previously stored name.
346Method names are ignored by the default RSA implementation
347but can be used by alternative implementations
348and by the application program.
349.Pp
350.Fn RSA_meth_get_flags
351retrieves the flags from
352.Fa meth .
353Flags are documented in
354.Xr RSA_test_flags 3 .
355.Fn RSA_meth_set_flags
356overwrites all flags in
357.Fa meth .
358Unlike
359.Xr RSA_set_flags 3 ,
360it does not preserve any flags that were set before the call.
361.Pp
362.Fn RSA_meth_get0_app_data
363and
364.Fn RSA_meth_set0_app_data
365get and set a pointer to implementation-specific data.
366The function
367.Fn RSA_meth_free
368does not
369.Xr free 3
370the memory pointed to by
371.Fa app_data .
372The default RSA implementation does not use
373.Fa app_data .
374.Pp
375.Fn RSA_meth_get_init
376and
377.Fn RSA_meth_set_init
378get and set an optional function used when creating a new
379.Vt RSA
380object.
381Unless
382.Fa init
383is
384.Dv NULL ,
385it will be called at the end of
386.Xr RSA_new 3 ,
387.Xr RSA_new_method 3 ,
388and
389.Xr RSA_set_method 3 ,
390passing a pointer to the newly allocated or reset
391.Vt RSA
392object as an argument.
393The default RSA implementation,
394.Xr RSA_PKCS1_SSLeay 3 ,
395contains an
396.Fa init
397function equivalent to calling
398.Xr RSA_set_flags 3
399with an argument of
400.Dv RSA_FLAG_CACHE_PUBLIC | RSA_FLAG_CACHE_PRIVATE .
401.Pp
402.Fn RSA_meth_get_finish
403and
404.Fn RSA_meth_set_finish
405get and set an optional function for destroying an
406.Vt RSA
407object.
408Unless
409.Fa finish
410is
411.Dv NULL ,
412it will be called from
413.Xr RSA_set_method 3
414and from
415.Xr RSA_free 3 .
416It takes the same argument as
417.Xr RSA_free 3
418and is intended to do RSA implementation specific cleanup.
419The memory used by the
420.Vt RSA
421object itself should not be freed by the
422.Fa finish
423function.
424The default RSA implementation contains a
425.Fa finish
426function freeing the memory used by the
427.Dv RSA_FLAG_CACHE_PUBLIC
428and
429.Dv RSA_FLAG_CACHE_PRIVATE
430caches.
431.Pp
432.Fn RSA_meth_get_pub_enc ,
433.Fn RSA_meth_set_pub_enc ,
434.Fn RSA_meth_get_pub_dec ,
435.Fn RSA_meth_set_pub_dec ,
436.Fn RSA_meth_get_priv_enc ,
437.Fn RSA_meth_set_priv_enc ,
438.Fn RSA_meth_get_priv_dec ,
439and
440.Fn RSA_meth_set_priv_dec
441get and set the mandatory functions
442used for public and private key encryption and decryption.
443These functions will be called from
444.Xr RSA_public_encrypt 3 ,
445.Xr RSA_public_decrypt 3 ,
446.Xr RSA_private_encrypt 3 ,
447and
448.Xr RSA_private_decrypt 3 ,
449respectively, and take the same parameters as those.
450.Pp
451.Fn RSA_meth_get_sign ,
452.Fn RSA_meth_set_sign ,
453.Fn RSA_meth_get_verify ,
454and
455.Fn RSA_meth_set_verify
456get and set the optional functions
457used for creating and verifying an RSA signature.
458.Pp
459.Fn RSA_meth_get_mod_exp
460and
461.Fn RSA_meth_set_mod_exp
462get and set the function
463used for Chinese Remainder Theorem (CRT) computations involving the
464.Fa p ,
465.Fa q ,
466.Fa dmp1 ,
467.Fa dmq1 ,
468and
469.Fa iqmp
470fields of an
471.Vt RSA
472object.
473It is used by the default RSA implementation during
474.Xr RSA_private_encrypt 3
475and
476.Xr RSA_private_decrypt 3
477when the required components of the private key are available
478or when the
479.Dv RSA_FLAG_EXT_PKEY
480flag is set.
481.Pp
482.Fn RSA_meth_get_bn_mod_exp
483and
484.Fn RSA_meth_set_bn_mod_exp
485get and set the function used for CRT computations,
486specifically the value r =
487.Fa a
488\(ha
489.Fa p
490mod
491.Fa m .
492It is used by the default RSA implementation during
493.Xr RSA_public_encrypt 3
494and
495.Xr RSA_public_decrypt 3
496and as a fallback during
497.Xr RSA_private_encrypt 3
498and
499.Xr RSA_private_decrypt 3 .
500.Pp
501.Fn RSA_meth_get_keygen
502and
503.Fn RSA_meth_set_keygen
504get and set the optional function used for generating a new RSA key pair.
505Unless
506.Fa keygen
507is
508.Dv NULL ,
509it will be called from
510.Xr RSA_generate_key_ex 3
511and takes the same parameters.
512Otherwise, a builtin default implementation is used.
513.Sh RETURN VALUES
514.Fn RSA_meth_new
515and
516.Fn RSA_meth_dup
517return the newly allocated
518.Vt RSA_METHOD
519object or
520.Dv NULL
521on failure.
522.Pp
523.Fn RSA_meth_get0_name
524returns an internal pointer which must not be freed by the caller.
525.Pp
526.Fn RSA_meth_get_flags
527returns zero or more
528.Dv RSA_FLAG_*
529constants OR'ed together, or 0 if no flags are set in
530.Fa meth .
531.Pp
532.Fn RSA_meth_get0_app_data
533returns the pointer that was earlier passed to
534.Fn RSA_meth_set0_app_data
535or
536.Dv NULL
537otherwise.
538.Pp
539All other
540.Fn RSA_meth_get_*
541functions return the appropriate function pointer that has been set
542with the corresponding
543.Fn RSA_meth_set_*
544function, or
545.Dv NULL
546if no such pointer has been set in
547.Fa meth .
548.Pp
549All
550.Fn RSA_meth_set*
551functions return 1 on success or 0 on failure.
552In the current implementation, only
553.Fn RSA_meth_set1_name
554can actually fail.
555.Sh SEE ALSO
556.Xr RSA_generate_key_ex 3 ,
557.Xr RSA_new 3 ,
558.Xr RSA_private_encrypt 3 ,
559.Xr RSA_public_encrypt 3 ,
560.Xr RSA_set_flags 3 ,
561.Xr RSA_set_method 3 ,
562.Xr RSA_sign 3
563.Sh HISTORY
564These functions first appeared in OpenSSL 1.1.0.
565.Fn RSA_meth_new ,
566.Fn RSA_meth_dup ,
567.Fn RSA_meth_free ,
568.Fn RSA_meth_set_finish ,
569.Fn RSA_meth_set_priv_enc ,
570and
571.Fn RSA_meth_set_priv_dec
572have been available since
573.Ox 6.3 ,
574.Fn RSA_meth_set1_name
575and
576.Fn RSA_meth_get_finish
577since
578.Ox 6.4 ,
579and
580.Fn RSA_meth_get0_name ,
581.Fn RSA_meth_get_flags ,
582.Fn RSA_meth_set_flags ,
583.Fn RSA_meth_get0_app_data ,
584.Fn RSA_meth_set0_app_data ,
585.Fn RSA_meth_get_init ,
586.Fn RSA_meth_set_init ,
587.Fn RSA_meth_set_finish ,
588.Fn RSA_meth_get_pub_enc ,
589.Fn RSA_meth_set_pub_enc ,
590.Fn RSA_meth_get_pub_dec ,
591.Fn RSA_meth_set_pub_dec ,
592.Fn RSA_meth_get_priv_enc ,
593.Fn RSA_meth_get_priv_dec ,
594.Fn RSA_meth_get_sign ,
595.Fn RSA_meth_set_sign ,
596.Fn RSA_meth_get_verify ,
597.Fn RSA_meth_set_verify ,
598.Fn RSA_meth_get_mod_exp ,
599.Fn RSA_meth_set_mod_exp ,
600.Fn RSA_meth_get_bn_mod_exp ,
601.Fn RSA_meth_set_bn_mod_exp ,
602.Fn RSA_meth_get_keygen ,
603and
604.Fn RSA_meth_set_keygen
605since
606.Ox 6.6 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-06 16:42:44 +0000