From 5199e08cc76e76ab6fe76ac808a659b4caa9f7e0 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Thu, 10 Nov 2016 14:42:21 +0000 Subject: import from OpenSSL, deleting ASN1_TIME_diff() which we don't have --- src/lib/libcrypto/man/ASN1_TIME_set.3 | 246 ++++++++++++++++++++++++++++++++++ 1 file changed, 246 insertions(+) create mode 100644 src/lib/libcrypto/man/ASN1_TIME_set.3 diff --git a/src/lib/libcrypto/man/ASN1_TIME_set.3 b/src/lib/libcrypto/man/ASN1_TIME_set.3 new file mode 100644 index 0000000000..784b98944d --- /dev/null +++ b/src/lib/libcrypto/man/ASN1_TIME_set.3 @@ -0,0 +1,246 @@ +.\" $OpenBSD: ASN1_TIME_set.3,v 1.1 2016/11/10 14:42:21 schwarze Exp $ +.\" OpenSSL 99d63d46 Mon Jun 6 00:43:05 2016 -0400 +.\" +.\" This file was written by Dr. Stephen Henson. +.\" Copyright (c) 2015 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 +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" 3. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" 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 $ +.Dt ASN1_TIME_SET 3 +.Os +.Sh NAME +.Nm ASN1_TIME_set , +.Nm ASN1_TIME_adj , +.Nm ASN1_TIME_check , +.Nm ASN1_TIME_set_string , +.Nm ASN1_TIME_print +.Nd ASN.1 Time functions +.Sh SYNOPSIS +.Ft ASN1_TIME * +.Fo ASN1_TIME_set +.Fa "ASN1_TIME *s" +.Fa "time_t t" +.Fc +.Ft ASN1_TIME * +.Fo ASN1_TIME_adj +.Fa "ASN1_TIME *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_TIME_check +.Fa "const ASN1_TIME *t" +.Fc +.Ft int +.Fo ASN1_TIME_print +.Fa "BIO *b" +.Fa "const ASN1_TIME *s" +.Fc +.Sh DESCRIPTION +The function +.Fn ASN1_TIME_set +sets the +.Vt ASN1_TIME +structure +.Fa s +to the time represented by the +.Vt time_t +value +.Fa t . +If +.Fa s +is +.Dv NULL , +a new +.Vt ASN1_TIME +structure is allocated and returned. +.Pp +.Fn ASN1_TIME_adj +sets the +.Vt ASN1_TIME +structure +.Fa s +to the time represented by the time +.Fa offset_day +and +.Fa offset_sec +after the +.Vt time_t +value +.Fa t . +The values of +.Fa offset_day +or +.Fa offset_sec +can be negative to set a time before +.Fa t . +The +.Fa offset_sec +value can also exceed the number of seconds in a day. +If +.Fa s +is +.Dv NULL , +a new +.Vt ASN1_TIME +structure is allocated and returned. +.Pp +.Fn ASN1_TIME_set_string +sets the +.Vt ASN1_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). +.Pp +.Fn ASN1_TIME_check +checks the syntax of the +.Vt ASN1_TIME +structure +.Fa s . +.Pp +.Fn ASN1_TIME_print +prints out the time +.Fa s +to +.Vt BIO +.Fa 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 an invalid format, +it prints out "Bad time value" and returns an error. +.Pp +The +.Vt ASN1_TIME +structure corresponds to the ASN.1 structure +.Sy 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. +.Pp +The +.Vt ASN1_TIME +structure is represented as an +.Vt ASN1_STRING +internally and can be freed up using +.Xr ASN1_STRING_free 3 . +.Pp +The +.Vt 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). +.Sh RETURN VALUES +.Fn ASN1_TIME_set +and +.Fn ASN1_TIME_adj +return a pointer to an +.Vt ASN1_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. +.Pp +.Fn ASN1_TIME_check +returns 1 if the 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 +occurred (I/O error or invalid time format). +.Sh EXAMPLES +Set a time structure to one hour after the current time and print it +out: +.Bd -literal -offset indent +#include +#include + +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); +.Ed +.Sh CAVEATS +Some applications add offset times directly to a +.Vt time_t +value and pass the results to +.Fn ASN1_TIME_set +(or equivalent). +This can cause problems as the +.Vt time_t +value can overflow on some systems resulting in unexpected results. +New applications should use +.Fn ASN1_TIME_adj +instead and pass the offset value in the +.Fa offset_sec +and +.Fa offset_day +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. +But all certificates complying with RFC5280 et al use GMT anyway. -- cgit v1.2.3-55-g6feb