Document X509_gmtime_adj(3).

While here, improve some argument names, improve ordering of the
material, and mention the meaning of negative and of large arguments,

1 files changed, 67 insertions, 23 deletions

diff --git a/src/lib/libcrypto/man/X509_cmp_time.3 b/src/lib/libcrypto/man/X509_cmp_time.3
index 96b671f3c9..7c61e2f605 100644
--- a/src/lib/libcrypto/man/X509_cmp_time.3
+++ b/src/lib/libcrypto/man/X509_cmp_time.3
@@ -1,7 +1,24 @@
-.\"     $OpenBSD: X509_cmp_time.3,v 1.9 2019/06/06 01:06:59 schwarze Exp $
-.\"     OpenSSL X509_cmp_time.pod 24053693 Mar 28 14:27:37 2017 +0200
+.\" $OpenBSD: X509_cmp_time.3,v 1.10 2021/11/08 14:44:14 schwarze Exp $
+.\" full merge up to: OpenSSL 83cf7abf May 29 13:07:08 2018 +0100
 .\"
-.\" This file was written by Emilia Kasper <emilia@openssl.org>
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2017, 2021 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" The original file was written by Emilia Kasper <emilia@openssl.org>
 .\" Copyright (c) 2017 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -48,14 +65,15 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 6 2019 $
+.Dd $Mdocdate: November 8 2021 $
 .Dt X509_CMP_TIME 3
 .Os
 .Sh NAME
 .Nm X509_cmp_time ,
 .Nm X509_cmp_current_time ,
 .Nm X509_time_adj_ex ,
-.Nm X509_time_adj
+.Nm X509_time_adj ,
+.Nm X509_gmtime_adj
 .Nd ASN.1 Time utilities
 .Sh SYNOPSIS
 .In openssl/x509.h
@@ -70,16 +88,21 @@
 .Fc
 .Ft ASN1_TIME *
 .Fo X509_time_adj_ex
-.Fa "ASN1_TIME *asn1_time"
+.Fa "ASN1_TIME *out_time"
 .Fa "int offset_day"
 .Fa "long offset_sec"
-.Fa "time_t *in_tm"
+.Fa "time_t *in_time"
 .Fc
 .Ft ASN1_TIME *
 .Fo X509_time_adj
-.Fa "ASN1_TIME *asn1_time"
+.Fa "ASN1_TIME *out_time"
+.Fa "long offset_sec"
+.Fa "time_t *in_time"
+.Fc
+.Ft ASN1_TIME *
+.Fo X509_gmtime_adj
+.Fa "ASN1_TIME *out_time"
 .Fa "long offset_sec"
-.Fa "time_t *in_tm"
 .Fc
 .Sh DESCRIPTION
 .Fn X509_cmp_time
@@ -94,28 +117,46 @@ compares it to the current time.
 .Pp
 .Fn X509_time_adj_ex
 sets
-.Fa asn1_time
+.Fa out_time
 to a time
 .Fa offset_day
 and
 .Fa offset_sec
 later than
-.Fa in_tm .
-.Fn X509_time_adj
-does the same with a 0 day offset.
+.Fa in_time .
+The values of
+.Fa offset_day
+and
+.Fa offset_sec
+can be negative to set a time before
+.Fa in_time .
+The
+.Fa offset_sec
+value can also exceed the number of seconds in a day.
 If
-.Fa asn1_time
+.Fa in_time
+is
+.Dv NULL ,
+the current time is used instead.
+If
+.Fa out_time
 is
 .Dv NULL ,
 a new
 .Vt ASN1_TIME
 structure is allocated and returned.
 .Pp
-In all functions, if
-.Fa in_tm
-is
-.Dv NULL ,
-the current time is used.
+.Fn X509_time_adj
+does the same with a 0 day offset.
+.Pp
+.Fn X509_gmtime_adj
+does the same using the current time instead of
+.Fa in_time ,
+that is, it sets
+.Fa out_time
+to a time
+.Fa offset_sec
+seconds later than the current time.
 .Sh RETURN VALUES
 .Fn X509_cmp_time
 and
@@ -126,10 +167,11 @@ is earlier than or equal to
 .Fa cmp_time ,
 1 if it is later, or 0 on error.
 .Pp
-.Fn X509_time_adj_ex
+.Fn X509_time_adj_ex ,
+.Fn X509_time_adj ,
 and
-.Fn X509_time_adj
-return a pointer to the updated
+.Fn X509_gmtime_adj
+return a pointer to the updated or newly allocated
 .Vt ASN1_TIME
 structure or
 .Dv NULL
@@ -141,7 +183,9 @@ on error.
 .Xr time 3
 .Sh HISTORY
 .Fn X509_cmp_current_time
-first appeared in SSLeay 0.6.0 and has been available since
+and
+.Fn X509_gmtime_adj
+first appeared in SSLeay 0.6.0 and have been available since
 .Ox 2.4 .
 .Pp
 .Fn X509_cmp_time