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