Managing Tanium keys

Overview of Tanium keys

TLS communication

Transport Layer Security (TLS) is a cryptographic protocol that uses digital keys to provide authentication, privacy, and data integrity between client-server applications that communicate over a network. The Tanium Core Platform supports TLS 1.2 for the following network connections (the green lines in Figure  1):

  • Tanium Client to Tanium Server
  • Tanium Client to Zone Server
  • Tanium Client to Tanium Client (version 7.4 or later only)
  • Tanium Server to Tanium Server in a high availability (HA) deployment
  • Tanium Server to Zone Server Hub to Zone Server
Figure  1:  TLS communication in the Tanium Core Platform

When you install or upgrade to Tanium Core Platform 7.4 or later, TLS is enabled by default on the platform servers (you cannot disable it) and on Tanium Clients. For more details about TLS, and the steps to enable or disable TLS on the clients or on servers running version 7.3 or earlier, see Tanium Core Platform Deployment Reference Guide: Setting up TLS communication.

Tanium keys apply only to communication among Tanium Core Platform components. Your enterprise public key infrastructure (PKI) governs the security of non-Tanium communication among the endpoints in your network, regardless of whether Tanium Clients are installed on them.

You require the Administrator reserved role to manage Tanium keys.

To manage the keys that secure Hypertext Transfer Protocol Secure (HTTPS) connections from user systems to the Tanium Console or API, and between the Tanium Server and Module Server, see Tanium Core Platform Deployment Reference Guide: Securing Tanium Console, API, and Module Server access.

For details about the key that is used to authenticate content files that you import into the Tanium Server, see Authenticating content files.

The Tanium Core Platform supports TLS for additional connections that various Tanium modules and shared services require. For details, see the user guides for your Tanium products at https://docs.tanium.com.

Root keys

When you install the Tanium Server, it automatically generates a public-private root key pair. These root keys are at the top of the Tanium key infrastructure and are required for all subordinate keys to secure connections among Tanium Core Platform components. You deploy the root public key to the Zone Server, Zone Server Hub, and Tanium Clients during installation or upgrade so that these components can secure communication with the Tanium Server.

