From 1798df84cbb794ed8d189740fcca83fd582846a0 Mon Sep 17 00:00:00 2001
From: schwarze <schwarze@openbsd.org>
Date: Tue, 16 Nov 2021 12:06:57 +0000
Subject: [PATCH] Recently, tb@ provided the following functions:
 X509_STORE_CTX_set_error_depth      x509_vfy.h 1.37  x509_vfy.c  1.91
 X509_STORE_CTX_set_current_cert     x509_vfy.h 1.37  x509_vfy.c  1.91
 X509_STORE_CTX_get_num_untrusted    x509_vfy.h 1.36  x509_vfy.c  1.90
 X509_STORE_CTX_set0_verified_chain  x509_vfy.h 1.37  x509_vfy.c  1.91

Merge the documentation from the OpenSSL 1.1.1 branch,
which is still under a free license; tweaked by me.
---
 lib/libcrypto/man/X509_STORE_CTX_get_error.3 | 75 ++++++++++++++++++--
 1 file changed, 71 insertions(+), 4 deletions(-)

diff --git a/lib/libcrypto/man/X509_STORE_CTX_get_error.3 b/lib/libcrypto/man/X509_STORE_CTX_get_error.3
index c97e60330be..36ea311dce8 100644
--- a/lib/libcrypto/man/X509_STORE_CTX_get_error.3
+++ b/lib/libcrypto/man/X509_STORE_CTX_get_error.3
@@ -1,7 +1,5 @@
-.\" $OpenBSD: X509_STORE_CTX_get_error.3,v 1.18 2021/07/29 09:14:23 schwarze Exp $
+.\" $OpenBSD: X509_STORE_CTX_get_error.3,v 1.19 2021/11/16 12:06:57 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
 .\"
@@ -70,20 +68,24 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 29 2021 $
+.Dd $Mdocdate: November 16 2021 $
 .Dt X509_STORE_CTX_GET_ERROR 3
 .Os
 .Sh NAME
 .Nm X509_STORE_CTX_get_error ,
 .Nm X509_STORE_CTX_set_error ,
 .Nm X509_STORE_CTX_get_error_depth ,
+.Nm X509_STORE_CTX_set_error_depth ,
 .Nm X509_STORE_CTX_get_current_cert ,
+.Nm X509_STORE_CTX_set_current_cert ,
 .Nm X509_STORE_CTX_get0_current_issuer ,
 .Nm X509_STORE_CTX_get0_current_crl ,
 .Nm X509_STORE_CTX_get0_parent_ctx ,
+.Nm X509_STORE_CTX_get_num_untrusted ,
 .Nm X509_STORE_CTX_get0_chain ,
 .Nm X509_STORE_CTX_get_chain ,
 .Nm X509_STORE_CTX_get1_chain ,
+.Nm X509_STORE_CTX_set0_verified_chain ,
 .Nm X509_STORE_CTX_get0_policy_tree ,
 .Nm X509_STORE_CTX_get_explicit_policy ,
 .Nm X509_verify_cert_error_string
@@ -103,10 +105,20 @@
 .Fo X509_STORE_CTX_get_error_depth
 .Fa "X509_STORE_CTX *ctx"
 .Fc
+.Ft void
+.Fo X509_STORE_CTX_set_error_depth
+.Fa "X509_STORE_CTX *ctx"
+.Fa "int depth"
+.Fc
 .Ft X509 *
 .Fo X509_STORE_CTX_get_current_cert
 .Fa "X509_STORE_CTX *ctx"
 .Fc
+.Ft void
+.Fo X509_STORE_CTX_set_current_cert
+.Fa "X509_STORE_CTX *ctx"
+.Fa "X509 *cert"
+.Fc
 .Ft X509 *
 .Fo X509_STORE_CTX_get0_current_issuer
 .Fa "X509_STORE_CTX *ctx"
@@ -119,6 +131,10 @@
 .Fo X509_STORE_CTX_get0_parent_ctx
 .Fa "X509_STORE_CTX *ctx"
 .Fc
