X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=doc%2Fman3%2FRSA_padding_add_PKCS1_type_1.pod;h=40eb8f94a938e492f4d2cfb3e9bf16191a0a1163;hp=93911cac97d6f6e405ba0e3b541ad9b07d8d143d;hb=bc42bd6298702a1abf70aa6383d36886dd5af4b3;hpb=1e3f62a3823f7e3db9d403f724fd9d66f5b04cf8

diff --git a/doc/man3/RSA_padding_add_PKCS1_type_1.pod b/doc/man3/RSA_padding_add_PKCS1_type_1.pod
index 93911cac97..40eb8f94a9 100644
--- a/doc/man3/RSA_padding_add_PKCS1_type_1.pod
+++ b/doc/man3/RSA_padding_add_PKCS1_type_1.pod
@@ -5,6 +5,7 @@
 RSA_padding_add_PKCS1_type_1, RSA_padding_check_PKCS1_type_1,
 RSA_padding_add_PKCS1_type_2, RSA_padding_check_PKCS1_type_2,
 RSA_padding_add_PKCS1_OAEP, RSA_padding_check_PKCS1_OAEP,
+RSA_padding_add_PKCS1_OAEP_mgf1, RSA_padding_check_PKCS1_OAEP_mgf1,
 RSA_padding_add_SSLv23, RSA_padding_check_SSLv23,
 RSA_padding_add_none, RSA_padding_check_none - asymmetric encryption
 padding
@@ -14,35 +15,46 @@ padding
  #include <openssl/rsa.h>
 
  int RSA_padding_add_PKCS1_type_1(unsigned char *to, int tlen,
-                                  unsigned char *f, int fl);
+                                  const unsigned char *f, int fl);
 
  int RSA_padding_check_PKCS1_type_1(unsigned char *to, int tlen,
-                                    unsigned char *f, int fl, int rsa_len);
+                                    const unsigned char *f, int fl, int rsa_len);
 
  int RSA_padding_add_PKCS1_type_2(unsigned char *to, int tlen,
-                                  unsigned char *f, int fl);
+                                  const unsigned char *f, int fl);
 
  int RSA_padding_check_PKCS1_type_2(unsigned char *to, int tlen,
-                                    unsigned char *f, int fl, int rsa_len);
+                                    const unsigned char *f, int fl, int rsa_len);
 
  int RSA_padding_add_PKCS1_OAEP(unsigned char *to, int tlen,
-                                unsigned char *f, int fl, unsigned char *p, int pl);
+                                const unsigned char *f, int fl,
+                                const unsigned char *p, int pl);
 
  int RSA_padding_check_PKCS1_OAEP(unsigned char *to, int tlen,
-                                  unsigned char *f, int fl, int rsa_len,
-                                  unsigned char *p, int pl);
+                                  const unsigned char *f, int fl, int rsa_len,
+                                  const unsigned char *p, int pl);
+
+ int RSA_padding_add_PKCS1_OAEP_mgf1(unsigned char *to, int tlen,
+                                     const unsigned char *f, int fl,
+                                     const unsigned char *p, int pl,
+                                     const EVP_MD *md, const EVP_MD *mgf1md);
+
+ int RSA_padding_check_PKCS1_OAEP_mgf1(unsigned char *to, int tlen,
+                                       const unsigned char *f, int fl, int rsa_len,
+                                       const unsigned char *p, int pl,
+                                       const EVP_MD *md, const EVP_MD *mgf1md);
 
  int RSA_padding_add_SSLv23(unsigned char *to, int tlen,
-                            unsigned char *f, int fl);
+                            const unsigned char *f, int fl);
 
  int RSA_padding_check_SSLv23(unsigned char *to, int tlen,
-                              unsigned char *f, int fl, int rsa_len);
+                              const unsigned char *f, int fl, int rsa_len);
 
  int RSA_padding_add_none(unsigned char *to, int tlen,
-                          unsigned char *f, int fl);
+                          const unsigned char *f, int fl);
 
  int RSA_padding_check_none(unsigned char *to, int tlen,
-                            unsigned char *f, int fl, int rsa_len);
+                            const unsigned char *f, int fl, int rsa_len);
 
 =head1 DESCRIPTION
 
@@ -88,6 +100,8 @@ simply copy the data
 
 The random number generator must be seeded prior to calling
 RSA_padding_add_xxx().
+If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
+external circumstances (see L<RAND(7)>), the operation will fail.
 
 RSA_padding_check_xxx() verifies that the B<fl> bytes at B<f> contain
 a valid encoding for a B<rsa_len> byte RSA key in the respective
@@ -98,6 +112,10 @@ at B<to>.
 For RSA_padding_xxx_OAEP(), B<p> points to the encoding parameter
 of length B<pl>. B<p> may be B<NULL> if B<pl> is 0.
 
+For RSA_padding_xxx_OAEP_mgf1(), B<md> points to the md hash,
+if B<md> is B<NULL> that means md=sha1, and B<mgf1md> points to
+the mgf1 hash, if B<mgf1md> is B<NULL> that means mgf1md=md.
+
 =head1 RETURN VALUES
 
 The RSA_padding_add_xxx() functions return 1 on success, 0 on error.
@@ -107,22 +125,34 @@ L<ERR_get_error(3)>.
 
 =head1 WARNING
 
-The RSA_padding_check_PKCS1_type_2() padding check leaks timing
+The result of RSA_padding_check_PKCS1_type_2() is a very sensitive
 information which can potentially be used to mount a Bleichenbacher
 padding oracle attack. This is an inherent weakness in the PKCS #1
-v1.5 padding design. Prefer PKCS1_OAEP padding.
+v1.5 padding design. Prefer PKCS1_OAEP padding. If that is not
+possible, the result of RSA_padding_check_PKCS1_type_2() should be
+checked in constant time if it matches the expected length of the
+plaintext and additionally some application specific consistency
+checks on the plaintext need to be performed in constant time.
+If the plaintext is rejected it must be kept secret which of the
+checks caused the application to reject the message.
+Do not remove the zero-padding from the decrypted raw RSA data
+which was computed by RSA_private_decrypt() with B<RSA_NO_PADDING>,
+as this would create a small timing side channel which could be
+used to mount a Bleichenbacher attack against any padding mode
+including PKCS1_OAEP.
 
 =head1 SEE ALSO
 
 L<RSA_public_encrypt(3)>,
 L<RSA_private_decrypt(3)>,
-L<RSA_sign(3)>, L<RSA_verify(3)>
+L<RSA_sign(3)>, L<RSA_verify(3)>,
+L<RAND(7)>
 
 =head1 COPYRIGHT
 
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.