Sync with OpenSSL: document several new functions, plus some additional

minor improvements. Mostly from Todd Short <tshort at akamai dot com> via OpenSSL commit cf37aaa3 Aug 4 11:24:03 2017 +1000.
author: schwarze <> 2017-08-20 17:16:40 +0000
committer: schwarze <> 2017-08-20 17:16:40 +0000
commit: d531af76dfc13a2772c8ce8d4017ff9a84b02dcc (patch)
tree: 2843b7b8b38c5c7d0ade99773a0f4b6b93b81b90
parent: f4e6aef61d0a10511f864f6d7fe108870a647703 (diff)
download: openbsd-d531af76dfc13a2772c8ce8d4017ff9a84b02dcc.tar.gz
openbsd-d531af76dfc13a2772c8ce8d4017ff9a84b02dcc.tar.bz2
openbsd-d531af76dfc13a2772c8ce8d4017ff9a84b02dcc.zip
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 $
+.\"     $OpenBSD: ASN1_TIME_set.3,v 1.3 2017/08/20 17:16:40 schwarze Exp $
-.\"     OpenSSL 99d63d46 Mon Jun 6 00:43:05 2016 -0400
+.\"     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.
+.\" This file was written by Dr. Stephen Henson <steve@openssl.org>
-.\" Copyright (c) 2015 The OpenSSL Project.  All rights reserved.
+.\" 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
+The functions
-.Fn ASN1_TIME_set
+.Fn ASN1_TIME_set ,
-sets the
+.Fn ASN1_UTCTIME_set ,
-.Vt ASN1_TIME
+and
-structure
+.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
+a new time structure is allocated and returned.
-.Vt ASN1_TIME
-structure is allocated and returned.
 .Pp
-.Fn ASN1_TIME_adj
+The functions
-sets the
+.Fn ASN1_TIME_adj ,
-.Vt ASN1_TIME
+.Fn ASN1_UTCTIME_adj ,
-structure
+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
+a new time structure is allocated and returned.
-.Vt ASN1_TIME
-structure is allocated and returned.
 .Pp
-.Fn ASN1_TIME_set_string
+.Fn ASN1_TIME_adj
-sets the
+may change the type from
-.Vt ASN1_TIME
+.Vt ASN1_GENERALIZEDTIME
-structure
+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
+The functions
-checks the syntax of the
+.Fn ASN1_TIME_check ,
-.Vt ASN1_TIME
+.Fn ASN1_UTCTIME_check ,
-structure
+and
+.Fn ASN1_GENERALIZEDTIME_check
+check the syntax of the time structure
 .Fa s .
 .Pp
-.Fn ASN1_TIME_print
+The functions
-prints out the time
+.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
+.Vt ASN1_TIME ,
-structure is represented as an
+.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
+.Pp
-.Fn ASN1_TIME_set
+.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
+.Vt ASN1_GENERALIZEDTIME
-return a pointer to an
+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
+.Fn ASN1_TIME_set_string ,
-returns 1 if the time value is successfully set or 0 otherwise.
+.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
+.Fn ASN1_TIME_check ,
-returns 1 if the structure is syntactically correct or 0 otherwise.
+.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
+.Fn ASN1_TIME_print ,
-returns 1 if the time is successfully printed out or 0 if an error
+.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
+.Fn ASN1_TIME_print ,
-currently does not print out the time zone: it either prints out "GMT"
+.Fn ASN1_UTCTIME_print ,
-or nothing.
+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.
author	schwarze <>	2017-08-20 17:16:40 +0000
committer	schwarze <>	2017-08-20 17:16:40 +0000
commit	d531af76dfc13a2772c8ce8d4017ff9a84b02dcc (patch)
tree	2843b7b8b38c5c7d0ade99773a0f4b6b93b81b90
parent	f4e6aef61d0a10511f864f6d7fe108870a647703 (diff)
download	openbsd-d531af76dfc13a2772c8ce8d4017ff9a84b02dcc.tar.gz openbsd-d531af76dfc13a2772c8ce8d4017ff9a84b02dcc.tar.bz2 openbsd-d531af76dfc13a2772c8ce8d4017ff9a84b02dcc.zip

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 @@
1	.\" $OpenBSD: ASN1_TIME_set.3,v 1.2 2016/11/10 15:08:13 jmc Exp $	1	.\" $OpenBSD: ASN1_TIME_set.3,v 1.3 2017/08/20 17:16:40 schwarze Exp $
2	.\" OpenSSL 99d63d46 Mon Jun 6 00:43:05 2016 -0400	2	.\" OpenSSL ASN1_TIME_set.pod cf37aaa3 Aug 4 11:24:03 2017 +1000
		3	.\" OpenSSL ASN1_TIME_set.pod e9b77246 Jan 20 19:58:49 2017 +0100
