lib/libcrypto/man/RSA_public_encrypt.3

   1 .\"     $OpenBSD: RSA_public_encrypt.3,v 1.8 2017/08/28 17:41:59 jsing Exp $
   2 .\"     OpenSSL RSA_public_encrypt.pod 1e3f62a3 Jul 17 16:47:13 2017 +0200
   3 .\"
   4 .\" This file was written by Ulf Moeller <ulf@openssl.org>.
   5 .\" Copyright (c) 2000, 2004 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: August 28 2017 $
  52 .Dt RSA_PUBLIC_ENCRYPT 3
  53 .Os
  54 .Sh NAME
  55 .Nm RSA_public_encrypt ,
  56 .Nm RSA_private_decrypt
  57 .Nd RSA public key cryptography
  58 .Sh SYNOPSIS
  59 .In openssl/rsa.h
  60 .Ft int
  61 .Fo RSA_public_encrypt
  62 .Fa "int flen"
  63 .Fa "const unsigned char *from"
  64 .Fa "unsigned char *to"
  65 .Fa "RSA *rsa"
  66 .Fa "int padding"
  67 .Fc
  68 .Ft int
  69 .Fo RSA_private_decrypt
  70 .Fa "int flen"
  71 .Fa "const unsigned char *from"
  72 .Fa "unsigned char *to"
  73 .Fa "RSA *rsa"
  74 .Fa "int padding"
  75 .Fc
  76 .Sh DESCRIPTION
  77 .Fn RSA_public_encrypt
  78 encrypts the
  79 .Fa flen
  80 bytes at
  81 .Fa from
  82 (usually a session key) using the public key
  83 .Fa rsa
  84 and stores the ciphertext in
  85 .Fa to .
  86 .Fa to
  87 must point to
  88 .Fn RSA_size rsa
  89 bytes of memory.
  90 .Pp
  91 .Fa padding
  92 denotes one of the following modes:
  93 .Bl -tag -width Ds
  94 .It Dv RSA_PKCS1_PADDING
  95 PKCS #1 v1.5 padding.
  96 This currently is the most widely used mode.
  97 .It Dv RSA_PKCS1_OAEP_PADDING
  98 EME-OAEP as defined in PKCS #1 v2.0 with SHA-1, MGF1 and an empty
  99 encoding parameter.
 100 This mode is recommended for all new applications.
 101 .It Dv RSA_NO_PADDING
 102 Raw RSA encryption.
 103 This mode should only be used to implement cryptographically sound
 104 padding modes in the application code.
 105 Encrypting user data directly with RSA is insecure.
 106 .El
 107 .Pp
 108 .Fa flen
 109 must be less than
 110 .Fn RSA_size rsa
 111 - 11 for the PKCS #1 v1.5 based padding modes, less than
 112 .Fn RSA_size rsa
 113 - 41 for
 114 .Dv RSA_PKCS1_OAEP_PADDING
 115 and exactly
 116 .Fn RSA_size rsa
 117 for
 118 .Dv RSA_NO_PADDING .
 119 .Pp
 120 .Fn RSA_private_decrypt
 121 decrypts the
 122 .Fa flen
 123 bytes at
 124 .Fa from
 125 using the private key
 126 .Fa rsa
 127 and stores the plaintext in
 128 .Fa to .
 129 .Fa to
 130 must point to a memory section large enough to hold the decrypted data
 131 (which is smaller than
 132 .Fn RSA_size rsa ) .
 133 .Fa padding
 134 is the padding mode that was used to encrypt the data.
 135 .Sh RETURN VALUES
 136 .Fn RSA_public_encrypt
 137 returns the size of the encrypted data (i.e.\&
 138 .Fn RSA_size rsa ) .
 139 .Fn RSA_private_decrypt
 140 returns the size of the recovered plaintext.
 141 .Pp
 142 On error, -1 is returned; the error codes can be obtained by
 143 .Xr ERR_get_error 3 .
 144 .Sh SEE ALSO
 145 .Xr ERR_get_error 3 ,
 146 .Xr RSA_new 3 ,
 147 .Xr RSA_size 3
 148 .Sh STANDARDS
 149 SSL, PKCS #1 v2.0
 150 .Sh HISTORY
 151 The
 152 .Fa padding
 153 argument was added in SSLeay 0.8.
 154 .Dv RSA_NO_PADDING
 155 is available since SSLeay 0.9.0.
 156 OAEP was added in OpenSSL 0.9.2b.
 157 .Sh BUGS
 158 Decryption failures in the
 159 .Dv RSA_PKCS1_PADDING
 160 mode leak information which can potentially be used to mount a
 161 Bleichenbacher padding oracle attack.
 162 This is an inherent weakness in the PKCS #1 v1.5 padding design.
 163 Prefer
 164 .Dv RSA_PKCS1_OAEP_PADDING .