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, see: Import content files.

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.

Create content authentication keys on Windows

  1. (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.
  2. 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	

Create content authentication keys on Linux

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.

  1. Contact Tanium Support to request the the KeyUtility-<release>.tgz file that contains TaniumKeyUtility and associated files:
    • 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).

  2. Copy KeyUtility-<release>.tgz to the working directory and uncompress it:

    tar -xvf KeyUtility-<release>.tgz

  3. 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.

Sign content files on Windows

  1. 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 Create content authentication keys on Windows.

  2. Open the Windows Command Prompt (cmd.exe) and go to the directory 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 sensors.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-->

Sign content files on Linux

  1. Copy the content file to a location that you can access from the directory where the TaniumKeyUtility and content-signing key files reside.
  2. Go to the directory where the TaniumKeyUtility and key files reside.

    cd <working directory>

  3. Sign the content file.

    ./TaniumKeyUtility signcontent <private_key> <content_file>

    The following is an example of the command:

    ./TaniumKeyUtility signcontent import.pvk "sensors.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-->

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.

Verify file signatures on Windows

  1. 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 Create content authentication keys on Windows.

  2. Open the Windows Command Prompt (cmd.exe) and go to the directory where the KeyUtility and key files reside.
  3. 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.

Verify file signatures on Linux

  1. Copy the content file to a location that you can access from the directory where the TaniumKeyUtility and content-signing key files reside.
  2. Go to the directory where the TaniumKeyUtility and key files reside.

    cd <working directory>

  3. 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.

Copy the public key to the key store on Windows

  1. 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 Create content authentication keys on Windows.

  2. Paste the public key into the \Program Files\Tanium\Tanium Server\content_public_keys\content directory.

Copy the public key to the key store on Linux

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.