|
@@ -61,108 +61,110 @@ ASN1_TIME_to_generalizedtime - ASN.1 Time functions
|
|
|
=head1 DESCRIPTION
|
|
|
|
|
|
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.
|
|
|
+functions set the structure I<s> to the time represented by the time_t
|
|
|
+value I<t>. If I<s> is NULL a new time structure is allocated and returned.
|
|
|
|
|
|
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 structure is allocated
|
|
|
+functions set the time structure I<s> to the time represented
|
|
|
+by the time I<offset_day> and I<offset_sec> after the time_t value I<t>.
|
|
|
+The values of I<offset_day> or I<offset_sec> can be negative to set a
|
|
|
+time before I<t>. The I<offset_sec> value can also exceed the number of
|
|
|
+seconds in a day. If I<s> is NULL a new structure is allocated
|
|
|
and returned.
|
|
|
|
|
|
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
|
|
|
+ASN1_GENERALIZEDTIME_set_string() functions set the time structure I<s>
|
|
|
+to the time represented by string I<str> which must be in appropriate ASN.1
|
|
|
+time format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). If I<s> is NULL
|
|
|
+this function performs a format check on I<str> only. The string I<str>
|
|
|
+is copied into I<s>.
|
|
|
+
|
|
|
+ASN1_TIME_set_string_X509() sets B<ASN1_TIME> structure I<s> to the time
|
|
|
+represented by string I<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.
|
|
|
+are not allowed. If I<s> is NULL this function performs a format check
|
|
|
+on I<str> only.
|
|
|
|
|
|
-The ASN1_TIME_normalize() function converts an ASN1_GENERALIZEDTIME or
|
|
|
-ASN1_UTCTIME into a time value that can be used in a certificate. It
|
|
|
+The ASN1_TIME_normalize() function converts an B<ASN1_GENERALIZEDTIME> or
|
|
|
+B<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>.
|
|
|
+functions check the syntax of the time structure I<s>.
|
|
|
|
|
|
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
|
|
|
+functions print the time structure I<s> to BIO I<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. 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.
|
|
|
-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. If B<s> is in Generalized format with fractional
|
|
|
+ASN1_TIME_to_tm() converts the time I<s> to the standard I<tm> structure.
|
|
|
+If I<s> is NULL, then the current time is converted. The output time is GMT.
|
|
|
+The I<tm_sec>, I<tm_min>, I<tm_hour>, I<tm_mday>, I<tm_wday>, I<tm_yday>,
|
|
|
+I<tm_mon> and I<tm_year> fields of I<tm> structure are set to proper values,
|
|
|
+whereas all other fields are set to 0. If I<tm> is NULL this function performs
|
|
|
+a format check on I<s> only. If I<s> is in Generalized format with fractional
|
|
|
seconds, e.g. YYYYMMDDHHMMSS.SSSZ, the fractional seconds will be lost while
|
|
|
-converting B<s> to B<tm> structure.
|
|
|
-
|
|
|
-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.
|
|
|
+converting I<s> to I<tm> structure.
|
|
|
+
|
|
|
+ASN1_TIME_diff() sets I<*pday> and I<*psec> to the time difference between
|
|
|
+I<from> and I<to>. If I<to> represents a time later than I<from> then
|
|
|
+one or both (depending on the time difference) of I<*pday> and I<*psec>
|
|
|
+will be positive. If I<to> represents a time earlier than I<from> then
|
|
|
+one or both of I<*pday> and I<*psec> will be negative. If I<to> and I<from>
|
|
|
+represent the same time then I<*pday> and I<*psec> will both be zero.
|
|
|
+If both I<*pday> and I<*psec> are non-zero they will always have the same
|
|
|
+sign. The value of I<*psec> will always be less than the number of seconds
|
|
|
+in a day. If I<from> or I<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 two times represented by the time structure I<s> and the time_t I<t>.
|
|
|
|
|
|
The ASN1_TIME_compare() function compares the two times represented by the
|
|
|
-time structures B<a> and B<b>.
|
|
|
+time structures I<a> and I<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.
|
|
|
+The ASN1_TIME_to_generalizedtime() function converts an B<ASN1_TIME> to an
|
|
|
+B<ASN1_GENERALIZEDTIME>, regardless of year. If either I<out> or
|
|
|
+I<*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>
|
|
|
+The B<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, ASN1_UTCTIME and ASN1_GENERALIZEDTIME structures are represented
|
|
|
-as an ASN1_STRING internally and can be freed up using ASN1_STRING_free().
|
|
|
+The B<ASN1_TIME>, B<ASN1_UTCTIME> and B<ASN1_GENERALIZEDTIME> structures are
|
|
|
+represented as an B<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
|
|
|
+The B<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.
|
|
|
+B<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.
|
|
|
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
|
|
|
+in the I<offset_sec> and I<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 vice versa, based on the resulting year. The ASN1_GENERALIZEDTIME_adj() and
|
|
|
-ASN1_UTCTIME_adj() functions will not modify the type of the return structure.
|
|
|
+ASN1_TIME_adj() may change the type from B<ASN1_GENERALIZEDTIME> to
|
|
|
+B<ASN1_UTCTIME>, or vice versa, based on the resulting year.
|
|
|
+ASN1_GENERALIZEDTIME_adj() and ASN1_UTCTIME_adj() 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.
|
|
|
+It is recommended that functions starting with B<ASN1_TIME> be used instead of
|
|
|
+those starting with B<ASN1_UTCTIME> or B<ASN1_GENERALIZEDTIME>. The functions
|
|
|
+starting with B<ASN1_UTCTIME> and B<ASN1_GENERALIZEDTIME> act only on that
|
|
|
+specific time format. The functions starting with B<ASN1_TIME> will operate on
|
|
|
+either format.
|
|
|
|
|
|
=head1 BUGS
|
|
|
|
|
@@ -175,21 +177,22 @@ printing to get GMT results.
|
|
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
|
|
-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(), 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(), 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_set_string(), ASN1_UTCTIME_set_string(),
|
|
|
+ASN1_GENERALIZEDTIME_set_string() and ASN1_TIME_set_string_X509() return
|
|
|
+1 if the time value is successfully set and 0 otherwise.
|
|
|
|
|
|
ASN1_TIME_normalize() returns 1 on success, and 0 on error.
|
|
|
|
|
|
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_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 occurred (invalid time format).
|
|
@@ -197,14 +200,15 @@ error occurred (invalid time format).
|
|
|
ASN1_TIME_diff() returns 1 for success and 0 for failure. It can fail if the
|
|
|
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
|
|
|
+ASN1_TIME_cmp_time_t() and ASN1_UTCTIME_cmp_time_t() return -1 if I<s> is
|
|
|
+before I<t>, 0 if I<s> equals I<t>, or 1 if I<s> is after I<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_compare() returns -1 if I<a> is before I<b>, 0 if I<a> equals I<b>,
|
|
|
+or 1 if I<a> is after I<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.
|
|
|
+ASN1_TIME_to_generalizedtime() returns a pointer to the appropriate time
|
|
|
+structure on success or NULL if an error occurred.
|
|
|
|
|
|
=head1 EXAMPLES
|
|
|
|