Various improvements; joint work with beck@:

1. Explain up front what "ASN1_TIME" is (suggested by beck@, wording by me).
2. For opaque structs, use the generic term "object",
like we already do it in many other LibreSSL manual pages.
3. Drop some redundant phrases.
4. Improve the EXAMPLES section (by beck@, with fixes by me).
6. Add a STANDARDS section.
...and some other minor polishing.
OK beck@

1 files changed, 72 insertions, 64 deletions

diff --git a/lib/libcrypto/man/ASN1_TIME_set.3 b/lib/libcrypto/man/ASN1_TIME_set.3
index b8a567ece07..4f6a99673a8 100644
--- a/lib/libcrypto/man/ASN1_TIME_set.3
+++ b/lib/libcrypto/man/ASN1_TIME_set.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ASN1_TIME_set.3,v 1.18 2022/11/10 17:44:05 schwarze Exp $
+.\" $OpenBSD: ASN1_TIME_set.3,v 1.19 2022/11/13 22:11:44 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
 .\"
@@ -6,14 +6,15 @@
 .\" The changes are covered by the following Copyright and license:
 .\"
 .\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2022 Bob Beck <beck@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
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS 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
@@ -67,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 10 2022 $
+.Dd $Mdocdate: November 13 2022 $
 .Dt ASN1_TIME_SET 3
 .Os
 .Sh NAME
@@ -217,12 +218,35 @@
 .Fa "ASN1_GENERALIZEDTIME **out"
 .Fc
 .Sh DESCRIPTION
+An
+.Vt ASN1_TIME
+object is a shallow wrapper around a string containing an ASN.1
+.Vt Time
+value in the restricted format valid in X.509 certificates.
+An
+.Vt ASN1_TIME
+object is either an
+.Vt ASN1_UTCTIME
+object containing a string of the format
+.Ar YYMMDDHHMMSS Ns Cm Z
+which is valid for the years 1950 to 2049, or an
+.Vt ASN1_GENERALIZEDTIME
+object containing a string of the format
+.Ar YYYYMMDDHHMMSS Ns Cm Z
+which is valid for the years 0000 to 1949 and 2050 to 9999.
+In both cases, the mandatory suffix
+.Sq Cm Z
+represents the GMT time zone.
+LibreSSL by design does not support the full syntax of ASN.1 times.
+In particular, it neither supports fractional seconds
+nor any other time zone.
+.Pp
 The functions
 .Fn ASN1_TIME_set ,
 .Fn ASN1_UTCTIME_set ,
 and
 .Fn ASN1_GENERALIZEDTIME_set
-set the time structure
+set the time object
 .Fa s
 to the time represented by the
 .Vt time_t
@@ -232,14 +256,14 @@ If
 .Fa s
 is
 .Dv NULL ,
-a new time structure is allocated and returned.
+a new time object is allocated and returned.
 .Pp
 The functions
 .Fn ASN1_TIME_adj ,
 .Fn ASN1_UTCTIME_adj ,
 and
 .Fn ASN1_GENERALIZEDTIME_adj
-set the time structure
+set the time object
 .Fa s
 to the time represented by the time
 .Fa offset_day
@@ -262,7 +286,7 @@ If
 .Fa s
 is
 .Dv NULL ,
-a new time structure is allocated and returned.
+a new time object is allocated and returned.
 .Pp
 .Fn ASN1_TIME_adj
 may change the type from
@@ -274,7 +298,7 @@ The functions
 .Fn ASN1_UTCTIME_adj
 and
 .Fn ASN1_GENERALIZEDTIME_adj
-do not modify the type of the return structure.
+do not modify the type of the return object.
 .Pp
 The functions
 .Fn ASN1_TIME_set_string ,
@@ -282,9 +306,9 @@ The functions
 .Fn ASN1_UTCTIME_set_string ,
 and
 .Fn ASN1_GENERALIZEDTIME_set_string
-set the time structure
+set the time object
 .Fa s
-to the time represented by the string
+to the time string
 .Fa str ,
 which must be in appropriate ASN.1 time format:
 YYMMDDHHMMSSZ for
@@ -308,32 +332,28 @@ 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
+behave identically and always set the time object
+to a valid value to use in an X.509 certificate.
 .Fn ASN1_GENERALIZEDTIME_set_string
-may accept additional formats that violate RFC 5280.
+may encode a time string that is not valid in an X.509 certificate.
 .Pp
 The function
 .Fn ASN1_TIME_normalize
 converts an
 .Vt ASN1_GENERALIZEDTIME
-or
+into a time value that can be used in a certificate
+by changing it to an
 .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 .
+if possible.
+It has no effect on an
+.Vt ASN1_UTCTIME .
 .Pp
 The functions
 .Fn ASN1_TIME_check ,
 .Fn ASN1_UTCTIME_check ,
 and
 .Fn ASN1_GENERALIZEDTIME_check
-check the syntax of the time structure
+check the syntax of the time string contained in the object
 .Fa s .
 .Pp
 The functions
