X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=doc%2Fman3%2FASN1_TIME_set.pod;h=b3163ad53952304e817325c2962b55aab64ce1d5;hb=HEAD;hp=5f041a575c926979348cd10c15d9d5eeaca30f0c;hpb=04e62715db684d83bffac53793ff4cfac51e047a;p=oweals%2Fopenssl.git

diff --git a/doc/man3/ASN1_TIME_set.pod b/doc/man3/ASN1_TIME_set.pod
index 5f041a575c..b3163ad539 100644
--- a/doc/man3/ASN1_TIME_set.pod
+++ b/doc/man3/ASN1_TIME_set.pod
@@ -2,98 +2,225 @@
 
 =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,
+ASN1_TIME_dup, ASN1_UTCTIME_dup, ASN1_GENERALIZEDTIME_dup - 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);
+
+ ASN1_TIME *ASN1_TIME_dup(const ASN1_TIME *t);
+ ASN1_UTCTIME *ASN1_UTCTIME_dup(const ASN1_UTCTIME *t);
+ ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_dup(const ASN1_GENERALIZEDTIME *t);
 
 =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 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.
 
-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
+The ASN1_TIME_adj(), ASN1_UTCTIME_adj() and ASN1_GENERALIZEDTIME_adj()
+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.
 
-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 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 ASN1_TIME structure B<s> to the time
-represented by string B<str> which must be in appropriate time format
+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.
 
-ASN1_TIME_check() checks the syntax of ASN1_TIME structure B<s>.
+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.
 
-ASN1_TIME_print() prints out the time B<s> to BIO B<b> in human readable
+The ASN1_TIME_check(), ASN1_UTCTIME_check() and ASN1_GENERALIZEDTIME_check()
+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 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.
-
-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.
-Only the B<tm_sec>, B<tm_min>, B<tm_hour>, B<tm_mday>, B<tm_mon> and B<tm_year>
-fields are updated.
-
-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.
+an error. The output for generalized time may include a fractional part
+following the second.
+
+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 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 nonzero 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 I<s> and the time_t I<t>.
+
+The ASN1_TIME_compare() function compares the two times represented by the
+time structures I<a> and I<b>.
+
+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.
+
+The ASN1_TIME_dup(), ASN1_UTCTIME_dup() and ASN1_GENERALIZEDTIME_dup() functions
+duplicate the time structure I<t> and return the duplicated result
+correspondingly.
 
 =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 structure is 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).
 
+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 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 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
 
-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 timezone: 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 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_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_to_tm() returns 1 if the time is successfully parsed and 0 if an
+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 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 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_dup(), ASN1_UTCTIME_dup() and ASN1_GENERALIZEDTIME_dup() return a
+pointer to a time structure or NULL if an error occurred.
 
 =head1 EXAMPLES
 
@@ -127,36 +254,19 @@ Determine if one time is later or sooner than the current time:
  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.
+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
 
-Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+Licensed under the Apache License 2.0 (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>.