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.

2 files changed, 113 insertions, 65 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 .
diff --git a/src/lib/libcrypto/man/X509_STORE_CTX_new.3 b/src/lib/libcrypto/man/X509_STORE_CTX_new.3
index bcacb99094..17faeb3f13 100644
--- a/src/lib/libcrypto/man/X509_STORE_CTX_new.3
+++ b/src/lib/libcrypto/man/X509_STORE_CTX_new.3
@@ -1,10 +1,27 @@
-.\" $OpenBSD: X509_STORE_CTX_new.3,v 1.20 2019/12/05 14:38:56 claudio Exp $
-.\" full merge up to: OpenSSL 186bb907 Apr 13 11:05:13 2015 -0700
-.\" selective merge up to: OpenSSL 7643a172 Apr 21 13:35:51 2017 +0200
+.\" $OpenBSD: X509_STORE_CTX_new.3,v 1.21 2021/07/22 14:30:38 schwarze Exp $
+.\" full merge up to: OpenSSL aae41f8c Jun 25 09:47:15 2015 +0100
+.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
-.\" This file was written by Dr. Stephen Henson <steve@openssl.org>
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>
 .\" and Rich Salz <rsalz@openssl.org>.
-.\" Copyright (c) 2009, 2015, 2016 The OpenSSL Project.  All rights reserved.
+.\" 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
@@ -50,7 +67,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 5 2019 $
+.Dd $Mdocdate: July 22 2021 $
 .Dt X509_STORE_CTX_NEW 3
 .Os
 .Sh NAME
@@ -62,14 +79,15 @@
 .Nm X509_STORE_CTX_set0_trusted_stack ,
 .Nm X509_STORE_CTX_trusted_stack ,
 .Nm X509_STORE_CTX_set_cert ,
+.Nm X509_STORE_CTX_get0_cert ,
 .\" X509_STORE_CTX_get0_chain moved to X509_STORE_CTX_get_error(3)
 .Nm X509_STORE_CTX_set_chain ,
+.Nm X509_STORE_CTX_set0_untrusted ,
+.Nm X509_STORE_CTX_get0_untrusted ,
 .Nm X509_STORE_CTX_set0_crls ,
 .Nm X509_STORE_CTX_set_flags ,
 .Nm X509_STORE_CTX_get0_param ,
 .Nm X509_STORE_CTX_set0_param ,
-.Nm X509_STORE_CTX_get0_untrusted ,
-.Nm X509_STORE_CTX_set0_untrusted ,
 .Nm X509_STORE_CTX_set_default
 .Nd X509_STORE_CTX initialisation
 .Sh SYNOPSIS
@@ -110,12 +128,25 @@
 .Fa "X509_STORE_CTX *ctx"
 .Fa "X509 *x"
 .Fc
+.Ft X509 *
+.Fo X509_STORE_CTX_get0_cert
+.Fa "X509_STORE_CTX *ctx"
+.Fc
 .Ft void
 .Fo X509_STORE_CTX_set_chain
 .Fa "X509_STORE_CTX *ctx"
 .Fa "STACK_OF(X509) *sk"
 .Fc
 .Ft void
+.Fo X509_STORE_CTX_set0_untrusted
+.Fa "X509_STORE_CTX *ctx"
+.Fa "STACK_OF(X509) *sk"
+.Fc
+.Ft STACK_OF(X509) *
+.Fo X509_STORE_CTX_get0_untrusted
+.Fa "X509_STORE_CTX *ctx"
+.Fc
+.Ft void
 .Fo X509_STORE_CTX_set0_crls
 .Fa "X509_STORE_CTX *ctx"
 .Fa "STACK_OF(X509_CRL) *sk"
@@ -139,15 +170,6 @@
 .Fa "X509_STORE_CTX *ctx"
 .Fa "const char *name"
 .Fc
-.Ft STACK_OF(X509)*
-.Fo X509_STORE_CTX_get0_untrusted
-.Fa "X509_STORE_CTX *ctx"
-.Fc
-.Ft void
-.Fo X509_STORE_CTX_set0_untrusted
-.Fa "X509_STORE_CTX *ctx"
-.Fa "STACK_OF(X509) *sk"
-.Fc
 .Sh DESCRIPTION
 These functions initialise an
 .Vt X509_STORE_CTX
@@ -165,6 +187,11 @@ internally cleans up an
 structure.
 The context can then be reused with a new call to
 .Fn X509_STORE_CTX_init .
+Calling both of these functions is required before
+.Xr X509_verify_cert 3
+can be called on the same
+.Fa ctx
+another time.
 .Pp
 .Fn X509_STORE_CTX_free
 completely frees up
@@ -181,13 +208,14 @@ pointer, no action occurs.
 .Fn X509_STORE_CTX_init
 sets up
 .Fa ctx
-for a subsequent verification operation.
+for one single subsequent verification operation using
+.Xr X509_verify_cert 3 .
 The trusted certificate store is set to
 .Fa store ,
 the end entity certificate to be verified is set to
