1b077aed3SPierre Pronchery=pod 2b077aed3SPierre Pronchery 3b077aed3SPierre Pronchery=head1 NAME 4b077aed3SPierre Pronchery 5b077aed3SPierre ProncheryEVP_ASYM_CIPHER_fetch, EVP_ASYM_CIPHER_free, EVP_ASYM_CIPHER_up_ref, 6b077aed3SPierre ProncheryEVP_ASYM_CIPHER_is_a, EVP_ASYM_CIPHER_get0_provider, 7b077aed3SPierre ProncheryEVP_ASYM_CIPHER_do_all_provided, EVP_ASYM_CIPHER_names_do_all, 8b077aed3SPierre ProncheryEVP_ASYM_CIPHER_get0_name, EVP_ASYM_CIPHER_get0_description, 9b077aed3SPierre ProncheryEVP_ASYM_CIPHER_gettable_ctx_params, EVP_ASYM_CIPHER_settable_ctx_params 10b077aed3SPierre Pronchery- Functions to manage EVP_ASYM_CIPHER algorithm objects 11b077aed3SPierre Pronchery 12b077aed3SPierre Pronchery=head1 SYNOPSIS 13b077aed3SPierre Pronchery 14b077aed3SPierre Pronchery #include <openssl/evp.h> 15b077aed3SPierre Pronchery 16b077aed3SPierre Pronchery EVP_ASYM_CIPHER *EVP_ASYM_CIPHER_fetch(OSSL_LIB_CTX *ctx, const char *algorithm, 17b077aed3SPierre Pronchery const char *properties); 18b077aed3SPierre Pronchery void EVP_ASYM_CIPHER_free(EVP_ASYM_CIPHER *cipher); 19b077aed3SPierre Pronchery int EVP_ASYM_CIPHER_up_ref(EVP_ASYM_CIPHER *cipher); 20b077aed3SPierre Pronchery const char *EVP_ASYM_CIPHER_get0_name(const EVP_ASYM_CIPHER *cipher); 21b077aed3SPierre Pronchery int EVP_ASYM_CIPHER_is_a(const EVP_ASYM_CIPHER *cipher, const char *name); 22b077aed3SPierre Pronchery OSSL_PROVIDER *EVP_ASYM_CIPHER_get0_provider(const EVP_ASYM_CIPHER *cipher); 23b077aed3SPierre Pronchery void EVP_ASYM_CIPHER_do_all_provided(OSSL_LIB_CTX *libctx, 24b077aed3SPierre Pronchery void (*fn)(EVP_ASYM_CIPHER *cipher, 25b077aed3SPierre Pronchery void *arg), 26b077aed3SPierre Pronchery void *arg); 27b077aed3SPierre Pronchery int EVP_ASYM_CIPHER_names_do_all(const EVP_ASYM_CIPHER *cipher, 28b077aed3SPierre Pronchery void (*fn)(const char *name, void *data), 29b077aed3SPierre Pronchery void *data); 30b077aed3SPierre Pronchery const char *EVP_ASYM_CIPHER_get0_description(const EVP_ASYM_CIPHER *cipher); 31b077aed3SPierre Pronchery const OSSL_PARAM *EVP_ASYM_CIPHER_gettable_ctx_params(const EVP_ASYM_CIPHER *cip); 32b077aed3SPierre Pronchery const OSSL_PARAM *EVP_ASYM_CIPHER_settable_ctx_params(const EVP_ASYM_CIPHER *cip); 33b077aed3SPierre Pronchery 34b077aed3SPierre Pronchery=head1 DESCRIPTION 35b077aed3SPierre Pronchery 36b077aed3SPierre ProncheryEVP_ASYM_CIPHER_fetch() fetches the implementation for the given 37b077aed3SPierre ProncheryB<algorithm> from any provider offering it, within the criteria given 38b077aed3SPierre Proncheryby the B<properties> and in the scope of the given library context B<ctx> (see 39b077aed3SPierre ProncheryL<OSSL_LIB_CTX(3)>). The algorithm will be one offering functions for performing 40b077aed3SPierre Proncheryasymmetric cipher related tasks such as asymmetric encryption and decryption. 41b077aed3SPierre ProncherySee L<crypto(7)/ALGORITHM FETCHING> for further information. 42b077aed3SPierre Pronchery 43b077aed3SPierre ProncheryThe returned value must eventually be freed with EVP_ASYM_CIPHER_free(). 44b077aed3SPierre Pronchery 45b077aed3SPierre ProncheryEVP_ASYM_CIPHER_free() decrements the reference count for the B<EVP_ASYM_CIPHER> 46b077aed3SPierre Proncherystructure. Typically this structure will have been obtained from an earlier call 47b077aed3SPierre Proncheryto EVP_ASYM_CIPHER_fetch(). If the reference count drops to 0 then the 48*a7148ab3SEnji Cooperstructure is freed. If the argument is NULL, nothing is done. 49b077aed3SPierre Pronchery 50b077aed3SPierre ProncheryEVP_ASYM_CIPHER_up_ref() increments the reference count for an 51b077aed3SPierre ProncheryB<EVP_ASYM_CIPHER> structure. 52b077aed3SPierre Pronchery 53b077aed3SPierre ProncheryEVP_ASYM_CIPHER_is_a() returns 1 if I<cipher> is an implementation of an 54b077aed3SPierre Proncheryalgorithm that's identifiable with I<name>, otherwise 0. 55b077aed3SPierre Pronchery 56b077aed3SPierre ProncheryEVP_ASYM_CIPHER_get0_provider() returns the provider that I<cipher> was 57b077aed3SPierre Proncheryfetched from. 58b077aed3SPierre Pronchery 59b077aed3SPierre ProncheryEVP_ASYM_CIPHER_do_all_provided() traverses all EVP_ASYM_CIPHERs implemented by 60b077aed3SPierre Proncheryall activated providers in the given library context I<libctx>, and for each of 61b077aed3SPierre Proncherythe implementations, calls the given function I<fn> with the implementation 62b077aed3SPierre Proncherymethod and the given I<arg> as argument. 63b077aed3SPierre Pronchery 64b077aed3SPierre ProncheryEVP_ASYM_CIPHER_get0_name() returns the algorithm name from the provided 65b077aed3SPierre Proncheryimplementation for the given I<cipher>. Note that the I<cipher> may have 66b077aed3SPierre Proncherymultiple synonyms associated with it. In this case the first name from the 67b077aed3SPierre Proncheryalgorithm definition is returned. Ownership of the returned string is retained 68b077aed3SPierre Proncheryby the I<cipher> object and should not be freed by the caller. 69b077aed3SPierre Pronchery 70b077aed3SPierre ProncheryEVP_ASYM_CIPHER_names_do_all() traverses all names for I<cipher>, and calls 71b077aed3SPierre ProncheryI<fn> with each name and I<data>. 72b077aed3SPierre Pronchery 73b077aed3SPierre ProncheryEVP_ASYM_CIPHER_get0_description() returns a description of the I<cipher>, 74b077aed3SPierre Proncherymeant for display and human consumption. The description is at the 75b077aed3SPierre Proncherydiscretion of the I<cipher> implementation. 76b077aed3SPierre Pronchery 77b077aed3SPierre ProncheryEVP_ASYM_CIPHER_gettable_ctx_params() and EVP_ASYM_CIPHER_settable_ctx_params() 78b077aed3SPierre Proncheryreturn a constant L<OSSL_PARAM(3)> array that describes the names and types of key 79b077aed3SPierre Proncheryparameters that can be retrieved or set by a key encryption algorithm using 80b077aed3SPierre ProncheryL<EVP_PKEY_CTX_get_params(3)> and L<EVP_PKEY_CTX_set_params(3)>. 81b077aed3SPierre Pronchery 82b077aed3SPierre Pronchery=head1 RETURN VALUES 83b077aed3SPierre Pronchery 84b077aed3SPierre ProncheryEVP_ASYM_CIPHER_fetch() returns a pointer to an B<EVP_ASYM_CIPHER> for success 85b077aed3SPierre Proncheryor B<NULL> for failure. 86b077aed3SPierre Pronchery 87b077aed3SPierre ProncheryEVP_ASYM_CIPHER_up_ref() returns 1 for success or 0 otherwise. 88b077aed3SPierre Pronchery 89b077aed3SPierre ProncheryEVP_ASYM_CIPHER_names_do_all() returns 1 if the callback was called for all 90b077aed3SPierre Proncherynames. A return value of 0 means that the callback was not called for any names. 91b077aed3SPierre Pronchery 92b077aed3SPierre ProncheryEVP_ASYM_CIPHER_gettable_ctx_params() and EVP_ASYM_CIPHER_settable_ctx_params() 93b077aed3SPierre Proncheryreturn a constant L<OSSL_PARAM(3)> array or NULL on error. 94b077aed3SPierre Pronchery 95b077aed3SPierre Pronchery=head1 SEE ALSO 96b077aed3SPierre Pronchery 97b077aed3SPierre ProncheryL<crypto(7)/ALGORITHM FETCHING>, L<OSSL_PROVIDER(3)> 98b077aed3SPierre Pronchery 99b077aed3SPierre Pronchery=head1 HISTORY 100b077aed3SPierre Pronchery 101b077aed3SPierre ProncheryThe functions described here were added in OpenSSL 3.0. 102b077aed3SPierre Pronchery 103b077aed3SPierre Pronchery=head1 COPYRIGHT 104b077aed3SPierre Pronchery 105*a7148ab3SEnji CooperCopyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved. 106b077aed3SPierre Pronchery 107b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 108b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 109b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 110b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 111b077aed3SPierre Pronchery 112b077aed3SPierre Pronchery=cut 113