| blob | 5fc6edb3db5642c2d069fe0ff0d96656d6d78ccb |
1 .\" $OpenBSD: ASN1_TIME_set.3,v 1.3 2017/08/20 17:16:40 schwarze Exp $
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
4 .\"
5 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>
6 .\" and Todd Short <tshort@akamai.com>.
7 .\" Copyright (c) 2015, 2017 The OpenSSL Project. All rights reserved.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\"
13 .\" 1. Redistributions of source code must retain the above copyright
14 .\" notice, this list of conditions and the following disclaimer.
15 .\"
16 .\" 2. Redistributions in binary form must reproduce the above copyright
17 .\" notice, this list of conditions and the following disclaimer in
18 .\" the documentation and/or other materials provided with the
19 .\" distribution.
20 .\"
21 .\" 3. All advertising materials mentioning features or use of this
22 .\" software must display the following acknowledgment:
23 .\" "This product includes software developed by the OpenSSL Project
24 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
25 .\"
26 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
27 .\" endorse or promote products derived from this software without
28 .\" prior written permission. For written permission, please contact
29 .\" openssl-core@openssl.org.
30 .\"
31 .\" 5. Products derived from this software may not be called "OpenSSL"
32 .\" nor may "OpenSSL" appear in their names without prior written
33 .\" permission of the OpenSSL Project.
34 .\"
35 .\" 6. Redistributions of any form whatsoever must retain the following
36 .\" acknowledgment:
37 .\" "This product includes software developed by the OpenSSL Project
38 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
39 .\"
40 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
41 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
42 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
43 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
44 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
45 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
46 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
47 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
48 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
49 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
50 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
51 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
52 .\"
53 .Dd $Mdocdate: August 20 2017 $
54 .Dt ASN1_TIME_SET 3
55 .Os
56 .Sh NAME
57 .Nm ASN1_TIME_set ,
58 .Nm ASN1_UTCTIME_set ,
59 .Nm ASN1_GENERALIZEDTIME_set ,
60 .Nm ASN1_TIME_adj ,
61 .Nm ASN1_UTCTIME_adj ,
62 .Nm ASN1_GENERALIZEDTIME_adj ,
63 .Nm ASN1_TIME_set_string ,
64 .Nm ASN1_UTCTIME_set_string ,
65 .Nm ASN1_GENERALIZEDTIME_set_string ,
66 .Nm ASN1_TIME_check ,
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
74 .Nd ASN.1 Time functions
75 .Sh SYNOPSIS
76 .Ft ASN1_TIME *
77 .Fo ASN1_TIME_set
78 .Fa "ASN1_TIME *s"
79 .Fa "time_t t"
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
91 .Ft ASN1_TIME *
92 .Fo ASN1_TIME_adj
93 .Fa "ASN1_TIME *s"
94 .Fa "time_t t"
95 .Fa "int offset_day"
96 .Fa "long offset_sec"
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
112 .Ft int
113 .Fo ASN1_TIME_set_string
114 .Fa "ASN1_TIME *s"
115 .Fa "const char *str"
116 .Fc
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
128 .Fo ASN1_TIME_check
129 .Fa "const ASN1_TIME *t"
130 .Fc
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
140 .Fo ASN1_TIME_print
141 .Fa "BIO *b"
142 .Fa "const ASN1_TIME *s"
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
164 .Sh DESCRIPTION
165 The functions
166 .Fn ASN1_TIME_set ,
167 .Fn ASN1_UTCTIME_set ,
168 and
169 .Fn ASN1_GENERALIZEDTIME_set
170 set the time structure
171 .Fa s
172 to the time represented by the
173 .Vt time_t
174 value
175 .Fa t .
176 If
177 .Fa s
178 is
179 .Dv NULL ,
180 a new time structure is allocated and returned.
181 .Pp
182 The functions
183 .Fn ASN1_TIME_adj ,
184 .Fn ASN1_UTCTIME_adj ,
185 and
186 .Fn ASN1_GENERALIZEDTIME_adj
187 set the time structure
188 .Fa s
189 to the time represented by the time
190 .Fa offset_day
191 and
192 .Fa offset_sec
193 after the
194 .Vt time_t
195 value
196 .Fa t .
197 The values of
198 .Fa offset_day
199 or
200 .Fa offset_sec
201 can be negative to set a time before
202 .Fa t .
203 The
204 .Fa offset_sec
205 value can also exceed the number of seconds in a day.
206 If
207 .Fa s
208 is
209 .Dv NULL ,
210 a new time structure is allocated and returned.
211 .Pp
212 .Fn ASN1_TIME_adj
213 may change the type from
214 .Vt ASN1_GENERALIZEDTIME
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
230 .Fa s
231 to the time represented by the string
232 .Fa str ,
233 which must be in appropriate ASN.1 time format (for example
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 .
245 .Pp
246 The functions
247 .Fn ASN1_TIME_check ,
248 .Fn ASN1_UTCTIME_check ,
249 and
250 .Fn ASN1_GENERALIZEDTIME_check
251 check the syntax of the time structure
252 .Fa s .
253 .Pp
254 The functions
255 .Fn ASN1_TIME_print ,
256 .Fn ASN1_UTCTIME_print ,
257 and
258 .Fn ASN1_GENERALIZEDTIME_print
259 print out the time
260 .Fa s
261 to
262 .Vt BIO
263 .Fa b
264 in human readable format.
265 It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example "Feb 3
266 00:55:52 2015 GMT".
267 It does not include a newline.
268 If the time structure has an invalid format,
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.
296 .Pp
297 The
298 .Vt ASN1_TIME
299 structure corresponds to the ASN.1 structure
300 .Sy Time
301 defined in RFC 5280 et al.
302 The time setting functions obey the rules outlined in RFC 5280: if the
303 date can be represented by UTCTime it is used, otherwise GeneralizedTime is
304 used.
305 .Pp
306 The
307 .Vt ASN1_TIME ,
308 .Vt ASN1_UTCTIME ,
309 and
310 .Vt ASN1_GENERALIZEDTIME
311 structures are represented as
312 .Vt ASN1_STRING
313 structures internally and can be freed using
314 .Xr ASN1_STRING_free 3 .
315 .Pp
316 The
317 .Vt ASN1_TIME
318 structure can represent years from 0000 to 9999 but no attempt is
319 made to correct ancient calendar changes (for example from Julian
320 to Gregorian calendars).
321 .Pp
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
333 and
334 .Vt ASN1_GENERALIZEDTIME
335 functions act only on that specific time format, while the
336 .Vt ASN1_TIME
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
348 .Dv NULL
349 if an error occurred.
350 .Pp
351 .Fn ASN1_TIME_set_string ,
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.
356 .Pp
357 .Fn ASN1_TIME_check ,
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.
362 .Pp
363 .Fn ASN1_TIME_print ,
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
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.
380 .Sh EXAMPLES
381 Set a time structure to one hour after the current time and print it
382 out:
383 .Bd -literal -offset indent
384 #include <time.h>
385 #include <openssl/asn1.h>
387 ASN1_TIME *tm;
388 time_t t;
389 BIO *b;
391 t = time(NULL);
392 tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60);
393 b = BIO_new_fp(stdout, BIO_NOCLOSE);
394 ASN1_TIME_print(b, tm);
395 ASN1_STRING_free(tm);
396 BIO_free(b);
397 .Ed
398 .Sh HISTORY
399 .Fn ASN1_TIME_cmp_time_t
400 first appeared in OpenSSL 1.1.1.
401 .Sh CAVEATS
402 Some applications add offset times directly to a
403 .Vt time_t
404 value and pass the results to
405 .Fn ASN1_TIME_set
406 (or equivalent).
407 This can cause problems as the
408 .Vt time_t
409 value can overflow on some systems resulting in unexpected results.
410 New applications should use
411 .Fn ASN1_TIME_adj
412 instead and pass the offset value in the
413 .Fa offset_sec
414 and
415 .Fa offset_day
416 parameters instead of directly manipulating a
417 .Vt time_t
418 value.
419 .Sh BUGS
420 .Fn ASN1_TIME_print ,
421 .Fn ASN1_UTCTIME_print ,
422 and
423 .Fn ASN1_GENERALIZEDTIME_print
424 do not print the time zone: they either print "GMT" or nothing.
425 But all certificates complying with RFC 5280 et al use GMT anyway.