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