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