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