Document the interactions of X509_V_FLAG_USE_CHECK_TIME,

X509_V_FLAG_NO_CHECK_TIME, X509_VERIFY_PARAM_set_time(3),
X509_VERIFY_PARAM_set_flags(3), and X509_VERIFY_PARAM_clear_flags(3)
in detail because the API design is both surprising and surprisingly
complicated in this respect, and the resulting nasty traps have
already caused bugs in the past.

diff --git a/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3 b/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3
index 6db1e0e..6e2c025 100644 (file)
--- a/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3
+++ b/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_VERIFY_PARAM_set_flags.3,v 1.19 2021/11/12 18:56:00 schwarze Exp $
+.\" $OpenBSD: X509_VERIFY_PARAM_set_flags.3,v 1.20 2021/11/13 19:21:17 schwarze Exp $
 .\" full merge up to: OpenSSL d33def66 Feb 9 14:17:13 2016 -0500
 .\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
@@ -68,7 +68,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 12 2021 $
+.Dd $Mdocdate: November 13 2021 $
 .Dt X509_VERIFY_PARAM_SET_FLAGS 3
 .Os
 .Sh NAME
@@ -599,13 +599,42 @@ certificates.
 This makes it possible to trust certificates issued by an intermediate
 CA without having to trust its ancestor root CA.
 .Pp
-The
+If
+.Dv X509_V_FLAG_USE_CHECK_TIME
+is set, the validity period of certificates and CRLs is checked.
+In this case,
 .Dv X509_V_FLAG_NO_CHECK_TIME
-flag suppresses checking the validity period of certificates and CRLs
-against the current time.
+is ignored.
+If the validation time was set with
+.Fn X509_VERIFY_PARAM_set_time ,
+that time is used.
 If
 .Fn X509_VERIFY_PARAM_set_time
-is used to specify a verification time, the check is not suppressed.
+was not called, the UNIX Epoch (January 1, 1970) is used.
+.Pp
+If neither
+.Dv X509_V_FLAG_USE_CHECK_TIME
+nor
+.Dv X509_V_FLAG_NO_CHECK_TIME
+is set, the validity period of certificates and CRLs is checked
+using the current time.
+This is the deafult behaviour.
+In this case, if a validation time was set with
+.Fn X509_VERIFY_PARAM_set_time
+but
+.Dv X509_V_FLAG_USE_CHECK_TIME
+was later cleared with
+.Fn X509_VERIFY_PARAM_clear_flags ,
+the configured validation time is ignored
+and the current time is used anyway.
+.Pp
+If
+.Dv X509_V_FLAG_USE_CHECK_TIME
+is not set but
+.Dv X509_V_FLAG_NO_CHECK_TIME
+is set, the validity period of certificates and CRLs is not checked
+at all, and like in the previous case, any configured validation
+time is ignored.
 .Sh EXAMPLES
 Enable CRL checking when performing certificate verification during
 SSL connections associated with an