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