Sortix 1.1dev ports manual

This manual documents Sortix 1.1dev ports. You can instead view this document in the latest official manual.

ASN1_TIME_SET(3)

Library Functions Manual

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

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.

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.

June 6, 2019

Debian