diff options
Diffstat (limited to 'doc/man3/ASN1_TIME_set.pod')
-rw-r--r-- | doc/man3/ASN1_TIME_set.pod | 154 |
1 files changed, 122 insertions, 32 deletions
diff --git a/doc/man3/ASN1_TIME_set.pod b/doc/man3/ASN1_TIME_set.pod index 2296296168..1bb5672457 100644 --- a/doc/man3/ASN1_TIME_set.pod +++ b/doc/man3/ASN1_TIME_set.pod @@ -2,41 +2,82 @@ =head1 NAME -ASN1_TIME_set, ASN1_TIME_adj, ASN1_TIME_check, -ASN1_TIME_set_string, ASN1_TIME_set_string_X509, -ASN1_TIME_print, ASN1_TIME_to_tm, ASN1_TIME_diff - ASN.1 Time functions +ASN1_TIME_set, ASN1_UTCTIME_set, ASN1_GENERALIZEDTIME_set, +ASN1_TIME_adj, ASN1_UTCTIME_adj, ASN1_GENERALIZEDTIME_adj, +ASN1_TIME_check, ASN1_UTCTIME_check, ASN1_GENERALIZEDTIME_check, +ASN1_TIME_set_string, ASN1_UTCTIME_set_string, ASN1_GENERALIZEDTIME_set_string, +ASN1_TIME_set_string_X509, +ASN1_TIME_normalize, +ASN1_TIME_to_tm, +ASN1_TIME_print, ASN1_UTCTIME_print, ASN1_GENERALIZEDTIME_print, +ASN1_TIME_diff, +ASN1_TIME_cmp_time_t, ASN1_UTCTIME_cmp_time_t, +ASN1_TIME_compare, +ASN1_TIME_to_generalizedtime - ASN.1 Time functions =head1 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); + 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_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 *a, const ASN1_TIME *b); + + ASN1_GENERALIZEDTIME *ASN1_TIME_to_generalizedtime(ASN1_TIME *t, + ASN1_GENERALIZEDTIME **out); =head1 DESCRIPTION -The function ASN1_TIME_set() sets the ASN1_TIME structure B<s> to the -time represented by the time_t value B<t>. If B<s> is NULL a new ASN1_TIME -structure is allocated and returned. +The ASN1_TIME_set(), ASN1_UTCTIME_set() and ASN1_GENERALIZEDTIME_set() +functions set the structure B<s> to the time represented by the time_t +value B<t>. If B<s> is NULL a new time structure is allocated and returned. -ASN1_TIME_adj() sets the ASN1_TIME structure B<s> to the time represented +The ASN1_TIME_adj(), ASN1_UTCTIME_adj() and ASN1_GENERALIZEDTIME_adj() +functions set the time structure B<s> to the time represented by the time B<offset_day> and B<offset_sec> after the time_t value B<t>. The values of B<offset_day> or B<offset_sec> can be negative to set a time before B<t>. The B<offset_sec> value can also exceed the number of -seconds in a day. If B<s> is NULL a new ASN1_TIME structure is allocated +seconds in a day. If B<s> is NULL a new structure is allocated and returned. -ASN1_TIME_set_string() sets ASN1_TIME structure B<s> to the time -represented by string B<str> which must be in appropriate ASN.1 time -format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). If B<s> is NULL -this function performs a format check on B<str> only. +The ASN1_TIME_set_string(), ASN1_UTCTIME_set_string() and +ASN1_GENERALIZEDTIME_set_string() functions set the time structure B<s> +to the time represented by string B<str> which must be in appropriate ASN.1 +time format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). If B<s> is NULL +this function performs a format check on B<str> only. The string B<str> +is copied into B<s>. ASN1_TIME_set_string_X509() sets ASN1_TIME structure B<s> to the time represented by string B<str> which must be in appropriate time format @@ -45,13 +86,21 @@ YYYYMMDDHHMMSSZ (leap second is rejected), all other ASN.1 time format are not allowed. If B<s> is NULL this function performs a format check on B<str> only. -ASN1_TIME_check() checks the syntax of ASN1_TIME structure B<s>. +The ASN1_TIME_normalize() function converts an ASN1_GENERALIZEDTIME or +ASN1_UTCTIME into a time value that can be used in a certificate. It +should be used after the ASN1_TIME_set_string() functions and before +ASN1_TIME_print() functions to get consistent (i.e. GMT) results. + +The ASN1_TIME_check(), ASN1_UTCTIME_check() and ASN1_GENERALIZEDTIME_check() +functions check the syntax of the time structure B<s>. -ASN1_TIME_print() prints out the time B<s> to BIO B<b> in human readable +The ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() +functions print the time structure B<s> to BIO B<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 invalid format it prints out "Bad time value" and returns -an error. +an error. The output for generalized time may include a fractional part +following the second. ASN1_TIME_to_tm() converts the time B<s> to the standard B<tm> structure. If B<s> is NULL, then the current time is converted. The output time is GMT. @@ -72,6 +121,16 @@ If both B<*pday> and B<*psec> are non-zero they will always have the same sign. The value of B<*psec> will always be less than the number of seconds in a day. If B<from> or B<to> is NULL the current time is used. +The ASN1_TIME_cmp_time_t() and ASN1_UTCTIME_cmp_time_t() functions compare +the two times represented by the time structure B<s> and the time_t B<t>. + +The ASN1_TIME_compare() function compares the two times represented by the +time structures B<a> and B<b>. + +The ASN1_TIME_to_generalizedtime() function converts an ASN1_TIME to an +ASN1_GENERALIZEDTIME, regardless of year. If either B<out> or +B<*out> are NULL, then a new object is allocated and must be freed after use. + =head1 NOTES The ASN1_TIME structure corresponds to the ASN.1 structure B<Time> @@ -79,13 +138,15 @@ defined in RFC5280 et al. The time setting functions obey the rules outlined in RFC5280: if the date can be represented by UTCTime it is used, else GeneralizedTime is used. -The ASN1_TIME structure is represented as an ASN1_STRING internally and can -be freed up using ASN1_STRING_free(). +The ASN1_TIME, ASN1_UTCTIME and ASN1_GENERALIZEDTIME structures are represented +as an ASN1_STRING internally and can be freed up using ASN1_STRING_free(). 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. + 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. @@ -93,11 +154,24 @@ New applications should use ASN1_TIME_adj() instead and pass the offset value in the B<offset_sec> and B<offset_day> parameters instead of directly manipulating a time_t value. +ASN1_TIME_adj() may change the type from ASN1_GENERALIZEDTIME to ASN1_UTCTIME, +or vise-versa, based on the resulting year. The ASN1_GENERALIZEDTIME_adj() and +ASN1_UTCTIME_adj() functions will not modify the type of the return structure. + +It is recommended that functions starting with ASN1_TIME be used instead of +those starting with ASN1_UTCTIME or ASN1_GENERALIZEDTIME. The functions +starting with ASN1_UTCTIME and ASN1_GENERALIZEDTIME act only on that specific +time format. The functions starting with ASN1_TIME will operate on either +format. + =head1 BUGS -ASN1_TIME_print() currently does not print out the time zone: it either prints -out "GMT" or nothing. But all certificates complying with RFC5280 et al use GMT -anyway. +ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() +do not print out the time zone: it either prints out "GMT" or nothing. But all +certificates complying with RFC5280 et al use GMT anyway. + +Use the ASN1_TIME_normalize() function to normalize the time value before +printing to get GMT results. =head1 EXAMPLES @@ -133,28 +207,44 @@ Determine if one time is later or sooner than the current time: =head1 RETURN VALUES -ASN1_TIME_set() and ASN1_TIME_adj() return a pointer to an ASN1_TIME structure +ASN1_TIME_set(), ASN1_UTCTIME_set(), ASN1_GENERALIZEDTIME_set(), ASN1_TIME_adj(), +ASN1_UTCTIME_adj and ASN1_GENERALIZEDTIME_set return a pointer to a time structure or NULL if an error occurred. -ASN1_TIME_set_string() and ASN1_TIME_set_string_X509() return 1 if the time -value is successfully set and 0 otherwise. +ASN1_TIME_set_string(), ASN1_UTCTIME_set_string(), ASN1_GENERALIZEDTIME_set_string() +ASN1_TIME_set_string_X509() return 1 if the time value is successfully set and 0 otherwise. -ASN1_TIME_check() returns 1 if the structure is syntactically correct and 0 -otherwise. +ASN1_TIME_normalize() returns 1 on success, and 0 on error. -ASN1_TIME_print() returns 1 if the time is successfully printed out and 0 if -an error occurred (I/O error or invalid time format). +ASN1_TIME_check(), ASN1_UTCTIME_check and ASN1_GENERALIZEDTIME_check() return 1 +if the structure is syntactically correct and 0 otherwise. + +ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() return 1 +if the time is successfully printed out and 0 if an error occurred (I/O error or +invalid time format). ASN1_TIME_to_tm() returns 1 if the time is successfully parsed and 0 if an error occured (invalid time format). ASN1_TIME_diff() returns 1 for success and 0 for failure. It can fail if the -pass ASN1_TIME structure has invalid syntax for example. +passed-in time structure has invalid syntax, for example. + +ASN1_TIME_cmp_time_t() and ASN1_UTCTIME_cmp_time_t() return -1 if B<s> is +before B<t>, 0 if B<s> equals B<t>, or 1 if B<s> is after B<t>. -2 is returned +on error. + +ASN1_TIME_compare() returns -1 if B<a> is before B<b>, 0 if B<a> equals B<b>, or 1 if B<a> is after B<b>. -2 is returned on error. + +ASN1_TIME_to_generalizedtime() returns a pointer to +the appropriate time structure on success or NULL if an error occurred. =head1 HISTORY The ASN1_TIME_to_tm() function was added in OpenSSL 1.1.1. The ASN1_TIME_set_string_X509() function was added in OpenSSL 1.1.1. +The ASN1_TIME_normalize() function was added in OpenSSL 1.1.1. +The ASN1_TIME_cmp_time_t() function was added in OpenSSL 1.1.1. +The ASN1_TIME_compare() function was added in OpenSSL 1.1.1. =head1 COPYRIGHT |