-.Fa x509
+.Fa x509 ,
 and a set of additional certificates (which will be untrusted but may be
-used to build the chain) in
+used to build the chain) can be supplied in
 .Fa chain .
 Any or all of the
 .Fa store ,
@@ -196,9 +224,22 @@ and
 .Fa chain
 parameters can be
 .Dv NULL .
+The three pointers passed in are stored internally, the three objects
+pointed to are not copied, their reference count is not incremented,
+and the caller remains responsible for managing their storage and for
+not freeing them until either
+.Fn X509_STORE_CTX_free
+is called on
+.Fa ctx
+or until both
+.Fn X509_STORE_CTX_cleanup
+and
+.Fn X509_STORE_CTX_init
+are called on
+.Fa ctx .
 .Pp
 .Fn X509_STORE_CTX_get0_store
-returns an internal pointer to the trusted certificate
+returns the internal pointer to the trusted certificate
 .Fa store
 that was set with
 .Fn X509_STORE_CTX_init .
@@ -219,13 +260,41 @@ is a deprecated alias for
 sets the certificate to be verified in
 .Fa ctx
 to
-.Fa x .
+.Fa x ,
+overriding the certificate that was set with
+.Fn X509_STORE_CTX_init .
+Again, the certificate is not copied
+and its reference count is not incremented.
+.Pp
+.Fn X509_STORE_CTX_get0_cert
+retrieves the internal pointer to the certificate being verified by
+.Fa ctx ,
+i.e. the last one set using either
+.Fn X509_STORE_CTX_init
+or
+.Fn X509_STORE_CTX_set_cert .
 .Pp
 .Fn X509_STORE_CTX_set_chain
-sets the additional certificate chain used by
+and
+.Fn X509_STORE_CTX_set0_untrusted
+are identical and set the additional, untrusted certificates used by
 .Fa ctx
 to
-.Fa sk .
+.Fa sk ,
+overriding the set of additional, untrusted certificates that was set with
+.Fn X509_STORE_CTX_init .
+Again, the set and the certificates contained in it are not copied
+and their reference counts are not incremented.
+.Pp
+.Fn X509_STORE_CTX_get0_untrusted
+retrieves the internal pointer
+to the set of additional, untrusted certificates associated with
+.Fa ctx ,
+i.e. the last one set using either
+.Fn X509_STORE_CTX_init ,
+.Fn X509_STORE_CTX_set_chain ,
+or
+.Fn X509_STORE_CTX_set0_untrusted .
 .Pp
 .Fn X509_STORE_CTX_set0_crls
 sets a set of CRLs to use to aid certificate verification to
@@ -264,18 +333,6 @@ This uses the function
 to find an appropriate set of parameters from
 .Fa name .
 .Pp
-.Fn X509_STORE_CTX_get0_untrusted
-retrieves an internal pointer
-to the stack of untrusted certificates associated with
-.Fa ctx .
-.Pp
-.Fn X509_STORE_CTX_set0_untrusted
-sets the internal pointer
-to the stack of untrusted certificates associated with
-.Fa ctx
-to
-.Fa sk .
-.Pp
 The certificates and CRLs in a store are used internally and should
 .Sy not
 be freed up until after the associated
@@ -316,6 +373,17 @@ if
 .Fa ctx
 was not initialised.
 .Pp
+.Fn X509_STORE_CTX_get0_cert
+returns the internal pointer to the certificate to be verified or
+.Dv NULL
+if no such certificate was set.
+.Pp
+.Fn X509_STORE_CTX_get0_untrusted
+returns the internal pointer
+to the set of additional, untrusted certificates or
+.Dv NULL
+if no set of additional certificates was provided.
+.Pp
 .Fn X509_STORE_CTX_get0_param
 returns a pointer to an
 .Vt X509_VERIFY_PARAM
@@ -325,9 +393,6 @@ if an error occurred.
 .Pp
 .Fn X509_STORE_CTX_set_default
 returns 1 for success or 0 if an error occurred.
-.Pp
-.Fn X509_STORE_CTX_get0_untrusted
-returns an internal pointer.
 .Sh SEE ALSO
 .Xr X509_CRL_new 3 ,
 .Xr X509_STORE_CTX_get_error 3 ,
@@ -368,16 +433,10 @@ first appeared in OpenSSL 0.9.8 and have been available since
 .Fn X509_STORE_CTX_get0_store
 first appeared in OpenSSL 1.0.2.
 .Fn X509_STORE_CTX_set0_trusted_stack ,
-.Fn X509_STORE_CTX_get0_untrusted ,
+.Fn X509_STORE_CTX_get0_cert ,
+.Fn X509_STORE_CTX_set0_untrusted ,
 and
-.Fn X509_STORE_CTX_set0_untrusted
+.Fn X509_STORE_CTX_get0_untrusted
 first appeared in OpenSSL 1.1.0.
 These functions have been available since
 .Ox 6.3 .
-.Sh BUGS
-The certificates and CRLs in a context are used internally and should
-.Sy not
-be freed up until after the associated
-.Vt X509_STORE_CTX
-is freed.
-Copies should be made or reference counts increased instead.