1b077aed3SPierre Pronchery=pod 2b077aed3SPierre Pronchery 3b077aed3SPierre Pronchery=head1 NAME 4b077aed3SPierre Pronchery 5b077aed3SPierre ProncheryEVP_PKEY_encapsulate_init, EVP_PKEY_encapsulate 6*aa795734SPierre Pronchery- Key encapsulation using a KEM algorithm with a public key 7b077aed3SPierre Pronchery 8b077aed3SPierre Pronchery=head1 SYNOPSIS 9b077aed3SPierre Pronchery 10b077aed3SPierre Pronchery #include <openssl/evp.h> 11b077aed3SPierre Pronchery 12b077aed3SPierre Pronchery int EVP_PKEY_encapsulate_init(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]); 13b077aed3SPierre Pronchery int EVP_PKEY_encapsulate(EVP_PKEY_CTX *ctx, 14*aa795734SPierre Pronchery unsigned char *wrappedkey, size_t *wrappedkeylen, 15b077aed3SPierre Pronchery unsigned char *genkey, size_t *genkeylen); 16b077aed3SPierre Pronchery 17b077aed3SPierre Pronchery=head1 DESCRIPTION 18b077aed3SPierre Pronchery 19b077aed3SPierre ProncheryThe EVP_PKEY_encapsulate_init() function initializes a public key algorithm 20b077aed3SPierre Proncherycontext I<ctx> for an encapsulation 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> is usually is produced using L<EVP_PKEY_CTX_new_from_pkey(3)>, 23*aa795734SPierre Proncheryspecifying the public key to use. 24b077aed3SPierre Pronchery 25b077aed3SPierre ProncheryThe EVP_PKEY_encapsulate() function performs a public key encapsulation 26*aa795734SPierre Proncheryoperation using I<ctx>. 27*aa795734SPierre ProncheryThe symmetric secret generated in I<genkey> can be used as key material. 28*aa795734SPierre ProncheryThe ciphertext in I<wrappedkey> is its encapsulated form, which can be sent 29*aa795734SPierre Proncheryto another party, who can use L<EVP_PKEY_decapsulate(3)> to retrieve it 30*aa795734SPierre Proncheryusing their private key. 31*aa795734SPierre ProncheryIf I<wrappedkey> is NULL then the maximum size of the output buffer 32*aa795734SPierre Proncheryis written to the I<*wrappedkeylen> parameter unless I<wrappedkeylen> is NULL 33*aa795734SPierre Proncheryand the maximum size of the generated key buffer is written to I<*genkeylen> 34*aa795734SPierre Proncheryunless I<genkeylen> is NULL. 35*aa795734SPierre ProncheryIf I<wrappedkey> is not NULL and the call is successful then the 36b077aed3SPierre Proncheryinternally generated key is written to I<genkey> and its size is written to 37b077aed3SPierre ProncheryI<*genkeylen>. The encapsulated version of the generated key is written to 38*aa795734SPierre ProncheryI<wrappedkey> and its size is written to I<*wrappedkeylen>. 39b077aed3SPierre Pronchery 40b077aed3SPierre Pronchery=head1 NOTES 41b077aed3SPierre Pronchery 42*aa795734SPierre ProncheryAfter the call to EVP_PKEY_encapsulate_init() algorithm-specific parameters 43b077aed3SPierre Proncheryfor the operation may be set or modified using L<EVP_PKEY_CTX_set_params(3)>. 44b077aed3SPierre Pronchery 45b077aed3SPierre Pronchery=head1 RETURN VALUES 46b077aed3SPierre Pronchery 47b077aed3SPierre ProncheryEVP_PKEY_encapsulate_init() and EVP_PKEY_encapsulate() return 1 for 48b077aed3SPierre Proncherysuccess and 0 or a negative value for failure. In particular a return value of -2 49b077aed3SPierre Proncheryindicates the operation is not supported by the public key algorithm. 50b077aed3SPierre Pronchery 51b077aed3SPierre Pronchery=head1 EXAMPLES 52b077aed3SPierre Pronchery 53b077aed3SPierre ProncheryEncapsulate an RSASVE key (for RSA keys). 54b077aed3SPierre Pronchery 55b077aed3SPierre Pronchery #include <openssl/evp.h> 56b077aed3SPierre Pronchery 57b077aed3SPierre Pronchery /* 58b077aed3SPierre Pronchery * NB: assumes rsa_pub_key is an public key of another party. 59b077aed3SPierre Pronchery */ 60b077aed3SPierre Pronchery 61b077aed3SPierre Pronchery EVP_PKEY_CTX *ctx = NULL; 62b077aed3SPierre Pronchery size_t secretlen = 0, outlen = 0; 63b077aed3SPierre Pronchery unsigned char *out = NULL, *secret = NULL; 64b077aed3SPierre Pronchery 65b077aed3SPierre Pronchery ctx = EVP_PKEY_CTX_new_from_pkey(libctx, rsa_pub_key, NULL); 66b077aed3SPierre Pronchery if (ctx = NULL) 67b077aed3SPierre Pronchery /* Error */ 68b077aed3SPierre Pronchery if (EVP_PKEY_encapsulate_init(ctx, NULL) <= 0) 69b077aed3SPierre Pronchery /* Error */ 70b077aed3SPierre Pronchery 71b077aed3SPierre Pronchery /* Set the mode - only 'RSASVE' is currently supported */ 72b077aed3SPierre Pronchery if (EVP_PKEY_CTX_set_kem_op(ctx, "RSASVE") <= 0) 73b077aed3SPierre Pronchery /* Error */ 74b077aed3SPierre Pronchery /* Determine buffer length */ 75b077aed3SPierre Pronchery if (EVP_PKEY_encapsulate(ctx, NULL, &outlen, NULL, &secretlen) <= 0) 76b077aed3SPierre Pronchery /* Error */ 77b077aed3SPierre Pronchery 78b077aed3SPierre Pronchery out = OPENSSL_malloc(outlen); 79b077aed3SPierre Pronchery secret = OPENSSL_malloc(secretlen); 80b077aed3SPierre Pronchery if (out == NULL || secret == NULL) 81b077aed3SPierre Pronchery /* malloc failure */ 82b077aed3SPierre Pronchery 83b077aed3SPierre Pronchery /* 84b077aed3SPierre Pronchery * The generated 'secret' can be used as key material. 85b077aed3SPierre Pronchery * The encapsulated 'out' can be sent to another party who can 86b077aed3SPierre Pronchery * decapsulate it using their private key to retrieve the 'secret'. 87b077aed3SPierre Pronchery */ 88b077aed3SPierre Pronchery if (EVP_PKEY_encapsulate(ctx, out, &outlen, secret, &secretlen) <= 0) 89b077aed3SPierre Pronchery /* Error */ 90b077aed3SPierre Pronchery 91b077aed3SPierre Pronchery=head1 SEE ALSO 92b077aed3SPierre Pronchery 93*aa795734SPierre ProncheryL<EVP_PKEY_CTX_new_from_pkey(3)>, 94b077aed3SPierre ProncheryL<EVP_PKEY_decapsulate(3)>, 95b077aed3SPierre ProncheryL<EVP_KEM-RSA(7)>, 96b077aed3SPierre Pronchery 97b077aed3SPierre Pronchery=head1 HISTORY 98b077aed3SPierre Pronchery 99b077aed3SPierre ProncheryThese functions were added in OpenSSL 3.0. 100b077aed3SPierre Pronchery 101b077aed3SPierre Pronchery=head1 COPYRIGHT 102b077aed3SPierre Pronchery 103*aa795734SPierre ProncheryCopyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved. 104b077aed3SPierre Pronchery 105b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 106b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 107b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 108b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 109b077aed3SPierre Pronchery 110b077aed3SPierre Pronchery=cut 111