3	.\"	4	.\"
4	.\" This file was written by Dr. Stephen Henson.	5	.\" This file was written by Dr. Stephen Henson <steve@openssl.org>
5	.\" Copyright (c) 2015 The OpenSSL Project. All rights reserved.	6	.\" and Todd Short <tshort@akamai.com>.
		7	.\" Copyright (c) 2015, 2017 The OpenSSL Project. All rights reserved.
6	.\"	8	.\"
7	.\" Redistribution and use in source and binary forms, with or without	9	.\" Redistribution and use in source and binary forms, with or without
8	.\" modification, are permitted provided that the following conditions	10	.\" modification, are permitted provided that the following conditions
@@ -48,15 +50,27 @@
48	.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED	50	.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49	.\" OF THE POSSIBILITY OF SUCH DAMAGE.	51	.\" OF THE POSSIBILITY OF SUCH DAMAGE.
50	.\"	52	.\"
51	.Dd $Mdocdate: November 10 2016 $	53	.Dd $Mdocdate: August 20 2017 $
52	.Dt ASN1_TIME_SET 3	54	.Dt ASN1_TIME_SET 3
53	.Os	55	.Os
54	.Sh NAME	56	.Sh NAME
55	.Nm ASN1_TIME_set ,	57	.Nm ASN1_TIME_set ,
		58	.Nm ASN1_UTCTIME_set ,
		59	.Nm ASN1_GENERALIZEDTIME_set ,
56	.Nm ASN1_TIME_adj ,	60	.Nm ASN1_TIME_adj ,
		61	.Nm ASN1_UTCTIME_adj ,
		62	.Nm ASN1_GENERALIZEDTIME_adj ,
57	.Nm ASN1_TIME_set_string ,	63	.Nm ASN1_TIME_set_string ,
		64	.Nm ASN1_UTCTIME_set_string ,
		65	.Nm ASN1_GENERALIZEDTIME_set_string ,
58	.Nm ASN1_TIME_check ,	66	.Nm ASN1_TIME_check ,
59	.Nm ASN1_TIME_print	67	.Nm ASN1_UTCTIME_check ,
		68	.Nm ASN1_GENERALIZEDTIME_check ,
		69	.Nm ASN1_TIME_print ,
		70	.Nm ASN1_UTCTIME_print ,
		71	.Nm ASN1_GENERALIZEDTIME_print ,
		72	.Nm ASN1_UTCTIME_cmp_time_t ,
		73	.Nm ASN1_TIME_to_generalizedtime
60	.Nd ASN.1 Time functions	74	.Nd ASN.1 Time functions
61	.Sh SYNOPSIS	75	.Sh SYNOPSIS
62	.Ft ASN1_TIME *	76	.Ft ASN1_TIME *
@@ -64,6 +78,16 @@
64	.Fa "ASN1_TIME *s"	78	.Fa "ASN1_TIME *s"
65	.Fa "time_t t"	79	.Fa "time_t t"
66	.Fc	80	.Fc
		81	.Ft ASN1_UTCTIME *
		82	.Fo ASN1_UTCTIME_set
		83	.Fa "ASN1_UTCTIME *s"
		84	.Fa "time_t t"
		85	.Fc
		86	.Ft ASN1_GENERALIZEDTIME *
		87	.Fo ASN1_GENERALIZEDTIME_set
		88	.Fa "ASN1_GENERALIZEDTIME *s"
		89	.Fa "time_t t"
		90	.Fc
67	.Ft ASN1_TIME *	91	.Ft ASN1_TIME *
68	.Fo ASN1_TIME_adj	92	.Fo ASN1_TIME_adj
69	.Fa "ASN1_TIME *s"	93	.Fa "ASN1_TIME *s"
@@ -71,26 +95,79 @@
71	.Fa "int offset_day"	95	.Fa "int offset_day"
72	.Fa "long offset_sec"	96	.Fa "long offset_sec"
73	.Fc	97	.Fc
		98	.Ft ASN1_UTCTIME *
		99	.Fo ASN1_UTCTIME_adj
		100	.Fa "ASN1_UTCTIME *s"
		101	.Fa "time_t t"
		102	.Fa "int offset_day"
		103	.Fa "long offset_sec"
		104	.Fc
		105	.Ft ASN1_GENERALIZEDTIME *
		106	.Fo ASN1_GENERALIZEDTIME_adj
		107	.Fa "ASN1_GENERALIZEDTIME *s"
		108	.Fa "time_t t"
		109	.Fa "int offset_day"
		110	.Fa "long offset_sec"
		111	.Fc
