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