49340f1399b80aa173c18b6b2a653ae238055ed5
[openssl.git] / doc / man3 / RSA_padding_add_PKCS1_type_1.pod
1 =pod
2
3 =head1 NAME
4
5 RSA_padding_add_PKCS1_type_1, RSA_padding_check_PKCS1_type_1,
6 RSA_padding_add_PKCS1_type_2, RSA_padding_check_PKCS1_type_2,
7 RSA_padding_add_PKCS1_OAEP, RSA_padding_check_PKCS1_OAEP,
8 RSA_padding_add_SSLv23, RSA_padding_check_SSLv23,
9 RSA_padding_add_none, RSA_padding_check_none - asymmetric encryption
10 padding
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,
33                                   unsigned char *p, int pl);
34
35  int RSA_padding_add_SSLv23(unsigned char *to, int tlen,
36                             unsigned char *f, int fl);
37
38  int RSA_padding_check_SSLv23(unsigned char *to, int tlen,
39                               unsigned char *f, int fl, int rsa_len);
40
41  int RSA_padding_add_none(unsigned char *to, int tlen,
42                           unsigned char *f, int fl);
43
44  int RSA_padding_check_none(unsigned char *to, int tlen,
45                             unsigned char *f, int fl, int rsa_len);
46
47 =head1 DESCRIPTION
48
49 The RSA_padding_xxx_xxx() functions are called from the RSA encrypt,
50 decrypt, sign and verify functions. Normally they should not be called
51 from application programs.
52
53 However, they can also be called directly to implement padding for other
54 asymmetric ciphers. RSA_padding_add_PKCS1_OAEP() and
55 RSA_padding_check_PKCS1_OAEP() may be used in an application combined
56 with B<RSA_NO_PADDING> in order to implement OAEP with an encoding
57 parameter.
58
59 RSA_padding_add_xxx() encodes B<fl> bytes from B<f> so as to fit into
60 B<tlen> bytes and stores the result at B<to>. An error occurs if B<fl>
61 does not meet the size requirements of the encoding method.
62
63 The following encoding methods are implemented:
64
65 =over 4
66
67 =item PKCS1_type_1
68
69 PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1); used for signatures
70
71 =item PKCS1_type_2
72
73 PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2)
74
75 =item PKCS1_OAEP
76
77 PKCS #1 v2.0 EME-OAEP
78
79 =item SSLv23
80
81 PKCS #1 EME-PKCS1-v1_5 with SSL-specific modification
82
83 =item none
84
85 simply copy the data
86
87 =back
88
89 The random number generator must be seeded prior to calling
90 RSA_padding_add_xxx().
91
92 RSA_padding_check_xxx() verifies that the B<fl> bytes at B<f> contain
93 a valid encoding for a B<rsa_len> byte RSA key in the respective
94 encoding method and stores the recovered data of at most B<tlen> bytes
95 (for B<RSA_NO_PADDING>: of size B<tlen>)
96 at B<to>.
97
98 For RSA_padding_xxx_OAEP(), B<p> points to the encoding parameter
99 of length B<pl>. B<p> may be B<NULL> if B<pl> is 0.
100
101 =head1 RETURN VALUES
102
103 The RSA_padding_add_xxx() functions return 1 on success, 0 on error.
104 The RSA_padding_check_xxx() functions return the length of the
105 recovered data, -1 on error. Error codes can be obtained by calling
106 L<ERR_get_error(3)>.
107
108 =head1 WARNING
109
110 The RSA_padding_check_PKCS1_type_2() padding check leaks timing
111 information which can potentially be used to mount a Bleichenbacher
112 padding oracle attack. This is an inherent weakness in the PKCS #1
113 v1.5 padding design. Prefer PKCS1_OAEP padding. Otherwise it can
114 be recommended to pass zero-padded B<f>, so that B<fl> equals to
115 B<rsa_len>, and if fixed by protocol, B<tlen> being set to the
116 expected length. In such case leakage would be minimal, it would
117 take attacker's ability to observe memory access pattern with byte
118 granilarity as it occurs, post-factum timing analysis won't do.
119
120 =head1 SEE ALSO
121
122 L<RSA_public_encrypt(3)>,
123 L<RSA_private_decrypt(3)>,
124 L<RSA_sign(3)>, L<RSA_verify(3)>
125
126 =head1 COPYRIGHT
127
128 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
129
130 Licensed under the Apache License 2.0 (the "License").  You may not use
131 this file except in compliance with the License.  You can obtain a copy
132 in the file LICENSE in the source distribution or at
133 L<https://www.openssl.org/source/license.html>.
134
135 =cut