5 1 0:How to Replace the REST Server HTTPS Certificate and Private Key

Other languages:

Deutsch
English

Welcome to the latest SEP sesam documentation version 5.1.0 Apollon. For previous documentation version(s), check documentation archive.

Overview

Additional resources

Visit SEP sesam YouTube Channel for latest videos and webinars.

Check FAQ to find the answers to most common questions.

Problems? See the Troubleshooting Guide.

If you are using an older SEP sesam version, refer to Documentation archive.

By default, SEP sesam uses a self-signed SSL certificate and private key for its REST Server and Web UI access. It is created in the system's temporary folder when the REST Server is started, unless you have configured another HTTPS certificate to be used by REST services.

You can improve security of the REST Server for use with HTTPS by adding your company official certificate or another trusted certificate signed by a certification authority (CA). To change the SSL certificate used by SEP sesam REST services to access Web UI, you will need to use an administrator command line.

How certificate checks work

When the REST server starts, it performs the following certificate checks to find custom HTTPS certificates:

If a certificate and the corresponding private key are specified via the command-line options ([-z|--sslCertificate] <absolute file name certificate>, [-k|--sslPrivateKey] <absolute file name private key>), the REST Server attempts to use the specified files first.
Then it will look in the default location <SESAM_VAR>/ini/ssl (see Directory Layout for details) through a list of default file names: [sesam.https.crt and sesam.https.key].
If a variable gv_ro_ssl exists in the SEP sesam Server configuration file <SESAM_VAR>/ini/sm.ini (section PATHES), this location is probed next using the default file names.
If a certificate and the corresponding private key are specified via the global environment variables (SESAM_SSL_CERT=<absolute file name certificate>, SESAM_SSL_KEY=<absolute file name private key>), the REST Server attempts to use the specified files.

If none of the attempts to find a certificate are successful, the HTTPS server is set up using a self-signed certificate when the REST Server is started.

Prerequisites

To install the custom HTTPS certificate, you need to have Administrator rights to the SEP sesam Server machine and be able to write to the <SESAM_VAR>/ini/ssl directory.
The private key must be in PKCS8 format. If you have a key in another format, you need to convert it (using openssl) to PKCS8 before it can be used.

Generating a self-signed HTTPS certificate

The following procedure describes the steps to create a self-signed HTTPS certificate for SEP sesam. This certificate can be used to secure the REST Server, for encrypted communication between the server and clients.

Generate the self-signed certificate using the following command (replace the placeholder values with your specific information):

openssl req -x509 -newkey rsa:4096 -keyout sesam.https.key -out sesam.https.crt -sha256 -days 365 -nodes -subj "/C=<2LetterCountryCode>/ST=<StateName>/L=<CityName>/O=<CompanyName>/OU=<CompanySectionName>/CN=<CommonNameOrHostname>"

`-newkey rsa:4096`	specifies the generation of a new RSA key with a 4096-bit length
`-keyout sesam.https.key`	sets the output file for the private key
`-out sesam.https.crt`	sets the output file for the certificate
`-sha256`	uses the SHA-256 hash algorithm for the certificate
`-days 365`	specifies the validity period of the certificate in days (adjust as needed)
`-nodes`	indicates that the private key should not be encrypted with a passphrase
`-subj`	defines the subject for the certificate with the following fields that provide information about the entity for which the certificate is being issued. Fields are separated by forward slashes (/). Required field is the Common Name (CN), the other fields are optional and can be omitted: `C (Country)`: The two-letter country code where the entity is located or registered. For example, "DE" or "US". `ST (State)`: The full name of the state or province where the entity is located. `L (Locality)`: The locality or city where the entity is located. `O (Organization)`: The legal name of the organization or company. `OU (Organizational Unit)`: An optional field specifying the department or unit within the organization. `CN (Common Name or Hostname)`: The fully qualified domain name (FQDN) or the hostname for which the certificate is being issued. If you're creating a self-signed certificate for use within a local network, you can specify the hostname of your server.

Create a Certificate Signing Request (CSR) using the following command:
```
openssl x509 -x509toreq -in sesam.https.crt -signkey sesam.https.key -out sesam.https.csr
```
This command takes the self-signed certificate (sesam.https.crt) and the private key (sesam.https.key) to generate a CSR (sesam.https.csr).

You can use the CSR to obtain a certificate from a Certificate Authority (CA).

Replacing the HTTPS certificate and private key on REST server

Log in as root (Linux) or Administrator (Windows) to the SEP sesam Server console and enter the following command to stop the REST Server:

sm_main stop rmi

Navigate to <SESAM_VAR>/ini/ssl.
Save the custom HTTPS certificate file as sesam.https.crt.
Save the custom HTTPS certificate private key file as sesam.https.key.
Start the REST Server:

sm_main start rmi

When restarting the REST server, monitor the sm_gui_server.log to make sure that everything works as expected. Look for a log message similar to this line:

<date> <time> INFO  <context> - Setting up HTTPS certificate from certificate file <SESAM_VAR>/ini/ssl/sesam.https.crt' (via default location lookup)

Once you have confirmed that the certificate setup has been logged, start the web browser and open the SEP sesam Web UI using the server name from the certificate:

https://<server name>:11401/