From 61e1293a14728599b7160bc57f2773db4f0e3df9 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Thu, 10 Nov 2022 17:44:05 +0000 Subject: In asn1.h rev. 1.65, beck@ provided ASN1_TIME_set_string_X509(3), ASN1_TIME_normalize(3), ASN1_TIME_to_tm(3), ASN1_TIME_cmp_time_t(3), and ASN1_TIME_compare(3). Merge documentation from the OpenSSL 1.1.1 branch, which is still under a free license, with tweaks by me in several respects to match our implementation, and also using some feedback from beck@. OK beck@. --- src/lib/libcrypto/man/ASN1_TIME_set.3 | 150 +++++++++++++++++++++++++++++++--- 1 file changed, 139 insertions(+), 11 deletions(-) (limited to 'src/lib') diff --git a/src/lib/libcrypto/man/ASN1_TIME_set.3 b/src/lib/libcrypto/man/ASN1_TIME_set.3 index cd6ab937d0..b8a567ece0 100644 --- a/src/lib/libcrypto/man/ASN1_TIME_set.3 +++ b/src/lib/libcrypto/man/ASN1_TIME_set.3 @@ -1,8 +1,25 @@ -.\" $OpenBSD: ASN1_TIME_set.3,v 1.17 2022/03/31 17:27:16 naddy Exp $ -.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 +.\" $OpenBSD: ASN1_TIME_set.3,v 1.18 2022/11/10 17:44:05 schwarze Exp $ +.\" full merge up to: OpenSSL 3d0f1cb9 Jul 11 03:01:24 2017 +0800 .\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 .\" -.\" This file was written by Dr. Stephen Henson +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2022 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" The original file was written by Dr. Stephen Henson .\" and Todd Short . .\" Copyright (c) 2015, 2017 The OpenSSL Project. All rights reserved. .\" @@ -50,7 +67,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: March 31 2022 $ +.Dd $Mdocdate: November 10 2022 $ .Dt ASN1_TIME_SET 3 .Os .Sh NAME @@ -61,16 +78,21 @@ .Nm ASN1_UTCTIME_adj , .Nm ASN1_GENERALIZEDTIME_adj , .Nm ASN1_TIME_set_string , +.Nm ASN1_TIME_set_string_X509 , .Nm ASN1_UTCTIME_set_string , .Nm ASN1_GENERALIZEDTIME_set_string , +.Nm ASN1_TIME_normalize , .Nm ASN1_TIME_check , .Nm ASN1_UTCTIME_check , .Nm ASN1_GENERALIZEDTIME_check , .Nm ASN1_TIME_print , .Nm ASN1_UTCTIME_print , .Nm ASN1_GENERALIZEDTIME_print , +.Nm ASN1_TIME_to_tm , .Nm ASN1_TIME_diff , +.Nm ASN1_TIME_cmp_time_t , .Nm ASN1_UTCTIME_cmp_time_t , +.Nm ASN1_TIME_compare , .Nm ASN1_TIME_to_generalizedtime .Nd ASN.1 Time functions .Sh SYNOPSIS @@ -117,6 +139,11 @@ .Fa "const char *str" .Fc .Ft int +.Fo ASN1_TIME_set_string_X509 +.Fa "ASN1_TIME *s" +.Fa "const char *str" +.Fc +.Ft int .Fo ASN1_UTCTIME_set_string .Fa "ASN1_UTCTIME *s" .Fa "const char *str" @@ -127,6 +154,10 @@ .Fa "const char *str" .Fc .Ft int +.Fo ASN1_TIME_normalize +.Fa "ASN1_TIME *s" +.Fc +.Ft int .Fo ASN1_TIME_check .Fa "const ASN1_TIME *t" .Fc @@ -154,6 +185,11 @@ .Fa "const ASN1_GENERALIZEDTIME *s" .Fc .Ft int +.Fo ASN1_TIME_to_tm +.Fa "const ASN1_TIME *s" +.Fa "struct tm *tm" +.Fc +.Ft int .Fo ASN1_TIME_diff .Fa "int *pday" .Fa "int *psec" @@ -161,10 +197,20 @@ .Fa "const ASN1_TIME *to" .Fc .Ft int +.Fo ASN1_TIME_cmp_time_t +.Fa "const ASN1_TIME *s" +.Fa "time_t t" +.Fc +.Ft int .Fo ASN1_UTCTIME_cmp_time_t .Fa "const ASN1_UTCTIME *s" .Fa "time_t t" .Fc +.Ft int +.Fo ASN1_TIME_compare +.Fa "const ASN1_TIME *s" +.Fa "const ASN1_TIME *t" +.Fc .Ft ASN1_GENERALIZEDTIME * .Fo ASN1_TIME_to_generalizedtime .Fa "const ASN1_TIME *t" @@ -232,6 +278,7 @@ do not modify the type of the return structure. .Pp The functions .Fn ASN1_TIME_set_string , +.Fn ASN1_TIME_set_string_X509 , .Fn ASN1_UTCTIME_set_string , and .Fn ASN1_GENERALIZEDTIME_set_string @@ -239,8 +286,13 @@ set the time structure .Fa s to the time represented by the string .Fa str , -which must be in appropriate ASN.1 time format (for example -YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). +which must be in appropriate ASN.1 time format: +YYMMDDHHMMSSZ for +.Vt ASN1_UTCTIME , +YYYYMMDDHHMMSSZ for +.Vt ASN1_GENERALIZEDTIME , +or either of the two for +.Vt ASN1_TIME . The string .Fa str is copied into @@ -252,6 +304,30 @@ is these functions only perform a format check on .Fa str . .Pp +In LibreSSL, +.Fn ASN1_TIME_set_string +and +.Fn ASN1_TIME_set_string_X509 +behave identically. +In other implementations, +.Fn ASN1_TIME_set_string , +.Fn ASN1_UTCTIME_set_string , +and +.Fn ASN1_GENERALIZEDTIME_set_string +may accept additional formats that violate RFC 5280. +.Pp +The function +.Fn ASN1_TIME_normalize +converts an +.Vt ASN1_GENERALIZEDTIME +or +.Vt ASN1_UTCTIME +into a time value that can be used in a certificate. +It is intended to be used after the +.Fn ASN1_TIME_set_string +functions to ensure the value is valid for use as an +.Vt ASN1_TIME . +.Pp The functions .Fn ASN1_TIME_check , .Fn ASN1_UTCTIME_check , @@ -281,6 +357,35 @@ The output of may include a fractional part following the second. .Pp The function +.Fn ASN1_TIME_to_tm +converts the time +.Fa s +to the standard +.Vt tm +structure. +If +.Fa s +is +.Dv NULL , +then the current time is converted. +The output time is GMT. +The +.Fa tm_sec , tm_min , tm_hour , tm_mday , tm_mon , +and +.Fa tm_year +fields of the +.Vt tm +structure are set to the proper values, +whereas all other fields are set to 0. +If +.Fa tm +is +.Dv NULL , +this function performs a format check on +.Fa s +only. +.Pp +The function .Fn ASN1_TIME_diff sets .Pf * Fa pday @@ -333,9 +438,12 @@ is .Dv NULL , the current time is used. .Pp -The function -.Fn ASN1_UTCTIME_cmp_time_t -compares the two times represented by +The functions +.Fn ASN1_TIME_cmp_time_t , +.Fn ASN1_UTCTIME_cmp_time_t , +and +.Fn ASN1_TIME_compare +compare the two times represented by .Fa s and .Fa t . @@ -411,11 +519,15 @@ return a pointer to a time structure or if an error occurred. .Pp .Fn ASN1_TIME_set_string , +.Fn ASN1_TIME_set_string_X509 , .Fn ASN1_UTCTIME_set_string , and .Fn ASN1_GENERALIZEDTIME_set_string return 1 if the time value is successfully set or 0 otherwise. .Pp +.Fn ASN1_TIME_normalize +returns 1 on success or 0 on error. +.Pp .Fn ASN1_TIME_check , .Fn ASN1_UTCTIME_check , and @@ -429,12 +541,19 @@ and return 1 if the time is successfully printed or 0 if an error occurred (I/O error or invalid time format). .Pp +.Fn ASN1_TIME_to_tm +returns 1 if the time is successfully parsed +or 0 if an error occurred, usually due to an invalid time format. +.Pp .Fn ASN1_TIME_diff returns 1 for success or 0 for failure. It can for example fail if a time structure passed in has invalid syntax. .Pp -.Fn ASN1_UTCTIME_cmp_time_t -returns \-1 if +.Fn ASN1_TIME_cmp_time_t , +.Fn ASN1_UTCTIME_cmp_time_t , +and +.Fn ASN1_TIME_compare +return \-1 if .Fa s is earlier than .Fa t , @@ -508,6 +627,15 @@ first appeared in OpenSSL 1.0.0 and have been available since .Fn ASN1_TIME_diff first appeared in OpenSSL 1.0.2 and have been available since .Ox 7.1 . +.Pp +.Fn ASN1_TIME_set_string_X509 , +.Fn ASN1_TIME_normalize , +.Fn ASN1_TIME_to_tm , +.Fn ASN1_TIME_cmp_time_t , +and +.Fn ASN1_TIME_compare +first appeared in OpenSSL 1.1.1 and have been available since +.Ox 7.2 . .Sh CAVEATS Some applications add offset times directly to a .Vt time_t -- cgit v1.2.3-55-g6feb