Documentation for EVP_PKEY_CTX_get0_pkey() and EVP_PKEY_CTX_get0_peerkey().

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/19962)

(cherry picked from commit 3be76745e55eab9ea976f7a23e6c8ecd3bb8136c)

2 files changed, 62 insertions, 0 deletions

diff --git a/doc/build.info b/doc/build.info
index 63b804be0e..ec8778f2ac 100644
--- a/doc/build.info
+++ b/doc/build.info
@@ -1167,6 +1167,10 @@ DEPEND[html/man3/EVP_PKEY_CTX_get0_libctx.html]=man3/EVP_PKEY_CTX_get0_libctx.po
 GENERATE[html/man3/EVP_PKEY_CTX_get0_libctx.html]=man3/EVP_PKEY_CTX_get0_libctx.pod
 DEPEND[man/man3/EVP_PKEY_CTX_get0_libctx.3]=man3/EVP_PKEY_CTX_get0_libctx.pod
 GENERATE[man/man3/EVP_PKEY_CTX_get0_libctx.3]=man3/EVP_PKEY_CTX_get0_libctx.pod
+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_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
@@ -3051,6 +3055,7 @@ html/man3/EVP_PKEY2PKCS8.html \
 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_new.html \
 html/man3/EVP_PKEY_CTX_set1_pbe_pass.html \
 html/man3/EVP_PKEY_CTX_set_hkdf_md.html \
@@ -3653,6 +3658,7 @@ man/man3/EVP_PKEY2PKCS8.3 \
 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_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_get0_pkey.pod b/doc/man3/EVP_PKEY_CTX_get0_pkey.pod
new file mode 100644
index 0000000000..26eef87cc1
--- /dev/null
+++ b/doc/man3/EVP_PKEY_CTX_get0_pkey.pod
@@ -0,0 +1,56 @@
+=pod
+
+=head1 NAME
+
+EVP_PKEY_CTX_get0_pkey,
+EVP_PKEY_CTX_get0_peerkey
+- functions for accessing the EVP_PKEY associated with an EVP_PKEY_CTX
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ EVP_PKEY *EVP_PKEY_CTX_get0_pkey(EVP_PKEY_CTX *ctx);
+ EVP_PKEY *EVP_PKEY_CTX_get0_peerkey(EVP_PKEY_CTX *ctx);
+
+=head1 DESCRIPTION
+
+EVP_PKEY_CTX_get0_pkey() is used to access the B<EVP_PKEY>
+associated with the given B<EVP_PKEY_CTX> I<ctx>.
+The B<EVP_PKEY> obtained is the one used for creating the B<EVP_PKEY_CTX>
+using either L<EVP_PKEY_CTX_new(3)> or L<EVP_PKEY_CTX_new_from_pkey(3)>.
+
+EVP_PKEY_CTX_get0_peerkey() is used to access the peer B<EVP_PKEY>
+associated with the given B<EVP_PKEY_CTX> I<ctx>.
+The peer B<EVP_PKEY> obtained is the one set using
+either L<EVP_PKEY_derive_set_peer(3)> or L<EVP_PKEY_derive_set_peer_ex(3)>.
+
+=head1 RETURN VALUES
+
+EVP_PKEY_CTX_get0_pkey() returns the B<EVP_PKEY> associated with the
+EVP_PKEY_CTX or NULL if it is not set.
+
+EVP_PKEY_CTX_get0_peerkey() returns the peer B<EVP_PKEY> associated with the
+EVP_PKEY_CTX or NULL if it is not set.
+
+The returned EVP_PKEY objects are owned by the EVP_PKEY_CTX,
+and therefore should not explicitly be freed by the caller.
+
+These functions do not affect the EVP_PKEY reference count.
+They merely act as getter functions, and should be treated as such.
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_new(3)>, L<EVP_PKEY_CTX_new_from_pkey(3)>,
+L<EVP_PKEY_derive_set_peer(3)>, L<EVP_PKEY_derive_set_peer_ex(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2022 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