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_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,
  33                                   unsigned char *p, int pl);
  34
  35  int RSA_padding_add_SSLv23(unsigned char *to, int tlen,
  36                             unsigned char *f, int fl);
  37
  38  int RSA_padding_check_SSLv23(unsigned char *to, int tlen,
  39                               unsigned char *f, int fl, int rsa_len);
  40
  41  int RSA_padding_add_none(unsigned char *to, int tlen,
  42                           unsigned char *f, int fl);
  43
  44  int RSA_padding_check_none(unsigned char *to, int tlen,
  45                             unsigned char *f, int fl, int rsa_len);
  46
  47 =head1 DESCRIPTION
  48
  49 The RSA_padding_xxx_xxx() functions are called from the RSA encrypt,
  50 decrypt, sign and verify functions. Normally they should not be called
  51 from application programs.
  52
  53 However, they can also be called directly to implement padding for other
  54 asymmetric ciphers. RSA_padding_add_PKCS1_OAEP() and
  55 RSA_padding_check_PKCS1_OAEP() may be used in an application combined
  56 with B<RSA_NO_PADDING> in order to implement OAEP with an encoding
  57 parameter.
  58
  59 RSA_padding_add_xxx() encodes B<fl> bytes from B<f> so as to fit into
  60 B<tlen> bytes and stores the result at B<to>. An error occurs if B<fl>
  61 does not meet the size requirements of the encoding method.
  62
  63 The following encoding methods are implemented:
  64
  65 =over 4
  66
  67 =item PKCS1_type_1
  68
  69 PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1); used for signatures
  70
  71 =item PKCS1_type_2
  72
  73 PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2)
  74
  75 =item PKCS1_OAEP
  76
  77 PKCS #1 v2.0 EME-OAEP
  78
  79 =item SSLv23
  80
  81 PKCS #1 EME-PKCS1-v1_5 with SSL-specific modification
  82
  83 =item none
  84
  85 simply copy the data
  86
  87 =back
  88
  89 The random number generator must be seeded prior to calling
  90 RSA_padding_add_xxx().
  91
  92 RSA_padding_check_xxx() verifies that the B<fl> bytes at B<f> contain
  93 a valid encoding for a B<rsa_len> byte RSA key in the respective
  94 encoding method and stores the recovered data of at most B<tlen> bytes
  95 (for B<RSA_NO_PADDING>: of size B<tlen>)
  96 at B<to>.
  97
  98 For RSA_padding_xxx_OAEP(), B<p> points to the encoding parameter
  99 of length B<pl>. B<p> may be B<NULL> if B<pl> is 0.
 100
 101 =head1 RETURN VALUES
 102
 103 The RSA_padding_add_xxx() functions return 1 on success, 0 on error.
 104 The RSA_padding_check_xxx() functions return the length of the
 105 recovered data, -1 on error. Error codes can be obtained by calling
 106 L<ERR_get_error(3)>.
 107
 108 =head1 WARNING
 109
 110 The RSA_padding_check_PKCS1_type_2() padding check leaks timing
 111 information which can potentially be used to mount a Bleichenbacher
 112 padding oracle attack. This is an inherent weakness in the PKCS #1
 113 v1.5 padding design. Prefer PKCS1_OAEP padding.
 114
 115 =head1 SEE ALSO
 116
 117 L<RSA_public_encrypt(3)>,
 118 L<RSA_private_decrypt(3)>,
 119 L<RSA_sign(3)>, L<RSA_verify(3)>
 120
 121 =head1 COPYRIGHT
 122
 123 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
 124
 125 Licensed under the OpenSSL license (the "License").  You may not use
 126 this file except in compliance with the License.  You can obtain a copy
 127 in the file LICENSE in the source distribution or at
 128 L<https://www.openssl.org/source/license.html>.
 129
 130 =cut