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.

diff --git a/lib/libcrypto/man/X509_STORE_CTX_get_error.3 b/lib/libcrypto/man/X509_STORE_CTX_get_error.3
index 5caf4ce..a53824c 100644 (file)
--- a/lib/libcrypto/man/X509_STORE_CTX_get_error.3
+++ b/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/lib/libcrypto/man/X509_STORE_CTX_new.3 b/lib/libcrypto/man/X509_STORE_CTX_new.3
index ca3c43e..35027a7 100644 (file)
--- a/lib/libcrypto/man/X509_STORE_CTX_new.3
+++ b/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