Authenticating content files

Tanium Cloud automatically imports required content. You cannot import custom content in a Tanium Cloud deployment.

Overview of content imports and exports

Exporting content (such as sensors and roles) enables you to review the content attributes offline in an application outside Tanium Console or to import the content into another Tanium Server.

Supported file formats

You can export content as a file in one of the following formats:

CSV: When you open the file in an application that supports CSV format, it lists the content with the same attributes (columns) as the page from which you perform the export. For example, a CSV file for sensors displays the same attributes as the Sensors page.
JSON: If you are assigned a role with the Export Content permission, you can export content configurations as a JSON file. You can then import the file into another Tanium Server. The Administrator reserved role has the Export Content permission.

Develop and test custom content in your lab environment before importing the content into the production servers in your Tanium deployment.

Digital signatures and keys

In Tanium deployments with a production license, content that you import requires a digital signature by default. Signature validation helps to protect your deployment from imports of unauthorized files. A private key is used to create the signature. The Tanium Server uses the associated public key to validate the signature during the import process. You maintain the public keys of trusted signers on the Tanium Server. If none of the public keys in the Tanium Server key store can validate the signature, the server does not import the content, and Tanium Console displays failure messages.

In Tanium deployments with a lab license, Tanium Console notifies you if the file you selected to import is unsigned and lets you choose whether to proceed. However, the best practice is to not import unsigned files in any deployment.

You do not have to generate keys or signatures for content that you import as a component of Tanium solutions (see Managing Tanium solutions). Tanium signs this content before making it available, and the associated public key is distributed to the Tanium Server key store during the server installation process. For all other content, you must manually generate a public-private key pair to sign and validate the content files that you import.

As one-time tasks before importing content, you must generate the public-private key pair and copy the public key to the Tanium Server key store. You must then use the private key to sign each new content file that you import. If you plan to import a file that another user signed, you can first perform an integrity check on the file as described at Verify content file signatures.

Import and export permissions

Users who are assigned a role with Import Signed Content permission can import signed content files. Users who have the Administrator reserved role can export and import all content types. For other users, the ability to export varies by content type and role assignments. For details, see Content management permissions.

Import and export procedures

For the steps to export content files, see Export content files.

For the steps to import content files after you digitally sign them, see Import content files.

To troubleshoot content import issues, see Tanium Core Platform Deployment Reference Guide: Tanium Downloader logs.

Create content authentication keys

The Tanium Server provides a command-line program to generate a cryptographic key pair for signing and validating content files. The program is KeyUtility on Windows and TaniumKeyUtility on Linux. The program and its associated files reside in the top-level installation directory of the Tanium Server. You can run the program from the server installation directory (Windows only) or copy the files to a working directory on another system and run the program from that working directory.

Windows: Create content authentication keys

(Optional) To run KeyUtility from a working directory, set up the directory as follows:
1. Copy the following files from the Tanium Server installation directory (such as \Program Files\Tanium\Tanium Server) or from the location where you unzipped the KeyUtility-<release>.zip file that Tanium Support provided:
  - KeyUtility.exe
  - libeay32.dll
  - ssleay32.dll
2. Paste the files into the working directory.
Open the Windows Command Prompt (cmd.exe) and run the following command from the directory where the KeyUtility files reside. The <file name> argument defines the key-file names, but you do not have to specify the suffix. KeyUtility automatically appends the suffix .pub for the public key and .pvk for the private key.
KeyUtility.exe makekeys <file name>

The following is an example of the command and the resulting contents of a working directory:

D:\Tanium\Working>KeyUtility.exe makekeys import

D:\Tanium\Working>dir
			
Directory of D:\Tanium\Working
			
09/05/2018  08:05 PM    <DIR>          .
09/05/2018  08:05 PM    <DIR>          ..
08/17/2018  03:04 AM         4,254,704 KeyUtility.exe
03/27/2018  07:03 PM         2,632,192 libeay32.dll
03/27/2018  07:03 PM           457,728 ssleay32.dll
09/05/2018  08:05 PM               158 import.pub
09/05/2018  08:05 PM               241 import.pvk
5 File(s)      7,345,023 bytes
2 Dir(s)  41,049,174,016 bytes free

Linux: Create content authentication keys

On a Tanium Appliance, running TaniumKeyUtility requires shell access, which is not available in most cases. The following steps describe how to run the program from another working directory instead.

Contact Tanium Support to request the the KeyUtility-<release>.tgz file that contains TaniumKeyUtility and associated files (see Contact Tanium Support):
- TaniumKeyUtility
- libcrypto.so.1.0.0
- libssl.so.1.0.0
You can also find the files in the Tanium Server installation directory (such as /opt/Tanium/TaniumServer).
Copy KeyUtility-<release>.tgz to the working directory and uncompress it:

