Skip to content

Commit

Permalink
Update the README after the migration to Quarkus
Browse files Browse the repository at this point in the history
  • Loading branch information
@dnl50
dnl50 committed Jul 15, 2023
1 parent 16b0966 commit cb7a904
Show file tree
Hide file tree
Showing 3 changed files with 45 additions and 66 deletions.
102 changes: 40 additions & 62 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,68 +1,59 @@
# Time Stamp Authority

**TODO: document changes after Quarkus migration**

This is a Java implementation of a Time Stamp Authority using the Time-Stamp Protocol (_TSP_) as defined
in [RFC 3161](https://tools.ietf.org/html/rfc3161) and
[RFC 5816](https://tools.ietf.org/html/rfc5816). It uses Bouncy Castle and Quarkus under the hood.
in [RFC 3161](https://tools.ietf.org/html/rfc3161) and [RFC 5816](https://tools.ietf.org/html/rfc5816).
It uses [Bouncy Castle](https://www.bouncycastle.org/java.html) and [Quarkus](https://quarkus.io) 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](https://hub.docker.com/r/dnl50/tsa-server).

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.

## Features

### Time Stamping

The main purpose of this application is to sign TSP requests using
the [HTTP Protocol](https://datatracker.ietf.org/doc/html/rfc3161.html#section-3.4). The application therefore offers an
HTTP endpoint at the root path which accepts `POST` requests with the content type `application/timestamp-query`. The
HTTP endpoint under `/tsa/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 application provides a server-side rendered web interface implemented with [Thymeleaf](https://www.thymeleaf.org/).
It is fully self-contained, so all resources (CSS, JavaScript etc.) are provided by the application. HTTP `GET` requests
sent to the root path are automatically redirected to the history page.

#### History

A sortable overview table of all issued Time Stamp Protocol responses utilizing pagination:
⚠️ The Web UI ist yet to be reimplemented after the migration to Quarkus ⚠️

![Overview Page](https://raw.githubusercontent.com/dnl50/tsa-server/develop/docs/images/overview-page.png "Overview Page")
### REST API

#### Time Stamp Response Analysis

You can enter a Base64 encoded ASN.1 DER response of an RFC 3161 / RFC 5816 Time Stamp Protocol Response to see what was
signed and who signed it:

![Validation Page](https://raw.githubusercontent.com/dnl50/tsa-server/develop/docs/images/validation-page.png "Validation Page")

You can also download the signing certificate in case it is included in the response.
The available REST Endpoints are documented in a OpenAPI specification which can be explored using a Swagger UI which is
available under `/q/swagger-ui`.

## Configuration

All Parameters mentioned below can be configured in variety of ways. Please refer to the
[Spring Boot Documentation](https://docs.spring.io/spring-boot/docs/3.0.2/reference/html/features.html#features.external-config)
for more information.

### Time Stamp Protocol
All Parameters mentioned below can be configured in variety of ways. Please refer to
the [Quarkus Documentation](https://quarkus.io/guides/config-reference#configuration-sources) for more information.

| Parameter Name | Mandatory | Default Value | Description |
|--------------------------------|-----------|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `tsa.ess-cert-id-algorithm` | No | SHA256 | The hash algorithm which is used to calculate the TSA's certificate identifier (ESSCertIDv2). |
| `tsa.signing-digest-algorithm` | No | SHA256 | The hash algorithm which is used to calculate the TSP requests digest, which will be signed by the TSA. |
| `tsa.accepted-hash-algorithms` | No | SHA1, SHA256, SHA512 | Comma-separated list of hash algorithms which are accepted by the Time Stamp Authority. |
| `tsa.policy-oid` | No | 1.2 | The OID of the policy under which the TSP responses are produced. |
| `tsa.certificate.path` | Yes | | The URL to load the PKCS#12 archive containing the certificate and private key used to sign TSP requests. Prefixing the path with `classpath:` will result in the PKCS#12 archive from being loaded from the classpath. |
| `tsa.certificate.password` | No | | The password of the PKCS#12 archive. |
| `tsa.server.port` | No | 318 | The TCP port under which Time Stamp Protocol Query Requests will be answered. |
| Parameter Name | Mandatory | Default Value | Description |
|--------------------------------|-----------|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `tsa.ess-cert-id-algorithm` | No | SHA256 | The hash algorithm which is used to calculate the TSA's certificate identifier (ESSCertIDv2). |
| `tsa.signing-digest-algorithm` | No | SHA256 | The hash algorithm which is used to calculate the TSP requests digest, which will be signed by the TSA. |
| `tsa.accepted-hash-algorithms` | No | SHA1, SHA256, SHA512 | Comma-separated list of hash algorithms which are accepted by the Time Stamp Authority. |
| `tsa.policy-oid` | No | 1.2 | The OID of the policy under which the TSP responses are produced. |
| `tsa.keystore.path` | Yes | | The URL to load the PKCS#12 archive containing the certificate and private key used to sign TSP requests. Prefixing the path with `classpath:` will result in the PKCS#12 archive from being loaded from the classpath (not supported in native image). |
| `tsa.keystore.password` | No | | The password of the PKCS#12 archive. |

### Web
### Logging

| Parameter Name | Mandatory | Default Value | Description |
|---------------------------------|-----------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| `server.port` | No | 8080 | The TCP port under which HTTP(S) frontend requests will be answered. |
| `tsa.http.port` | No | 80 | The TCP port for which requests will be redirected to HTTPS. Only active when the HTTPS is activated by setting the `server.ssl.key-store` parameter. |
| `server.ssl.key-store` | No | | The absolut path of the keystore containing the TLS certificate to use for HTTPS. Accepts Java Key Stores (`jks`) and PKCS#12 (`p12`) files. |
| `server.ssl.key-store-password` | No | | The password of the aforementioned keystore. |
| `server.ssl.key-store-type` | No | | The type of the keystore to use (`jks` or `pkcs12`). |
By default, all log messages will be printed to STDOUT. Please refer to
the [Quarkus Documentation](https://quarkus.io/guides/logging) for further information on how to configure the log
output.

## Issuing a signing certificate

Expand All @@ -77,34 +68,21 @@ extension when creating a self-signed certificate:
openssl x509 ... -addext extendedKeyUsage=critical,timeStamping
```

## Running in Docker

Docker images are automatically published to [Docker Hub](https://hub.docker.com/r/dnl50/tsa-server). The Embedded
Database writes its data to the `/application/db` directory. Mounting a filesystem directory or a named volume under
that path will make the DB data persistent.

## Configure Logging

By default, all log messages will be printed to STDOUT. If you want to configure the logging library used ([Logback](https://logback.qos.ch/)), please refer to the relevant section in the [Spring Boot Documentation](https://docs.spring.io/spring-boot/docs/3.0.2/reference/html/features.html#features.logging)

## Development

### Running in development mode

In normal operation, no signing certificate is configured since you probably want to use your own/your organizations
certificate and not a self-signed certificate 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 can be enabled by
activating the `dev` Spring profile (e.g. by setting the `spring.profiles.active` JVM System Property to `dev`). In
addition, this also has the following effects:
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
* enables the H2 Database Console which can be accessed
under [localhost:8080/h2-console](http://localhost:8080/h2-console)
* uses a self-singed RSA certificate for signing TSP requests
* uses a self-singed 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
unter `/eclipse-formatter.xml`. A custom import order configuration file os located under `/spotless.importorder`. The
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](https://github.com/diffplug/spotless). Just execute
the `spotlessApply` Gradle Task and you are good to go!
2 changes: 1 addition & 1 deletion app/build.gradle.kts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98,5 +98,5 @@ quarkus {
// creates a h2 db in server mode (using the H2DevServicesProcessor) which runs on the host machine and sets the JDBC URL
// to something like "jdbc:h2:tcp://localhost:53233/mem:test" which obviously does not work inside the docker container
tasks.quarkusIntTest.configure {
systemProperty("quarkus.datasource.jdbc.url", "jdbc:h2:file:/work/data")
systemProperty("quarkus.datasource.jdbc.url", "jdbc:h2:file:/work/data/tsa")
}
7 changes: 4 additions & 3 deletions app/src/main/resources/application.properties
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
# DB Configuration
quarkus.flyway.migrate-at-start=true
quarkus.hibernate-orm.physical-naming-strategy=org.hibernate.boot.model.naming.CamelCaseToUnderscoresNamingStrategy
%prod.quarkus.datasource.jdbc.url=jdbc:h2:file:/work/data
%prod.quarkus.datasource.jdbc.url=jdbc:h2:file:/work/data/tsa
# OpenAPI Configuration
quarkus.swagger-ui.always-include=true
quarkus.swagger-ui.show-common-extensions=true
mp.openapi.extensions.smallrye.operationIdStrategy=METHOD
# Dev Profile
%dev.tsa.keystore.path=classpath:keystore/ec.p12
# TSA Configuration
%dev.tsa.keystore.path=classpath:keystore/ec.p12
%prod.tsa.keystore.path=/work/keystore.p12

0 comments on commit cb7a904

Please sign in to comment.