dnl50/tsa-server repository overview

⁠Time Stamp Authority

This is a Java implementation of a Time Stamp Authority using the Time-Stamp Protocol (TSP) as defined in RFC 3161⁠ and RFC 5816⁠. It uses Bouncy Castle⁠ and Quarkus⁠ under the hood.

The application utilizes GraalVM's Native Image technology, which leads to a very small memory footprint of about 10 MB and a near instant startup in about 50 milliseconds.

⁠Docker Images

Docker images are automatically published to Docker Hub⁠.

By default, the embedded H2 database writes its data to the /work/data/tsa.mv.db file. Mounting a directory or a named volume to the /work/data will make the DB data persistent.

The keystore containing the certificate and private key used to sign the requests with is loaded from /work/keystore.p12 by default.

There are two Docker Image variants: Native and JVM. Native Images (e.g. dnl50/tsa-server:3.1.0) are only available for x86-64. The JVM variant (e.g. dnl50/tsa-server:3.1.0-jvm) is available for x86-64 and arm64.

⁠Features

⁠Time Stamping

The main purpose of this application is to sign TSP requests using the HTTP Protocol⁠. The application therefore offers an HTTP endpoint under /sign which accepts POST requests with the content type application/timestamp-query. The ASN.1 DER-encoded Time-Stamp Request must be supplied in the request body.

⁠Web UI

⚠️ The Web UI ist yet to be reimplemented after the migration to Quarkus ⚠️

⁠REST API

The available REST Endpoints are documented in a OpenAPI specification which can be downloaded from /q/openapi. When the application is run in dev mode using the quarkusDev command you can also explore it using a Swagger UI which can be accessed under /q/swagger-ui.

⁠WebSocket Endpoint

The application exposes an WebSocket endpoint under /history/responses. The JSON representation of every TSP response will be broadcast there.

⁠Configuration

All Parameters mentioned below can be configured in variety of ways. Please refer to the Quarkus Documentation⁠ for more information.

⁠Logging

By default, all log messages will be printed to STDOUT. Please refer to the Quarkus Documentation⁠ for further information on how to configure the log output.

⁠Issuing a signing certificate

The signing certificate used by the Time Stamp Authority must be an RSA, DSA or EC certificate with an Extended Key Usage⁠ extension marked as critical. The only KeyPurposeId present in the sequence must be id-kp-timeStamping (OID 1.3.6.1.5.5.7.3.8).

The following parameter can be added to the OpenSSL x509 utility to add the required critical Extended Key Usage extension when creating a self-signed certificate:

openssl x509 ... -addext extendedKeyUsage=critical,timeStamping

⁠Development

⁠Running in development mode

In normal operation, no signing certificate is configured by default since you probably want to use your own/your organizations key pair and not a self-signed key pair I issued to use in integration tests. Configuring a file system path to a valid certificate for development is error-prone though. That's what the development mode is for. It is automatically enabled when running Quarkus using the quarkusDev Gradle Task. The dev mode has the following effects:

• application data is written into an in-memory Database which will be scrapped on application shutdown
• uses a self-signed EC certificate for signing TSP requests

⁠Using the code formatter

The source code is formatted using the Eclipse Code Formatter. The formatter config file is located under /eclipse-formatter.xml. A custom import order configuration file os located under /spotless.importorder. The code can also be formatted using the Spotless Gradle Plugin⁠. Just execute the spotlessApply Gradle Task and you are good to go!

⁠License

This project is licensed under the terms of the MIT license.