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 |
|
---|
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 *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
|
---|
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)>.
|
---|
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
|
---|
35 | for the operation may be set or modified using L<EVP_PKEY_CTX_set_params(3)>.
|
---|
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 */
|
---|
60 | if (EVP_PKEY_encapsulate_init(ctx, NULL) <= 0)
|
---|
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 |
|
---|
95 | Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
|
---|
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
|
---|