How to replace the self-signed SSL certificate in EcoStruxure IT Gateway versions 1.16 and newer

[EcoStruxureIT]

Contact support for information about Gateway versions older than 1.16.

Note: An imported SSL certificate signed by a trusted certificate authority or a CA certificate imported to the keystore will not persist through an EcoStruxure IT Gateway update.

You must import the certificate again after you update your Gateway software.

Windows

These command examples are formatted for use in the Windows command prompt.
Using PowerShell requires using single quotes instead of the double quotes displayed below.

EcoStruxure IT Gateway stores the user interface SSL certificates in two Java keystore files in the C:\Program Files\EcoStruxureITGateway\<current Gateway install version>\gateway\conf\keystore\ directory:

dcos.keystore (PrivateKeyEntry)

dcos.truststore (trustedCertEntry)

Verify the contents of the Java keystores

1. Open C:\Program Files\EcoStruxureITGateway\<current Gateway install version>\gateway\conf\application-installer.yaml 

2. In the server: > ssl: section, find the line key-store-password and remember the password for the keystores.

3. Open a command prompt window and change the directory to C:\Program Files\EcoStruxureITGateway\<current Gateway install version>\gateway\conf\keystore

4. Type the command 
   "C:\Program Files\EcoStruxureITGateway\<current Gateway install version>\jre\bin\keytool.exe” -list -v -keystore dcos.keystore

5. Enter the password you remembered in step 2.

6. Verify the keystore contents are displayed without error.

7. Type the command 
   "C:\Program Files\EcoStruxureITGateway\<current Gateway install version>\jre\bin\keytool.exe" -list -v -keystore dcos.truststore

8. Enter the password you remember from step 2 when prompted.

9. Verify the keystore contents are displayed without error. 

Create a new keystore for the trusted SSL certificate

1. Stop the EcoStruxureITGateway-x.x.x.x service.

2. Delete the existing keystore file, C:\Program Files\EcoStruxureITGateway\<current Gateway install version>\gateway\conf\keystore\dcos.keystore.

3. Open a command prompt and change the directory to C:\Program Files\EcoStruxureITGateway\<current Gateway install version>\gateway\conf\keystore

4. Type the command
   "C:\Program Files\EcoStruxureITGateway\<current Gateway install version>\jre\bin\keytool.exe" -genkey -alias dcos -keyalg RSA -keystore dcos.keystore -keysize 2048

5. The other values might need to match the values present on the CA. Some values are required by the CA, and others might be optional. This depends on the CA configuration.

6. Use the .csr file to create a new certificate signed by the Trusted CA. This could be a CA run by your company, or it might need to be sent to a third-party Certificate Authority.

7. Use the same password you remembered in step 2 of the ‘Verify the contents of the Java keystores” section.

8. Verify that the file dcos.keystore now exists in the keystore folder.

9. Start the EcoStruxureITGateway-x.x.x.x service. 

Create a certificate signing request and a new SSL certificate signed by a trusted CA

1. Type the command:  
   "C:\Program Files\EcoStruxureITGateway\<current Gateway install version>\jre\bin\keytool.exe" -certreq -alias dcos -keystore dcos.keystore -file newSxOnGW.csr

2. Enter the required values when prompted. The first value must match the hostname or FQDN (Fully Qualified Domain Name) of the server where EcoStruxure IT Gateway is installed.

Import the Root CA and Web Server SSL certificates to the EcoStruxure IT Gateway keystore

1. Copy rootca.crt and newSxOnGW.crt to the machine where EcoStruxure IT Gateway is installed.

2. Stop the EcoStruxureITGateway-x.x.x.x service.

3. Open a command prompt and change the directory to C:\Program Files\EcoStruxureITGateway\<current Gateway install version>\gateway\conf\keystore

4. Import the root CA certificate. Type the command  
   “C:\Program Files\EcoStruxureITGateway\<current Gateway install version>\jre\bin\keytool.exe" -importCert -trustcacerts -alias root -file rootca.crt -keystore root.truststore

5. Import the Web Server SSL certificate. Type the command
   "C:\Program Files\EcoStruxureITGateway\<current Gateway install version>\jre\bin\keytool.exe" -importCert -trustcacerts -alias dcos -file newSxOnGW.crt -keystore dcos.keystore

