1.\" $OpenBSD: ASN1_TIME_set.3,v 1.2 2016/11/10 15:08:13 jmc Exp $ 2.\" OpenSSL 99d63d46 Mon Jun 6 00:43:05 2016 -0400 3.\" 4.\" This file was written by Dr. Stephen Henson. 5.\" Copyright (c) 2015 The OpenSSL Project. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in 16.\" the documentation and/or other materials provided with the 17.\" distribution. 18.\" 19.\" 3. All advertising materials mentioning features or use of this 20.\" software must display the following acknowledgment: 21.\" "This product includes software developed by the OpenSSL Project 22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 23.\" 24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 25.\" endorse or promote products derived from this software without 26.\" prior written permission. For written permission, please contact 27.\" openssl-core@openssl.org. 28.\" 29.\" 5. Products derived from this software may not be called "OpenSSL" 30.\" nor may "OpenSSL" appear in their names without prior written 31.\" permission of the OpenSSL Project. 32.\" 33.\" 6. Redistributions of any form whatsoever must retain the following 34.\" acknowledgment: 35.\" "This product includes software developed by the OpenSSL Project 36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 37.\" 38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 49.\" OF THE POSSIBILITY OF SUCH DAMAGE. 50.\" 51.Dd $Mdocdate: November 10 2016 $ 52.Dt ASN1_TIME_SET 3 53.Os 54.Sh NAME 55.Nm ASN1_TIME_set , 56.Nm ASN1_TIME_adj , 57.Nm ASN1_TIME_set_string , 58.Nm ASN1_TIME_check , 59.Nm ASN1_TIME_print 60.Nd ASN.1 Time functions 61.Sh SYNOPSIS 62.Ft ASN1_TIME * 63.Fo ASN1_TIME_set 64.Fa "ASN1_TIME *s" 65.Fa "time_t t" 66.Fc 67.Ft ASN1_TIME * 68.Fo ASN1_TIME_adj 69.Fa "ASN1_TIME *s" 70.Fa "time_t t" 71.Fa "int offset_day" 72.Fa "long offset_sec" 73.Fc 74.Ft int 75.Fo ASN1_TIME_set_string 76.Fa "ASN1_TIME *s" 77.Fa "const char *str" 78.Fc 79.Ft int 80.Fo ASN1_TIME_check 81.Fa "const ASN1_TIME *t" 82.Fc 83.Ft int 84.Fo ASN1_TIME_print 85.Fa "BIO *b" 86.Fa "const ASN1_TIME *s" 87.Fc 88.Sh DESCRIPTION 89The function 90.Fn ASN1_TIME_set 91sets the 92.Vt ASN1_TIME 93structure 94.Fa s 95to the time represented by the 96.Vt time_t 97value 98.Fa t . 99If 100.Fa s 101is 102.Dv NULL , 103a new 104.Vt ASN1_TIME 105structure is allocated and returned. 106.Pp 107.Fn ASN1_TIME_adj 108sets the 109.Vt ASN1_TIME 110structure 111.Fa s 112to the time represented by the time 113.Fa offset_day 114and 115.Fa offset_sec 116after the 117.Vt time_t 118value 119.Fa t . 120The values of 121.Fa offset_day 122or 123.Fa offset_sec 124can be negative to set a time before 125.Fa t . 126The 127.Fa offset_sec 128value can also exceed the number of seconds in a day. 129If 130.Fa s 131is 132.Dv NULL , 133a new 134.Vt ASN1_TIME 135structure is allocated and returned. 136.Pp 137.Fn ASN1_TIME_set_string 138sets the 139.Vt ASN1_TIME 140structure 141.Fa s 142to the time represented by the string 143.Fa str , 144which must be in appropriate ASN.1 time format (for example 145YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). 146.Pp 147.Fn ASN1_TIME_check 148checks the syntax of the 149.Vt ASN1_TIME 150structure 151.Fa s . 152.Pp 153.Fn ASN1_TIME_print 154prints out the time 155.Fa s 156to 157.Vt BIO 158.Fa b 159in human readable format. 160It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example "Feb 3 16100:55:52 2015 GMT". 162It does not include a newline. 163If the time structure has an invalid format, 164it prints out "Bad time value" and returns an error. 165.Pp 166The 167.Vt ASN1_TIME 168structure corresponds to the ASN.1 structure 169.Sy Time 170defined in RFC 5280 et al. 171The time setting functions obey the rules outlined in RFC 5280: if the 172date can be represented by UTCTime it is used, otherwise GeneralizedTime is 173used. 174.Pp 175The 176.Vt ASN1_TIME 177structure is represented as an 178.Vt ASN1_STRING 179internally and can be freed up using 180.Xr ASN1_STRING_free 3 . 181.Pp 182The 183.Vt ASN1_TIME 184structure can represent years from 0000 to 9999 but no attempt is 185made to correct ancient calendar changes (for example from Julian 186to Gregorian calendars). 187.Sh RETURN VALUES 188.Fn ASN1_TIME_set 189and 190.Fn ASN1_TIME_adj 191return a pointer to an 192.Vt ASN1_TIME 193structure or 194.Dv NULL 195if an error occurred. 196.Pp 197.Fn ASN1_TIME_set_string 198returns 1 if the time value is successfully set or 0 otherwise. 199.Pp 200.Fn ASN1_TIME_check 201returns 1 if the structure is syntactically correct or 0 otherwise. 202.Pp 203.Fn ASN1_TIME_print 204returns 1 if the time is successfully printed out or 0 if an error 205occurred (I/O error or invalid time format). 206.Sh EXAMPLES 207Set a time structure to one hour after the current time and print it 208out: 209.Bd -literal -offset indent 210#include <time.h> 211#include <openssl/asn1.h> 212 213ASN1_TIME *tm; 214time_t t; 215BIO *b; 216 217t = time(NULL); 218tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60); 219b = BIO_new_fp(stdout, BIO_NOCLOSE); 220ASN1_TIME_print(b, tm); 221ASN1_STRING_free(tm); 222BIO_free(b); 223.Ed 224.Sh CAVEATS 225Some applications add offset times directly to a 226.Vt time_t 227value and pass the results to 228.Fn ASN1_TIME_set 229(or equivalent). 230This can cause problems as the 231.Vt time_t 232value can overflow on some systems resulting in unexpected results. 233New applications should use 234.Fn ASN1_TIME_adj 235instead and pass the offset value in the 236.Fa offset_sec 237and 238.Fa offset_day 239parameters instead of directly manipulating a 240.Vt time_t 241value. 242.Sh BUGS 243.Fn ASN1_TIME_print 244currently does not print out the time zone: it either prints out "GMT" 245or nothing. 246But all certificates complying with RFC 5280 et al use GMT anyway. 247