1b077aed3SPierre Pronchery=pod 2b077aed3SPierre Pronchery 3b077aed3SPierre Pronchery=head1 NAME 4b077aed3SPierre Pronchery 5b077aed3SPierre ProncheryEVP_PKEY_decapsulate_init, EVP_PKEY_decapsulate 6*aa795734SPierre Pronchery- Key decapsulation using a KEM algorithm with a private key 7b077aed3SPierre Pronchery 8b077aed3SPierre Pronchery=head1 SYNOPSIS 9b077aed3SPierre Pronchery 10b077aed3SPierre Pronchery #include <openssl/evp.h> 11b077aed3SPierre Pronchery 12b077aed3SPierre Pronchery int EVP_PKEY_decapsulate_init(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]); 13b077aed3SPierre Pronchery int EVP_PKEY_decapsulate(EVP_PKEY_CTX *ctx, 14*aa795734SPierre Pronchery unsigned char *unwrapped, size_t *unwrappedlen, 15b077aed3SPierre Pronchery const unsigned char *wrapped, size_t wrappedlen); 16b077aed3SPierre Pronchery 17b077aed3SPierre Pronchery=head1 DESCRIPTION 18b077aed3SPierre Pronchery 19b077aed3SPierre ProncheryThe EVP_PKEY_decapsulate_init() function initializes a private key algorithm 20b077aed3SPierre Proncherycontext I<ctx> for a decapsulation operation and then sets the I<params> 21b077aed3SPierre Proncheryon the context in the same way as calling L<EVP_PKEY_CTX_set_params(3)>. 22*aa795734SPierre ProncheryNote that I<ctx> usually is produced using L<EVP_PKEY_CTX_new_from_pkey(3)>, 23*aa795734SPierre Proncheryspecifying the private key to use. 24b077aed3SPierre Pronchery 25b077aed3SPierre ProncheryThe EVP_PKEY_decapsulate() function performs a private key decapsulation 26b077aed3SPierre Proncheryoperation using I<ctx>. The data to be decapsulated is specified using the 27b077aed3SPierre ProncheryI<wrapped> and I<wrappedlen> parameters. 28*aa795734SPierre ProncheryIf I<unwrapped> is NULL then the maximum size of the output secret buffer 29*aa795734SPierre Proncheryis written to I<*unwrappedlen>. If I<unwrapped> is not NULL and the 30*aa795734SPierre Proncherycall is successful then the decapsulated secret data is written to I<unwrapped> 31*aa795734SPierre Proncheryand the amount of data written to I<*unwrappedlen>. 32b077aed3SPierre Pronchery 33b077aed3SPierre Pronchery=head1 NOTES 34b077aed3SPierre Pronchery 35*aa795734SPierre ProncheryAfter the call to EVP_PKEY_decapsulate_init() algorithm-specific parameters 36b077aed3SPierre Proncheryfor the operation may be set or modified using L<EVP_PKEY_CTX_set_params(3)>. 37b077aed3SPierre Pronchery 38b077aed3SPierre Pronchery=head1 RETURN VALUES 39b077aed3SPierre Pronchery 40b077aed3SPierre ProncheryEVP_PKEY_decapsulate_init() and EVP_PKEY_decapsulate() return 1 for 41b077aed3SPierre Proncherysuccess and 0 or a negative value for failure. In particular a return value of -2 42b077aed3SPierre Proncheryindicates the operation is not supported by the private key algorithm. 43b077aed3SPierre Pronchery 44b077aed3SPierre Pronchery=head1 EXAMPLES 45b077aed3SPierre Pronchery 46b077aed3SPierre ProncheryDecapsulate data using RSA: 47b077aed3SPierre Pronchery 48b077aed3SPierre Pronchery #include <openssl/evp.h> 49b077aed3SPierre Pronchery 50b077aed3SPierre Pronchery /* 51b077aed3SPierre Pronchery * NB: assumes rsa_priv_key is an RSA private key, 52b077aed3SPierre Pronchery * and that in, inlen are already set up to contain encapsulated data. 53b077aed3SPierre Pronchery */ 54b077aed3SPierre Pronchery 55b077aed3SPierre Pronchery EVP_PKEY_CTX *ctx = NULL; 56b077aed3SPierre Pronchery size_t secretlen = 0; 57b077aed3SPierre Pronchery unsigned char *secret = NULL;; 58b077aed3SPierre Pronchery 59b077aed3SPierre Pronchery ctx = EVP_PKEY_CTX_new_from_pkey(libctx, rsa_priv_key, NULL); 60b077aed3SPierre Pronchery if (ctx = NULL) 61b077aed3SPierre Pronchery /* Error */ 62b077aed3SPierre Pronchery if (EVP_PKEY_decapsulate_init(ctx, NULL) <= 0) 63b077aed3SPierre Pronchery /* Error */ 64b077aed3SPierre Pronchery 65b077aed3SPierre Pronchery /* Set the mode - only 'RSASVE' is currently supported */ 66b077aed3SPierre Pronchery if (EVP_PKEY_CTX_set_kem_op(ctx, "RSASVE") <= 0) 67b077aed3SPierre Pronchery /* Error */ 68b077aed3SPierre Pronchery 69b077aed3SPierre Pronchery /* Determine buffer length */ 70b077aed3SPierre Pronchery if (EVP_PKEY_decapsulate(ctx, NULL, &secretlen, in, inlen) <= 0) 71b077aed3SPierre Pronchery /* Error */ 72b077aed3SPierre Pronchery 73b077aed3SPierre Pronchery secret = OPENSSL_malloc(secretlen); 74b077aed3SPierre Pronchery if (secret == NULL) 75b077aed3SPierre Pronchery /* malloc failure */ 76b077aed3SPierre Pronchery 77b077aed3SPierre Pronchery /* Decapsulated secret data is secretlen bytes long */ 78b077aed3SPierre Pronchery if (EVP_PKEY_decapsulaterctx, secret, &secretlen, in, inlen) <= 0) 79b077aed3SPierre Pronchery /* Error */ 80b077aed3SPierre Pronchery 81b077aed3SPierre Pronchery 82b077aed3SPierre Pronchery=head1 SEE ALSO 83b077aed3SPierre Pronchery 84*aa795734SPierre ProncheryL<EVP_PKEY_CTX_new_from_pkey(3)>, 85b077aed3SPierre ProncheryL<EVP_PKEY_encapsulate(3)>, 86b077aed3SPierre ProncheryL<EVP_KEM-RSA(7)>, 87b077aed3SPierre Pronchery 88b077aed3SPierre Pronchery=head1 HISTORY 89b077aed3SPierre Pronchery 90b077aed3SPierre ProncheryThese functions were added in OpenSSL 3.0. 91b077aed3SPierre Pronchery 92b077aed3SPierre Pronchery=head1 COPYRIGHT 93b077aed3SPierre Pronchery 94*aa795734SPierre ProncheryCopyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved. 95b077aed3SPierre Pronchery 96b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 97b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 98b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 99b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 100b077aed3SPierre Pronchery 101b077aed3SPierre Pronchery=cut 102