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