Creating and installing a CA-signed server certificate for SSMC

SSMC ships with a self-signed certificate by default. HPE recommends you to install your own CA-signed certificate for the web server considering your enterprise security policy and practices. So, SSMC provides the necessary hooks and tools to generate and install a CA-signed certificate for the SSMC web server.

Prerequisites

Contact the CA signing authority for your enterprise. Explain that a CSR (Certificate Signing Request) in PKCS#10 (RFC 2986) format can be provided for SSMC, and one or more corresponding CA-signed certificates must be in PEM format that conforms to X.509 certificate standard. Consult them on what is required for the certificate fields, for example:
```
Common Name, “CN=”; 
Organization Unit, “OU=”; 
Organization, “O=”; 
Locality or city, “L=”; 
State, “ST=”; 
Country, “C=”. 
Certificate validity in days
```
Once you have received the CA signed certificates, download the root and intermediate PEM encoded CA-signed certificates from your corporate CA website.
Import the root and intermediate CA certificates into the client web browser.
If you are creating this keystore after you have enabled FIPS (not recommended), you must make additional modifications to the keystore. See Modifying keystore entries for FIPS.

WARNING:

Migrating from any prior SSMC versions using the HPE SSMC Migration Tool overwrites the CA-signed certificate that may be installed on the target appliance with the one from source. Hewlett Packard Enterprise recommends you to install the CA-signed certificate on the target appliance only after the migration is done. If your target appliance already has the CA-signed certificate installed, then you have to reinstall CA certificate post migration.

Procedure

Use any SSH client to log on to the SSMC virtual appliance as ssmcadmin. Enter "x" from TUI to exit to bash shell.
The keytool executable is located at path /opt/hpe/ssmc/ssmcbase/fips/jre/bin/. Add this to the PATH environment variable for ease of use.
export PATH=/opt/hpe/ssmc/ssmcbase/fips/jre/bin:$PATH

Back up the Jetty keystore by renaming it:

cd /opt/hpe/ssmc/ssmcbase/etc/ 
mv keystore keystore.orig

Generate the new public and private key-pair for SSMC in a new keystore.
1. Execute the following command specifying the certificate validity in days:
```
keytool –genkeypair –keystore keystore -storetype JKS –alias jetty –
keyalg RSA -validity <validity_days>
```
  NOTE:
  Certain browser versions (Google chrome version 58 and later) require Subject Alternative Name (SAN), which is an X.509 extension, be present in the server certificate.
  If you want to use a Subject Alternative Name (SAN) in your server certificate, add the following options to the keytool command line.
  If you are adding an alternative name, use –ext san=dns:servername.example.com.
  If you want to use an IP address, use –ext san=ip:192.168.10.1.
  For example, keytool -genkeypair –keystore keystore -storetype JKS -alias jetty -keyalg RSA -validity 365 -ext san=dns:servername.example.com
2. At the prompt, "Enter keystore password", enter the password to be used to access the keystore content. Remember this keystore password.
3. Complete the prompts for certificate fields needed by your Certification Authority, which you have collected earlier, such as CN, OU, O, L, ST, and C.
4. The next prompt will be to review the values of the field entered. If anything is incorrect, then respond with "no" or <enter> to repeat the field entries with needed corrections.
```
Is CN=…, OU=…, O=…, L=…, ST=…, C=… correct? 
[no]:  yes 
Generating 2,048 bit RSA key pair and self-signed certificate (SHA256withRSA) with a 
validity of <validity_days> days 
        for: CN=…, OU=…, O=…, L=…, ST=…, C=…
```
5. At the next prompt, specify the password for the key:
```
Enter key password for <jetty> 

       (RETURN if same as keystore password): 

[Storing keystore]
```
  Remember this as keymanager password, especially if it is not the same as the Keystore password.
  NOTE:
  It is safe to ignore the following warning message issued by keytool:
```
"The JKS keystore uses a proprietary format. It is recommended to migrate 
to PKCS12 which is an industry standard format using "keytool -importkeystore 
-srckeystore keystore -destkeystore keystore -deststoretype pkcs12".
```
Generate the CSR (Certificate Signing Request) for SSMC:
```
keytool –certreq –keystore keystore –alias jetty –file ~/SSMC_csr.txt
```
NOTE: If you have specified a SAN using -ext argument in step 4, then use the same while generating CSR in this step. For example:
keytool -certreq -keystore keystore -alias jetty -file ~/SSMC_csr.txt -ext san=dns:server.example.com

Display the CSR to verify content:

cat ~/SSMC_csr.txt

The content looks something like this (

PKCS#10, RFC
							2986

) with a PEM encoded ASCII text enclosed within

-----BEGIN NEW CERTIFICATE REQUEST----- and -----END NEW
							CERTIFICATE REQUEST-----

-----BEGIN NEW CERTIFICATE REQUEST----- 
MIIC+jCCAeICAQAwgYQxCzAJBgNVBAYTAlVTMREwDwYDVQQIEwhDb2xvcmFkbzEV 
MBMGA1UEBxMMRm9ydCBDb2xsaW5zMSMwIQYDVQQKExpIZXdsZXR0IFBhY2thcmQg 
RW50ZXJwcmlzZTEQMA4GA1UECxMHVW5rbm93bjEUMBIGA1UEAxMLZnNlcnQubG9j 
. 
. 
. 
jrpTDTeG9xDTjqEDX7IBIdcaksyjuXKEQVuCq/5vBXsQiTyZmMBVNyDqEc8hYHQq 
JszjVqyNmQ6TEg9TyT+Rvlw663Npfex87pY2AA0pIY2dS5TllyJeIjg/oMB2JrFw 
ILeYl7/SWC0VIZFo8WerlHb03ihzbQH8HIwSAV4k27uLA8hrkokH4xEyRrWYeg== 
-----END NEW CERTIFICATE REQUEST-----

