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