Debian Codegraph @

upstream/debian-unstable/man3/X509_cmp_time.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "X509_CMP_TIME 3SSL"
58 .TH X509_CMP_TIME 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 X509_cmp_time, X509_cmp_current_time, X509_cmp_timeframe,
65 X509_time_adj, X509_time_adj_ex, X509_gmtime_adj
66 \&\- X509 time functions
67 .SH SYNOPSIS
68 .IX Header "SYNOPSIS"
69 .Vb 8
70 \& int X509_cmp_time(const ASN1_TIME *asn1_time, time_t *in_tm);
71 \& int X509_cmp_current_time(const ASN1_TIME *asn1_time);
72 \& int X509_cmp_timeframe(const X509_VERIFY_PARAM *vpm,
73 \& const ASN1_TIME *start, const ASN1_TIME *end);
74 \& ASN1_TIME *X509_time_adj(ASN1_TIME *asn1_time, long offset_sec, time_t *in_tm);
75 \& ASN1_TIME *X509_time_adj_ex(ASN1_TIME *asn1_time, int offset_day, long
76 \& offset_sec, time_t *in_tm);
77 \& ASN1_TIME *X509_gmtime_adj(ASN1_TIME *asn1_time, long offset_sec);
78 .Ve
79 .SH DESCRIPTION
80 .IX Header "DESCRIPTION"
81 \&\fBX509_cmp_time()\fR compares the ASN1_TIME in \fIasn1_time\fR with the time
82 in <in_tm>.
83 .PP
84 \&\fBX509_cmp_current_time()\fR compares the ASN1_TIME in
85 \&\fIasn1_time\fR with the current time, expressed as time_t.
86 .PP
87 \&\fBX509_cmp_timeframe()\fR compares the given time period with the reference time
88 included in the verification parameters \fIvpm\fR if they are not NULL and contain
89 \&\fBX509_V_FLAG_USE_CHECK_TIME\fR; else the current time is used as reference time.
90 .PP
91 \&\fBX509_time_adj_ex()\fR sets the ASN1_TIME structure \fIasn1_time\fR to the time
92 \&\fIoffset_day\fR and \fIoffset_sec\fR after \fIin_tm\fR.
93 .PP
94 \&\fBX509_time_adj()\fR sets the ASN1_TIME structure \fIasn1_time\fR to the time
95 \&\fIoffset_sec\fR after \fIin_tm\fR. This method can only handle second
96 offsets up to the capacity of long, so the newer \fBX509_time_adj_ex()\fR
97 API should be preferred.
98 .PP
99 In both methods, if \fIasn1_time\fR is NULL, a new ASN1_TIME structure
100 is allocated and returned.
101 .PP
102 In all methods, if \fIin_tm\fR is NULL, the current time, expressed as
103 time_t, is used.
104 .PP
105 \&\fIasn1_time\fR must satisfy the ASN1_TIME format mandated by RFC 5280,
106 i.e., its format must be either YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ.
107 .PP
108 \&\fBX509_gmtime_adj()\fR sets the ASN1_TIME structure \fIasn1_time\fR to the time
109 \&\fIoffset_sec\fR after the current time. It is equivalent to calling
110 \&\fBX509_time_adj()\fR with the last parameter as NULL.
111 .SH BUGS
112 .IX Header "BUGS"
113 Unlike many standard comparison functions, \fBX509_cmp_time()\fR and
114 \&\fBX509_cmp_current_time()\fR return 0 on error.
115 .SH "RETURN VALUES"
116 .IX Header "RETURN VALUES"
117 \&\fBX509_cmp_time()\fR and \fBX509_cmp_current_time()\fR return \-1 if \fIasn1_time\fR
118 is earlier than, or equal to, \fIin_tm\fR (resp. current time), and 1
119 otherwise. These methods return 0 on error.
120 .PP
121 \&\fBX509_cmp_timeframe()\fR returns 0 if \fIvpm\fR is not NULL and the verification
122 parameters do not contain \fBX509_V_FLAG_USE_CHECK_TIME\fR
123 but do contain \fBX509_V_FLAG_NO_CHECK_TIME\fR. Otherwise it returns
124 1 if the end time is not NULL and the reference time (which has determined as
125 stated above) is past the end time, \-1 if the start time is not NULL and the
126 reference time is before, else 0 to indicate that the reference time is in range
127 (implying that the end time is not before the start time if both are present).
128 .PP
129 \&\fBX509_time_adj()\fR, \fBX509_time_adj_ex()\fR and \fBX509_gmtime_adj()\fR return a pointer to
130 the updated ASN1_TIME structure, and NULL on error.
131 .SH HISTORY
132 .IX Header "HISTORY"
133 \&\fBX509_cmp_timeframe()\fR was added in OpenSSL 3.0.
134 .SH COPYRIGHT
135 .IX Header "COPYRIGHT"
136 Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved.
137 .PP
138 Licensed under the Apache License 2.0 (the "License"). You may not use
139 this file except in compliance with the License. You can obtain a copy
140 in the file LICENSE in the source distribution or at
141 <https://www.openssl.org/source/license.html>.