The Tanium Server uses separate root key pairs for TLS communication with Tanium Clients based on their version. Initially after a fresh installation or upgrade, Tanium Client 7.4 or later uses the root public key that has a Server value of <Tanium Server FQDN> Root 0 (see Figure  3). Each new root public key that you create for version 7.4 or later has a unique Server value (<Tanium Server FQDN> Root <#>). The root public key for Tanium Client 7.2 has the Server value legacy-root. You cannot create new keys for version 7.2.

Subordinate keys

The Tanium Server, Zone Server, Zone Server Hub, and Tanium Clients generate subordinate keys locally and request a digital signature for each key pair. The signatures are required for TLS communication. The Tanium Core Platform uses the following subordinate keys, as shown in Figure  2:

  • TLS keys: Each Tanium Core Platform server and Tanium Client uses TLS keys to enable TLS communication with other servers and clients. The Tanium Server uses the root private key to generate signatures for the server TLS keys.
  • Message-signing keys: The Tanium Server uses these keys to sign messages (such as for action packages) that it sends to Tanium Clients. The Tanium Server uses the root private key to generate a signature for the message-signing keys.
  • Intermediate TLS keys: An intermediate TLS private key is used to generate signatures for the TLS keys of Tanium Clients. The intermediate TLS key pair resides on the Zone Server in deployments that have one (as shown in Figure  2), and on the Tanium Server otherwise. The server returns both the signature and the intermediate TLS public key to each client to enable TLS communication. Using intermediate TLS keys instead of the root keys for this function makes client registration faster and less CPU intensive. For security, you can rotate the intermediate keys independently of the root keys.
Figure  2:  Tanium keys

A copy of the root public key resides in the Zone Server Hub installation directory regardless of whether the hub is installed on the same host as the Tanium Server (as shown in Figure  2) or on a dedicated host.

To enable communication among the Tanium Core Platform servers, you must also enable trust. For details, see Managing Tanium Server trust and Managing Zone Servers and hubs.

Key rotation

Although root keys never expire, you can rotate them, which means generating new keys and revoking the old keys. Rotating keys is useful if your organization has a policy for periodic key rotation or the security of the active keys is in doubt. If your organization does not have a key rotation policy, the best practice is to rotate the root keys at least once every year but no more than once every six months. If the security of the active root keys is in doubt, rotate them immediately.

You cannot rotate the root keys for Tanium Client 7.2. The Tanium Console identifies the 7.2 root keys with a Server value of legacy-root (see Figure  3).

To ensure the security of root private keys, the Tanium Console exposes only root public keys. However, when you generate or revoke a public key, the Tanium Server automatically generates and revokes the private key. Furthermore, when you rotate the root keys, the Tanium Core Platform automatically rotates all subordinate keys. Regardless of whether you rotate the root keys, the subordinate keys automatically rotate at configurable intervals.

The following steps summarize the workflow for rotating keys:

  1. (Optional best practice) On each Tanium Server, encrypt the pki.db file that contains the root keys, Tanium Server TLS keys, and message-signing keys. This is a one-time only task that you perform to prevent unauthorized access to the keys. See Encrypt the root keys database.
  2. (Optional best practice) Back up the pki.db file that resides on each Tanium Server, in case the servers later experience an unrecoverable failure. Do this whenever you rotate the root keys. See Back up the root keys.
  3. If your organization has a key rotation policy, configure automatic rotation for subordinate keys to match the policy. This is a one-time only task, unless your policy changes. See Configure automatic rotation for subordinate keys.
  4. Generate a new root public key. The Tanium Server automatically generates a new corresponding private key and triggers the creation of new subordinate keys. See Generate root keys.

    As a best practice, 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. However, if the security of the root keys is in doubt, revoke the old keys immediately after generating the new keys.

  5. Revoke the old root public key. The Tanium Server automatically revokes the associated private key and propagates the revocation directive for the old root keys and subordinate keys to all Tanium Core Platform components. For details, see Revoke root keys.

View root key information

The Configuration > Tanium Server > Root Key Management page displays a tile for each root public key that is active, and also displays a grid that lists revocation details for revoked keys. In an HA deployment, the page displays the keys for both Tanium Servers, but only after you approve trust between them (see Managing Tanium Server trust). You can identify keys by their Fingerprint, which is the hash digest of the key, and by the Server value. The root public key that the Tanium Server uses for TLS communication with Tanium Client 7.2 has a Server value of legacy-root. All the other keys are for TLS communication with Tanium Core Platform servers and with Tanium Client 7.4 or later.

Figure  3:  Tanium root public keys

Encrypt the root keys database

As a best practice to prevent unauthorized access, specify a password to encrypt the root keys that the Tanium Server stores in the pki.db file. In an HA deployment, perform this task on each Tanium Server.

The Tanium Console displays the values of most settings that you configure. However, for security, the console does not display the encryption password unless you manually reveal it: see View protected Tanium Server settings.

Set the encryption password

Encrypt the root keys by adding the PKIDatabasePassword setting:

  1. Go to Configuration > Tanium Server > Local Settings and click New Setting.
  2. For the Setting Name, enter PKIDatabasePassword.
  3. For the Setting Value, enter a password.
  4. Set the Value Type to protected.
  5. Click Save and confirm the operation when prompted.

As a best practice, store the password in a safe location.

Change the encryption password

After adding the PKIDatabasePassword setting, you can later change the password as follows:

  1. Go to Configuration > Tanium Server > Local Settings.
  2. Select the PKIDatabasePassword setting.
  3. Click Edit and enter the new password in the Setting Value.
  4. Click Save and confirm the operation when prompted.

Back up the root keys

As a best practice when you rotate the root keys, first back up the pki.db file that contains them, along with the associated password if you encrypted the file. You can use the backup in the event of a Tanium Server failure. Copy the pki.db file from the <Tanium_Server>/backups folder to the host where you store backups, and store the password in a secure location. In an HA deployment, perform this task for each Tanium Server.

If you restore the backup pki.db on a Tanium Server, you must also restore the associated Tanium database to enable Tanium Clients to connect to that Tanium Server. Therefore, back up the Tanium database whenever you back up pki.db.

Generate root keys

You can generate up to two active public-private root key pairs for each Tanium Server. Perform this task on each Tanium Server in an HA deployment.

  1. Go to Configuration > Tanium Server > Root Key Management.
  2. Click Create Key beside the name of the Tanium Server that requires a new public-private root key pair. The Root Key Management page displays the root public key details in a new tile.

Revoke root keys

To prevent communication disruptions among Tanium Core Platform components, you cannot revoke a root key pair until you first generate a new key pair to replace it. Review the key rotation workflow before revoking the old root key pair. You must revoke keys on both Tanium Servers in an HA deployment. Revoke keys as follows:

  1. (HA deployments only) If the Tanium Server for which you will revoke the keys has only one active root key pair, you must revoke trust for that server before revoking its keys: see Revoke trust.
  2. Go to Configuration > Tanium Server > Root Key Management.
  3. In the Active Root Keys section, click Revoke in the tile of the public key and confirm the operation when prompted.

Download infrastructure configuration files (keys)

The Zone Server, Zone Server Hub, and Tanium Clients must authenticate the Tanium Server to enable communication with it. Version 7.4 of the servers and clients use keys (including the root public key) that are inside the initialization bundle (tanium-init.dat) to authenticate. Tanium Clients 7.2 or earlier use only the root public key (tanium.pub) to authenticate. Downloading the initialization file or public key file from the Tanium Server enables you to then deploy the file to the Tanium Clients, Zone Server, and Zone Server Hub.

For version 7.4 or later of the servers and clients, the initialization bundle is required for fresh installations. If you upgraded and plan to deploy more 7.2 clients, use the public key. If you upgraded and plan to deploy new 7.4 clients, using the initialization bundle is the best practice.

  1. (HA deployment only) Enable trust between the Tanium Servers in an HA deployment if you haven't already. Upon establishing trust, the servers exchange the necessary keys so that the tanium-init.dat file on each server contains the public key of both servers. For details, see Managing Tanium Server trust.
  2. Go to Configuration > Tanium Server > Infrastructure Configuration Files.
  3. Click Download in the Clients v7.4+ and Zone Server or Clients v7.2 and v6.x section, depending on which file you need.
  4. Optionally modify the default file name, and then click OK. The file appears in the Downloads folder on the system that you use to access the Tanium Console.

To deploy tanium-init.dat or tanium.pub, see the relevant user guide:

Configure automatic rotation for subordinate keys

Tanium Core Platform components automatically generate new subordinate key pairs when it is time to rotate them. For example, Tanium Clients renew their TLS keys four hours (the renewal window) before the end of each seven-day validity period (expiration interval) by default. The renewal windows ensure components have enough time to re-establish trust in the Tanium environment before the current keys expire. Configure the validity periods and renewal windows to match the policy of your organization. If your organization does not have a policy, the best practice is to use the default windows and validity periods. Perform the following steps for each type of subordinate key pair:

  1. Go to Administration > Global Settings and select the setting in the grid (see Table 1).
  2. In the Selected System Setting pane, click Edit.
  3. In the Setting Value, enter the appropriate validity period or renewal window.
  4. In the Affects drop-down list, select an option based on the setting:
    • PKIClientTLSKeyRenewalWindowHours: Select client.
    • All other settings: Select server.
  5. Click Save.
Table 1:   Settings for key rotation
Setting Guidelines
pki_server_tls_key_duration_days The validity period for the key pair that the Tanium Server uses for TLS communication with another Tanium Server (in an HA deployment), the Zone Server Hub, or Tanium Clients (in deployments without a Zone Server). The default is 7 days.
pki_server_tls_key_renewal_window_hours The renewal window for the key pair that the Tanium Server uses for TLS communication with another Tanium Server (in an HA deployment), the Zone Server Hub, or Tanium Clients (in deployments without a Zone Server). The default is 4 hours.
pki_message_signing_key_duration_days The validity period for the key pair that the Tanium Server uses to sign messages (such as for action packages) that it sends to Tanium Clients. The default is 180 days.
pki_message_signing_key_renewal_window_hours The renewal window for the key pair that the Tanium Server uses to sign messages (such as for action packages) that it sends to Tanium Clients. The default is 4 hours.
pki_hub_tls_key_duration_days The validity period for the key pair that the Zone Server Hub uses for TLS communication with the Tanium Server and Zone Server. The default is 60 days.
pki_hub_tls_key_renewal_window_hours The renewal window for the key pair that the Zone Server Hub uses for TLS communication with the Tanium Server and Zone Server. The default is 4 hours.
pki_zoneserver_tls_key_duration_days The validity period for the key pair that the Zone Server uses for TLS communication with the Zone Server Hub and Tanium Clients. The default is 60 days.
pki_zoneserver_tls_key_renewal_window_hours The renewal window for the key pair that the Zone Server uses for TLS communication with the Zone Server Hub and Tanium Clients. The default is 4 hours.
pki_client_tls_ca_key_duration_days The validity period for the key pair that the Zone Server or Tanium Server (in deployments without a Zone Server) uses to provide digital signatures for Tanium Clients when they generate new TLS key pairs. The default is 180 days.
pki_client_tls_ca_key_renewal_window_hours The renewal window for the key pair that the Zone Server or Tanium Server (in deployments without a Zone Server) uses to provide digital signatures for Tanium Clients when they generate new TLS key pairs. The default is 168 hours (7 days).
pki_client_tls_key_duration_days The validity period for the key pairs that Tanium Clients use for TLS communication with each other and with the Zone Server or Tanium Server (in deployments without a Zone Server). The default is 7 days.
PKIClientTLSKeyRenewalWindowHours The renewal window for the key pairs that Tanium Clients use for TLS communication with each other and with the Zone Server or Tanium Server (in deployments without a Zone Server). The default is 4 hours.