Submit the CSR file ~/SSMC_csr.txt, or cut and paste all the text (including the BEGIN and END records) to your corporate CA for generation of the SSMC CA-signed certificate.
The certificates provided by the customer CA in response to this request must be of X.509 standard with PEM encoding. Certificates provided by the customer CA can be in same or separate files, and the expected certificates will be:
```
1 x CA-signed SSMC server certificate; 
1 x Customer CA root certificate; 
N x Customer CA specified intermediate certificate(s) [N>=0]
```
Do a preliminary examination of one or more certificate files received:
1. Each of these certificate entries must be a PEM encoded ASCII text enclosed within -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- conforming to X.509 standard.
  cat <certificate_file_name>
  The output looks something like this:
```
-----BEGIN CERTIFICATE----- 
MIIGoTCCBYmgAwIBAgIQL6hBGubWdXYmFXBoILHAaDANBgkqhkiG9w0BAQUFADCB 
njEPMA0GA1UEChMGaHAuY29tMRowGAYDVQQLExFJVCBJbmZyYXN0cnVjdHVyZTEL 
MAkGA1UEBhMCVVMxIDAeBgNVBAoTF0hld2xldHQtUGFja2FyZCBDb21wYW55MUAw 
. 
. 
. 
Dm6NmvrhHeR8NSbvpDmD/raoCyZZenD0JtiMnuYMF3Vd7DtwEjSZ27BvQbs8skp+ 
c6LVqo9nbzpnwrHFQIuk1W2saNxu 
-----END CERTIFICATE----- 
```
  NOTE:
  There may be repeating sections of the above in case the PEM certificate file received carries all the certificates in the chain of trust.
2. Execute this command to view the certificate content for each of the certificate file received:
  keytool -v -printcert -file <certificate_file_name>
3. Ensure that the issuer of each subject certificate also has a corresponding certificate and the whole chain can be traversed until the root certificate, which is self-signed (wherein the issuer and the subject are the same)
Create a backup copy of the keystore with CSR:
cp -p /opt/hpe/ssmc/ssmcbase/etc/keystore ~/keystore_4csr

Import the root CA certificate provided with alias specified as root:


keytool –import –alias root –keystore keystore –file <root_ca_cert_file_name> 
Enter keystore password: 
. 
. 
. 
Trust this certificate? [no]: yes 
Certificate was added to keystore

Import any intermediate CA certificates provided by the CA:
```
keytool -import -keystore keystore -file <intermediate_ca_cert_file_name>
```
Repeat this step until all intermediate certificates in the certificate chain are added to the keystore.

Add the CA-signed SSMC server certificate to the keystore using the jetty as the alias:

keytool -import -alias jetty -keystore keystore -file <ssmc_ca_server_cert_file_name>

Adjust the file permission and ownership to jetty keystore as follows:
```
chmod 640 ./keystore
chown ssmcadmin:hpe3parssmcuser ./keystore
```
Update the Jetty configuration with the new keystore and key passwords, so that Jetty can access the certificate in the keystore while binding to the secure server port.
1. Back up the current Jetty configuration file.
```
cp -p jetty-ssl-context.xml /home/ssmcadmin/backup/jetty-ssl-context.xml_orig
```
2. Optional: If your enterprise security policies prevent use of clear text passwords in configuration files, follow the procedure mentioned in the section Using obfuscated passwords in configuration files to generate obfuscated password for the keystore password (and keymanager password if it is different from keystore password).
3. Use vi to open and modify the Jetty configuration file.
```
vi jetty-ssl-context.xml
```
  Update the keystore password and keymanager password (with clear or obfuscated value, as required). The obfuscated password must retain the prefix "OBF:" .
```
<Set name="KeyStorePassword"><Property 
name="jetty.sslContext.keyStorePassword" 
deprecated="jetty.keystore.password" 
default="OBF:1v2j1uum1xtv1zej1zer1xtn1uvk1v1v"/></Set> 

<Set name="KeyStoreType"><Property 
name="jetty.sslContext.keyStoreType" 
default="JKS"/></Set> 

<Set name="KeyStoreProvider:><Property 
name="jetty.sslContext.keyStoreProvider"/></Set> 

<Set name="KeyManagerPassword"><Property 
name="jetty.sslContext.keyManagerPassword" 
deprecated="jetty.keymanagerpassword"
default="OBF:1v2j1uum1xtv1zej1zer1xtn1uvk1v1"/></Set>
```
Go back to the TUI by using the config_appliance command.
Restart the SSMC service, using menu option 2.
Import the CA root certificate that has signed the server certificate of SSMC into the trusted CA roots trust store of your browser, if not already done. For more information, see Importing root and intermediate CA certificates into the client web browser.
Using the Storage Administrator's browser, enter the SSMC's system FQDN in the URL: https://< SSMC_system_FQDN> :8443.
Examine the certificate from the browser. It must be the newly installed CA-signed server certificate for SSMC.