1.\" $OpenBSD: ASN1_TIME_set.3,v 1.19 2022/11/13 22:11:44 schwarze Exp $ 2.\" full merge up to: OpenSSL 3d0f1cb9 Jul 11 03:01:24 2017 +0800 3.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 4.\" 5.\" This file is a derived work. 6.\" The changes are covered by the following Copyright and license: 7.\" 8.\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org> 9.\" Copyright (c) 2022 Bob Beck <beck@openbsd.org> 10.\" 11.\" Permission to use, copy, modify, and distribute this software for any 12.\" purpose with or without fee is hereby granted, provided that the above 13.\" copyright notice and this permission notice appear in all copies. 14.\" 15.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES 16.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 17.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR 18.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 19.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 20.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 21.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 22.\" 23.\" The original file was written by Dr. Stephen Henson <steve@openssl.org> 24.\" and Todd Short <tshort@akamai.com>. 25.\" Copyright (c) 2015, 2017 The OpenSSL Project. All rights reserved. 26.\" 27.\" Redistribution and use in source and binary forms, with or without 28.\" modification, are permitted provided that the following conditions 29.\" are met: 30.\" 31.\" 1. Redistributions of source code must retain the above copyright 32.\" notice, this list of conditions and the following disclaimer. 33.\" 34.\" 2. Redistributions in binary form must reproduce the above copyright 35.\" notice, this list of conditions and the following disclaimer in 36.\" the documentation and/or other materials provided with the 37.\" distribution. 38.\" 39.\" 3. All advertising materials mentioning features or use of this 40.\" software must display the following acknowledgment: 41.\" "This product includes software developed by the OpenSSL Project 42.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 43.\" 44.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 45.\" endorse or promote products derived from this software without 46.\" prior written permission. For written permission, please contact 47.\" openssl-core@openssl.org. 48.\" 49.\" 5. Products derived from this software may not be called "OpenSSL" 50.\" nor may "OpenSSL" appear in their names without prior written 51.\" permission of the OpenSSL Project. 52.\" 53.\" 6. Redistributions of any form whatsoever must retain the following 54.\" acknowledgment: 55.\" "This product includes software developed by the OpenSSL Project 56.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 57.\" 58.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 59.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 60.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 61.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 62.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 63.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 64.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 65.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 66.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 67.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 68.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 69.\" OF THE POSSIBILITY OF SUCH DAMAGE. 70.\" 71.Dd $Mdocdate: November 13 2022 $ 72.Dt ASN1_TIME_SET 3 73.Os 74.Sh NAME 75.Nm ASN1_TIME_set , 76.Nm ASN1_UTCTIME_set , 77.Nm ASN1_GENERALIZEDTIME_set , 78.Nm ASN1_TIME_adj , 79.Nm ASN1_UTCTIME_adj , 80.Nm ASN1_GENERALIZEDTIME_adj , 81.Nm ASN1_TIME_set_string , 82.Nm ASN1_TIME_set_string_X509 , 83.Nm ASN1_UTCTIME_set_string , 84.Nm ASN1_GENERALIZEDTIME_set_string , 85.Nm ASN1_TIME_normalize , 86.Nm ASN1_TIME_check , 87.Nm ASN1_UTCTIME_check , 88.Nm ASN1_GENERALIZEDTIME_check , 89.Nm ASN1_TIME_print , 90.Nm ASN1_UTCTIME_print , 91.Nm ASN1_GENERALIZEDTIME_print , 92.Nm ASN1_TIME_to_tm , 93.Nm ASN1_TIME_diff , 94.Nm ASN1_TIME_cmp_time_t , 95.Nm ASN1_UTCTIME_cmp_time_t , 96.Nm ASN1_TIME_compare , 97.Nm ASN1_TIME_to_generalizedtime 98.Nd ASN.1 Time functions 99.Sh SYNOPSIS 100.In openssl/asn1.h 101.Ft ASN1_TIME * 102.Fo ASN1_TIME_set 103.Fa "ASN1_TIME *s" 104.Fa "time_t t" 105.Fc 106.Ft ASN1_UTCTIME * 107.Fo ASN1_UTCTIME_set 108.Fa "ASN1_UTCTIME *s" 109.Fa "time_t t" 110.Fc 111.Ft ASN1_GENERALIZEDTIME * 112.Fo ASN1_GENERALIZEDTIME_set 113.Fa "ASN1_GENERALIZEDTIME *s" 114.Fa "time_t t" 115.Fc 116.Ft ASN1_TIME * 117.Fo ASN1_TIME_adj 118.Fa "ASN1_TIME *s" 119.Fa "time_t t" 120.Fa "int offset_day" 121.Fa "long offset_sec" 122.Fc 123.Ft ASN1_UTCTIME * 124.Fo ASN1_UTCTIME_adj 125.Fa "ASN1_UTCTIME *s" 126.Fa "time_t t" 127.Fa "int offset_day" 128.Fa "long offset_sec" 129.Fc 130.Ft ASN1_GENERALIZEDTIME * 131.Fo ASN1_GENERALIZEDTIME_adj 132.Fa "ASN1_GENERALIZEDTIME *s" 133.Fa "time_t t" 134.Fa "int offset_day" 135.Fa "long offset_sec" 136.Fc 137.Ft int 138.Fo ASN1_TIME_set_string 139.Fa "ASN1_TIME *s" 140.Fa "const char *str" 141.Fc 142.Ft int 143.Fo ASN1_TIME_set_string_X509 144.Fa "ASN1_TIME *s" 145.Fa "const char *str" 146.Fc 147.Ft int 148.Fo ASN1_UTCTIME_set_string 149.Fa "ASN1_UTCTIME *s" 150.Fa "const char *str" 151.Fc 152.Ft int 153.Fo ASN1_GENERALIZEDTIME_set_string 154.Fa "ASN1_GENERALIZEDTIME *s" 155.Fa "const char *str" 156.Fc 157.Ft int 158.Fo ASN1_TIME_normalize 159.Fa "ASN1_TIME *s" 160.Fc 161.Ft int 162.Fo ASN1_TIME_check 163.Fa "const ASN1_TIME *t" 164.Fc 165.Ft int 166.Fo ASN1_UTCTIME_check 167.Fa "const ASN1_UTCTIME *t" 168.Fc 169.Ft int 170.Fo ASN1_GENERALIZEDTIME_check 171.Fa "const ASN1_GENERALIZEDTIME *t" 172.Fc 173.Ft int 174.Fo ASN1_TIME_print 175.Fa "BIO *b" 176.Fa "const ASN1_TIME *s" 177.Fc 178.Ft int 179.Fo ASN1_UTCTIME_print 180.Fa "BIO *b" 181.Fa "const ASN1_UTCTIME *s" 182.Fc 183.Ft int 184.Fo ASN1_GENERALIZEDTIME_print 185.Fa "BIO *b" 186.Fa "const ASN1_GENERALIZEDTIME *s" 187.Fc 188.Ft int 189.Fo ASN1_TIME_to_tm 190.Fa "const ASN1_TIME *s" 191.Fa "struct tm *tm" 192.Fc 193.Ft int 194.Fo ASN1_TIME_diff 195.Fa "int *pday" 196.Fa "int *psec" 197.Fa "const ASN1_TIME *from" 198.Fa "const ASN1_TIME *to" 199.Fc 200.Ft int 201.Fo ASN1_TIME_cmp_time_t 202.Fa "const ASN1_TIME *s" 203.Fa "time_t t" 204.Fc 205.Ft int 206.Fo ASN1_UTCTIME_cmp_time_t 207.Fa "const ASN1_UTCTIME *s" 208.Fa "time_t t" 209.Fc 210.Ft int 211.Fo ASN1_TIME_compare 212.Fa "const ASN1_TIME *s" 213.Fa "const ASN1_TIME *t" 214.Fc 215.Ft ASN1_GENERALIZEDTIME * 216.Fo ASN1_TIME_to_generalizedtime 217.Fa "const ASN1_TIME *t" 218.Fa "ASN1_GENERALIZEDTIME **out" 219.Fc 220.Sh DESCRIPTION 221An 222.Vt ASN1_TIME 223object is a shallow wrapper around a string containing an ASN.1 224.Vt Time 225value in the restricted format valid in X.509 certificates. 226An 227.Vt ASN1_TIME 228object is either an 229.Vt ASN1_UTCTIME 230object containing a string of the format 231.Ar YYMMDDHHMMSS Ns Cm Z 232which is valid for the years 1950 to 2049, or an 233.Vt ASN1_GENERALIZEDTIME 234object containing a string of the format 235.Ar YYYYMMDDHHMMSS Ns Cm Z 236which is valid for the years 0000 to 1949 and 2050 to 9999. 237In both cases, the mandatory suffix 238.Sq Cm Z 239represents the GMT time zone. 240LibreSSL by design does not support the full syntax of ASN.1 times. 241In particular, it neither supports fractional seconds 242nor any other time zone. 243.Pp 244The functions 245.Fn ASN1_TIME_set , 246.Fn ASN1_UTCTIME_set , 247and 248.Fn ASN1_GENERALIZEDTIME_set 249set the time object 250.Fa s 251to the time represented by the 252.Vt time_t 253value 254.Fa t . 255If 256.Fa s 257is 258.Dv NULL , 259a new time object is allocated and returned. 260.Pp 261The functions 262.Fn ASN1_TIME_adj , 263.Fn ASN1_UTCTIME_adj , 264and 265.Fn ASN1_GENERALIZEDTIME_adj 266set the time object 267.Fa s 268to the time represented by the time 269.Fa offset_day 270and 271.Fa offset_sec 272after the 273.Vt time_t 274value 275.Fa t . 276The values of 277.Fa offset_day 278or 279.Fa offset_sec 280can be negative to set a time before 281.Fa t . 282The 283.Fa offset_sec 284value can also exceed the number of seconds in a day. 285If 286.Fa s 287is 288.Dv NULL , 289a new time object is allocated and returned. 290.Pp 291.Fn ASN1_TIME_adj 292may change the type from 293.Vt ASN1_GENERALIZEDTIME 294to 295.Vt ASN1_UTCTIME 296or vice versa depending on the resulting year. 297The functions 298.Fn ASN1_UTCTIME_adj 299and 300.Fn ASN1_GENERALIZEDTIME_adj 301do not modify the type of the return object. 302.Pp 303The functions 304.Fn ASN1_TIME_set_string , 305.Fn ASN1_TIME_set_string_X509 , 306.Fn ASN1_UTCTIME_set_string , 307and 308.Fn ASN1_GENERALIZEDTIME_set_string 309set the time object 310.Fa s 311to the time string 312.Fa str , 313which must be in appropriate ASN.1 time format: 314YYMMDDHHMMSSZ for 315.Vt ASN1_UTCTIME , 316YYYYMMDDHHMMSSZ for 317.Vt ASN1_GENERALIZEDTIME , 318or either of the two for 319.Vt ASN1_TIME . 320The string 321.Fa str 322is copied into 323.Fa s . 324If 325.Fa s 326is 327.Dv NULL , 328these functions only perform a format check on 329.Fa str . 330.Pp 331In LibreSSL, 332.Fn ASN1_TIME_set_string 333and 334.Fn ASN1_TIME_set_string_X509 335behave identically and always set the time object 336to a valid value to use in an X.509 certificate. 337.Fn ASN1_GENERALIZEDTIME_set_string 338may encode a time string that is not valid in an X.509 certificate. 339.Pp 340The function 341.Fn ASN1_TIME_normalize 342converts an 343.Vt ASN1_GENERALIZEDTIME 344into a time value that can be used in a certificate 345by changing it to an 346.Vt ASN1_UTCTIME 347if possible. 348It has no effect on an 349.Vt ASN1_UTCTIME . 350.Pp 351The functions 352.Fn ASN1_TIME_check , 353.Fn ASN1_UTCTIME_check , 354and 355.Fn ASN1_GENERALIZEDTIME_check 356check the syntax of the time string contained in the object 357.Fa s . 358.Pp 359The functions 360.Fn ASN1_TIME_print , 361.Fn ASN1_UTCTIME_print , 362and 363.Fn ASN1_GENERALIZEDTIME_print 364print out the time 365.Fa s 366to 367.Vt BIO 368.Fa b 369in human readable format. 370It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example "Feb 3 37100:55:52 2015 GMT". 372It does not include a newline. 373If the time string has an invalid format, 374it prints out "Bad time value" and returns an error. 375.Pp 376The function 377.Fn ASN1_TIME_to_tm 378converts the time 379.Fa s 380to the standard 381.Vt tm 382structure. 383If 384.Fa s 385is 386.Dv NULL , 387then the current time is converted. 388The output time is always in the GMT time zone. 389The 390.Fa tm_sec , tm_min , tm_hour , tm_mday , tm_mon , 391and 392.Fa tm_year 393fields of the 394.Vt tm 395structure are set to the proper values, 396whereas all other fields are set to 0. 397If 398.Fa tm 399is 400.Dv NULL , 401this function performs a format check on 402.Fa s 403only. 404.Pp 405The function 406.Fn ASN1_TIME_diff 407sets 408.Pf * Fa pday 409and 410.Pf * Fa psec 411to the time difference between 412.Fa from 413and 414.Fa to . 415If 416.Fa to 417represents a time later than 418.Fa from , 419then one or both (depending on the time difference) of 420.Pf * Fa pday 421and 422.Pf * Fa psec 423will be positive. 424If 425.Fa to 426represents a time earlier than 427.Fa from , 428then one or both of 429.Pf * Fa pday 430and 431.Pf * Fa psec 432will be negative. 433If 434.Fa to 435and 436.Fa from 437represent the same time, then 438.Pf * Fa pday 439and 440.Pf * Fa psec 441will both be zero. 442If both 443.Pf * Fa pday 444and 445.Pf * Fa psec 446are nonzero, they will always have the same sign. 447The value of 448.Pf * Fa psec 449will always be less than the number of seconds in a day. 450If 451.Fa from 452or 453.Fa to 454is 455.Dv NULL , 456the current time is used. 457.Pp 458The functions 459.Fn ASN1_TIME_cmp_time_t , 460.Fn ASN1_UTCTIME_cmp_time_t , 461and 462.Fn ASN1_TIME_compare 463compare the two times represented by 464.Fa s 465and 466.Fa t . 467.Pp 468The function 469.Fn ASN1_TIME_to_generalizedtime 470converts the 471.Vt ASN1_TIME 472.Fa t 473to an 474.Vt ASN1_GENERALIZEDTIME , 475regardless of year. 476If either 477.Fa out 478or 479.Pf * Fa out 480is 481.Dv NULL , 482then a new object is allocated and must be freed after use. 483.Pp 484The 485.Vt ASN1_TIME , 486.Vt ASN1_UTCTIME , 487and 488.Vt ASN1_GENERALIZEDTIME 489objects are represented as 490.Vt ASN1_STRING 491objects internally and can be freed using 492.Xr ASN1_STRING_free 3 . 493.Pp 494It is recommended that 495.Vt ASN1_TIME 496functions be used instead of 497.Vt ASN1_UTCTIME 498or 499.Vt ASN1_GENERALIZEDTIME 500functions because the 501.Vt ASN1_UTCTIME 502and 503.Vt ASN1_GENERALIZEDTIME 504functions act only on that specific time format, while the 505.Vt ASN1_TIME 506functions operate on either format. 507.Sh RETURN VALUES 508.Fn ASN1_TIME_set , 509.Fn ASN1_UTCTIME_set , 510.Fn ASN1_GENERALIZEDTIME_set , 511.Fn ASN1_TIME_adj , 512.Fn ASN1_UTCTIME_adj , 513.Fn ASN1_GENERALIZEDTIME_adj , 514and 515.Fn ASN1_TIME_to_generalizedtime 516return a pointer to a time object or 517.Dv NULL 518if an error occurred. 519.Pp 520.Fn ASN1_TIME_set_string , 521.Fn ASN1_TIME_set_string_X509 , 522.Fn ASN1_UTCTIME_set_string , 523and 524.Fn ASN1_GENERALIZEDTIME_set_string 525return 1 if the time value is successfully set or 0 otherwise. 526.Pp 527.Fn ASN1_TIME_normalize 528returns 1 on success or 0 on error. 529.Pp 530.Fn ASN1_TIME_check , 531.Fn ASN1_UTCTIME_check , 532and 533.Fn ASN1_GENERALIZEDTIME_check 534return 1 if the time string contained in the object is syntactically 535correct or 0 otherwise. 536.Pp 537.Fn ASN1_TIME_print , 538.Fn ASN1_UTCTIME_print , 539and 540.Fn ASN1_GENERALIZEDTIME_print 541return 1 if the time is successfully printed or 0 if an error 542occurred (I/O error or invalid time format). 543.Pp 544.Fn ASN1_TIME_to_tm 545returns 1 if the time is successfully parsed 546or 0 if an error occurred, usually due to an invalid time format. 547.Pp 548.Fn ASN1_TIME_diff 549returns 1 for success or 0 for failure. 550It can for example fail if a time string passed in has invalid syntax. 551.Pp 552.Fn ASN1_TIME_cmp_time_t , 553.Fn ASN1_UTCTIME_cmp_time_t , 554and 555.Fn ASN1_TIME_compare 556return \-1 if 557.Fa s 558is earlier than 559.Fa t , 5600 if both are equal, 1 if 561.Fa s 562is later than 563.Fa t , 564or \-2 on error. 565.Sh EXAMPLES 566Set a time object to one hour after the current time and print it 567out: 568.Bd -literal -offset indent 569#include <time.h> 570#include <openssl/asn1.h> 571 572ASN1_TIME *asn1_time; 573time_t t; 574BIO *b; 575 576t = time(NULL); 577asn1_time = ASN1_TIME_adj(NULL, t, 0, 60 * 60); 578b = BIO_new_fp(stdout, BIO_NOCLOSE); 579if (asn1_time != NULL) { 580 ASN1_TIME_print(b, asn1_time); 581 BIO_printf(b, "\en"); 582} else { 583 BIO_printf(b, "Time out of range or un-representable\en"); 584} 585ASN1_STRING_free(asn1_time); 586BIO_free(b); 587.Ed 588.Sh SEE ALSO 589.Xr ASN1_TIME_new 3 , 590.Xr ASN1_time_parse 3 , 591.Xr X509_cmp_time 3 592.Sh STANDARDS 593The usage of the ASN.1 594.Vt Time , 595.Vt UTCTime , 596and 597.Vt GeneralizedTime 598data types in X.509 certificates is specified in 599RFC 5280, Internet X.509 Public Key Infrastructure Certificate and 600Certificate Revocation List (CRL) Profile, 601section 4.1.2.5 (TBS Certificate Validity). 602.Sh HISTORY 603.Fn ASN1_UTCTIME_check 604and 605.Fn ASN1_UTCTIME_print 606first appeared in SSLeay 0.5.1. 607.Fn ASN1_UTCTIME_set 608first appeared in SSLeay 0.6.0. 609.Fn ASN1_UTCTIME_set_string 610first appeared in SSLeay 0.9.0. 611All these functions have been available since 612.Ox 2.4 . 613.Pp 614.Fn ASN1_TIME_set , 615.Fn ASN1_GENERALIZEDTIME_set , 616.Fn ASN1_GENERALIZEDTIME_set_string , 617.Fn ASN1_GENERALIZEDTIME_check , 618.Fn ASN1_TIME_print , 619and 620.Fn ASN1_GENERALIZEDTIME_print 621first appeared in OpenSSL 0.9.2b and have been available since 622.Ox 2.6 . 623.Pp 624.Fn ASN1_UTCTIME_cmp_time_t 625first appeared in OpenSSL 0.9.6 and has been available since 626.Ox 2.9 . 627.Pp 628.Fn ASN1_TIME_check 629and 630.Fn ASN1_TIME_to_generalizedtime 631first appeared in OpenSSL 0.9.7 and have been available since 632.Ox 3.2 . 633.Pp 634.Fn ASN1_TIME_adj , 635.Fn ASN1_UTCTIME_adj , 636.Fn ASN1_GENERALIZEDTIME_adj , 637and 638.Fn ASN1_TIME_set_string 639first appeared in OpenSSL 1.0.0 and have been available since 640.Ox 4.9 . 641.Pp 642.Fn ASN1_TIME_diff 643first appeared in OpenSSL 1.0.2 and have been available since 644.Ox 7.1 . 645.Pp 646.Fn ASN1_TIME_set_string_X509 , 647.Fn ASN1_TIME_normalize , 648.Fn ASN1_TIME_to_tm , 649.Fn ASN1_TIME_cmp_time_t , 650and 651.Fn ASN1_TIME_compare 652first appeared in OpenSSL 1.1.1 and have been available since 653.Ox 7.2 . 654.Sh CAVEATS 655Some applications add offset times directly to a 656.Vt time_t 657value and pass the results to 658.Fn ASN1_TIME_set 659(or equivalent). 660This can cause problems as the 661.Vt time_t 662value can overflow on some systems resulting in unexpected results. 663New applications should use 664.Fn ASN1_TIME_adj 665instead and pass the offset value in the 666.Fa offset_sec 667and 668.Fa offset_day 669parameters instead of directly manipulating a 670.Vt time_t 671value. 672