summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authorschwarze <>2016-11-04 10:17:17 +0000
committerschwarze <>2016-11-04 10:17:17 +0000
commit195fe5e91c60bd205043b4bea113abdff1c67bcc (patch)
tree1d15fe02d83a7ffb422ebe78c34ee1117da63e59 /src
parent00872265b9546fcf2d5795aa3a120c35142d268b (diff)
downloadopenbsd-195fe5e91c60bd205043b4bea113abdff1c67bcc.tar.gz
openbsd-195fe5e91c60bd205043b4bea113abdff1c67bcc.tar.bz2
openbsd-195fe5e91c60bd205043b4bea113abdff1c67bcc.zip
convert RSA manuals from pod to mdoc
Diffstat (limited to 'src')
-rw-r--r--src/lib/libcrypto/doc/RSA_blinding_on.pod41
-rw-r--r--src/lib/libcrypto/doc/RSA_check_key.pod67
-rw-r--r--src/lib/libcrypto/doc/RSA_generate_key.pod79
-rw-r--r--src/lib/libcrypto/doc/RSA_get_ex_new_index.pod122
-rw-r--r--src/lib/libcrypto/doc/RSA_new.pod39
-rw-r--r--src/lib/libcrypto/doc/RSA_padding_add_PKCS1_type_1.pod121
-rw-r--r--src/lib/libcrypto/doc/RSA_print.pod49
-rw-r--r--src/lib/libcrypto/doc/RSA_private_encrypt.pod69
-rw-r--r--src/lib/libcrypto/doc/RSA_public_encrypt.pod82
-rw-r--r--src/lib/libcrypto/doc/RSA_set_method.pod201
-rw-r--r--src/lib/libcrypto/doc/RSA_sign.pod61
-rw-r--r--src/lib/libcrypto/doc/RSA_sign_ASN1_OCTET_STRING.pod57
-rw-r--r--src/lib/libcrypto/doc/RSA_size.pod33
-rw-r--r--src/lib/libcrypto/doc/d2i_RSAPublicKey.pod63
-rw-r--r--src/lib/libcrypto/doc/rsa.pod123
-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
31 files changed, 1919 insertions, 1223 deletions
diff --git a/src/lib/libcrypto/doc/RSA_blinding_on.pod b/src/lib/libcrypto/doc/RSA_blinding_on.pod
deleted file mode 100644
index f96e3cf7c9..0000000000
--- a/src/lib/libcrypto/doc/RSA_blinding_on.pod
+++ /dev/null
@@ -1,41 +0,0 @@
1=pod
2
3=head1 NAME
4
5RSA_blinding_on, RSA_blinding_off - protect the RSA operation from timing
6attacks
7
8=head1 SYNOPSIS
9
10 #include <openssl/rsa.h>
11
12 int RSA_blinding_on(RSA *rsa, BN_CTX *ctx);
13
14 void RSA_blinding_off(RSA *rsa);
15
16=head1 DESCRIPTION
17
18RSA is vulnerable to timing attacks. In a setup where attackers can
19measure the time of RSA decryption or signature operations, blinding
20must be used to protect the RSA operation from that attack.
21
22RSA_blinding_on() turns blinding on for key B<rsa> and generates a
23random blinding factor. B<ctx> is B<NULL> or a pre-allocated and
24initialized B<BN_CTX>.
25
26RSA_blinding_off() turns blinding off and frees the memory used for
27the blinding factor.
28
29=head1 RETURN VALUES
30
31RSA_blinding_on() returns 1 on success, and 0 if an error occurred.
32
33=head1 SEE ALSO
34
35L<rsa(3)|rsa(3)>, L<rand(3)|rand(3)>
36
37=head1 HISTORY
38
39RSA_blinding_on() and RSA_blinding_off() appeared in SSLeay 0.9.0.
40
41=cut
diff --git a/src/lib/libcrypto/doc/RSA_check_key.pod b/src/lib/libcrypto/doc/RSA_check_key.pod
deleted file mode 100644
index a5198f3db5..0000000000
--- a/src/lib/libcrypto/doc/RSA_check_key.pod
+++ /dev/null
@@ -1,67 +0,0 @@
1=pod
2
3=head1 NAME
4
5RSA_check_key - validate private RSA keys
6
7=head1 SYNOPSIS
8
9 #include <openssl/rsa.h>
10
11 int RSA_check_key(RSA *rsa);
12
13=head1 DESCRIPTION
14
15This function validates RSA keys. It checks that B<p> and B<q> are
16in fact prime, and that B<n = p*q>.
17
18It also checks that B<d*e = 1 mod (p-1*q-1)>,
19and that B<dmp1>, B<dmq1> and B<iqmp> are set correctly or are B<NULL>.
20
21As such, this function can not be used with any arbitrary RSA key object,
22even if it is otherwise fit for regular RSA operation. See B<NOTES> for more
23information.
24
25=head1 RETURN VALUE
26
27RSA_check_key() returns 1 if B<rsa> is a valid RSA key, and 0 otherwise.
28-1 is returned if an error occurs while checking the key.
29
30If the key is invalid or an error occurred, the reason code can be
31obtained using L<ERR_get_error(3)|ERR_get_error(3)>.
32
33=head1 NOTES
34
35This function does not work on RSA public keys that have only the modulus
36and public exponent elements populated. It performs integrity checks on all
37the RSA key material, so the RSA key structure must contain all the private
38key data too.
39
40Unlike most other RSA functions, this function does B<not> work
41transparently with any underlying ENGINE implementation because it uses the
42key data in the RSA structure directly. An ENGINE implementation can
43override the way key data is stored and handled, and can even provide
44support for HSM keys - in which case the RSA structure may contain B<no>
45key data at all! If the ENGINE in question is only being used for
46acceleration or analysis purposes, then in all likelihood the RSA key data
47is complete and untouched, but this can't be assumed in the general case.
48
49=head1 BUGS
50
51A method of verifying the RSA key using opaque RSA API functions might need
52to be considered. Right now RSA_check_key() simply uses the RSA structure
53elements directly, bypassing the RSA_METHOD table altogether (and
54completely violating encapsulation and object-orientation in the process).
55The best fix will probably be to introduce a "check_key()" handler to the
56RSA_METHOD function table so that alternative implementations can also
57provide their own verifiers.
58
59=head1 SEE ALSO
60
61L<rsa(3)|rsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>
62
63=head1 HISTORY
64
65RSA_check_key() appeared in OpenSSL 0.9.4.
66
67=cut
diff --git a/src/lib/libcrypto/doc/RSA_generate_key.pod b/src/lib/libcrypto/doc/RSA_generate_key.pod
deleted file mode 100644
index 00026f04df..0000000000
--- a/src/lib/libcrypto/doc/RSA_generate_key.pod
+++ /dev/null
@@ -1,79 +0,0 @@
1=pod
2
3=head1 NAME
4
5RSA_generate_key_ex, RSA_generate_key - generate RSA key pair
6
7=head1 SYNOPSIS
8
9 #include <openssl/rsa.h>
10
11 int RSA_generate_key_ex(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb);
12
13Deprecated:
14
15 RSA *RSA_generate_key(int num, unsigned long e,
16 void (*callback)(int,int,void *), void *cb_arg);
17
18=head1 DESCRIPTION
19
20RSA_generate_key_ex() generates a key pair and stores it in the B<RSA>
21structure provided in B<rsa>.
22
23The modulus size will be of length B<bits>, and the public exponent will be
24B<e>. Key sizes with B<num> E<lt> 1024 should be considered insecure.
25The exponent is an odd number, typically 3, 17 or 65537.
26
27A callback function may be used to provide feedback about the
28progress of the key generation. If B<cb> is not B<NULL>, it
29will be called as follows using the BN_GENCB_call() function
30described on the L<BN_generate_prime(3)|BN_generate_prime(3)> page:
31
32=over 4
33
34=item *
35
36While a random prime number is generated, it is called as
37described in L<BN_generate_prime(3)|BN_generate_prime(3)>.
38
39=item *
40
41When the n-th randomly generated prime is rejected as not
42suitable for the key, B<BN_GENCB_call(cb, 2, n)> is called.
43
44=item *
45
46When a random p has been found with p-1 relatively prime to B<e>,
47it is called as B<BN_GENCB_call(cb, 3, 0)>.
48
49=back
50
51The process is then repeated for prime q with B<BN_GENCB_call(cb, 3, 1)>.
52
53RSA_generate_key is deprecated (new applications should use
54RSA_generate_key_ex instead). RSA_generate_key works in the same was as
55RSA_generate_key_ex except it uses "old style" call backs. See
56L<BN_generate_prime(3)|BN_generate_prime(3)> for further details.
57
58=head1 RETURN VALUE
59
60If key generation fails, RSA_generate_key() returns B<NULL>.
61
62The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
63
64=head1 BUGS
65
66B<BN_GENCB_call(cb, 2, x)> is used with two different meanings.
67
68RSA_generate_key() goes into an infinite loop for illegal input values.
69
70=head1 SEE ALSO
71
72L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>,
73L<RSA_free(3)|RSA_free(3)>, L<BN_generate_prime(3)|BN_generate_prime(3)>
74
75=head1 HISTORY
76
77The B<cb_arg> argument was added in SSLeay 0.9.0.
78
79=cut
diff --git a/src/lib/libcrypto/doc/RSA_get_ex_new_index.pod b/src/lib/libcrypto/doc/RSA_get_ex_new_index.pod
deleted file mode 100644
index b1ac1167dd..0000000000
--- a/src/lib/libcrypto/doc/RSA_get_ex_new_index.pod
+++ /dev/null
@@ -1,122 +0,0 @@
1=pod
2
3=head1 NAME
4
5RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - add application
6specific data to RSA structures
7
8=head1 SYNOPSIS
9
10 #include <openssl/rsa.h>
11
12 int RSA_get_ex_new_index(long argl, void *argp,
13 CRYPTO_EX_new *new_func,
14 CRYPTO_EX_dup *dup_func,
15 CRYPTO_EX_free *free_func);
16
17 int RSA_set_ex_data(RSA *r, int idx, void *arg);
18
19 void *RSA_get_ex_data(RSA *r, int idx);
20
21 typedef int CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
22 int idx, long argl, void *argp);
23 typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
24 int idx, long argl, void *argp);
25 typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d,
26 int idx, long argl, void *argp);
27
28=head1 DESCRIPTION
29
30Several OpenSSL structures can have application specific data attached to them.
31This has several potential uses, it can be used to cache data associated with
32a structure (for example the hash of some part of the structure) or some
33additional data (for example a handle to the data in an external library).
34
35Since the application data can be anything at all it is passed and retrieved
36as a B<void *> type.
37
38The B<RSA_get_ex_new_index()> function is initially called to "register" some
39new application specific data. It takes three optional function pointers which
40are called when the parent structure (in this case an RSA structure) is
41initially created, when it is copied and when it is freed up. If any or all of
42these function pointer arguments are not used they should be set to NULL. The
43precise manner in which these function pointers are called is described in more
44detail below. B<RSA_get_ex_new_index()> also takes additional long and pointer
45parameters which will be passed to the supplied functions but which otherwise
46have no special meaning. It returns an B<index> which should be stored
47(typically in a static variable) and passed used in the B<idx> parameter in
48the remaining functions. Each successful call to B<RSA_get_ex_new_index()>
49will return an index greater than any previously returned, this is important
50because the optional functions are called in order of increasing index value.
51
52B<RSA_set_ex_data()> is used to set application specific data, the data is
53supplied in the B<arg> parameter and its precise meaning is up to the
54application.
55
56B<RSA_get_ex_data()> is used to retrieve application specific data. The data
57is returned to the application, this will be the same value as supplied to
58a previous B<RSA_set_ex_data()> call.
59
60B<new_func()> is called when a structure is initially allocated (for example
61with B<RSA_new()>. The parent structure members will not have any meaningful
62values at this point. This function will typically be used to allocate any
63application specific structure.
64
65B<free_func()> is called when a structure is being freed up. The dynamic parent
66structure members should not be accessed because they will be freed up when
67this function is called.
68
69B<new_func()> and B<free_func()> take the same parameters. B<parent> is a
70pointer to the parent RSA structure. B<ptr> is a the application specific data
71(this wont be of much use in B<new_func()>. B<ad> is a pointer to the
72B<CRYPTO_EX_DATA> structure from the parent RSA structure: the functions
73B<CRYPTO_get_ex_data()> and B<CRYPTO_set_ex_data()> can be called to manipulate
74it. The B<idx> parameter is the index: this will be the same value returned by
75B<RSA_get_ex_new_index()> when the functions were initially registered. Finally
76the B<argl> and B<argp> parameters are the values originally passed to the same
77corresponding parameters when B<RSA_get_ex_new_index()> was called.
78
79B<dup_func()> is called when a structure is being copied. Pointers to the
80destination and source B<CRYPTO_EX_DATA> structures are passed in the B<to> and
81B<from> parameters respectively. The B<from_d> parameter is passed a pointer to
82the source application data when the function is called, when the function
83returns the value is copied to the destination: the application can thus modify
84the data pointed to by B<from_d> and have different values in the source and
85destination. The B<idx>, B<argl> and B<argp> parameters are the same as those
86in B<new_func()> and B<free_func()>.
87
88=head1 RETURN VALUES
89
90B<RSA_get_ex_new_index()> returns a new index or -1 on failure (note 0 is a
91valid index value).
92
93B<RSA_set_ex_data()> returns 1 on success or 0 on failure.
94
95B<RSA_get_ex_data()> returns the application data or 0 on failure. 0 may also
96be valid application data but currently it can only fail if given an invalid
97B<idx> parameter.
98
99B<new_func()> and B<dup_func()> should return 0 for failure and 1 for success.
100
101On failure an error code can be obtained from
102L<ERR_get_error(3)|ERR_get_error(3)>.
103
104=head1 BUGS
105
106B<dup_func()> is currently never called.
107
108The return value of B<new_func()> is ignored.
109
110The B<new_func()> function isn't very useful because no meaningful values are
111present in the parent RSA structure when it is called.
112
113=head1 SEE ALSO
114
115L<rsa(3)|rsa(3)>, L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>
116
117=head1 HISTORY
118
119RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() are
120available since SSLeay 0.9.0.
121
122=cut
diff --git a/src/lib/libcrypto/doc/RSA_new.pod b/src/lib/libcrypto/doc/RSA_new.pod
deleted file mode 100644
index 0c85dc1d62..0000000000
--- a/src/lib/libcrypto/doc/RSA_new.pod
+++ /dev/null
@@ -1,39 +0,0 @@
1=pod
2
3=head1 NAME
4
5RSA_new, RSA_free - allocate and free RSA objects
6
7=head1 SYNOPSIS
8
9 #include <openssl/rsa.h>
10
11 RSA * RSA_new(void);
12
13 void RSA_free(RSA *rsa);
14
15=head1 DESCRIPTION
16
17RSA_new() allocates and initializes an B<RSA> structure. It is equivalent to
18calling RSA_new_method(NULL).
19
20RSA_free() frees the B<RSA> structure and its components. The key is
21erased before the memory is returned to the system.
22
23=head1 RETURN VALUES
24
25If the allocation fails, RSA_new() returns B<NULL> and sets an error code that
26can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a
27pointer to the newly allocated structure.
28
29=head1 SEE ALSO
30
31L<ERR_get_error(3)|ERR_get_error(3)>, L<rsa(3)|rsa(3)>,
32L<RSA_generate_key(3)|RSA_generate_key(3)>,
33L<RSA_new_method(3)|RSA_new_method(3)>
34
35=head1 HISTORY
36
37RSA_new() and RSA_free() are available in all versions of SSLeay and OpenSSL.
38
39=cut
diff --git a/src/lib/libcrypto/doc/RSA_padding_add_PKCS1_type_1.pod b/src/lib/libcrypto/doc/RSA_padding_add_PKCS1_type_1.pod
deleted file mode 100644
index 1c90b2b44d..0000000000
--- a/src/lib/libcrypto/doc/RSA_padding_add_PKCS1_type_1.pod
+++ /dev/null
@@ -1,121 +0,0 @@
1=pod
2
3=head1 NAME
4
5RSA_padding_add_PKCS1_type_1, RSA_padding_check_PKCS1_type_1,
6RSA_padding_add_PKCS1_type_2, RSA_padding_check_PKCS1_type_2,
7RSA_padding_add_PKCS1_OAEP, RSA_padding_check_PKCS1_OAEP,
8RSA_padding_add_SSLv23, RSA_padding_check_SSLv23,
9RSA_padding_add_none, RSA_padding_check_none - asymmetric encryption
10padding
11
12=head1 SYNOPSIS
13
14 #include <openssl/rsa.h>
15
16 int RSA_padding_add_PKCS1_type_1(unsigned char *to, int tlen,
17 unsigned char *f, int fl);
18
19 int RSA_padding_check_PKCS1_type_1(unsigned char *to, int tlen,
20 unsigned char *f, int fl, int rsa_len);
21
22 int RSA_padding_add_PKCS1_type_2(unsigned char *to, int tlen,
23 unsigned char *f, int fl);
24
25 int RSA_padding_check_PKCS1_type_2(unsigned char *to, int tlen,
26 unsigned char *f, int fl, int rsa_len);
27
28 int RSA_padding_add_PKCS1_OAEP(unsigned char *to, int tlen,
29 unsigned char *f, int fl, unsigned char *p, int pl);
30
31 int RSA_padding_check_PKCS1_OAEP(unsigned char *to, int tlen,
32 unsigned char *f, int fl, int rsa_len, unsigned char *p, int pl);
33
34 int RSA_padding_add_SSLv23(unsigned char *to, int tlen,
35 unsigned char *f, int fl);
36
37 int RSA_padding_check_SSLv23(unsigned char *to, int tlen,
38 unsigned char *f, int fl, int rsa_len);
39
40 int RSA_padding_add_none(unsigned char *to, int tlen,
41 unsigned char *f, int fl);
42
43 int RSA_padding_check_none(unsigned char *to, int tlen,
44 unsigned char *f, int fl, int rsa_len);
45
46=head1 DESCRIPTION
47
48The RSA_padding_xxx_xxx() functions are called from the RSA encrypt,
49decrypt, sign and verify functions. Normally they should not be called
50from application programs.
51
52However, they can also be called directly to implement padding for other
53asymmetric ciphers. RSA_padding_add_PKCS1_OAEP() and
54RSA_padding_check_PKCS1_OAEP() may be used in an application combined
55with B<RSA_NO_PADDING> in order to implement OAEP with an encoding
56parameter.
57
58RSA_padding_add_xxx() encodes B<fl> bytes from B<f> so as to fit into
59B<tlen> bytes and stores the result at B<to>. An error occurs if B<fl>
60does not meet the size requirements of the encoding method.
61
62The following encoding methods are implemented:
63
64=over 4
65
66=item PKCS1_type_1
67
68PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1); used for signatures
69
70=item PKCS1_type_2
71
72PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2)
73
74=item PKCS1_OAEP
75
76PKCS #1 v2.0 EME-OAEP
77
78=item SSLv23
79
80PKCS #1 EME-PKCS1-v1_5 with SSL-specific modification
81
82=item none
83
84simply copy the data
85
86=back
87
88RSA_padding_check_xxx() verifies that the B<fl> bytes at B<f> contain
89a valid encoding for a B<rsa_len> byte RSA key in the respective
90encoding method and stores the recovered data of at most B<tlen> bytes
91(for B<RSA_NO_PADDING>: of size B<tlen>)
92at B<to>.
93
94For RSA_padding_xxx_OAEP(), B<p> points to the encoding parameter
95of length B<pl>. B<p> may be B<NULL> if B<pl> is 0.
96
97=head1 RETURN VALUES
98
99The RSA_padding_add_xxx() functions return 1 on success, 0 on error.
100The RSA_padding_check_xxx() functions return the length of the
101recovered data, -1 on error. Error codes can be obtained by calling
102L<ERR_get_error(3)|ERR_get_error(3)>.
103
104=head1 SEE ALSO
105
106L<RSA_public_encrypt(3)|RSA_public_encrypt(3)>,
107L<RSA_private_decrypt(3)|RSA_private_decrypt(3)>,
108L<RSA_sign(3)|RSA_sign(3)>, L<RSA_verify(3)|RSA_verify(3)>
109
110=head1 HISTORY
111
112RSA_padding_add_PKCS1_type_1(), RSA_padding_check_PKCS1_type_1(),
113RSA_padding_add_PKCS1_type_2(), RSA_padding_check_PKCS1_type_2(),
114RSA_padding_add_SSLv23(), RSA_padding_check_SSLv23(),
115RSA_padding_add_none() and RSA_padding_check_none() appeared in
116SSLeay 0.9.0.
117
118RSA_padding_add_PKCS1_OAEP() and RSA_padding_check_PKCS1_OAEP() were
119added in OpenSSL 0.9.2b.
120
121=cut
diff --git a/src/lib/libcrypto/doc/RSA_print.pod b/src/lib/libcrypto/doc/RSA_print.pod
deleted file mode 100644
index c971e91f4d..0000000000
--- a/src/lib/libcrypto/doc/RSA_print.pod
+++ /dev/null
@@ -1,49 +0,0 @@
1=pod
2
3=head1 NAME
4
5RSA_print, RSA_print_fp,
6DSAparams_print, DSAparams_print_fp, DSA_print, DSA_print_fp,
7DHparams_print, DHparams_print_fp - print cryptographic parameters
8
9=head1 SYNOPSIS
10
11 #include <openssl/rsa.h>
12
13 int RSA_print(BIO *bp, RSA *x, int offset);
14 int RSA_print_fp(FILE *fp, RSA *x, int offset);
15
16 #include <openssl/dsa.h>
17
18 int DSAparams_print(BIO *bp, DSA *x);
19 int DSAparams_print_fp(FILE *fp, DSA *x);
20 int DSA_print(BIO *bp, DSA *x, int offset);
21 int DSA_print_fp(FILE *fp, DSA *x, int offset);
22
23 #include <openssl/dh.h>
24
25 int DHparams_print(BIO *bp, DH *x);
26 int DHparams_print_fp(FILE *fp, DH *x);
27
28=head1 DESCRIPTION
29
30A human-readable hexadecimal output of the components of the RSA
31key, DSA parameters or key or DH parameters is printed to B<bp> or B<fp>.
32
33The output lines are indented by B<offset> spaces.
34
35=head1 RETURN VALUES
36
37These functions return 1 on success, 0 on error.
38
39=head1 SEE ALSO
40
41L<dh(3)|dh(3)>, L<dsa(3)|dsa(3)>, L<rsa(3)|rsa(3)>, L<BN_bn2bin(3)|BN_bn2bin(3)>
42
43=head1 HISTORY
44
45RSA_print(), RSA_print_fp(), DSA_print(), DSA_print_fp(), DH_print(),
46DH_print_fp() are available in all versions of SSLeay and OpenSSL.
47DSAparams_print() and DSAparams_print_fp() were added in SSLeay 0.8.
48
49=cut
diff --git a/src/lib/libcrypto/doc/RSA_private_encrypt.pod b/src/lib/libcrypto/doc/RSA_private_encrypt.pod
deleted file mode 100644
index aa2bc1bd76..0000000000
--- a/src/lib/libcrypto/doc/RSA_private_encrypt.pod
+++ /dev/null
@@ -1,69 +0,0 @@
1=pod
2
3=head1 NAME
4
5RSA_private_encrypt, RSA_public_decrypt - low level signature operations
6
7=head1 SYNOPSIS
8
9 #include <openssl/rsa.h>
10
11 int RSA_private_encrypt(int flen, unsigned char *from,
12 unsigned char *to, RSA *rsa, int padding);
13
14 int RSA_public_decrypt(int flen, unsigned char *from,
15 unsigned char *to, RSA *rsa, int padding);
16
17=head1 DESCRIPTION
18
19These functions handle RSA signatures at a low level.
20
21RSA_private_encrypt() signs the B<flen> bytes at B<from> (usually a
22message digest with an algorithm identifier) using the private key
23B<rsa> and stores the signature in B<to>. B<to> must point to
24B<RSA_size(rsa)> bytes of memory.
25
26B<padding> denotes one of the following modes:
27
28=over 4
29
30=item RSA_PKCS1_PADDING
31
32PKCS #1 v1.5 padding. This function does not handle the B<algorithmIdentifier>
33specified in PKCS #1. When generating or verifying PKCS #1 signatures,
34L<RSA_sign(3)|RSA_sign(3)> and L<RSA_verify(3)|RSA_verify(3)> should be used.
35
36=item RSA_NO_PADDING
37
38Raw RSA signature. This mode should I<only> be used to implement
39cryptographically sound padding modes in the application code.
40Signing user data directly with RSA is insecure.
41
42=back
43
44RSA_public_decrypt() recovers the message digest from the B<flen>
45bytes long signature at B<from> using the signer's public key
46B<rsa>. B<to> must point to a memory section large enough to hold the
47message digest (which is smaller than B<RSA_size(rsa) -
4811>). B<padding> is the padding mode that was used to sign the data.
49
50=head1 RETURN VALUES
51
52RSA_private_encrypt() returns the size of the signature (i.e.,
53RSA_size(rsa)). RSA_public_decrypt() returns the size of the
54recovered message digest.
55
56On error, -1 is returned; the error codes can be
57obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
58
59=head1 SEE ALSO
60
61L<ERR_get_error(3)|ERR_get_error(3)>, L<rsa(3)|rsa(3)>,
62L<RSA_sign(3)|RSA_sign(3)>, L<RSA_verify(3)|RSA_verify(3)>
63
64=head1 HISTORY
65
66The B<padding> argument was added in SSLeay 0.8. RSA_NO_PADDING is
67available since SSLeay 0.9.0.
68
69=cut
diff --git a/src/lib/libcrypto/doc/RSA_public_encrypt.pod b/src/lib/libcrypto/doc/RSA_public_encrypt.pod
deleted file mode 100644
index 4bbee53f09..0000000000
--- a/src/lib/libcrypto/doc/RSA_public_encrypt.pod
+++ /dev/null
@@ -1,82 +0,0 @@
1=pod
2
3=head1 NAME
4
5RSA_public_encrypt, RSA_private_decrypt - RSA public key cryptography
6
7=head1 SYNOPSIS
8
9 #include <openssl/rsa.h>
10
11 int RSA_public_encrypt(int flen, unsigned char *from,
12 unsigned char *to, RSA *rsa, int padding);
13
14 int RSA_private_decrypt(int flen, unsigned char *from,
15 unsigned char *to, RSA *rsa, int padding);
16
17=head1 DESCRIPTION
18
19RSA_public_encrypt() encrypts the B<flen> bytes at B<from> (usually a
20session key) using the public key B<rsa> and stores the ciphertext in
21B<to>. B<to> must point to RSA_size(B<rsa>) bytes of memory.
22
23B<padding> denotes one of the following modes:
24
25=over 4
26
27=item RSA_PKCS1_PADDING
28
29PKCS #1 v1.5 padding. This currently is the most widely used mode.
30
31=item RSA_PKCS1_OAEP_PADDING
32
33EME-OAEP as defined in PKCS #1 v2.0 with SHA-1, MGF1 and an empty
34encoding parameter. This mode is recommended for all new applications.
35
36=item RSA_SSLV23_PADDING
37
38PKCS #1 v1.5 padding with an SSL-specific modification that denotes
39that the server is SSL3 capable.
40
41=item RSA_NO_PADDING
42
43Raw RSA encryption. This mode should I<only> be used to implement
44cryptographically sound padding modes in the application code.
45Encrypting user data directly with RSA is insecure.
46
47=back
48
49B<flen> must be less than RSA_size(B<rsa>) - 11 for the PKCS #1 v1.5
50based padding modes, less than RSA_size(B<rsa>) - 41 for
51RSA_PKCS1_OAEP_PADDING and exactly RSA_size(B<rsa>) for RSA_NO_PADDING.
52
53RSA_private_decrypt() decrypts the B<flen> bytes at B<from> using the
54private key B<rsa> and stores the plaintext in B<to>. B<to> must point
55to a memory section large enough to hold the decrypted data (which is
56smaller than RSA_size(B<rsa>)). B<padding> is the padding mode that
57was used to encrypt the data.
58
59=head1 RETURN VALUES
60
61RSA_public_encrypt() returns the size of the encrypted data (i.e.,
62RSA_size(B<rsa>)). RSA_private_decrypt() returns the size of the
63recovered plaintext.
64
65On error, -1 is returned; the error codes can be
66obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
67
68=head1 CONFORMING TO
69
70SSL, PKCS #1 v2.0
71
72=head1 SEE ALSO
73
74L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>,
75L<RSA_size(3)|RSA_size(3)>
76
77=head1 HISTORY
78
79The B<padding> argument was added in SSLeay 0.8. RSA_NO_PADDING is
80available since SSLeay 0.9.0, OAEP was added in OpenSSL 0.9.2b.
81
82=cut
diff --git a/src/lib/libcrypto/doc/RSA_set_method.pod b/src/lib/libcrypto/doc/RSA_set_method.pod
deleted file mode 100644
index 3f50a89e5c..0000000000
--- a/src/lib/libcrypto/doc/RSA_set_method.pod
+++ /dev/null
@@ -1,201 +0,0 @@
1=pod
2
3=head1 NAME
4
5RSA_set_default_method, RSA_get_default_method, RSA_set_method,
6RSA_get_method, RSA_PKCS1_SSLeay, RSA_null_method, RSA_flags,
7RSA_new_method, RSA_get_default_openssl_method,
8RSA_set_default_openssl_method - select RSA method
9
10=head1 SYNOPSIS
11
12 #include <openssl/rsa.h>
13
14 void RSA_set_default_method(const RSA_METHOD *meth);
15
16 RSA_METHOD *RSA_get_default_method(void);
17
18 int RSA_set_method(RSA *rsa, const RSA_METHOD *meth);
19
20 RSA_METHOD *RSA_get_method(const RSA *rsa);
21
22 RSA_METHOD *RSA_PKCS1_SSLeay(void);
23
24 RSA_METHOD *RSA_null_method(void);
25
26 int RSA_flags(const RSA *rsa);
27
28 RSA *RSA_new_method(RSA_METHOD *method);
29
30=head1 DESCRIPTION
31
32An B<RSA_METHOD> specifies the functions that OpenSSL uses for RSA
33operations. By modifying the method, alternative implementations such as
34hardware accelerators may be used. IMPORTANT: See the NOTES section for
35important information about how these RSA API functions are affected by the
36use of B<ENGINE> API calls.
37
38Initially, the default RSA_METHOD is the OpenSSL internal implementation,
39as returned by RSA_PKCS1_SSLeay().
40
41RSA_set_default_method() makes B<meth> the default method for all RSA
42structures created later. B<NB>: This is true only whilst no ENGINE has
43been set as a default for RSA, so this function is no longer recommended.
44
45RSA_get_default_method() returns a pointer to the current default
46RSA_METHOD. However, the meaningfulness of this result is dependent on
47whether the ENGINE API is being used, so this function is no longer
48recommended.
49
50RSA_set_method() selects B<meth> to perform all operations using the key
51B<rsa>. This will replace the RSA_METHOD used by the RSA key and if the
52previous method was supplied by an ENGINE, the handle to that ENGINE will
53be released during the change. It is possible to have RSA keys that only
54work with certain RSA_METHOD implementations (eg. from an ENGINE module
55that supports embedded hardware-protected keys), and in such cases
56attempting to change the RSA_METHOD for the key can have unexpected
57results.
58
59RSA_get_method() returns a pointer to the RSA_METHOD being used by B<rsa>.
60This method may or may not be supplied by an ENGINE implementation, but if
61it is, the return value can only be guaranteed to be valid as long as the
62RSA key itself is valid and does not have its implementation changed by
63RSA_set_method().
64
65RSA_flags() returns the B<flags> that are set for B<rsa>'s current
66RSA_METHOD. See the BUGS section.
67
68RSA_new_method() allocates and initializes an RSA structure so that
69B<engine> will be used for the RSA operations. If B<engine> is NULL, the
70default ENGINE for RSA operations is used, and if no default ENGINE is set,
71the RSA_METHOD controlled by RSA_set_default_method() is used.
72
73RSA_flags() returns the B<flags> that are set for B<rsa>'s current method.
74
75RSA_new_method() allocates and initializes an B<RSA> structure so that
76B<method> will be used for the RSA operations. If B<method> is B<NULL>,
77the default method is used.
78
79=head1 THE RSA_METHOD STRUCTURE
80
81 typedef struct rsa_meth_st
82 {
83 /* name of the implementation */
84 const char *name;
85
86 /* encrypt */
87 int (*rsa_pub_enc)(int flen, unsigned char *from,
88 unsigned char *to, RSA *rsa, int padding);
89
90 /* verify arbitrary data */
91 int (*rsa_pub_dec)(int flen, unsigned char *from,
92 unsigned char *to, RSA *rsa, int padding);
93
94 /* sign arbitrary data */
95 int (*rsa_priv_enc)(int flen, unsigned char *from,
96 unsigned char *to, RSA *rsa, int padding);
97
98 /* decrypt */
99 int (*rsa_priv_dec)(int flen, unsigned char *from,
100 unsigned char *to, RSA *rsa, int padding);
101
102 /* compute r0 = r0 ^ I mod rsa->n (May be NULL for some
103 implementations) */
104 int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa);
105
106 /* compute r = a ^ p mod m (May be NULL for some implementations) */
107 int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
108 const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
109
110 /* called at RSA_new */
111 int (*init)(RSA *rsa);
112
113 /* called at RSA_free */
114 int (*finish)(RSA *rsa);
115
116 /* RSA_FLAG_EXT_PKEY - rsa_mod_exp is called for private key
117 * operations, even if p,q,dmp1,dmq1,iqmp
118 * are NULL
119 * RSA_FLAG_SIGN_VER - enable rsa_sign and rsa_verify
120 * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match
121 */
122 int flags;
123
124 char *app_data; /* ?? */
125
126 /* sign. For backward compatibility, this is used only
127 * if (flags & RSA_FLAG_SIGN_VER)
128 */
129 int (*rsa_sign)(int type, unsigned char *m, unsigned int m_len,
130 unsigned char *sigret, unsigned int *siglen, RSA *rsa);
131
132 /* verify. For backward compatibility, this is used only
133 * if (flags & RSA_FLAG_SIGN_VER)
134 */
135 int (*rsa_verify)(int type, unsigned char *m, unsigned int m_len,
136 unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
137
138 } RSA_METHOD;
139
140=head1 RETURN VALUES
141
142RSA_PKCS1_SSLeay(), RSA_PKCS1_null_method(), RSA_get_default_method()
143and RSA_get_method() return pointers to the respective RSA_METHODs.
144
145RSA_set_method() returns a pointer to the old RSA_METHOD implementation
146that was replaced. However, this return value should probably be ignored
147because if it was supplied by an ENGINE, the pointer could be invalidated
148at any time if the ENGINE is unloaded (in fact it could be unloaded as a
149result of the RSA_set_method() function releasing its handle to the
150ENGINE). For this reason, the return type may be replaced with a B<void>
151declaration in a future release.
152
153RSA_new_method() returns NULL and sets an error code that can be obtained
154by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation fails. Otherwise
155it returns a pointer to the newly allocated structure.
156
157=head1 NOTES
158
159As of version 0.9.7, RSA_METHOD implementations are grouped together with
160other algorithmic APIs (eg. DSA_METHOD, EVP_CIPHER, etc) into B<ENGINE>
161modules. If a default ENGINE is specified for RSA functionality using an
162ENGINE API function, that will override any RSA defaults set using the RSA
163API (ie. RSA_set_default_method()). For this reason, the ENGINE API is the
164recommended way to control default implementations for use in RSA and other
165cryptographic algorithms.
166
167=head1 BUGS
168
169The behaviour of RSA_flags() is a mis-feature that is left as-is for now
170to avoid creating compatibility problems. RSA functionality, such as the
171encryption functions, are controlled by the B<flags> value in the RSA key
172itself, not by the B<flags> value in the RSA_METHOD attached to the RSA key
173(which is what this function returns). If the flags element of an RSA key
174is changed, the changes will be honoured by RSA functionality but will not
175be reflected in the return value of the RSA_flags() function - in effect
176RSA_flags() behaves more like an RSA_default_flags() function (which does
177not currently exist).
178
179=head1 SEE ALSO
180
181L<rsa(3)|rsa(3)>, L<RSA_new(3)|RSA_new(3)>
182
183=head1 HISTORY
184
185RSA_new_method() and RSA_set_default_method() appeared in SSLeay 0.8.
186RSA_get_default_method(), RSA_set_method() and RSA_get_method() as
187well as the rsa_sign and rsa_verify components of RSA_METHOD were
188added in OpenSSL 0.9.4.
189
190RSA_set_default_openssl_method() and RSA_get_default_openssl_method()
191replaced RSA_set_default_method() and RSA_get_default_method()
192respectively, and RSA_set_method() and RSA_new_method() were altered to use
193B<ENGINE>s rather than B<RSA_METHOD>s during development of the engine
194version of OpenSSL 0.9.6. For 0.9.7, the handling of defaults in the ENGINE
195API was restructured so that this change was reversed, and behaviour of the
196other functions resembled more closely the previous behaviour. The
197behaviour of defaults in the ENGINE API now transparently overrides the
198behaviour of defaults in the RSA API without requiring changing these
199function prototypes.
200
201=cut
diff --git a/src/lib/libcrypto/doc/RSA_sign.pod b/src/lib/libcrypto/doc/RSA_sign.pod
deleted file mode 100644
index 51587bdc41..0000000000
--- a/src/lib/libcrypto/doc/RSA_sign.pod
+++ /dev/null
@@ -1,61 +0,0 @@
1=pod
2
3=head1 NAME
4
5RSA_sign, RSA_verify - RSA signatures
6
7=head1 SYNOPSIS
8
9 #include <openssl/rsa.h>
10
11 int RSA_sign(int type, const unsigned char *m, unsigned int m_len,
12 unsigned char *sigret, unsigned int *siglen, RSA *rsa);
13
14 int RSA_verify(int type, const unsigned char *m, unsigned int m_len,
15 unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
16
17=head1 DESCRIPTION
18
19RSA_sign() signs the message digest B<m> of size B<m_len> using the
20private key B<rsa> as specified in PKCS #1 v2.0. It stores the
21signature in B<sigret> and the signature size in B<siglen>. B<sigret>
22must point to RSA_size(B<rsa>) bytes of memory.
23Note that PKCS #1 adds meta-data, placing limits on the size of the
24key that can be used.
25See L<RSA_private_encrypt(3)|RSA_private_encrypt(3)> for lower-level
26operations.
27
28B<type> denotes the message digest algorithm that was used to generate
29B<m>. It usually is one of B<NID_sha1>, B<NID_ripemd160> and B<NID_md5>;
30see L<objects(3)|objects(3)> for details. If B<type> is B<NID_md5_sha1>,
31an SSL signature (MD5 and SHA1 message digests with PKCS #1 padding
32and no algorithm identifier) is created.
33
34RSA_verify() verifies that the signature B<sigbuf> of size B<siglen>
35matches a given message digest B<m> of size B<m_len>. B<type> denotes
36the message digest algorithm that was used to generate the signature.
37B<rsa> is the signer's public key.
38
39=head1 RETURN VALUES
40
41RSA_sign() returns 1 on success, 0 otherwise. RSA_verify() returns 1
42on successful verification, 0 otherwise.
43
44The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
45
46=head1 CONFORMING TO
47
48SSL, PKCS #1 v2.0
49
50=head1 SEE ALSO
51
52L<ERR_get_error(3)|ERR_get_error(3)>, L<objects(3)|objects(3)>,
53L<rsa(3)|rsa(3)>, L<RSA_private_encrypt(3)|RSA_private_encrypt(3)>,
54L<RSA_public_decrypt(3)|RSA_public_decrypt(3)>
55
56=head1 HISTORY
57
58RSA_sign() and RSA_verify() are available in all versions of SSLeay
59and OpenSSL.
60
61=cut
diff --git a/src/lib/libcrypto/doc/RSA_sign_ASN1_OCTET_STRING.pod b/src/lib/libcrypto/doc/RSA_sign_ASN1_OCTET_STRING.pod
deleted file mode 100644
index 664b46174b..0000000000
--- a/src/lib/libcrypto/doc/RSA_sign_ASN1_OCTET_STRING.pod
+++ /dev/null
@@ -1,57 +0,0 @@
1=pod
2
3=head1 NAME
4
5RSA_sign_ASN1_OCTET_STRING, RSA_verify_ASN1_OCTET_STRING - RSA signatures
6
7=head1 SYNOPSIS
8
9 #include <openssl/rsa.h>
10
11 int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m,
12 unsigned int m_len, unsigned char *sigret, unsigned int *siglen,
13 RSA *rsa);
14
15 int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m,
16 unsigned int m_len, unsigned char *sigbuf, unsigned int siglen,
17 RSA *rsa);
18
19=head1 DESCRIPTION
20
21RSA_sign_ASN1_OCTET_STRING() signs the octet string B<m> of size
22B<m_len> using the private key B<rsa> represented in DER using PKCS #1
23padding. It stores the signature in B<sigret> and the signature size
24in B<siglen>. B<sigret> must point to B<RSA_size(rsa)> bytes of
25memory.
26
27B<dummy> is ignored.
28
29RSA_verify_ASN1_OCTET_STRING() verifies that the signature B<sigbuf>
30of size B<siglen> is the DER representation of a given octet string
31B<m> of size B<m_len>. B<dummy> is ignored. B<rsa> is the signer's
32public key.
33
34=head1 RETURN VALUES
35
36RSA_sign_ASN1_OCTET_STRING() returns 1 on success, 0 otherwise.
37RSA_verify_ASN1_OCTET_STRING() returns 1 on successful verification, 0
38otherwise.
39
40The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
41
42=head1 BUGS
43
44These functions serve no recognizable purpose.
45
46=head1 SEE ALSO
47
48L<ERR_get_error(3)|ERR_get_error(3)>, L<objects(3)|objects(3)>,
49L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<RSA_sign(3)|RSA_sign(3)>,
50L<RSA_verify(3)|RSA_verify(3)>
51
52=head1 HISTORY
53
54RSA_sign_ASN1_OCTET_STRING() and RSA_verify_ASN1_OCTET_STRING() were
55added in SSLeay 0.8.
56
57=cut
diff --git a/src/lib/libcrypto/doc/RSA_size.pod b/src/lib/libcrypto/doc/RSA_size.pod
deleted file mode 100644
index 5b7f835f95..0000000000
--- a/src/lib/libcrypto/doc/RSA_size.pod
+++ /dev/null
@@ -1,33 +0,0 @@
1=pod
2
3=head1 NAME
4
5RSA_size - get RSA modulus size
6
7=head1 SYNOPSIS
8
9 #include <openssl/rsa.h>
10
11 int RSA_size(const RSA *rsa);
12
13=head1 DESCRIPTION
14
15This function returns the RSA modulus size in bytes. It can be used to
16determine how much memory must be allocated for an RSA encrypted
17value.
18
19B<rsa-E<gt>n> must not be B<NULL>.
20
21=head1 RETURN VALUE
22
23The size in bytes.
24
25=head1 SEE ALSO
26
27L<rsa(3)|rsa(3)>
28
29=head1 HISTORY
30
31RSA_size() is available in all versions of SSLeay and OpenSSL.
32
33=cut
diff --git a/src/lib/libcrypto/doc/d2i_RSAPublicKey.pod b/src/lib/libcrypto/doc/d2i_RSAPublicKey.pod
deleted file mode 100644
index 11515d0ace..0000000000
--- a/src/lib/libcrypto/doc/d2i_RSAPublicKey.pod
+++ /dev/null
@@ -1,63 +0,0 @@
1=pod
2
3=head1 NAME
4
5d2i_RSAPublicKey, i2d_RSAPublicKey, d2i_RSAPrivateKey, i2d_RSAPrivateKey,
6d2i_RSA_PUBKEY, i2d_RSA_PUBKEY, i2d_Netscape_RSA,
7d2i_Netscape_RSA - RSA public and private key encoding functions.
8
9=head1 SYNOPSIS
10
11 #include <openssl/rsa.h>
12 #include <openssl/x509.h>
13
14 RSA * d2i_RSAPublicKey(RSA **a, const unsigned char **pp, long length);
15
16 int i2d_RSAPublicKey(RSA *a, unsigned char **pp);
17
18 RSA * d2i_RSA_PUBKEY(RSA **a, const unsigned char **pp, long length);
19
20 int i2d_RSA_PUBKEY(RSA *a, unsigned char **pp);
21
22 RSA * d2i_RSAPrivateKey(RSA **a, const unsigned char **pp, long length);
23
24 int i2d_RSAPrivateKey(RSA *a, unsigned char **pp);
25
26 int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)());
27
28 RSA * d2i_Netscape_RSA(RSA **a, const unsigned char **pp, long length, int (*cb)());
29
30=head1 DESCRIPTION
31
32d2i_RSAPublicKey() and i2d_RSAPublicKey() decode and encode a PKCS#1
33RSAPublicKey structure.
34
35d2i_RSA_PUBKEY() and i2d_RSA_PUBKEY() decode and encode an RSA public key using
36a SubjectPublicKeyInfo (certificate public key) structure.
37
38d2i_RSAPrivateKey(), i2d_RSAPrivateKey() decode and encode a PKCS#1
39RSAPrivateKey structure.
40
41d2i_Netscape_RSA(), i2d_Netscape_RSA() decode and encode an RSA private key in
42NET format.
43
44The usage of all of these functions is similar to the d2i_X509() and
45i2d_X509() described in the L<d2i_X509(3)|d2i_X509(3)> manual page.
46
47=head1 NOTES
48
49The B<RSA> structure passed to the private key encoding functions should have
50all the PKCS#1 private key components present.
51
52The data encoded by the private key functions is unencrypted and therefore
53offers no private key security.
54
55The NET format functions are present to provide compatibility with certain very
56old software. This format has some severe security weaknesses and should be
57avoided if possible.
58
59=head1 SEE ALSO
60
61L<d2i_X509(3)|d2i_X509(3)>
62
63=cut
diff --git a/src/lib/libcrypto/doc/rsa.pod b/src/lib/libcrypto/doc/rsa.pod
deleted file mode 100644
index 829ce24701..0000000000
--- a/src/lib/libcrypto/doc/rsa.pod
+++ /dev/null
@@ -1,123 +0,0 @@
1=pod
2
3=head1 NAME
4
5rsa - RSA public key cryptosystem
6
7=head1 SYNOPSIS
8
9 #include <openssl/rsa.h>
10 #include <openssl/engine.h>
11
12 RSA * RSA_new(void);
13 void RSA_free(RSA *rsa);
14
15 int RSA_public_encrypt(int flen, unsigned char *from,
16 unsigned char *to, RSA *rsa, int padding);
17 int RSA_private_decrypt(int flen, unsigned char *from,
18 unsigned char *to, RSA *rsa, int padding);
19 int RSA_private_encrypt(int flen, unsigned char *from,
20 unsigned char *to, RSA *rsa,int padding);
21 int RSA_public_decrypt(int flen, unsigned char *from,
22 unsigned char *to, RSA *rsa,int padding);
23
24 int RSA_sign(int type, unsigned char *m, unsigned int m_len,
25 unsigned char *sigret, unsigned int *siglen, RSA *rsa);
26 int RSA_verify(int type, unsigned char *m, unsigned int m_len,
27 unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
28
29 int RSA_size(const RSA *rsa);
30
31 RSA *RSA_generate_key(int num, unsigned long e,
32 void (*callback)(int,int,void *), void *cb_arg);
33
34 int RSA_check_key(RSA *rsa);
35
36 int RSA_blinding_on(RSA *rsa, BN_CTX *ctx);
37 void RSA_blinding_off(RSA *rsa);
38
39 void RSA_set_default_method(const RSA_METHOD *meth);
40 const RSA_METHOD *RSA_get_default_method(void);
41 int RSA_set_method(RSA *rsa, const RSA_METHOD *meth);
42 const RSA_METHOD *RSA_get_method(const RSA *rsa);
43 RSA_METHOD *RSA_PKCS1_SSLeay(void);
44 RSA_METHOD *RSA_null_method(void);
45 int RSA_flags(const RSA *rsa);
46 RSA *RSA_new_method(ENGINE *engine);
47
48 int RSA_print(BIO *bp, RSA *x, int offset);
49 int RSA_print_fp(FILE *fp, RSA *x, int offset);
50
51 int RSA_get_ex_new_index(long argl, char *argp, int (*new_func)(),
52 int (*dup_func)(), void (*free_func)());
53 int RSA_set_ex_data(RSA *r,int idx,char *arg);
54 char *RSA_get_ex_data(RSA *r, int idx);
55
56 int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m,
57 unsigned int m_len, unsigned char *sigret, unsigned int *siglen,
58 RSA *rsa);
59 int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m,
60 unsigned int m_len, unsigned char *sigbuf, unsigned int siglen,
61 RSA *rsa);
62
63=head1 DESCRIPTION
64
65These functions implement RSA public key encryption and signatures
66as defined in PKCS #1 v2.0 [RFC 2437].
67
68The B<RSA> structure consists of several BIGNUM components. It can
69contain public as well as private RSA keys:
70
71 struct
72 {
73 BIGNUM *n; // public modulus
74 BIGNUM *e; // public exponent
75 BIGNUM *d; // private exponent
76 BIGNUM *p; // secret prime factor
77 BIGNUM *q; // secret prime factor
78 BIGNUM *dmp1; // d mod (p-1)
79 BIGNUM *dmq1; // d mod (q-1)
80 BIGNUM *iqmp; // q^-1 mod p
81 // ...
82 };
83 RSA
84
85In public keys, the private exponent and the related secret values are
86B<NULL>.
87
88B<p>, B<q>, B<dmp1>, B<dmq1> and B<iqmp> may be B<NULL> in private
89keys, but the RSA operations are much faster when these values are
90available.
91
92Note that RSA keys may use non-standard B<RSA_METHOD> implementations,
93either directly or by the use of B<ENGINE> modules. In some cases (eg. an
94ENGINE providing support for hardware-embedded keys), these BIGNUM values
95will not be used by the implementation or may be used for alternative data
96storage. For this reason, applications should generally avoid using RSA
97structure elements directly and instead use API functions to query or
98modify keys.
99
100=head1 CONFORMING TO
101
102SSL, PKCS #1 v2.0
103
104=head1 PATENTS
105
106RSA was covered by a US patent which expired in September 2000.
107
108=head1 SEE ALSO
109
110L<rsa(1)|rsa(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>,
111L<rand(3)|rand(3)>, L<engine(3)|engine(3)>, L<RSA_new(3)|RSA_new(3)>,
112L<RSA_public_encrypt(3)|RSA_public_encrypt(3)>,
113L<RSA_sign(3)|RSA_sign(3)>, L<RSA_size(3)|RSA_size(3)>,
114L<RSA_generate_key(3)|RSA_generate_key(3)>,
115L<RSA_check_key(3)|RSA_check_key(3)>,
116L<RSA_blinding_on(3)|RSA_blinding_on(3)>,
117L<RSA_set_method(3)|RSA_set_method(3)>, L<RSA_print(3)|RSA_print(3)>,
118L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>,
119L<RSA_private_encrypt(3)|RSA_private_encrypt(3)>,
120L<RSA_sign_ASN1_OCTET_STRING(3)|RSA_sign_ASN1_OCTET_STRING(3)>,
121L<RSA_padding_add_PKCS1_type_1(3)|RSA_padding_add_PKCS1_type_1(3)>
122
123=cut
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-03-21 10:59:54 +0000