lib/libcrypto/man/RSA_padding_add_PKCS1_type_1.3

   1 .\"     $OpenBSD: RSA_padding_add_PKCS1_type_1.3,v 1.4 2016/12/11 12:21:48 schwarze Exp $
   2 .\"     OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
   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: December 11 2016 $
  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_SSLv23 ,
  62 .Nm RSA_padding_check_SSLv23 ,
  63 .Nm RSA_padding_add_none ,
  64 .Nm RSA_padding_check_none
  65 .Nd asymmetric encryption padding
  66 .Sh SYNOPSIS
  67 .In openssl/rsa.h
  68 .Ft int
  69 .Fo RSA_padding_add_PKCS1_type_1
  70 .Fa "unsigned char *to"
  71 .Fa "int tlen"
  72 .Fa "unsigned char *f"
  73 .Fa "int fl"
  74 .Fc
  75 .Ft int
  76 .Fo RSA_padding_check_PKCS1_type_1
  77 .Fa "unsigned char *to"
  78 .Fa "int tlen"
  79 .Fa "unsigned char *f"
  80 .Fa "int fl"
  81 .Fa "int rsa_len"
  82 .Fc
  83 .Ft int
  84 .Fo RSA_padding_add_PKCS1_type_2
  85 .Fa "unsigned char *to"
  86 .Fa "int tlen"
  87 .Fa "unsigned char *f"
  88 .Fa "int fl"
  89 .Fc
  90 .Ft int
  91 .Fo RSA_padding_check_PKCS1_type_2
  92 .Fa "unsigned char *to"
  93 .Fa "int tlen"
  94 .Fa "unsigned char *f"
  95 .Fa "int fl"
  96 .Fa "int rsa_len"
  97 .Fc
  98 .Ft int
  99 .Fo RSA_padding_add_PKCS1_OAEP
 100 .Fa "unsigned char *to"
 101 .Fa "int tlen"
 102 .Fa "unsigned char *f"
 103 .Fa "int fl"
 104 .Fa "unsigned char *p"
 105 .Fa "int pl"
 106 .Fc
 107 .Ft int
 108 .Fo RSA_padding_check_PKCS1_OAEP
 109 .Fa "unsigned char *to"
 110 .Fa "int tlen"
 111 .Fa "unsigned char *f"
 112 .Fa "int fl"
 113 .Fa "int rsa_len"
 114 .Fa "unsigned char *p"
 115 .Fa "int pl"
 116 .Fc
 117 .Ft int
 118 .Fo RSA_padding_add_SSLv23
 119 .Fa "unsigned char *to"
 120 .Fa "int tlen"
 121 .Fa "unsigned char *f"
 122 .Fa "int fl"
 123 .Fc
 124 .Ft int
 125 .Fo RSA_padding_check_SSLv23
 126 .Fa "unsigned char *to"
 127 .Fa "int tlen"
 128 .Fa "unsigned char *f"
 129 .Fa "int fl"
 130 .Fa "int rsa_len"
 131 .Fc
 132 .Ft int
 133 .Fo RSA_padding_add_none
 134 .Fa "unsigned char *to"
 135 .Fa "int tlen"
 136 .Fa "unsigned char *f"
 137 .Fa "int fl"
 138 .Fc
 139 .Ft int
 140 .Fo RSA_padding_check_none
 141 .Fa "unsigned char *to"
 142 .Fa "int tlen"
 143 .Fa "unsigned char *f"
 144 .Fa "int fl"
 145 .Fa "int rsa_len"
 146 .Fc
 147 .Sh DESCRIPTION
 148 These functions are called from the RSA encrypt, decrypt, sign, and
 149 verify functions.
 150 Normally they should not be called from application programs.
 151 .Pp
 152 However, they can also be called directly to implement padding for other
 153 asymmetric ciphers.
 154 .Fn RSA_padding_add_PKCS1_OAEP
 155 and
 156 .Fn RSA_padding_check_PKCS1_OAEP
 157 may be used in an application combined with
 158 .Dv RSA_NO_PADDING
 159 in order to implement OAEP with an encoding parameter.
 160 .Pp
 161 .Fn RSA_padding_add_*
 162 encodes
 163 .Fa fl
 164 bytes from
 165 .Fa f
 166 so as to fit into
 167 .Fa tlen
 168 bytes and stores the result at
 169 .Fa to .
 170 An error occurs if
 171 .Fa fl
 172 does not meet the size requirements of the encoding method.
 173 .Pp
 174 The following encoding methods are implemented:
 175 .Pp
 176 .Bl -tag -width PKCS1_type_2 -compact
 177 .It PKCS1_type_1
 178 PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1);
 179 used for signatures
 180 .It PKCS1_type_2
 181 PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2)
 182 .It PKCS1_OAEP
 183 PKCS #1 v2.0 EME-OAEP
 184 .It SSLv23
 185 PKCS #1 EME-PKCS1-v1_5 with SSL-specific modification
 186 .It none
 187 simply copy the data
 188 .El
 189 .Pp
 190 .Fn RSA_padding_check_*
 191 verifies that the
 192 .Fa fl
 193 bytes at
 194 .Fa f
 195 contain a valid encoding for a
 196 .Fa rsa_len
 197 byte RSA key in the respective encoding method and stores the recovered
 198 data of at most
 199 .Fa tlen
 200 bytes (for
 201 .Dv RSA_NO_PADDING :
 202 of size
 203 .Fa tlen )
 204 at
 205 .Fa to .
 206 .Pp
 207 For
 208 .Fn RSA_padding_*_OAEP ,
 209 .Fa p
 210 points to the encoding parameter of length
 211 .Fa pl .
 212 .Fa p
 213 may be
 214 .Dv NULL
 215 if
 216 .Fa pl
 217 is 0.
 218 .Sh RETURN VALUES
 219 The
 220 .Fn RSA_padding_add_*
 221 functions return 1 on success or 0 on error.
 222 The
 223 .Fn RSA_padding_check_*
 224 functions return the length of the recovered data or -1 on error.
 225 Error codes can be obtained by calling
 226 .Xr ERR_get_error 3 .
 227 .Sh SEE ALSO
 228 .Xr RSA_new 3 ,
 229 .Xr RSA_private_decrypt 3 ,
 230 .Xr RSA_public_encrypt 3 ,
 231 .Xr RSA_sign 3 ,
 232 .Xr RSA_verify 3
 233 .Sh HISTORY
 234 .Fn RSA_padding_add_PKCS1_type_1 ,
 235 .Fn RSA_padding_check_PKCS1_type_1 ,
 236 .Fn RSA_padding_add_PKCS1_type_2 ,
 237 .Fn RSA_padding_check_PKCS1_type_2 ,
 238 .Fn RSA_padding_add_SSLv23 ,
 239 .Fn RSA_padding_check_SSLv23 ,
 240 .Fn RSA_padding_add_none ,
 241 and
 242 .Fn RSA_padding_check_none
 243 appeared in SSLeay 0.9.0.
 244 .Pp
 245 .Fn RSA_padding_add_PKCS1_OAEP
 246 and
 247 .Fn RSA_padding_check_PKCS1_OAEP
 248 were added in OpenSSL 0.9.2b.