lib/libcrypto/man/RSA_padding_add_PKCS1_type_1.3

   1 .\"     $OpenBSD: RSA_padding_add_PKCS1_type_1.3,v 1.8 2018/03/21 16:09:51 schwarze Exp $
   2 .\"     OpenSSL 1e3f62a3 Jul 17 16:47:13 2017 +0200
   3 .\"
   4 .\" This file was written by Ulf Moeller <ulf@openssl.org>.
   5 .\" Copyright (c) 2000 The OpenSSL Project.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\"
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in
  16 .\"    the documentation and/or other materials provided with the
  17 .\"    distribution.
  18 .\"
  19 .\" 3. All advertising materials mentioning features or use of this
  20 .\"    software must display the following acknowledgment:
  21 .\"    "This product includes software developed by the OpenSSL Project
  22 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  23 .\"
  24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  25 .\"    endorse or promote products derived from this software without
  26 .\"    prior written permission. For written permission, please contact
  27 .\"    openssl-core@openssl.org.
  28 .\"
  29 .\" 5. Products derived from this software may not be called "OpenSSL"
  30 .\"    nor may "OpenSSL" appear in their names without prior written
  31 .\"    permission of the OpenSSL Project.
  32 .\"
  33 .\" 6. Redistributions of any form whatsoever must retain the following
  34 .\"    acknowledgment:
  35 .\"    "This product includes software developed by the OpenSSL Project
  36 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  37 .\"
  38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  41 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  50 .\"
  51 .Dd $Mdocdate: March 21 2018 $
  52 .Dt RSA_PADDING_ADD_PKCS1_TYPE_1 3
  53 .Os
  54 .Sh NAME
  55 .Nm RSA_padding_add_PKCS1_type_1 ,
  56 .Nm RSA_padding_check_PKCS1_type_1 ,
  57 .Nm RSA_padding_add_PKCS1_type_2 ,
  58 .Nm RSA_padding_check_PKCS1_type_2 ,
  59 .Nm RSA_padding_add_PKCS1_OAEP ,
  60 .Nm RSA_padding_check_PKCS1_OAEP ,
  61 .Nm RSA_padding_add_none ,
  62 .Nm RSA_padding_check_none
  63 .Nd asymmetric encryption padding
  64 .Sh SYNOPSIS
  65 .In openssl/rsa.h
  66 .Ft int
  67 .Fo RSA_padding_add_PKCS1_type_1
  68 .Fa "unsigned char *to"
  69 .Fa "int tlen"
  70 .Fa "unsigned char *f"
  71 .Fa "int fl"
  72 .Fc
  73 .Ft int
  74 .Fo RSA_padding_check_PKCS1_type_1
  75 .Fa "unsigned char *to"
  76 .Fa "int tlen"
  77 .Fa "unsigned char *f"
  78 .Fa "int fl"
  79 .Fa "int rsa_len"
  80 .Fc
  81 .Ft int
  82 .Fo RSA_padding_add_PKCS1_type_2
  83 .Fa "unsigned char *to"
  84 .Fa "int tlen"
  85 .Fa "unsigned char *f"
  86 .Fa "int fl"
  87 .Fc
  88 .Ft int
  89 .Fo RSA_padding_check_PKCS1_type_2
  90 .Fa "unsigned char *to"
  91 .Fa "int tlen"
  92 .Fa "unsigned char *f"
  93 .Fa "int fl"
  94 .Fa "int rsa_len"
  95 .Fc
  96 .Ft int
  97 .Fo RSA_padding_add_PKCS1_OAEP
  98 .Fa "unsigned char *to"
  99 .Fa "int tlen"
 100 .Fa "unsigned char *f"
 101 .Fa "int fl"
 102 .Fa "unsigned char *p"
 103 .Fa "int pl"
 104 .Fc
 105 .Ft int
 106 .Fo RSA_padding_check_PKCS1_OAEP
 107 .Fa "unsigned char *to"
 108 .Fa "int tlen"
 109 .Fa "unsigned char *f"
 110 .Fa "int fl"
 111 .Fa "int rsa_len"
 112 .Fa "unsigned char *p"
 113 .Fa "int pl"
 114 .Fc
 115 .Ft int
 116 .Fo RSA_padding_add_none
 117 .Fa "unsigned char *to"
 118 .Fa "int tlen"
 119 .Fa "unsigned char *f"
 120 .Fa "int fl"
 121 .Fc
 122 .Ft int
 123 .Fo RSA_padding_check_none
 124 .Fa "unsigned char *to"
 125 .Fa "int tlen"
 126 .Fa "unsigned char *f"
 127 .Fa "int fl"
 128 .Fa "int rsa_len"
 129 .Fc
 130 .Sh DESCRIPTION
 131 These functions are called from the RSA encrypt, decrypt, sign, and
 132 verify functions.
 133 Normally they should not be called from application programs.
 134 .Pp
 135 However, they can also be called directly to implement padding for other
 136 asymmetric ciphers.
 137 .Fn RSA_padding_add_PKCS1_OAEP
 138 and
 139 .Fn RSA_padding_check_PKCS1_OAEP
 140 may be used in an application combined with
 141 .Dv RSA_NO_PADDING
 142 in order to implement OAEP with an encoding parameter.
 143 .Pp
 144 .Fn RSA_padding_add_*
 145 encodes
 146 .Fa fl
 147 bytes from
 148 .Fa f
 149 so as to fit into
 150 .Fa tlen
 151 bytes and stores the result at
 152 .Fa to .
 153 An error occurs if
 154 .Fa fl
 155 does not meet the size requirements of the encoding method.
 156 .Pp
 157 The following encoding methods are implemented:
 158 .Pp
 159 .Bl -tag -width PKCS1_type_2 -compact
 160 .It PKCS1_type_1
 161 PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1);
 162 used for signatures
 163 .It PKCS1_type_2
 164 PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2)
 165 .It PKCS1_OAEP
 166 PKCS #1 v2.0 EME-OAEP
 167 .It none
 168 simply copy the data
 169 .El
 170 .Pp
 171 .Fn RSA_padding_check_*
 172 verifies that the
 173 .Fa fl
 174 bytes at
 175 .Fa f
 176 contain a valid encoding for a
 177 .Fa rsa_len
 178 byte RSA key in the respective encoding method and stores the recovered
 179 data of at most
 180 .Fa tlen
 181 bytes (for
 182 .Dv RSA_NO_PADDING :
 183 of size
 184 .Fa tlen )
 185 at
 186 .Fa to .
 187 .Pp
 188 For
 189 .Fn RSA_padding_*_OAEP ,
 190 .Fa p
 191 points to the encoding parameter of length
 192 .Fa pl .
 193 .Fa p
 194 may be
 195 .Dv NULL
 196 if
 197 .Fa pl
 198 is 0.
 199 .Sh RETURN VALUES
 200 The
 201 .Fn RSA_padding_add_*
 202 functions return 1 on success or 0 on error.
 203 The
 204 .Fn RSA_padding_check_*
 205 functions return the length of the recovered data or -1 on error.
 206 Error codes can be obtained by calling
 207 .Xr ERR_get_error 3 .
 208 .Sh SEE ALSO
 209 .Xr RSA_new 3 ,
 210 .Xr RSA_private_decrypt 3 ,
 211 .Xr RSA_public_encrypt 3 ,
 212 .Xr RSA_sign 3 ,
 213 .Xr RSA_verify 3
 214 .Sh HISTORY
 215 .Fn RSA_padding_add_PKCS1_type_1 ,
 216 .Fn RSA_padding_check_PKCS1_type_1 ,
 217 .Fn RSA_padding_add_PKCS1_type_2 ,
 218 .Fn RSA_padding_check_PKCS1_type_2 ,
 219 .Fn RSA_padding_add_none ,
 220 and
 221 .Fn RSA_padding_check_none
 222 first appeared in SSLeay 0.9.0 and have been available since
 223 .Ox 2.4 .
 224 .Pp
 225 .Fn RSA_padding_add_PKCS1_OAEP
 226 and
 227 .Fn RSA_padding_check_PKCS1_OAEP
 228 first appeared in OpenSSL 0.9.2b and have been available since
 229 .Ox 2.6 .
 230 .Sh BUGS
 231 The
 232 .Fn RSA_padding_check_PKCS1_type_2
 233 padding check leaks timing information which can potentially be
 234 used to mount a Bleichenbacher padding oracle attack.
 235 This is an inherent weakness in the PKCS #1 v1.5 padding design.
 236 Prefer PKCS1_OAEP padding.