path: root/lib/libcrypto/man/ASN1_TIME_set.3

.\"	$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
.\"
.\" 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_set_string ,
.Nm ASN1_TIME_check ,
.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 RFC 5280 et al.
The time setting functions obey the rules outlined in RFC 5280: if the
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_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 <time.h>
#include <openssl/asn1.h>

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 RFC 5280 et al use GMT anyway.