Securing keys with an HSM

Tanium Cloud uses Transport Layer Security (TLS) to secure the connections among Tanium Core Platform components. You cannot use a hardware security module (HSM) to manage the digital keys that Tanium Cloud uses for TLS communication.

HSM integration overview

A hardware security module (HSM) is a hardened, tamper-resistant device that organizations use to store and generate digital keys and to perform cryptographic operations with those keys, such as encryption and decryption for Transport Layer Security (TLS) communication. During these operations, the keys never leave the HSM and are therefore more secure than if you store them in a file system, such as the installation directories of Tanium Core Platform servers. You can use any HSM that supports the standard PKCS #11 API (Cryptoki) to manage the Tanium root keys and message-signing keys. For details about how the Tanium Core Platform uses these keys, see Tanium Console User Guide: Managing Tanium keys.

You require the Administrator reserved role to configure and manage an HSM integration.

If you upgrade from Tanium Core Platform 7.3 to version 7.4 or later, the HSM configuration is preserved and the HSM stores the root keys for all Tanium Client versions.

If you configure HSM for a deployment that is at Tanium Core Platform 7.4 or later, the HSM stores the root key for Tanium Client 7.4 or later but not the legacy-root key for Tanium Client 7.2. The best practice is to upgrade Tanium Client 7.2 to version 7.4.

Tanium Appliance: Integrate with an HSM

Contact Tanium Support at [email protected] for the steps to integrate the Tanium Appliance with an HSM.

Windows: Integrate with an HSM

Before you begin

Perform the following tasks before configuring the Tanium deployment to use an HSM.

  1. Set up the HSM. For details, see the HSM documentation.

  2. Determine the PKCS #11 module that the HSM vendor provides to support Cryptoki. The module enables communication between the Tanium Server and HSM. For example, Thales HSM provides the library cknfast.dll as the PKCS #11 module for 32-bit Windows systems.

  3. Work with an HSM Security Officer (SO) to initialize tokens on the HSM to contain Tanium keys. Initialization involves assigning a token name (or ID) and personal identification number (PIN) for each token. You must know the PINs and the token names or IDs to configure the Tanium Server to authenticate to the tokens. The server authenticates when performing operations that involve the keys in those tokens.

    In HSM terminology, a token is a logical view of a cryptographic device that contains keys.

  4. (Optional, best practice) Back up the Tanium deployment. See Tanium Core Platform Deployment Guide for Windows: Back up Tanium Core Platform servers and databases.

    If you need to back up keys after integrating with an HSM, see the HSM documentation.

  5. Determine a maintenance window to perform the HSM integration. You must restart the Tanium Server during the process of configuring it to use an HSM, and the restart interrupts any operations that the server is performing.

Integrate the Tanium deployment with an HSM

In an active-active deployment, Tanium Servers do not synchronize local settings, which include HSM settings. Therefore, perform the steps for adding settings and restarting the Tanium Server service on each server.

  1. From the Main menu, go to Administration > Configuration > Settings > Advanced Settings.
  2. Click Add Setting, configure the HSMModulePath setting as follows, and click Save:

    • Setting TypeLocal

    • Name: HSMModulePath
    • Value Type: Text
    • Value: Directory path of the HSM vendor-specific PKCS #11 module, such as C:\Program Files\nCipher\nfast\toolkits\pkcs11\cknfast.dll

    In the following steps, replace the <key> variable with the Tanium key that the HSM will manage: Root or MessageSigning.

  3. For each key, click Add Setting, configure the UseHSM setting as follows, and click Save. UseHSM forces the Tanium Server to generate the key on the HSM instead of locally.

    • Setting Type: Local

    • Name: Keys.<key>.UseHSM

    • Value Type: Numeric

    • Value: 1

  4. For each key, click Add Setting, configure the HSMPassword setting as follows, and click Save. When the Tanium Server performs key operations, it uses the HSMPassword to authenticate to the token that contains the key.

    • Setting Type: Local

    • Name: Keys.<key>.HSMPassword

    • Value Type: Protected

    • Value: The PIN that is associated with the token that contains the key

  5. For each key, click Add Setting, configure the HSMTokenName or HSMTokenID setting as follows, and click Save. The Tanium Server uses HSMTokenName or HSMTokenID to identify the token that contains the key.

    • Setting Type: Local

    • Name: Keys.<key>.HSMTokenName or Keys.<key>.HSMTokenID

    • Value Type: Text for HSMTokenName or Numeric for HSMTokenID

    • Value: The token name or ID

  6. (Optional) Review the settings to ensure you entered them correctly. To display only the HSM settings on the Advanced Settings page, enter HSM in the Filter items field.
  7. Sign in to the Tanium Server host, open the Windows Services program, right-click the Tanium Server service, and select All Tasks > Restart.

    Wait for the Tanium Server service to finish restarting before continuing. In an active-active deployment, restart the service on both servers before continuing.

  8. Rotate the root keys by generating new keys and revoking the old keys. See Tanium Console User Guide: Managing Tanium keys.

    When you rotate the root keys, the Tanium Server automatically rotates the subordinate keys. The new keys are stored on the HSM instead of on the Tanium Server.

    After generating new keys, wait one week before revoking the old root keys to ensure that the process of generating new keys finishes for all Tanium Core Platform components. When you revoke, any components that did not finish this process expend more processing resources and network traffic to generate new keys.

  9. Verify that the new keys on the HSM work. See Verify an HSM integration.

