Authenticating content files

Tanium as a Service (TaaS) automatically imports required content. You cannot import custom content in a TaaS deployment.

Overview of content imports and exports

The Tanium Console supports exporting and importing content, which is useful when you want to copy the content between Tanium Servers. You can export and import the content files in JSON format (best practice) or XML format.

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

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 the Tanium Console displays failure messages.

Figure  1:  Signature validation errors

In Tanium deployments with a lab license, the 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 or Tanium content packs (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.

Users who have the Administrator reserved role can export and import all content types. Users who have a role with the Import Signed Content permission enabled can import content only if the content file is signed and if the users have read permissions for the content type. For other users, the ability to export and import varies by content type and role assignments. For details, see Content management permissions.

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. For the steps to import signed content files and to export content, see Managing Tanium solutions.

Create content authentication keys

The Tanium Server provides the KeyUtility command-line program to generate a cryptographic key pair for signing and validating content files. KeyUtility and its associated files reside in the top-level installation folder of the Tanium Server (such as \Program Files\Tanium\Tanium Server). You can run the KeyUtility program from the installation folder or copy the files to a working folder on any Windows system and run the program from that working folder.

  1. (Optional) To run KeyUtility from a working folder, set up the folder as follows:
    1. Copy the following files from the Tanium Server installation folder (Windows deployments only) or from the location where you unzipped the file that Tanium Support provided:
      • KeyUtility.exe
      • libeay32.dll
      • ssleay32.dll
    2. Paste the files into the working folder.
  2. Open the Windows Command Prompt (cmd.exe) and run the following command from the folder 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 folder:

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

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
09/05/2018  08:05 PM               241 TaniumLab.pvk
5 File(s)      7,345,023 bytes
2 Dir(s)  41,049,174,016 bytes free	

Sign content files

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

  1. Copy the content file to a location that you can access from the folder where the KeyUtility and content-signing key files reside.

    The folder is either the Tanium Server installation folder (such as \Program Files\Tanium\Tanium Server) or a working folder that you set up: see Create content authentication keys.

  2. Open the Windows Command Prompt (cmd.exe) and go to the folder where the KeyUtility and key files reside.
  3. Sign the content file.

    KeyUtility.exe signcontent <private_key> <content_file>

    The following is an example of the command:

    KeyUtility.exe signcontent import.pvk "Example Multicolumn Sensor Windows Registry.json"

  4. Open the content file in a text editor and verify that a signature such as the following appears at the bottom:

    <!--hash=2a8bc7529c9fcdad037982bcbfc12306aa88ac8b9d95d02248ec369008188b7c0e356ad1811609c7 54eb01dc97c09b9f2acb10331e2d9dbf77d309124c61950a;signature=01AF3D547A97CCBD62A022F398 586DEAD4E29A30C29406283DA2E8F1E9FCF176194D66D4D9602538102F8F2FBBCFBC7AF370DB44E839C04 7253A246447E9A146706F00E94CD26D2CF29D8916E6EE0F21C77F0E13A6769905E5DDC09458912A94BB74 C1311C9B26301DB8D8C73AC043EBC6A5A836FB6815011F1ACB37E0248A30F100B631-->

Copy the public key to the key store

Before you import a content file, the Tanium Server keys folder (such as \Tanium\Tanium Server\content_public_keys\content) must have a copy of the public key that the server uses to validate the signature in the file. Copy the public key from the folder where you ran the key-generation command. The folder is either the Tanium Server installation folder (such as \Program Files\Tanium\Tanium Server) or a working folder that you set up: see Create content authentication keys.

For information on adding the content signing key to the Tanium Server on a Tanium Appliance, see Tanium Appliance Installation Guide: Enable import of user-created content.