In x509_vfy.h rev. 1.21 2018/02/22 17:11:30, jsing@ provided

X509_STORE_CTX_get0_chain(3).  Adapt the documentation.

It is absurd that OpenSSL documents the two almost identical functions
X509_STORE_CTX_get0_chain(3) and X509_STORE_CTX_get1_chain(3) in
two different manual pages, with quite different wordings, and without
even referencing each other.  It is very obvious that they have
lost their way in their own mire of functions.

2 files changed, 32 insertions, 14 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 5caf4cefe4..a53824c821 100644
--- a/src/lib/libcrypto/man/X509_STORE_CTX_get_error.3
+++ b/src/lib/libcrypto/man/X509_STORE_CTX_get_error.3
@@ -1,6 +1,9 @@
-.\" $OpenBSD: X509_STORE_CTX_get_error.3,v 1.6 2018/02/15 11:09:34 schwarze Exp $
-.\" full merge up to: OpenSSL f0e0fd51 Apr 14 23:59:26 2016 -0400
-.\" selective merge up to: OpenSSL 2947af32 Nov 19 00:10:05 2016 +0100
+.\" $OpenBSD: X509_STORE_CTX_get_error.3,v 1.7 2018/02/25 16:04:07 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 2947af32 Nov 19 00:10:05 2016 +0100
+.\" OpenSSL man3/X509_STORE_CTX_new 7643a172 Apr 21 13:35:51 2017 +0200
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2009, 2013, 2015, 2016 The OpenSSL Project.
@@ -50,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: February 15 2018 $
+.Dd $Mdocdate: February 25 2018 $
 .Dt X509_STORE_CTX_GET_ERROR 3
 .Os
 .Sh NAME
@@ -59,6 +62,7 @@
 .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_get1_chain ,
 .Nm X509_verify_cert_error_string
 .Nd get or set certificate verification status information
@@ -86,6 +90,10 @@
 .Fa "X509_STORE_CTX *ctx"
 .Fc
 .Ft STACK_OF(X509) *
+.Fo X509_STORE_CTX_get0_chain
+.Fa "X509_STORE_CTX *ctx"
+.Fc
+.Ft STACK_OF(X509) *
 .Fo X509_STORE_CTX_get1_chain
 .Fa "X509_STORE_CTX *ctx"
 .Fc
@@ -128,19 +136,19 @@ which caused the error or
 .Dv NULL
 if no certificate is relevant.
 .Pp
-.Fn X509_STORE_CTX_get1_chain
-returns a complete validate chain if a previous call to
+.Fn X509_STORE_CTX_get0_chain
+returns an internal pointer to a complete validate chain
+if a previous call to
 .Xr X509_verify_cert 3
-is successful.
+was successful.
 If the call to
 .Xr X509_verify_cert 3
-is
-.Sy not
-successful, the returned chain may be incomplete or invalid.
-The returned chain persists after the
+was not successful, the returned chain may be incomplete or invalid.
+.Fn X509_STORE_CTX_get1_chain
+returns a deep copy of the same chain which persists even after the
 .Fa ctx
 structure is freed.
-When it is no longer needed, it should be freed up using
+When it is no longer needed, it should be freed using
 .Fn sk_X509_pop_free chain X509_free .
 .Pp
 .Fn X509_verify_cert_error_string
@@ -182,6 +190,13 @@ if no certificate is relevant to the error.
 retrieves an internal pointer to the certificate being verified by
 .Fa ctx .
 .Pp
+.Fn X509_STORE_CTX_get0_chain
+and
+.Fn X509_STORE_CTX_get1_chain
+return a pointer to a stack of certificates or
+.Dv NULL
+if an error occurs.
+.Pp
 .Fn X509_verify_cert_error_string
 returns a human readable error string for verification error
 .Fa n .
@@ -356,5 +371,6 @@ An application specific error.
 This will never be returned unless explicitly set by an application.
 .El
 .Sh SEE ALSO
+.Xr X509_STORE_CTX_new 3 ,
 .Xr X509_up_ref 3 ,
 .Xr X509_verify_cert 3
diff --git a/src/lib/libcrypto/man/X509_STORE_CTX_new.3 b/src/lib/libcrypto/man/X509_STORE_CTX_new.3
index ca3c43ecbd..35027a7154 100644
--- a/src/lib/libcrypto/man/X509_STORE_CTX_new.3
+++ b/src/lib/libcrypto/man/X509_STORE_CTX_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_STORE_CTX_new.3,v 1.7 2018/02/15 11:09:34 schwarze Exp $
+.\" $OpenBSD: X509_STORE_CTX_new.3,v 1.8 2018/02/25 16:04:07 schwarze 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
 .\"
@@ -50,7 +50,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: February 15 2018 $
+.Dd $Mdocdate: February 25 2018 $
 .Dt X509_STORE_CTX_NEW 3
 .Os
 .Sh NAME
@@ -61,6 +61,7 @@
 .Nm X509_STORE_CTX_set0_trusted_stack ,
 .Nm X509_STORE_CTX_trusted_stack ,
 .Nm X509_STORE_CTX_set_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_crls ,
 .Nm X509_STORE_CTX_get0_param ,
@@ -297,6 +298,7 @@ returns 1 for success or 0 if an error occurred.
 .Fn X509_STORE_CTX_get0_untrusted
 returns an internal pointer.
 .Sh SEE ALSO
+.Xr X509_STORE_CTX_get_error 3 ,
 .Xr X509_verify_cert 3 ,
 .Xr X509_VERIFY_PARAM_set_flags 3
 .Sh HISTORY