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