ASN1_TIME_SET(3)

NAME
ASN1_TIME_set, ASN1_UTCTIME_set, ASN1_GENERALIZEDTIME_set, ASN1_TIME_adj, ASN1_UTCTIME_adj, ASN1_GENERALIZEDTIME_adj, ASN1_TIME_set_string, ASN1_UTCTIME_set_string, ASN1_GENERALIZEDTIME_set_string, ASN1_TIME_check, ASN1_UTCTIME_check, ASN1_GENERALIZEDTIME_check, ASN1_TIME_print, ASN1_UTCTIME_print, ASN1_GENERALIZEDTIME_print, ASN1_TIME_diff, ASN1_UTCTIME_cmp_time_t, ASN1_TIME_to_generalizedtime - 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_UTCTIME_set_string(ASN1_UTCTIME *s, const char *str);
int
ASN1_GENERALIZEDTIME_set_string(ASN1_GENERALIZEDTIME *s, const char *str);
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_diff(int *pday, int *psec, const ASN1_TIME *from, const ASN1_TIME *to);
int
ASN1_UTCTIME_cmp_time_t(const ASN1_UTCTIME *s, time_t t);
ASN1_GENERALIZEDTIME *
ASN1_TIME_to_generalizedtime(const ASN1_TIME *t, ASN1_GENERALIZEDTIME **out);

DESCRIPTION
The functions ASN1_TIME_set(), ASN1_UTCTIME_set(), and ASN1_GENERALIZEDTIME_set() set the time structure s to the time represented by the time_t value t. If s is NULL, a new time structure is allocated and returned.

The functions ASN1_TIME_adj(), ASN1_UTCTIME_adj(), and ASN1_GENERALIZEDTIME_adj() set the time structure 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 structure 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 structure.

The functions ASN1_TIME_set_string(), ASN1_UTCTIME_set_string(), and ASN1_GENERALIZEDTIME_set_string() set the time structure s to the time represented by the string str, which must be in appropriate ASN.1 time format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). The string str is copied into s. If s is NULL, these functions only perform a format check on str.

The functions ASN1_TIME_check(), ASN1_UTCTIME_check(), and ASN1_GENERALIZEDTIME_check() check the syntax of the time structure 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 structure has an invalid format, it prints out "Bad time value" and returns an error. The output of ASN1_GENERALIZEDTIME_print() may include a fractional part following the second.

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 function ASN1_UTCTIME_cmp_time_t() compares 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 structure corresponds to the ASN.1 structure 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.

The ASN1_TIME, ASN1_UTCTIME, and ASN1_GENERALIZEDTIME structures are represented as ASN1_STRING structures internally and can be freed using ASN1_STRING_free(3).

The 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).

ASN1_UTCTIME is limited to a year range of 1950 through 2049.

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.

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 structure or NULL if an error occurred.

ASN1_TIME_set_string(), ASN1_UTCTIME_set_string(), and ASN1_GENERALIZEDTIME_set_string() return 1 if the time value is successfully set or 0 otherwise.

ASN1_TIME_check(), ASN1_UTCTIME_check(), and ASN1_GENERALIZEDTIME_check() return 1 if the time structure 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_diff() returns 1 for success or 0 for failure. It can for example fail if a time structure passed in has invalid syntax.

ASN1_UTCTIME_cmp_time_t() returns -1 if s is earlier than t, 0 if both are equal, 1 if s is later than t, or -2 on error.

EXAMPLES
Set a time structure to one hour after the current time and print it out:

    #include <time.h>
    #include <openssl/asn1.h>
    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);

SEE ALSO
ASN1_TIME_new(3), ASN1_time_parse(3), X509_cmp_time(3)

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.

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.

BUGS
ASN1_TIME_print(), ASN1_UTCTIME_print(), and 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.