74	.Ft int	112	.Ft int
75	.Fo ASN1_TIME_set_string	113	.Fo ASN1_TIME_set_string
76	.Fa "ASN1_TIME *s"	114	.Fa "ASN1_TIME *s"
77	.Fa "const char *str"	115	.Fa "const char *str"
78	.Fc	116	.Fc
79	.Ft int	117	.Ft int
		118	.Fo ASN1_UTCTIME_set_string
		119	.Fa "ASN1_UTCTIME *s"
		120	.Fa "const char *str"
		121	.Fc
		122	.Ft int
		123	.Fo ASN1_GENERALIZEDTIME_set_string
		124	.Fa "ASN1_GENERALIZEDTIME *s"
		125	.Fa "const char *str"
		126	.Fc
		127	.Ft int
80	.Fo ASN1_TIME_check	128	.Fo ASN1_TIME_check
81	.Fa "const ASN1_TIME *t"	129	.Fa "const ASN1_TIME *t"
82	.Fc	130	.Fc
83	.Ft int	131	.Ft int
		132	.Fo ASN1_UTCTIME_check
		133	.Fa "const ASN1_UTCTIME *t"
		134	.Fc
		135	.Ft int
		136	.Fo ASN1_GENERALIZEDTIME_check
		137	.Fa "const ASN1_GENERALIZEDTIME *t"
		138	.Fc
		139	.Ft int
84	.Fo ASN1_TIME_print	140	.Fo ASN1_TIME_print
85	.Fa "BIO *b"	141	.Fa "BIO *b"
86	.Fa "const ASN1_TIME *s"	142	.Fa "const ASN1_TIME *s"
87	.Fc	143	.Fc
		144	.Ft int
		145	.Fo ASN1_UTCTIME_print
		146	.Fa "BIO *b"
		147	.Fa "const ASN1_UTCTIME *s"
		148	.Fc
		149	.Ft int
		150	.Fo ASN1_GENERALIZEDTIME_print
		151	.Fa "BIO *b"
		152	.Fa "const ASN1_GENERALIZEDTIME *s"
		153	.Fc
		154	.Ft int
		155	.Fo ASN1_UTCTIME_cmp_time_t
		156	.Fa "const ASN1_UTCTIME *s"
		157	.Fa "time_t t"
		158	.Fc
		159	.Ft ASN1_GENERALIZEDTIME *
		160	.Fo ASN1_TIME_to_generalizedtime
		161	.Fa "ASN1_TIME *t"
		162	.Fa "ASN1_GENERALIZEDTIME **out"
		163	.Fc
88	.Sh DESCRIPTION	164	.Sh DESCRIPTION
89	The function	165	The functions
90	.Fn ASN1_TIME_set	166	.Fn ASN1_TIME_set ,
91	sets the	167	.Fn ASN1_UTCTIME_set ,
92	.Vt ASN1_TIME	168	and
93	structure	169	.Fn ASN1_GENERALIZEDTIME_set
		170	set the time structure
94	.Fa s	171	.Fa s
95	to the time represented by the	172	to the time represented by the
96	.Vt time_t	173	.Vt time_t
@@ -100,14 +177,14 @@ If
100	.Fa s	177	.Fa s
101	is	178	is
102	.Dv NULL ,	179	.Dv NULL ,
103	a new	180	a new time structure is allocated and returned.
104	.Vt ASN1_TIME
105	structure is allocated and returned.
106	.Pp	181	.Pp
107	.Fn ASN1_TIME_adj	182	The functions
108	sets the	183	.Fn ASN1_TIME_adj ,
109	.Vt ASN1_TIME	184	.Fn ASN1_UTCTIME_adj ,
110	structure	185	and
		186	.Fn ASN1_GENERALIZEDTIME_adj
		187	set the time structure
