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