From d531af76dfc13a2772c8ce8d4017ff9a84b02dcc Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Sun, 20 Aug 2017 17:16:40 +0000 Subject: Sync with OpenSSL: document several new functions, plus some additional minor improvements. Mostly from Todd Short via OpenSSL commit cf37aaa3 Aug 4 11:24:03 2017 +1000. --- src/lib/libcrypto/man/ASN1_TIME_set.3 | 275 ++++++++++++++++++++++++++++------ 1 file changed, 227 insertions(+), 48 deletions(-) (limited to 'src') diff --git a/src/lib/libcrypto/man/ASN1_TIME_set.3 b/src/lib/libcrypto/man/ASN1_TIME_set.3 index 830fa39242..5fc6edb3db 100644 --- a/src/lib/libcrypto/man/ASN1_TIME_set.3 +++ b/src/lib/libcrypto/man/ASN1_TIME_set.3 @@ -1,8 +1,10 @@ -.\" $OpenBSD: ASN1_TIME_set.3,v 1.2 2016/11/10 15:08:13 jmc Exp $ -.\" OpenSSL 99d63d46 Mon Jun 6 00:43:05 2016 -0400 +.\" $OpenBSD: ASN1_TIME_set.3,v 1.3 2017/08/20 17:16:40 schwarze Exp $ +.\" OpenSSL ASN1_TIME_set.pod cf37aaa3 Aug 4 11:24:03 2017 +1000 +.\" OpenSSL ASN1_TIME_set.pod e9b77246 Jan 20 19:58:49 2017 +0100 .\" -.\" This file was written by Dr. Stephen Henson. -.\" Copyright (c) 2015 The OpenSSL Project. All rights reserved. +.\" This file was written by Dr. Stephen Henson +.\" and Todd Short . +.\" Copyright (c) 2015, 2017 The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -48,15 +50,27 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: November 10 2016 $ +.Dd $Mdocdate: August 20 2017 $ .Dt ASN1_TIME_SET 3 .Os .Sh NAME .Nm ASN1_TIME_set , +.Nm ASN1_UTCTIME_set , +.Nm ASN1_GENERALIZEDTIME_set , .Nm ASN1_TIME_adj , +.Nm ASN1_UTCTIME_adj , +.Nm ASN1_GENERALIZEDTIME_adj , .Nm ASN1_TIME_set_string , +.Nm ASN1_UTCTIME_set_string , +.Nm ASN1_GENERALIZEDTIME_set_string , .Nm ASN1_TIME_check , -.Nm ASN1_TIME_print +.Nm ASN1_UTCTIME_check , +.Nm ASN1_GENERALIZEDTIME_check , +.Nm ASN1_TIME_print , +.Nm ASN1_UTCTIME_print , +.Nm ASN1_GENERALIZEDTIME_print , +.Nm ASN1_UTCTIME_cmp_time_t , +.Nm ASN1_TIME_to_generalizedtime .Nd ASN.1 Time functions .Sh SYNOPSIS .Ft ASN1_TIME * @@ -64,6 +78,16 @@ .Fa "ASN1_TIME *s" .Fa "time_t t" .Fc +.Ft ASN1_UTCTIME * +.Fo ASN1_UTCTIME_set +.Fa "ASN1_UTCTIME *s" +.Fa "time_t t" +.Fc +.Ft ASN1_GENERALIZEDTIME * +.Fo ASN1_GENERALIZEDTIME_set +.Fa "ASN1_GENERALIZEDTIME *s" +.Fa "time_t t" +.Fc .Ft ASN1_TIME * .Fo ASN1_TIME_adj .Fa "ASN1_TIME *s" @@ -71,26 +95,79 @@ .Fa "int offset_day" .Fa "long offset_sec" .Fc +.Ft ASN1_UTCTIME * +.Fo ASN1_UTCTIME_adj +.Fa "ASN1_UTCTIME *s" +.Fa "time_t t" +.Fa "int offset_day" +.Fa "long offset_sec" +.Fc +.Ft ASN1_GENERALIZEDTIME * +.Fo ASN1_GENERALIZEDTIME_adj +.Fa "ASN1_GENERALIZEDTIME *s" +.Fa "time_t t" +.Fa "int offset_day" +.Fa "long offset_sec" +.Fc .Ft int .Fo ASN1_TIME_set_string .Fa "ASN1_TIME *s" .Fa "const char *str" .Fc .Ft int +.Fo ASN1_UTCTIME_set_string +.Fa "ASN1_UTCTIME *s" +.Fa "const char *str" +.Fc +.Ft int +.Fo ASN1_GENERALIZEDTIME_set_string +.Fa "ASN1_GENERALIZEDTIME *s" +.Fa "const char *str" +.Fc +.Ft int .Fo ASN1_TIME_check .Fa "const ASN1_TIME *t" .Fc .Ft int +.Fo ASN1_UTCTIME_check +.Fa "const ASN1_UTCTIME *t" +.Fc +.Ft int +.Fo ASN1_GENERALIZEDTIME_check +.Fa "const ASN1_GENERALIZEDTIME *t" +.Fc +.Ft int .Fo ASN1_TIME_print .Fa "BIO *b" .Fa "const ASN1_TIME *s" .Fc +.Ft int +.Fo ASN1_UTCTIME_print +.Fa "BIO *b" +.Fa "const ASN1_UTCTIME *s" +.Fc +.Ft int +.Fo ASN1_GENERALIZEDTIME_print +.Fa "BIO *b" +.Fa "const ASN1_GENERALIZEDTIME *s" +.Fc +.Ft int +.Fo ASN1_UTCTIME_cmp_time_t +.Fa "const ASN1_UTCTIME *s" +.Fa "time_t t" +.Fc +.Ft ASN1_GENERALIZEDTIME * +.Fo ASN1_TIME_to_generalizedtime +.Fa "ASN1_TIME *t" +.Fa "ASN1_GENERALIZEDTIME **out" +.Fc .Sh DESCRIPTION -The function -.Fn ASN1_TIME_set -sets the -.Vt ASN1_TIME -structure +The functions +.Fn ASN1_TIME_set , +.Fn ASN1_UTCTIME_set , +and +.Fn ASN1_GENERALIZEDTIME_set +set the time structure .Fa s to the time represented by the .Vt time_t @@ -100,14 +177,14 @@ If .Fa s is .Dv NULL , -a new -.Vt ASN1_TIME -structure is allocated and returned. +a new time structure is allocated and returned. .Pp -.Fn ASN1_TIME_adj -sets the -.Vt ASN1_TIME -structure +The functions +.Fn ASN1_TIME_adj , +.Fn ASN1_UTCTIME_adj , +and +.Fn ASN1_GENERALIZEDTIME_adj +set the time structure .Fa s to the time represented by the time .Fa offset_day @@ -130,28 +207,56 @@ If .Fa s is .Dv NULL , -a new -.Vt ASN1_TIME -structure is allocated and returned. +a new time structure is allocated and returned. .Pp -.Fn ASN1_TIME_set_string -sets the -.Vt ASN1_TIME -structure +.Fn ASN1_TIME_adj +may change the type from +.Vt ASN1_GENERALIZEDTIME +to +.Vt ASN1_UTCTIME +or vise-versa depending on the resulting year. +The functions +.Fn ASN1_UTCTIME_adj +and +.Fn ASN1_GENERALIZEDTIME_adj +do not modify the type of the return structure. +.Pp +The functions +.Fn ASN1_TIME_set_string , +.Fn ASN1_UTCTIME_set_string , +and +.Fn ASN1_GENERALIZEDTIME_set_string +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). +The string +.Fa str +is copied into +.Fa s . +If +.Fa s +is +.Dv NULL , +these functions only perform a format check on +.Fa str . .Pp -.Fn ASN1_TIME_check -checks the syntax of the -.Vt ASN1_TIME -structure +The functions +.Fn ASN1_TIME_check , +.Fn ASN1_UTCTIME_check , +and +.Fn ASN1_GENERALIZEDTIME_check +check the syntax of the time structure .Fa s . .Pp -.Fn ASN1_TIME_print -prints out the time +The functions +.Fn ASN1_TIME_print , +.Fn ASN1_UTCTIME_print , +and +.Fn ASN1_GENERALIZEDTIME_print +print out the time .Fa s to .Vt BIO @@ -162,6 +267,32 @@ It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example "Feb 3 It does not include a newline. If the time structure has an invalid format, it prints out "Bad time value" and returns an error. +The output of +.Fn ASN1_GENERALIZEDTIME_print +may include a fractional part following the second. +.Pp +The function +.Fn ASN1_UTCTIME_cmp_time_t +compares the two times represented by +.Fa s +and +.Fa t . +.Pp +The function +.Fn ASN1_TIME_to_generalizedtime +converts the +.Vt ASN1_TIME +.Fa t +to an +.Vt ASN1_GENERALIZEDTIME , +regardless of year. +If either +.Fa out +or +.Pf * Fa out +is +.Dv NULL , +then a new object is allocated and must be freed after use. .Pp The .Vt ASN1_TIME @@ -173,10 +304,13 @@ date can be represented by UTCTime it is used, otherwise GeneralizedTime is used. .Pp The -.Vt ASN1_TIME -structure is represented as an +.Vt ASN1_TIME , +.Vt ASN1_UTCTIME , +and +.Vt ASN1_GENERALIZEDTIME +structures are represented as .Vt ASN1_STRING -internally and can be freed up using +structures internally and can be freed using .Xr ASN1_STRING_free 3 . .Pp The @@ -184,25 +318,65 @@ The 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). -.Sh RETURN VALUES -.Fn ASN1_TIME_set +.Pp +.Vt ASN1_UTCTIME +is limited to a year range of 1950 through 2049. +.Pp +It is recommended that +.Vt ASN1_TIME +functions be used instead of +.Vt ASN1_UTCTIME +or +.Vt ASN1_GENERALIZEDTIME +functions because the +.Vt ASN1_UTCTIME and -.Fn ASN1_TIME_adj -return a pointer to an +.Vt ASN1_GENERALIZEDTIME +functions act only on that specific time format, while the .Vt ASN1_TIME -structure or +functions operate on either format. +.Sh RETURN VALUES +.Fn ASN1_TIME_set , +.Fn ASN1_UTCTIME_set , +.Fn ASN1_GENERALIZEDTIME_set , +.Fn ASN1_TIME_adj , +.Fn ASN1_UTCTIME_adj , +.Fn ASN1_GENERALIZEDTIME_adj , +and +.Fn ASN1_TIME_to_generalizedtime +return a pointer to a time structure or .Dv NULL if an error occurred. .Pp -.Fn ASN1_TIME_set_string -returns 1 if the time value is successfully set or 0 otherwise. +.Fn ASN1_TIME_set_string , +.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_check -returns 1 if the structure is syntactically correct or 0 otherwise. +.Fn ASN1_TIME_check , +.Fn ASN1_UTCTIME_check , +and +.Fn ASN1_GENERALIZEDTIME_check +return 1 if the time structure is syntactically correct or 0 otherwise. .Pp -.Fn ASN1_TIME_print -returns 1 if the time is successfully printed out or 0 if an error +.Fn ASN1_TIME_print , +.Fn ASN1_UTCTIME_print , +and +.Fn ASN1_GENERALIZEDTIME_print +return 1 if the time is successfully printed or 0 if an error occurred (I/O error or invalid time format). +.Pp +.Fn ASN1_UTCTIME_cmp_time_t +returns \-1 if +.Fa s +is earlier than +.Fa t , +0 if both are equal, 1 if +.Fa s +is later than +.Fa t , +or \-2 on error. .Sh EXAMPLES Set a time structure to one hour after the current time and print it out: @@ -221,6 +395,9 @@ ASN1_TIME_print(b, tm); ASN1_STRING_free(tm); BIO_free(b); .Ed +.Sh HISTORY +.Fn ASN1_TIME_cmp_time_t +first appeared in OpenSSL 1.1.1. .Sh CAVEATS Some applications add offset times directly to a .Vt time_t @@ -240,7 +417,9 @@ parameters instead of directly manipulating a .Vt time_t value. .Sh BUGS -.Fn ASN1_TIME_print -currently does not print out the time zone: it either prints out "GMT" -or nothing. +.Fn ASN1_TIME_print , +.Fn ASN1_UTCTIME_print , +and +.Fn ASN1_GENERALIZEDTIME_print +do not print the time zone: they either print "GMT" or nothing. But all certificates complying with RFC 5280 et al use GMT anyway. -- cgit v1.2.3-55-g6feb