111	.Fa s	188	.Fa s
112	to the time represented by the time	189	to the time represented by the time
113	.Fa offset_day	190	.Fa offset_day
@@ -130,28 +207,56 @@ If
130	.Fa s	207	.Fa s
131	is	208	is
132	.Dv NULL ,	209	.Dv NULL ,
133	a new	210	a new time structure is allocated and returned.
134	.Vt ASN1_TIME
135	structure is allocated and returned.
136	.Pp	211	.Pp
137	.Fn ASN1_TIME_set_string	212	.Fn ASN1_TIME_adj
138	sets the	213	may change the type from
139	.Vt ASN1_TIME	214	.Vt ASN1_GENERALIZEDTIME
140	structure	215	to
		216	.Vt ASN1_UTCTIME
		217	or vise-versa depending on the resulting year.
		218	The functions
		219	.Fn ASN1_UTCTIME_adj
		220	and
		221	.Fn ASN1_GENERALIZEDTIME_adj
		222	do not modify the type of the return structure.
		223	.Pp
		224	The functions
		225	.Fn ASN1_TIME_set_string ,
		226	.Fn ASN1_UTCTIME_set_string ,
		227	and
		228	.Fn ASN1_GENERALIZEDTIME_set_string
		229	set the time structure
141	.Fa s	230	.Fa s
142	to the time represented by the string	231	to the time represented by the string
143	.Fa str ,	232	.Fa str ,
144	which must be in appropriate ASN.1 time format (for example	233	which must be in appropriate ASN.1 time format (for example
145	YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ).	234	YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ).
		235	The string
		236	.Fa str
		237	is copied into
		238	.Fa s .
		239	If
		240	.Fa s
		241	is
		242	.Dv NULL ,
		243	these functions only perform a format check on
		244	.Fa str .
146	.Pp	245	.Pp
147	.Fn ASN1_TIME_check	246	The functions
148	checks the syntax of the	247	.Fn ASN1_TIME_check ,
149	.Vt ASN1_TIME	248	.Fn ASN1_UTCTIME_check ,
150	structure	249	and
		250	.Fn ASN1_GENERALIZEDTIME_check
		251	check the syntax of the time structure
151	.Fa s .	252	.Fa s .
152	.Pp	253	.Pp
153	.Fn ASN1_TIME_print	254	The functions
154	prints out the time	255	.Fn ASN1_TIME_print ,
		256	.Fn ASN1_UTCTIME_print ,
		257	and
		258	.Fn ASN1_GENERALIZEDTIME_print
		259	print out the time
155	.Fa s	260	.Fa s
156	to	261	to
157	.Vt BIO	262	.Vt BIO
@@ -162,6 +267,32 @@ It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example "Feb 3
162	It does not include a newline.	267	It does not include a newline.
163	If the time structure has an invalid format,	268	If the time structure has an invalid format,
164	it prints out "Bad time value" and returns an error.	269	it prints out "Bad time value" and returns an error.
		270	The output of
		271	.Fn ASN1_GENERALIZEDTIME_print
		272	may include a fractional part following the second.
		273	.Pp
		274	The function
		275	.Fn ASN1_UTCTIME_cmp_time_t
		276	compares the two times represented by
		277	.Fa s
		278	and
		279	.Fa t .
		280	.Pp
		281	The function
		282	.Fn ASN1_TIME_to_generalizedtime
		283	converts the
		284	.Vt ASN1_TIME
		285	.Fa t
		286	to an
		287	.Vt ASN1_GENERALIZEDTIME ,
		288	regardless of year.
		289	If either
		290	.Fa out
		291	or
		292	.Pf * Fa out
		293	is
		294	.Dv NULL ,
		295	then a new object is allocated and must be freed after use.
165	.Pp	296	.Pp
166	The	297	The
167	.Vt ASN1_TIME	298	.Vt ASN1_TIME
@@ -173,10 +304,13 @@ date can be represented by UTCTime it is used, otherwise GeneralizedTime is
173	used.	304	used.
174	.Pp	305	.Pp
175	The	306	The
176	.Vt ASN1_TIME	307	.Vt ASN1_TIME ,
177	structure is represented as an	308	.Vt ASN1_UTCTIME ,
		309	and
		310	.Vt ASN1_GENERALIZEDTIME
		311	structures are represented as
178	.Vt ASN1_STRING	312	.Vt ASN1_STRING
179	internally and can be freed up using	313	structures internally and can be freed using
180	.Xr ASN1_STRING_free 3 .	314	.Xr ASN1_STRING_free 3 .
181	.Pp	315	.Pp
182	The	316	The
@@ -184,25 +318,65 @@ The
184	structure can represent years from 0000 to 9999 but no attempt is	318	structure can represent years from 0000 to 9999 but no attempt is
185	made to correct ancient calendar changes (for example from Julian	319	made to correct ancient calendar changes (for example from Julian
186	to Gregorian calendars).	320	to Gregorian calendars).
187	.Sh RETURN VALUES	321	.Pp
188	.Fn ASN1_TIME_set	322	.Vt ASN1_UTCTIME
		323	is limited to a year range of 1950 through 2049.
		324	.Pp
		325	It is recommended that
		326	.Vt ASN1_TIME
		327	functions be used instead of
		328	.Vt ASN1_UTCTIME
		329	or
		330	.Vt ASN1_GENERALIZEDTIME
		331	functions because the
		332	.Vt ASN1_UTCTIME