6. Make sure the root CA certificate is imported to the internet browser on all the computers that will be used to access the Gateway user interface.

7. Start the EcoStruxureITGateway-x.x.x.x service.

EcoStruxure IT Gateway will now use the new signed certificate, and no SSL Certificate security warning will be displayed by the browser when the Gateway user interface is launched.

C:\Program Files\EcoStruxureITGateway\<version>\gateway\conf\keystore\dcos.keystore (PrivateKeyEntry)

C:\Program Files\EcoStruxureITGateway\<version>\gateway\conf\keystore\dcos.truststore (trustedCertEntry)

Linux

EcoStruxure IT Gateway stores the user interface SSL certificates in two Java keystore files in the /opt/EcoStruxureITGateway/<current Gateway install version>/gateway/conf/keystore directory:

dcos.keystore (PrivateKeyEntry)

dcos.truststore (trustedCertEntry)

Verify the contents of the Java keystores

1. Open /opt/EcoStruxureITGateway</current Gateway install version>/gateway/conf/application-installer.yaml 

2. In the server: > ssl: section, find the line key-store-password and remember the password for the keystores.

3. Open a command prompt window and change the directory to /opt/EcoStruxureITGateway/<current Gateway install version>/gateway/conf/keystore

4. Type the command 
   '/opt/EcoStruxureITGateway/<current Gateway install version>/jre/bin/keytool.exe' -list -v -keystore dcos.keystore

5. Enter the password you remembered in step 2.

6. Verify the keystore contents are displayed without error.

7. Type the command 
   'opt/EcoStruxureITGateway/<current Gateway install version>/jre/bin/keytool' -list -v -keystore dcos.truststore

8. Enter the password you remember from step 2 when prompted.

9. Verify the keystore contents are displayed without error. 

Create a new keystore for the trusted SSL certificate

1. Stop the EcoStruxureITGateway-x.x.x.x service.

2. Delete the existing keystore file, /opt/EcoStruxureITGateway/<current Gateway install version>/gateway/conf/keystore/dcos.keystore.

3. Open a command prompt and change the directory to /opt/EcoStruxureITGateway/<current Gateway install version>/gateway/conf/keystore

4. Type the command
   '/opt/EcoStruxureITGateway/<current Gateway install version>/jre/bin/keytool' -genkey -alias dcos -keyalg RSA -keystore dcos.keystore -keysize 2048

5. The other values might need to match the values present on the CA. Some values are required by the CA, and others might be optional. This depends on the CA configuration.

6. Use the .csr file to create a new certificate signed by the Trusted CA. This could be a CA run by your company, or it might need to be sent to a third-party Certificate Authority.

7. Use the same password you remembered in step 2 of the ‘Verify the contents of the Java keystores” section.

8. Verify that the file dcos.keystore now exists in the keystore folder.

9. Start the EcoStruxureITGateway-x.x.x.x service. 

Create a certificate signing request and a new SSL certificate signed by a trusted CA

1. Type the command:  
   '/opt/EcoStruxureITGateway/<current Gateway install version>/jre/bin/keytool' -certreq -alias dcos -keystore dcos.keystore -file newSxOnGW.csr

2. Enter the required values when prompted. The first value must match the hostname or FQDN (Fully Qualified Domain Name) of the server where EcoStruxure IT Gateway is installed.

Import the Root CA and Web Server SSL certificates to the EcoStruxure IT Gateway keystore

1. Copy rootca.crt and newSxOnGW.crt to the machine where EcoStruxure IT Gateway is installed.

2. Stop the EcoStruxureITGateway-x.x.x.x service.

3. Open a command prompt and change the directory to /opt/EcoStruxureITGateway/<current Gateway install version>/gateway/conf/keystore

4. Import the root CA certificate. Type the command  
   '/opt/EcoStruxureITGateway/<current Gateway install version>/jre/bin/keytool' -importCert -trustcacerts -alias root -file rootca.crt -keystore root.truststore

5. Import the Web Server SSL certificate. Type the command
   '/opt/EcoStruxureITGateway/<current Gateway install version>/jre/bin/keytool' -importCert -trustcacerts -alias dcos -file newSxOnGW.crt -keystore dcos.keystore

6. Make sure the root CA certificate is imported to the internet browser on all the computers that will be used to access the Gateway user interface.

