In asn1.h rev. 1.65, beck@ provided ASN1_TIME_set_string_X509(3),

ASN1_TIME_normalize(3), ASN1_TIME_to_tm(3), ASN1_TIME_cmp_time_t(3),
and ASN1_TIME_compare(3).
Merge documentation from the OpenSSL 1.1.1 branch, which is still
under a free license, with tweaks by me in several respects to match
our implementation, and also using some feedback from beck@.
OK beck@.

diff --git a/lib/libcrypto/man/ASN1_TIME_set.3 b/lib/libcrypto/man/ASN1_TIME_set.3
index cd6ab93..b8a567e 100644 (file)
--- a/lib/libcrypto/man/ASN1_TIME_set.3
+++ b/lib/libcrypto/man/ASN1_TIME_set.3
@@ -1,8 +1,25 @@
-.\" $OpenBSD: ASN1_TIME_set.3,v 1.17 2022/03/31 17:27:16 naddy Exp $
-.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
+.\" $OpenBSD: ASN1_TIME_set.3,v 1.18 2022/11/10 17:44:05 schwarze Exp $
+.\" full merge up to: OpenSSL 3d0f1cb9 Jul 11 03:01:24 2017 +0800
 .\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
-.\" This file was written by Dr. Stephen Henson <steve@openssl.org>
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>
 .\" and Todd Short <tshort@akamai.com>.
 .\" Copyright (c) 2015, 2017 The OpenSSL Project.  All rights reserved.
 .\"
@@ -50,7 +67,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 31 2022 $
+.Dd $Mdocdate: November 10 2022 $
 .Dt ASN1_TIME_SET 3
 .Os
 .Sh NAME
@@ -61,16 +78,21 @@
 .Nm ASN1_UTCTIME_adj ,
 .Nm ASN1_GENERALIZEDTIME_adj ,
 .Nm ASN1_TIME_set_string ,
+.Nm ASN1_TIME_set_string_X509 ,
 .Nm ASN1_UTCTIME_set_string ,
 .Nm ASN1_GENERALIZEDTIME_set_string ,
+.Nm ASN1_TIME_normalize ,
 .Nm ASN1_TIME_check ,
 .Nm ASN1_UTCTIME_check ,
 .Nm ASN1_GENERALIZEDTIME_check ,
 .Nm ASN1_TIME_print ,
 .Nm ASN1_UTCTIME_print ,
 .Nm ASN1_GENERALIZEDTIME_print ,
+.Nm ASN1_TIME_to_tm ,
 .Nm ASN1_TIME_diff ,
+.Nm ASN1_TIME_cmp_time_t ,
 .Nm ASN1_UTCTIME_cmp_time_t ,
+.Nm ASN1_TIME_compare ,
 .Nm ASN1_TIME_to_generalizedtime
 .Nd ASN.1 Time functions
 .Sh SYNOPSIS
@@ -117,6 +139,11 @@
 .Fa "const char *str"
 .Fc
 .Ft int
+.Fo ASN1_TIME_set_string_X509
+.Fa "ASN1_TIME *s"
+.Fa "const char *str"
+.Fc
+.Ft int
 .Fo ASN1_UTCTIME_set_string
 .Fa "ASN1_UTCTIME *s"
 .Fa "const char *str"
@@ -127,6 +154,10 @@
 .Fa "const char *str"
 .Fc
 .Ft int
+.Fo ASN1_TIME_normalize
+.Fa "ASN1_TIME *s"
+.Fc
+.Ft int
 .Fo ASN1_TIME_check
 .Fa "const ASN1_TIME *t"
 .Fc
@@ -154,6 +185,11 @@
 .Fa "const ASN1_GENERALIZEDTIME *s"
 .Fc
 .Ft int
+.Fo ASN1_TIME_to_tm
+.Fa "const ASN1_TIME *s"
+.Fa "struct tm *tm"
+.Fc
+.Ft int
 .Fo ASN1_TIME_diff
 .Fa "int *pday"
 .Fa "int *psec"
@@ -161,10 +197,20 @@
 .Fa "const ASN1_TIME *to"
 .Fc
 .Ft int
+.Fo ASN1_TIME_cmp_time_t
+.Fa "const ASN1_TIME *s"
+.Fa "time_t t"
+.Fc
+.Ft int
 .Fo ASN1_UTCTIME_cmp_time_t
 .Fa "const ASN1_UTCTIME *s"
 .Fa "time_t t"
 .Fc
+.Ft int
+.Fo ASN1_TIME_compare
+.Fa "const ASN1_TIME *s"
+.Fa "const ASN1_TIME *t"
+.Fc
 .Ft ASN1_GENERALIZEDTIME *
 .Fo ASN1_TIME_to_generalizedtime
 .Fa "const ASN1_TIME *t"
@@ -232,6 +278,7 @@ do not modify the type of the return structure.
 .Pp
 The functions
 .Fn ASN1_TIME_set_string ,
+.Fn ASN1_TIME_set_string_X509 ,
 .Fn ASN1_UTCTIME_set_string ,
 and
 .Fn ASN1_GENERALIZEDTIME_set_string