189	and	333	and
190	.Fn ASN1_TIME_adj	334	.Vt ASN1_GENERALIZEDTIME
191	return a pointer to an	335	functions act only on that specific time format, while the
192	.Vt ASN1_TIME	336	.Vt ASN1_TIME
193	structure or	337	functions operate on either format.
		338	.Sh RETURN VALUES
		339	.Fn ASN1_TIME_set ,
		340	.Fn ASN1_UTCTIME_set ,
		341	.Fn ASN1_GENERALIZEDTIME_set ,
		342	.Fn ASN1_TIME_adj ,
		343	.Fn ASN1_UTCTIME_adj ,
		344	.Fn ASN1_GENERALIZEDTIME_adj ,
		345	and
		346	.Fn ASN1_TIME_to_generalizedtime
		347	return a pointer to a time structure or
194	.Dv NULL	348	.Dv NULL
195	if an error occurred.	349	if an error occurred.
196	.Pp	350	.Pp
197	.Fn ASN1_TIME_set_string	351	.Fn ASN1_TIME_set_string ,
198	returns 1 if the time value is successfully set or 0 otherwise.	352	.Fn ASN1_UTCTIME_set_string ,
		353	and
		354	.Fn ASN1_GENERALIZEDTIME_set_string
		355	return 1 if the time value is successfully set or 0 otherwise.
199	.Pp	356	.Pp
200	.Fn ASN1_TIME_check	357	.Fn ASN1_TIME_check ,
201	returns 1 if the structure is syntactically correct or 0 otherwise.	358	.Fn ASN1_UTCTIME_check ,
		359	and
		360	.Fn ASN1_GENERALIZEDTIME_check
		361	return 1 if the time structure is syntactically correct or 0 otherwise.
202	.Pp	362	.Pp
203	.Fn ASN1_TIME_print	363	.Fn ASN1_TIME_print ,
204	returns 1 if the time is successfully printed out or 0 if an error	364	.Fn ASN1_UTCTIME_print ,
		365	and
		366	.Fn ASN1_GENERALIZEDTIME_print
		367	return 1 if the time is successfully printed or 0 if an error
205	occurred (I/O error or invalid time format).	368	occurred (I/O error or invalid time format).
		369	.Pp
		370	.Fn ASN1_UTCTIME_cmp_time_t
		371	returns \-1 if
		372	.Fa s
		373	is earlier than
		374	.Fa t ,
		375	0 if both are equal, 1 if
		376	.Fa s
		377	is later than
		378	.Fa t ,
		379	or \-2 on error.
206	.Sh EXAMPLES	380	.Sh EXAMPLES
207	Set a time structure to one hour after the current time and print it	381	Set a time structure to one hour after the current time and print it
208	out:	382	out:
@@ -221,6 +395,9 @@ ASN1_TIME_print(b, tm);
221	ASN1_STRING_free(tm);	395	ASN1_STRING_free(tm);
222	BIO_free(b);	396	BIO_free(b);
223	.Ed	397	.Ed
		398	.Sh HISTORY
		399	.Fn ASN1_TIME_cmp_time_t
		400	first appeared in OpenSSL 1.1.1.
224	.Sh CAVEATS	401	.Sh CAVEATS
225	Some applications add offset times directly to a	402	Some applications add offset times directly to a
226	.Vt time_t	403	.Vt time_t
@@ -240,7 +417,9 @@ parameters instead of directly manipulating a
240	.Vt time_t	417	.Vt time_t
241	value.	418	value.
242	.Sh BUGS	419	.Sh BUGS
243	.Fn ASN1_TIME_print	420	.Fn ASN1_TIME_print ,
244	currently does not print out the time zone: it either prints out "GMT"	421	.Fn ASN1_UTCTIME_print ,
245	or nothing.	422	and
		423	.Fn ASN1_GENERALIZEDTIME_print
		424	do not print the time zone: they either print "GMT" or nothing.
246	But all certificates complying with RFC 5280 et al use GMT anyway.	425	But all certificates complying with RFC 5280 et al use GMT anyway.