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_PKCS1_OAEP_mgf1, RSA_padding_check_PKCS1_OAEP_mgf1, 9RSA_padding_add_SSLv23, RSA_padding_check_SSLv23, 10RSA_padding_add_none, RSA_padding_check_none - asymmetric encryption 11padding 12 13=head1 SYNOPSIS 14 15 #include <openssl/rsa.h> 16 17 int RSA_padding_add_PKCS1_type_1(unsigned char *to, int tlen, 18 const unsigned char *f, int fl); 19 20 int RSA_padding_check_PKCS1_type_1(unsigned char *to, int tlen, 21 const unsigned char *f, int fl, int rsa_len); 22 23 int RSA_padding_add_PKCS1_type_2(unsigned char *to, int tlen, 24 const unsigned char *f, int fl); 25 26 int RSA_padding_check_PKCS1_type_2(unsigned char *to, int tlen, 27 const unsigned char *f, int fl, int rsa_len); 28 29 int RSA_padding_add_PKCS1_OAEP(unsigned char *to, int tlen, 30 const unsigned char *f, int fl, 31 const unsigned char *p, int pl); 32 33 int RSA_padding_check_PKCS1_OAEP(unsigned char *to, int tlen, 34 const unsigned char *f, int fl, int rsa_len, 35 const unsigned char *p, int pl); 36 37 int RSA_padding_add_PKCS1_OAEP_mgf1(unsigned char *to, int tlen, 38 const unsigned char *f, int fl, 39 const unsigned char *p, int pl, 40 const EVP_MD *md, const EVP_MD *mgf1md); 41 42 int RSA_padding_check_PKCS1_OAEP_mgf1(unsigned char *to, int tlen, 43 const unsigned char *f, int fl, int rsa_len, 44 const unsigned char *p, int pl, 45 const EVP_MD *md, const EVP_MD *mgf1md); 46 47 int RSA_padding_add_SSLv23(unsigned char *to, int tlen, 48 const unsigned char *f, int fl); 49 50 int RSA_padding_check_SSLv23(unsigned char *to, int tlen, 51 const unsigned char *f, int fl, int rsa_len); 52 53 int RSA_padding_add_none(unsigned char *to, int tlen, 54 const unsigned char *f, int fl); 55 56 int RSA_padding_check_none(unsigned char *to, int tlen, 57 const unsigned char *f, int fl, int rsa_len); 58 59=head1 DESCRIPTION 60 61The RSA_padding_xxx_xxx() functions are called from the RSA encrypt, 62decrypt, sign and verify functions. Normally they should not be called 63from application programs. 64 65However, they can also be called directly to implement padding for other 66asymmetric ciphers. RSA_padding_add_PKCS1_OAEP() and 67RSA_padding_check_PKCS1_OAEP() may be used in an application combined 68with B<RSA_NO_PADDING> in order to implement OAEP with an encoding 69parameter. 70 71RSA_padding_add_xxx() encodes B<fl> bytes from B<f> so as to fit into 72B<tlen> bytes and stores the result at B<to>. An error occurs if B<fl> 73does not meet the size requirements of the encoding method. 74 75The following encoding methods are implemented: 76 77=over 4 78 79=item PKCS1_type_1 80 81PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1); used for signatures 82 83=item PKCS1_type_2 84 85PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2) 86 87=item PKCS1_OAEP 88 89PKCS #1 v2.0 EME-OAEP 90 91=item SSLv23 92 93PKCS #1 EME-PKCS1-v1_5 with SSL-specific modification 94 95=item none 96 97simply copy the data 98 99=back 100 101The random number generator must be seeded prior to calling 102RSA_padding_add_xxx(). 103If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to 104external circumstances (see L<RAND(7)>), the operation will fail. 105 106RSA_padding_check_xxx() verifies that the B<fl> bytes at B<f> contain 107a valid encoding for a B<rsa_len> byte RSA key in the respective 108encoding method and stores the recovered data of at most B<tlen> bytes 109(for B<RSA_NO_PADDING>: of size B<tlen>) 110at B<to>. 111 112For RSA_padding_xxx_OAEP(), B<p> points to the encoding parameter 113of length B<pl>. B<p> may be B<NULL> if B<pl> is 0. 114 115For RSA_padding_xxx_OAEP_mgf1(), B<md> points to the md hash, 116if B<md> is B<NULL> that means md=sha1, and B<mgf1md> points to 117the mgf1 hash, if B<mgf1md> is B<NULL> that means mgf1md=md. 118 119=head1 RETURN VALUES 120 121The RSA_padding_add_xxx() functions return 1 on success, 0 on error. 122The RSA_padding_check_xxx() functions return the length of the 123recovered data, -1 on error. Error codes can be obtained by calling 124L<ERR_get_error(3)>. 125 126=head1 WARNINGS 127 128The result of RSA_padding_check_PKCS1_type_2() is a very sensitive 129information which can potentially be used to mount a Bleichenbacher 130padding oracle attack. This is an inherent weakness in the PKCS #1 131v1.5 padding design. Prefer PKCS1_OAEP padding. If that is not 132possible, the result of RSA_padding_check_PKCS1_type_2() should be 133checked in constant time if it matches the expected length of the 134plaintext and additionally some application specific consistency 135checks on the plaintext need to be performed in constant time. 136If the plaintext is rejected it must be kept secret which of the 137checks caused the application to reject the message. 138Do not remove the zero-padding from the decrypted raw RSA data 139which was computed by RSA_private_decrypt() with B<RSA_NO_PADDING>, 140as this would create a small timing side channel which could be 141used to mount a Bleichenbacher attack against any padding mode 142including PKCS1_OAEP. 143 144=head1 SEE ALSO 145 146L<RSA_public_encrypt(3)>, 147L<RSA_private_decrypt(3)>, 148L<RSA_sign(3)>, L<RSA_verify(3)>, 149L<RAND(7)> 150 151=head1 COPYRIGHT 152 153Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved. 154 155Licensed under the OpenSSL license (the "License"). You may not use 156this file except in compliance with the License. You can obtain a copy 157in the file LICENSE in the source distribution or at 158L<https://www.openssl.org/source/license.html>. 159 160=cut 161