]>
Commit | Line | Data |
---|---|---|
a724e79e DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | ASN1_TIME_set, ASN1_TIME_adj, ASN1_TIME_check, ASN1_TIME_set_string, | |
bb9ad09e | 6 | ASN1_TIME_print, ASN1_TIME_diff - ASN.1 Time functions |
a724e79e DSH |
7 | |
8 | =head1 SYNOPSIS | |
9 | ||
10 | ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t t); | |
11 | ASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t, | |
12 | int offset_day, long offset_sec); | |
13 | int ASN1_TIME_set_string(ASN1_TIME *s, const char *str); | |
14 | int ASN1_TIME_check(const ASN1_TIME *t); | |
15 | int ASN1_TIME_print(BIO *b, const ASN1_TIME *s); | |
16 | ||
17 | int ASN1_TIME_diff(int *pday, int *psec, | |
18 | const ASN1_TIME *from, const ASN1_TIME *to); | |
19 | ||
20 | =head1 DESCRIPTION | |
21 | ||
22 | The function ASN1_TIME_set() sets the ASN1_TIME structure B<s> to the | |
23 | time represented by the time_t value B<t>. If B<s> is NULL a new ASN1_TIME | |
24 | structure is allocated and returned. | |
25 | ||
26 | ASN1_TIME_adj() sets the ASN1_TIME structure B<s> to the time represented | |
27 | by the time B<offset_day> and B<offset_sec> after the time_t value B<t>. | |
28 | The values of B<offset_day> or B<offset_sec> can be negative to set a | |
29 | time before B<t>. The B<offset_sec> value can also exceed the number of | |
30 | seconds in a day. If B<s> is NULL a new ASN1_TIME structure is allocated | |
31 | and returned. | |
32 | ||
33 | ASN1_TIME_set_string() sets ASN1_TIME structure B<s> to the time | |
34 | represented by string B<str> which must be in appropriate ASN.1 time | |
35 | format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). | |
36 | ||
37 | ASN1_TIME_check() checks the syntax of ASN1_TIME structure B<s>. | |
38 | ||
39 | ASN1_TIME_print() prints out the time B<s> to BIO B<b> in human readable | |
40 | format. It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example | |
41 | "Feb 3 00:55:52 2015 GMT" it does not include a newline. If the time | |
42 | structure has invalid format it prints out "Bad time value" and returns | |
43 | an error. | |
44 | ||
45 | ASN1_TIME_diff() sets B<*pday> and B<*psec> to the time difference between | |
46 | B<from> and B<to>. If B<to> represents a time later than B<from> then | |
47 | one or both (depending on the time difference) of B<*pday> and B<*psec> | |
48 | will be positive. If B<to> represents a time earlier than B<from> then | |
49 | one or both of B<*pday> and B<*psec> will be negative. If B<to> and B<from> | |
50 | represent the same time then B<*pday> and B<*psec> will both be zero. | |
51 | If both B<*pday> and B<*psec> are non-zero they will always have the same | |
52 | sign. The value of B<*psec> will always be less than the number of seconds | |
53 | in a day. If B<from> or B<to> is NULL the current time is used. | |
54 | ||
55 | =head1 NOTES | |
56 | ||
57 | The ASN1_TIME structure corresponds to the ASN.1 structure B<Time> | |
58 | defined in RFC5280 et al. The time setting functions obey the rules outlined | |
59 | in RFC5280: if the date can be represented by UTCTime it is used, else | |
60 | GeneralizedTime is used. | |
61 | ||
62 | The ASN1_TIME structure is represented as an ASN1_STRING internally and can | |
63 | be freed up using ASN1_STRING_free(). | |
64 | ||
65 | The ASN1_TIME structure can represent years from 0000 to 9999 but no attempt | |
66 | is made to correct ancient calendar changes (for example from Julian to | |
67 | Gregorian calendars). | |
68 | ||
69 | Some applications add offset times directly to a time_t value and pass the | |
70 | results to ASN1_TIME_set() (or equivalent). This can cause problems as the | |
71 | time_t value can overflow on some systems resulting in unexpected results. | |
72 | New applications should use ASN1_TIME_adj() instead and pass the offset value | |
73 | in the B<offset_sec> and B<offset_day> parameters instead of directly | |
74 | manipulating a time_t value. | |
75 | ||
76 | =head1 BUGS | |
77 | ||
78 | ASN1_TIME_print() currently does not print out the time zone: it either prints | |
79 | out "GMT" or nothing. But all certificates complying with RFC5280 et al use GMT | |
80 | anyway. | |
81 | ||
82 | =head1 EXAMPLES | |
83 | ||
84 | Set a time structure to one hour after the current time and print it out: | |
85 | ||
86 | #include <time.h> | |
87 | #include <openssl/asn1.h> | |
88 | ASN1_TIME *tm; | |
89 | time_t t; | |
90 | BIO *b; | |
91 | t = time(NULL); | |
92 | tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60); | |
93 | b = BIO_new_fp(stdout, BIO_NOCLOSE); | |
94 | ASN1_TIME_print(b, tm); | |
95 | ASN1_STRING_free(tm); | |
96 | BIO_free(b); | |
97 | ||
98 | Determine if one time is later or sooner than the current time: | |
99 | ||
100 | int day, sec; | |
101 | ||
102 | if (!ASN1_TIME_diff(&day, &sec, NULL, to)) | |
1bc74519 | 103 | /* Invalid time format */ |
a724e79e DSH |
104 | |
105 | if (day > 0 || sec > 0) | |
106 | printf("Later\n"); | |
107 | else if (day < 0 || sec < 0) | |
108 | printf("Sooner\n"); | |
109 | else | |
110 | printf("Same\n"); | |
111 | ||
112 | =head1 RETURN VALUES | |
113 | ||
114 | ASN1_TIME_set() and ASN1_TIME_adj() return a pointer to an ASN1_TIME structure | |
115 | or NULL if an error occurred. | |
116 | ||
117 | ASN1_TIME_set_string() returns 1 if the time value is successfully set and | |
118 | 0 otherwise. | |
119 | ||
120 | ASN1_TIME_check() returns 1 if the structure is syntactically correct and 0 | |
121 | otherwise. | |
122 | ||
123 | ASN1_TIME_print() returns 1 if the time is successfully printed out and 0 if | |
124 | an error occurred (I/O error or invalid time format). | |
125 | ||
186bb907 | 126 | ASN1_TIME_diff() returns 1 for success and 0 for failure. It can fail if the |
a724e79e DSH |
127 | pass ASN1_TIME structure has invalid syntax for example. |
128 | ||
e2f92610 RS |
129 | =head1 COPYRIGHT |
130 | ||
131 | Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. | |
132 | ||
133 | Licensed under the OpenSSL license (the "License"). You may not use | |
134 | this file except in compliance with the License. You can obtain a copy | |
135 | in the file LICENSE in the source distribution or at | |
136 | L<https://www.openssl.org/source/license.html>. | |
137 | ||
138 | =cut |