summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man')
-rw-r--r--src/lib/libcrypto/man/Makefile32
-rw-r--r--src/lib/libcrypto/man/RSA_blinding_on.346
-rw-r--r--src/lib/libcrypto/man/RSA_check_key.397
-rw-r--r--src/lib/libcrypto/man/RSA_generate_key.3105
-rw-r--r--src/lib/libcrypto/man/RSA_get_ex_new_index.3227
-rw-r--r--src/lib/libcrypto/man/RSA_new.346
-rw-r--r--src/lib/libcrypto/man/RSA_padding_add_PKCS1_type_1.3197
-rw-r--r--src/lib/libcrypto/man/RSA_print.391
-rw-r--r--src/lib/libcrypto/man/RSA_private_encrypt.397
-rw-r--r--src/lib/libcrypto/man/RSA_public_encrypt.3108
-rw-r--r--src/lib/libcrypto/man/RSA_set_method.3339
-rw-r--r--src/lib/libcrypto/man/RSA_sign.3103
-rw-r--r--src/lib/libcrypto/man/RSA_sign_ASN1_OCTET_STRING.381
-rw-r--r--src/lib/libcrypto/man/RSA_size.327
-rw-r--r--src/lib/libcrypto/man/d2i_RSAPublicKey.3101
-rw-r--r--src/lib/libcrypto/man/rsa.3238
16 files changed, 1919 insertions, 16 deletions
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 0b3a08a7d3..8bc8ffb6aa 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
1# $OpenBSD: Makefile,v 1.44 2016/11/03 15:48:22 schwarze Exp $ 1# $OpenBSD: Makefile,v 1.45 2016/11/04 10:17:17 schwarze Exp $
2 2
3.include <bsd.own.mk> # for NOMAN 3.include <bsd.own.mk> # for NOMAN
4 4
@@ -137,6 +137,19 @@ MAN= \
137 RAND_cleanup.3 \ 137 RAND_cleanup.3 \
138 RAND_load_file.3 \ 138 RAND_load_file.3 \
139 RAND_set_rand_method.3 \ 139 RAND_set_rand_method.3 \
140 RSA_blinding_on.3 \
141 RSA_check_key.3 \
142 RSA_generate_key.3 \
143 RSA_get_ex_new_index.3 \
144 RSA_new.3 \
145 RSA_padding_add_PKCS1_type_1.3 \
146 RSA_print.3 \
147 RSA_private_encrypt.3 \
148 RSA_public_encrypt.3 \
149 RSA_set_method.3 \
150 RSA_sign.3 \
151 RSA_sign_ASN1_OCTET_STRING.3 \
152 RSA_size.3 \
140 SMIME_read_PKCS7.3 \ 153 SMIME_read_PKCS7.3 \
141 SMIME_write_PKCS7.3 \ 154 SMIME_write_PKCS7.3 \
142 UI_new.3 \ 155 UI_new.3 \
@@ -144,27 +157,16 @@ MAN= \
144 crypto.3 \ 157 crypto.3 \
145 d2i_ASN1_OBJECT.3 \ 158 d2i_ASN1_OBJECT.3 \
146 d2i_PKCS8PrivateKey_bio.3 \ 159 d2i_PKCS8PrivateKey_bio.3 \
160 d2i_RSAPublicKey.3 \
147 des_read_pw.3 \ 161 des_read_pw.3 \
148 evp.3 \ 162 evp.3 \
149 i2d_PKCS7_bio_stream.3 \ 163 i2d_PKCS7_bio_stream.3 \
150 lh_new.3 \ 164 lh_new.3 \
165 rsa.3 \
151 166
152GENMAN= \ 167GENMAN= \
153 RC4.3 \ 168 RC4.3 \
154 RIPEMD160.3 \ 169 RIPEMD160.3 \
155 RSA_blinding_on.3 \
156 RSA_check_key.3 \
157 RSA_generate_key.3 \
158 RSA_get_ex_new_index.3 \
159 RSA_new.3 \
160 RSA_padding_add_PKCS1_type_1.3 \
161 RSA_print.3 \
162 RSA_private_encrypt.3 \
163 RSA_public_encrypt.3 \
164 RSA_set_method.3 \
165 RSA_sign.3 \
166 RSA_sign_ASN1_OCTET_STRING.3 \
167 RSA_size.3 \
168 SHA1.3 \ 170 SHA1.3 \
169 X509_NAME_ENTRY_get_object.3 \ 171 X509_NAME_ENTRY_get_object.3 \
170 X509_NAME_add_entry_by_txt.3 \ 172 X509_NAME_add_entry_by_txt.3 \
@@ -182,7 +184,6 @@ GENMAN= \
182 d2i_DHparams.3 \ 184 d2i_DHparams.3 \
183 d2i_DSAPublicKey.3 \ 185 d2i_DSAPublicKey.3 \
184 d2i_ECPKParameters.3 \ 186 d2i_ECPKParameters.3 \
185 d2i_RSAPublicKey.3 \
186 d2i_X509.3 \ 187 d2i_X509.3 \
187 d2i_X509_ALGOR.3 \ 188 d2i_X509_ALGOR.3 \
188 d2i_X509_CRL.3 \ 189 d2i_X509_CRL.3 \
@@ -194,7 +195,6 @@ GENMAN= \
194 ec.3 \ 195 ec.3 \
195 engine.3 \ 196 engine.3 \
196 lh_stats.3 \ 197 lh_stats.3 \
197 rsa.3 \
198 x509.3 \ 198 x509.3 \
199 199
200MAN+= ${GENMAN} 200MAN+= ${GENMAN}
diff --git a/src/lib/libcrypto/man/RSA_blinding_on.3 b/src/lib/libcrypto/man/RSA_blinding_on.3
new file mode 100644
index 0000000000..a2d22c9093
--- /dev/null
+++ b/src/lib/libcrypto/man/RSA_blinding_on.3
@@ -0,0 +1,46 @@
1.Dd $Mdocdate: November 4 2016 $
2.Dt RSA_BLINDING_ON 3
3.Os
4.Sh NAME
5.Nm RSA_blinding_on ,
6.Nm RSA_blinding_off
7.Nd protect the RSA operation from timing attacks
8.Sh SYNOPSIS
9.In openssl/rsa.h
10.Ft int
11.Fo RSA_blinding_on
12.Fa "RSA *rsa"
13.Fa "BN_CTX *ctx"
14.Fc
15.Ft void
16.Fo RSA_blinding_off
17.Fa "RSA *rsa"
18.Fc
19.Sh DESCRIPTION
20RSA is vulnerable to timing attacks.
21In a setup where attackers can measure the time of RSA decryption or
22signature operations, blinding must be used to protect the RSA operation
23from that attack.
24.Pp
25.Fn RSA_blinding_on
26turns blinding on for key
27.Fa rsa
28and generates a random blinding factor.
29.Fa ctx
30is
31.Dv NULL
32or a pre-allocated and initialized
33.Vt BN_CTX .
34.Pp
35.Fn RSA_blinding_off
36turns blinding off and frees the memory used for the blinding factor.
37.Sh RETURN VALUES
38.Fn RSA_blinding_on
39returns 1 on success, and 0 if an error occurred.
40.Sh SEE ALSO
41.Xr rsa 3
42.Sh HISTORY
43.Fn RSA_blinding_on
44and
45.Fn RSA_blinding_off
46appeared in SSLeay 0.9.0.
diff --git a/src/lib/libcrypto/man/RSA_check_key.3 b/src/lib/libcrypto/man/RSA_check_key.3
new file mode 100644
index 0000000000..c57ed4b4db
--- /dev/null
+++ b/src/lib/libcrypto/man/RSA_check_key.3
@@ -0,0 +1,97 @@
1.Dd $Mdocdate: November 4 2016 $
2.Dt RSA_CHECK_KEY 3
3.Os
4.Sh NAME
5.Nm RSA_check_key
6.Nd validate private RSA keys
7.Sh SYNOPSIS
8.In openssl/rsa.h
9.Ft int
10.Fo RSA_check_key
11.Fa "RSA *rsa"
12.Fc
13.Sh DESCRIPTION
14This function validates RSA keys.
15It checks that
16.Fa rsa->p
17and
18.Fa rsa->q
19are in fact prime, and that
20.Fa rsa->n
21satifies n = p*q.
22.Pp
23It also checks that
24.Fa rsa->d
25and
26.Fa rsa->e
27satisfy d*e = 1 mod ((p-1)*(q-1)),
28and that
29.Fa rsa->dmp1 ,
30.Fa rsa->dmq1 ,
31and
32.Fa resa->iqmp
33are set correctly or are
34.Dv NULL .
35.Pp
36As such, this function cannot be used with any arbitrary
37.Vt RSA
38key object, even if it is otherwise fit for regular RSA operation.
39.Pp
40This function does not work on RSA public keys that have only the
41modulus and public exponent elements populated.
42It performs integrity checks on all the RSA key material, so the
43.Vt RSA
44key structure must contain all the private key data too.
45.Pp
46Unlike most other RSA functions, this function does
47.Sy not
48work transparently with any underlying
49.Vt ENGINE
50implementation because it uses the key data in the
51.Vt RSA
52structure directly.
53An
54.Vt ENGINE
55implementation can override the way key data is stored and handled,
56and can even provide support for HSM keys - in which case the
57.Vt RSA
58structure may contain
59.Sy no
60key data at all!
61If the
62.Vt ENGINE
63in question is only being used for acceleration or analysis purposes,
64then in all likelihood the RSA key data is complete and untouched,
65but this can't be assumed in the general case.
66.Sh RETURN VALUE
67.Fn RSA_check_key
68returns 1 if
69.Fa rsa
70is a valid RSA key, and 0 otherwise.
71-1 is returned if an error occurs while checking the key.
72.Pp
73If the key is invalid or an error occurred, the reason code can be
74obtained using
75.Xr ERR_get_error 3 .
76.Sh SEE ALSO
77.Xr ERR_get_error 3 ,
78.Xr rsa 3
79.Sh HISTORY
80.Fn RSA_check_key
81appeared in OpenSSL 0.9.4.
82.Sh BUGS
83A method of verifying the RSA key using opaque RSA API functions might
84need to be considered.
85Right now
86.Fn RSA_check_key
87simply uses the
88.Vt RSA
89structure elements directly, bypassing the
90.Vt RSA_METHOD
91table altogether (and completely violating encapsulation and
92object-orientation in the process).
93The best fix will probably be to introduce a check_key() handler
94to the
95.Vt RSA_METHOD
96function table so that alternative implementations can also provide
97their own verifiers.
diff --git a/src/lib/libcrypto/man/RSA_generate_key.3 b/src/lib/libcrypto/man/RSA_generate_key.3
new file mode 100644
index 0000000000..a9e72c6594
--- /dev/null
+++ b/src/lib/libcrypto/man/RSA_generate_key.3
@@ -0,0 +1,105 @@
1.Dd $Mdocdate: November 4 2016 $
2.Dt RSA_GENERATE_KEY 3
3.Os
4.Sh NAME
5.Nm RSA_generate_key_ex ,
6.Nm RSA_generate_key
7.Nd generate RSA key pair
8.Sh SYNOPSIS
9.In openssl/rsa.h
10.Ft int
11.Fo RSA_generate_key_ex
12.Fa "RSA *rsa"
13.Fa "int bits"
14.Fa "BIGNUM *e"
15.Fa "BN_GENCB *cb"
16.Fc
17.Pp
18Deprecated:
19.Pp
20.Ft RSA *
21.Fo RSA_generate_key
22.Fa "int num"
23.Fa "unsigned long e"
24.Fa "void (*callback)(int, int, void *)"
25.Fa "void *cb_arg"
26.Fc
27.Sh DESCRIPTION
28.Fn RSA_generate_key_ex
29generates a key pair and stores it in
30.Fa rsa .
31.Pp
32The modulus size will be of length
33.Fa bits ,
34and the public exponent will be
35.Fa e .
36Key sizes with
37.Fa num
38< 1024 should be considered insecure.
39The exponent is an odd number, typically 3, 17 or 65537.
40.Pp
41A callback function may be used to provide feedback about the progress
42of the key generation.
43If
44.Fa cb
45is not
46.Dv NULL ,
47it will be called as follows using the
48.Xr BN_GENCB_call 3
49function:
50.Bl -bullet
51.It
52While a random prime number is generated, it is called as described in
53.Xr BN_generate_prime 3 .
54.It
55When the
56.Fa n Ns -th
57randomly generated prime is rejected as not suitable for
58the key,
59.Fn BN_GENCB_call cb 2 n
60is called.
61.It
62When a random p has been found with p-1 relatively prime to
63.Fa e ,
64it is called as
65.Fn BN_GENCB_call cb 3 0 .
66.El
67.Pp
68The process is then repeated for prime q with
69.Fn BN_GENCB_call cb 3 1 .
70.Pp
71.Fn RSA_generate_key
72is deprecated.
73New applications should use
74.Fn RSA_generate_key_ex
75instead.
76.Fn RSA_generate_key
77works in the same was as
78.Fn RSA_generate_key_ex
79except it uses "old style" call backs.
80See
81.Xr BN_generate_prime 3
82for further details.
83.Sh RETURN VALUE
84If key generation fails,
85.Fn RSA_generate_key
86returns
87.Dv NULL .
88.Pp
89The error codes can be obtained by
90.Xr ERR_get_error 3 .
91.Sh SEE ALSO
92.Xr BN_generate_prime 3 ,
93.Xr ERR_get_error 3 ,
94.Xr rsa 3 ,
95.Xr RSA_free 3
96.Sh HISTORY
97The
98.Fa cb_arg
99argument was added in SSLeay 0.9.0.
100.Sh BUGS
101.Fn BN_GENCB_call cb 2 x
102is used with two different meanings.
103.Pp
104.Fn RSA_generate_key
105goes into an infinite loop for illegal input values.
diff --git a/src/lib/libcrypto/man/RSA_get_ex_new_index.3 b/src/lib/libcrypto/man/RSA_get_ex_new_index.3
new file mode 100644
index 0000000000..b61084a18e
--- /dev/null
+++ b/src/lib/libcrypto/man/RSA_get_ex_new_index.3
@@ -0,0 +1,227 @@
1.Dd $Mdocdate: November 4 2016 $
2.Dt RSA_GET_EX_NEW_INDEX 3
3.Os
4.Sh NAME
5.Nm RSA_get_ex_new_index ,
6.Nm RSA_set_ex_data ,
7.Nm RSA_get_ex_data
8.Nd add application specific data to RSA structures
9.Sh SYNOPSIS
10.In openssl/rsa.h
11.Ft int
12.Fo RSA_get_ex_new_index
13.Fa "long argl"
14.Fa "void *argp"
15.Fa "CRYPTO_EX_new *new_func"
16.Fa "CRYPTO_EX_dup *dup_func"
17.Fa "CRYPTO_EX_free *free_func"
18.Fc
19.Ft int
20.Fo RSA_set_ex_data
21.Fa "RSA *r"
22.Fa "int idx"
23.Fa "void *arg"
24.Fc
25.Ft void *
26.Fo RSA_get_ex_data
27.Fa "RSA *r"
28.Fa "int idx"
29.Fc
30.Ft typedef int
31.Fo CRYPTO_EX_new
32.Fa "void *parent"
33.Fa "void *ptr"
34.Fa "CRYPTO_EX_DATA *ad"
35.Fa "int idx"
36.Fa "long argl"
37.Fa "void *argp"
38.Fc
39.Ft typedef void
40.Fo CRYPTO_EX_free
41.Fa "void *parent"
42.Fa "void *ptr"
43.Fa "CRYPTO_EX_DATA *ad"
44.Fa "int idx"
45.Fa "long argl"
46.Fa "void *argp"
47.Fc
48.Ft typedef int
49.Fo CRYPTO_EX_dup
50.Fa "CRYPTO_EX_DATA *to"
51.Fa "CRYPTO_EX_DATA *from"
52.Fa "void *from_d"
53.Fa "int idx"
54.Fa "long argl"
55.Fa "void *argp"
56.Fc
57.Sh DESCRIPTION
58Several OpenSSL structures can have application specific data attached
59to them.
60This has several potential uses, it can be used to cache data associated
61with a structure (for example the hash of some part of the structure) or
62some additional data (for example a handle to the data in an external
63library).
64.Pp
65Since the application data can be anything at all it is passed and
66retrieved as a
67.Vt void *
68type.
69.Pp
70The
71.Fn RSA_get_ex_new_index
72function is initially called to "register" some new application specific
73data.
74It takes three optional function pointers which are called when the
75parent structure (in this case an RSA structure) is initially created,
76when it is copied and when it is freed up.
77If any or all of these function pointer arguments are not used, they
78should be set to
79.Dv NULL .
80The precise manner in which these function pointers are called is
81described in more detail below.
82.Fn RSA_get_ex_new_index
83also takes additional long and pointer parameters which will be passed
84to the supplied functions but which otherwise have no special meaning.
85It returns an index which should be stored (typically in a static
86variable) and passed as the
87.Fa idx
88parameter in the remaining functions.
89Each successful call to
90.Fn RSA_get_ex_new_index
91will return an index greater than any previously returned.
92This is
93important because the optional functions are called in order of
94increasing index value.
95.Pp
96.Fn RSA_set_ex_data
97is used to set application specific data, the data is supplied in the
98.Fa arg
99parameter and its precise meaning is up to the application.
100.Pp
101.Fn RSA_get_ex_data
102is used to retrieve application specific data.
103The data is returned to the application, this will be the same value as
104supplied to a previous
105.Fn RSA_set_ex_data
106call.
107.Pp
108.Fa new_func
109is called when a structure is initially allocated (for example with
110.Xr RSA_new 3 .
111The parent structure members will not have any meaningful values at this
112point.
113This function will typically be used to allocate any application
114specific structure.
115.Pp
116.Fa free_func
117is called when a structure is being freed up.
118The dynamic parent structure members should not be accessed because they
119will be freed up when this function is called.
120.Pp
121.Fa new_func
122and
123.Fa free_func
124take the same parameters.
125.Fa parent
126is a pointer to the parent
127.Vt RSA
128structure.
129.Fa ptr
130is the application specific data (this won't be of much use in
131.Fa new_func ) .
132.Fa ad
133is a pointer to the
134.Vt CRYPTO_EX_DATA
135structure from the parent
136.Vt RSA
137structure: the functions
138.Fn CRYPTO_get_ex_data
139and
140.Fn CRYPTO_set_ex_data
141can be called to manipulate it.
142The
143.Fa idx
144parameter is the index: this will be the same value returned by
145.Fn RSA_get_ex_new_index
146when the functions were initially registered.
147Finally the
148.Fa argl
149and
150.Fa argp
151parameters are the values originally passed to the same corresponding
152parameters when
153.Fn RSA_get_ex_new_index
154was called.
155.Pp
156.Fa dup_func
157is called when a structure is being copied.
158Pointers to the destination and source
159.Vt CRYPTO_EX_DATA
160structures are passed in the
161.Fa to
162and
163.Fa from
164parameters, respectively.
165The
166.Fa from_d
167parameter is passed a pointer to the source application data when the
168function is called.
169When the function returns, the value is copied to the destination:
170the application can thus modify the data pointed to by
171.Fa from_d
172and have different values in the source and destination.
173The
174.Fa idx ,
175.Fa argl ,
176and
177.Fa argp
178parameters are the same as those in
179.Fa new_func
180and
181.Fa free_func .
182.Sh RETURN VALUES
183.Fn RSA_get_ex_new_index
184returns a new index or -1 on failure.
185Note that 0 is a valid index value.
186.Pp
187.Fn RSA_set_ex_data
188returns 1 on success or 0 on failure.
189.Pp
190.Fn RSA_get_ex_data
191returns the application data or
192.Dv NULL
193on failure.
194.Dv NULL
195may also be valid application data, but currently it can only fail if
196given an invalid
197.Fa idx
198parameter.
199.Pp
200.Fa new_func
201and
202.Fa dup_func
203should return 0 for failure and 1 for success.
204.Pp
205On failure an error code can be obtained from
206.Xr ERR_get_error 3 .
207.Sh SEE ALSO
208.Xr CRYPTO_set_ex_data 3 ,
209.Xr rsa 3
210.Sh HISTORY
211.Fn RSA_get_ex_new_index ,
212.Fn RSA_set_ex_data ,
213and
214.Fn RSA_get_ex_data
215are available since SSLeay 0.9.0.
216.Sh BUGS
217.Fa dup_func
218is currently never called.
219.Pp
220The return value of
221.Fa new_func
222is ignored.
223.Pp
224The
225.Fa new_func
226function isn't very useful because no meaningful values are present in
227the parent RSA structure when it is called.
diff --git a/src/lib/libcrypto/man/RSA_new.3 b/src/lib/libcrypto/man/RSA_new.3
new file mode 100644
index 0000000000..b01c8cd089
--- /dev/null
+++ b/src/lib/libcrypto/man/RSA_new.3
@@ -0,0 +1,46 @@
1.Dd $Mdocdate: November 4 2016 $
2.Dt RSA_NEW 3
3.Os
4.Sh NAME
5.Nm RSA_new ,
6.Nm RSA_free
7.Nd allocate and free RSA objects
8.Sh SYNOPSIS
9.In openssl/rsa.h
10.Ft RSA *
11.Fn RSA_new void
12.Ft void
13.Fo RSA_free
14.Fa "RSA *rsa"
15.Fc
16.Sh DESCRIPTION
17.Fn RSA_new
18allocates and initializes an
19.Vt RSA
20structure.
21It is equivalent to calling
22.Fn RSA_new_method NULL .
23.Pp
24.Fn RSA_free
25frees the
26.Vt RSA
27structure and its components.
28The key is erased before the memory is returned to the system.
29.Sh RETURN VALUES
30If the allocation fails,
31.Fn RSA_new
32returns
33.Dv NULL
34and sets an error code that can be obtained by
35.Xr ERR_get_error 3 .
36Otherwise it returns a pointer to the newly allocated structure.
37.Sh SEE ALSO
38.Xr ERR_get_error 3 ,
39.Xr rsa 3 ,
40.Xr RSA_generate_key 3 ,
41.Xr RSA_new_method 3
42.Sh HISTORY
43.Fn RSA_new
44and
45.Fn RSA_free
46are available in all versions of SSLeay and OpenSSL.
diff --git a/src/lib/libcrypto/man/RSA_padding_add_PKCS1_type_1.3 b/src/lib/libcrypto/man/RSA_padding_add_PKCS1_type_1.3
new file mode 100644
index 0000000000..7724f45970
--- /dev/null
+++ b/src/lib/libcrypto/man/RSA_padding_add_PKCS1_type_1.3
@@ -0,0 +1,197 @@
1.Dd $Mdocdate: November 4 2016 $
2.Dt RSA_PADDING_ADD_PKCS1_TYPE_1 3
3.Os
4.Sh NAME
5.Nm RSA_padding_add_PKCS1_type_1 ,
6.Nm RSA_padding_check_PKCS1_type_1 ,
7.Nm RSA_padding_add_PKCS1_type_2 ,
8.Nm RSA_padding_check_PKCS1_type_2 ,
9.Nm RSA_padding_add_PKCS1_OAEP ,
10.Nm RSA_padding_check_PKCS1_OAEP ,
11.Nm RSA_padding_add_SSLv23 ,
12.Nm RSA_padding_check_SSLv23 ,
13.Nm RSA_padding_add_none ,
14.Nm RSA_padding_check_none
15.Nd asymmetric encryption padding
16.Sh SYNOPSIS
17.In openssl/rsa.h
18.Ft int
19.Fo RSA_padding_add_PKCS1_type_1
20.Fa "unsigned char *to"
21.Fa "int tlen"
22.Fa "unsigned char *f"
23.Fa "int fl"
24.Fc
25.Ft int
26.Fo RSA_padding_check_PKCS1_type_1
27.Fa "unsigned char *to"
28.Fa "int tlen"
29.Fa "unsigned char *f"
30.Fa "int fl"
31.Fa "int rsa_len"
32.Fc
33.Ft int
34.Fo RSA_padding_add_PKCS1_type_2
35.Fa "unsigned char *to"
36.Fa "int tlen"
37.Fa "unsigned char *f"
38.Fa "int fl"
39.Fc
40.Ft int
41.Fo RSA_padding_check_PKCS1_type_2
42.Fa "unsigned char *to"
43.Fa "int tlen"
44.Fa "unsigned char *f"
45.Fa "int fl"
46.Fa "int rsa_len"
47.Fc
48.Ft int
49.Fo RSA_padding_add_PKCS1_OAEP
50.Fa "unsigned char *to"
51.Fa "int tlen"
52.Fa "unsigned char *f"
53.Fa "int fl"
54.Fa "unsigned char *p"
55.Fa "int pl"
56.Fc
57.Ft int
58.Fo RSA_padding_check_PKCS1_OAEP
59.Fa "unsigned char *to"
60.Fa "int tlen"
61.Fa "unsigned char *f"
62.Fa "int fl"
63.Fa "int rsa_len"
64.Fa "unsigned char *p"
65.Fa "int pl"
66.Fc
67.Ft int
68.Fo RSA_padding_add_SSLv23
69.Fa "unsigned char *to"
70.Fa "int tlen"
71.Fa "unsigned char *f"
72.Fa "int fl"
73.Fc
74.Ft int
75.Fo RSA_padding_check_SSLv23
76.Fa "unsigned char *to"
77.Fa "int tlen"
78.Fa "unsigned char *f"
79.Fa "int fl"
80.Fa "int rsa_len"
81.Fc
82.Ft int
83.Fo RSA_padding_add_none
84.Fa "unsigned char *to"
85.Fa "int tlen"
86.Fa "unsigned char *f"
87.Fa "int fl"
88.Fc
89.Ft int
90.Fo RSA_padding_check_none
91.Fa "unsigned char *to"
92.Fa "int tlen"
93.Fa "unsigned char *f"
94.Fa "int fl"
95.Fa "int rsa_len"
96.Fc
97.Sh DESCRIPTION
98These functions are called from the RSA encrypt, decrypt, sign, and
99verify functions.
100Normally they should not be called from application programs.
101.Pp
102However, they can also be called directly to implement padding for other
103asymmetric ciphers.
104.Fn RSA_padding_add_PKCS1_OAEP
105and
106.Fn RSA_padding_check_PKCS1_OAEP
107may be used in an application combined with
108.Dv RSA_NO_PADDING
109in order to implement OAEP with an encoding parameter.
110.Pp
111.Fn RSA_padding_add_*
112encodes
113.Fa fl
114bytes from
115.Fa f
116so as to fit into
117.Fa tlen
118bytes and stores the result at
119.Fa to .
120An error occurs if
121.Fa fl
122does not meet the size requirements of the encoding method.
123.Pp
124The following encoding methods are implemented:
125.Pp
126.Bl -tag -width PKCS1_type_2 -compact
127.It PKCS1_type_1
128PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1);
129used for signatures
130.It PKCS1_type_2
131PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2)
132.It PKCS1_OAEP
133PKCS #1 v2.0 EME-OAEP
134.It SSLv23
135PKCS #1 EME-PKCS1-v1_5 with SSL-specific modification
136.It none
137simply copy the data
138.El
139.Pp
140.Fn RSA_padding_check_*
141verifies that the
142.Fa fl
143bytes at
144.Fa f
145contain a valid encoding for a
146.Fa rsa_len
147byte RSA key in the respective encoding method and stores the recovered
148data of at most
149.Fa tlen
150bytes (for
151.Dv RSA_NO_PADDING :
152of size
153.Fa tlen )
154at
155.Fa to .
156.Pp
157For
158.Fn RSA_padding_*_OAEP ,
159.Fa p
160points to the encoding parameter of length
161.Fa pl .
162.Fa p
163may be
164.Dv NULL
165if
166.Fa pl
167is 0.
168.Sh RETURN VALUES
169The
170.Fn RSA_padding_add_*
171functions return 1 on success or 0 on error.
172The
173.Fn RSA_padding_check_*
174functions return the length of the recovered data or -1 on error.
175Error codes can be obtained by calling
176.Xr ERR_get_error 3 .
177.Sh SEE ALSO
178.Xr RSA_private_decrypt 3 ,
179.Xr RSA_public_encrypt 3 ,
180.Xr RSA_sign 3 ,
181.Xr RSA_verify 3
182.Sh HISTORY
183.Fn RSA_padding_add_PKCS1_type_1 ,
184.Fn RSA_padding_check_PKCS1_type_1 ,
185.Fn RSA_padding_add_PKCS1_type_2 ,
186.Fn RSA_padding_check_PKCS1_type_2 ,
187.Fn RSA_padding_add_SSLv23 ,
188.Fn RSA_padding_check_SSLv23 ,
189.Fn RSA_padding_add_none ,
190and
191.Fn RSA_padding_check_none
192appeared in SSLeay 0.9.0.
193.Pp
194.Fn RSA_padding_add_PKCS1_OAEP
195and
196.Fn RSA_padding_check_PKCS1_OAEP
197were added in OpenSSL 0.9.2b.
diff --git a/src/lib/libcrypto/man/RSA_print.3 b/src/lib/libcrypto/man/RSA_print.3
new file mode 100644
index 0000000000..986dce2eb4
--- /dev/null
+++ b/src/lib/libcrypto/man/RSA_print.3
@@ -0,0 +1,91 @@
1.Dd $Mdocdate: November 4 2016 $
2.Dt RSA_PRINT 3
3.Os
4.Sh NAME
5.Nm RSA_print ,
6.Nm RSA_print_fp ,
7.Nm DSAparams_print ,
8.Nm DSAparams_print_fp ,
9.Nm DSA_print ,
10.Nm DSA_print_fp ,
11.Nm DHparams_print ,
12.Nm DHparams_print_fp
13.Nd print cryptographic parameters
14.Sh SYNOPSIS
15.In openssl/rsa.h
16.Ft int
17.Fo RSA_print
18.Fa "BIO *bp"
19.Fa "RSA *x"
20.Fa "int offset"
21.Fc
22.Ft int
23.Fo RSA_print_fp
24.Fa "FILE *fp"
25.Fa "RSA *x"
26.Fa "int offset"
27.Fc
28.In openssl/dsa.h
29.Ft int
30.Fo DSAparams_print
31.Fa "BIO *bp"
32.Fa "DSA *x"
33.Fc
34.Ft int
35.Fo DSAparams_print_fp
36.Fa "FILE *fp"
37.Fa "DSA *x"
38.Fc
39.Ft int
40.Fo DSA_print
41.Fa "BIO *bp"
42.Fa "DSA *x"
43.Fa "int offset"
44.Fc
45.Ft int
46.Fo DSA_print_fp
47.Fa "FILE *fp"
48.Fa "DSA *x"
49.Fa "int offset"
50.Fc
51.In openssl/dh.h
52.Ft int
53.Fo DHparams_print
54.Fa "BIO *bp"
55.Fa "DH *x"
56.Fc
57.Ft int
58.Fo DHparams_print_fp
59.Fa "FILE *fp"
60.Fa "DH *x"
61.Fc
62.Sh DESCRIPTION
63A human-readable hexadecimal output of the components of the RSA key,
64DSA parameters or key or DH parameters is printed to
65.Fa bp
66or
67.Fa fp .
68.Pp
69The output lines are indented by
70.Fa offset
71spaces.
72.Sh RETURN VALUES
73These functions return 1 on success or 0 on error.
74.Sh SEE ALSO
75.Xr BN_bn2bin 3 ,
76.Xr dh 3 ,
77.Xr dsa 3 ,
78.Xr rsa 3
79.Sh HISTORY
80.Fn RSA_print ,
81.Fn RSA_print_fp ,
82.Fn DSA_print ,
83.Fn DSA_print_fp ,
84.Fn DHparams_print ,
85and
86.Fn DHparams_print_fp
87are available in all versions of SSLeay and OpenSSL.
88.Fn DSAparams_print
89and
90.Fn DSAparams_print_fp
91were added in SSLeay 0.8.
diff --git a/src/lib/libcrypto/man/RSA_private_encrypt.3 b/src/lib/libcrypto/man/RSA_private_encrypt.3
new file mode 100644
index 0000000000..ff59e66f6a
--- /dev/null
+++ b/src/lib/libcrypto/man/RSA_private_encrypt.3
@@ -0,0 +1,97 @@
1.Dd $Mdocdate: November 4 2016 $
2.Dt RSA_PRIVATE_ENCRYPT 3
3.Os
4.Sh NAME
5.Nm RSA_private_encrypt ,
6.Nm RSA_public_decrypt
7.Nd low level signature operations
8.Sh SYNOPSIS
9.In openssl/rsa.h
10.Ft int
11.Fo RSA_private_encrypt
12.Fa "int flen"
13.Fa "unsigned char *from"
14.Fa "unsigned char *to"
15.Fa "RSA *rsa"
16.Fa "int padding"
17.Fc
18.Ft int
19.Fo RSA_public_decrypt
20.Fa "int flen"
21.Fa "unsigned char *from"
22.Fa "unsigned char *to"
23.Fa "RSA *rsa"
24.Fa "int padding"
25.Fc
26.Sh DESCRIPTION
27These functions handle RSA signatures at a low level.
28.Pp
29.Fn RSA_private_encrypt
30signs the
31.Fa flen
32bytes at
33.Fa from
34(usually a message digest with an algorithm identifier) using the
35private key
36.Fa rsa
37and stores the signature in
38.Fa to .
39.Fa to
40must point to
41.Fn RSA_size rsa
42bytes of memory.
43.Pp
44.Fa padding
45denotes one of the following modes:
46.Bl -tag -width Ds
47.It Dv RSA_PKCS1_PADDING
48PKCS #1 v1.5 padding.
49This function does not handle the
50.Sy algorithmIdentifier
51specified in PKCS #1.
52When generating or verifying PKCS #1 signatures,
53.Xr RSA_sign 3
54and
55.Xr RSA_verify 3
56should be used.
57.It Dv RSA_NO_PADDING
58Raw RSA signature.
59This mode should only be used to implement cryptographically sound
60padding modes in the application code.
61Signing user data directly with RSA is insecure.
62.El
63.Pp
64.Fn RSA_public_decrypt
65recovers the message digest from the
66.Fa flen
67bytes long signature at
68.Fa from
69using the signer's public key
70.Fa rsa .
71.Fa to
72must point to a memory section large enough to hold the message digest
73(which is smaller than
74.Fn RSA_size rsa
75- 11).
76.Fa padding
77is the padding mode that was used to sign the data.
78.Sh RETURN VALUES
79.Fn RSA_private_encrypt
80returns the size of the signature (i.e.,
81.Fn RSA_size rsa ) .
82.Fn RSA_public_decrypt
83returns the size of the recovered message digest.
84.Pp
85On error, -1 is returned; the error codes can be obtained by
86.Xr ERR_get_error 3 .
87.Sh SEE ALSO
88.Xr ERR_get_error 3 ,
89.Xr rsa 3 ,
90.Xr RSA_sign 3 ,
91.Xr RSA_verify 3
92.Sh HISTORY
93The
94.Fa padding
95argument was added in SSLeay 0.8.
96.Dv RSA_NO_PADDING
97is available since SSLeay 0.9.0.
diff --git a/src/lib/libcrypto/man/RSA_public_encrypt.3 b/src/lib/libcrypto/man/RSA_public_encrypt.3
new file mode 100644
index 0000000000..c2c81019c6
--- /dev/null
+++ b/src/lib/libcrypto/man/RSA_public_encrypt.3
@@ -0,0 +1,108 @@
1.Dd $Mdocdate: November 4 2016 $
2.Dt RSA_PUBLIC_ENCRYPT 3
3.Os
4.Sh NAME
5.Nm RSA_public_encrypt ,
6.Nm RSA_private_decrypt
7.Nd RSA public key cryptography
8.Sh SYNOPSIS
9.In openssl/rsa.h
10.Ft int
11.Fo RSA_public_encrypt
12.Fa "int flen"
13.Fa "unsigned char *from"
14.Fa "unsigned char *to"
15.Fa "RSA *rsa"
16.Fa "int padding"
17.Fc
18.Ft int
19.Fo RSA_private_decrypt
20.Fa "int flen"
21.Fa "unsigned char *from"
22.Fa "unsigned char *to"
23.Fa "RSA *rsa"
24.Fa "int padding"
25.Fc
26.Sh DESCRIPTION
27.Fn RSA_public_encrypt
28encrypts the
29.Fa flen
30bytes at
31.Fa from
32(usually a session key) using the public key
33.Fa rsa
34and stores the ciphertext in
35.Fa to .
36.Fa to
37must point to
38.Fn RSA_size rsa
39bytes of memory.
40.Pp
41.Fa padding
42denotes one of the following modes:
43.Bl -tag -width Ds
44.It Dv RSA_PKCS1_PADDING
45PKCS #1 v1.5 padding.
46This currently is the most widely used mode.
47.It Dv RSA_PKCS1_OAEP_PADDING
48EME-OAEP as defined in PKCS #1 v2.0 with SHA-1, MGF1 and an empty
49encoding parameter.
50This mode is recommended for all new applications.
51.It Dv RSA_SSLV23_PADDING
52PKCS #1 v1.5 padding with an SSL-specific modification that denotes that
53the server is SSL3 capable.
54.It Dv RSA_NO_PADDING
55Raw RSA encryption.
56This mode should only be used to implement cryptographically sound
57padding modes in the application code.
58Encrypting user data directly with RSA is insecure.
59.El
60.Pp
61.Fa flen
62must be less than
63.Fn RSA_size rsa
64- 11 for the PKCS #1 v1.5 based padding modes, less than
65.Fn RSA_size rsa
66- 41 for
67.Dv RSA_PKCS1_OAEP_PADDING
68and exactly
69.Fn RSA_size rsa
70for
71.Dv RSA_NO_PADDING .
72.Pp
73.Fn RSA_private_decrypt
74decrypts the
75.Fa flen
76bytes at
77.Fa from
78using the private key
79.Fa rsa
80and stores the plaintext in
81.Fa to .
82.Fa to
83must point to a memory section large enough to hold the decrypted data
84(which is smaller than
85.Fn RSA_size rsa ) .
86.Fa padding
87is the padding mode that was used to encrypt the data.
88.Sh RETURN VALUES
89.Fn RSA_public_encrypt
90returns the size of the encrypted data (i.e.,
91.Fn RSA_size rsa ) .
92.Fn RSA_private_decrypt
93returns the size of the recovered plaintext.
94.Pp
95On error, -1 is returned; the error codes can be obtained by
96.Xr ERR_get_error 3 .
97.Sh SEE ALSO
98.Xr ERR_get_error 3 ,
99.Xr rsa 3 ,
100.Xr RSA_size 3
101.Sh STANDARDS
102SSL, PKCS #1 v2.0
103.Sh HISTORY
104The
105.Fa padding
106argument was added in SSLeay 0.8.
107.Dv RSA_NO_PADDING is available since SSLeay 0.9.0.
108OAEP was added in OpenSSL 0.9.2b.
diff --git a/src/lib/libcrypto/man/RSA_set_method.3 b/src/lib/libcrypto/man/RSA_set_method.3
new file mode 100644
index 0000000000..d7a2756b70
--- /dev/null
+++ b/src/lib/libcrypto/man/RSA_set_method.3
@@ -0,0 +1,339 @@
1.Dd $Mdocdate: November 4 2016 $
2.Dt RSA_SET_METHOD 3
3.Os
4.Sh NAME
5.Nm RSA_set_default_method ,
6.Nm RSA_get_default_method ,
7.Nm RSA_set_method ,
8.Nm RSA_get_method ,
9.Nm RSA_PKCS1_SSLeay ,
10.Nm RSA_null_method ,
11.Nm RSA_flags ,
12.Nm RSA_new_method ,
13.Nm RSA_get_default_openssl_method ,
14.Nm RSA_set_default_openssl_method
15.Nd select RSA method
16.Sh SYNOPSIS
17.In openssl/rsa.h
18.Ft void
19.Fo RSA_set_default_method
20.Fa "const RSA_METHOD *meth"
21.Fc
22.Ft RSA_METHOD *
23.Fn RSA_get_default_method void
24.Ft int
25.Fo RSA_set_method
26.Fa "RSA *rsa"
27.Fa "const RSA_METHOD *meth"
28.Fc
29.Ft RSA_METHOD *
30.Fo RSA_get_method
31.Fa "const RSA *rsa"
32.Fc
33.Ft RSA_METHOD *
34.Fn RSA_PKCS1_SSLeay void
35.Ft RSA_METHOD *
36.Fn RSA_null_method void
37.Ft int
38.Fo RSA_flags
39.Fa "const RSA *rsa"
40.Fc
41.Ft RSA *
42.Fo RSA_new_method
43.Fa "RSA_METHOD *meth"
44.Fc
45.Sh DESCRIPTION
46An
47.Vt RSA_METHOD
48specifies the functions that OpenSSL uses for RSA operations.
49By modifying the method, alternative implementations such as hardware
50accelerators may be used.
51See the
52.Sx CAVEATS
53section for how these RSA API functions are affected by the use of
54.Xr engine 3
55API calls.
56.Pp
57Initially, the default
58.Vt RSA_METHOD
59is the OpenSSL internal implementation, as returned by
60.Fn RSA_PKCS1_SSLeay .
61.Pp
62.Fn RSA_set_default_method
63makes
64.Fa meth
65the default method for all
66.Vt RSA
67structures created later.
68.Sy NB :
69This is true only whilst no
70.Vt ENGINE
71has been set as a default for RSA, so this function is no longer
72recommended.
73.Pp
74.Fn RSA_get_default_method
75returns a pointer to the current default
76.Vt RSA_METHOD .
77However, the meaningfulness of this result is dependent on whether
78the
79.Xr engine 3
80API is being used, so this function is no longer recommended.
81.Pp
82.Fn RSA_set_method
83selects
84.Fa meth
85to perform all operations using the key
86.Fa rsa .
87This will replace the
88.Vt RSA_METHOD
89used by the RSA key, and if the previous method was supplied by an
90.Vt ENGINE ,
91the handle to that
92.Vt ENGINE
93will be released during the change.
94It is possible to have RSA keys that only work with certain
95.Vt RSA_METHOD
96implementations (eg. from an
97.Vt ENGINE
98module that supports embedded hardware-protected keys),
99and in such cases attempting to change the
100.Vt RSA_METHOD
101for the key can have unexpected results.
102.Pp
103.Fn RSA_get_method
104returns a pointer to the
105.Vt RSA_METHOD
106being used by
107.Fa rsa .
108This method may or may not be supplied by an
109.Vt ENGINE
110implementation, but if it is, the return value can only be guaranteed
111to be valid as long as the RSA key itself is valid and does not
112have its implementation changed by
113.Fn RSA_set_method .
114.Pp
115.Fn RSA_flags
116returns the flags that are set for the current
117.Vt RSA_METHOD
118of
119.Fa rsa .
120See the
121.Sx BUGS
122section.
123.Pp
124.Fn RSA_new_method
125allocates and initializes an
126.Vt RSA
127structure so that
128.Fa meth
129will be used for the RSA operations.
130If
131.Sy engine
132is NULL, the default ENGINE for RSA operations is used, and if no
133default ENGINE is set, the RSA_METHOD controlled by
134.Fn RSA_set_default_method
135is used.
136.Pp
137.Fn RSA_flags
138returns the
139.Sy flags
140that are set for
141.Fa rsa Ns 's
142current method.
143.Pp
144.Fn RSA_new_method
145allocates and initializes an
146.Vt RSA
147structure so that
148.Fa meth
149will be used for the RSA operations.
150If
151.Fa meth
152is
153.Dv NULL ,
154the default method is used.
155.Sh THE RSA_METHOD STRUCTURE
156.Bd -literal
157typedef struct rsa_meth_st
158{
159 /* name of the implementation */
160 const char *name;
161
162 /* encrypt */
163 int (*rsa_pub_enc)(int flen, unsigned char *from,
164 unsigned char *to, RSA *rsa, int padding);
165
166 /* verify arbitrary data */
167 int (*rsa_pub_dec)(int flen, unsigned char *from,
168 unsigned char *to, RSA *rsa, int padding);
169
170 /* sign arbitrary data */
171 int (*rsa_priv_enc)(int flen, unsigned char *from,
172 unsigned char *to, RSA *rsa, int padding);
173
174 /* decrypt */
175 int (*rsa_priv_dec)(int flen, unsigned char *from,
176 unsigned char *to, RSA *rsa, int padding);
177
178 /* compute r0 = r0 ^ I mod rsa->n (May be NULL for some
179 implementations) */
180 int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa);
181
182 /* compute r = a ^ p mod m (May be NULL for some implementations) */
183 int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
184 const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
185
186 /* called at RSA_new */
187 int (*init)(RSA *rsa);
188
189 /* called at RSA_free */
190 int (*finish)(RSA *rsa);
191
192 /* RSA_FLAG_EXT_PKEY - rsa_mod_exp is called for private key
193 * operations, even if p,q,dmp1,dmq1,iqmp
194 * are NULL
195 * RSA_FLAG_SIGN_VER - enable rsa_sign and rsa_verify
196 * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match
197 */
198 int flags;
199
200 char *app_data; /* ?? */
201
202 /* sign. For backward compatibility, this is used only
203 * if (flags & RSA_FLAG_SIGN_VER)
204 */
205 int (*rsa_sign)(int type, unsigned char *m, unsigned int m_len,
206 unsigned char *sigret, unsigned int *siglen, RSA *rsa);
207
208 /* verify. For backward compatibility, this is used only
209 * if (flags & RSA_FLAG_SIGN_VER)
210 */
211 int (*rsa_verify)(int type, unsigned char *m, unsigned int m_len,
212 unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
213
214} RSA_METHOD;
215.Ed
216.Sh RETURN VALUES
217.Fn RSA_PKCS1_SSLeay ,
218.Fn RSA_null_method ,
219.Fn RSA_get_default_method
220and
221.Fn RSA_get_method
222return pointers to the respective
223.Vt RSA_METHOD .
224.Pp
225.Fn RSA_set_method
226returns a pointer to the old
227.Vt RSA_METHOD
228implementation that was replaced.
229However, this return value should probably be ignored because if it was
230supplied by an
231.Vt ENGINE ,
232the pointer could be invalidated at any time if the
233.Vt ENGINE
234is unloaded.
235In fact, it could be unloaded as a result of the
236.Fn RSA_set_method
237function releasing its handle to the
238.Vt ENGINE .
239For this reason, the return type may be replaced with a
240.Vt void
241declaration in a future release.
242.Pp
243.Fn RSA_new_method
244returns
245.Dv NULL
246and sets an error code that can be obtained by
247.Xr ERR_get_error 3
248if the allocation fails.
249Otherwise it returns a pointer to the newly allocated structure.
250.Sh SEE ALSO
251.Xr rsa 3 ,
252.Xr RSA_new 3
253.Sh HISTORY
254.Fn RSA_new_method
255and
256.Fn RSA_set_default_method
257appeared in SSLeay 0.8.
258.Fn RSA_get_default_method ,
259.Fn RSA_set_method ,
260and
261.Fn RSA_get_method
262as well as the
263.Fa rsa_sign
264and
265.Fa rsa_verify
266components of
267.Vt RSA_METHOD
268were added in OpenSSL 0.9.4.
269.Pp
270.Fn RSA_set_default_openssl_method
271and
272.Fn RSA_get_default_openssl_method
273replaced
274.Fn RSA_set_default_method
275and
276.Fn RSA_get_default_method
277respectively, and
278.Fn RSA_set_method
279and
280.Fn RSA_new_method
281were altered to use
282.Vt ENGINE Ns s
283rather than
284.Vt RSA_METHOD Ns s
285during development of the
286.Xr engine 3
287version of OpenSSL 0.9.6.
288For 0.9.7, the handling of defaults in the
289.Xr engine 3
290API was restructured so that this change was reversed, and behaviour
291of the other functions resembled more closely the previous behaviour.
292The behaviour of defaults in the
293.Xr engine 3
294API now transparently overrides the behaviour of defaults in the
295RSA API without requiring changing these function prototypes.
296.Sh CAVEATS
297As of version 0.9.7,
298.Vt RSA_METHOD
299implementations are grouped together with other algorithmic APIs (eg.\&
300.Vt DSA_METHOD ,
301.Vt EVP_CIPHER ,
302etc.) into
303.Vt ENGINE
304modules.
305If a default
306.Vt ENGINE
307is specified for RSA functionality using an
308.Xr engine 3
309API function, that will override any RSA defaults set using the RSA
310API, ie.\&
311.Fn RSA_set_default_method .
312For this reason, the
313.Xr engine 3
314API is the recommended way to control default implementations for
315use in RSA and other cryptographic algorithms.
316.Sh BUGS
317The behaviour of
318.Fn RSA_flags
319is a mis-feature that is left as-is for now to avoid creating
320compatibility problems.
321RSA functionality, such as the encryption functions, are controlled by
322the
323.Fa flags
324value in the
325.Vt RSA
326key itself, not by the
327.Fa flags
328value in the
329.Vt RSA_METHOD
330attached to the RSA key (which is what this function returns).
331If the flags element of an
332.Vt RSA
333key is changed, the changes will be honoured by RSA functionality
334but will not be reflected in the return value of the
335.Fn RSA_flags
336function - in effect
337.Fn RSA_flags
338behaves more like a RSA_default_flags() function, which does not
339currently exist.
diff --git a/src/lib/libcrypto/man/RSA_sign.3 b/src/lib/libcrypto/man/RSA_sign.3
new file mode 100644
index 0000000000..2b9e5eb6f1
--- /dev/null
+++ b/src/lib/libcrypto/man/RSA_sign.3
@@ -0,0 +1,103 @@
1.Dd $Mdocdate: November 4 2016 $
2.Dt RSA_SIGN 3
3.Os
4.Sh NAME
5.Nm RSA_sign ,
6.Nm RSA_verify
7.Nd RSA signatures
8.Sh SYNOPSIS
9.In openssl/rsa.h
10.Ft int
11.Fo RSA_sign
12.Fa "int type"
13.Fa "const unsigned char *m"
14.Fa "unsigned int m_len"
15.Fa "unsigned char *sigret"
16.Fa "unsigned int *siglen"
17.Fa "RSA *rsa"
18.Fc
19.Ft int
20.Fo RSA_verify
21.Fa "int type"
22.Fa "const unsigned char *m"
23.Fa "unsigned int m_len"
24.Fa "unsigned char *sigbuf"
25.Fa "unsigned int siglen"
26.Fa "RSA *rsa"
27.Fc
28.Sh DESCRIPTION
29.Fn RSA_sign
30signs the message digest
31.Fa m
32of size
33.Fa m_len
34using the private key
35.Fa rsa
36as specified in PKCS #1 v2.0.
37It stores the signature in
38.Fa sigret
39and the signature size in
40.Fa siglen .
41.Fa sigret
42must point to
43.Fn RSA_size rsa
44bytes of memory.
45Note that PKCS #1 adds meta-data, placing limits on the size of the key
46that can be used.
47See
48.Xr RSA_private_encrypt 3
49for lower-level operations.
50.Pp
51.Fa type
52denotes the message digest algorithm that was used to generate
53.Fa m .
54It usually is one of
55.Dv NID_sha1 ,
56.Dv NID_ripemd160 ,
57or
58.Dv NID_md5 ;
59see
60.Xr OBJ_nid2obj 3
61for details.
62If
63.Fa type
64is
65.Sy NID_md5_sha1 ,
66an SSL signature (MD5 and SHA1 message digests with PKCS #1 padding and
67no algorithm identifier) is created.
68.Pp
69.Fn RSA_verify
70verifies that the signature
71.Fa sigbuf
72of size
73.Fa siglen
74matches a given message digest
75.Fa m
76of size
77.Fa m_len .
78.Fa type
79denotes the message digest algorithm that was used to generate the
80signature.
81.Fa rsa
82is the signer's public key.
83.Sh RETURN VALUES
84.Fn RSA_sign
85returns 1 on success or 0 otherwise.
86.Fn RSA_verify
87returns 1 on successful verification or 0 otherwise.
88.Pp
89The error codes can be obtained by
90.Xr ERR_get_error 3 .
91.Sh SEE ALSO
92.Xr ERR_get_error 3 ,
93.Xr objects 3 ,
94.Xr rsa 3 ,
95.Xr RSA_private_encrypt 3 ,
96.Xr RSA_public_decrypt 3
97.Sh STANDARDS
98SSL, PKCS #1 v2.0
99.Sh HISTORY
100.Fn RSA_sign
101and
102.Fn RSA_verify
103are available in all versions of SSLeay and OpenSSL.
diff --git a/src/lib/libcrypto/man/RSA_sign_ASN1_OCTET_STRING.3 b/src/lib/libcrypto/man/RSA_sign_ASN1_OCTET_STRING.3
new file mode 100644
index 0000000000..7398a294c9
--- /dev/null
+++ b/src/lib/libcrypto/man/RSA_sign_ASN1_OCTET_STRING.3
@@ -0,0 +1,81 @@
1.Dd $Mdocdate: November 4 2016 $
2.Dt RSA_SIGN_ASN1_OCTET_STRING 3
3.Os
4.Sh NAME
5.Nm RSA_sign_ASN1_OCTET_STRING ,
6.Nm RSA_verify_ASN1_OCTET_STRING
7.Nd RSA signatures
8.Sh SYNOPSIS
9.In openssl/rsa.h
10.Ft int
11.Fo RSA_sign_ASN1_OCTET_STRING
12.Fa "int dummy"
13.Fa "unsigned char *m"
14.Fa "unsigned int m_len"
15.Fa "unsigned char *sigret"
16.Fa "unsigned int *siglen"
17.Fa "RSA *rsa"
18.Fc
19.Ft int
20.Fo RSA_verify_ASN1_OCTET_STRING
21.Fa "int dummy"
22.Fa "unsigned char *m"
23.Fa "unsigned int m_len"
24.Fa "unsigned char *sigbuf"
25.Fa "unsigned int siglen"
26.Fa "RSA *rsa"
27.Fc
28.Sh DESCRIPTION
29.Fn RSA_sign_ASN1_OCTET_STRING
30signs the octet string
31.Fa m
32of size
33.Fa m_len
34using the private key
35.Fa rsa
36represented in DER using PKCS #1 padding.
37It stores the signature in
38.Fa sigret
39and the signature size in
40.Fa siglen .
41.Fa sigret
42must point to
43.Fn RSA_size rsa
44bytes of memory.
45.Pp
46.Fa dummy
47is ignored.
48.Pp
49.Fn RSA_verify_ASN1_OCTET_STRING
50verifies that the signature
51.Fa sigbuf
52of size
53.Fa siglen
54is the DER representation of a given octet string
55.Fa m
56of size
57.Fa m_len .
58.Fa dummy
59is ignored.
60.Fa rsa
61is the signer's public key.
62.Sh RETURN VALUES
63.Fn RSA_sign_ASN1_OCTET_STRING
64returns 1 on success or 0 otherwise.
65.Fn RSA_verify_ASN1_OCTET_STRING
66returns 1 on successful verification or 0 otherwise.
67.Pp
68The error codes can be obtained by
69.Xr ERR_get_error 3 .
70.Sh SEE ALSO
71.Xr ERR_get_error 3 ,
72.Xr rsa 3 ,
73.Xr RSA_sign 3 ,
74.Xr RSA_verify 3
75.Sh HISTORY
76.Fn RSA_sign_ASN1_OCTET_STRING
77and
78.Fn RSA_verify_ASN1_OCTET_STRING
79were added in SSLeay 0.8.
80.Sh BUGS
81These functions serve no recognizable purpose.
diff --git a/src/lib/libcrypto/man/RSA_size.3 b/src/lib/libcrypto/man/RSA_size.3
new file mode 100644
index 0000000000..8b9a4d0552
--- /dev/null
+++ b/src/lib/libcrypto/man/RSA_size.3
@@ -0,0 +1,27 @@
1.Dd $Mdocdate: November 4 2016 $
2.Dt RSA_SIZE 3
3.Os
4.Sh NAME
5.Nm RSA_size
6.Nd get RSA modulus size
7.Sh SYNOPSIS
8.In openssl/rsa.h
9.Ft int
10.Fo RSA_size
11.Fa "const RSA *rsa"
12.Fc
13.Sh DESCRIPTION
14This function returns the RSA modulus size in bytes.
15It can be used to determine how much memory must be allocated for an RSA
16encrypted value.
17.Pp
18.Fa rsa->n
19must not be
20.Dv NULL .
21.Sh RETURN VALUE
22The size in bytes.
23.Sh SEE ALSO
24.Xr rsa 3
25.Sh HISTORY
26.Fn RSA_size
27is available in all versions of SSLeay and OpenSSL.
diff --git a/src/lib/libcrypto/man/d2i_RSAPublicKey.3 b/src/lib/libcrypto/man/d2i_RSAPublicKey.3
new file mode 100644
index 0000000000..b54487a621
--- /dev/null
+++ b/src/lib/libcrypto/man/d2i_RSAPublicKey.3
@@ -0,0 +1,101 @@
1.Dd $Mdocdate: November 4 2016 $
2.Dt D2I_RSAPUBLICKEY 3
3.Os
4.Sh NAME
5.Nm d2i_RSAPublicKey ,
6.Nm i2d_RSAPublicKey ,
7.Nm d2i_RSAPrivateKey ,
8.Nm i2d_RSAPrivateKey ,
9.Nm d2i_RSA_PUBKEY ,
10.Nm i2d_RSA_PUBKEY ,
11.Nm i2d_Netscape_RSA ,
12.Nm d2i_Netscape_RSA
13.Nd RSA public and private key encoding functions
14.Sh SYNOPSIS
15.In openssl/rsa.h
16.In openssl/x509.h
17.Ft RSA *
18.Fo d2i_RSAPublicKey
19.Fa "RSA **a"
20.Fa "const unsigned char **pp"
21.Fa "long length"
22.Fc
23.Ft int
24.Fo i2d_RSAPublicKey
25.Fa "RSA *a"
26.Fa "unsigned char **pp"
27.Fc
28.Ft RSA *
29.Fo d2i_RSA_PUBKEY
30.Fa "RSA **a"
31.Fa "const unsigned char **pp"
32.Fa "long length"
33.Fc
34.Ft int
35.Fo i2d_RSA_PUBKEY
36.Fa "RSA *a"
37.Fa "unsigned char **pp"
38.Fc
39.Ft RSA *
40.Fo d2i_RSAPrivateKey
41.Fa "RSA **a"
42.Fa "const unsigned char **pp"
43.Fa "long length"
44.Fc
45.Ft int
46.Fo i2d_RSAPrivateKey
47.Fa "RSA *a"
48.Fa "unsigned char **pp"
49.Fc
50.Ft int
51.Fo i2d_Netscape_RSA
52.Fa "RSA *a"
53.Fa "unsigned char **pp"
54.Fa "int (*cb)()"
55.Fc
56.Ft RSA *
57.Fo d2i_Netscape_RSA
58.Fa "RSA **a"
59.Fa "const unsigned char **pp"
60.Fa "long length"
61.Fa "int (*cb)()"
62.Fc
63.Sh DESCRIPTION
64.Fn d2i_RSAPublicKey
65and
66.Fn i2d_RSAPublicKey
67decode and encode a PKCS#1 RSAPublicKey structure.
68.Pp
69.Fn d2i_RSA_PUBKEY
70and
71.Fn i2d_RSA_PUBKEY
72decode and encode an RSA public key using a SubjectPublicKeyInfo
73(certificate public key) structure.
74.Pp
75.Fn d2i_RSAPrivateKey ,
76.Fn i2d_RSAPrivateKey
77decode and encode a PKCS#1 RSAPrivateKey structure.
78.Pp
79.Fn d2i_Netscape_RSA ,
80.Fn i2d_Netscape_RSA
81decode and encode an RSA private key in NET format.
82.Pp
83The usage of all of these functions is similar to
84.Xr d2i_X509 3
85and
86.Xr i2d_X509 3 .
87.Pp
88The
89.Vt RSA
90structure passed to the private key encoding functions should have all
91the PKCS#1 private key components present.
92.Pp
93The data encoded by the private key functions is unencrypted and
94therefore offers no private key security.
95.Pp
96The NET format functions are present to provide compatibility with
97certain very old software.
98This format has some severe security weaknesses and should be avoided if
99possible.
100.Sh SEE ALSO
101.Xr d2i_X509 3
diff --git a/src/lib/libcrypto/man/rsa.3 b/src/lib/libcrypto/man/rsa.3
new file mode 100644
index 0000000000..7c34f3595b
--- /dev/null
+++ b/src/lib/libcrypto/man/rsa.3
@@ -0,0 +1,238 @@
1.Dd $Mdocdate: November 4 2016 $
2.Dt RSA 3
3.Os
4.Sh NAME
5.Nm rsa
6.Nd RSA public key cryptosystem
7.Sh SYNOPSIS
8.In openssl/rsa.h
9.In openssl/engine.h
10.Ft RSA *
11.Fn RSA_new void
12.Ft void
13.Fo RSA_free
14.Fa "RSA *rsa"
15.Fc
16.Ft int
17.Fo RSA_public_encrypt
18.Fa "int flen"
19.Fa "unsigned char *from"
20.Fa "unsigned char *to"
21.Fa "RSA *rsa"
22.Fa "int padding"
23.Fc
24.Ft int
25.Fo RSA_private_decrypt
26.Fa "int flen"
27.Fa "unsigned char *from"
28.Fa "unsigned char *to"
29.Fa "RSA *rsa"
30.Fa "int padding"
31.Fc
32.Ft int
33.Fo RSA_private_encrypt
34.Fa "int flen"
35.Fa "unsigned char *from"
36.Fa "unsigned char *to"
37.Fa "RSA *rsa"
38.Fa "int padding"
39.Fc
40.Ft int
41.Fo RSA_public_decrypt
42.Fa "int flen"
43.Fa "unsigned char *from"
44.Fa "unsigned char *to"
45.Fa "RSA *rsa"
46.Fa "int padding"
47.Fc
48.Ft int
49.Fo RSA_sign
50.Fa "int type"
51.Fa "unsigned char *m"
52.Fa "unsigned int m_len"
53.Fa "unsigned char *sigret"
54.Fa "unsigned int *siglen"
55.Fa "RSA *rsa"
56.Fc
57.Ft int
58.Fo RSA_verify
59.Fa "int type"
60.Fa "unsigned char *m"
61.Fa "unsigned int m_len"
62.Fa "unsigned char *sigbuf"
63.Fa "unsigned int siglen"
64.Fa "RSA *rsa"
65.Fc
66.Ft int
67.Fo RSA_size
68.Fa "const RSA *rsa"
69.Fc
70.Ft RSA *
71.Fo RSA_generate_key
72.Fa "int num"
73.Fa "unsigned long e"
74.Fa "void (*callback)(int, int, void *)"
75.Fa "void *cb_arg"
76.Fc
77.Ft int
78.Fo RSA_check_key
79.Fa "RSA *rsa"
80.Fc
81.Ft int
82.Fo RSA_blinding_on
83.Fa "RSA *rsa"
84.Fa "BN_CTX *ctx"
85.Fc
86.Ft void
87.Fo RSA_blinding_off
88.Fa "RSA *rsa"
89.Fc
90.Ft void
91.Fo RSA_set_default_method
92.Fa "const RSA_METHOD *meth"
93.Fc
94.Ft const RSA_METHOD *
95.Fn RSA_get_default_method void
96.Ft int
97.Fo RSA_set_method
98.Fa "RSA *rsa"
99.Fa "const RSA_METHOD *meth"
100.Fc
101.Ft const RSA_METHOD *
102.Fo RSA_get_method
103.Fa "const RSA *rsa"
104.Fc
105.Ft RSA_METHOD *
106.Fn RSA_PKCS1_SSLeay void
107.Ft RSA_METHOD *
108.Fn RSA_null_method void
109.Ft int
110.Fo RSA_flags
111.Fa "const RSA *rsa"
112.Fc
113.Ft RSA *
114.Fo RSA_new_method
115.Fa "ENGINE *engine"
116.Fc
117.Ft int
118.Fo RSA_print
119.Fa "BIO *bp"
120.Fa "RSA *x"
121.Fa "int offset"
122.Fc
123.Ft int
124.Fo RSA_print_fp
125.Fa "FILE *fp"
126.Fa "RSA *x"
127.Fa "int offset"
128.Fc
129.Ft int
130.Fo RSA_get_ex_new_index
131.Fa "long argl"
132.Fa "char *argp"
133.Fa "int (*new_func)()"
134.Fa "int (*dup_func)()"
135.Fa "void (*free_func)()"
136.Fc
137.Ft int
138.Fo RSA_set_ex_data
139.Fa "RSA *r"
140.Fa "int idx"
141.Fa "char *arg"
142.Fc
143.Ft char *
144.Fo RSA_get_ex_data
145.Fa "RSA *r"
146.Fa "int idx"
147.Fc
148.Ft int
149.Fo RSA_sign_ASN1_OCTET_STRING
150.Fa "int dummy"
151.Fa "unsigned char *m"
152.Fa "unsigned int m_len"
153.Fa "unsigned char *sigret"
154.Fa "unsigned int *siglen"
155.Fa "RSA *rsa"
156.Fc
157.Ft int
158.Fo RSA_verify_ASN1_OCTET_STRING
159.Fa "int dummy"
160.Fa "unsigned char *m"
161.Fa "unsigned int m_len"
162.Fa "unsigned char *sigbuf"
163.Fa "unsigned int siglen"
164.Fa "RSA *rsa"
165.Fc
166.Sh DESCRIPTION
167These functions implement RSA public key encryption and signatures as
168defined in PKCS #1 v2.0 [RFC 2437].
169.Pp
170The
171.Vt RSA
172structure consists of several BIGNUM components.
173It can contain public as well as private RSA keys:
174.Bd -literal
175typdef struct {
176 BIGNUM *n; // public modulus
177 BIGNUM *e; // public exponent
178 BIGNUM *d; // private exponent
179 BIGNUM *p; // secret prime factor
180 BIGNUM *q; // secret prime factor
181 BIGNUM *dmp1; // d mod (p-1)
182 BIGNUM *dmq1; // d mod (q-1)
183 BIGNUM *iqmp; // q^-1 mod p
184 // ...
185} RSA;
186.Ed
187.Pp
188In public keys, the private exponent and the related secret values are
189.Dv NULL .
190.Pp
191.Fa p ,
192.Fa q ,
193.Fa dmp1 ,
194.Fa dmq1 ,
195and
196.Fa iqmp
197may be
198.Dv NULL
199in private keys, but the RSA operations are much faster when these
200values are available.
201.Pp
202Note that RSA keys may use non-standard
203.Vt RSA_METHOD
204implementations, either directly or by the use of
205.Vt ENGINE
206modules.
207In some cases (eg. an
208.Vt ENGINE
209providing support for hardware-embedded keys), these
210.Vt BIGNUM
211values will not be used by the implementation or may be used for
212alternative data storage.
213For this reason, applications should generally avoid using
214.Vt RSA
215structure elements directly and instead use API functions to query
216or modify keys.
217.Sh SEE ALSO
218.Xr bn 3 ,
219.Xr dh 3 ,
220.Xr dsa 3 ,
221.Xr engine 3 ,
222.Xr RSA_blinding_on 3 ,
223.Xr RSA_check_key 3 ,
224.Xr RSA_generate_key 3 ,
225.Xr RSA_get_ex_new_index 3 ,
226.Xr RSA_new 3 ,
227.Xr RSA_padding_add_PKCS1_type_1 3 ,
228.Xr RSA_print 3 ,
229.Xr RSA_private_encrypt 3 ,
230.Xr RSA_public_encrypt 3 ,
231.Xr RSA_set_method 3 ,
232.Xr RSA_sign 3 ,
233.Xr RSA_sign_ASN1_OCTET_STRING 3 ,
234.Xr RSA_size 3
235.Sh STANDARDS
236SSL, PKCS #1 v2.0
237.Pp
238RSA was covered by a US patent which expired in September 2000.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-04-26 17:59:42 +0000