Skip to content
Swiss federal authorities

Network Services TLS-Certificates

Both the Web Service Proxy / sedex Messaging REST API and the Monitoring Service should be operated exclusively over the secure HTTPS protocol.
To enable HTTPS, each service must be configured with a valid TLS certificate that ensures the cryptographic protection of network communication.

The sedex-Client supports two types of TLS certificates:

  1. Self-signed certificate – automatically generated and managed by the sedex-Client (default).
  2. Custom TLS certificate – provided by the participant, either issued by an internal Certificate Authority (CA) or by an official public registrar.

Both approaches are described in detail in the following sections.

Note

The two HTTPS service endpoints offered by the sedex-Client — the Web Service Proxy and the Monitoring Service — are configured in the same way.
The only difference lies in the prefix of the configuration properties:
properties for the Web Service Proxy start with wsproxy.https., while properties for the Monitoring Service start with monitoring.https..

1. Using Self-Signed TLS Certificates (Automatically Generated by the sedex-Client)🔗

If no TLS certificate is found for a service during startup, the sedex-Client automatically generates and configures a self-signed TLS certificate for that service (unless this behavior has been explicitly disabled).

Characteristics of the Automatically Generated Certificate🔗

  • The self-signed certificate is not issued by a public or generally trusted Certificate Authority (CA).
    Consequently, it is not trusted by default and must be manually added to the trust store of any business application that connects to the sedex service.
  • The generated certificate is valid for five years.
    Its expiration date can be viewed on the sedex-Client’s Monitoring page.
  • The certificate’s subject includes all host names automatically detected by the sedex-Client at generation time.
  • The private key and certificate are stored in a PKCS#12 (P12) keystore file located under:
    <sedex_home>/conf/certificates
  • In addition, a CER file containing the public certificate is created.
    This file can be provided to business application developers or operators so they can import the certificate into their trust store.

Regenerating the Certificate🔗

To regenerate a self-signed certificate, clear the certificate path in the configuration — that is, remove the value following the equals sign — and then restart the sedex-Client.
A new certificate will then be generated automatically.

Service Configuration Property to be cleared
Web Service Proxy / sedex Messaging REST API wsproxy.https.key-store-file=
Monitoring Service monitoring.https.key-store-file=

Creating a Certificate with an Additional Host Name🔗

If you need a self-signed certificate that includes an additional host name, proceed as follows.
The example below uses the Web Service Proxy properties, but the same steps apply analogously to the Monitoring Service using the corresponding monitoring.https. property prefix.

  1. Add the parameter specifying the desired host name, for example:
    wsproxy.https.hostname=your-host-name
  2. Remove the value of the property
    wsproxy.https.key-store-file= (or monitoring.https.key-store-file=).
  3. Restart the sedex-Client.
    A new certificate will be generated automatically with the additional host name included.

2. Using a Custom TLS Certificate (Provided by the Operator)🔗

If a valid TLS certificate is already available, the sedex-Client can be configured to use it for its HTTPS endpoints instead of generating a self-signed one.

The certificate must be stored in one of the following key store formats:

  • PKCS#12 (.p12 file)
  • Java Key Store (.jks file)

Key Store Requirement

The provided key store must contain both the private key and the corresponding certificate under the same alias name.

Useful Tool

The freely available Java-based tool KeyStore Explorer allows convenient editing of key store files.
For example, it can be used to create a new key store from separate private key and certificate files, which can then be used by the sedex-Client.

Installation and Configuration Steps🔗

  1. Copy the key store file (e.g. my-tls-keystore.p12) into the certificate configuration directory of the sedex-Client:
    <sedex_home>/conf/certificates/my-tls-keystore.p12

  2. Configure the key store in the sedex-Client’s main configuration file.
    All property keys use the respective service prefix (wsproxy.https. or monitoring.https.):

    Property Key Installation-Type Description / Example
    Key Store File OS-based installation wsproxy.https.key-store-file=${sedex.home}/conf/certificates/my-tls-keystore.p12
    Note: The variable ${sedex.home} can be used to define a path relative to the sedex-Client home directory.
    Key Store Filename Docker-based installation wsproxy.https.key-store-filename=my-tls-keystore.p12
    Key Store Password Both wsproxy.https.key-store-password=myKeystorePassword
    Key Password (optional) Both wsproxy.https.key-password=myKeyPassword
    Only required if the key password differs from the keystore password.
    Key Alias (optional) Both wsproxy.https.key-alias=myAlias
    Only required if the keystore contains multiple key entries.

  3. Restart the sedex-Client and check the service log files for startup messages or potential TLS configuration errors.