]>
Commit | Line | Data |
---|---|---|
80f4fd18 SL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_KEM_fetch, EVP_KEM_free, EVP_KEM_up_ref, | |
6 | EVP_KEM_number, EVP_KEM_is_a, EVP_KEM_provider, | |
5a950048 SL |
7 | EVP_KEM_do_all_provided, EVP_KEM_names_do_all, |
8 | EVP_KEM_gettable_ctx_params, EVP_KEM_settable_ctx_params | |
80f4fd18 SL |
9 | - Functions to manage EVP_KEM algorithm objects |
10 | ||
11 | =head1 SYNOPSIS | |
12 | ||
13 | #include <openssl/evp.h> | |
14 | ||
b4250010 | 15 | EVP_KEM *EVP_KEM_fetch(OSSL_LIB_CTX *ctx, const char *algorithm, |
80f4fd18 SL |
16 | const char *properties); |
17 | void EVP_KEM_free(EVP_KEM *kem); | |
18 | int EVP_KEM_up_ref(EVP_KEM *kem); | |
19 | int EVP_KEM_number(const EVP_KEM *kem); | |
20 | int EVP_KEM_is_a(const EVP_KEM *kem, const char *name); | |
21 | OSSL_PROVIDER *EVP_KEM_provider(const EVP_KEM *kem); | |
b4250010 | 22 | void EVP_KEM_do_all_provided(OSSL_LIB_CTX *libctx, |
80f4fd18 | 23 | void (*fn)(EVP_KEM *kem, void *arg), void *arg); |
d84f5515 MC |
24 | int EVP_KEM_names_do_all(const EVP_KEM *kem, |
25 | void (*fn)(const char *name, void *data), void *data); | |
5a950048 SL |
26 | const OSSL_PARAM *EVP_KEM_gettable_ctx_params(const EVP_KEM *kem); |
27 | const OSSL_PARAM *EVP_KEM_settable_ctx_params(const EVP_KEM *kem); | |
80f4fd18 SL |
28 | |
29 | =head1 DESCRIPTION | |
30 | ||
31 | EVP_KEM_fetch() fetches the implementation for the given B<algorithm> from any | |
32 | provider offering it, within the criteria given by the B<properties> and in the | |
b4250010 | 33 | scope of the given library context B<ctx> (see L<OSSL_LIB_CTX(3)>). The algorithm |
80f4fd18 SL |
34 | will be one offering functions for performing asymmetric kem related tasks such |
35 | as key encapsulation and decapsulation. | |
36 | See L<provider(7)/Fetching algorithms> for further information. | |
37 | ||
38 | The returned value must eventually be freed with EVP_KEM_free(). | |
39 | ||
40 | EVP_KEM_free() decrements the reference count for the B<EVP_KEM> structure. | |
41 | Typically this structure will have been obtained from an earlier call to | |
42 | EVP_KEM_fetch(). If the reference count drops to 0 then the structure is freed. | |
43 | ||
44 | EVP_KEM_up_ref() increments the reference count for an B<EVP_KEM> structure. | |
45 | ||
46 | EVP_KEM_is_a() returns 1 if I<kem> is an implementation of an | |
47 | algorithm that's identifiable with I<name>, otherwise 0. | |
48 | ||
49 | EVP_KEM_provider() returns the provider that I<kem> was fetched from. | |
50 | ||
51 | EVP_KEM_do_all_provided() traverses all EVP_KEMs implemented by all activated | |
52 | providers in the given library context I<libctx>, and for each of the | |
53 | implementations, calls the given function I<fn> with the implementation method | |
54 | and the given I<arg> as argument. | |
55 | ||
56 | EVP_KEM_number() returns the internal dynamic number assigned to I<kem>. | |
57 | ||
58 | EVP_KEM_names_do_all() traverses all names for I<kem>, and calls I<fn> with | |
59 | each name and I<data>. | |
60 | ||
5a950048 SL |
61 | EVP_KEM_gettable_ctx_params() and EVP_KEM_settable_ctx_params() return |
62 | a constant B<OSSL_PARAM> array that describes the names and types of key | |
63 | parameters that can be retrieved or set by a key encapsulation algorithm using | |
64 | L<EVP_PKEY_CTX_get_params(3)> and L<EVP_PKEY_CTX_set_params(3)>. | |
65 | ||
80f4fd18 SL |
66 | =head1 RETURN VALUES |
67 | ||
68 | EVP_KEM_fetch() returns a pointer to an B<EVP_KEM> for success or B<NULL> for | |
69 | failure. | |
70 | ||
71 | EVP_KEM_up_ref() returns 1 for success or 0 otherwise. | |
72 | ||
d84f5515 MC |
73 | EVP_KEM_names_do_all() returns 1 if the callback was called for all names. A |
74 | return value of 0 means that the callback was not called for any names. | |
75 | ||
5a950048 SL |
76 | EVP_KEM_gettable_ctx_params() and EVP_KEM_settable_ctx_params() return |
77 | a constant B<OSSL_PARAM> array or NULL on error. | |
78 | ||
80f4fd18 SL |
79 | =head1 SEE ALSO |
80 | ||
81 | L<provider(7)/Fetching algorithms>, L<OSSL_PROVIDER(3)> | |
82 | ||
83 | =head1 HISTORY | |
84 | ||
85 | The functions described here were added in OpenSSL 3.0. | |
86 | ||
87 | =head1 COPYRIGHT | |
88 | ||
89 | Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. | |
90 | ||
91 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
92 | this file except in compliance with the License. You can obtain a copy | |
93 | in the file LICENSE in the source distribution or at | |
94 | L<https://www.openssl.org/source/license.html>. | |
95 | ||
96 | =cut |