lib/libcrypto/man/EVP_PKEY_encrypt.3

   1 .\"     $OpenBSD: EVP_PKEY_encrypt.3,v 1.4 2016/11/27 15:23:29 schwarze Exp $
   2 .\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
   3 .\"
   4 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
   5 .\" Copyright (c) 2006, 2009, 2013, 2014, 2016 The OpenSSL Project.
   6 .\" All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\"
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\"
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in
  17 .\"    the documentation and/or other materials provided with the
  18 .\"    distribution.
  19 .\"
  20 .\" 3. All advertising materials mentioning features or use of this
  21 .\"    software must display the following acknowledgment:
  22 .\"    "This product includes software developed by the OpenSSL Project
  23 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  24 .\"
  25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  26 .\"    endorse or promote products derived from this software without
  27 .\"    prior written permission. For written permission, please contact
  28 .\"    openssl-core@openssl.org.
  29 .\"
  30 .\" 5. Products derived from this software may not be called "OpenSSL"
  31 .\"    nor may "OpenSSL" appear in their names without prior written
  32 .\"    permission of the OpenSSL Project.
  33 .\"
  34 .\" 6. Redistributions of any form whatsoever must retain the following
  35 .\"    acknowledgment:
  36 .\"    "This product includes software developed by the OpenSSL Project
  37 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  38 .\"
  39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  42 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  51 .\"
  52 .Dd $Mdocdate: November 27 2016 $
  53 .Dt EVP_PKEY_ENCRYPT 3
  54 .Os
  55 .Sh NAME
  56 .Nm EVP_PKEY_encrypt_init ,
  57 .Nm EVP_PKEY_encrypt
  58 .Nd encrypt using a public key algorithm
  59 .Sh SYNOPSIS
  60 .In openssl/evp.h
  61 .Ft int
  62 .Fo EVP_PKEY_encrypt_init
  63 .Fa "EVP_PKEY_CTX *ctx"
  64 .Fc
  65 .Ft int
  66 .Fo EVP_PKEY_encrypt
  67 .Fa "EVP_PKEY_CTX *ctx"
  68 .Fa "unsigned char *out"
  69 .Fa "size_t *outlen"
  70 .Fa "const unsigned char *in"
  71 .Fa "size_t inlen"
  72 .Fc
  73 .Sh DESCRIPTION
  74 The
  75 .Fn EVP_PKEY_encrypt_init
  76 function initializes a public key algorithm context using key
  77 .Fa ctx->pkey
  78 for an encryption operation.
  79 .Pp
  80 The
  81 .Fn EVP_PKEY_encrypt
  82 function performs a public key encryption operation using
  83 .Fa ctx .
  84 The data to be encrypted is specified using the
  85 .Fa in
  86 and
  87 .Fa inlen
  88 parameters.
  89 If
  90 .Fa out
  91 is
  92 .Dv NULL ,
  93 then the maximum size of the output buffer is written to the
  94 .Fa outlen
  95 parameter.
  96 If
  97 .Fa out
  98 is not
  99 .Dv NULL ,
 100 then before the call the
 101 .Fa outlen
 102 parameter should contain the length of the
 103 .Fa out
 104 buffer.
 105 If the call is successful the encrypted data is written to
 106 .Fa out
 107 and the amount of data written to
 108 .Fa outlen .
 109 .Pp
 110 After the call to
 111 .Fn EVP_PKEY_encrypt_init ,
 112 algorithm specific control operations can be performed to set any
 113 appropriate parameters for the operation.
 114 .Pp
 115 The function
 116 .Fn EVP_PKEY_encrypt
 117 can be called more than once on the same context if several operations
 118 are performed using the same parameters.
 119 .Sh RETURN VALUES
 120 .Fn EVP_PKEY_encrypt_init
 121 and
 122 .Fn EVP_PKEY_encrypt
 123 return 1 for success and 0 or a negative value for failure.
 124 In particular, a return value of -2 indicates the operation is not
 125 supported by the public key algorithm.
 126 .Sh EXAMPLES
 127 Encrypt data using OAEP (for RSA keys).
 128 See also
 129 .Xr PEM_read_PUBKEY 3
 130 and
 131 .Xr d2i_X509 3
 132 for means to load a public key.
 133 You may also simply set
 134 .Ql eng = NULL;
 135 to start with the default OpenSSL RSA implementation:
 136 .Bd -literal -offset indent
 137 #include <openssl/evp.h>
 138 #include <openssl/rsa.h>
 139 #include <openssl/engine.h>
 140
 141 EVP_PKEY_CTX *ctx;
 142 ENGINE *eng;
 143 unsigned char *out, *in;
 144 size_t outlen, inlen;
 145 EVP_PKEY *key;
 146 /* NB: assumes eng, key in, inlen are already set up
 147  * and that key is an RSA public key
 148  */
 149 ctx = EVP_PKEY_CTX_new(key, eng);
 150 if (!ctx)
 151         /* Error occurred */
 152 if (EVP_PKEY_encrypt_init(ctx) <= 0)
 153         /* Error */
 154 if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_OAEP_PADDING) <= 0)
 155         /* Error */
 156
 157 /* Determine buffer length */
 158 if (EVP_PKEY_encrypt(ctx, NULL, &outlen, in, inlen) <= 0)
 159         /* Error */
 160
 161 out = malloc(outlen);
 162
 163 if (!out)
 164         /* malloc failure */
 165
 166 if (EVP_PKEY_encrypt(ctx, out, &outlen, in, inlen) <= 0)
 167         /* Error */
 168
 169 /* Encrypted data is outlen bytes written to buffer out */
 170 .Ed
 171 .Sh SEE ALSO
 172 .Xr EVP_PKEY_CTX_new 3 ,
 173 .Xr EVP_PKEY_decrypt 3 ,
 174 .Xr EVP_PKEY_derive 3 ,
 175 .Xr EVP_PKEY_sign 3 ,
 176 .Xr EVP_PKEY_verify 3 ,
 177 .Xr EVP_PKEY_verify_recover 3
 178 .Sh HISTORY
 179 These functions were first added to OpenSSL 1.0.0.