1 files changed, 227 insertions, 48 deletions

diff --git a/src/lib/libcrypto/man/ASN1_TIME_set.3 b/src/lib/libcrypto/man/ASN1_TIME_set.3
index 830fa39242..5fc6edb3db 100644
--- a/src/lib/libcrypto/man/ASN1_TIME_set.3
+++ b/src/lib/libcrypto/man/ASN1_TIME_set.3
@@ -1,8 +1,10 @@
-.\"     $OpenBSD: ASN1_TIME_set.3,v 1.2 2016/11/10 15:08:13 jmc Exp $
-.\"     OpenSSL 99d63d46 Mon Jun 6 00:43:05 2016 -0400
+.\"     $OpenBSD: ASN1_TIME_set.3,v 1.3 2017/08/20 17:16:40 schwarze Exp $
+.\"     OpenSSL ASN1_TIME_set.pod cf37aaa3 Aug 4 11:24:03 2017 +1000
+.\"     OpenSSL ASN1_TIME_set.pod e9b77246 Jan 20 19:58:49 2017 +0100
 .\"
-.\" This file was written by Dr. Stephen Henson.
-.\" Copyright (c) 2015 The OpenSSL Project.  All rights reserved.
+.\" This 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.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -48,15 +50,27 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 10 2016 $
+.Dd $Mdocdate: August 20 2017 $
 .Dt ASN1_TIME_SET 3
 .Os
 .Sh NAME
 .Nm ASN1_TIME_set ,
+.Nm ASN1_UTCTIME_set ,
+.Nm ASN1_GENERALIZEDTIME_set ,
 .Nm ASN1_TIME_adj ,
+.Nm ASN1_UTCTIME_adj ,
+.Nm ASN1_GENERALIZEDTIME_adj ,
 .Nm ASN1_TIME_set_string ,
+.Nm ASN1_UTCTIME_set_string ,
+.Nm ASN1_GENERALIZEDTIME_set_string ,
 .Nm ASN1_TIME_check ,
-.Nm ASN1_TIME_print
+.Nm ASN1_UTCTIME_check ,
+.Nm ASN1_GENERALIZEDTIME_check ,
+.Nm ASN1_TIME_print ,
+.Nm ASN1_UTCTIME_print ,
+.Nm ASN1_GENERALIZEDTIME_print ,
+.Nm ASN1_UTCTIME_cmp_time_t ,
+.Nm ASN1_TIME_to_generalizedtime
 .Nd ASN.1 Time functions
 .Sh SYNOPSIS
 .Ft ASN1_TIME *
@@ -64,6 +78,16 @@
 .Fa "ASN1_TIME *s"
 .Fa "time_t t"
 .Fc
+.Ft ASN1_UTCTIME *
+.Fo ASN1_UTCTIME_set
+.Fa "ASN1_UTCTIME *s"
+.Fa "time_t t"
+.Fc
+.Ft ASN1_GENERALIZEDTIME *
+.Fo ASN1_GENERALIZEDTIME_set
+.Fa "ASN1_GENERALIZEDTIME *s"
+.Fa "time_t t"
+.Fc
 .Ft ASN1_TIME *
 .Fo ASN1_TIME_adj
 .Fa "ASN1_TIME *s"
@@ -71,26 +95,79 @@
 .Fa "int offset_day"
 .Fa "long offset_sec"
 .Fc
+.Ft ASN1_UTCTIME *
+.Fo ASN1_UTCTIME_adj
+.Fa "ASN1_UTCTIME *s"
+.Fa "time_t t"
+.Fa "int offset_day"
+.Fa "long offset_sec"
+.Fc
+.Ft ASN1_GENERALIZEDTIME *
+.Fo ASN1_GENERALIZEDTIME_adj
+.Fa "ASN1_GENERALIZEDTIME *s"
+.Fa "time_t t"
+.Fa "int offset_day"
+.Fa "long offset_sec"
+.Fc
 .Ft int
 .Fo ASN1_TIME_set_string
 .Fa "ASN1_TIME *s"
 .Fa "const char *str"
 .Fc
 .Ft int
