Discuss this help topic in SecureBlackbox Forum
Create and send the timestamp request
To create a timstamping request, you need to use TElFileTSPClient or TElHTTPTSPClient component (they are descendants of TElCustomTSPClient, which defines most properties and methods). Do not use TElCustomTSPClient directly, use one of its descendants instead.
Create an instance of the TSPClient class of your choice. TElFileTSPClient creates a request and lets you transfer the request and the reply to/from the TSP server. TElHTTPTSPClient automatically transfers the request and the reply to/from the server using HTTP or HTTPS protocol.
TSP protocol signs not the data itself, but the hashes, calculated using some hash (digest) algorithm. So the next step is to set the hash algorithm using HashAlgorithm property of TElCustomTSPClient class. The algorithm, required by the standard for now is SHA1 and the value for this property is by default set to SB_ALGORITHM_DGST_SHA1. Other algorithms, such as SHA-2 (SB_ALGORITHM_DGST_SHA256, SB_ALGORITHM_DGST_SHA512 constants) can be used, if you know that they are supported by the server.
When using a different algorithm to timestamp the high-level data (e.g. during PAdES signing), you need to properly setup the corresponding high-level component to make it use the same algorithm that you have specified for timestamping.
Optionally you can specify in the request, whether the reply should include the certificates, used to sign the TSP response. This is done using IncludeCertificates property of TElCustomTSPClient class.
To prevent so-called "replay attacks" you can specify a so-called Nonce. Nonce is an arbitrary data, whose sole purpose is to add a random part to the data being signed. Nonce is specified by Nonce property of TElTSPInfo class. The instance of the class is contained in TSPInfo property of TElCustomTSPClient class.
If you use TElFileTSPClient , be sure to define an event handler for OnTimestampNeeded event of TElFileTSPClient class. The event will be used to pass the request to the application and pick the reply.
If you use TElHTTPTSPClient, you need to set the HTTPClient property of TElHTTPTSPClient class to the instance of TElHTTPSClient component. Note, that TElHTTPTSPClient is provided together with TElHTTPSClient in SSLBlackbox package (i.e. not in PKIBlackbox, as TElCustomTSPClient one). Also, you need to specify the address of the TSP server in URL property of TElHTTPTSPClient class.
The final step is to create a request. Call Timestamp() method, which creates a request, transfers it to the server, retrieves the reply then processes the reply and returns the result. In this method you need to pass the data hash, which is signed. The hash is passed in HashedData parameter. The size of the data, passed in HashedData parameter, must be equal to the product of the HashAlgorithm. For SHA1 this is 20 bytes.
With TElFileTSPClient you get the request, which you need to send to the server, in RequestStream parameter of OnTimestampNeeded event hander. TElHTTPTSPClient sends the request automatically.
See more about how to handle the reply, in the corresponding how-to article.
TSP protocol is described in RFC 3161.
