RSA_padding_add_PKCS1_type_1.pod revision 344604 
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
88The random number generator must be seeded prior to calling
89RSA_padding_add_xxx().
90
91RSA_padding_check_xxx() verifies that the B<fl> bytes at B<f> contain
92a valid encoding for a B<rsa_len> byte RSA key in the respective
93encoding method and stores the recovered data of at most B<tlen> bytes
94(for B<RSA_NO_PADDING>: of size B<tlen>)
95at B<to>.
96
97For RSA_padding_xxx_OAEP(), B<p> points to the encoding parameter
98of length B<pl>. B<p> may be B<NULL> if B<pl> is 0.
99
100=head1 RETURN VALUES
101
102The RSA_padding_add_xxx() functions return 1 on success, 0 on error.
103The RSA_padding_check_xxx() functions return the length of the
104recovered data, -1 on error. Error codes can be obtained by calling
105L<ERR_get_error(3)|ERR_get_error(3)>.
106
107=head1 WARNING
108
109The RSA_padding_check_PKCS1_type_2() padding check leaks timing
110information which can potentially be used to mount a Bleichenbacher
111padding oracle attack. This is an inherent weakness in the PKCS #1
112v1.5 padding design. Prefer PKCS1_OAEP padding. Otherwise it can
113be recommended to pass zero-padded B<f>, so that B<fl> equals to
114B<rsa_len>, and if fixed by protocol, B<tlen> being set to the
115expected length. In such case leakage would be minimal, it would
116take attacker's ability to observe memory access pattern with byte
117granilarity as it occurs, post-factum timing analysis won't do.
118
119=head1 SEE ALSO
120
121L<RSA_public_encrypt(3)|RSA_public_encrypt(3)>,
122L<RSA_private_decrypt(3)|RSA_private_decrypt(3)>,
123L<RSA_sign(3)|RSA_sign(3)>, L<RSA_verify(3)|RSA_verify(3)>
124
125=head1 HISTORY
126
127RSA_padding_add_PKCS1_type_1(), RSA_padding_check_PKCS1_type_1(),
128RSA_padding_add_PKCS1_type_2(), RSA_padding_check_PKCS1_type_2(),
129RSA_padding_add_SSLv23(), RSA_padding_check_SSLv23(),
130RSA_padding_add_none() and RSA_padding_check_none() appeared in
131SSLeay 0.9.0.
132
133RSA_padding_add_PKCS1_OAEP() and RSA_padding_check_PKCS1_OAEP() were
134added in OpenSSL 0.9.2b.
135
136=cut
137