mirror of
https://github.com/openssl/openssl.git
synced 2024-12-21 06:09:35 +08:00
1a68e5b0d9
Using Zeller's congruence to fill the day of week field, Also populate the day of year field. Add unit test to cover a number of cases. Reviewed-by: Rich Salz <rsalz@openssl.org> (Merged from https://github.com/openssl/openssl/pull/3999)
167 lines
6.2 KiB
Plaintext
167 lines
6.2 KiB
Plaintext
=pod
|
|
|
|
=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
|
|
|
|
=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);
|
|
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_TIME_check(const ASN1_TIME *t);
|
|
int ASN1_TIME_print(BIO *b, const ASN1_TIME *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);
|
|
|
|
=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.
|
|
|
|
ASN1_TIME_adj() sets the ASN1_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
|
|
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.
|
|
|
|
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
|
|
that RFC 5280 requires, which means it only allows YYMMDDHHMMSSZ and
|
|
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>.
|
|
|
|
ASN1_TIME_print() prints out the time 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.
|
|
|
|
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.
|
|
The B<tm_sec>, B<tm_min>, B<tm_hour>, B<tm_mday>, B<tm_wday>, B<tm_yday>,
|
|
B<tm_mon> and B<tm_year> fields of B<tm> structure are set to proper values,
|
|
whereas all other fields are set to 0. If B<tm> is NULL this function performs
|
|
a format check on B<s> only.
|
|
|
|
ASN1_TIME_diff() sets B<*pday> and B<*psec> to the time difference between
|
|
B<from> and B<to>. If B<to> represents a time later than B<from> then
|
|
one or both (depending on the time difference) of B<*pday> and B<*psec>
|
|
will be positive. If B<to> represents a time earlier than B<from> then
|
|
one or both of B<*pday> and B<*psec> will be negative. If B<to> and B<from>
|
|
represent the same time then B<*pday> and B<*psec> will both be zero.
|
|
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.
|
|
|
|
=head1 NOTES
|
|
|
|
The ASN1_TIME structure corresponds to the ASN.1 structure B<Time>
|
|
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 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).
|
|
|
|
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 B<offset_sec> and B<offset_day> parameters instead of directly
|
|
manipulating a time_t value.
|
|
|
|
=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.
|
|
|
|
=head1 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);
|
|
|
|
Determine if one time is later or sooner than the current time:
|
|
|
|
int day, sec;
|
|
|
|
if (!ASN1_TIME_diff(&day, &sec, NULL, to))
|
|
/* Invalid time format */
|
|
|
|
if (day > 0 || sec > 0)
|
|
printf("Later\n");
|
|
else if (day < 0 || sec < 0)
|
|
printf("Sooner\n");
|
|
else
|
|
printf("Same\n");
|
|
|
|
=head1 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() and 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_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_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.
|
|
|
|
=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.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved.
|
|
|
|
Licensed under the OpenSSL license (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|