Source:How to Replace the REST Server HTTPS Certificate and Private Key: Difference between revisions

Revision as of 10:51, 27 May 2020

Other languages:

Deutsch
English

Any form of reproduction of the contents or parts of this manual is allowed only with the express written permission from SEP AG. When compiling and designing user documentation SEP AG uses great diligence and attempts to deliver accurate and correct information. However, SEP AG cannot issue a guarantee for the contents of this manual.

	WORK IN PROGRESS
	This article is in the initial stage and may be updated, replaced or deleted at any time. It is inappropriate to use this document as reference material as it is a work in progress and should be treated as such.

Welcome to the latest SEP sesam documentation version 4.4.3 Beefalo/4.4.3 Beefalo V2. For previous documentation version(s), check documentation archive.

Overview

Additional resources

Check FAQ to find the answers to the most common questions.

Problems? See the Troubleshooting Guide.

Watch SEP sesam installation videos & screencasts.

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 variable gv_ro_ssl_https exists in the <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.

Prerequisite

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.

Steps

Log in as root (Linux) or Administrator (Windows) to the SEP sesam Server console and enter the following command to stop the REST Server:
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:
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:

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/
Verify that the web browser is trusting the HTTPS certificate.

@@ Line 13: / Line 13: @@
 | style="padding:0px 40px 0px 10px; color: grey; font-size: 90%; text-align:left;" |
 <translate>
-See also: [[Special:MyLanguage/Configuring_SSL_Secured_Communication_for_SEP_sesam_Backup_Network|Configuring SSL Secured Communication for SEP sesam Backup Network]] – [[Special:MyLanguage/About_Authentication_and_Authorization|About Authentication and Authorization]] – [[Special:MyLanguage/SEP_sesam_Web_UI|SEP sesam Web UI]]</translate>
+See also: [[Special:MyLanguage/Configuring_SSL_Secured_Communication_for_SEP_sesam_Backup_Network|Configuring SSL Secured Communication for SEP sesam Backup Network]] – [[Special:MyLanguage/SEP_sesam_Web_UI|SEP sesam Web UI]]</translate>
 |}
@@ Line 35: / Line 35: @@
 | style="padding:0px 40px 0px 10px; color: grey; font-size: 90%; text-align:left;" | <translate><!--T:8-->
 Watch SEP sesam [[Special:MyLanguage/Video Tutorials & Screencasts#installation|installation videos & screencasts]].</translate>
-|}
 |}</div>
 <translate>
@@ Line 52: / Line 52: @@
 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===
+===Prerequisite===
+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 {{path|<SESAM_VAR>/ini/ssl}} directory.
-You must have SEP sesam administrator privileges to run SEP sesam CLI commands and use the command prompt as an administrator. All commands are run from the {{Sesamroot|/bin/sesam/}} directory. If you want to execute SEP sesam commands globally (and not from the actual ''run directory''), set the SEP sesam profile as described in [[Special:MyLanguage/FAQ#profile_setting|What happens when I set a profile?]].
 ==Steps==
 </translate>
-<ol><li><translate>Log in to the SEP sesam Server console and enter the following command to stop the REST Server:</translate></li>
+<ol><li><translate>Log in as ''root'' (Linux) or ''Administrator'' (Windows) to the SEP sesam Server console and enter the following command to stop the REST Server:</translate></li>
   sm_main stop rmi
-<li><translate>The certificate and the private key file must be provided as two separate files and placed into a directory that is accessible by the REST server. The REST server must have read access to those files. </translate></li>
+<li><translate>Navigate to {{path|<SESAM_VAR>/ini/ssl}}.</translate></li>
-<li><translate>Type the following command to install the certificate file:</translate></li>
+<li><translate>Save the custom HTTPS certificate file as <tt>sesam.https.crt</tt>.</translate></li>
+<li><translate>Save the custom HTTPS certificate private key file as <tt>sesam.https.key</tt>.</translate></li>
   - sm_java server --sslCertificate <absolute file name of certificate> --sslPrivateKey <absolute file name of private key>
-<li><translate>Restart the REST Server:</translate></li>
-<li><translate>Type the following command to install the certificate file:</translate></li>
- - sm_java server --sslCertificate <absolute file name of certificate> --sslPrivateKey <absolute file name of private key>
-<li><translate>Restart the REST Server:</translate></li>
- sm_main start rmi
-</ol>
-<translate>
-<span style="color:red">Damit sollte man a) sehen was der Server tut und b) ob es jetzt mal funktioniert. -> I need more information on what what the server does and how to check whether it works? Maybe: Verify that the REST server is able to handle a HTTPS request.</span>
-Proceed as follows to make sure that the system environment variables are correctly set when the REST server starts as a (Windows) service:
-</translate>
-<ol><li><translate>Stop the REST Server again:</translate></li>
- sm_main stop rmi
-<li><translate>Configure the REST server to use your certificate and private key pair files by specifying the following environment variables:</translate></li>
- SESAM_SSL_CERT = <absolute file name of certificate>
- SESAM_SSL_KEY = <absolute file name of private key>
 <li><translate>Start the REST Server:</translate></li>
   sm_main start rmi
+<li><translate>When restarting the REST server, monitor the <tt>sm_gui_server.log</tt> to make sure that everything works as expected. Look for a log message similar to this line:</translate></li>
+ <date> <time> INFO  <context> - Setting up HTTPS certificate from certificate file <SESAM_VAR>/ini/ssl/sesam.https.crt' (via default location lookup)
+<li><translate>Once you have confirmed that the certificate setup has been logged, start the web browser and open the [[Special:MyLanguage/SEP_sesam_Web_UI|SEP sesam Web UI]] using the server name from the certificate:</translate></li>
+'''https://<server name>:11401/''' <br />
+Verify that the web browser is trusting the HTTPS certificate.
 </ol>
-<translate>
-{{tip|You can enable authentication to make sure that you are providing access to your SEP sesam environment to the right recipients and not to the unknown users. For details, see [[Special:MyLanguage/About_Authentication_and_Authorization|About Authentication and Authorization]].}}
-</translate>
 <translate><div class="noprint">
 == See also == <!--T:95-->
-[[Special:MyLanguage/Configuring_SSL_Secured_Communication_for_SEP_sesam_Backup_Network|Configuring SSL Secured Communication for SEP sesam Backup Network]] – [[Special:MyLanguage/About_Authentication_and_Authorization|About Authentication and Authorization]] – [[Special:MyLanguage/SEP_sesam_Web_UI|SEP sesam Web UI]]</div></translate>
+[[Special:MyLanguage/Configuring_SSL_Secured_Communication_for_SEP_sesam_Backup_Network|Configuring SSL Secured Communication for SEP sesam Backup Network]] – [[Special:MyLanguage/SEP_sesam_Web_UI|SEP sesam Web UI]]</div></translate>