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.

                  
  # use system clock as the time source
  CASimpleTime on
  # assign a random serial number
  CASimpleSerialRandom on


# frontend configuration:

  
    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
  

]]>
                

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:

 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.

                  
  # use system clock as the time source
  CASimpleTime on
  # assign a random serial number
  CASimpleSerialRandom on


# frontend configuration:

  
    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
  

]]>
                

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).

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).

    reply.tsq
   ]]>

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

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

   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.

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.