mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-04-06 20:20:50 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add and Update Documentation for TS_VERIFY_CTX Functions

Browse Source 
Mark the existing `TS_VERIFY_CTX_set_certs` function as deprecated in the
documentation.
Add missing documentation for the deprecated functions `TS_VERIFY_CTX_set_data`,
`TS_VERIFY_CTX_set_imprint`, and `TS_VERIFY_CTX_set_store`.
Write missing documentation for the following functions:
- `TS_VERIFY_CTX_new`
- `TS_VERIFY_CTX_init`
- `TS_VERIFY_CTX_free`
- `TS_VERIFY_CTX_cleanup`
- `TS_VERIFY_CTX_set_flags`
- `TS_VERIFY_CTX_add_flags`
- `TS_VERIFY_CTX_set0_data`
- `TS_VERIFY_CTX_set0_imprint`
- `TS_VERIFY_CTX_set0_store`
- `TS_VERIFY_CTX_set0_certs`

Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/24701)
This commit is contained in:
erbsland-dev 2024-06-21 15:21:04 +02:00 committed by Tomas Mraz
parent 6f811d839f
commit 2c1ef172f8
5 changed files with 169 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
doc/build.info
View File

@ -2803,10 +2803,10 @@ DEPEND[html/man3/TS_RESP_CTX_new.html]=man3/TS_RESP_CTX_new.pod
GENERATE[html/man3/TS_RESP_CTX_new.html]=man3/TS_RESP_CTX_new.pod
DEPEND[man/man3/TS_RESP_CTX_new.3]=man3/TS_RESP_CTX_new.pod
GENERATE[man/man3/TS_RESP_CTX_new.3]=man3/TS_RESP_CTX_new.pod
DEPEND[html/man3/TS_VERIFY_CTX_set_certs.html]=man3/TS_VERIFY_CTX_set_certs.pod
GENERATE[html/man3/TS_VERIFY_CTX_set_certs.html]=man3/TS_VERIFY_CTX_set_certs.pod
DEPEND[man/man3/TS_VERIFY_CTX_set_certs.3]=man3/TS_VERIFY_CTX_set_certs.pod
GENERATE[man/man3/TS_VERIFY_CTX_set_certs.3]=man3/TS_VERIFY_CTX_set_certs.pod
DEPEND[html/man3/TS_VERIFY_CTX.html]=man3/TS_VERIFY_CTX.pod
GENERATE[html/man3/TS_VERIFY_CTX.html]=man3/TS_VERIFY_CTX.pod
DEPEND[man/man3/TS_VERIFY_CTX.3]=man3/TS_VERIFY_CTX.pod
GENERATE[man/man3/TS_VERIFY_CTX.3]=man3/TS_VERIFY_CTX.pod
DEPEND[html/man3/UI_STRING.html]=man3/UI_STRING.pod
GENERATE[html/man3/UI_STRING.html]=man3/UI_STRING.pod
DEPEND[man/man3/UI_STRING.3]=man3/UI_STRING.pod
@ -3684,7 +3684,7 @@ html/man3/SSL_stream_reset.html \
html/man3/SSL_want.html \
html/man3/SSL_write.html \
html/man3/TS_RESP_CTX_new.html \
html/man3/TS_VERIFY_CTX_set_certs.html \
html/man3/TS_VERIFY_CTX.html \
html/man3/UI_STRING.html \
html/man3/UI_UTIL_read_pw.html \
html/man3/UI_create_method.html \
@ -4342,7 +4342,7 @@ man/man3/SSL_stream_reset.3 \
man/man3/SSL_want.3 \
man/man3/SSL_write.3 \
man/man3/TS_RESP_CTX_new.3 \
man/man3/TS_VERIFY_CTX_set_certs.3 \
man/man3/TS_VERIFY_CTX.3 \
man/man3/UI_STRING.3 \
man/man3/UI_UTIL_read_pw.3 \
man/man3/UI_create_method.3 \

154
doc/man3/TS_VERIFY_CTX.pod Normal file
View File

