summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/ASN1_TIME_set.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/ASN1_TIME_set.3')
-rw-r--r--src/lib/libcrypto/man/ASN1_TIME_set.3466
1 files changed, 0 insertions, 466 deletions
diff --git a/src/lib/libcrypto/man/ASN1_TIME_set.3 b/src/lib/libcrypto/man/ASN1_TIME_set.3
deleted file mode 100644
index 7aa3009207..0000000000
--- a/src/lib/libcrypto/man/ASN1_TIME_set.3
+++ /dev/null
@@ -1,466 +0,0 @@
1.\" $OpenBSD: ASN1_TIME_set.3,v 1.15 2019/06/06 01:06:58 schwarze Exp $
2.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
3.\" selective merge up to: OpenSSL b0edda11 Mar 20 13:00:17 2018 +0000
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: June 6 2019 $
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.In openssl/asn1.h
77.Ft ASN1_TIME *
78.Fo ASN1_TIME_set
79.Fa "ASN1_TIME *s"
80.Fa "time_t t"
81.Fc
82.Ft ASN1_UTCTIME *
83.Fo ASN1_UTCTIME_set
84.Fa "ASN1_UTCTIME *s"
85.Fa "time_t t"
86.Fc
87.Ft ASN1_GENERALIZEDTIME *
88.Fo ASN1_GENERALIZEDTIME_set
89.Fa "ASN1_GENERALIZEDTIME *s"
90.Fa "time_t t"
91.Fc
92.Ft ASN1_TIME *
93.Fo ASN1_TIME_adj
94.Fa "ASN1_TIME *s"
95.Fa "time_t t"
96.Fa "int offset_day"
97.Fa "long offset_sec"
98.Fc
99.Ft ASN1_UTCTIME *
100.Fo ASN1_UTCTIME_adj
101.Fa "ASN1_UTCTIME *s"
102.Fa "time_t t"
103.Fa "int offset_day"
104.Fa "long offset_sec"
105.Fc
106.Ft ASN1_GENERALIZEDTIME *
107.Fo ASN1_GENERALIZEDTIME_adj
108.Fa "ASN1_GENERALIZEDTIME *s"
109.Fa "time_t t"
110.Fa "int offset_day"
111.Fa "long offset_sec"
112.Fc
113.Ft int
114.Fo ASN1_TIME_set_string
115.Fa "ASN1_TIME *s"
116.Fa "const char *str"
117.Fc
118.Ft int
119.Fo ASN1_UTCTIME_set_string
120.Fa "ASN1_UTCTIME *s"
121.Fa "const char *str"
122.Fc
123.Ft int
124.Fo ASN1_GENERALIZEDTIME_set_string
125.Fa "ASN1_GENERALIZEDTIME *s"
126.Fa "const char *str"
127.Fc
128.Ft int
129.Fo ASN1_TIME_check
130.Fa "const ASN1_TIME *t"
131.Fc
132.Ft int
133.Fo ASN1_UTCTIME_check
134.Fa "const ASN1_UTCTIME *t"
135.Fc
136.Ft int
137.Fo ASN1_GENERALIZEDTIME_check
138.Fa "const ASN1_GENERALIZEDTIME *t"
139.Fc
140.Ft int
141.Fo ASN1_TIME_print
142.Fa "BIO *b"
143.Fa "const ASN1_TIME *s"
144.Fc
145.Ft int
146.Fo ASN1_UTCTIME_print
147.Fa "BIO *b"
148.Fa "const ASN1_UTCTIME *s"
149.Fc
150.Ft int
151.Fo ASN1_GENERALIZEDTIME_print
152.Fa "BIO *b"
153.Fa "const ASN1_GENERALIZEDTIME *s"
154.Fc
155.Ft int
156.Fo ASN1_UTCTIME_cmp_time_t
157.Fa "const ASN1_UTCTIME *s"
158.Fa "time_t t"
159.Fc
160.Ft ASN1_GENERALIZEDTIME *
161.Fo ASN1_TIME_to_generalizedtime
162.Fa "const ASN1_TIME *t"
163.Fa "ASN1_GENERALIZEDTIME **out"
164.Fc
165.Sh DESCRIPTION
166The functions
167.Fn ASN1_TIME_set ,
168.Fn ASN1_UTCTIME_set ,
169and
170.Fn ASN1_GENERALIZEDTIME_set
171set the time structure
172.Fa s
173to the time represented by the
174.Vt time_t
175value
176.Fa t .
177If
178.Fa s
179is
180.Dv NULL ,
181a new time structure is allocated and returned.
182.Pp
183The functions
184.Fn ASN1_TIME_adj ,
185.Fn ASN1_UTCTIME_adj ,
186and
187.Fn ASN1_GENERALIZEDTIME_adj
188set the time structure
189.Fa s
190to the time represented by the time
191.Fa offset_day
192and
193.Fa offset_sec
194after the
195.Vt time_t
196value
197.Fa t .
198The values of
199.Fa offset_day
200or
201.Fa offset_sec
202can be negative to set a time before
203.Fa t .
204The
205.Fa offset_sec
206value can also exceed the number of seconds in a day.
207If
208.Fa s
209is
210.Dv NULL ,
211a new time structure is allocated and returned.
212.Pp
213.Fn ASN1_TIME_adj
214may change the type from
215.Vt ASN1_GENERALIZEDTIME
216to
217.Vt ASN1_UTCTIME
218or vice versa depending on the resulting year.
219The functions
220.Fn ASN1_UTCTIME_adj
221and
222.Fn ASN1_GENERALIZEDTIME_adj
223do not modify the type of the return structure.
224.Pp
225The functions
226.Fn ASN1_TIME_set_string ,
227.Fn ASN1_UTCTIME_set_string ,
228and
229.Fn ASN1_GENERALIZEDTIME_set_string
230set the time structure
231.Fa s
232to the time represented by the string
233.Fa str ,
234which must be in appropriate ASN.1 time format (for example
235YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ).
236The string
237.Fa str
238is copied into
239.Fa s .
240If
241.Fa s
242is
243.Dv NULL ,
244these functions only perform a format check on
245.Fa str .
246.Pp
247The functions
248.Fn ASN1_TIME_check ,
249.Fn ASN1_UTCTIME_check ,
250and
251.Fn ASN1_GENERALIZEDTIME_check
252check the syntax of the time structure
253.Fa s .
254.Pp
255The functions
256.Fn ASN1_TIME_print ,
257.Fn ASN1_UTCTIME_print ,
258and
259.Fn ASN1_GENERALIZEDTIME_print
260print out the time
261.Fa s
262to
263.Vt BIO
264.Fa b
265in human readable format.
266It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example "Feb 3
26700:55:52 2015 GMT".
268It does not include a newline.
269If the time structure has an invalid format,
270it prints out "Bad time value" and returns an error.
271The output of
272.Fn ASN1_GENERALIZEDTIME_print
273may include a fractional part following the second.
274.Pp
275The function
276.Fn ASN1_UTCTIME_cmp_time_t
277compares the two times represented by
278.Fa s
279and
280.Fa t .
281.Pp
282The function
283.Fn ASN1_TIME_to_generalizedtime
284converts the
285.Vt ASN1_TIME
286.Fa t
287to an
288.Vt ASN1_GENERALIZEDTIME ,
289regardless of year.
290If either
291.Fa out
292or
293.Pf * Fa out
294is
295.Dv NULL ,
296then a new object is allocated and must be freed after use.
297.Pp
298The
299.Vt ASN1_TIME
300structure corresponds to the ASN.1 structure
301.Sy Time
302defined in RFC 5280 et al.
303The time setting functions obey the rules outlined in RFC 5280: if the
304date can be represented by UTCTime it is used, otherwise GeneralizedTime is
305used.
306.Pp
307The
308.Vt ASN1_TIME ,
309.Vt ASN1_UTCTIME ,
310and
311.Vt ASN1_GENERALIZEDTIME
312structures are represented as
313.Vt ASN1_STRING
314structures internally and can be freed using
315.Xr ASN1_STRING_free 3 .
316.Pp
317The
318.Vt ASN1_TIME
319structure can represent years from 0000 to 9999 but no attempt is
320made to correct ancient calendar changes (for example from Julian
321to Gregorian calendars).
322.Pp
323.Vt ASN1_UTCTIME
324is limited to a year range of 1950 through 2049.
325.Pp
326It is recommended that
327.Vt ASN1_TIME
328functions be used instead of
329.Vt ASN1_UTCTIME
330or
331.Vt ASN1_GENERALIZEDTIME
332functions because the
333.Vt ASN1_UTCTIME
334and
335.Vt ASN1_GENERALIZEDTIME
336functions act only on that specific time format, while the
337.Vt ASN1_TIME
338functions operate on either format.
339.Sh RETURN VALUES
340.Fn ASN1_TIME_set ,
341.Fn ASN1_UTCTIME_set ,
342.Fn ASN1_GENERALIZEDTIME_set ,
343.Fn ASN1_TIME_adj ,
344.Fn ASN1_UTCTIME_adj ,
345.Fn ASN1_GENERALIZEDTIME_adj ,
346and
347.Fn ASN1_TIME_to_generalizedtime
348return a pointer to a time structure or
349.Dv NULL
350if an error occurred.
351.Pp
352.Fn ASN1_TIME_set_string ,
353.Fn ASN1_UTCTIME_set_string ,
354and
355.Fn ASN1_GENERALIZEDTIME_set_string
356return 1 if the time value is successfully set or 0 otherwise.
357.Pp
358.Fn ASN1_TIME_check ,
359.Fn ASN1_UTCTIME_check ,
360and
361.Fn ASN1_GENERALIZEDTIME_check
362return 1 if the time structure is syntactically correct or 0 otherwise.
363.Pp
364.Fn ASN1_TIME_print ,
365.Fn ASN1_UTCTIME_print ,
366and
367.Fn ASN1_GENERALIZEDTIME_print
368return 1 if the time is successfully printed or 0 if an error
369occurred (I/O error or invalid time format).
370.Pp
371.Fn ASN1_UTCTIME_cmp_time_t
372returns \-1 if
373.Fa s
374is earlier than
375.Fa t ,
3760 if both are equal, 1 if
377.Fa s
378is later than
379.Fa t ,
380or \-2 on error.
381.Sh EXAMPLES
382Set a time structure to one hour after the current time and print it
383out:
384.Bd -literal -offset indent
385#include <time.h>
386#include <openssl/asn1.h>
387
388ASN1_TIME *tm;
389time_t t;
390BIO *b;
391
392t = time(NULL);
393tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60);
394b = BIO_new_fp(stdout, BIO_NOCLOSE);
395ASN1_TIME_print(b, tm);
396ASN1_STRING_free(tm);
397BIO_free(b);
398.Ed
399.Sh SEE ALSO
400.Xr ASN1_TIME_new 3 ,
401.Xr ASN1_time_parse 3 ,
402.Xr X509_cmp_time 3
403.Sh HISTORY
404.Fn ASN1_UTCTIME_check
405and
406.Fn ASN1_UTCTIME_print
407first appeared in SSLeay 0.5.1.
408.Fn ASN1_UTCTIME_set
409first appeared in SSLeay 0.6.0.
410.Fn ASN1_UTCTIME_set_string
411first appeared in SSLeay 0.9.0.
412All these functions have been available since
413.Ox 2.4 .
414.Pp
415.Fn ASN1_TIME_set ,
416.Fn ASN1_GENERALIZEDTIME_set ,
417.Fn ASN1_GENERALIZEDTIME_set_string ,
418.Fn ASN1_GENERALIZEDTIME_check ,
419.Fn ASN1_TIME_print ,
420and
421.Fn ASN1_GENERALIZEDTIME_print
422first appeared in OpenSSL 0.9.2b and have been available since
423.Ox 2.6 .
424.Pp
425.Fn ASN1_UTCTIME_cmp_time_t
426first appeared in OpenSSL 0.9.6 and has been available since
427.Ox 2.9 .
428.Pp
429.Fn ASN1_TIME_check
430and
431.Fn ASN1_TIME_to_generalizedtime
432first appeared in OpenSSL 0.9.7 and have been available since
433.Ox 3.2 .
434.Pp
435.Fn ASN1_TIME_adj ,
436.Fn ASN1_UTCTIME_adj ,
437.Fn ASN1_GENERALIZEDTIME_adj ,
438and
439.Fn ASN1_TIME_set_string
440first appeared in OpenSSL 1.0.0 and have been available since
441.Ox 4.9 .
442.Sh CAVEATS
443Some applications add offset times directly to a
444.Vt time_t
445value and pass the results to
446.Fn ASN1_TIME_set
447(or equivalent).
448This can cause problems as the
449.Vt time_t
450value can overflow on some systems resulting in unexpected results.
451New applications should use
452.Fn ASN1_TIME_adj
453instead and pass the offset value in the
454.Fa offset_sec
455and
456.Fa offset_day
457parameters instead of directly manipulating a
458.Vt time_t
459value.
460.Sh BUGS
461.Fn ASN1_TIME_print ,
462.Fn ASN1_UTCTIME_print ,
463and
464.Fn ASN1_GENERALIZEDTIME_print
465do not print the time zone: they either print "GMT" or nothing.
466But all certificates complying with RFC 5280 et al use GMT anyway.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-02-14 08:47:26 +0000