doc: Document EVP_{TYPE}_CTX_get_algor etc

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Neil Horman <nhorman@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/25000)

diff --git a/doc/build.info b/doc/build.info
index 1363ab54fffe00a89501528ea63c174715bce7ae..8131a0aa98c5d371d01aa2617e75bbf9c813dadc 100644 (file)
--- a/doc/build.info
+++ b/doc/build.info
@@ -1203,6 +1203,10 @@ DEPEND[html/man3/EVP_PKEY_CTX_get0_pkey.html]=man3/EVP_PKEY_CTX_get0_pkey.pod
 GENERATE[html/man3/EVP_PKEY_CTX_get0_pkey.html]=man3/EVP_PKEY_CTX_get0_pkey.pod
 DEPEND[man/man3/EVP_PKEY_CTX_get0_pkey.3]=man3/EVP_PKEY_CTX_get0_pkey.pod
 GENERATE[man/man3/EVP_PKEY_CTX_get0_pkey.3]=man3/EVP_PKEY_CTX_get0_pkey.pod
+DEPEND[html/man3/EVP_PKEY_CTX_get_algor.html]=man3/EVP_PKEY_CTX_get_algor.pod
+GENERATE[html/man3/EVP_PKEY_CTX_get_algor.html]=man3/EVP_PKEY_CTX_get_algor.pod
+DEPEND[man/man3/EVP_PKEY_CTX_get_algor.3]=man3/EVP_PKEY_CTX_get_algor.pod
+GENERATE[man/man3/EVP_PKEY_CTX_get_algor.3]=man3/EVP_PKEY_CTX_get_algor.pod
 DEPEND[html/man3/EVP_PKEY_CTX_new.html]=man3/EVP_PKEY_CTX_new.pod
 GENERATE[html/man3/EVP_PKEY_CTX_new.html]=man3/EVP_PKEY_CTX_new.pod
 DEPEND[man/man3/EVP_PKEY_CTX_new.3]=man3/EVP_PKEY_CTX_new.pod
@@ -3300,6 +3304,7 @@ html/man3/EVP_PKEY_ASN1_METHOD.html \
 html/man3/EVP_PKEY_CTX_ctrl.html \
 html/man3/EVP_PKEY_CTX_get0_libctx.html \
 html/man3/EVP_PKEY_CTX_get0_pkey.html \
+html/man3/EVP_PKEY_CTX_get_algor.html \
 html/man3/EVP_PKEY_CTX_new.html \
 html/man3/EVP_PKEY_CTX_set1_pbe_pass.html \
 html/man3/EVP_PKEY_CTX_set_hkdf_md.html \
@@ -3962,6 +3967,7 @@ man/man3/EVP_PKEY_ASN1_METHOD.3 \
 man/man3/EVP_PKEY_CTX_ctrl.3 \
 man/man3/EVP_PKEY_CTX_get0_libctx.3 \
 man/man3/EVP_PKEY_CTX_get0_pkey.3 \
+man/man3/EVP_PKEY_CTX_get_algor.3 \
 man/man3/EVP_PKEY_CTX_new.3 \
 man/man3/EVP_PKEY_CTX_set1_pbe_pass.3 \
 man/man3/EVP_PKEY_CTX_set_hkdf_md.3 \

diff --git a/doc/man3/EVP_PKEY_CTX_get_algor.pod b/doc/man3/EVP_PKEY_CTX_get_algor.pod
new file mode 100644 (file)
index 0000000..be408c1
--- /dev/null
+++ b/doc/man3/EVP_PKEY_CTX_get_algor.pod
@@ -0,0 +1,76 @@
+=pod
+
+=begin comment
+
+This page collects all existing functions with this pattern:
+
+EVP_{TYPE}_CTX_get_algor()
+EVP_{TYPE}_CTX_get_algor_params()
+EVP_{TYPE}_CTX_set_algor_params()
+
+... where {TYPE} is the name of an EVP operation type.
+
+=end comment
+
+=head1 NAME
+
+EVP_CIPHER_CTX_get_algor,
+EVP_CIPHER_CTX_get_algor_params,
+EVP_CIPHER_CTX_set_algor_params,
+EVP_PKEY_CTX_get_algor,
+EVP_PKEY_CTX_get_algor_params,
+EVP_PKEY_CTX_set_algor_params
+- pass AlgorithmIdentifier and its params to/from algorithm implementations
+
+=head1 SYNOPSIS
+
+=for openssl generic
+
+ int EVP_TYPE_CTX_get_algor(EVP_TYPE_CTX *ctx, X509_ALGOR **alg);
+ int EVP_TYPE_CTX_get_algor_params(EVP_TYPE_CTX *ctx, X509_ALGOR *alg);
+ int EVP_TYPE_CTX_set_algor_params(EVP_TYPE_CTX *ctx, const X509_ALGOR *alg);
+
+=head1 DESCRIPTION
+
+In the description here and the L</SYNOPSIS> above, B<I<TYPE>> is used as a
+placeholder for any EVP operation type.
+
+B<EVP_I<TYPE>_CTX_get_algor>() attempts to retrieve a complete
+AlgorithmIdentifier from the B<EVP_I<TYPE>> implementation, and populates
+I<*alg> with it.
+If I<alg> is NULL, calling this function will serve to see if calling this
+function is supported at all by the B<EVP_I<TYPE>> implementation.
+If I<*alg> is NULL, space will be allocated automatically, and assigned to
+I<*alg>.
+
+B<EVP_I<TYPE>_CTX_get_algor_params>() attempts to retrieve the I<parameters>
+part of an AlgorithmIdentifier from the B<EVP_I<TYPE>> implementation, and
+populates I<alg->parameters> with it.
+If I<alg> is NULL, calling this function will serve to see if calling this
+function is supported at all by the B<EVP_I<TYPE>> implementation.
+If I<< alg->parameters >> is NULL, space will be allocated automatically, and
+assigned to  I<< alg->parameters >>.
+If I<< alg->parameters >> is not NULL, its previous contents will be overwritten
+with the retrieved AlgorithmIdentifier parameters.  Beware!
+
+B<EVP_I<TYPE>_CTX_set_algor_params>() attempts to pass I<< alg->parameters >>
+to the B<EVP_I<TYPE>> implementation.
+If I<alg> is NULL, calling this function will serve to see if calling this
+function is supported at all by the B<EVP_I<TYPE>> implementation.
+
+=head1 RETURN VALUES
+
+All functions return 1 for success, and 0 or a negative number if an error
+occurs.  In particular, -2 is returned when the function isn't supported by
+the B<EVP_I<TYPE>> implementation.
+
+=head1 COPYRIGHT
+
+Copyright 2024 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