ASN1_TIME_SET(3)

NAME
ASN1_TIME_set, ASN1_TIME_adj, ASN1_TIME_set_string, ASN1_TIME_check, ASN1_TIME_print - ASN.1 Time functions

SYNOPSIS
ASN1_TIME *
ASN1_TIME_set(ASN1_TIME *s, time_t t);
ASN1_TIME *
ASN1_TIME_adj(ASN1_TIME *s, time_t t, int offset_day, long offset_sec);
int
ASN1_TIME_set_string(ASN1_TIME *s, const char *str);
int
ASN1_TIME_check(const ASN1_TIME *t);
int
ASN1_TIME_print(BIO *b, const ASN1_TIME *s);

DESCRIPTION
The function ASN1_TIME_set() sets the ASN1_TIME structure s to the time represented by the time_t value t. If s is NULL, a new ASN1_TIME structure is allocated and returned.

ASN1_TIME_adj() sets the ASN1_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 ASN1_TIME structure is allocated and returned.

ASN1_TIME_set_string() sets the ASN1_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).

ASN1_TIME_check() checks the syntax of the ASN1_TIME structure s.

ASN1_TIME_print() prints 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 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 structure is represented as an ASN1_STRING internally and can be freed up 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).

RETURN VALUES
ASN1_TIME_set() and ASN1_TIME_adj() return a pointer to an ASN1_TIME structure or NULL if an error occurred.

ASN1_TIME_set_string() returns 1 if the time value is successfully set or 0 otherwise.

ASN1_TIME_check() returns 1 if the structure is syntactically correct or 0 otherwise.

ASN1_TIME_print() returns 1 if the time is successfully printed out or 0 if an error occurred (I/O error or invalid time format).

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);

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() currently does not print out the time zone: it either prints out "GMT" or nothing. But all certificates complying with RFC 5280 et al use GMT anyway.