Integration with AWS CloudHSM

Keeper SSO Connect On-Prem optionally integrates with cloud-based Amazon HSM (CloudHsmV2) devices for key protection and storage.

Integration with AWS Cavium CloudHsmV2

Keeper SSO Connect HSM Overview

Inside SSO Connect's data folder there are several files. Two of the files contain secret keys generated on the server that must be protected and are utilized to encrypt and decrypt the end-user's auto-generated master passwords. There is also a .sql file which contains a local cache of encrypted data. It is critical that access to this data folder is restricted.

On non-Windows machines the data folder is under the SSO Connect install folder, typically $HOME/sso_connect/data.

On Windows machines the data folder is in C:\ProgramData\Keeper SSO Connect\data\ since v14.1. Prior to v14.1 it was in C:\Program Files\Keeper Security\SSO Connect\data\.

You can add an extra layer of security by utilizing an HSM (Hardware Security Module) as described below. When an HSM is available, an encryption key is generated for each SSO Connect instance and stored securely in the HSM. The encryption key is used to encrypt the critical property files in the data/ folder.

AWS Cavium CloudHsmV2 Instructions

HSM Requirements

1. Amazon currently allows only CloudHsmV2 for new HSM deployments; Keeper supports this version. a. Legacy Cloud HSM v1 hardware is not supported by Keeper.

2. Amazon HSM software currently supports Linux or Windows installations.

Network Requirements

• Port TCP/443 open, stateful outbound from Keeper SSO Connect to www.keepersecurity.com

• Port TCP/2223 open, bidirectional from the SSO Connect machine to the HSM hardware

• Port TCP/2225 open, bidirectional from the SSO Connect machine to the HSM hardware

• Port TCP/8080 open, inbound from a Keeper Admin workstation to Keeper SSO Connect for admin GUI access (optional)

Testing network access

$ telnet www.keepersecurity.com 443
Trying 52.204.60.27
Connected to www.keepersecurity.com.
Escape character is '^]'.

CloudHsmV2 software installation

Provision your Amazon HSM cluster and install the HSM software on the SSO Connect machine as described in:

https://docs.aws.amazon.com/cloudhsm/latest/userguide/install-and-configure-client-linux.html

or

https://docs.aws.amazon.com/cloudhsm/latest/userguide/install-and-configure-client-win.html

You will need the Java libraries. On Linux the software is installed in /opt/cloudhsm.

Ensure that the cloudhsm_client service is running in the background:

$ ps aux | grep cloud
   If cloudhsm_client is not running:
       $ sudo service cloudhsm-client start
       $ ps aux | grep cloud
         ... /opt/cloudhsm/bin/cloudhsm_client ...

Test the Software Installation

$ sudo /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
aws-cloudhsm>listUsers
aws-cloudhsm>loginHSM CU <hsm_user> <hsm_password>
aws-cloudhsm>listUsers
aws-cloudhsm>getHSMInfo
aws-cloudhsm>quit

Install SSO Connect as usual.

NOTE: The Amazon HSM Java software is supposed to recognize a file named HsmCredentials.properties on the Java Classpath. However, this may not work for some reason. Instead you may need to set HSM_USER, HSM_PASSWORD, and HSM_PARTITION environment variables. For testing, you will probably have to set the shell variables.

Test the HSM connection:

$  java -Djava.library.path=/opt/cloudhsm/lib/ -classpath ~/sso_connect/SSOConnect.jar com.keepersecurity.util.AmazonKeyStoreExampleRunner

It should print the keys in the HSM.

Configure SSO Connect as usual via the command line or in the admin interface at http://localhost:8080/config

a. Set the "Advertised Hostname", a. Add the SSL certificate, a. Add the SAML XML metadata file.

In the admin interface, the HSM configuration section is at the bottom of the Configuration page.

a. Select "Amazon CloudHsmV2" as the type, a. Some properties will appear in the box below. You probably don't need to change them. i. An exception would be if the certificate to be used to talk to the HSM is not the same certificate used for SSL in SSO Connect. i. You may need to enter a password for the certificate file (usually the same one used for the SSL certificate file). a. Click the Enabled/Disabled box, a. Click Save

