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