]>
Commit | Line | Data |
---|---|---|
a724e79e DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
cf37aaa3 TS |
5 | ASN1_TIME_set, ASN1_UTCTIME_set, ASN1_GENERALIZEDTIME_set, |
6 | ASN1_TIME_adj, ASN1_UTCTIME_adj, ASN1_GENERALIZEDTIME_adj, | |
7 | ASN1_TIME_check, ASN1_UTCTIME_check, ASN1_GENERALIZEDTIME_check, | |
8 | ASN1_TIME_set_string, ASN1_UTCTIME_set_string, ASN1_GENERALIZEDTIME_set_string, | |
9 | ASN1_TIME_set_string_X509, | |
10 | ASN1_TIME_normalize, | |
11 | ASN1_TIME_to_tm, | |
12 | ASN1_TIME_print, ASN1_UTCTIME_print, ASN1_GENERALIZEDTIME_print, | |
13 | ASN1_TIME_diff, | |
14 | ASN1_TIME_cmp_time_t, ASN1_UTCTIME_cmp_time_t, | |
15 | ASN1_TIME_compare, | |
16 | ASN1_TIME_to_generalizedtime - ASN.1 Time functions | |
a724e79e DSH |
17 | |
18 | =head1 SYNOPSIS | |
19 | ||
20 | ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t t); | |
cf37aaa3 TS |
21 | ASN1_UTCTIME *ASN1_UTCTIME_set(ASN1_UTCTIME *s, time_t t); |
22 | ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_set(ASN1_GENERALIZEDTIME *s, | |
23 | time_t t); | |
24 | ||
25 | ASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t, int offset_day, | |
26 | long offset_sec); | |
27 | ASN1_UTCTIME *ASN1_UTCTIME_adj(ASN1_UTCTIME *s, time_t t, | |
28 | int offset_day, long offset_sec); | |
29 | ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_adj(ASN1_GENERALIZEDTIME *s, | |
30 | time_t t, int offset_day, | |
31 | long offset_sec); | |
32 | ||
a724e79e | 33 | int ASN1_TIME_set_string(ASN1_TIME *s, const char *str); |
04e62715 | 34 | int ASN1_TIME_set_string_X509(ASN1_TIME *s, const char *str); |
cf37aaa3 TS |
35 | int ASN1_UTCTIME_set_string(ASN1_UTCTIME *s, const char *str); |
36 | int ASN1_GENERALIZEDTIME_set_string(ASN1_GENERALIZEDTIME *s, | |
37 | const char *str); | |
38 | ||
39 | int ASN1_TIME_normalize(ASN1_TIME *s); | |
40 | ||
a724e79e | 41 | int ASN1_TIME_check(const ASN1_TIME *t); |
cf37aaa3 TS |
42 | int ASN1_UTCTIME_check(const ASN1_UTCTIME *t); |
43 | int ASN1_GENERALIZEDTIME_check(const ASN1_GENERALIZEDTIME *t); | |
44 | ||
a724e79e | 45 | int ASN1_TIME_print(BIO *b, const ASN1_TIME *s); |
cf37aaa3 TS |
46 | int ASN1_UTCTIME_print(BIO *b, const ASN1_UTCTIME *s); |
47 | int ASN1_GENERALIZEDTIME_print(BIO *b, const ASN1_GENERALIZEDTIME *s); | |
48 | ||
1c036c64 | 49 | int ASN1_TIME_to_tm(const ASN1_TIME *s, struct tm *tm); |
cf37aaa3 TS |
50 | int ASN1_TIME_diff(int *pday, int *psec, const ASN1_TIME *from, |
51 | const ASN1_TIME *to); | |
a724e79e | 52 | |
cf37aaa3 TS |
53 | int ASN1_TIME_cmp_time_t(const ASN1_TIME *s, time_t t); |
54 | int ASN1_UTCTIME_cmp_time_t(const ASN1_UTCTIME *s, time_t t); | |
55 | ||
56 | int ASN1_TIME_compare(const ASN1_TIME *a, const ASN1_TIME *b); | |
57 | ||
58 | ASN1_GENERALIZEDTIME *ASN1_TIME_to_generalizedtime(ASN1_TIME *t, | |
59 | ASN1_GENERALIZEDTIME **out); | |
a724e79e DSH |
60 | |
61 | =head1 DESCRIPTION | |
62 | ||
cf37aaa3 TS |
63 | The ASN1_TIME_set(), ASN1_UTCTIME_set() and ASN1_GENERALIZEDTIME_set() |
64 | functions set the structure B<s> to the time represented by the time_t | |
65 | value B<t>. If B<s> is NULL a new time structure is allocated and returned. | |
a724e79e | 66 | |
cf37aaa3 TS |
67 | The ASN1_TIME_adj(), ASN1_UTCTIME_adj() and ASN1_GENERALIZEDTIME_adj() |
68 | functions set the time structure B<s> to the time represented | |
a724e79e DSH |
69 | by the time B<offset_day> and B<offset_sec> after the time_t value B<t>. |
70 | The values of B<offset_day> or B<offset_sec> can be negative to set a | |
71 | time before B<t>. The B<offset_sec> value can also exceed the number of | |
cf37aaa3 | 72 | seconds in a day. If B<s> is NULL a new structure is allocated |
a724e79e DSH |
73 | and returned. |
74 | ||
cf37aaa3 TS |
75 | The ASN1_TIME_set_string(), ASN1_UTCTIME_set_string() and |
76 | ASN1_GENERALIZEDTIME_set_string() functions set the time structure B<s> | |
77 | to the time represented by string B<str> which must be in appropriate ASN.1 | |
78 | time format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). If B<s> is NULL | |
79 | this function performs a format check on B<str> only. The string B<str> | |
80 | is copied into B<s>. | |
04e62715 RS |
81 | |
82 | ASN1_TIME_set_string_X509() sets ASN1_TIME structure B<s> to the time | |
83 | represented by string B<str> which must be in appropriate time format | |
84 | that RFC 5280 requires, which means it only allows YYMMDDHHMMSSZ and | |
85 | YYYYMMDDHHMMSSZ (leap second is rejected), all other ASN.1 time format | |
86 | are not allowed. If B<s> is NULL this function performs a format check | |
87 | on B<str> only. | |
a724e79e | 88 | |
cf37aaa3 TS |
89 | The ASN1_TIME_normalize() function converts an ASN1_GENERALIZEDTIME or |
90 | ASN1_UTCTIME into a time value that can be used in a certificate. It | |
91 | should be used after the ASN1_TIME_set_string() functions and before | |
92 | ASN1_TIME_print() functions to get consistent (i.e. GMT) results. | |
93 | ||
94 | The ASN1_TIME_check(), ASN1_UTCTIME_check() and ASN1_GENERALIZEDTIME_check() | |
95 | functions check the syntax of the time structure B<s>. | |
a724e79e | 96 | |
cf37aaa3 TS |
97 | The ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() |
98 | functions print the time structure B<s> to BIO B<b> in human readable | |
a724e79e DSH |
99 | format. It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example |
100 | "Feb 3 00:55:52 2015 GMT" it does not include a newline. If the time | |
101 | structure has invalid format it prints out "Bad time value" and returns | |
cf37aaa3 TS |
102 | an error. The output for generalized time may include a fractional part |
103 | following the second. | |
a724e79e | 104 | |
1c036c64 TS |
105 | ASN1_TIME_to_tm() converts the time B<s> to the standard B<tm> structure. |
106 | If B<s> is NULL, then the current time is converted. The output time is GMT. | |
1a68e5b0 P |
107 | The B<tm_sec>, B<tm_min>, B<tm_hour>, B<tm_mday>, B<tm_wday>, B<tm_yday>, |
108 | B<tm_mon> and B<tm_year> fields of B<tm> structure are set to proper values, | |
109 | whereas all other fields are set to 0. If B<tm> is NULL this function performs | |
27eb9f23 | 110 | a format check on B<s> only. If B<s> is in Generalized format with fractional |
1c026996 PY |
111 | seconds, e.g. YYYYMMDDHHMMSS.SSSZ, the fractional seconds will be lost while |
112 | converting B<s> to B<tm> structure. | |
1c036c64 | 113 | |
a724e79e DSH |
114 | ASN1_TIME_diff() sets B<*pday> and B<*psec> to the time difference between |
115 | B<from> and B<to>. If B<to> represents a time later than B<from> then | |
116 | one or both (depending on the time difference) of B<*pday> and B<*psec> | |
117 | will be positive. If B<to> represents a time earlier than B<from> then | |
118 | one or both of B<*pday> and B<*psec> will be negative. If B<to> and B<from> | |
119 | represent the same time then B<*pday> and B<*psec> will both be zero. | |
120 | If both B<*pday> and B<*psec> are non-zero they will always have the same | |
121 | sign. The value of B<*psec> will always be less than the number of seconds | |
122 | in a day. If B<from> or B<to> is NULL the current time is used. | |
123 | ||
cf37aaa3 TS |
124 | The ASN1_TIME_cmp_time_t() and ASN1_UTCTIME_cmp_time_t() functions compare |
125 | the two times represented by the time structure B<s> and the time_t B<t>. | |
126 | ||
127 | The ASN1_TIME_compare() function compares the two times represented by the | |
128 | time structures B<a> and B<b>. | |
129 | ||
130 | The ASN1_TIME_to_generalizedtime() function converts an ASN1_TIME to an | |
131 | ASN1_GENERALIZEDTIME, regardless of year. If either B<out> or | |
132 | B<*out> are NULL, then a new object is allocated and must be freed after use. | |
133 | ||
a724e79e DSH |
134 | =head1 NOTES |
135 | ||
136 | The ASN1_TIME structure corresponds to the ASN.1 structure B<Time> | |
137 | defined in RFC5280 et al. The time setting functions obey the rules outlined | |
138 | in RFC5280: if the date can be represented by UTCTime it is used, else | |
139 | GeneralizedTime is used. | |
140 | ||
cf37aaa3 TS |
141 | The ASN1_TIME, ASN1_UTCTIME and ASN1_GENERALIZEDTIME structures are represented |
142 | as an ASN1_STRING internally and can be freed up using ASN1_STRING_free(). | |
a724e79e DSH |
143 | |
144 | The ASN1_TIME structure can represent years from 0000 to 9999 but no attempt | |
145 | is made to correct ancient calendar changes (for example from Julian to | |
146 | Gregorian calendars). | |
147 | ||
cf37aaa3 TS |
148 | ASN1_UTCTIME is limited to a year range of 1950 through 2049. |
149 | ||
a724e79e DSH |
150 | Some applications add offset times directly to a time_t value and pass the |
151 | results to ASN1_TIME_set() (or equivalent). This can cause problems as the | |
152 | time_t value can overflow on some systems resulting in unexpected results. | |
153 | New applications should use ASN1_TIME_adj() instead and pass the offset value | |
154 | in the B<offset_sec> and B<offset_day> parameters instead of directly | |
155 | manipulating a time_t value. | |
156 | ||
cf37aaa3 | 157 | ASN1_TIME_adj() may change the type from ASN1_GENERALIZEDTIME to ASN1_UTCTIME, |
d47eaaf4 | 158 | or vice versa, based on the resulting year. The ASN1_GENERALIZEDTIME_adj() and |
cf37aaa3 TS |
159 | ASN1_UTCTIME_adj() functions will not modify the type of the return structure. |
160 | ||
161 | It is recommended that functions starting with ASN1_TIME be used instead of | |
162 | those starting with ASN1_UTCTIME or ASN1_GENERALIZEDTIME. The functions | |
163 | starting with ASN1_UTCTIME and ASN1_GENERALIZEDTIME act only on that specific | |
164 | time format. The functions starting with ASN1_TIME will operate on either | |
165 | format. | |
166 | ||
a724e79e DSH |
167 | =head1 BUGS |
168 | ||
cf37aaa3 TS |
169 | ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() |
170 | do not print out the time zone: it either prints out "GMT" or nothing. But all | |
171 | certificates complying with RFC5280 et al use GMT anyway. | |
172 | ||
173 | Use the ASN1_TIME_normalize() function to normalize the time value before | |
174 | printing to get GMT results. | |
a724e79e | 175 | |
a724e79e DSH |
176 | =head1 RETURN VALUES |
177 | ||
cf37aaa3 TS |
178 | ASN1_TIME_set(), ASN1_UTCTIME_set(), ASN1_GENERALIZEDTIME_set(), ASN1_TIME_adj(), |
179 | ASN1_UTCTIME_adj and ASN1_GENERALIZEDTIME_set return a pointer to a time structure | |
a724e79e DSH |
180 | or NULL if an error occurred. |
181 | ||
cf37aaa3 TS |
182 | ASN1_TIME_set_string(), ASN1_UTCTIME_set_string(), ASN1_GENERALIZEDTIME_set_string() |
183 | ASN1_TIME_set_string_X509() return 1 if the time value is successfully set and 0 otherwise. | |
a724e79e | 184 | |
cf37aaa3 | 185 | ASN1_TIME_normalize() returns 1 on success, and 0 on error. |
a724e79e | 186 | |
cf37aaa3 TS |
187 | ASN1_TIME_check(), ASN1_UTCTIME_check and ASN1_GENERALIZEDTIME_check() return 1 |
188 | if the structure is syntactically correct and 0 otherwise. | |
189 | ||
190 | ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() return 1 | |
191 | if the time is successfully printed out and 0 if an error occurred (I/O error or | |
192 | invalid time format). | |
a724e79e | 193 | |
1c036c64 | 194 | ASN1_TIME_to_tm() returns 1 if the time is successfully parsed and 0 if an |
f4411faa | 195 | error occurred (invalid time format). |
1c036c64 | 196 | |
186bb907 | 197 | ASN1_TIME_diff() returns 1 for success and 0 for failure. It can fail if the |
cf37aaa3 TS |
198 | passed-in time structure has invalid syntax, for example. |
199 | ||
200 | ASN1_TIME_cmp_time_t() and ASN1_UTCTIME_cmp_time_t() return -1 if B<s> is | |
201 | before B<t>, 0 if B<s> equals B<t>, or 1 if B<s> is after B<t>. -2 is returned | |
202 | on error. | |
203 | ||
204 | ASN1_TIME_compare() returns -1 if B<a> is before B<b>, 0 if B<a> equals B<b>, or 1 if B<a> is after B<b>. -2 is returned on error. | |
205 | ||
206 | ASN1_TIME_to_generalizedtime() returns a pointer to | |
207 | the appropriate time structure on success or NULL if an error occurred. | |
a724e79e | 208 | |
4564e77a PY |
209 | =head1 EXAMPLES |
210 | ||
211 | Set a time structure to one hour after the current time and print it out: | |
212 | ||
213 | #include <time.h> | |
214 | #include <openssl/asn1.h> | |
215 | ||
216 | ASN1_TIME *tm; | |
217 | time_t t; | |
218 | BIO *b; | |
219 | ||
220 | t = time(NULL); | |
221 | tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60); | |
222 | b = BIO_new_fp(stdout, BIO_NOCLOSE); | |
223 | ASN1_TIME_print(b, tm); | |
224 | ASN1_STRING_free(tm); | |
225 | BIO_free(b); | |
226 | ||
227 | Determine if one time is later or sooner than the current time: | |
228 | ||
229 | int day, sec; | |
230 | ||
231 | if (!ASN1_TIME_diff(&day, &sec, NULL, to)) | |
232 | /* Invalid time format */ | |
233 | ||
234 | if (day > 0 || sec > 0) | |
235 | printf("Later\n"); | |
236 | else if (day < 0 || sec < 0) | |
237 | printf("Sooner\n"); | |
238 | else | |
239 | printf("Same\n"); | |
240 | ||
1c036c64 TS |
241 | =head1 HISTORY |
242 | ||
243 | The ASN1_TIME_to_tm() function was added in OpenSSL 1.1.1. | |
04e62715 | 244 | The ASN1_TIME_set_string_X509() function was added in OpenSSL 1.1.1. |
cf37aaa3 TS |
245 | The ASN1_TIME_normalize() function was added in OpenSSL 1.1.1. |
246 | The ASN1_TIME_cmp_time_t() function was added in OpenSSL 1.1.1. | |
247 | The ASN1_TIME_compare() function was added in OpenSSL 1.1.1. | |
1c036c64 | 248 | |
e2f92610 RS |
249 | =head1 COPYRIGHT |
250 | ||
b0edda11 | 251 | Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 252 | |
4746f25a | 253 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
254 | this file except in compliance with the License. You can obtain a copy |
255 | in the file LICENSE in the source distribution or at | |
256 | L<https://www.openssl.org/source/license.html>. | |
257 | ||
258 | =cut |