@@ -350,11 +370,8 @@ in human readable format.
 It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example "Feb 3
 00:55:52 2015 GMT".
 It does not include a newline.
-If the time structure has an invalid format,
+If the time string has an invalid format,
 it prints out "Bad time value" and returns an error.
-The output of
-.Fn ASN1_GENERALIZEDTIME_print
-may include a fractional part following the second.
 .Pp
 The function
 .Fn ASN1_TIME_to_tm
@@ -368,7 +385,7 @@ If
 is
 .Dv NULL ,
 then the current time is converted.
-The output time is GMT.
+The output time is always in the GMT time zone.
 The
 .Fa tm_sec , tm_min , tm_hour , tm_mday , tm_mon ,
 and
@@ -465,33 +482,15 @@ is
 then a new object is allocated and must be freed after use.
 .Pp
 The
-.Vt ASN1_TIME
-structure corresponds to the ASN.1 structure
-.Sy Time
-defined in RFC 5280 et al.
-The time setting functions obey the rules outlined in RFC 5280: if the
-date can be represented by UTCTime it is used, otherwise GeneralizedTime is
-used.
-.Pp
-The
 .Vt ASN1_TIME ,
 .Vt ASN1_UTCTIME ,
 and
 .Vt ASN1_GENERALIZEDTIME
-structures are represented as
+objects are represented as
 .Vt ASN1_STRING
-structures internally and can be freed using
+objects internally and can be freed using
 .Xr ASN1_STRING_free 3 .
 .Pp
-The
-.Vt ASN1_TIME
-structure can represent years from 0000 to 9999 but no attempt is
-made to correct ancient calendar changes (for example from Julian
-to Gregorian calendars).
-.Pp
-.Vt ASN1_UTCTIME
-is limited to a year range of 1950 through 2049.
-.Pp
 It is recommended that
 .Vt ASN1_TIME
 functions be used instead of
@@ -514,7 +513,7 @@ functions operate on either format.
 .Fn ASN1_GENERALIZEDTIME_adj ,
 and
 .Fn ASN1_TIME_to_generalizedtime
-return a pointer to a time structure or
+return a pointer to a time object or
 .Dv NULL
 if an error occurred.
 .Pp
@@ -532,7 +531,8 @@ returns 1 on success or 0 on error.
 .Fn ASN1_UTCTIME_check ,
 and
 .Fn ASN1_GENERALIZEDTIME_check
-return 1 if the time structure is syntactically correct or 0 otherwise.
+return 1 if the time string contained in the object is syntactically
+correct or 0 otherwise.
 .Pp
 .Fn ASN1_TIME_print ,
 .Fn ASN1_UTCTIME_print ,
@@ -547,7 +547,7 @@ 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.
+It can for example fail if a time string passed in has invalid syntax.
 .Pp
 .Fn ASN1_TIME_cmp_time_t ,
 .Fn ASN1_UTCTIME_cmp_time_t ,
@@ -563,27 +563,42 @@ is later than
 .Fa t ,
 or \-2 on error.
 .Sh EXAMPLES
-Set a time structure to one hour after the current time and print it
+Set a time object to one hour after the current time and print it
 out:
 .Bd -literal -offset indent
 #include <time.h>
 #include <openssl/asn1.h>
 
-ASN1_TIME *tm;
+ASN1_TIME *asn1_time;
 time_t t;
 BIO *b;
 
 t = time(NULL);
-tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60);
+asn1_time = ASN1_TIME_adj(NULL, t, 0, 60 * 60);
 b = BIO_new_fp(stdout, BIO_NOCLOSE);
-ASN1_TIME_print(b, tm);
-ASN1_STRING_free(tm);
+if (asn1_time != NULL) {
+	ASN1_TIME_print(b, asn1_time);
+	BIO_printf(b, "\en");
+} else {
+	BIO_printf(b, "Time out of range or un-representable\en");
+}
+ASN1_STRING_free(asn1_time);
 BIO_free(b);
 .Ed
 .Sh SEE ALSO
 .Xr ASN1_TIME_new 3 ,
 .Xr ASN1_time_parse 3 ,
 .Xr X509_cmp_time 3
+.Sh STANDARDS
+The usage of the ASN.1
+.Vt Time ,
+.Vt UTCTime ,
+and
+.Vt GeneralizedTime
+data types in X.509 certificates is specified in
+RFC 5280, Internet X.509 Public Key Infrastructure Certificate and
+Certificate Revocation List (CRL) Profile,
+section 4.1.2.5 (TBS Certificate Validity).
 .Sh HISTORY
 .Fn ASN1_UTCTIME_check
 and
@@ -654,10 +669,3 @@ and
 parameters instead of directly manipulating a
 .Vt time_t
 value.
-.Sh BUGS
-.Fn ASN1_TIME_print ,
-.Fn ASN1_UTCTIME_print ,
-and
-.Fn ASN1_GENERALIZEDTIME_print
-do not print the time zone: they either print "GMT" or nothing.
-But all certificates complying with RFC 5280 et al use GMT anyway.