+.Fo ASN1_UTCTIME_set_string
+.Fa "ASN1_UTCTIME *s"
+.Fa "const char *str"
+.Fc
+.Ft int
+.Fo ASN1_GENERALIZEDTIME_set_string
+.Fa "ASN1_GENERALIZEDTIME *s"
+.Fa "const char *str"
+.Fc
+.Ft int
 .Fo ASN1_TIME_check
 .Fa "const ASN1_TIME *t"
 .Fc
 .Ft int
+.Fo ASN1_UTCTIME_check
+.Fa "const ASN1_UTCTIME *t"
+.Fc
+.Ft int
+.Fo ASN1_GENERALIZEDTIME_check
+.Fa "const ASN1_GENERALIZEDTIME *t"
+.Fc
+.Ft int
 .Fo ASN1_TIME_print
 .Fa "BIO *b"
 .Fa "const ASN1_TIME *s"
 .Fc
+.Ft int
+.Fo ASN1_UTCTIME_print
+.Fa "BIO *b"
+.Fa "const ASN1_UTCTIME *s"
+.Fc
+.Ft int
+.Fo ASN1_GENERALIZEDTIME_print
+.Fa "BIO *b"
+.Fa "const ASN1_GENERALIZEDTIME *s"
+.Fc
+.Ft int
+.Fo ASN1_UTCTIME_cmp_time_t
+.Fa "const ASN1_UTCTIME *s"
+.Fa "time_t t"
+.Fc
+.Ft ASN1_GENERALIZEDTIME *
+.Fo ASN1_TIME_to_generalizedtime
+.Fa "ASN1_TIME *t"
+.Fa "ASN1_GENERALIZEDTIME **out"
+.Fc
 .Sh DESCRIPTION
-The function
-.Fn ASN1_TIME_set
-sets the
-.Vt ASN1_TIME
-structure
+The functions
+.Fn ASN1_TIME_set ,
+.Fn ASN1_UTCTIME_set ,
+and
+.Fn ASN1_GENERALIZEDTIME_set
+set the time structure
 .Fa s
 to the time represented by the
 .Vt time_t
@@ -100,14 +177,14 @@ If
 .Fa s
 is
 .Dv NULL ,
-a new
-.Vt ASN1_TIME
-structure is allocated and returned.
+a new time structure is allocated and returned.
 .Pp
-.Fn ASN1_TIME_adj
-sets the
-.Vt ASN1_TIME
-structure
+The functions
+.Fn ASN1_TIME_adj ,
+.Fn ASN1_UTCTIME_adj ,
+and
+.Fn ASN1_GENERALIZEDTIME_adj
+set the time structure
 .Fa s
 to the time represented by the time
 .Fa offset_day
@@ -130,28 +207,56 @@ If
 .Fa s
 is
 .Dv NULL ,
-a new
-.Vt ASN1_TIME
-structure is allocated and returned.
+a new time structure is allocated and returned.
 .Pp
-.Fn ASN1_TIME_set_string
-sets the
-.Vt ASN1_TIME
-structure
+.Fn ASN1_TIME_adj
+may change the type from
+.Vt ASN1_GENERALIZEDTIME
+to
+.Vt ASN1_UTCTIME
+or vise-versa depending on the resulting year.
+The functions
+.Fn ASN1_UTCTIME_adj
+and
+.Fn ASN1_GENERALIZEDTIME_adj
+do not modify the type of the return structure.
+.Pp
+The functions
+.Fn ASN1_TIME_set_string ,
+.Fn ASN1_UTCTIME_set_string ,
+and
+.Fn ASN1_GENERALIZEDTIME_set_string
+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).
+The string
+.Fa str
+is copied into
+.Fa s .
+If
+.Fa s
+is
+.Dv NULL ,
+these functions only perform a format check on
+.Fa str .
 .Pp
-.Fn ASN1_TIME_check
-checks the syntax of the
-.Vt ASN1_TIME
-structure
+The functions
+.Fn ASN1_TIME_check ,
+.Fn ASN1_UTCTIME_check ,
+and
+.Fn ASN1_GENERALIZEDTIME_check
+check the syntax of the time structure
 .Fa s .
 .Pp