7. Start the EcoStruxureITGateway-x.x.x.x service.

EcoStruxure IT Gateway will now use the new signed certificate, and no SSL Certificate security warning will be displayed by the browser when the Gateway user interface is launched.

/opt/EcoStruxureITGateway/<version>/gateway/conf/keystore/dcos.keystore (PrivateKeyEntry)

/opt/EcoStruxureITGateway/<version>\gateway/conf/keystore/dcos.truststore (trustedCertEntry)

[JMollica]

Hello,

I would recommend under the Create a new keystore for the trusted SSL certificate for Step 4 to add argument '-validity 365' or any number, to set the number of days the certificate will be valid for, otherwise the default will be 3 months' time.

ex: 
'/opt/EcoStruxureITGateway/<current Gateway install version>/jre/bin/keytool' -genkey -alias dcos -keyalg RSA -keystore dcos.keystore -keysize 2048 -validity 365

[HWeser]

Hello,

I'm struggeliung now with this instruction to setup a EcoStruxure IT Gateway for almost a week. But got is solved. Could you please review on the points below and advise?

1. The instruction always is refering to 2 keystore files (the "dcos.keystore" and "dcos.truststore"). No explaination why the RootCA should be loaded into a file "root.truststore". If you follow this instruction, the dialog ask you to create a container password. To allow the application to access the container, its password and filename need to get added to the "application-installer.yaml" file, same as the entries for the other 2 containers.
2. The instruction does not advise how to install intermediate certificates if your CA requires to do so. If you skip this step, you cant add the server certificate itself getting an error in "keytool error: java.lang.Exception: Failed to establish chain from reply".

My findings in short:

1. verify Java keystore content
2. stop Gateway service
3. stop Gateway database service
4. delete the dcos.keystore AND the dcos.truststore
5. generate a new dcos.keystore and provide the requested information as necessary. The values entered will be issued for the CSR with next step:
   1. CN - FQDN of the server
   2. OU - e.g. company name
   3. O - e.g. department name
   4. S - state
   5. C - country
   6. confirm the summary with "yes" or "no" to walk thru steps again.
6. Create CSR file and handover to your CA.
7. Your CA may provide you ideally with indidividual CRT files. If you receive PEM - that file can be opened with a plain texteditor and each section starting with "----BEGIN CERTIFICATE----" and ending with "----END CERTIFICATE----" can be saved in separate files. Usually the first section is the server cert, the second section an Intermediate and the last section the root certificate. Then rename files extension into CRT and check the content.
8. Upload the certificates provided by your CA to server.
9. Load the RootCA.CRT to your dcos.truststore and use alias "root". Because you deleted the dcos.truststore in step 3 you will be prompted to set a password. Check the password value in file "application-installer.yaml" and use same there.
10. If your CA requires an intermediate certificate to install, load the Intermediate.CRT to your dcos.truststore and use alias "intermediate". If your CA didn't provide, goto next step.
11. Load the Server.CRT into your dcos.keystore and use alias "dcos". (Here I couldn't get further with the following error message:

keytool error: java.lang.Exception: Failed to establish chain from reply

Solution to establish the chain:

1. Load the provided RootCA.crt into the "dcos.keystore" and use alias "root".
2. Load the provided Intermediate.crt into the "dcos.keystore" and use alias "intermediate".
3. Load the provided Server.crt into the "dcos.keystore" and use alias "dcos". You shouldn't get an error anymore.
4. Verify the content of "dcos.keystore". There should be now 3 entries separated with double lines of stars "*********" :
   1. PrivateKeyEntry with key and 3 certificates ending section with separators ********
   2. TrustedCertEntry "root" ending section with separators *********
   3. TrustedCertEntry "intermediate" ending section with separators *********
5. Now you need to remove the TrustedCertEntries 2+3 from keystore by using command "keytool.exe -delete -alias root -keystore dcos.keystore" and "keytool.exe -delete -alias intermediate -keystore dcos.keystore".
   (Note: This step was required otherwise the webserver is still seen with a certificate not verified issuer.)
6. One more time verify the content of "dcos.keystore". There should now only 1 PrivateKeyEntry with Key and 3 subrecords with certificates.
7. start Gateway database service
8. start Gateway service

Many thanks and happy about a response