.\" $OpenBSD: ASN1_TIME_set.3,v 1.15 2019/06/06 01:06:58 schwarze Exp $ .\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 .\" selective merge up to: OpenSSL b0edda11 Mar 20 13:00:17 2018 +0000 .\" .\" This file was written by Dr. Stephen Henson .\" and Todd Short . .\" Copyright (c) 2015, 2017 The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in .\" the documentation and/or other materials provided with the .\" distribution. .\" .\" 3. All advertising materials mentioning features or use of this .\" software must display the following acknowledgment: .\" "This product includes software developed by the OpenSSL Project .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" .\" .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to .\" endorse or promote products derived from this software without .\" prior written permission. For written permission, please contact .\" openssl-core@openssl.org. .\" .\" 5. Products derived from this software may not be called "OpenSSL" .\" nor may "OpenSSL" appear in their names without prior written .\" permission of the OpenSSL Project. .\" .\" 6. Redistributions of any form whatsoever must retain the following .\" acknowledgment: .\" "This product includes software developed by the OpenSSL Project .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" .\" .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" .Dd $Mdocdate: June 6 2019 $ .Dt ASN1_TIME_SET 3 .Os .Sh NAME .Nm ASN1_TIME_set , .Nm ASN1_UTCTIME_set , .Nm ASN1_GENERALIZEDTIME_set , .Nm ASN1_TIME_adj , .Nm ASN1_UTCTIME_adj , .Nm ASN1_GENERALIZEDTIME_adj , .Nm ASN1_TIME_set_string , .Nm ASN1_UTCTIME_set_string , .Nm ASN1_GENERALIZEDTIME_set_string , .Nm ASN1_TIME_check , .Nm ASN1_UTCTIME_check , .Nm ASN1_GENERALIZEDTIME_check , .Nm ASN1_TIME_print , .Nm ASN1_UTCTIME_print , .Nm ASN1_GENERALIZEDTIME_print , .Nm ASN1_UTCTIME_cmp_time_t , .Nm ASN1_TIME_to_generalizedtime .Nd ASN.1 Time functions .Sh SYNOPSIS .In openssl/asn1.h .Ft ASN1_TIME * .Fo ASN1_TIME_set .Fa "ASN1_TIME *s" .Fa "time_t t" .Fc .Ft ASN1_UTCTIME * .Fo ASN1_UTCTIME_set .Fa "ASN1_UTCTIME *s" .Fa "time_t t" .Fc .Ft ASN1_GENERALIZEDTIME * .Fo ASN1_GENERALIZEDTIME_set .Fa "ASN1_GENERALIZEDTIME *s" .Fa "time_t t" .Fc .Ft ASN1_TIME * .Fo ASN1_TIME_adj .Fa "ASN1_TIME *s" .Fa "time_t t" .Fa "int offset_day" .Fa "long offset_sec" .Fc .Ft ASN1_UTCTIME * .Fo ASN1_UTCTIME_adj .Fa "ASN1_UTCTIME *s" .Fa "time_t t" .Fa "int offset_day" .Fa "long offset_sec" .Fc .Ft ASN1_GENERALIZEDTIME * .Fo ASN1_GENERALIZEDTIME_adj .Fa "ASN1_GENERALIZEDTIME *s" .Fa "time_t t" .Fa "int offset_day" .Fa "long offset_sec" .Fc .Ft int .Fo ASN1_TIME_set_string .Fa "ASN1_TIME *s" .Fa "const char *str" .Fc .Ft int .Fo ASN1_UTCTIME_set_string .Fa "ASN1_UTCTIME *s" .Fa "const char *str" .Fc .Ft int .Fo ASN1_GENERALIZEDTIME_set_string .Fa "ASN1_GENERALIZEDTIME *s" .Fa "const char *str" .Fc .Ft int .Fo ASN1_TIME_check .Fa "const ASN1_TIME *t" .Fc .Ft int .Fo ASN1_UTCTIME_check .Fa "const ASN1_UTCTIME *t" .Fc .Ft int .Fo ASN1_GENERALIZEDTIME_check .Fa "const ASN1_GENERALIZEDTIME *t" .Fc .Ft int .Fo ASN1_TIME_print .Fa "BIO *b" .Fa "const ASN1_TIME *s" .Fc .Ft int .Fo ASN1_UTCTIME_print .Fa "BIO *b" .Fa "const ASN1_UTCTIME *s" .Fc .Ft int .Fo ASN1_GENERALIZEDTIME_print .Fa "BIO *b" .Fa "const ASN1_GENERALIZEDTIME *s" .Fc .Ft int .Fo ASN1_UTCTIME_cmp_time_t .Fa "const ASN1_UTCTIME *s" .Fa "time_t t" .Fc .Ft ASN1_GENERALIZEDTIME * .Fo ASN1_TIME_to_generalizedtime .Fa "const ASN1_TIME *t" .Fa "ASN1_GENERALIZEDTIME **out" .Fc .Sh DESCRIPTION The functions .Fn ASN1_TIME_set , .Fn ASN1_UTCTIME_set , and .Fn ASN1_GENERALIZEDTIME_set set the time structure .Fa s to the time represented by the .Vt time_t value .Fa t . If .Fa s is .Dv NULL , a new time structure is allocated and returned. .Pp The functions .Fn ASN1_TIME_adj , .Fn ASN1_UTCTIME_adj , and .Fn ASN1_GENERALIZEDTIME_adj set the time structure .Fa s to the time represented by the time .Fa offset_day and .Fa offset_sec after the .Vt time_t value .Fa t . The values of .Fa offset_day or .Fa offset_sec can be negative to set a time before .Fa t . The .Fa offset_sec value can also exceed the number of seconds in a day. If .Fa s is .Dv NULL , a new time structure is allocated and returned. .Pp .Fn ASN1_TIME_adj may change the type from .Vt ASN1_GENERALIZEDTIME to .Vt ASN1_UTCTIME or vice versa depending on the resulting year. The functions .Fn ASN1_UTCTIME_adj and .Fn ASN1_GENERALIZEDTIME_adj do not modify the type of the return structure. .Pp The functions .Fn ASN1_TIME_set_string , .Fn ASN1_UTCTIME_set_string , and .Fn ASN1_GENERALIZEDTIME_set_string set the time structure .Fa s to the time represented by the string .Fa str , which must be in appropriate ASN.1 time format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). The string .Fa str is copied into .Fa s . If .Fa s is .Dv NULL , these functions only perform a format check on .Fa str . .Pp The functions .Fn ASN1_TIME_check , .Fn ASN1_UTCTIME_check , and .Fn ASN1_GENERALIZEDTIME_check check the syntax of the time structure .Fa s . .Pp The functions .Fn ASN1_TIME_print , .Fn ASN1_UTCTIME_print , and .Fn ASN1_GENERALIZEDTIME_print print out the time .Fa s to .Vt BIO .Fa b in human readable format. It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example "Feb 3 00:55:52 2015 GMT". It does not include a newline. If the time structure has an invalid format, it prints out "Bad time value" and returns an error. The output of .Fn ASN1_GENERALIZEDTIME_print may include a fractional part following the second. .Pp The function .Fn ASN1_UTCTIME_cmp_time_t compares the two times represented by .Fa s and .Fa t . .Pp The function .Fn ASN1_TIME_to_generalizedtime converts the .Vt ASN1_TIME .Fa t to an .Vt ASN1_GENERALIZEDTIME , regardless of year. If either .Fa out or .Pf * Fa out is .Dv NULL , then a new object is allocated and must be freed after use. .Pp The .Vt ASN1_TIME structure corresponds to the ASN.1 structure .Sy Time defined in RFC 5280 et al. The time setting functions obey the rules outlined in RFC 5280: if the date can be represented by UTCTime it is used, otherwise GeneralizedTime is used. .Pp The .Vt ASN1_TIME , .Vt ASN1_UTCTIME , and .Vt ASN1_GENERALIZEDTIME structures are represented as .Vt ASN1_STRING structures internally and can be freed using .Xr ASN1_STRING_free 3 . .Pp The .Vt ASN1_TIME structure can represent years from 0000 to 9999 but no attempt is made to correct ancient calendar changes (for example from Julian to Gregorian calendars). .Pp .Vt ASN1_UTCTIME is limited to a year range of 1950 through 2049. .Pp It is recommended that .Vt ASN1_TIME functions be used instead of .Vt ASN1_UTCTIME or .Vt ASN1_GENERALIZEDTIME functions because the .Vt ASN1_UTCTIME and .Vt ASN1_GENERALIZEDTIME functions act only on that specific time format, while the .Vt ASN1_TIME functions operate on either format. .Sh RETURN VALUES .Fn ASN1_TIME_set , .Fn ASN1_UTCTIME_set , .Fn ASN1_GENERALIZEDTIME_set , .Fn ASN1_TIME_adj , .Fn ASN1_UTCTIME_adj , .Fn ASN1_GENERALIZEDTIME_adj , and .Fn ASN1_TIME_to_generalizedtime return a pointer to a time structure or .Dv NULL if an error occurred. .Pp .Fn ASN1_TIME_set_string , .Fn ASN1_UTCTIME_set_string , and .Fn ASN1_GENERALIZEDTIME_set_string return 1 if the time value is successfully set or 0 otherwise. .Pp .Fn ASN1_TIME_check , .Fn ASN1_UTCTIME_check , and .Fn ASN1_GENERALIZEDTIME_check return 1 if the time structure is syntactically correct or 0 otherwise. .Pp .Fn ASN1_TIME_print , .Fn ASN1_UTCTIME_print , and .Fn ASN1_GENERALIZEDTIME_print return 1 if the time is successfully printed or 0 if an error occurred (I/O error or invalid time format). .Pp .Fn ASN1_UTCTIME_cmp_time_t returns \-1 if .Fa s is earlier than .Fa t , 0 if both are equal, 1 if .Fa s is later than .Fa t , or \-2 on error. .Sh EXAMPLES Set a time structure to one hour after the current time and print it out: .Bd -literal -offset indent #include #include ASN1_TIME *tm; time_t t; BIO *b; t = time(NULL); tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60); b = BIO_new_fp(stdout, BIO_NOCLOSE); ASN1_TIME_print(b, tm); ASN1_STRING_free(tm); BIO_free(b); .Ed .Sh SEE ALSO .Xr ASN1_TIME_new 3 , .Xr ASN1_time_parse 3 , .Xr X509_cmp_time 3 .Sh HISTORY .Fn ASN1_UTCTIME_check and .Fn ASN1_UTCTIME_print first appeared in SSLeay 0.5.1. .Fn ASN1_UTCTIME_set first appeared in SSLeay 0.6.0. .Fn ASN1_UTCTIME_set_string first appeared in SSLeay 0.9.0. All these functions have been available since .Ox 2.4 . .Pp .Fn ASN1_TIME_set , .Fn ASN1_GENERALIZEDTIME_set , .Fn ASN1_GENERALIZEDTIME_set_string , .Fn ASN1_GENERALIZEDTIME_check , .Fn ASN1_TIME_print , and .Fn ASN1_GENERALIZEDTIME_print first appeared in OpenSSL 0.9.2b and have been available since .Ox 2.6 . .Pp .Fn ASN1_UTCTIME_cmp_time_t first appeared in OpenSSL 0.9.6 and has been available since .Ox 2.9 . .Pp .Fn ASN1_TIME_check and .Fn ASN1_TIME_to_generalizedtime first appeared in OpenSSL 0.9.7 and have been available since .Ox 3.2 . .Pp .Fn ASN1_TIME_adj , .Fn ASN1_UTCTIME_adj , .Fn ASN1_GENERALIZEDTIME_adj , and .Fn ASN1_TIME_set_string first appeared in OpenSSL 1.0.0 and have been available since .Ox 4.9 . .Sh CAVEATS Some applications add offset times directly to a .Vt time_t value and pass the results to .Fn ASN1_TIME_set (or equivalent). This can cause problems as the .Vt time_t value can overflow on some systems resulting in unexpected results. New applications should use .Fn ASN1_TIME_adj instead and pass the offset value in the .Fa offset_sec and .Fa offset_day parameters instead of directly manipulating a .Vt time_t value. .Sh BUGS .Fn ASN1_TIME_print , .Fn ASN1_UTCTIME_print , and .Fn ASN1_GENERALIZEDTIME_print do not print the time zone: they either print "GMT" or nothing. But all certificates complying with RFC 5280 et al use GMT anyway.