xref: /openssl/doc/man3/TS_VERIFY_CTX.pod (revision 2c1ef172) 
1=pod
2
3=head1 NAME
4
5TS_VERIFY_CTX, TS_VERIFY_CTX_new, TS_VERIFY_CTX_init, TS_VERIFY_CTX_free,
6TS_VERIFY_CTX_cleanup, TS_VERIFY_CTX_set_flags, TS_VERIFY_CTX_add_flags,
7TS_VERIFY_CTX_set0_data, TS_VERIFY_CTX_set0_imprint, TS_VERIFY_CTX_set0_store,
8TS_VERIFY_CTX_set0_certs, TS_VERIFY_CTX_set_certs, TS_VERIFY_CTS_set_certs,
9TS_VERIFY_CTX_set_data, TS_VERIFY_CTX_set_imprint, TS_VERIFY_CTX_set_store
10- manage the TS response verification context
11
12=head1 SYNOPSIS
13
14 #include <openssl/ts.h>
15
16 typedef struct TS_verify_ctx TS_VERIFY_CTX;
17
18 TS_VERIFY_CTX *TS_VERIFY_CTX_new(void);
19 void TS_VERIFY_CTX_init(TS_VERIFY_CTX *ctx);
20 void TS_VERIFY_CTX_free(TS_VERIFY_CTX *ctx);
21 void TS_VERIFY_CTX_cleanup(TS_VERIFY_CTX *ctx);
22 int TS_VERIFY_CTX_set_flags(TS_VERIFY_CTX *ctx, int f);
23 int TS_VERIFY_CTX_add_flags(TS_VERIFY_CTX *ctx, int f);
24 int TS_VERIFY_CTX_set0_data(TS_VERIFY_CTX *ctx, BIO *b);
25 int TS_VERIFY_CTX_set0_imprint(TS_VERIFY_CTX *ctx,
26                                unsigned char *hexstr, long len);
27 int TS_VERIFY_CTX_set0_store(TS_VERIFY_CTX *ctx, X509_STORE *s);
28 int TS_VERIFY_CTX_set0_certs(TS_VERIFY_CTX *ctx, STACK_OF(X509) *certs);
29
30The following functions have been deprecated since OpenSSL 3.4:
31
32 BIO *TS_VERIFY_CTX_set_data(TS_VERIFY_CTX *ctx, BIO *b);
33 unsigned char *TS_VERIFY_CTX_set_imprint(TS_VERIFY_CTX *ctx,
34                                          unsigned char *hexstr, long len);
35 X509_STORE *TS_VERIFY_CTX_set_store(TS_VERIFY_CTX *ctx, X509_STORE *s);
36 STACK_OF(X509) *TS_VERIFY_CTX_set_certs(TS_VERIFY_CTX *ctx,
37                                         STACK_OF(X509) *certs);
38
39The following function has been deprecated since OpenSSL 3.0:
40
41 STACK_OF(X509) *TS_VERIFY_CTS_set_certs(TS_VERIFY_CTX *ctx,
42                                         STACK_OF(X509) *certs);
43
44=head1 DESCRIPTION
45
46The Time-Stamp Protocol (TSP) is defined by RFC 3161. TSP is a protocol used to
47provide long-term proof of the existence of certain data before a particular
48time. TSP defines a Time Stamping Authority (TSA) and an entity that makes
49requests to the TSA. Usually, the TSA is referred to as the server side, and the
50requesting entity is referred to as the client.
51
52In TSP, when a server sends a response to a client, the server normally
53needs to sign the response data - the TimeStampToken (TST) - with its private
54key. Then the client verifies the received TST using the server's certificate
55chain.
56
57For all the following methods, unless noted otherwise, I<ctx> is the
58verification context created in advance.
59
60TS_VERIFY_CTX_new() returns an allocated B<TS_VERIFY_CTX> structure.
61
62TS_VERIFY_CTX_init() initializes a verification context.
63
64TS_VERIFY_CTX_free() frees up a B<TS_VERIFY_CTX> object. I<ctx> is the
65verification context to be freed. If I<ctx> is NULL, the call is ignored.
66
67TS_VERIFY_CTX_set_flags() sets the flags in the verification context. I<f> are
68the flags to be set.
69
70TS_VERIFY_CTX_add_flags() adds flags to the verification context. I<f> are the
71flags to be added (OR'd).
72
73TS_VERIFY_CTX_set0_data() sets the data to be verified. I<b> is the B<BIO> with
74the data. A previously assigned B<BIO> is freed.
75
76TS_VERIFY_CTX_set0_imprint() sets the message imprint. I<hexstr> is the
77message imprint to be assigned. A previously assigned imprint is freed.
78
79TS_VERIFY_CTX_set0_store() sets the store for the verification context. I<s> is
80the store to be assigned. A previously assigned store is freed.
81
82TS_VERIFY_CTX_set0_certs() is used to set the server's certificate chain when
83verifying a TST. I<certs> is a stack of B<X509> certificates.
84
85TS_VERIFY_CTX_cleanup() frees all data associated with the given
86B<TS_VERIFY_CTX> object and initializes it. I<ctx> is the verification context
87created in advance. If I<ctx> is NULL, the call is ignored.
88
89All of the following functions described are deprecated. Applications should
90instead use the functions L<TS_VERIFY_CTX_set0_data(3)>,
91L<TS_VERIFY_CTX_set0_imprint(3)>, L<TS_VERIFY_CTX_set0_store(3)>,
92L<TS_VERIFY_CTX_set0_certs(3)>.
93
94TS_VERIFY_CTX_set_data() is used to set the BIO with the data to be verified.
95A previously assigned BIO is B<not freed> by this call. I<b> is the B<BIO>
96with the data to assign.
97
98TS_VERIFY_CTX_set_imprint() is used to set the message imprint. A previously
99assigned imprint B<is freed> by this call. I<hexstr> is the string with the
100message imprint to assign.
101
102TS_VERIFY_CTX_set_store() is used to set the certificate store. A previously
103assigned store is B<not freed> by this call. I<s> is the store to assign.
104
105TS_VERIFY_CTX_set_certs() is used to set the server's certificate chain.
106A previously assigned stack is B<not freed> by this call. I<certs> is a stack
107of B<X509> certificates.
108
109TS_VERIFY_CTS_set_certs() is a misspelled version of TS_VERIFY_CTX_set_certs()
110which takes the same parameters and returns the same result.
111
112=head1 RETURN VALUES
113
114TS_VERIFY_CTX_new() returns an allocated B<TS_VERIFY_CTX> structure.
115
116TS_VERIFY_CTX_set_flags() returns the flags passed via parameter I<f>.
117
118TS_VERIFY_CTX_add_flags() returns the flags of the context after the ones
119passed via parameter I<f> are added to it.
120
121TS_VERIFY_CTX_set0_data(), TS_VERIFY_CTX_set0_imprint(),
122TS_VERIFY_CTX_set0_store(), and TS_VERIFY_CTX_set0_certs() return 1 if the
123value could be successfully set and 0 in case of any error.
124
125The deprecated functions TS_VERIFY_CTX_set_data(), TS_VERIFY_CTX_set_imprint(),
126TS_VERIFY_CTX_set_store(), TS_VERIFY_CTX_set_certs() return the parameter
127the user passes via parameter I<bio>, I<hexstr>, I<s> or I<certs>.
128
129=head1 SEE ALSO
130
131L<OSSL_ESS_check_signing_certs(3)>
132
133=head1 HISTORY
134
135TS_VERIFY_CTX_set0_data(), TS_VERIFY_CTX_set0_imprint(),
136TS_VERIFY_CTX_set0_store(), TS_VERIFY_CTX_set0_certs() replace the functions
137TS_VERIFY_CTX_set_data(), TS_VERIFY_CTX_set_imprint(),
138TS_VERIFY_CTX_set_store(), TS_VERIFY_CTX_set_certs() that were deprecated
139in OpenSSL 3.4.0.
140
141The spelling of TS_VERIFY_CTX_set_certs() was corrected in OpenSSL 3.0.0.
142The misspelled version TS_VERIFY_CTS_set_certs() has been retained for
143compatibility reasons, but it is deprecated in OpenSSL 3.0.0.
144
145=head1 COPYRIGHT
146
147Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved.
148
149Licensed under the Apache License 2.0 (the "License"). You may not use
150this file except in compliance with the License. You can obtain a copy
151in the file LICENSE in the source distribution or at
152L<https://www.openssl.org/source/license.html>.
153
154=cut
155