@@ -239,8 +286,13 @@ set the time structure
 .Fa s
 to the time represented by the string
 .Fa str ,
-which must be in appropriate ASN.1 time format (for example
-YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ).
+which must be in appropriate ASN.1 time format:
+YYMMDDHHMMSSZ for
+.Vt ASN1_UTCTIME ,
+YYYYMMDDHHMMSSZ for
+.Vt ASN1_GENERALIZEDTIME ,
+or either of the two for
+.Vt ASN1_TIME .
 The string
 .Fa str
 is copied into
@@ -252,6 +304,30 @@ is
 these functions only perform a format check on
 .Fa str .
 .Pp
+In LibreSSL,
+.Fn ASN1_TIME_set_string
+and
+.Fn ASN1_TIME_set_string_X509
+behave identically.
+In other implementations,
+.Fn ASN1_TIME_set_string ,
+.Fn ASN1_UTCTIME_set_string ,
+and
+.Fn ASN1_GENERALIZEDTIME_set_string
+may accept additional formats that violate RFC 5280.
+.Pp
+The function
+.Fn ASN1_TIME_normalize
+converts an
+.Vt ASN1_GENERALIZEDTIME
+or
+.Vt ASN1_UTCTIME
+into a time value that can be used in a certificate.
+It is intended to be used after the
+.Fn ASN1_TIME_set_string
+functions to ensure the value is valid for use as an
+.Vt ASN1_TIME .
+.Pp
 The functions
 .Fn ASN1_TIME_check ,
 .Fn ASN1_UTCTIME_check ,
@@ -281,6 +357,35 @@ The output of
 may include a fractional part following the second.
 .Pp
 The function
+.Fn ASN1_TIME_to_tm
+converts the time
+.Fa s
+to the standard
+.Vt tm
+structure.
+If
+.Fa s
+is
+.Dv NULL ,
+then the current time is converted.
+The output time is GMT.
+The
+.Fa tm_sec , tm_min , tm_hour , tm_mday , tm_mon ,
+and
+.Fa tm_year
+fields of the
+.Vt tm
+structure are set to the proper values,
+whereas all other fields are set to 0.
+If
+.Fa tm
+is
+.Dv NULL ,
+this function performs a format check on
+.Fa s
+only.
+.Pp
+The function
 .Fn ASN1_TIME_diff
 sets
 .Pf * Fa pday
@@ -333,9 +438,12 @@ is
 .Dv NULL ,
 the current time is used.
 .Pp
-The function
-.Fn ASN1_UTCTIME_cmp_time_t
-compares the two times represented by
+The functions
+.Fn ASN1_TIME_cmp_time_t ,
+.Fn ASN1_UTCTIME_cmp_time_t ,
+and
+.Fn ASN1_TIME_compare
+compare the two times represented by
 .Fa s
 and
 .Fa t .
@@ -411,11 +519,15 @@ return a pointer to a time structure or
 if an error occurred.
 .Pp
 .Fn ASN1_TIME_set_string ,
+.Fn ASN1_TIME_set_string_X509 ,
 .Fn ASN1_UTCTIME_set_string ,
 and
 .Fn ASN1_GENERALIZEDTIME_set_string
 return 1 if the time value is successfully set or 0 otherwise.
 .Pp
+.Fn ASN1_TIME_normalize
+returns 1 on success or 0 on error.
+.Pp
 .Fn ASN1_TIME_check ,
 .Fn ASN1_UTCTIME_check ,
 and
@@ -429,12 +541,19 @@ and
 return 1 if the time is successfully printed or 0 if an error
 occurred (I/O error or invalid time format).
 .Pp
+.Fn ASN1_TIME_to_tm
+returns 1 if the time is successfully parsed
+or 0 if an error occurred, usually due to an invalid time format.
+.Pp
 .Fn ASN1_TIME_diff
 returns 1 for success or 0 for failure.
 It can for example fail if a time structure passed in has invalid syntax.
 .Pp
-.Fn ASN1_UTCTIME_cmp_time_t
-returns \-1 if
+.Fn ASN1_TIME_cmp_time_t ,
+.Fn ASN1_UTCTIME_cmp_time_t ,
+and
+.Fn ASN1_TIME_compare
+return \-1 if
 .Fa s
 is earlier than
 .Fa t ,
@@ -508,6 +627,15 @@ first appeared in OpenSSL 1.0.0 and have been available since
 .Fn ASN1_TIME_diff
 first appeared in OpenSSL 1.0.2 and have been available since
 .Ox 7.1 .
+.Pp
+.Fn ASN1_TIME_set_string_X509 ,
+.Fn ASN1_TIME_normalize ,
+.Fn ASN1_TIME_to_tm ,
+.Fn ASN1_TIME_cmp_time_t ,
+and
+.Fn ASN1_TIME_compare
+first appeared in OpenSSL 1.1.1 and have been available since
+.Ox 7.2 .
 .Sh CAVEATS
 Some applications add offset times directly to a
 .Vt time_t