1.\" $OpenBSD: ASN1_TIME_set.3,v 1.15 2019/06/06 01:06:58 schwarze Exp $ 2.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 3.\" selective merge up to: OpenSSL b0edda11 Mar 20 13:00:17 2018 +0000 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: June 6 2019 $ 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.In openssl/asn1.h 77.Ft ASN1_TIME * 78.Fo ASN1_TIME_set 79.Fa "ASN1_TIME *s" 80.Fa "time_t t" 81.Fc 82.Ft ASN1_UTCTIME * 83.Fo ASN1_UTCTIME_set 84.Fa "ASN1_UTCTIME *s" 85.Fa "time_t t" 86.Fc 87.Ft ASN1_GENERALIZEDTIME * 88.Fo ASN1_GENERALIZEDTIME_set 89.Fa "ASN1_GENERALIZEDTIME *s" 90.Fa "time_t t" 91.Fc 92.Ft ASN1_TIME * 93.Fo ASN1_TIME_adj 94.Fa "ASN1_TIME *s" 95.Fa "time_t t" 96.Fa "int offset_day" 97.Fa "long offset_sec" 98.Fc 99.Ft ASN1_UTCTIME * 100.Fo ASN1_UTCTIME_adj 101.Fa "ASN1_UTCTIME *s" 102.Fa "time_t t" 103.Fa "int offset_day" 104.Fa "long offset_sec" 105.Fc 106.Ft ASN1_GENERALIZEDTIME * 107.Fo ASN1_GENERALIZEDTIME_adj 108.Fa "ASN1_GENERALIZEDTIME *s" 109.Fa "time_t t" 110.Fa "int offset_day" 111.Fa "long offset_sec" 112.Fc 113.Ft int 114.Fo ASN1_TIME_set_string 115.Fa "ASN1_TIME *s" 116.Fa "const char *str" 117.Fc 118.Ft int 119.Fo ASN1_UTCTIME_set_string 120.Fa "ASN1_UTCTIME *s" 121.Fa "const char *str" 122.Fc 123.Ft int 124.Fo ASN1_GENERALIZEDTIME_set_string 125.Fa "ASN1_GENERALIZEDTIME *s" 126.Fa "const char *str" 127.Fc 128.Ft int 129.Fo ASN1_TIME_check 130.Fa "const ASN1_TIME *t" 131.Fc 132.Ft int 133.Fo ASN1_UTCTIME_check 134.Fa "const ASN1_UTCTIME *t" 135.Fc 136.Ft int 137.Fo ASN1_GENERALIZEDTIME_check 138.Fa "const ASN1_GENERALIZEDTIME *t" 139.Fc 140.Ft int 141.Fo ASN1_TIME_print 142.Fa "BIO *b" 143.Fa "const ASN1_TIME *s" 144.Fc 145.Ft int 146.Fo ASN1_UTCTIME_print 147.Fa "BIO *b" 148.Fa "const ASN1_UTCTIME *s" 149.Fc 150.Ft int 151.Fo ASN1_GENERALIZEDTIME_print 152.Fa "BIO *b" 153.Fa "const ASN1_GENERALIZEDTIME *s" 154.Fc 155.Ft int 156.Fo ASN1_UTCTIME_cmp_time_t 157.Fa "const ASN1_UTCTIME *s" 158.Fa "time_t t" 159.Fc 160.Ft ASN1_GENERALIZEDTIME * 161.Fo ASN1_TIME_to_generalizedtime 162.Fa "const ASN1_TIME *t" 163.Fa "ASN1_GENERALIZEDTIME **out" 164.Fc 165.Sh DESCRIPTION 166The functions 167.Fn ASN1_TIME_set , 168.Fn ASN1_UTCTIME_set , 169and 170.Fn ASN1_GENERALIZEDTIME_set 171set the time structure 172.Fa s 173to the time represented by the 174.Vt time_t 175value 176.Fa t . 177If 178.Fa s 179is 180.Dv NULL , 181a new time structure is allocated and returned. 182.Pp 183The functions 184.Fn ASN1_TIME_adj , 185.Fn ASN1_UTCTIME_adj , 186and 187.Fn ASN1_GENERALIZEDTIME_adj 188set the time structure 189.Fa s 190to the time represented by the time 191.Fa offset_day 192and 193.Fa offset_sec 194after the 195.Vt time_t 196value 197.Fa t . 198The values of 199.Fa offset_day 200or 201.Fa offset_sec 202can be negative to set a time before 203.Fa t . 204The 205.Fa offset_sec 206value can also exceed the number of seconds in a day. 207If 208.Fa s 209is 210.Dv NULL , 211a new time structure is allocated and returned. 212.Pp 213.Fn ASN1_TIME_adj 214may change the type from 215.Vt ASN1_GENERALIZEDTIME 216to 217.Vt ASN1_UTCTIME 218or vice versa depending on the resulting year. 219The functions 220.Fn ASN1_UTCTIME_adj 221and 222.Fn ASN1_GENERALIZEDTIME_adj 223do not modify the type of the return structure. 224.Pp 225The functions 226.Fn ASN1_TIME_set_string , 227.Fn ASN1_UTCTIME_set_string , 228and 229.Fn ASN1_GENERALIZEDTIME_set_string 230set the time structure 231.Fa s 232to the time represented by the string 233.Fa str , 234which must be in appropriate ASN.1 time format (for example 235YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). 236The string 237.Fa str 238is copied into 239.Fa s . 240If 241.Fa s 242is 243.Dv NULL , 244these functions only perform a format check on 245.Fa str . 246.Pp 247The functions 248.Fn ASN1_TIME_check , 249.Fn ASN1_UTCTIME_check , 250and 251.Fn ASN1_GENERALIZEDTIME_check 252check the syntax of the time structure 253.Fa s . 254.Pp 255The functions 256.Fn ASN1_TIME_print , 257.Fn ASN1_UTCTIME_print , 258and 259.Fn ASN1_GENERALIZEDTIME_print 260print out the time 261.Fa s 262to 263.Vt BIO 264.Fa b 265in human readable format. 266It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example "Feb 3 26700:55:52 2015 GMT". 268It does not include a newline. 269If the time structure has an invalid format, 270it prints out "Bad time value" and returns an error. 271The output of 272.Fn ASN1_GENERALIZEDTIME_print 273may include a fractional part following the second. 274.Pp 275The function 276.Fn ASN1_UTCTIME_cmp_time_t 277compares the two times represented by 278.Fa s 279and 280.Fa t . 281.Pp 282The function 283.Fn ASN1_TIME_to_generalizedtime 284converts the 285.Vt ASN1_TIME 286.Fa t 287to an 288.Vt ASN1_GENERALIZEDTIME , 289regardless of year. 290If either 291.Fa out 292or 293.Pf * Fa out 294is 295.Dv NULL , 296then a new object is allocated and must be freed after use. 297.Pp 298The 299.Vt ASN1_TIME 300structure corresponds to the ASN.1 structure 301.Sy Time 302defined in RFC 5280 et al. 303The time setting functions obey the rules outlined in RFC 5280: if the 304date can be represented by UTCTime it is used, otherwise GeneralizedTime is 305used. 306.Pp 307The 308.Vt ASN1_TIME , 309.Vt ASN1_UTCTIME , 310and 311.Vt ASN1_GENERALIZEDTIME 312structures are represented as 313.Vt ASN1_STRING 314structures internally and can be freed using 315.Xr ASN1_STRING_free 3 . 316.Pp 317The 318.Vt ASN1_TIME 319structure can represent years from 0000 to 9999 but no attempt is 320made to correct ancient calendar changes (for example from Julian 321to Gregorian calendars). 322.Pp 323.Vt ASN1_UTCTIME 324is limited to a year range of 1950 through 2049. 325.Pp 326It is recommended that 327.Vt ASN1_TIME 328functions be used instead of 329.Vt ASN1_UTCTIME 330or 331.Vt ASN1_GENERALIZEDTIME 332functions because the 333.Vt ASN1_UTCTIME 334and 335.Vt ASN1_GENERALIZEDTIME 336functions act only on that specific time format, while the 337.Vt ASN1_TIME 338functions operate on either format. 339.Sh RETURN VALUES 340.Fn ASN1_TIME_set , 341.Fn ASN1_UTCTIME_set , 342.Fn ASN1_GENERALIZEDTIME_set , 343.Fn ASN1_TIME_adj , 344.Fn ASN1_UTCTIME_adj , 345.Fn ASN1_GENERALIZEDTIME_adj , 346and 347.Fn ASN1_TIME_to_generalizedtime 348return a pointer to a time structure or 349.Dv NULL 350if an error occurred. 351.Pp 352.Fn ASN1_TIME_set_string , 353.Fn ASN1_UTCTIME_set_string , 354and 355.Fn ASN1_GENERALIZEDTIME_set_string 356return 1 if the time value is successfully set or 0 otherwise. 357.Pp 358.Fn ASN1_TIME_check , 359.Fn ASN1_UTCTIME_check , 360and 361.Fn ASN1_GENERALIZEDTIME_check 362return 1 if the time structure is syntactically correct or 0 otherwise. 363.Pp 364.Fn ASN1_TIME_print , 365.Fn ASN1_UTCTIME_print , 366and 367.Fn ASN1_GENERALIZEDTIME_print 368return 1 if the time is successfully printed or 0 if an error 369occurred (I/O error or invalid time format). 370.Pp 371.Fn ASN1_UTCTIME_cmp_time_t 372returns \-1 if 373.Fa s 374is earlier than 375.Fa t , 3760 if both are equal, 1 if 377.Fa s 378is later than 379.Fa t , 380or \-2 on error. 381.Sh EXAMPLES 382Set a time structure to one hour after the current time and print it 383out: 384.Bd -literal -offset indent 385#include <time.h> 386#include <openssl/asn1.h> 387 388ASN1_TIME *tm; 389time_t t; 390BIO *b; 391 392t = time(NULL); 393tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60); 394b = BIO_new_fp(stdout, BIO_NOCLOSE); 395ASN1_TIME_print(b, tm); 396ASN1_STRING_free(tm); 397BIO_free(b); 398.Ed 399.Sh SEE ALSO 400.Xr ASN1_TIME_new 3 , 401.Xr ASN1_time_parse 3 , 402.Xr X509_cmp_time 3 403.Sh HISTORY 404.Fn ASN1_UTCTIME_check 405and 406.Fn ASN1_UTCTIME_print 407first appeared in SSLeay 0.5.1. 408.Fn ASN1_UTCTIME_set 409first appeared in SSLeay 0.6.0. 410.Fn ASN1_UTCTIME_set_string 411first appeared in SSLeay 0.9.0. 412All these functions have been available since 413.Ox 2.4 . 414.Pp 415.Fn ASN1_TIME_set , 416.Fn ASN1_GENERALIZEDTIME_set , 417.Fn ASN1_GENERALIZEDTIME_set_string , 418.Fn ASN1_GENERALIZEDTIME_check , 419.Fn ASN1_TIME_print , 420and 421.Fn ASN1_GENERALIZEDTIME_print 422first appeared in OpenSSL 0.9.2b and have been available since 423.Ox 2.6 . 424.Pp 425.Fn ASN1_UTCTIME_cmp_time_t 426first appeared in OpenSSL 0.9.6 and has been available since 427.Ox 2.9 . 428.Pp 429.Fn ASN1_TIME_check 430and 431.Fn ASN1_TIME_to_generalizedtime 432first appeared in OpenSSL 0.9.7 and have been available since 433.Ox 3.2 . 434.Pp 435.Fn ASN1_TIME_adj , 436.Fn ASN1_UTCTIME_adj , 437.Fn ASN1_GENERALIZEDTIME_adj , 438and 439.Fn ASN1_TIME_set_string 440first appeared in OpenSSL 1.0.0 and have been available since 441.Ox 4.9 . 442.Sh CAVEATS 443Some applications add offset times directly to a 444.Vt time_t 445value and pass the results to 446.Fn ASN1_TIME_set 447(or equivalent). 448This can cause problems as the 449.Vt time_t 450value can overflow on some systems resulting in unexpected results. 451New applications should use 452.Fn ASN1_TIME_adj 453instead and pass the offset value in the 454.Fa offset_sec 455and 456.Fa offset_day 457parameters instead of directly manipulating a 458.Vt time_t 459value. 460.Sh BUGS 461.Fn ASN1_TIME_print , 462.Fn ASN1_UTCTIME_print , 463and 464.Fn ASN1_GENERALIZEDTIME_print 465do not print the time zone: they either print "GMT" or nothing. 466But all certificates complying with RFC 5280 et al use GMT anyway. 467