1.\" $OpenBSD: ASN1_TIME_set.3,v 1.3 2017/08/20 17:16:40 schwarze Exp $ 2.\" OpenSSL ASN1_TIME_set.pod cf37aaa3 Aug 4 11:24:03 2017 +1000 3.\" OpenSSL ASN1_TIME_set.pod e9b77246 Jan 20 19:58:49 2017 +0100 4.\" 5.\" This file was written by Dr. Stephen Henson <steve@openssl.org> 6.\" and Todd Short <tshort@akamai.com>. 7.\" Copyright (c) 2015, 2017 The OpenSSL Project. All rights reserved. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in 18.\" the documentation and/or other materials provided with the 19.\" distribution. 20.\" 21.\" 3. All advertising materials mentioning features or use of this 22.\" software must display the following acknowledgment: 23.\" "This product includes software developed by the OpenSSL Project 24.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 25.\" 26.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 27.\" endorse or promote products derived from this software without 28.\" prior written permission. For written permission, please contact 29.\" openssl-core@openssl.org. 30.\" 31.\" 5. Products derived from this software may not be called "OpenSSL" 32.\" nor may "OpenSSL" appear in their names without prior written 33.\" permission of the OpenSSL Project. 34.\" 35.\" 6. Redistributions of any form whatsoever must retain the following 36.\" acknowledgment: 37.\" "This product includes software developed by the OpenSSL Project 38.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 39.\" 40.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 41.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 42.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 43.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 44.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 46.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 47.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 48.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 49.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 51.\" OF THE POSSIBILITY OF SUCH DAMAGE. 52.\" 53.Dd $Mdocdate: August 20 2017 $ 54.Dt ASN1_TIME_SET 3 55.Os 56.Sh NAME 57.Nm ASN1_TIME_set , 58.Nm ASN1_UTCTIME_set , 59.Nm ASN1_GENERALIZEDTIME_set , 60.Nm ASN1_TIME_adj , 61.Nm ASN1_UTCTIME_adj , 62.Nm ASN1_GENERALIZEDTIME_adj , 63.Nm ASN1_TIME_set_string , 64.Nm ASN1_UTCTIME_set_string , 65.Nm ASN1_GENERALIZEDTIME_set_string , 66.Nm ASN1_TIME_check , 67.Nm ASN1_UTCTIME_check , 68.Nm ASN1_GENERALIZEDTIME_check , 69.Nm ASN1_TIME_print , 70.Nm ASN1_UTCTIME_print , 71.Nm ASN1_GENERALIZEDTIME_print , 72.Nm ASN1_UTCTIME_cmp_time_t , 73.Nm ASN1_TIME_to_generalizedtime 74.Nd ASN.1 Time functions 75.Sh SYNOPSIS 76.Ft ASN1_TIME * 77.Fo ASN1_TIME_set 78.Fa "ASN1_TIME *s" 79.Fa "time_t t" 80.Fc 81.Ft ASN1_UTCTIME * 82.Fo ASN1_UTCTIME_set 83.Fa "ASN1_UTCTIME *s" 84.Fa "time_t t" 85.Fc 86.Ft ASN1_GENERALIZEDTIME * 87.Fo ASN1_GENERALIZEDTIME_set 88.Fa "ASN1_GENERALIZEDTIME *s" 89.Fa "time_t t" 90.Fc 91.Ft ASN1_TIME * 92.Fo ASN1_TIME_adj 93.Fa "ASN1_TIME *s" 94.Fa "time_t t" 95.Fa "int offset_day" 96.Fa "long offset_sec" 97.Fc 98.Ft ASN1_UTCTIME * 99.Fo ASN1_UTCTIME_adj 100.Fa "ASN1_UTCTIME *s" 101.Fa "time_t t" 102.Fa "int offset_day" 103.Fa "long offset_sec" 104.Fc 105.Ft ASN1_GENERALIZEDTIME * 106.Fo ASN1_GENERALIZEDTIME_adj 107.Fa "ASN1_GENERALIZEDTIME *s" 108.Fa "time_t t" 109.Fa "int offset_day" 110.Fa "long offset_sec" 111.Fc 112.Ft int 113.Fo ASN1_TIME_set_string 114.Fa "ASN1_TIME *s" 115.Fa "const char *str" 116.Fc 117.Ft int 118.Fo ASN1_UTCTIME_set_string 119.Fa "ASN1_UTCTIME *s" 120.Fa "const char *str" 121.Fc 122.Ft int 123.Fo ASN1_GENERALIZEDTIME_set_string 124.Fa "ASN1_GENERALIZEDTIME *s" 125.Fa "const char *str" 126.Fc 127.Ft int 128.Fo ASN1_TIME_check 129.Fa "const ASN1_TIME *t" 130.Fc 131.Ft int 132.Fo ASN1_UTCTIME_check 133.Fa "const ASN1_UTCTIME *t" 134.Fc 135.Ft int 136.Fo ASN1_GENERALIZEDTIME_check 137.Fa "const ASN1_GENERALIZEDTIME *t" 138.Fc 139.Ft int 140.Fo ASN1_TIME_print 141.Fa "BIO *b" 142.Fa "const ASN1_TIME *s" 143.Fc 144.Ft int 145.Fo ASN1_UTCTIME_print 146.Fa "BIO *b" 147.Fa "const ASN1_UTCTIME *s" 148.Fc 149.Ft int 150.Fo ASN1_GENERALIZEDTIME_print 151.Fa "BIO *b" 152.Fa "const ASN1_GENERALIZEDTIME *s" 153.Fc 154.Ft int 155.Fo ASN1_UTCTIME_cmp_time_t 156.Fa "const ASN1_UTCTIME *s" 157.Fa "time_t t" 158.Fc 159.Ft ASN1_GENERALIZEDTIME * 160.Fo ASN1_TIME_to_generalizedtime 161.Fa "ASN1_TIME *t" 162.Fa "ASN1_GENERALIZEDTIME **out" 163.Fc 164.Sh DESCRIPTION 165The functions 166.Fn ASN1_TIME_set , 167.Fn ASN1_UTCTIME_set , 168and 169.Fn ASN1_GENERALIZEDTIME_set 170set the time structure 171.Fa s 172to the time represented by the 173.Vt time_t 174value 175.Fa t . 176If 177.Fa s 178is 179.Dv NULL , 180a new time structure is allocated and returned. 181.Pp 182The functions 183.Fn ASN1_TIME_adj , 184.Fn ASN1_UTCTIME_adj , 185and 186.Fn ASN1_GENERALIZEDTIME_adj 187set the time structure 188.Fa s 189to the time represented by the time 190.Fa offset_day 191and 192.Fa offset_sec 193after the 194.Vt time_t 195value 196.Fa t . 197The values of 198.Fa offset_day 199or 200.Fa offset_sec 201can be negative to set a time before 202.Fa t . 203The 204.Fa offset_sec 205value can also exceed the number of seconds in a day. 206If 207.Fa s 208is 209.Dv NULL , 210a new time structure is allocated and returned. 211.Pp 212.Fn ASN1_TIME_adj 213may change the type from 214.Vt ASN1_GENERALIZEDTIME 215to 216.Vt ASN1_UTCTIME 217or vise-versa depending on the resulting year. 218The functions 219.Fn ASN1_UTCTIME_adj 220and 221.Fn ASN1_GENERALIZEDTIME_adj 222do not modify the type of the return structure. 223.Pp 224The functions 225.Fn ASN1_TIME_set_string , 226.Fn ASN1_UTCTIME_set_string , 227and 228.Fn ASN1_GENERALIZEDTIME_set_string 229set the time structure 230.Fa s 231to the time represented by the string 232.Fa str , 233which must be in appropriate ASN.1 time format (for example 234YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). 235The string 236.Fa str 237is copied into 238.Fa s . 239If 240.Fa s 241is 242.Dv NULL , 243these functions only perform a format check on 244.Fa str . 245.Pp 246The functions 247.Fn ASN1_TIME_check , 248.Fn ASN1_UTCTIME_check , 249and 250.Fn ASN1_GENERALIZEDTIME_check 251check the syntax of the time structure 252.Fa s . 253.Pp 254The functions 255.Fn ASN1_TIME_print , 256.Fn ASN1_UTCTIME_print , 257and 258.Fn ASN1_GENERALIZEDTIME_print 259print out the time 260.Fa s 261to 262.Vt BIO 263.Fa b 264in human readable format. 265It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example "Feb 3 26600:55:52 2015 GMT". 267It does not include a newline. 268If the time structure has an invalid format, 269it prints out "Bad time value" and returns an error. 270The output of 271.Fn ASN1_GENERALIZEDTIME_print 272may include a fractional part following the second. 273.Pp 274The function 275.Fn ASN1_UTCTIME_cmp_time_t 276compares the two times represented by 277.Fa s 278and 279.Fa t . 280.Pp 281The function 282.Fn ASN1_TIME_to_generalizedtime 283converts the 284.Vt ASN1_TIME 285.Fa t 286to an 287.Vt ASN1_GENERALIZEDTIME , 288regardless of year. 289If either 290.Fa out 291or 292.Pf * Fa out 293is 294.Dv NULL , 295then a new object is allocated and must be freed after use. 296.Pp 297The 298.Vt ASN1_TIME 299structure corresponds to the ASN.1 structure 300.Sy Time 301defined in RFC 5280 et al. 302The time setting functions obey the rules outlined in RFC 5280: if the 303date can be represented by UTCTime it is used, otherwise GeneralizedTime is 304used. 305.Pp 306The 307.Vt ASN1_TIME , 308.Vt ASN1_UTCTIME , 309and 310.Vt ASN1_GENERALIZEDTIME 311structures are represented as 312.Vt ASN1_STRING 313structures internally and can be freed using 314.Xr ASN1_STRING_free 3 . 315.Pp 316The 317.Vt ASN1_TIME 318structure can represent years from 0000 to 9999 but no attempt is 319made to correct ancient calendar changes (for example from Julian 320to Gregorian calendars). 321.Pp 322.Vt ASN1_UTCTIME 323is limited to a year range of 1950 through 2049. 324.Pp 325It is recommended that 326.Vt ASN1_TIME 327functions be used instead of 328.Vt ASN1_UTCTIME 329or 330.Vt ASN1_GENERALIZEDTIME 331functions because the 332.Vt ASN1_UTCTIME 333and 334.Vt ASN1_GENERALIZEDTIME 335functions act only on that specific time format, while the 336.Vt ASN1_TIME 337functions operate on either format. 338.Sh RETURN VALUES 339.Fn ASN1_TIME_set , 340.Fn ASN1_UTCTIME_set , 341.Fn ASN1_GENERALIZEDTIME_set , 342.Fn ASN1_TIME_adj , 343.Fn ASN1_UTCTIME_adj , 344.Fn ASN1_GENERALIZEDTIME_adj , 345and 346.Fn ASN1_TIME_to_generalizedtime 347return a pointer to a time structure or 348.Dv NULL 349if an error occurred. 350.Pp 351.Fn ASN1_TIME_set_string , 352.Fn ASN1_UTCTIME_set_string , 353and 354.Fn ASN1_GENERALIZEDTIME_set_string 355return 1 if the time value is successfully set or 0 otherwise. 356.Pp 357.Fn ASN1_TIME_check , 358.Fn ASN1_UTCTIME_check , 359and 360.Fn ASN1_GENERALIZEDTIME_check 361return 1 if the time structure is syntactically correct or 0 otherwise. 362.Pp 363.Fn ASN1_TIME_print , 364.Fn ASN1_UTCTIME_print , 365and 366.Fn ASN1_GENERALIZEDTIME_print 367return 1 if the time is successfully printed or 0 if an error 368occurred (I/O error or invalid time format). 369.Pp 370.Fn ASN1_UTCTIME_cmp_time_t 371returns \-1 if 372.Fa s 373is earlier than 374.Fa t , 3750 if both are equal, 1 if 376.Fa s 377is later than 378.Fa t , 379or \-2 on error. 380.Sh EXAMPLES 381Set a time structure to one hour after the current time and print it 382out: 383.Bd -literal -offset indent 384#include <time.h> 385#include <openssl/asn1.h> 386 387ASN1_TIME *tm; 388time_t t; 389BIO *b; 390 391t = time(NULL); 392tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60); 393b = BIO_new_fp(stdout, BIO_NOCLOSE); 394ASN1_TIME_print(b, tm); 395ASN1_STRING_free(tm); 396BIO_free(b); 397.Ed 398.Sh HISTORY 399.Fn ASN1_TIME_cmp_time_t 400first appeared in OpenSSL 1.1.1. 401.Sh CAVEATS 402Some applications add offset times directly to a 403.Vt time_t 404value and pass the results to 405.Fn ASN1_TIME_set 406(or equivalent). 407This can cause problems as the 408.Vt time_t 409value can overflow on some systems resulting in unexpected results. 410New applications should use 411.Fn ASN1_TIME_adj 412instead and pass the offset value in the 413.Fa offset_sec 414and 415.Fa offset_day 416parameters instead of directly manipulating a 417.Vt time_t 418value. 419.Sh BUGS 420.Fn ASN1_TIME_print , 421.Fn ASN1_UTCTIME_print , 422and 423.Fn ASN1_GENERALIZEDTIME_print 424do not print the time zone: they either print "GMT" or nothing. 425But all certificates complying with RFC 5280 et al use GMT anyway. 426