tar -xvf KeyUtility-<release>.tgz
Run the following command from the directory where TaniumKeyUtility resides. The <file name> argument defines the key-file names, but you do not have to specify the suffix. TaniumKeyUtility automatically appends the suffix .pub for the public key and .pvk for the private key.
./TaniumKeyUtility makekeys <file name>

The following is an example of the command and the resulting contents of a working directory:

./TaniumKeyUtility makekeys import

ls -l			

-r-xr-x---  1 tanium tanium  7947792 Jun  1 13:39 TaniumKeyUtility
-r-xr-x---  1 tanium tanium  2947600 Jun  1 13:39 libcrypto.so.1.0.0
-r-xr-x---  1 tanium tanium   459272 Jun  1 13:39 libssl.so.1.0.0
-rw-r-----  1 tanium tanium      158 Jul 19 16:38 import.pub
-rw-r--r--  1 tanium tanium      241 Jul 19 16:38 import.pvk

Sign content files

After you create a public-private key pair for authenticating content files, use the private key to sign the files.

Windows: Sign content files

Copy the content file to a location that you can access from the directory where the KeyUtility and content-signing key files reside.
The directory is either the Tanium Server installation directory (such as \Program Files\Tanium\Tanium Server) or a working directory that you set up. See Windows: Create content authentication keys.
Open the Windows Command Prompt (cmd.exe) and go to the directory where the KeyUtility and key files reside.
Sign the content file.
KeyUtility.exe signcontent <private_key> <content_file>
The following is an example of the command:
KeyUtility.exe signcontent import.pvk sensors.json
Open the content file in a text editor and verify that a signature such as the following appears at the bottom:

Linux: Sign content files

Copy the content file to a location that you can access from the directory where the TaniumKeyUtility and content-signing key files reside.
Go to the directory where the TaniumKeyUtility and key files reside.
cd <working directory>
Sign the content file.

./TaniumKeyUtility signcontent <private_key> <content_file>

The following is an example of the command:

./TaniumKeyUtility signcontent import.pvk "sensors.json"
Open the content file in a text editor and verify that a signature such as the following appears at the bottom:

Verify content file signatures

Users might copy content files between systems to make the files accessible for importing. For example, after testing custom sensors in a lab environment, a user might export the sensors as a JSON file and copy it to a production environment. Before you import a file that another user digitally signed, you can verify the integrity of the file as a security measure. Signature verification ensures that the correct private key was used to sign the file and that no one modified the file after it was signed. To verify the signature of a private key, you specify its associated public key in the verification command.

Windows: Verify file signatures

Copy the content file to a location that you can access from the directory where the KeyUtility and content-signing key files reside.
The directory is either the Tanium Server installation directory (such as \Program Files\Tanium\Tanium Server) or a working directory that you set up. See Windows: Create content authentication keys.
Open the Windows Command Prompt (cmd.exe) and go to the directory where the KeyUtility and key files reside.
Run the following command, where <public_key> is the public key associated with the private key that you are verifying:

KeyUtility.exe verifycontent <public_key> <content_file>

The following is an example of the command:

KeyUtility.exe verifycontent import.pub sensors.json

If the file passes verification, the output is:

Signature Verified.

Linux: Verify file signatures

Copy the content file to a location that you can access from the directory where the TaniumKeyUtility and content-signing key files reside.
Go to the directory where the TaniumKeyUtility and key files reside.
cd <working directory>
Run the following command, where <public_key> is the public key associated with the private key that you are verifying:

./TaniumKeyUtility verifycontent <public_key> <content_file>

The following is an example of the command:

./TaniumKeyUtility verifycontent import.pub sensors.json

If the file passes verification, the output is:

Signature Verified.

Copy the public key to the key store

Before you import a content file, the Tanium Server keys directory must have a copy of the public key that the server uses to validate the signature in the file. This is the public key that is associated with the private key that you use to sign content files, not the Tanium Server root public key tanium.pub.

Windows: Copy the public key to the key store

Copy the public key from the directory where you ran the key-generation command. The directory is either the Tanium Server installation directory (such as \Program Files\Tanium\Tanium Server) or a working directory that you set up. See Windows: Create content authentication keys.
Paste the public key into the \Program Files\Tanium\Tanium Server\content_public_keys\content directory.

Linux: Copy the public key to the key store

To add the public key to the Tanium Server on an Appliance, perform the steps in Tanium Appliance Installation Guide: Enable import of user-created content. Because you already generated the keys, skip the steps to download the utility and generate keys.