]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - secure/lib/libcrypto/man/ASN1_TIME_set.3
Add libbearssl
[FreeBSD/FreeBSD.git] / secure / lib / libcrypto / man / ASN1_TIME_set.3
1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings.  \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 .    ds -- \(*W-
28 .    ds PI pi
29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
31 .    ds L" ""
32 .    ds R" ""
33 .    ds C` ""
34 .    ds C' ""
35 'br\}
36 .el\{\
37 .    ds -- \|\(em\|
38 .    ds PI \(*p
39 .    ds L" ``
40 .    ds R" ''
41 .    ds C`
42 .    ds C'
43 'br\}
44 .\"
45 .\" Escape single quotes in literal strings from groff's Unicode transform.
46 .ie \n(.g .ds Aq \(aq
47 .el       .ds Aq '
48 .\"
49 .\" If the F register is >0, we'll generate index entries on stderr for
50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
52 .\" output yourself in some meaningful fashion.
53 .\"
54 .\" Avoid warning from groff about undefined register 'F'.
55 .de IX
56 ..
57 .if !\nF .nr F 0
58 .if \nF>0 \{\
59 .    de IX
60 .    tm Index:\\$1\t\\n%\t"\\$2"
61 ..
62 .    if !\nF==2 \{\
63 .        nr % 0
64 .        nr F 2
65 .    \}
66 .\}
67 .\"
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
70 .    \" fudge factors for nroff and troff
71 .if n \{\
72 .    ds #H 0
73 .    ds #V .8m
74 .    ds #F .3m
75 .    ds #[ \f1
76 .    ds #] \fP
77 .\}
78 .if t \{\
79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 .    ds #V .6m
81 .    ds #F 0
82 .    ds #[ \&
83 .    ds #] \&
84 .\}
85 .    \" simple accents for nroff and troff
86 .if n \{\
87 .    ds ' \&
88 .    ds ` \&
89 .    ds ^ \&
90 .    ds , \&
91 .    ds ~ ~
92 .    ds /
93 .\}
94 .if t \{\
95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101 .\}
102 .    \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 .    \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 .    \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
117 \{\
118 .    ds : e
119 .    ds 8 ss
120 .    ds o a
121 .    ds d- d\h'-1'\(ga
122 .    ds D- D\h'-1'\(hy
123 .    ds th \o'bp'
124 .    ds Th \o'LP'
125 .    ds ae ae
126 .    ds Ae AE
127 .\}
128 .rm #[ #] #H #V #F C
129 .\" ========================================================================
130 .\"
131 .IX Title "ASN1_TIME_SET 3"
132 .TH ASN1_TIME_SET 3 "2018-11-20" "1.1.1a" "OpenSSL"
133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
134 .\" way too many mistakes in technical documents.
135 .if n .ad l
136 .nh
137 .SH "NAME"
138 ASN1_TIME_set, ASN1_UTCTIME_set, ASN1_GENERALIZEDTIME_set, ASN1_TIME_adj, ASN1_UTCTIME_adj, ASN1_GENERALIZEDTIME_adj, ASN1_TIME_check, ASN1_UTCTIME_check, ASN1_GENERALIZEDTIME_check, ASN1_TIME_set_string, ASN1_UTCTIME_set_string, ASN1_GENERALIZEDTIME_set_string, ASN1_TIME_set_string_X509, ASN1_TIME_normalize, ASN1_TIME_to_tm, ASN1_TIME_print, ASN1_UTCTIME_print, ASN1_GENERALIZEDTIME_print, ASN1_TIME_diff, ASN1_TIME_cmp_time_t, ASN1_UTCTIME_cmp_time_t, ASN1_TIME_compare, ASN1_TIME_to_generalizedtime \- ASN.1 Time functions
139 .SH "SYNOPSIS"
140 .IX Header "SYNOPSIS"
141 .Vb 4
142 \& ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t t);
143 \& ASN1_UTCTIME *ASN1_UTCTIME_set(ASN1_UTCTIME *s, time_t t);
144 \& ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_set(ASN1_GENERALIZEDTIME *s,
145 \&                                                time_t t);
146 \&
147 \& ASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t, int offset_day,
148 \&                          long offset_sec);
149 \& ASN1_UTCTIME *ASN1_UTCTIME_adj(ASN1_UTCTIME *s, time_t t,
150 \&                                int offset_day, long offset_sec);
151 \& ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_adj(ASN1_GENERALIZEDTIME *s,
152 \&                                                time_t t, int offset_day,
153 \&                                                long offset_sec);
154 \&
155 \& int ASN1_TIME_set_string(ASN1_TIME *s, const char *str);
156 \& int ASN1_TIME_set_string_X509(ASN1_TIME *s, const char *str);
157 \& int ASN1_UTCTIME_set_string(ASN1_UTCTIME *s, const char *str);
158 \& int ASN1_GENERALIZEDTIME_set_string(ASN1_GENERALIZEDTIME *s,
159 \&                                     const char *str);
160 \&
161 \& int ASN1_TIME_normalize(ASN1_TIME *s);
162 \&
163 \& int ASN1_TIME_check(const ASN1_TIME *t);
164 \& int ASN1_UTCTIME_check(const ASN1_UTCTIME *t);
165 \& int ASN1_GENERALIZEDTIME_check(const ASN1_GENERALIZEDTIME *t);
166 \&
167 \& int ASN1_TIME_print(BIO *b, const ASN1_TIME *s);
168 \& int ASN1_UTCTIME_print(BIO *b, const ASN1_UTCTIME *s);
169 \& int ASN1_GENERALIZEDTIME_print(BIO *b, const ASN1_GENERALIZEDTIME *s);
170 \&
171 \& int ASN1_TIME_to_tm(const ASN1_TIME *s, struct tm *tm);
172 \& int ASN1_TIME_diff(int *pday, int *psec, const ASN1_TIME *from,
173 \&                    const ASN1_TIME *to);
174 \&
175 \& int ASN1_TIME_cmp_time_t(const ASN1_TIME *s, time_t t);
176 \& int ASN1_UTCTIME_cmp_time_t(const ASN1_UTCTIME *s, time_t t);
177 \&
178 \& int ASN1_TIME_compare(const ASN1_TIME *a, const ASN1_TIME *b);
179 \&
180 \& ASN1_GENERALIZEDTIME *ASN1_TIME_to_generalizedtime(ASN1_TIME *t,
181 \&                                                    ASN1_GENERALIZEDTIME **out);
182 .Ve
183 .SH "DESCRIPTION"
184 .IX Header "DESCRIPTION"
185 The \fIASN1_TIME_set()\fR, \fIASN1_UTCTIME_set()\fR and \fIASN1_GENERALIZEDTIME_set()\fR
186 functions set the structure \fBs\fR to the time represented by the time_t
187 value \fBt\fR. If \fBs\fR is \s-1NULL\s0 a new time structure is allocated and returned.
188 .PP
189 The \fIASN1_TIME_adj()\fR, \fIASN1_UTCTIME_adj()\fR and \fIASN1_GENERALIZEDTIME_adj()\fR
190 functions set the time structure \fBs\fR to the time represented
191 by the time \fBoffset_day\fR and \fBoffset_sec\fR after the time_t value \fBt\fR.
192 The values of \fBoffset_day\fR or \fBoffset_sec\fR can be negative to set a
193 time before \fBt\fR. The \fBoffset_sec\fR value can also exceed the number of
194 seconds in a day. If \fBs\fR is \s-1NULL\s0 a new structure is allocated
195 and returned.
196 .PP
197 The \fIASN1_TIME_set_string()\fR, \fIASN1_UTCTIME_set_string()\fR and
198 \&\fIASN1_GENERALIZEDTIME_set_string()\fR functions set the time structure \fBs\fR
199 to the time represented by string \fBstr\fR which must be in appropriate \s-1ASN.1\s0
200 time format (for example \s-1YYMMDDHHMMSSZ\s0 or \s-1YYYYMMDDHHMMSSZ\s0). If \fBs\fR is \s-1NULL\s0
201 this function performs a format check on \fBstr\fR only. The string \fBstr\fR
202 is copied into \fBs\fR.
203 .PP
204 \&\fIASN1_TIME_set_string_X509()\fR sets \s-1ASN1_TIME\s0 structure \fBs\fR to the time
205 represented by string \fBstr\fR which must be in appropriate time format
206 that \s-1RFC 5280\s0 requires, which means it only allows \s-1YYMMDDHHMMSSZ\s0 and
207 \&\s-1YYYYMMDDHHMMSSZ\s0 (leap second is rejected), all other \s-1ASN.1\s0 time format
208 are not allowed. If \fBs\fR is \s-1NULL\s0 this function performs a format check
209 on \fBstr\fR only.
210 .PP
211 The \fIASN1_TIME_normalize()\fR function converts an \s-1ASN1_GENERALIZEDTIME\s0 or
212 \&\s-1ASN1_UTCTIME\s0 into a time value that can be used in a certificate. It
213 should be used after the \fIASN1_TIME_set_string()\fR functions and before
214 \&\fIASN1_TIME_print()\fR functions to get consistent (i.e. \s-1GMT\s0) results.
215 .PP
216 The \fIASN1_TIME_check()\fR, \fIASN1_UTCTIME_check()\fR and \fIASN1_GENERALIZEDTIME_check()\fR
217 functions check the syntax of the time structure \fBs\fR.
218 .PP
219 The \fIASN1_TIME_print()\fR, \fIASN1_UTCTIME_print()\fR and \fIASN1_GENERALIZEDTIME_print()\fR
220 functions print the time structure \fBs\fR to \s-1BIO\s0 \fBb\fR in human readable
221 format. It will be of the format \s-1MMM DD HH:MM:SS YYYY\s0 [\s-1GMT\s0], for example
222 \&\*(L"Feb  3 00:55:52 2015 \s-1GMT\*(R"\s0 it does not include a newline. If the time
223 structure has invalid format it prints out \*(L"Bad time value\*(R" and returns
224 an error. The output for generalized time may include a fractional part
225 following the second.
226 .PP
227 \&\fIASN1_TIME_to_tm()\fR converts the time \fBs\fR to the standard \fBtm\fR structure.
228 If \fBs\fR is \s-1NULL,\s0 then the current time is converted. The output time is \s-1GMT.\s0
229 The \fBtm_sec\fR, \fBtm_min\fR, \fBtm_hour\fR, \fBtm_mday\fR, \fBtm_wday\fR, \fBtm_yday\fR,
230 \&\fBtm_mon\fR and \fBtm_year\fR fields of \fBtm\fR structure are set to proper values,
231 whereas all other fields are set to 0. If \fBtm\fR is \s-1NULL\s0 this function performs
232 a format check on \fBs\fR only. If \fBs\fR is in Generalized format with fractional
233 seconds, e.g. \s-1YYYYMMDDHHMMSS.SSSZ,\s0 the fractional seconds will be lost while
234 converting \fBs\fR to \fBtm\fR structure.
235 .PP
236 \&\fIASN1_TIME_diff()\fR sets \fB*pday\fR and \fB*psec\fR to the time difference between
237 \&\fBfrom\fR and \fBto\fR. If \fBto\fR represents a time later than \fBfrom\fR then
238 one or both (depending on the time difference) of \fB*pday\fR and \fB*psec\fR
239 will be positive. If \fBto\fR represents a time earlier than \fBfrom\fR then
240 one or both of \fB*pday\fR and \fB*psec\fR will be negative. If \fBto\fR and \fBfrom\fR
241 represent the same time then \fB*pday\fR and \fB*psec\fR will both be zero.
242 If both \fB*pday\fR and \fB*psec\fR are non-zero they will always have the same
243 sign. The value of \fB*psec\fR will always be less than the number of seconds
244 in a day. If \fBfrom\fR or \fBto\fR is \s-1NULL\s0 the current time is used.
245 .PP
246 The \fIASN1_TIME_cmp_time_t()\fR and \fIASN1_UTCTIME_cmp_time_t()\fR functions compare
247 the two times represented by the time structure \fBs\fR and the time_t \fBt\fR.
248 .PP
249 The \fIASN1_TIME_compare()\fR function compares the two times represented by the
250 time structures \fBa\fR and \fBb\fR.
251 .PP
252 The \fIASN1_TIME_to_generalizedtime()\fR function converts an \s-1ASN1_TIME\s0 to an
253 \&\s-1ASN1_GENERALIZEDTIME,\s0 regardless of year. If either \fBout\fR or
254 \&\fB*out\fR are \s-1NULL,\s0 then a new object is allocated and must be freed after use.
255 .SH "NOTES"
256 .IX Header "NOTES"
257 The \s-1ASN1_TIME\s0 structure corresponds to the \s-1ASN.1\s0 structure \fBTime\fR
258 defined in \s-1RFC5280\s0 et al. The time setting functions obey the rules outlined
259 in \s-1RFC5280:\s0 if the date can be represented by UTCTime it is used, else
260 GeneralizedTime is used.
261 .PP
262 The \s-1ASN1_TIME, ASN1_UTCTIME\s0 and \s-1ASN1_GENERALIZEDTIME\s0 structures are represented
263 as an \s-1ASN1_STRING\s0 internally and can be freed up using \fIASN1_STRING_free()\fR.
264 .PP
265 The \s-1ASN1_TIME\s0 structure can represent years from 0000 to 9999 but no attempt
266 is made to correct ancient calendar changes (for example from Julian to
267 Gregorian calendars).
268 .PP
269 \&\s-1ASN1_UTCTIME\s0 is limited to a year range of 1950 through 2049.
270 .PP
271 Some applications add offset times directly to a time_t value and pass the
272 results to \fIASN1_TIME_set()\fR (or equivalent). This can cause problems as the
273 time_t value can overflow on some systems resulting in unexpected results.
274 New applications should use \fIASN1_TIME_adj()\fR instead and pass the offset value
275 in the \fBoffset_sec\fR and \fBoffset_day\fR parameters instead of directly
276 manipulating a time_t value.
277 .PP
278 \&\fIASN1_TIME_adj()\fR may change the type from \s-1ASN1_GENERALIZEDTIME\s0 to \s-1ASN1_UTCTIME,\s0
279 or vice versa, based on the resulting year. The \fIASN1_GENERALIZEDTIME_adj()\fR and
280 \&\fIASN1_UTCTIME_adj()\fR functions will not modify the type of the return structure.
281 .PP
282 It is recommended that functions starting with \s-1ASN1_TIME\s0 be used instead of
283 those starting with \s-1ASN1_UTCTIME\s0 or \s-1ASN1_GENERALIZEDTIME.\s0 The functions
284 starting with \s-1ASN1_UTCTIME\s0 and \s-1ASN1_GENERALIZEDTIME\s0 act only on that specific
285 time format. The functions starting with \s-1ASN1_TIME\s0 will operate on either
286 format.
287 .SH "BUGS"
288 .IX Header "BUGS"
289 \&\fIASN1_TIME_print()\fR, \fIASN1_UTCTIME_print()\fR and \fIASN1_GENERALIZEDTIME_print()\fR
290 do not print out the time zone: it either prints out \*(L"\s-1GMT\*(R"\s0 or nothing. But all
291 certificates complying with \s-1RFC5280\s0 et al use \s-1GMT\s0 anyway.
292 .PP
293 Use the \fIASN1_TIME_normalize()\fR function to normalize the time value before
294 printing to get \s-1GMT\s0 results.
295 .SH "EXAMPLES"
296 .IX Header "EXAMPLES"
297 Set a time structure to one hour after the current time and print it out:
298 .PP
299 .Vb 2
300 \& #include <time.h>
301 \& #include <openssl/asn1.h>
302 \&
303 \& ASN1_TIME *tm;
304 \& time_t t;
305 \& BIO *b;
306 \&
307 \& t = time(NULL);
308 \& tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60);
309 \& b = BIO_new_fp(stdout, BIO_NOCLOSE);
310 \& ASN1_TIME_print(b, tm);
311 \& ASN1_STRING_free(tm);
312 \& BIO_free(b);
313 .Ve
314 .PP
315 Determine if one time is later or sooner than the current time:
316 .PP
317 .Vb 1
318 \& int day, sec;
319 \&
320 \& if (!ASN1_TIME_diff(&day, &sec, NULL, to))
321 \&     /* Invalid time format */
322 \&
323 \& if (day > 0 || sec > 0)
324 \&     printf("Later\en");
325 \& else if (day < 0 || sec < 0)
326 \&     printf("Sooner\en");
327 \& else
328 \&     printf("Same\en");
329 .Ve
330 .SH "RETURN VALUES"
331 .IX Header "RETURN VALUES"
332 \&\fIASN1_TIME_set()\fR, \fIASN1_UTCTIME_set()\fR, \fIASN1_GENERALIZEDTIME_set()\fR, \fIASN1_TIME_adj()\fR,
333 ASN1_UTCTIME_adj and ASN1_GENERALIZEDTIME_set return a pointer to a time structure
334 or \s-1NULL\s0 if an error occurred.
335 .PP
336 \&\fIASN1_TIME_set_string()\fR, \fIASN1_UTCTIME_set_string()\fR, \fIASN1_GENERALIZEDTIME_set_string()\fR
337 \&\fIASN1_TIME_set_string_X509()\fR return 1 if the time value is successfully set and 0 otherwise.
338 .PP
339 \&\fIASN1_TIME_normalize()\fR returns 1 on success, and 0 on error.
340 .PP
341 \&\fIASN1_TIME_check()\fR, ASN1_UTCTIME_check and \fIASN1_GENERALIZEDTIME_check()\fR return 1
342 if the structure is syntactically correct and 0 otherwise.
343 .PP
344 \&\fIASN1_TIME_print()\fR, \fIASN1_UTCTIME_print()\fR and \fIASN1_GENERALIZEDTIME_print()\fR return 1
345 if the time is successfully printed out and 0 if an error occurred (I/O error or
346 invalid time format).
347 .PP
348 \&\fIASN1_TIME_to_tm()\fR returns 1 if the time is successfully parsed and 0 if an
349 error occurred (invalid time format).
350 .PP
351 \&\fIASN1_TIME_diff()\fR returns 1 for success and 0 for failure. It can fail if the
352 passed-in time structure has invalid syntax, for example.
353 .PP
354 \&\fIASN1_TIME_cmp_time_t()\fR and \fIASN1_UTCTIME_cmp_time_t()\fR return \-1 if \fBs\fR is
355 before \fBt\fR, 0 if \fBs\fR equals \fBt\fR, or 1 if \fBs\fR is after \fBt\fR. \-2 is returned
356 on error.
357 .PP
358 \&\fIASN1_TIME_compare()\fR returns \-1 if \fBa\fR is before \fBb\fR, 0 if \fBa\fR equals \fBb\fR, or 1 if \fBa\fR is after \fBb\fR. \-2 is returned on error.
359 .PP
360 \&\fIASN1_TIME_to_generalizedtime()\fR returns a pointer to
361 the appropriate time structure on success or \s-1NULL\s0 if an error occurred.
362 .SH "HISTORY"
363 .IX Header "HISTORY"
364 The \fIASN1_TIME_to_tm()\fR function was added in OpenSSL 1.1.1.
365 The \fIASN1_TIME_set_string_X509()\fR function was added in OpenSSL 1.1.1.
366 The \fIASN1_TIME_normalize()\fR function was added in OpenSSL 1.1.1.
367 The \fIASN1_TIME_cmp_time_t()\fR function was added in OpenSSL 1.1.1.
368 The \fIASN1_TIME_compare()\fR function was added in OpenSSL 1.1.1.
369 .SH "COPYRIGHT"
370 .IX Header "COPYRIGHT"
371 Copyright 2015\-2018 The OpenSSL Project Authors. All Rights Reserved.
372 .PP
373 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
374 this file except in compliance with the License.  You can obtain a copy
375 in the file \s-1LICENSE\s0 in the source distribution or at
376 <https://www.openssl.org/source/license.html>.