SSMC certificates and X.509 two-factor authentication

There are two client certificates and two server certificates used in SSMC. These certificates are typically signed by the same set of CA root and intermediaries. The SSMC X.509 two-factor authentication solution uses several of these certificates for authentication purposes.
IMPORTANT:

For enabling two-factor authentication, Hewlett Packard Enterprise recommends you to disable FIPS on SSMC, if already enabled. You can re-enable FIPS mode after two-factor authentication is configured. Alternatively, ensure that appropriate modifications are made as outlined in Modifying keystore entries for FIPS.

  • Certificate A — Client certificate identifying the browser (user) to SSMC.

    This certificate identifies the user who will log in to SSMC. The specifics vary depending on the certificate use model (smart card, virtual smart card, software tokens). With CAC (Common Access Card), the certificate resides on a physical smart card. With Virtual Smart Card, the certificate has a private key stored in the physical TPM (Trusted Platform Module) chip on the client computer. With software tokens, the certificate resides entirely in the operating system or the browser.

    Installing trust for user certificate

    • Install trust for the user identity (client) certificate in SSMC web-server trust store at /opt/hpe/ssmc/ssmcbase/etc/truststore using Java keytool.

      For example:

      • Save the public certificate to be trusted (trust anchor for user certificate; this is typically the CA root of the chain or one of the intermediates that you want to trust) in PEM format as ~/user_trust.pem

      • cd /opt/hpe/ssmc/ssmcbase/etc

      • /opt/hpe/ssmc/jre/bin/keytool -keystore truststore -import -trustcacerts -alias <any_alias> -file ~/user_trust.pem

    • The default trust store password is BuyMore3PAR!. Changing this password requires a configuration change to /opt/hpe/ssmc/ssmcbase/etc/jetty-ssl-context.xml.

    • Generate an obfuscated string for the new password by following the procedure mentioned in the section Using obfuscated passwords in configuration files.

    • Replace the existing obfuscated trust store password string for the TrustStorePassword property in /opt/hpe/ssmc/ssmcbase/etc/jettyssl-context.xml with the newly generated one.

    For Primera arrays running firmware versions 4.3 or later, ensure that the user certificate is trusted by the array as well. SSMC performs the authentication of user certificate at its level and passes the certificate to the array for final authentication. For all lower versions of the firmware and 3PAR arrays, the following procedure is not applicable, and you can skip to the section on Certificate B.

    Import trust for user (client) certificate on Primera UI

    If two-factor authentication is intended for Primera UI as well, then perform the following steps. Otherwise, skip this section and proceed to Import trust for user (client) certificate on the array. For more information on configuring two-factor authentication for Primera UI, see HPE Primera UI User Guide.

    1. Log in to Primera UI as Super user.

    2. Navigate to Settings and select Trusted Certificates.

    3. Click the create icon (+) at the top right corner to add new trusted certificate.

    4. Select Other and paste PEM text of issuer certificates to be trusted.

      This could be one or more intermediate certificates and/or the CA root certificates.

    5. Click Add to save.

    Import trust for user (client) certificate on the array

    1. Log in to array CLI using an SSH client.

    2. Import root of trust for CAC user certificate authentication using the following command: 

      importcert cac -ca stdin

    3. Paste the CAC root user certificate in PEM text format on screen.

    4. Press Enter twice to continue and complete the import of user trust.

  • Certificate B — Server certificate identifying SSMC to the browser (not strictly necessary for two-factor authentication).

    This certificate is automatically created as a self-signed server certificate when you install SSMC. You can replace it with a certificate signed by a CA.

    This certificate resides in the Java keystore at /opt/hpe/ssmc/ssmcbase/etc/keystore. You can manage Certificate B with Java keytool. For more information on generating and installing this certificate in SSMC, see Installing CA-signed certificates for SSMC.

  • Certificate C — Client (or partner) certificate identifying SSMC to the storage array.

    This certificate does not exist by default. Generate the certificate according to your IT policy.

    Use the following example as a guideline to generate and install Certificate C in SSMC:
    • Perform initial set-ups.
      export PATH=/opt/hpe/ssmc/ssmcbase/fips/jre/bin:$PATH
cd /opt/hpe/ssmc/ssmcbase/data/StoreServMC/security/
    • Back up any existing TPDServerKeyStore file. 
      mv TPDServerKeyStore ~/TPDServerKeyStore.old
    • Generate a new self-signed key pair for SSMC identity certificate.
      keytool -genkeypair -keystore TPDServerKeyStore -storetype jks -storepass HPESecureStorage -keypass HPESecureStorage! -validity 365 -alias ssmc_id -keysize 2048 -keyalg RSA -storetype JKS -dname "cn=ssmc, ou=My Org Unit, o=My Org, st=NY, l=NYC, c=US" -ext KeyUsage=keyEncipherment,digitalSignature -ext ExtendedKeyUsage=clientAuth,1.3.6.1.4.1.12925.2.1.1
    • Generate CSR.
      keytool -certreq  -keystore TPDServerKeyStore -storepass HPESecureStorage -keypass HPESecureStorage! -alias ssmc_id -ext KeyUsage=keyEncipherment,digitalSignature -ext ExtendedKeyUsage=clientAuth,1.3.6.1.4.1.12925.2.1.1 -file ~/ssmc_id_csr.txt
      IMPORTANT: If any of the arrays that SSMC manages are Primera running OS version 4.3 or later, then it is mandatory to have the following certificate extensions in the final CA-signed certificate preserved as-is.
      -ext KeyUsage=keyEncipherment,digitalSignature 
