Add doc for TS_VERIFY_CTX_set_certs()

This addition is based on PR #9472.

Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/9838)

diff --git a/doc/man3/TS_VERIFY_CTX_set_certs.pod b/doc/man3/TS_VERIFY_CTX_set_certs.pod
new file mode 100644 (file)
index 0000000..a7aae4a
--- /dev/null
+++ b/doc/man3/TS_VERIFY_CTX_set_certs.pod
@@ -0,0 +1,57 @@
+=pod
+
+=head1 NAME
+
+TS_VERIFY_CTX_set_certs, TS_VERIFY_CTS_set_certs
+- set certificates for TS response verification
+
+=head1 SYNOPSIS
+
+ #include <openssl/ts.h>
+
+ STACK_OF(X509) *TS_VERIFY_CTX_set_certs(TS_VERIFY_CTX *ctx,
+                                         STACK_OF(X509) *certs);
+ STACK_OF(X509) *TS_VERIFY_CTS_set_certs(TS_VERIFY_CTX *ctx,
+                                         STACK_OF(X509) *certs);
+
+=head1 DESCRIPTION
+
+The Time-Stamp Protocol (TSP) is defined by RFC 3161. TSP is a protocol used to
+provide long term proof of the existence of a certain datum before a particular
+time. TSP defines a Time Stamping Authority (TSA) and an entity who shall make
+requests to the TSA. Usually the TSA is denoted as the server side and the
+requesting entity is denoted as the client.
+
+In TSP, when a server is sending a response to a client, the server normally
+needs to sign the response data - the TimeStampToken (TST) - with its private
+key. Then the client shall verify the received TST by the server's certificate
+chain.
+
+TS_VERIFY_CTX_set_certs() is used to set the server's certificate chain when
+verifying a TST. B<ctx> is the verification context created in advance and
+B<certs> is a stack of B<X509> certificates.
+
+TS_VERIFY_CTS_set_certs() is a misspelled version of TS_VERIFY_CTX_set_certs()
+which takes the same parameters and returns the same result.
+
+=head1 RETURN VALUES
+
+TS_VERIFY_CTX_set_certs() returns the stack of B<X509> certificates the user
+passes in via parameter B<certs>.
+
+=head1 HISTORY
+
+The spelling of TS_VERIFY_CTX_set_certs() was corrected in OpenSSL 3.0.0.
+The misspelled version TS_VERIFY_CTS_set_certs() has been retained for
+compatibility reasons, but it is deprecated in OpenSSL 3.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut

diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt
index cf6824d49e10444f710fcb0c5f29db9ece736d36..7f1cf49ab3cec2c558e0e56d1e95de2b624df714 100644 (file)
--- a/util/missingcrypto.txt
+++ b/util/missingcrypto.txt
@@ -1070,7 +1070,6 @@ TS_TST_INFO_set_serial(3)
 TS_TST_INFO_set_time(3)
 TS_TST_INFO_set_tsa(3)
 TS_TST_INFO_set_version(3)
-TS_VERIFY_CTX_set_certs(3)
 TS_VERIFY_CTX_add_flags(3)
 TS_VERIFY_CTX_cleanup(3)
 TS_VERIFY_CTX_free(3)

diff --git a/util/missingmacro.txt b/util/missingmacro.txt
index 3d825b199dc49780b067b82de71baee9dacbacdd..8738c87d9f3d521c457618cae739d99fbbcc94ea 100644 (file)
--- a/util/missingmacro.txt
+++ b/util/missingmacro.txt
@@ -175,4 +175,3 @@ X509V3_set_ctx_test(3)
 X509V3_set_ctx_nodb(3)
 EXT_BITSTRING(3)
 EXT_IA5STRING(3)
-TS_VERIFY_CTS_set_certs(3)

diff --git a/util/other.syms b/util/other.syms
index c6b2404f2c91667c46ced4a01f1daa98c6c5ceb0..b57af07c7d5a188754f709264feb1706736754c3 100644 (file)
--- a/util/other.syms
+++ b/util/other.syms
@@ -562,3 +562,4 @@ OSSL_TRACE_CANCEL                       define
 OSSL_TRACE1                             define
 OSSL_TRACE2                             define
 OSSL_TRACE9                             define
+TS_VERIFY_CTS_set_certs                 define deprecated 3.0.0