+.Ft int
+.Fo X509_STORE_CTX_get_num_untrusted
+.Fa "X509_STORE_CTX *ctx"
+.Fc
 .Ft STACK_OF(X509) *
 .Fo X509_STORE_CTX_get0_chain
 .Fa "X509_STORE_CTX *ctx"
@@ -131,6 +147,11 @@
 .Fo X509_STORE_CTX_get1_chain
 .Fa "X509_STORE_CTX *ctx"
 .Fc
+.Ft void
+.Fo X509_STORE_CTX_set0_verified_chain
+.Fa "X509_STORE_CTX *ctx"
+.Fa "STACK_OF(X509) *chain"
+.Fc
 .Ft X509_POLICY_TREE *
 .Fo X509_STORE_CTX_get0_policy_tree
 .Fa "X509_STORE_CTX *ctx"
@@ -173,6 +194,12 @@ chain the error occurred.
 If it is zero, it occurred in the end entity certificate, one if it is
 the certificate which signed the end entity certificate, and so on.
 .Pp
+.Fn X509_STORE_CTX_set_error_depth
+sets the error depth.
+This can be used in combination with
+.Fn X509_STORE_CTX_set_error
+to set the depth at which an error condition was detected.
+.Pp
 .Fn X509_STORE_CTX_get_current_cert
 returns the certificate in
 .Fa ctx
@@ -180,6 +207,22 @@ which caused the error or
 .Dv NULL
 if no certificate is relevant.
 .Pp
+.Fn X509_STORE_CTX_set_current_cert
+sets the certificate which caused the error in
+.Fa ctx
+to the given
+.Fa cert .
+This value is not intended to remain valid for very long,
+and remains owned by the caller.
+It may be examined by a verification callback invoked to handle
+each error encountered during chain verification and is no longer
+required after such a callback.
+If a callback wishes the save the certificate for use after it returns,
+it needs to increment its reference count via
+.Xr X509_up_ref 3 .
+Once such a saved certificate is no longer needed, it can be freed with
+.Xr X509_free 3 .
+.Pp
 .Fn X509_STORE_CTX_get0_current_issuer
 returns the certificate that caused issuer validation to fail or
 .Dv NULL
@@ -224,6 +267,17 @@ structure is freed.
 When it is no longer needed, it should be freed using
 .Fn sk_X509_pop_free chain X509_free .
 .Pp
+.Fn X509_STORE_CTX_set0_verified_chain
+frees the validate chain generated by if a previous call to
+.Xr X509_verify_cert 3 ,
+if any, and replaces it with the given
+.Fa chain .
+Ownership of the
+.Fa chain
+is transferred to the
+.Fa ctx ,
+so it should not be freed by the caller.
+.Pp
 .Fn X509_verify_cert_error_string
 returns a human readable error string for verification error
 .Fa n .
@@ -270,6 +324,11 @@ if
 is not a temporary child context
 used for path validation of a CRL issuer certificate.
 .Pp
+.Fn X509_STORE_CTX_get_num_untrusted
+returns the number of untrusted certificates
+that were used in building the chain during a call to
+.Xr X509_verify_cert 3 .
+.Pp
 .Fn X509_STORE_CTX_get0_chain ,
 .Fn X509_STORE_CTX_get_chain ,
 and
@@ -506,3 +565,11 @@ first appeared in OpenSSL 1.0.0 and have been available since
 .Fn X509_STORE_CTX_get0_chain
 first appeared in OpenSSL 1.1.0 and has been available since
 .Ox 6.3 .
+.Pp
+.Fn X509_STORE_CTX_set_error_depth ,
+.Fn X509_STORE_CTX_set_current_cert ,
+.Fn X509_STORE_CTX_get_num_untrusted ,
+and
+.Fn X509_STORE_CTX_set0_verified_chain
+first appeared in OpenSSL 1.1.0 and have been available since
+.Ox 7.1 .
-- 
2.20.1