-.Fn ASN1_TIME_print
-prints out the time
+The functions
+.Fn ASN1_TIME_print ,
+.Fn ASN1_UTCTIME_print ,
+and
+.Fn ASN1_GENERALIZEDTIME_print
+print out the time
 .Fa s
 to
 .Vt BIO
@@ -162,6 +267,32 @@ It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example "Feb 3
 It does not include a newline.
 If the time structure 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_UTCTIME_cmp_time_t
+compares the two times represented by
+.Fa s
+and
+.Fa t .
+.Pp
+The function
+.Fn ASN1_TIME_to_generalizedtime
+converts the
+.Vt ASN1_TIME
+.Fa t
+to an
+.Vt ASN1_GENERALIZEDTIME ,
+regardless of year.
+If either
+.Fa out
+or
+.Pf * Fa out
+is
+.Dv NULL ,
+then a new object is allocated and must be freed after use.
 .Pp
 The
 .Vt ASN1_TIME
@@ -173,10 +304,13 @@ date can be represented by UTCTime it is used, otherwise GeneralizedTime is
 used.
 .Pp
 The
-.Vt ASN1_TIME
-structure is represented as an
+.Vt ASN1_TIME ,
+.Vt ASN1_UTCTIME ,
+and
+.Vt ASN1_GENERALIZEDTIME
+structures are represented as
 .Vt ASN1_STRING
-internally and can be freed up using
+structures internally and can be freed using
 .Xr ASN1_STRING_free 3 .
 .Pp
 The
@@ -184,25 +318,65 @@ The
 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).
-.Sh RETURN VALUES
-.Fn ASN1_TIME_set
+.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
+.Vt ASN1_UTCTIME
+or
+.Vt ASN1_GENERALIZEDTIME
+functions because the
+.Vt ASN1_UTCTIME
 and
-.Fn ASN1_TIME_adj
-return a pointer to an
+.Vt ASN1_GENERALIZEDTIME
+functions act only on that specific time format, while the
 .Vt ASN1_TIME
-structure or
+functions operate on either format.
+.Sh RETURN VALUES
+.Fn ASN1_TIME_set ,
+.Fn ASN1_UTCTIME_set ,
+.Fn ASN1_GENERALIZEDTIME_set ,
+.Fn ASN1_TIME_adj ,
+.Fn ASN1_UTCTIME_adj ,
+.Fn ASN1_GENERALIZEDTIME_adj ,
+and
+.Fn ASN1_TIME_to_generalizedtime
+return a pointer to a time structure or
 .Dv NULL
 if an error occurred.
 .Pp
-.Fn ASN1_TIME_set_string
-returns 1 if the time value is successfully set or 0 otherwise.
+.Fn ASN1_TIME_set_string ,
+.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_check
-returns 1 if the structure is syntactically correct or 0 otherwise.
+.Fn ASN1_TIME_check ,
+.Fn ASN1_UTCTIME_check ,
+and
+.Fn ASN1_GENERALIZEDTIME_check
+return 1 if the time structure is syntactically correct or 0 otherwise.
 .Pp
-.Fn ASN1_TIME_print
-returns 1 if the time is successfully printed out or 0 if an error
+.Fn ASN1_TIME_print ,
+.Fn ASN1_UTCTIME_print ,
+and
+.Fn ASN1_GENERALIZEDTIME_print
+return 1 if the time is successfully printed or 0 if an error
 occurred (I/O error or invalid time format).
+.Pp
+.Fn ASN1_UTCTIME_cmp_time_t
+returns \-1 if
+.Fa s
+is earlier than
+.Fa t ,
+0 if both are equal, 1 if
+.Fa s
+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
 out:
@@ -221,6 +395,9 @@ ASN1_TIME_print(b, tm);
 ASN1_STRING_free(tm);
 BIO_free(b);
 .Ed
+.Sh HISTORY
+.Fn ASN1_TIME_cmp_time_t
+first appeared in OpenSSL 1.1.1.
 .Sh CAVEATS
 Some applications add offset times directly to a
 .Vt time_t
@@ -240,7 +417,9 @@ parameters instead of directly manipulating a
 .Vt time_t
 value.
 .Sh BUGS
-.Fn ASN1_TIME_print
-currently does not print out the time zone: it either prints out "GMT"
-or nothing.
+.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.