Configure TLS

To protect communication with the Transaction Security Broker (TSB) in transit, it is highly recommended to configure TLS.

To configure TLS, set up a key for the server to use in the TLS handshake.

Prerequisites

This example uses openssl to create a key and a certificate, but you can use other tools, too.

To start, enter the TSB configuration directory, for example cd ~/securosys_tsb-configuration-v2.3.1/.

Step 1: Create Key Pair and Certificate

Create the TLS directory. Then generate a key pair and a self-signed certificate using OpenSSL:

cd config-files && mkdir -p tls && cd tls || exit 1
openssl req -new -x509 -nodes -sha256 -newkey rsa:4096 -days 3650 -subj '/CN=localhost' -keyout webserver_tls.key -out webserver_tls.crt

info

Alternatively, you can generate a .key and obtain the .crt from a certificate authority such as Let's Encrypt. Using a (public) certificate authority is recommended for production deployments.

Step 2: Import Key and Certificate into Key Store

Next, take your .key and .crt files and bundle them into a PKCS#12 archive:

openssl pkcs12 -export -in webserver_tls.crt -inkey webserver_tls.key -out securosys-ska-server.p12

Step 3: Configure the application

1. Copy the securosys-ska-server.p12 file into the config-files/tls directory.

2. Modify the application config (config-files/application-local.yml) to enable TLS:

nano ../application-local.yml

## HTTPS CONFIGURATION
tls:
  # set to true if you want to use TLS (https)
  enabled: true
  keyStore: 'file:/etc/app/config/tls/securosys-ska-server.p12'
  keyStorePassword: secret  

Step 4: Restart the application

Stop the application:

docker compose down

Restart the application:

docker compose up -d

Inspect the logs:

docker logs securosys_tsb -f

You should see in the TSB logs that the server started with http(s). The relevant lines are:

Tomcat initialized with port(s): 8080 (https)
Connector [https-jsse-nio-8080], TLS virtual host [_default_], certificate type [UNDEFINED] configured from keystore [/root/.keystore] using alias [tomcat] with trust store [null]
Tomcat started on port(s): 8080 (https) with context path ''

Full example:

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::                (v3.1.6)

2024.01.03 10:13:28.700 INFO [  restartedMain] [ com.securosys.ska.Application]Starting Application using Java 17.0.2 with PID 1 (/opt/app started by root in /)
2024.01.03 10:13:28.706 INFO [  restartedMain] [ com.securosys.ska.Application]No active profile set, falling back to 1 default profile: "default"
2024.01.03 10:13:28.905 INFO [  restartedMain] [sPropertyDefaultsPostProcessor]For additional web related logging consider setting the 'logging.level.web' property to 'DEBUG'
2024.01.03 10:13:31.887 INFO [  restartedMain] [epositoryConfigurationDelegate]Bootstrapping Spring Data JPA repositories in DEFAULT mode.
2024.01.03 10:13:32.096 INFO [  restartedMain] [epositoryConfigurationDelegate]Finished Spring Data repository scanning in 196 ms. Found 10 JPA repository interfaces.
2024.01.03 10:13:36.722 INFO [  restartedMain] [mbedded.tomcat.TomcatWebServer]Tomcat initialized with port(s): 8080 (https)
2024.01.03 10:13:36.805 INFO [  restartedMain] [oyote.http11.Http11NioProtocol]Initializing ProtocolHandler ["https-jsse-nio-8080"]
2024.01.03 10:13:36.819 INFO [  restartedMain] [.catalina.core.StandardService]Starting service [Tomcat]
...
2024.01.03 10:13:53.391 INFO [  restartedMain] [oyote.http11.Http11NioProtocol]Starting ProtocolHandler ["https-jsse-nio-8080"]
2024.01.03 10:13:54.082 INFO [  restartedMain] [il.net.NioEndpoint.certificate]Connector [https-jsse-nio-8080], TLS virtual host [_default_], certificate type [UNDEFINED] configured from keystore [/root/.keystore] using alias [tomcat] with trust store [null]
2024.01.03 10:13:54.099 INFO [  restartedMain] [mbedded.tomcat.TomcatWebServer]Tomcat started on port(s): 8080 (https) with context path ''
2024.01.03 10:13:54.179 INFO [  restartedMain] [ com.securosys.ska.Application]Started Application in 27.365 seconds (process running for 29.127)
2024.01.03 10:13:54.183 INFO [  restartedMain] [.business.BootstrappingProcess]Executing application bootstrapping
...

Test with cURL

IMPORTANT

Never use --insecure in production. Use --cacert webserver_tls.crt or install a trusted Root CA.

curl --insecure https://localhost:8080/v1/licenseInfo

Response:

{"clientFlags":["IMPORT","EXPORT","EXTRACT","KEY_AUTH","REST_API","TSB_ENGINE","EXTERNAL_STORAGE","DESTROY_OBJECTS","EXPORT_LOGS","EXTENDED_KEY_ATTRIBUTES","BTC","ETH","RIPPLE","IOTA","ROOT_KEY_STORE","TIMESTAMP_SERVICE","USEABLE_OBJECTS","CARDANO","PERSISTENT_EXTERNAL_OBJ","KYBER","DILITHIUM","SPHINCSPLUS","LMS","XMSS"]}

Listing Keys

curl -v --insecure https://localhost:8080/v1/key

Response:

['attestation-key', 'timestamp-key']

What's next?

• Setup API Authentication
• Configure Database TLS
• Follow the instructions to Create a Key and use it to encrypt and decrypt a payload