1.\" $OpenBSD: ASN1_TIME_set.3,v 1.21 2023/11/16 14:20:49 tb 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 16 2023 $ 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.Nm OPENSSL_gmtime , 99.Nm OPENSSL_timegm 100.Nd ASN.1 Time functions 101.Sh SYNOPSIS 102.In openssl/asn1.h 103.Ft ASN1_TIME * 104.Fo ASN1_TIME_set 105.Fa "ASN1_TIME *s" 106.Fa "time_t t" 107.Fc 108.Ft ASN1_UTCTIME * 109.Fo ASN1_UTCTIME_set 110.Fa "ASN1_UTCTIME *s" 111.Fa "time_t t" 112.Fc 113.Ft ASN1_GENERALIZEDTIME * 114.Fo ASN1_GENERALIZEDTIME_set 115.Fa "ASN1_GENERALIZEDTIME *s" 116.Fa "time_t t" 117.Fc 118.Ft ASN1_TIME * 119.Fo ASN1_TIME_adj 120.Fa "ASN1_TIME *s" 121.Fa "time_t t" 122.Fa "int offset_day" 123.Fa "long offset_sec" 124.Fc 125.Ft ASN1_UTCTIME * 126.Fo ASN1_UTCTIME_adj 127.Fa "ASN1_UTCTIME *s" 128.Fa "time_t t" 129.Fa "int offset_day" 130.Fa "long offset_sec" 131.Fc 132.Ft ASN1_GENERALIZEDTIME * 133.Fo ASN1_GENERALIZEDTIME_adj 134.Fa "ASN1_GENERALIZEDTIME *s" 135.Fa "time_t t" 136.Fa "int offset_day" 137.Fa "long offset_sec" 138.Fc 139.Ft int 140.Fo ASN1_TIME_set_string 141.Fa "ASN1_TIME *s" 142.Fa "const char *str" 143.Fc 144.Ft int 145.Fo ASN1_TIME_set_string_X509 146.Fa "ASN1_TIME *s" 147.Fa "const char *str" 148.Fc 149.Ft int 150.Fo ASN1_UTCTIME_set_string 151.Fa "ASN1_UTCTIME *s" 152.Fa "const char *str" 153.Fc 154.Ft int 155.Fo ASN1_GENERALIZEDTIME_set_string 156.Fa "ASN1_GENERALIZEDTIME *s" 157.Fa "const char *str" 158.Fc 159.Ft int 160.Fo ASN1_TIME_normalize 161.Fa "ASN1_TIME *s" 162.Fc 163.Ft int 164.Fo ASN1_TIME_check 165.Fa "const ASN1_TIME *t" 166.Fc 167.Ft int 168.Fo ASN1_UTCTIME_check 169.Fa "const ASN1_UTCTIME *t" 170.Fc 171.Ft int 172.Fo ASN1_GENERALIZEDTIME_check 173.Fa "const ASN1_GENERALIZEDTIME *t" 174.Fc 175.Ft int 176.Fo ASN1_TIME_print 177.Fa "BIO *b" 178.Fa "const ASN1_TIME *s" 179.Fc 180.Ft int 181.Fo ASN1_UTCTIME_print 182.Fa "BIO *b" 183.Fa "const ASN1_UTCTIME *s" 184.Fc 185.Ft int 186.Fo ASN1_GENERALIZEDTIME_print 187.Fa "BIO *b" 188.Fa "const ASN1_GENERALIZEDTIME *s" 189.Fc 190.Ft int 191.Fo ASN1_TIME_to_tm 192.Fa "const ASN1_TIME *s" 193.Fa "struct tm *tm" 194.Fc 195.Ft int 196.Fo ASN1_TIME_diff 197.Fa "int *pday" 198.Fa "int *psec" 199.Fa "const ASN1_TIME *from" 200.Fa "const ASN1_TIME *to" 201.Fc 202.Ft int 203.Fo ASN1_TIME_cmp_time_t 204.Fa "const ASN1_TIME *s" 205.Fa "time_t t" 206.Fc 207.Ft int 208.Fo ASN1_UTCTIME_cmp_time_t 209.Fa "const ASN1_UTCTIME *s" 210.Fa "time_t t" 211.Fc 212.Ft int 213.Fo ASN1_TIME_compare 214.Fa "const ASN1_TIME *s" 215.Fa "const ASN1_TIME *t" 216.Fc 217.Ft ASN1_GENERALIZEDTIME * 218.Fo ASN1_TIME_to_generalizedtime 219.Fa "const ASN1_TIME *t" 220.Fa "ASN1_GENERALIZEDTIME **out" 221.Fc 222.Ft struct tm * 223.Fo OPENSSL_gmtime 224.Fa "const time_t *time" 225.Fa "struct tm *out_tm" 226.Fc 227.Ft int 228.Fo OPENSSL_timegm 229.Fa "const struct tm *tm" 230.Fa "time_t *out_time" 231.Fc 232.Sh DESCRIPTION 233An 234.Vt ASN1_TIME 235object is a shallow wrapper around a string containing an ASN.1 236.Vt Time 237value in the restricted format valid in X.509 certificates. 238An 239.Vt ASN1_TIME 240object is either an 241.Vt ASN1_UTCTIME 242object containing a string of the format 243.Ar YYMMDDHHMMSS Ns Cm Z 244which is valid for the years 1950 to 2049, or an 245.Vt ASN1_GENERALIZEDTIME 246object containing a string of the format 247.Ar YYYYMMDDHHMMSS Ns Cm Z 248which is valid for the years 0000 to 1949 and 2050 to 9999. 249In both cases, the mandatory suffix 250.Sq Cm Z 251represents the GMT time zone. 252LibreSSL by design does not support the full syntax of ASN.1 times. 253In particular, it neither supports fractional seconds 254nor any other time zone. 255.Pp 256The functions 257.Fn ASN1_TIME_set , 258.Fn ASN1_UTCTIME_set , 259and 260.Fn ASN1_GENERALIZEDTIME_set 261set the time object 262.Fa s 263to the time represented by the 264.Vt time_t 265value 266.Fa t . 267If 268.Fa s 269is 270.Dv NULL , 271a new time object is allocated and returned. 272.Pp 273The functions 274.Fn ASN1_TIME_adj , 275.Fn ASN1_UTCTIME_adj , 276and 277.Fn ASN1_GENERALIZEDTIME_adj 278set the time object 279.Fa s 280to the time represented by the time 281.Fa offset_day 282and 283.Fa offset_sec 284after the 285.Vt time_t 286value 287.Fa t . 288The values of 289.Fa offset_day 290or 291.Fa offset_sec 292can be negative to set a time before 293.Fa t . 294The 295.Fa offset_sec 296value can also exceed the number of seconds in a day. 297If 298.Fa s 299is 300.Dv NULL , 301a new time object is allocated and returned. 302.Pp 303.Fn ASN1_TIME_adj 304may change the type from 305.Vt ASN1_GENERALIZEDTIME 306to 307.Vt ASN1_UTCTIME 308or vice versa depending on the resulting year. 309The functions 310.Fn ASN1_UTCTIME_adj 311and 312.Fn ASN1_GENERALIZEDTIME_adj 313do not modify the type of the return object. 314.Pp 315The functions 316.Fn ASN1_TIME_set_string , 317.Fn ASN1_TIME_set_string_X509 , 318.Fn ASN1_UTCTIME_set_string , 319and 320.Fn ASN1_GENERALIZEDTIME_set_string 321set the time object 322.Fa s 323to the time string 324.Fa str , 325which must be in appropriate ASN.1 time format: 326YYMMDDHHMMSSZ for 327.Vt ASN1_UTCTIME , 328YYYYMMDDHHMMSSZ for 329.Vt ASN1_GENERALIZEDTIME , 330or either of the two for 331.Vt ASN1_TIME . 332The string 333.Fa str 334is copied into 335.Fa s . 336If 337.Fa s 338is 339.Dv NULL , 340these functions only perform a format check on 341.Fa str . 342.Pp 343In LibreSSL, 344.Fn ASN1_TIME_set_string 345and 346.Fn ASN1_TIME_set_string_X509 347behave identically and always set the time object 348to a valid value to use in an X.509 certificate. 349.Fn ASN1_GENERALIZEDTIME_set_string 350may encode a time string that is not valid in an X.509 certificate. 351.Pp 352The function 353.Fn ASN1_TIME_normalize 354converts an 355.Vt ASN1_GENERALIZEDTIME 356into a time value that can be used in a certificate 357by changing it to an 358.Vt ASN1_UTCTIME 359if possible. 360It has no effect on an 361.Vt ASN1_UTCTIME . 362.Pp 363The functions 364.Fn ASN1_TIME_check , 365.Fn ASN1_UTCTIME_check , 366and 367.Fn ASN1_GENERALIZEDTIME_check 368check the syntax of the time string contained in the object 369.Fa s . 370.Pp 371The functions 372.Fn ASN1_TIME_print , 373.Fn ASN1_UTCTIME_print , 374and 375.Fn ASN1_GENERALIZEDTIME_print 376print out the time 377.Fa s 378to 379.Vt BIO 380.Fa b 381in human readable format. 382It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example "Feb 3 38300:55:52 2015 GMT". 384It does not include a newline. 385If the time string has an invalid format, 386it prints out "Bad time value" and returns an error. 387.Pp 388The function 389.Fn ASN1_TIME_to_tm 390converts the time 391.Fa s 392to the standard 393.Vt tm 394structure. 395If 396.Fa s 397is 398.Dv NULL , 399then the current time is converted. 400The output time is always in the GMT time zone. 401The 402.Fa tm_sec , tm_min , tm_hour , tm_mday , tm_mon , 403and 404.Fa tm_year 405fields of the 406.Vt tm 407structure are set to the proper values, 408whereas all other fields are set to 0. 409If 410.Fa tm 411is 412.Dv NULL , 413this function performs a format check on 414.Fa s 415only. 416.Pp 417The function 418.Fn ASN1_TIME_diff 419sets 420.Pf * Fa pday 421and 422.Pf * Fa psec 423to the time difference between 424.Fa from 425and 426.Fa to . 427If 428.Fa to 429represents a time later than 430.Fa from , 431then one or both (depending on the time difference) of 432.Pf * Fa pday 433and 434.Pf * Fa psec 435will be positive. 436If 437.Fa to 438represents a time earlier than 439.Fa from , 440then one or both of 441.Pf * Fa pday 442and 443.Pf * Fa psec 444will be negative. 445If 446.Fa to 447and 448.Fa from 449represent the same time, then 450.Pf * Fa pday 451and 452.Pf * Fa psec 453will both be zero. 454If both 455.Pf * Fa pday 456and 457.Pf * Fa psec 458are nonzero, they will always have the same sign. 459The value of 460.Pf * Fa psec 461will always be less than the number of seconds in a day. 462If 463.Fa from 464or 465.Fa to 466is 467.Dv NULL , 468the current time is used. 469.Pp 470The functions 471.Fn ASN1_TIME_cmp_time_t , 472.Fn ASN1_UTCTIME_cmp_time_t , 473and 474.Fn ASN1_TIME_compare 475compare the two times represented by 476.Fa s 477and 478.Fa t . 479.Pp 480The function 481.Fn ASN1_TIME_to_generalizedtime 482converts the 483.Vt ASN1_TIME 484.Fa t 485to an 486.Vt ASN1_GENERALIZEDTIME , 487regardless of year. 488If either 489.Fa out 490or 491.Pf * Fa out 492is 493.Dv NULL , 494then a new object is allocated and must be freed after use. 495.Pp 496The 497.Vt ASN1_TIME , 498.Vt ASN1_UTCTIME , 499and 500.Vt ASN1_GENERALIZEDTIME 501objects are represented as 502.Vt ASN1_STRING 503objects internally and can be freed using 504.Xr ASN1_STRING_free 3 . 505.Pp 506It is recommended that 507.Vt ASN1_TIME 508functions be used instead of 509.Vt ASN1_UTCTIME 510or 511.Vt ASN1_GENERALIZEDTIME 512functions because the 513.Vt ASN1_UTCTIME 514and 515.Vt ASN1_GENERALIZEDTIME 516functions act only on that specific time format, while the 517.Vt ASN1_TIME 518functions operate on either format. 519.Pp 520.Fn OPENSSL_gmtime 521converts a time_t value in 522.Fa time 523to a struct tm in 524.Fa out_tm 525and also returns the struct passed in on success. 526.Pp 527.Fn OPENSSL_timegm 528converts a time structure in UTC time in 529.Fa tm 530to a time_t value in 531.Fa out_time . 532.Sh RETURN VALUES 533.Fn ASN1_TIME_set , 534.Fn ASN1_UTCTIME_set , 535.Fn ASN1_GENERALIZEDTIME_set , 536.Fn ASN1_TIME_adj , 537.Fn ASN1_UTCTIME_adj , 538.Fn ASN1_GENERALIZEDTIME_adj , 539and 540.Fn ASN1_TIME_to_generalizedtime 541return a pointer to a time object or 542.Dv NULL 543if an error occurred. 544.Pp 545.Fn ASN1_TIME_set_string , 546.Fn ASN1_TIME_set_string_X509 , 547.Fn ASN1_UTCTIME_set_string , 548and 549.Fn ASN1_GENERALIZEDTIME_set_string 550return 1 if the time value is successfully set or 0 otherwise. 551.Pp 552.Fn ASN1_TIME_normalize 553returns 1 on success or 0 on error. 554.Pp 555.Fn ASN1_TIME_check , 556.Fn ASN1_UTCTIME_check , 557and 558.Fn ASN1_GENERALIZEDTIME_check 559return 1 if the time string contained in the object is syntactically 560correct or 0 otherwise. 561.Pp 562.Fn ASN1_TIME_print , 563.Fn ASN1_UTCTIME_print , 564and 565.Fn ASN1_GENERALIZEDTIME_print 566return 1 if the time is successfully printed or 0 if an error 567occurred (I/O error or invalid time format). 568.Pp 569.Fn ASN1_TIME_to_tm 570returns 1 if the time is successfully parsed 571or 0 if an error occurred, usually due to an invalid time format. 572.Pp 573.Fn ASN1_TIME_diff 574returns 1 for success or 0 for failure. 575It can for example fail if a time string passed in has invalid syntax. 576.Pp 577.Fn ASN1_TIME_cmp_time_t , 578.Fn ASN1_UTCTIME_cmp_time_t , 579and 580.Fn ASN1_TIME_compare 581return \-1 if 582.Fa s 583is earlier than 584.Fa t , 5850 if both are equal, 1 if 586.Fa s 587is later than 588.Fa t , 589or \-2 on error. 590.Pp 591.Fn OPENSSL_timegm 592returns 1 for success or 0 for failure. 593It can fail if the time is not representable in a time_t, 594or falls outside the range allowed in RFC 5280 times. 595.Pp 596.Fn OPENSSL_gmtime 597returns 598.Fa out_tm 599on success or NULL for failure. 600It can fail if the time is not representable in a struct tm, 601or falls outside the range allowed in RFC 5280 times. 602.Sh EXAMPLES 603Set a time object to one hour after the current time and print it 604out: 605.Bd -literal -offset indent 606#include <time.h> 607#include <openssl/asn1.h> 608 609ASN1_TIME *asn1_time; 610time_t t; 611BIO *b; 612 613t = time(NULL); 614asn1_time = ASN1_TIME_adj(NULL, t, 0, 60 * 60); 615b = BIO_new_fp(stdout, BIO_NOCLOSE); 616if (asn1_time != NULL) { 617 ASN1_TIME_print(b, asn1_time); 618 BIO_printf(b, "\en"); 619} else { 620 BIO_printf(b, "Time out of range or un-representable\en"); 621} 622ASN1_STRING_free(asn1_time); 623BIO_free(b); 624.Ed 625.Sh SEE ALSO 626.Xr ASN1_TIME_new 3 , 627.Xr ASN1_time_parse 3 , 628.Xr X509_cmp_time 3 629.Sh STANDARDS 630The usage of the ASN.1 631.Vt Time , 632.Vt UTCTime , 633and 634.Vt GeneralizedTime 635data types in X.509 certificates is specified in 636RFC 5280, Internet X.509 Public Key Infrastructure Certificate and 637Certificate Revocation List (CRL) Profile, 638section 4.1.2.5 (TBS Certificate Validity). 639.Sh HISTORY 640.Fn ASN1_UTCTIME_check 641and 642.Fn ASN1_UTCTIME_print 643first appeared in SSLeay 0.5.1. 644.Fn ASN1_UTCTIME_set 645first appeared in SSLeay 0.6.0. 646.Fn ASN1_UTCTIME_set_string 647first appeared in SSLeay 0.9.0. 648All these functions have been available since 649.Ox 2.4 . 650.Pp 651.Fn ASN1_TIME_set , 652.Fn ASN1_GENERALIZEDTIME_set , 653.Fn ASN1_GENERALIZEDTIME_set_string , 654.Fn ASN1_GENERALIZEDTIME_check , 655.Fn ASN1_TIME_print , 656and 657.Fn ASN1_GENERALIZEDTIME_print 658first appeared in OpenSSL 0.9.2b and have been available since 659.Ox 2.6 . 660.Pp 661.Fn ASN1_UTCTIME_cmp_time_t 662first appeared in OpenSSL 0.9.6 and has been available since 663.Ox 2.9 . 664.Pp 665.Fn ASN1_TIME_check 666and 667.Fn ASN1_TIME_to_generalizedtime 668first appeared in OpenSSL 0.9.7 and have been available since 669.Ox 3.2 . 670.Pp 671.Fn ASN1_TIME_adj , 672.Fn ASN1_UTCTIME_adj , 673.Fn ASN1_GENERALIZEDTIME_adj , 674and 675.Fn ASN1_TIME_set_string 676first appeared in OpenSSL 1.0.0 and have been available since 677.Ox 4.9 . 678.Pp 679.Fn ASN1_TIME_diff 680first appeared in OpenSSL 1.0.2 and have been available since 681.Ox 7.1 . 682.Pp 683.Fn ASN1_TIME_set_string_X509 , 684.Fn ASN1_TIME_normalize , 685.Fn ASN1_TIME_to_tm , 686.Fn ASN1_TIME_cmp_time_t , 687and 688.Fn ASN1_TIME_compare 689first appeared in OpenSSL 1.1.1 and have been available since 690.Ox 7.2 . 691.Pp 692.Fn OPENSSL_gmtime 693and 694.Fn OPENSSL_timegm 695first appeared in BoringSSL and have been available since 696.Ox 7.5 . 697.Sh CAVEATS 698Some applications add offset times directly to a 699.Vt time_t 700value and pass the results to 701.Fn ASN1_TIME_set 702(or equivalent). 703This can cause problems as the 704.Vt time_t 705value can overflow on some systems resulting in unexpected results. 706New applications should use 707.Fn ASN1_TIME_adj 708instead and pass the offset value in the 709.Fa offset_sec 710and 711.Fa offset_day 712parameters instead of directly manipulating a 713.Vt time_t 714value. 715