document X509_STORE_CTX_get0_parent_ctx(3)

1 files changed, 34 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 f7466c4bd9e..c97e60330be 100644
--- a/lib/libcrypto/man/X509_STORE_CTX_get_error.3
+++ b/lib/libcrypto/man/X509_STORE_CTX_get_error.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_STORE_CTX_get_error.3,v 1.17 2021/07/28 14:48:09 schwarze Exp $
+.\" $OpenBSD: X509_STORE_CTX_get_error.3,v 1.18 2021/07/29 09:14:23 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:
@@ -70,7 +70,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 28 2021 $
+.Dd $Mdocdate: July 29 2021 $
 .Dt X509_STORE_CTX_GET_ERROR 3
 .Os
 .Sh NAME
@@ -80,6 +80,7 @@
 .Nm X509_STORE_CTX_get_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_get0_chain ,
 .Nm X509_STORE_CTX_get_chain ,
 .Nm X509_STORE_CTX_get1_chain ,
@@ -114,6 +115,10 @@
 .Fo X509_STORE_CTX_get0_current_crl
 .Fa "X509_STORE_CTX *ctx"
 .Fc
+.Ft X509_STORE_CTX *
+.Fo X509_STORE_CTX_get0_parent_ctx
+.Fa "X509_STORE_CTX *ctx"
+.Fc
 .Ft STACK_OF(X509) *
 .Fo X509_STORE_CTX_get0_chain
 .Fa "X509_STORE_CTX *ctx"
@@ -185,6 +190,22 @@ returns the certificate revocation list that caused CRL checking to fail or
 .Dv NULL
 if no CRL is relevant.
 .Pp
+When, during certification path validation, the need arises to check
+the validity of the certification path of a CRL issuer certificate,
+the library creates a new, temporary
+.Vt X509_STORE_CTX
+object.
+If
+.Fn X509_STORE_CTX_get0_parent_ctx
+is called on that temporary object, a pointer to the original
+certification path validation context is returned.
+This may be useful in callback functions called from
+.Xr X509_verify_cert 3
+or from its subroutines to find out whether the callback is called
+from the path validation of the target certificate or from the path
+validation of a related CRL issuer certificate, and if the latter,
+what the target certificate is.
+.Pp
 .Fn X509_STORE_CTX_get0_chain
 returns an internal pointer to a complete validate chain
 if a previous call to
@@ -241,6 +262,14 @@ return the object which caused the error or
 .Dv NULL
 if no object of the requested kind is relevant to the error.
 .Pp
+.Fn X509_STORE_CTX_get0_parent_ctx
+returns the parent context or
+.Dv NULL
+if
+.Fa ctx
+is not a temporary child context
+used for path validation of a CRL issuer certificate.
+.Pp
 .Fn X509_STORE_CTX_get0_chain ,
 .Fn X509_STORE_CTX_get_chain ,
 and
@@ -467,9 +496,10 @@ and
 first appeared in OpenSSL 0.9.8 and have been available since
 .Ox 4.5 .
 .Pp
-.Fn X509_STORE_CTX_get0_current_issuer
+.Fn X509_STORE_CTX_get0_current_issuer ,
+.Fn X509_STORE_CTX_get0_current_crl ,
 and
-.Fn X509_STORE_CTX_get0_current_crl
+.Fn X509_STORE_CTX_get0_parent_ctx
 first appeared in OpenSSL 1.0.0 and have been available since
 .Ox 4.9 .
 .Pp