Add doc for TS_VERIFY_CTX_set_certs()
authorPaul Yang <kaishen.yy@antfin.com>
Tue, 10 Sep 2019 05:08:29 +0000 (13:08 +0800)
committerPaul Yang <kaishen.yy@antfin.com>
Thu, 16 Jan 2020 03:28:04 +0000 (11:28 +0800)
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)

doc/man3/TS_VERIFY_CTX_set_certs.pod [new file with mode: 0644]
util/missingcrypto.txt
util/missingmacro.txt
util/other.syms

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
@@ -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
index cf6824d..7f1cf49 100644 (file)
@@ -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)
index 3d825b1..8738c87 100644 (file)
@@ -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)
index c6b2404..b57af07 100644 (file)
@@ -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