From: Matt Caswell <matt@openssl.org>
Date: Wed, 6 Nov 2019 11:03:12 +0000 (+0000)
Subject: Document the public EVP_ASYM_CIPHER releated functions
X-Git-Tag: openssl-3.0.0-alpha1~955
X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=c68f5050dbc1dc043accb4e28e3aaf4d5cfd1c65;p=oweals%2Fopenssl.git

Document the public EVP_ASYM_CIPHER releated functions

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10152)
---

diff --git a/doc/man3/EVP_ASYM_CIPHER_free.pod b/doc/man3/EVP_ASYM_CIPHER_free.pod
new file mode 100644
index 0000000000..d7f9991c26
--- /dev/null
+++ b/doc/man3/EVP_ASYM_CIPHER_free.pod
@@ -0,0 +1,88 @@
+=pod
+
+=head1 NAME
+
+EVP_ASYM_CIPHER_fetch, EVP_ASYM_CIPHER_free, EVP_ASYM_CIPHER_up_ref,
+EVP_ASYM_CIPHER_number, EVP_ASYM_CIPHER_is_a, EVP_ASYM_CIPHER_provider,
+EVP_ASYM_CIPHER_do_all_provided, EVP_ASYM_CIPHER_names_do_all
+- Functions to manage EVP_ASYM_CIPHER algorithm objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ EVP_ASYM_CIPHER *EVP_ASYM_CIPHER_fetch(OPENSSL_CTX *ctx, const char *algorithm,
+                                        const char *properties);
+ void EVP_ASYM_CIPHER_free(EVP_ASYM_CIPHER *cipher);
+ int EVP_ASYM_CIPHER_up_ref(EVP_ASYM_CIPHER *cipher);
+ int EVP_ASYM_CIPHER_number(const EVP_ASYM_CIPHER *cipher);
+ int EVP_ASYM_CIPHER_is_a(const EVP_ASYM_CIPHER *cipher, const char *name);
+ OSSL_PROVIDER *EVP_ASYM_CIPHER_provider(const EVP_ASYM_CIPHER *cipher);
+ void EVP_ASYM_CIPHER_do_all_provided(OPENSSL_CTX *libctx,
+                                      void (*fn)(EVP_ASYM_CIPHER *cipher,
+                                                 void *arg),
+                                      void *arg);
+ void EVP_ASYM_CIPHER_names_do_all(const EVP_ASYM_CIPHER *cipher,
+                                   void (*fn)(const char *name, void *data),
+                                   void *data);
+
+=head1 DESCRIPTION
+
+EVP_ASYM_CIPHER_fetch() fetches the implementation for the given
+B<algorithm> from any provider offering it, within the criteria given
+by the B<properties> and in the scope of the given library context B<ctx> (see
+L<OPENSSL_CTX(3)>). The algorithm will be one offering functions for performing
+asymmetric cipher related tasks such as asymmetric encryption and decryption.
+See L<provider(7)/Fetching algorithms> for further information.
+
+The returned value must eventually be freed with EVP_ASYM_CIPHER_free().
+
+EVP_ASYM_CIPHER_free() decrements the reference count for the B<EVP_ASYM_CIPHER>
+structure. Typically this structure will have been obtained from an earlier call
+to EVP_ASYM_CIPHER_fetch(). If the reference count drops to 0 then the
+structure is freed.
+
+EVP_ASYM_CIPHER_up_ref() increments the reference count for an
+B<EVP_ASYM_CIPHER> structure.
+
+EVP_ASYM_CIPHER_is_a() returns 1 if I<cipher> is an implementation of an
+algorithm that's identifiable with I<name>, otherwise 0.
+
+EVP_ASYM_CIPHER_provider() returns the provider that I<cipher> was fetched from.
+
+EVP_ASYM_CIPHER_do_all_provided() traverses all EVP_ASYM_CIPHERs implemented by
+all activated providers in the given library context I<libctx>, and for each of
+the implementations, calls the given function I<fn> with the implementation
+method and the given I<arg> as argument.
+
+EVP_ASYM_CIPHER_number() returns the internal dynamic number assigned to
+I<cipher>.
+
+EVP_ASYM_CIPHER_names_do_all() traverses all names for I<cipher>, and calls
+I<fn> with each name and I<data>.
+
+=head1 RETURN VALUES
+
+EVP_ASYM_CIPHER_fetch() returns a pointer to an B<EVP_ASYM_CIPHER> for success
+or B<NULL> for failure.
+
+EVP_ASYM_CIPHER_up_ref() returns 1 for success or 0 otherwise.
+
+=head1 SEE ALSO
+
+L<provider(7)/Fetching algorithms>, L<OSSL_PROVIDER(3)>
+
+=head1 HISTORY
+
+The functions described here were added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut