Debian Codegraph @

upstream/debian-unstable/man3/TS_VERIFY_CTX.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 "TS_VERIFY_CTX 3SSL"
58 .TH TS_VERIFY_CTX 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 TS_VERIFY_CTX, TS_VERIFY_CTX_new, TS_VERIFY_CTX_init, TS_VERIFY_CTX_free,
65 TS_VERIFY_CTX_cleanup, TS_VERIFY_CTX_set_flags, TS_VERIFY_CTX_add_flags,
66 TS_VERIFY_CTX_set0_data, TS_VERIFY_CTX_set0_imprint, TS_VERIFY_CTX_set0_store,
67 TS_VERIFY_CTX_set0_certs, TS_VERIFY_CTX_set_certs, TS_VERIFY_CTS_set_certs,
68 TS_VERIFY_CTX_set_data, TS_VERIFY_CTX_set_imprint, TS_VERIFY_CTX_set_store
69 \&\- manage the TS response verification context
70 .SH SYNOPSIS
71 .IX Header "SYNOPSIS"
72 .Vb 1
73 \& #include <openssl/ts.h>
74 \&
75 \& typedef struct TS_verify_ctx TS_VERIFY_CTX;
76 \&
77 \& TS_VERIFY_CTX *TS_VERIFY_CTX_new(void);
78 \& void TS_VERIFY_CTX_init(TS_VERIFY_CTX *ctx);
79 \& void TS_VERIFY_CTX_free(TS_VERIFY_CTX *ctx);
80 \& void TS_VERIFY_CTX_cleanup(TS_VERIFY_CTX *ctx);
81 \& int TS_VERIFY_CTX_set_flags(TS_VERIFY_CTX *ctx, int f);
82 \& int TS_VERIFY_CTX_add_flags(TS_VERIFY_CTX *ctx, int f);
83 \& int TS_VERIFY_CTX_set0_data(TS_VERIFY_CTX *ctx, BIO *b);
84 \& int TS_VERIFY_CTX_set0_imprint(TS_VERIFY_CTX *ctx,
85 \& unsigned char *hexstr, long len);
86 \& int TS_VERIFY_CTX_set0_store(TS_VERIFY_CTX *ctx, X509_STORE *s);
87 \& int TS_VERIFY_CTX_set0_certs(TS_VERIFY_CTX *ctx, STACK_OF(X509) *certs);
88 .Ve
89 .PP
90 The following functions have been deprecated since OpenSSL 3.4:
91 .PP
92 .Vb 6
93 \& BIO *TS_VERIFY_CTX_set_data(TS_VERIFY_CTX *ctx, BIO *b);
94 \& unsigned char *TS_VERIFY_CTX_set_imprint(TS_VERIFY_CTX *ctx,
95 \& unsigned char *hexstr, long len);
96 \& X509_STORE *TS_VERIFY_CTX_set_store(TS_VERIFY_CTX *ctx, X509_STORE *s);
97 \& STACK_OF(X509) *TS_VERIFY_CTX_set_certs(TS_VERIFY_CTX *ctx,
98 \& STACK_OF(X509) *certs);
99 .Ve
100 .PP
101 The following function has been deprecated since OpenSSL 3.0:
102 .PP
103 .Vb 2
104 \& STACK_OF(X509) *TS_VERIFY_CTS_set_certs(TS_VERIFY_CTX *ctx,
105 \& STACK_OF(X509) *certs);
106 .Ve
107 .SH DESCRIPTION
108 .IX Header "DESCRIPTION"
109 The Time-Stamp Protocol (TSP) is defined by RFC 3161. TSP is a protocol used to
110 provide long-term proof of the existence of certain data before a particular
111 time. TSP defines a Time Stamping Authority (TSA) and an entity that makes
112 requests to the TSA. Usually, the TSA is referred to as the server side, and the
113 requesting entity is referred to as the client.
114 .PP
115 In TSP, when a server sends a response to a client, the server normally
116 needs to sign the response data \- the TimeStampToken (TST) \- with its private
117 key. Then the client verifies the received TST using the server's certificate
118 chain.
119 .PP
120 For all the following methods, unless noted otherwise, \fIctx\fR is the
121 verification context created in advance.
122 .PP
123 \&\fBTS_VERIFY_CTX_new()\fR returns an allocated \fBTS_VERIFY_CTX\fR structure.
124 .PP
125 \&\fBTS_VERIFY_CTX_init()\fR initializes a verification context.
126 .PP
127 \&\fBTS_VERIFY_CTX_free()\fR frees up a \fBTS_VERIFY_CTX\fR object. \fIctx\fR is the
128 verification context to be freed. If \fIctx\fR is NULL, the call is ignored.
129 .PP
130 \&\fBTS_VERIFY_CTX_set_flags()\fR sets the flags in the verification context. \fIf\fR are
131 the flags to be set.
132 .PP
133 \&\fBTS_VERIFY_CTX_add_flags()\fR adds flags to the verification context. \fIf\fR are the
134 flags to be added (OR'd).
135 .PP
136 \&\fBTS_VERIFY_CTX_set0_data()\fR sets the data to be verified. \fIb\fR is the \fBBIO\fR with
137 the data. A previously assigned \fBBIO\fR is freed.
138 .PP
139 \&\fBTS_VERIFY_CTX_set0_imprint()\fR sets the message imprint. \fIhexstr\fR is the
140 message imprint to be assigned. A previously assigned imprint is freed.
141 .PP
142 \&\fBTS_VERIFY_CTX_set0_store()\fR sets the store for the verification context. \fIs\fR is
143 the store to be assigned. A previously assigned store is freed.
144 .PP
145 \&\fBTS_VERIFY_CTX_set0_certs()\fR is used to set the server's certificate chain when
146 verifying a TST. \fIcerts\fR is a stack of \fBX509\fR certificates.
147 .PP
148 \&\fBTS_VERIFY_CTX_cleanup()\fR frees all data associated with the given
149 \&\fBTS_VERIFY_CTX\fR object and initializes it. \fIctx\fR is the verification context
150 created in advance. If \fIctx\fR is NULL, the call is ignored.
151 .PP
152 All of the following functions described are deprecated. Applications should
153 instead use the functions \fBTS_VERIFY_CTX_set0_data\fR\|(3),
154 \&\fBTS_VERIFY_CTX_set0_imprint\fR\|(3), \fBTS_VERIFY_CTX_set0_store\fR\|(3),
155 \&\fBTS_VERIFY_CTX_set0_certs\fR\|(3).
156 .PP
157 \&\fBTS_VERIFY_CTX_set_data()\fR is used to set the BIO with the data to be verified.
158 A previously assigned BIO is \fBnot freed\fR by this call. \fIb\fR is the \fBBIO\fR
159 with the data to assign.
160 .PP
161 \&\fBTS_VERIFY_CTX_set_imprint()\fR is used to set the message imprint. A previously
162 assigned imprint \fBis freed\fR by this call. \fIhexstr\fR is the string with the
163 message imprint to assign.
164 .PP
165 \&\fBTS_VERIFY_CTX_set_store()\fR is used to set the certificate store. A previously
166 assigned store is \fBnot freed\fR by this call. \fIs\fR is the store to assign.
167 .PP
168 \&\fBTS_VERIFY_CTX_set_certs()\fR is used to set the server's certificate chain.
169 A previously assigned stack is \fBnot freed\fR by this call. \fIcerts\fR is a stack
170 of \fBX509\fR certificates.
171 .PP
172 \&\fBTS_VERIFY_CTS_set_certs()\fR is a misspelled version of \fBTS_VERIFY_CTX_set_certs()\fR
173 which takes the same parameters and returns the same result.
174 .SH "RETURN VALUES"
175 .IX Header "RETURN VALUES"
176 \&\fBTS_VERIFY_CTX_new()\fR returns an allocated \fBTS_VERIFY_CTX\fR structure.
177 .PP
178 \&\fBTS_VERIFY_CTX_set_flags()\fR returns the flags passed via parameter \fIf\fR.
179 .PP
180 \&\fBTS_VERIFY_CTX_add_flags()\fR returns the flags of the context after the ones
181 passed via parameter \fIf\fR are added to it.
182 .PP
183 \&\fBTS_VERIFY_CTX_set0_data()\fR, \fBTS_VERIFY_CTX_set0_imprint()\fR,
184 \&\fBTS_VERIFY_CTX_set0_store()\fR, and \fBTS_VERIFY_CTX_set0_certs()\fR return 1 if the
185 value could be successfully set and 0 in case of any error.
186 .PP
187 The deprecated functions \fBTS_VERIFY_CTX_set_data()\fR, \fBTS_VERIFY_CTX_set_imprint()\fR,
188 \&\fBTS_VERIFY_CTX_set_store()\fR, \fBTS_VERIFY_CTX_set_certs()\fR return the parameter
189 the user passes via parameter \fIbio\fR, \fIhexstr\fR, \fIs\fR or \fIcerts\fR.
190 .SH "SEE ALSO"
191 .IX Header "SEE ALSO"
192 \&\fBOSSL_ESS_check_signing_certs\fR\|(3)
193 .SH HISTORY
194 .IX Header "HISTORY"
195 \&\fBTS_VERIFY_CTX_set0_data()\fR, \fBTS_VERIFY_CTX_set0_imprint()\fR,
196 \&\fBTS_VERIFY_CTX_set0_store()\fR, \fBTS_VERIFY_CTX_set0_certs()\fR replace the functions
197 \&\fBTS_VERIFY_CTX_set_data()\fR, \fBTS_VERIFY_CTX_set_imprint()\fR,
198 \&\fBTS_VERIFY_CTX_set_store()\fR, \fBTS_VERIFY_CTX_set_certs()\fR that were deprecated
199 in OpenSSL 3.4.0.
200 .PP
201 The spelling of \fBTS_VERIFY_CTX_set_certs()\fR was corrected in OpenSSL 3.0.0.
202 The misspelled version \fBTS_VERIFY_CTS_set_certs()\fR has been retained for
203 compatibility reasons, but it is deprecated in OpenSSL 3.0.0.
204 .SH COPYRIGHT
205 .IX Header "COPYRIGHT"
206 Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved.
207 .PP
208 Licensed under the Apache License 2.0 (the "License"). You may not use
209 this file except in compliance with the License. You can obtain a copy
210 in the file LICENSE in the source distribution or at
211 <https://www.openssl.org/source/license.html>.