@ -0,0 +1,154 @@
=pod
=head1 NAME
TS_VERIFY_CTX, TS_VERIFY_CTX_new, TS_VERIFY_CTX_init, TS_VERIFY_CTX_free,
TS_VERIFY_CTX_cleanup, TS_VERIFY_CTX_set_flags, TS_VERIFY_CTX_add_flags,
TS_VERIFY_CTX_set0_data, TS_VERIFY_CTX_set0_imprint, TS_VERIFY_CTX_set0_store,
TS_VERIFY_CTX_set0_certs, TS_VERIFY_CTX_set_certs, TS_VERIFY_CTS_set_certs,
TS_VERIFY_CTX_set_data, TS_VERIFY_CTX_set_imprint, TS_VERIFY_CTX_set_store
- manage the TS response verification context
=head1 SYNOPSIS
#include <openssl/ts.h>
typedef struct TS_verify_ctx TS_VERIFY_CTX;
TS_VERIFY_CTX *TS_VERIFY_CTX_new(void);
void TS_VERIFY_CTX_init(TS_VERIFY_CTX *ctx);
void TS_VERIFY_CTX_free(TS_VERIFY_CTX *ctx);
void TS_VERIFY_CTX_cleanup(TS_VERIFY_CTX *ctx);
int TS_VERIFY_CTX_set_flags(TS_VERIFY_CTX *ctx, int f);
int TS_VERIFY_CTX_add_flags(TS_VERIFY_CTX *ctx, int f);
int TS_VERIFY_CTX_set0_data(TS_VERIFY_CTX *ctx, BIO *b);
int TS_VERIFY_CTX_set0_imprint(TS_VERIFY_CTX *ctx,
unsigned char *hexstr, long len);
int TS_VERIFY_CTX_set0_store(TS_VERIFY_CTX *ctx, X509_STORE *s);
int TS_VERIFY_CTX_set0_certs(TS_VERIFY_CTX *ctx, STACK_OF(X509) *certs);
The following functions have been deprecated since OpenSSL 3.4:
BIO *TS_VERIFY_CTX_set_data(TS_VERIFY_CTX *ctx, BIO *b);
unsigned char *TS_VERIFY_CTX_set_imprint(TS_VERIFY_CTX *ctx,
unsigned char *hexstr, long len);
X509_STORE *TS_VERIFY_CTX_set_store(TS_VERIFY_CTX *ctx, X509_STORE *s);
STACK_OF(X509) *TS_VERIFY_CTX_set_certs(TS_VERIFY_CTX *ctx,
STACK_OF(X509) *certs);
The following function has been deprecated since OpenSSL 3.0:
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 certain data before a particular
time. TSP defines a Time Stamping Authority (TSA) and an entity that makes
requests to the TSA. Usually, the TSA is referred to as the server side, and the
requesting entity is referred to as the client.
In TSP, when a server sends a response to a client, the server normally
needs to sign the response data - the TimeStampToken (TST) - with its private
key. Then the client verifies the received TST using the server's certificate
chain.
For all the following methods, unless noted otherwise, I<ctx> is the
verification context created in advance.
TS_VERIFY_CTX_new() returns an allocated B<TS_VERIFY_CTX> structure.
TS_VERIFY_CTX_init() initializes a verification context.
TS_VERIFY_CTX_free() frees up a B<TS_VERIFY_CTX> object. I<ctx> is the
verification context to be freed. If I<ctx> is NULL, the call is ignored.
TS_VERIFY_CTX_set_flags() sets the flags in the verification context. I<f> are
the flags to be set.
TS_VERIFY_CTX_add_flags() adds flags to the verification context. I<f> are the
flags to be added (OR'd).
TS_VERIFY_CTX_set0_data() sets the data to be verified. I<b> is the B<BIO> with
the data. A previously assigned B<BIO> is freed.
TS_VERIFY_CTX_set0_imprint() sets the message imprint. I<hexstr> is the
message imprint to be assigned. A previously assigned imprint is freed.
TS_VERIFY_CTX_set0_store() sets the store for the verification context. I<s> is
the store to be assigned. A previously assigned store is freed.
TS_VERIFY_CTX_set0_certs() is used to set the server's certificate chain when
verifying a TST. I<certs> is a stack of B<X509> certificates.
TS_VERIFY_CTX_cleanup() frees all data associated with the given
B<TS_VERIFY_CTX> object and initializes it. I<ctx> is the verification context
created in advance. If I<ctx> is NULL, the call is ignored.
All of the following functions described are deprecated. Applications should
instead use the functions L<TS_VERIFY_CTX_set0_data(3)>,
L<TS_VERIFY_CTX_set0_imprint(3)>, L<TS_VERIFY_CTX_set0_store(3)>,
L<TS_VERIFY_CTX_set0_certs(3)>.
TS_VERIFY_CTX_set_data() is used to set the BIO with the data to be verified.
A previously assigned BIO is B<not freed> by this call. I<b> is the B<BIO>
with the data to assign.
TS_VERIFY_CTX_set_imprint() is used to set the message imprint. A previously
assigned imprint B<is freed> by this call. I<hexstr> is the string with the
message imprint to assign.
TS_VERIFY_CTX_set_store() is used to set the certificate store. A previously
assigned store is B<not freed> by this call. I<s> is the store to assign.
TS_VERIFY_CTX_set_certs() is used to set the server's certificate chain.
A previously assigned stack is B<not freed> by this call. I<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_new() returns an allocated B<TS_VERIFY_CTX> structure.
TS_VERIFY_CTX_set_flags() returns the flags passed via parameter I<f>.
TS_VERIFY_CTX_add_flags() returns the flags of the context after the ones
passed via parameter I<f> are added to it.
TS_VERIFY_CTX_set0_data(), TS_VERIFY_CTX_set0_imprint(),
TS_VERIFY_CTX_set0_store(), and TS_VERIFY_CTX_set0_certs() return 1 if the
value could be successfully set and 0 in case of any error.
The deprecated functions TS_VERIFY_CTX_set_data(), TS_VERIFY_CTX_set_imprint(),
TS_VERIFY_CTX_set_store(), TS_VERIFY_CTX_set_certs() return the parameter
the user passes via parameter I<bio>, I<hexstr>, I<s> or I<certs>.
=head1 SEE ALSO
L<OSSL_ESS_check_signing_certs(3)>
=head1 HISTORY
TS_VERIFY_CTX_set0_data(), TS_VERIFY_CTX_set0_imprint(),
TS_VERIFY_CTX_set0_store(), TS_VERIFY_CTX_set0_certs() replace the functions
TS_VERIFY_CTX_set_data(), TS_VERIFY_CTX_set_imprint(),
TS_VERIFY_CTX_set_store(), TS_VERIFY_CTX_set_certs() that were deprecated
in OpenSSL 3.4.0.
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-2024 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

61
doc/man3/TS_VERIFY_CTX_set_certs.pod
View File

@ -1,61 +0,0 @@
=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 SEE ALSO
L<OSSL_ESS_check_signing_certs(3)>
=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-2021 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

12
util/libcrypto.num
View File

@ -153,7 +153,7 @@ BN_is_prime_fasttest_ex 155 3_0_0 EXIST::FUNCTION:DEPRECATEDIN_3
ERR_load_PKCS12_strings 156 3_0_0 EXIST::FUNCTION:DEPRECATEDIN_3_0
EVP_sha384 157 3_0_0 EXIST::FUNCTION:
i2d_DHparams 158 3_0_0 EXIST::FUNCTION:DEPRECATEDIN_3_0,DH
TS_VERIFY_CTX_set_store 159 3_0_0 EXIST::FUNCTION:TS
TS_VERIFY_CTX_set_store 159 3_0_0 EXIST::FUNCTION:DEPRECATEDIN_3_4,TS
PKCS12_verify_mac 160 3_0_0 EXIST::FUNCTION:
X509v3_addr_canonize 161 3_0_0 EXIST::FUNCTION:RFC3779
ASN1_item_ex_i2d 162 3_0_0 EXIST::FUNCTION:
@ -915,7 +915,7 @@ TS_TST_INFO_ext_free 938 3_0_0 EXIST::FUNCTION:TS
i2d_X509_CRL_fp 939 3_0_0 EXIST::FUNCTION:STDIO
PKCS7_get0_signers 940 3_0_0 EXIST::FUNCTION:
X509_STORE_CTX_set_ex_data 941 3_0_0 EXIST::FUNCTION:
TS_VERIFY_CTX_set_certs 942 3_0_0 EXIST::FUNCTION:TS
TS_VERIFY_CTX_set_certs 942 3_0_0 EXIST::FUNCTION:DEPRECATEDIN_3_4,TS
BN_MONT_CTX_copy 943 3_0_0 EXIST::FUNCTION:
OPENSSL_INIT_new 945 3_0_0 EXIST::FUNCTION:
TS_ACCURACY_dup 946 3_0_0 EXIST::FUNCTION:TS
@ -2421,7 +2421,7 @@ ASIdOrRange_free 2472 3_0_0 EXIST::FUNCTION:RFC3779
EC_POINT_get_Jprojective_coordinates_GFp 2473 3_0_0 EXIST::FUNCTION:DEPRECATEDIN_3_0,EC
EVP_aes_128_cbc_hmac_sha256 2474 3_0_0 EXIST::FUNCTION:
i2d_PKCS7_SIGNED 2475 3_0_0 EXIST::FUNCTION:
TS_VERIFY_CTX_set_data 2476 3_0_0 EXIST::FUNCTION:TS
TS_VERIFY_CTX_set_data 2476 3_0_0 EXIST::FUNCTION:DEPRECATEDIN_3_4,TS
BN_pseudo_rand_range 2477 3_0_0 EXIST::FUNCTION:DEPRECATEDIN_3_0
X509V3_EXT_add_nconf 2478 3_0_0 EXIST::FUNCTION:
EVP_CIPHER_CTX_ctrl 2479 3_0_0 EXIST::FUNCTION:
@ -2612,7 +2612,7 @@ RSA_public_encrypt 2670 3_0_0 EXIST::FUNCTION:DEPRECATEDIN_
X509_CRL_get0_extensions 2671 3_0_0 EXIST::FUNCTION:
CMS_digest_verify 2672 3_0_0 EXIST::FUNCTION:CMS
ASN1_GENERALIZEDTIME_set 2673 3_0_0 EXIST::FUNCTION:
TS_VERIFY_CTX_set_imprint 2674 3_0_0 EXIST::FUNCTION:TS
TS_VERIFY_CTX_set_imprint 2674 3_0_0 EXIST::FUNCTION:DEPRECATEDIN_3_4,TS
BN_RECP_CTX_set 2675 3_0_0 EXIST::FUNCTION:
CRYPTO_secure_zalloc 2676 3_0_0 EXIST::FUNCTION:
i2d_EXTENDED_KEY_USAGE 2677 3_0_0 EXIST::FUNCTION:
@ -5683,6 +5683,10 @@ OSSL_TARGETING_INFORMATION_free ? 3_4_0 EXIST::FUNCTION:
OSSL_TARGETING_INFORMATION_new ? 3_4_0 EXIST::FUNCTION:
OSSL_TARGETING_INFORMATION_it ? 3_4_0 EXIST::FUNCTION:
OSSL_GENERAL_NAMES_print ? 3_4_0 EXIST::FUNCTION:
TS_VERIFY_CTX_set0_data ? 3_4_0 EXIST::FUNCTION:TS
TS_VERIFY_CTX_set0_imprint ? 3_4_0 EXIST::FUNCTION:TS
TS_VERIFY_CTX_set0_store ? 3_4_0 EXIST::FUNCTION:TS
TS_VERIFY_CTX_set0_certs ? 3_4_0 EXIST::FUNCTION:TS
CRYPTO_atomic_add64 ? 3_4_0 EXIST::FUNCTION:
CRYPTO_atomic_and ? 3_4_0 EXIST::FUNCTION:
d2i_OSSL_ATTRIBUTES_SYNTAX ? 3_4_0 EXIST::FUNCTION:

1
util/other.syms
View File

@ -832,3 +832,4 @@ EVP_PKEY_size define
EVP_PKEY_id define
EVP_PKEY_base_id define
SSL_set_retry_verify define
TS_VERIFY_CTX define