This module implements a Time Stamp Protocol endpoint that supports assertions of proof that a datum existed before a particular time.

Based on configuration, an incoming POST request with a content type of application/timestamp-query is received, the datum is signed, and the response is returned as application/timestamp-reply.

This hook generates the serial number to be included in the timestamp response. The hook is mandatory, and the request will be rejected if left unconfigured.

This hooks returns the time to be used when generating the timestamp. The hook is mandatory, and the request will be rejected if left unconfigured.

The simplest case: generate a timestamp for anybody who wants one.

                  
LoadModule ca_module /usr/local/libexec/apache-modules/mod_ca.so
LoadModule ca_simple_module /usr/local/libexec/apache-modules/mod_ca_simple.so
LoadModule timestamp_module /usr/local/libexec/apache-modules/mod_timestamp.so

# backend configuration:
<IfModule mod_ca_simple.c>
  # use system clock as the time source
  CASimpleTime on
  # assign a random serial number
  CASimpleSerialRandom on
</IfModule>

# frontend configuration:
<IfModule mod_timestamp.c>
  <Location /timestamp>
    SetHandler timestamp
    # sign with this certificate...
    TimestampSigningCertificate /etc/pki/ssl/timestamp.cert
    # ...and private key
    TimestampSigningKey /etc/pki/ssl/timestamp.key
    # use a sha256 digest
    TimestampDigest SHA256
    # set the policy to an oid of your choice
    TimestampDefaultPolicy 1.2.3.4

    # Allow anyone to get a signed timestamp
    require all granted
  </Location>
</IfModule>

                

Note that it is essential that the timestamp sever certifcate (as set with TimestampSigningCertificate) has the key usage extensions cirtical and timeStamping

These can be set by openssl (e.g. when testing) with:

# Generate an unencrypted keypair and a request.
#
openssl req -newkey rsa:1024 -nodes \
   -subj   "/C=NL/ST=Zuid-Holland/L=Leiden/O=TimeServices/CN=Churchtower" \
   -keyout /etc/pki/ssl/timestamp.key \
   -out    /tmp/timestamp.csr 

# Create a config file:
#
echo extendedKeyUsage=critical,timeStamping > ts.cnf

# And (self sign) the request; with the required timestamp
# key usage
#
openssl x509 -req -days 365 \
    -in      /tmp/timestamp.csr \
    -signkey /etc/pki/ssl/timestamp.key \
    -out     /etc/pki/ssl/timestamp.cert.pem -extfile ts.cnf

# And delete the request - it is no longer needed.
rm /tmp/timestmap.csr

A more typical scenario: generate a timestamp for a logged in user.

In this example it is assumed that Apache configuration exists that authenticates a user against a database, directory, a token, or a previous certificate.

                  
# backend configuration:
<IfModule mod_ca_simple.c>
  # use system clock as the time source
  CASimpleTime on
  # assign a random serial number
  CASimpleSerialRandom on
</IfModule>

# frontend configuration:
<IfModule mod_timestamp.c>
  <Location /timestamp>
    SetHandler timestamp
    # standard Apache authorisation
    Require valid-user
    # sign with this certificate...
    TimestampSigningCertificate /etc/pki/ssl/timestamp.cert
    # ...and private key
    TimestampSigningKey /etc/pki/ssl/timestamp.key
    # use a sha256 digest
    TimestampDigest SHA256
    # set the policy to an oid of your choice
    TimestampDefaultPolicy 1.2.3.4
  </Location>
</IfModule>

                

Client implementations for RFC3160 can be found for most languages; and some applications have these build in (in that case -the URI to enter for the above examples would be https://fqdn.com/timestamp.

It is also possible to use OpenSSL its build in ts utility; an example is show below; where a file caled my-novel.doc is timestamped (any binary file will do).

1. First create a signing request for the file. What actually gets signed is the SHA256 (specified by the -cert flag).

   
   openssl ts -query -data my-novel.doc -cert -sha256 -no_nonce -out request.tsq
   

2. Then offer this to the signing server (assumed here to run localhost); as an HTTP POST request with the right content type. The reply is signed receipt (in binary, DER, format).

   
   curl -H Content-type:application/timestamp-query --data-binary @request.tsq http://127.0.0.1/timestamp > reply.tsq
   

3. You can now dump the content of this reply;

   
   openssl ts -reply -text -in reply.tsq
   openssl asn1parse -inform DER -in reply.tsq
   

   or, better, verify it against the timestamp certificate (or, with the chain, against any of the higher CA certificates as the root):

   
   openssl ts -verify -in reqply.tsq  -data my-novel.doc -CAfile /etc/pki/ssl/timestamp.cert
   

   Note: As we dit not set a 'nonce' in step 1 - we did not get one back (which you can use to verify against the one in the request). And in this particular case - we get a random `serial' number set by the time server (As we set CASimpleSerialRandom to on in the servr configuration).

   In this case - we simply use the certificate set in the configuration file of the signing timeserver (by TimestampSigningCertificate) to verify. So we have no chain issues.

After calling the make serial hook, and the get time hook, return the time stamped response.

SetHandler timestamp

Set to the name of the signing certificate.

Set to the name of the signing key.

Set to the name of a file containing the rest of the certificate chain.

Set to the maximum size of the timestamp request from the client. This value cannot be smaller than 4096 bytes.

Set the URL location of the WADL returned by the OPTIONS method.

Add the given policy to the timestamp.

Set the given policy as the default timestamp policy.

Add the given digest to the timestamp.

Indicate whether the certificate chain should be included in the ESS signing certificate attribute within the response.

Set ordering to true in the response.

Set to include the TSA name in the response.

Set the number of clock precision digits.