Move X509_STORE_CTX_get0_cert(3) to the X509_STORE_CTX_new(3) manual.

OpenSSL documents it in X509_STORE_CTX_get_error(3), but it is
misplaced there.  It has nothing to do with accessing status or
error information but merely retrieves a pointer to the certificate
that the users wants to validate.  It is a companion function to
X509_STORE_CTX_init(3), X509_STORE_CTX_set_cert(3),
X509_STORE_CTX_get0_store(3), and X509_STORE_CTX_get0_untrusted(3).

While here:
1. Clarify how the new, init, verify, cleanup, and free calls interact,
and who owns the memory involved, because this is all really confusing
from the user perspective.
2. Clarify how X509_STORE_CTX_init(3), X509_STORE_CTX_set_cert(3), and
X509_STORE_CTX_set_chain(3) partially override each other.
3. Move X509_STORE_CTX_set0_untrusted(3) to the proper place because
it is the same as X509_STORE_CTX_set_chain(3).
4. Add a few missing words and improve some wordings.

1 files changed, 6 insertions, 17 deletions

diff --git a/src/lib/libcrypto/man/X509_STORE_CTX_get_error.3 b/src/lib/libcrypto/man/X509_STORE_CTX_get_error.3
index 3294658ac6..6192c0d2fc 100644
--- a/src/lib/libcrypto/man/X509_STORE_CTX_get_error.3
+++ b/src/lib/libcrypto/man/X509_STORE_CTX_get_error.3
@@ -1,13 +1,13 @@
-.\" $OpenBSD: X509_STORE_CTX_get_error.3,v 1.14 2021/07/21 15:03:45 schwarze Exp $
+.\" $OpenBSD: X509_STORE_CTX_get_error.3,v 1.15 2021/07/22 14:30:38 schwarze Exp $
 .\" full merge up to:
 .\" OpenSSL crypto/X509_STORE_CTX_get_error f0e0fd51 Apr 14 23:59:26 2016 -0400
 .\" selective merge up to:
 .\" OpenSSL man3/X509_STORE_CTX_get_error 24a535ea Sep 22 13:14:20 2020 +0100
 .\" OpenSSL man3/X509_STORE_CTX_new 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
-.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
-.\" Copyright (c) 2009, 2013, 2015, 2016 The OpenSSL Project.
-.\" All rights reserved.
+.\" This file was written by Dr. Stephen Henson <steve@openssl.org>
+.\" and Rich Salz <rsalz@openssl.org>.
+.\" Copyright (c) 2009, 2016 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -53,7 +53,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 21 2021 $
+.Dd $Mdocdate: July 22 2021 $
 .Dt X509_STORE_CTX_GET_ERROR 3
 .Os
 .Sh NAME
@@ -61,7 +61,6 @@
 .Nm X509_STORE_CTX_set_error ,
 .Nm X509_STORE_CTX_get_error_depth ,
 .Nm X509_STORE_CTX_get_current_cert ,
-.Nm X509_STORE_CTX_get0_cert ,
 .Nm X509_STORE_CTX_get0_chain ,
 .Nm X509_STORE_CTX_get_chain ,
 .Nm X509_STORE_CTX_get1_chain ,
@@ -86,10 +85,6 @@
 .Fo X509_STORE_CTX_get_current_cert
 .Fa "X509_STORE_CTX *ctx"
 .Fc
-.Ft X509 *
-.Fo X509_STORE_CTX_get0_cert
-.Fa "X509_STORE_CTX *ctx"
-.Fc
 .Ft STACK_OF(X509) *
 .Fo X509_STORE_CTX_get0_chain
 .Fa "X509_STORE_CTX *ctx"
@@ -195,10 +190,6 @@ returns the certificate which caused the error or
 .Dv NULL
 if no certificate is relevant to the error.
 .Pp
-.Fn X509_STORE_CTX_get0_cert
-retrieves an internal pointer to the certificate being verified by
-.Fa ctx .
-.Pp
 .Fn X509_STORE_CTX_get0_chain ,
 .Fn X509_STORE_CTX_get_chain ,
 and
@@ -399,8 +390,6 @@ first appeared in SSLeay 0.8.0 and have been available since
 first appeared in OpenSSL 0.9.5 and has been available since
 .Ox 2.7 .
 .Pp
-.Fn X509_STORE_CTX_get0_cert
-and
 .Fn X509_STORE_CTX_get0_chain
-first appeared in OpenSSL 1.1.0 and have been available since
+first appeared in OpenSSL 1.1.0 and has been available since
 .Ox 6.3 .