SSO Connect should now restart and connect to the HSM. If the status page shows that HSM is enabled, it worked. In rare situations when startup is very slow you may need to click on the Status command again so that it updates the status.

If it didn't work, check the SSO Connect error log. The most common error is that it can't find the HSM credentials. Set the credentials as environment variables to ensure that they are available.

If it didn't work, check the error log. The most common error is that it can't find the HSM credentials. Set the credentials as environment variables to ensure that they are available.

Troubleshooting

Troubleshooting the Configuration

1. Verify that SSOconnect is installed on the machine.

   • Usually there is a folder called sso_connect, KeeperSSO, or some similar name. The folder will contain many jar files.

2. Verify that the HSM device is accessible.

   • SSOconnect has a built-in test program copied from the Amazon test libraries:

     $  java -Djava.library.path=/opt/cloudhsm/lib/ -classpath ~/sso_connect/SSOConnect.jar com.keepersecurity.util.AmazonKeyStoreExampleRunner

     It should print the keys stored in the HSM.

Troubleshooting the Operation

1. Check the log file for errors. The Secure Key Storage subsystem of SSOconnect will print an ERROR line to the log if it encounters a problem.

   $ more logs/ssoconnect.log

2. The error will be a variation of "Unable to use Secure Key Storage". This indicates one of the following problems:

     a. Network problem accessing the HSM
        - Ensure that ports 2223 and 2225 are open.
   
     b. data/sks.properties is missing
        - if data/sks.properties is missing you will need to re-configure SSOConnect.
   
     c. The encrypted property files are missing
        - Check for data/instance.encp and data/shared.encp.
   
     d. The encryption key is missing from the HSM
        - Did somebody clear the HSM partition?  You will need to re-configure SSOConnect.
   
     e. The server may be out of disk space
        - clear some disk space.
   
     f. The encryption algorithm used is not supported on the HSM
        - The algorithm is AES/GCM/NoPadding.  Check with the device provider.
   
     g. The file data/sso-keystore.jks is missing
        - The program cannot store a key in the HSM without the certificate chain from the sso_keystore.jks file.
          Find the file and ensure that it is in the data folder.

Backup

The data folder contains the SSO Connect configuration files. At a minimum it should be backed up after initial configuration and each time the configuration is modified. In addition to the configuration files, there are data files in data but they will automatically be refreshed if they get out of synch with the Keeper server. Thus, regular periodic backups can be used but are not necessary. The data folder on each SSO Connect instance needs to be backed up independently because not all of the configuration settings are shared among instances.

On non-Windows machines the data folder is under the SSO Connect install folder, typically $HOME/sso_connect/data.

On Windows machines the data folder is in C:\ProgramData\Keeper SSO Connect\data\ since v14.1. Prior to v14.1 it was in C:\Program Files\Keeper Security\SSO Connect\data\.

Recovery

Server Failure

If the SSO Connect server dies you will need to reinstall Amazon HSM and SSO Connect on the replacement machine using the standard installation instructions above.

If you have backed up the data folder as described above, restore it before starting SSO Connect. If a data folder already exists (because you started SSO Connect), stop SSO Connect, remove all files in the data folder, copy the files from the backed-up data folder, and restart SSO Connect. SSO Connect should start successfully.

If you did not backup the data folder or if the backup is out-of-date you will need to configure the replacement instance as if it were a new installation. Please follow the SSO Connect installation guide.

HSM Failure

When using an HSM, the HSM stores the encryption key used to decrypt the configuration files in the data folder. The HSM is accessed once, when SSO Connect starts, and also any time the configuration is changed. If the configuration files are encrypted and the encryption key stored on the HSM is lost or inaccessible the SSO Connect instance will need to be configured again in order to create new, unencrypted configuration files. Delete the contents of the data folder and configure SSO Connect from scratch again.

You can disable HSM/SKS use by entering 'no' to the "Enable SKS?" configuration question, or by using the -disableSKS command-line option.