-ext ExtendedKeyUsage=clientAuth,1.3.6.1.4.1.12925.2.1.1

    • Get the CSR (ssmc_id_csr.txt) signed by your CA as per your IT policy. Store the signed certificate in PEM encoding as ~/ssmc_id_signed.cer. Also, store the intermediate CA issuer certificate as ~/ssmc_intca.cer and the root CA certificate as ~/ssmc_rootca.cer.

    • Now, import the root CA certificate provided with alias specified as root: 
      keytool -import -alias root -keystore TPDServerKeyStore -storepass 
HPESecureStorage -file ~/ssmc_rootca.cer 
Enter keystore password:
.
.
.
Trust this certificate? [no]: yes
Certificate was added to keystore
      Next, import any intermediate CA certificates provided by the CA:
      keytool -import -keystore TPDServerKeyStore -storepass HPESecureStorage 
-file ~/ssmc_intca.cer

      Repeat this step until all intermediate certificates in the certificate chain are added to the keystore.

    • Finally, add the CA-signed SSMC identity certificate to the keystore using the ssmc_id as the alias:
      keytool -import -keystore TPDServerKeyStore -alias ssmc_id -storepass 
HPESecureStorage -keypass HPESecureStorage! -file ~/ssmc_id_signed.cer
    • Adjust the file permission and ownership to TPDServerKeyStore as follows:
      chmod 640 ./TPDServerKeyStore
chown ssmcadmin:hpe3parssmcuser ./TPDServerKeyStore
      IMPORTANT: You must edit ssmc.properties file and set the values of alias, keystore password, and key password (if different from keystore password) you have used while setting up TPDServerKeyStore.

    • You can add a clear-text password or generate an obfuscated string for the new password used, following the procedure mentioned in the section Using obfuscated passwords in configuration files.

      For example:

      Set these key value pairs in ssmc.properties (clear): 
      tpd.server.key.alias = ssmc_id
tpd.server.keystore.password = HPESecureStorage
tpd.server.keymanager.password = HPESecureStorage!
      Or set these key value pairs in ssmc.properties (obfuscated): 
      tpd.server.key.alias = ssmc_id
tpd.server.keystore.password = OBF:1nc21pbc1lyb1s2o1v1x1vn21spt1vnw1vn61snx1vo
01v2h1s4e1lzv1pcm1ndo
tpd.server.keymanager.password = OBF:19ye1ox61n4t1oq91vn61unn1z7k1s4e1t331s2o1
z7i1uob1vnw1or11n6p1oyc19w8
    For Primera arrays running firmware versions 4.3 or later, the partner (SSMC Certificate C) must be trusted in both Primera UI and the array. For all lower versions of the firmware and 3PAR arrays, the following procedure is not applicable, and you can skip to the section on Certificate D.

    1. Log in to Primera UI as Super user.

    2. Navigate to Settings and select Trusted Certificates.

    3. Click the create icon (+) at the top right corner to add new trusted certificate.

    4. Select Partner certificate and paste the PEM text of SSMC partner certificate (Certificate C) along with any text from intermediate issuers and then the CA root certificate as one combined PEM text.

    5. Click Add to save.

    6. Go to the array CLI and restart the WSAPI services by issuing the stopwsapi command followed by startwsapi.

  • Certificate D — Server certificate identifying the 3PAR/Primera storage array to SSMC.

    The 3PAR/Primera storage array automatically creates this certificate as a self-signed server certificate. You can install your own CA-signed certificate by generating and exporting a certificate signing request, getting it signed by your CA, and importing the signed array certificate.

    For example:

    • Issue the following command on array CLI to create a certificate signing request: 

      createcert unified-server -csr
    • Copy the csr text, and get it signed from your CA as per your IT policy. The signed certificate along with the trust chain is expected to be in PEM format. For example, cert.pem is the signed array certificate, int_ca.pem is the intermediate CA certificate, and root_ca.pem is the CA root certificate.
      IMPORTANT: When SSMC connects to the array, SSMC does a mutual TLS handshake (mTLS). In this process, the array requests for a client certificate from SSMC signed by the same issuer who signed the array's certificate, which is imported into the array certificate store as shown above. Therefore, it is required that both SSMC Partner certificate (Certificate C) and the array certificate (Certificate D) must be signed by the same issuer CA.
    • Combine the CA root and all the intermediate CA certificates (we have just one in this example) in PEM text form into a single file. 
      cat int_ca.pem root_ca.pem > ca_bundle.pem
    • Issue the following command on array CLI to import the CA-signed certificate along with the trust CA bundle.
      importcert unified-server stdin stdin

      Paste cert.pem file content first and press Enter twice. Paste CA bundle file content next and press Enter twice.

      For more information on certificate management commands on the array, see 3PAR/Primera array Command Line Interface (CLI) guide.

    • Export the trust chain (CA root + intermediate CAs) of Certificate D in PEM text form to a file. Copy that file to the /opt/hpe/ssmc/ssmcbase/data/StoreServMC/security path on the SSMC appliance. This allows SSMC to find trust for the storage array that presents its newly installed array certificate (cert.pem) during TLS connection.

      • Navigate to Administrator Console and the array would remain in Certificate Acceptance Needed state.

      • Choose Accept Certificate from Actions menu. Review, accept, and cache the new array certificate presented over the wire for the connection to be established.

      NOTE: If SSMC is in FIPS mode, you have to import the array certificate (cert.pem) manually.