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