NAME
ASN1_TIME_set,
ASN1_UTCTIME_set,
ASN1_GENERALIZEDTIME_set,
ASN1_TIME_adj,
ASN1_UTCTIME_adj,
ASN1_GENERALIZEDTIME_adj,
ASN1_TIME_set_string,
ASN1_TIME_set_string_X509,
ASN1_UTCTIME_set_string,
ASN1_GENERALIZEDTIME_set_string,
ASN1_TIME_normalize,
ASN1_TIME_check,
ASN1_UTCTIME_check,
ASN1_GENERALIZEDTIME_check,
ASN1_TIME_print,
ASN1_UTCTIME_print,
ASN1_GENERALIZEDTIME_print,
ASN1_TIME_to_tm,
ASN1_TIME_diff,
ASN1_TIME_cmp_time_t,
ASN1_UTCTIME_cmp_time_t,
ASN1_TIME_compare,
ASN1_TIME_to_generalizedtime,
OPENSSL_gmtime,
OPENSSL_timegm,
OPENSSL_posix_to_tm,
OPENSSL_tm_to_posix —
ASN.1 Time functions
SYNOPSIS
#include
<openssl/asn1.h>
ASN1_TIME *
ASN1_TIME_set(ASN1_TIME *s,
time_t t);
ASN1_UTCTIME *
ASN1_UTCTIME_set(ASN1_UTCTIME
*s, time_t t);
ASN1_GENERALIZEDTIME *
ASN1_GENERALIZEDTIME_set(ASN1_GENERALIZEDTIME
*s, time_t t);
ASN1_TIME *
ASN1_TIME_adj(ASN1_TIME *s,
time_t t, int offset_day,
long offset_sec);
ASN1_UTCTIME *
ASN1_UTCTIME_adj(ASN1_UTCTIME
*s, time_t t, int
offset_day, long offset_sec);
ASN1_GENERALIZEDTIME *
ASN1_GENERALIZEDTIME_adj(ASN1_GENERALIZEDTIME
*s, time_t t, int
offset_day, long offset_sec);
int
ASN1_TIME_set_string(ASN1_TIME
*s, const char *str);
int
ASN1_TIME_set_string_X509(ASN1_TIME
*s, const char *str);
int
ASN1_UTCTIME_set_string(ASN1_UTCTIME
*s, const char *str);
int
ASN1_GENERALIZEDTIME_set_string(ASN1_GENERALIZEDTIME
*s, const char *str);
int
ASN1_TIME_normalize(ASN1_TIME
*s);
int
ASN1_TIME_check(const ASN1_TIME
*t);
int
ASN1_UTCTIME_check(const ASN1_UTCTIME
*t);
int
ASN1_GENERALIZEDTIME_check(const
ASN1_GENERALIZEDTIME *t);
int
ASN1_TIME_print(BIO *b,
const ASN1_TIME *s);
int
ASN1_UTCTIME_print(BIO *b,
const ASN1_UTCTIME *s);
int
ASN1_GENERALIZEDTIME_print(BIO
*b, const ASN1_GENERALIZEDTIME *s);
int
ASN1_TIME_to_tm(const ASN1_TIME
*s, struct tm *tm);
int
ASN1_TIME_diff(int *pday,
int *psec, const ASN1_TIME
*from, const ASN1_TIME *to);
int
ASN1_TIME_cmp_time_t(const ASN1_TIME
*s, time_t t);
int
ASN1_UTCTIME_cmp_time_t(const
ASN1_UTCTIME *s, time_t t);
int
ASN1_TIME_compare(const ASN1_TIME
*s, const ASN1_TIME *t);
ASN1_GENERALIZEDTIME *
ASN1_TIME_to_generalizedtime(const
ASN1_TIME *t, ASN1_GENERALIZEDTIME **out);
#include
<openssl/crypto.h>
struct tm *
OPENSSL_gmtime(const time_t
*time, struct tm *out_tm);
#include
<openssl/posix_time.h>
int
OPENSSL_timegm(const struct tm
*tm, time_t *out_time);
int
OPENSSL_posix_to_tm(int64_t
time, struct tm *out_tm);
int
OPENSSL_tm_to_posix(struct tm
*t_tm, int64_t *out);
DESCRIPTION
An ASN1_TIME object is a shallow wrapper
around a string containing an ASN.1 Time value in the
restricted format valid in X.509 certificates. An
ASN1_TIME object is either an
ASN1_UTCTIME object containing a string of the format
YYMMDDHHMMSSZ which is valid
for the years 1950 to 2049, or an ASN1_GENERALIZEDTIME
object containing a string of the format
YYYYMMDDHHMMSSZ which is valid
for the years 0000 to 1949 and 2050 to 9999. In both cases, the mandatory
suffix ‘Z’ represents the GMT time
zone. LibreSSL by design does not support the full syntax of ASN.1 times. In
particular, it neither supports fractional seconds nor any other time
zone.
The functions
ASN1_TIME_set(),
ASN1_UTCTIME_set(),
and
ASN1_GENERALIZEDTIME_set()
set the time object s to the time represented by the
time_t value t. If
s is NULL, a new time object
is allocated and returned.
The functions
ASN1_TIME_adj(),
ASN1_UTCTIME_adj(),
and
ASN1_GENERALIZEDTIME_adj()
set the time object s to the time represented by the
time offset_day and offset_sec
after the time_t value t. The
values of offset_day or
offset_sec can be negative to set a time before
t. The offset_sec value can also
exceed the number of seconds in a day. If s is
NULL, a new time object is allocated and
returned.
ASN1_TIME_adj()
may change the type from ASN1_GENERALIZEDTIME to
ASN1_UTCTIME or vice versa depending on the resulting
year. The functions
ASN1_UTCTIME_adj()
and
ASN1_GENERALIZEDTIME_adj()
do not modify the type of the return object.
The functions
ASN1_TIME_set_string(),
ASN1_TIME_set_string_X509(),
ASN1_UTCTIME_set_string(),
and ASN1_GENERALIZEDTIME_set_string() set the time
object s to the time string str,
which must be in appropriate ASN.1 time format: YYMMDDHHMMSSZ for
ASN1_UTCTIME, YYYYMMDDHHMMSSZ for
ASN1_GENERALIZEDTIME, or either of the two for
ASN1_TIME. The string str is
copied into s. If s is
NULL, these functions only perform a format check on
str.
In LibreSSL,
ASN1_TIME_set_string()
and
ASN1_TIME_set_string_X509()
behave identically and always set the time object to a valid value to use in
an X.509 certificate.
ASN1_GENERALIZEDTIME_set_string()
may encode a time string that is not valid in an X.509 certificate.
The function
ASN1_TIME_normalize()
converts an ASN1_GENERALIZEDTIME into a time value
that can be used in a certificate by changing it to an
ASN1_UTCTIME if possible. It has no effect on an
ASN1_UTCTIME.
The functions
ASN1_TIME_check(),
ASN1_UTCTIME_check(),
and
ASN1_GENERALIZEDTIME_check()
check the syntax of the time string contained in the object
s.
The functions
ASN1_TIME_print(),
ASN1_UTCTIME_print(),
and
ASN1_GENERALIZEDTIME_print()
print out the time s to BIO
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 string has an invalid format, it
prints out "Bad time value" and returns an error.
The function
ASN1_TIME_to_tm()
converts the time s to the standard
tm structure. If s is
NULL, then the current time is converted. The output
time is always in the GMT time zone. The tm_sec,
tm_min, tm_hour,
tm_mday, tm_mon, and
tm_year fields of the tm
structure are set to the proper values, whereas all other fields are set to
0. If tm is NULL, this
function performs a format check on s only.
The function
ASN1_TIME_diff()
sets *pday and *psec to the time
difference between from and to.
If to represents a time later than
from, then one or both (depending on the time
difference) of *pday and *psec
will be positive. If to represents a time earlier than
from, then one or both of *pday
and *psec will be negative. If
to and from represent the same
time, then *pday and *psec will
both be zero. If both *pday and
*psec are nonzero, they will always have the same
sign. The value of *psec will always be less than the
number of seconds in a day. If from or
to is NULL, the current time
is used.
The functions
ASN1_TIME_cmp_time_t(),
ASN1_UTCTIME_cmp_time_t(),
and
ASN1_TIME_compare()
compare the two times represented by s and
t.
The function
ASN1_TIME_to_generalizedtime()
converts the ASN1_TIME t to an
ASN1_GENERALIZEDTIME, regardless of year. If either
out or *out is
NULL, then a new object is allocated and must be
freed after use.
The ASN1_TIME, ASN1_UTCTIME, and ASN1_GENERALIZEDTIME objects are represented as ASN1_STRING objects internally and can be freed using ASN1_STRING_free(3).
It is recommended that ASN1_TIME functions be used instead of ASN1_UTCTIME or ASN1_GENERALIZEDTIME functions because the ASN1_UTCTIME and ASN1_GENERALIZEDTIME functions act only on that specific time format, while the ASN1_TIME functions operate on either format.
OPENSSL_gmtime()
converts a time_t value in time to a struct tm in
out_tm and also returns the struct passed in on
success.
OPENSSL_timegm()
converts a time structure in UTC time in tm to a
time_t value in out_time.
OPENSSL_posix_to_tm()
converts an int64_t POSIX time value in
time, which must be in the range of year 0 to 9999, to
a broken out time value in tm.
OPENSSL_tm_to_posix()
converts a time value between the years 0 and 9999 in
tm to a POSIX time value in
out.
RETURN VALUES
ASN1_TIME_set(),
ASN1_UTCTIME_set(),
ASN1_GENERALIZEDTIME_set(),
ASN1_TIME_adj(),
ASN1_UTCTIME_adj(),
ASN1_GENERALIZEDTIME_adj(), and
ASN1_TIME_to_generalizedtime() return a pointer to a
time object or NULL if an error occurred.
ASN1_TIME_set_string(),
ASN1_TIME_set_string_X509(),
ASN1_UTCTIME_set_string(), and
ASN1_GENERALIZEDTIME_set_string() return 1 if the
time value is successfully set or 0 otherwise.
ASN1_TIME_normalize() returns 1 on success
or 0 on error.
ASN1_TIME_check(),
ASN1_UTCTIME_check(), and
ASN1_GENERALIZEDTIME_check() return 1 if the time
string contained in the object is syntactically correct or 0 otherwise.
ASN1_TIME_print(),
ASN1_UTCTIME_print(), and
ASN1_GENERALIZEDTIME_print() return 1 if the time is
successfully printed or 0 if an error occurred (I/O error or invalid time
format).
ASN1_TIME_to_tm() returns 1 if the time is
successfully parsed or 0 if an error occurred, usually due to an invalid
time format.
ASN1_TIME_diff() returns 1 for success or
0 for failure. It can for example fail if a time string passed in has
invalid syntax.
ASN1_TIME_cmp_time_t(),
ASN1_UTCTIME_cmp_time_t(), and
ASN1_TIME_compare() return -1 if
s is earlier than t, 0 if both
are equal, 1 if s is later than
t, or -2 on error.
OPENSSL_timegm() returns 1 for success or
0 for failure. It can fail if the time is not representable in a time_t, or
falls outside the range allowed in RFC 5280 times.
OPENSSL_gmtime() returns
out_tm on success or NULL for failure. It can fail if
the time is not representable in a struct tm, or falls outside the range
allowed in RFC 5280 times.
OPENSSL_posix_to_tm() and
OPENSSL_tm_to_posix() return 1 for success or 0 on
failure. It is a failure if the year is less than 0 or more than 9999.
EXAMPLES
Set a time object to one hour after the current time and print it out:
#include <time.h>
#include <openssl/asn1.h>
ASN1_TIME *asn1_time;
time_t t;
BIO *b;
t = time(NULL);
asn1_time = ASN1_TIME_adj(NULL, t, 0, 60 * 60);
b = BIO_new_fp(stdout, BIO_NOCLOSE);
if (asn1_time != NULL) {
ASN1_TIME_print(b, asn1_time);
BIO_printf(b, "\n");
} else {
BIO_printf(b, "Time out of range or un-representable\n");
}
ASN1_STRING_free(asn1_time);
BIO_free(b);
SEE ALSO
STANDARDS
The usage of the ASN.1 Time, UTCTime, and GeneralizedTime data types in X.509 certificates is specified in RFC 5280, Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile, section 4.1.2.5 (TBS Certificate Validity).
HISTORY
ASN1_UTCTIME_check() and
ASN1_UTCTIME_print() first appeared in SSLeay 0.5.1.
ASN1_UTCTIME_set() first appeared in SSLeay 0.6.0.
ASN1_UTCTIME_set_string() first appeared in SSLeay
0.9.0. All these functions have been available since
OpenBSD 2.4.
ASN1_TIME_set(),
ASN1_GENERALIZEDTIME_set(),
ASN1_GENERALIZEDTIME_set_string(),
ASN1_GENERALIZEDTIME_check(),
ASN1_TIME_print(), and
ASN1_GENERALIZEDTIME_print() first appeared in
OpenSSL 0.9.2b and have been available since OpenBSD
2.6.
ASN1_UTCTIME_cmp_time_t() first appeared
in OpenSSL 0.9.6 and has been available since OpenBSD
2.9.
ASN1_TIME_check() and
ASN1_TIME_to_generalizedtime() first appeared in
OpenSSL 0.9.7 and have been available since OpenBSD
3.2.
ASN1_TIME_adj(),
ASN1_UTCTIME_adj(),
ASN1_GENERALIZEDTIME_adj(), and
ASN1_TIME_set_string() first appeared in OpenSSL
1.0.0 and have been available since OpenBSD 4.9.
ASN1_TIME_diff() first appeared in OpenSSL
1.0.2 and have been available since OpenBSD 7.1.
ASN1_TIME_set_string_X509(),
ASN1_TIME_normalize(),
ASN1_TIME_to_tm(),
ASN1_TIME_cmp_time_t(), and
ASN1_TIME_compare() first appeared in OpenSSL 1.1.1
and have been available since OpenBSD 7.2.
OPENSSL_gmtime() first appeared in OpenSSL
0.9.7. OPENSSL_timegm(),
OPENSSL_posix_to_tm(), and
OPENSSL_tm_to_posix() first appeared in BoringSSL;
all these functions have been available since OpenBSD
7.5.
CAVEATS
Some applications add offset times directly to a
time_t value and pass the results to
ASN1_TIME_set() (or equivalent). This can cause
problems as the time_t value can overflow on some
systems resulting in unexpected results. New applications should use
ASN1_TIME_adj() instead and pass the offset value in
the offset_sec and offset_day
parameters instead of directly manipulating a time_t
value.