doc/man3/EVP_PKEY_decrypt.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_PKEY_decrypt_init, EVP_PKEY_decrypt_init_ex,
   6 EVP_PKEY_decrypt - decrypt using a public key algorithm
   7
   8 =head1 SYNOPSIS
   9
  10  #include <openssl/evp.h>
  11
  12  int EVP_PKEY_decrypt_init(EVP_PKEY_CTX *ctx);
  13  int EVP_PKEY_decrypt_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);
  14  int EVP_PKEY_decrypt(EVP_PKEY_CTX *ctx,
  15                       unsigned char *out, size_t *outlen,
  16                       const unsigned char *in, size_t inlen);
  17
  18 =head1 DESCRIPTION
  19
  20 The EVP_PKEY_decrypt_init() function initializes a public key algorithm
  21 context using key I<pkey> for a decryption operation.
  22
  23 The EVP_PKEY_decrypt_init_ex() function initializes a public key algorithm
  24 context using key I<pkey> for a decryption operation and sets the
  25 algorithm specific I<params>.
  26
  27 The EVP_PKEY_decrypt() function performs a public key decryption operation
  28 using I<ctx>. The data to be decrypted is specified using the I<in> and
  29 I<inlen> parameters. If I<out> is NULL then the minimum required size of
  30 the output buffer is written to the I<*outlen> parameter.
  31
  32 If I<out> is not NULL then before the call the I<*outlen> parameter must
  33 contain the length of the I<out> buffer. If the call is successful the
  34 decrypted data is written to I<out> and the amount of the decrypted data
  35 written to I<*outlen>, otherwise an error is returned.
  36
  37 =head1 NOTES
  38
  39 After the call to EVP_PKEY_decrypt_init() algorithm specific control
  40 operations can be performed to set any appropriate parameters for the
  41 operation.  These operations can be included in the EVP_PKEY_decrypt_init_ex()
  42 call.
  43
  44 The function EVP_PKEY_decrypt() can be called more than once on the same
  45 context if several operations are performed using the same parameters.
  46
  47 =head1 RETURN VALUES
  48
  49 EVP_PKEY_decrypt_init(), EVP_PKEY_decrypt_init_ex() and EVP_PKEY_decrypt()
  50 return 1 for success and 0 or a negative value for failure. In particular a
  51 return value of -2 indicates the operation is not supported by the public key
  52 algorithm.
  53
  54 =head1 WARNINGS
  55
  56 In OpenSSL versions before 3.1.0, when used in PKCS#1 v1.5 padding,
  57 both the return value from the EVP_PKEY_decrypt() and the B<outlen> provided
  58 information useful in mounting a Bleichenbacher attack against the
  59 used private key. They had to processed in a side-channel free way.
  60
  61 Since version 3.1.0, the EVP_PKEY_decrypt() method when used with PKCS#1
  62 v1.5 padding doesn't return an error in case it detects an error in padding,
  63 instead it returns a pseudo-randomly generated message, removing the need
  64 of side-channel secure code from applications using OpenSSL.
  65
  66 =head1 EXAMPLES
  67
  68 Decrypt data using OAEP (for RSA keys):
  69
  70  #include <openssl/evp.h>
  71  #include <openssl/rsa.h>
  72
  73  EVP_PKEY_CTX *ctx;
  74  ENGINE *eng;
  75  unsigned char *out, *in;
  76  size_t outlen, inlen;
  77  EVP_PKEY *key;
  78
  79  /*
  80   * NB: assumes key, eng, in, inlen are already set up
  81   * and that key is an RSA private key
  82   */
  83  ctx = EVP_PKEY_CTX_new(key, eng);
  84  if (!ctx)
  85      /* Error occurred */
  86  if (EVP_PKEY_decrypt_init(ctx) <= 0)
  87      /* Error */
  88  if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_OAEP_PADDING) <= 0)
  89      /* Error */
  90
  91  /* Determine buffer length */
  92  if (EVP_PKEY_decrypt(ctx, NULL, &outlen, in, inlen) <= 0)
  93      /* Error */
  94
  95  out = OPENSSL_malloc(outlen);
  96
  97  if (!out)
  98      /* malloc failure */
  99
 100  if (EVP_PKEY_decrypt(ctx, out, &outlen, in, inlen) <= 0)
 101      /* Error */
 102
 103  /* Decrypted data is outlen bytes written to buffer out */
 104
 105 =head1 SEE ALSO
 106
 107 L<EVP_PKEY_CTX_new(3)>,
 108 L<EVP_PKEY_encrypt(3)>,
 109 L<EVP_PKEY_sign(3)>,
 110 L<EVP_PKEY_verify(3)>,
 111 L<EVP_PKEY_verify_recover(3)>,
 112 L<EVP_PKEY_derive(3)>
 113
 114 =head1 HISTORY
 115
 116 These functions were added in OpenSSL 1.0.0.
 117
 118 =head1 COPYRIGHT
 119
 120 Copyright 2006-2021 The OpenSSL Project Authors. All Rights Reserved.
 121
 122 Licensed under the Apache License 2.0 (the "License").  You may not use
 123 this file except in compliance with the License.  You can obtain a copy
 124 in the file LICENSE in the source distribution or at
 125 L<https://www.openssl.org/source/license.html>.
 126
 127 =cut