Verify an HSM integration

After you generate new keys on an HSM, verify that the Tanium Core Platform can use the keys for communication among platform components:

  1. Sign in to the Tanium Console as a user who is assigned a role that allows issuing questions.
  2. Verify that the Environment Status section on the Tanium Home page shows Tanium Clients are connected to the Tanium Server. Connectivity indicates that the root keys work properly.
  3. Issue any question to any number of Tanium Clients. If the clients return results, the message-signing key works properly. See Tanium Console User Guide: Asking questions.

If any verification steps fail, see Troubleshoot an HSM integration.

Disable an HSM integration

You might want to temporarily disable an HSM integration if, for example, you plan to migrate to a new HSM appliance. After completing the migration, you would configure the HSM settings with the values of the new appliance and re-enable the integration. If you do not want to use any HSM for managing keys, you can remove the integration.

  1. From the Main menu, go to Administration > Configuration > Settings > Advanced Settings.
  2. Perform one of the following sub-tasks based on whether you want to temporarily disable the HSM integration or remove it entirely. In an active-active deployment, perform the sub-task on each Tanium Server.
    • Disable the integration temporarily: Perform the following sub-steps for each Tanium key that the HSM manages.
      1. In the Name column, click Keys.<key>.UseHSM, where <key> is Root or MessageSigning.
      2. Set the Value to 0 and click Save.
    • Remove the integration:
      1. Enter HSM in the Filter items field to display only the HSM settings.
      2. Select all the HSM settings and click Delete Selected Settings Delete Selected Settings.
  3. Rotate the root keys by generating new keys and revoking the old keys. See Tanium Console User Guide: Managing Tanium keys.

    When you rotate the root keys, the Tanium Server automatically rotates the subordinate keys. The new keys are stored on the Tanium Server (pki.db file) instead of on the HSM.

    After generating new keys, wait one week before revoking the old root keys to ensure that the process of generating new keys finishes for all Tanium Core Platform components. When you revoke, any components that did not finish this process expend more processing resources and network traffic to generate new keys.

  4. Verify that the new keys on the Tanium Server work. The verification steps are the same as when you enable an HSM integration. See Verify an HSM integration.

Update token PINS, names, or IDs

If possible, avoid changing the PIN, name, or ID for a token that stores Tanium keys. If updating these token credentials becomes necessary, update the key settings as described in the following steps. Additionally, for a new token name or ID, you must contact Tanium Support at [email protected] for help performing configuration steps that are not available through the Tanium Console.

  1. From the Main menu, go to Administration > Configuration > Settings > Advanced Settings.

    In the remaining steps, replace the <key> variable with the Tanium key that the HSM manages: Root or MessageSigning.

  2. To change a token PIN, click Keys.<key>.HSMPassword in the Name column, set the Value to the new PIN, and click Save.
  3. To change a token name, click Keys.<key>.HSMTokenName in the Name column, set the Value to the new name, and click Save.
  4. To change a token ID, click Keys.<key>.HSMTokenID in the Name column, set the Value to the new ID, and click Save.

Troubleshoot an HSM integration

If issues occur when you configure or verify an HSM integration:

  1. Review the PKI logs for error messages. All Tanium Core Platform servers and Tanium Clients generate PKI logs.

    • Platform servers on Windows: See PKI logs.

    • Tanium Appliance: Sign in to the TanOS console, open a read-only restricted shell, and review the PKI logs in the <server_installation_directory>/Logs directory of each server. See Tanium Appliance Deployment Guide: Open read-only restricted shell.
    • Tanium Client: The PKI logs are in the <client_installation_directory>/Logs directory.
  2. Verify that Tanium Clients are using the correct keys. See Tanium Client Management User Guide: Review or reset the public key to troubleshoot connection issues.
  3. Resolve the issues. If necessary, contact Tanium Support at [email protected] for assistance.

  4. Perform the task Verify an HSM integration to confirm the resolution works.