Quick Start

This quick start guide describes the concise steps to set up and run a CT-VL appliance to perform tokenization, encryption, and key management. This guide focuses on using a virtual machine hosted on VMware vSphere ESXi. For other options to run a CT-VL appliance, see Alternative Deployments.

Prerequisites for Installing CT-VL

Prerequisites for installing CT-VL as a VM are listed below:

• CipherTrust Manager server 2.0 or higher.

• VMWare vSphere ESXi Server 6.0 or higher.

• CT-VL OVA image version 2.6.0 or higher.

• For optimal performance, the recommended settings for a CT-VL VM are 4 CPUs and 16GB memory.

Installing CT-VL

Steps for installing CT-VL as a VM are listed below:

1. Create a CT-VL virtual machine

2. Log in to the VM

3. Set up the VM network

4. Register VM with the Key Manager

5. Initialize the CT-VL cluster

1. Creating a CT-VL Virtual Machine

Obtain a CT-VL ISO or OVA image file (for example, cts-2.6.0.205.ova) and deploy it to create a virtual machine. Refer to the VMware ESX User Guide on how to create a virtual machine using an ISO or OVA image. It is recommended to use Thick Provisioning for hard disks. Select the Guest OS Family as Linux and Guest OS Version as Ubuntu Linux (64-bit).

For a multi-node setup, you can repeat this installation process for additional machines. You would then configure each node separately and join them in a cluster. See Configuring CT-VL Nodes for details.

2. Initial Log In

Power up the CT-VL virtual machine that you have created. Open the virtual machine console and log in using the following credentials:

login: cliadmin
password: cliadmin123

This initial log-in will prompt you to change the password of the cliadmin user.

3. Network Setup

Networking for CT-VL can either use DHCP or the static IP configuration.

4. Register the CT-VL VM with CipherTrust Manager (CM)

You can register the CT-VL VM with the CM as the key manager. For complete set of steps, see Registering CT-VL VM with CipherTrust Manager.

Perform the following steps to register the CT-VL VM with the CipherTrust Manager:

Log in to the CM server

1. Create an NAE interface.

2. Choose a port number for the NAE interface and set the mode to "TLS, verify client cert, user must supply password."

3. For the CipherTrust Manager 2.11 and higher, enable Allow unregistered clients.

4. Set a local CA for the NAE interface.

5. Create a CM user for CT-VL use.

6. Create AES key(s) for CT-VL use. Preferably, use 256 bits for key size.

7. Set the AES key(s) to be exportable.

8. Set the AES key(s) to be accessible by the CM user created in #4 above.

Log in to the CT-VL VM

1. Run the CLI command below to configure the CM server.

   icapi setup
   

   This command runs an interactive setup to configure connectivity to the CM server. Follow the prompts to supply the IP address of the CM, port number of the NAE interface, CM user, and password. The CM user supplied must have access to the keys that will be used by CT-VL.

2. Run the CLI command below to register the CT-VL VM to the CM server.

   icapi register --host <ipaddress> --user <admin>
   

   where:
   ipaddress - IP address of the CM server.

   admin - name of a user on the CM with admin access to sign certificates.

3. Enable CM for CT-VL use.

   icapi enable yes
   

4. Restart VTS service.

   vts> service --restart
   

5. Test connectivity to the CM server.

   Run the CLI command below to test if CT-VL can connect and authenticate to the CM server.

   icapi test --server_connection
   

6. Test access to a key on the CM.

   Run the CLI command below to test if CT-VL has access to a key.

   icapi test --key keyname
   

5. Initialize the CT-VL Cluster

Even if you have only one CT-VL server, you need to create and initialize a cluster. Run the command below to initialize the CT-VL cluster.

cluster create

This command is interactive. You will be prompted to supply a username, password, and email. This user will be created on the CT-VL VM and will serve as the initial administrative user to the WebUI.

Configuring CT-VL

Complete the following steps to configure CT-VL:

I. Configure CT-VL Tokenization API

Browse to the hostname or IP address https://<ct-vl_ipaddress>/ of the VM.

Log in to the CT-VL Web user interface using the username and password created during cluster initialization.

II. Create Users

1. Navigate to the Users menu.

2. Select the 'New User' button and specify the appropriate details to create users. At a minimum, users created must have 'Active' permission to allow access to tokenization, encryption, and key management REST-APIs. To allow access to the WebUI, users must have 'Staff' or 'Superuser' permissions. Setting users with 'Staff' permission will allow WebUI access but read-only. Setting users with 'Superuser' permission will allow WebUI access with read-write.

III. Create Keys

1. Navigate to the Keys menu.

2. Select the 'Symmetric Keys' tab.

3. Create symmetric keys you will use for tokenization, encryption, or key management. The name of the keys supplied must match the name of keys on the Key Manager.

IV. Create Token Groups

1. Navigate to the Tokenization > Token Groups Menu.

2. Create a token group and assign a key that it will use.

V. Create Token Templates

1. Navigate to the 'Tokenization Templates' Menu.

2. Create a Tokenization Template and set a name and token group for it.

3. Select a Format algorithm, e.g., FPE.

4. Select a Character Set, e.g., All digits.

VI. Set Key Permissions

1. Navigate to the 'Permissions' Menu.

2. Select a user and key.

3. Select the permissions you will require for the user. For tokenization operations, select 'Tokenize' and/or 'Detokenize'. For cryptographic operations, options are: Encrypt, Decrypt, Sign, and Verify. For key management operations, options are: Destroy, Modify, Export, and Find.

Run a sample tokenization, detokenization, cryptographic operation.

Complete the required operations:

• Tokenize Data

• Detokenize Data

• Encrypt Data

• Decrypt Data

Tokenize Plaintext Data

Use a REST-API client to tokenize a plaintext numeric data.

Request POST Parameters

Request

curl -k -u vtsuser -X POST 'https://ipaddress/vts/rest/v2.0/tokenize' \
-H 'content-type: application/json' \
-d '{"tokengroup": "TG1", "tokentemplate": "TT1", "data": "1111222233334444"}'

Response

{
    "token": "6300847582017130",
    "status": "Succeed"
}

Detokenize Tokenized Data

Use a REST-API client to detokenize a tokenized data.

Request POST Parameters

Request

curl -k -u vtsuser -X POST 'https://ipaddress/vts/rest/v2.0/detokenize' \
-H 'content-type: application/json' \
-d '{"tokengroup": "TG1", "tokentemplate": "TT1", "token": "6300847582017130"}'

Response

{
    "data": "1111222233334444",
    "status": "Succeed"
}

Encrypt Plaintext Data

Use a REST-API client to encrypt a plaintext data.

Request POST Parameters

Sample POST request data for encryption:

{
    "plaintext": "9mBirbK+VZLR/x6gDlGioQ==",
    "alg": "A256CBCPAD",
    "kid": "key1",
    "params": {
        "iv": "aKcjACEIDhOx0AXOSCQoqQ=="
    }
}

Request

curl -k -u vtsuser -X POST 'https://ipaddress/vts/crypto/v1/encrypt' \
-H 'content-type: application/json' \
--data @encrypt_data.yaml

Response

{
    "ciphertext":"WPn2Py8oC7kM1MRTtf4xYxho+UnbVYmTKmKibC9X2+o=",
    "tag":""
}

Decrypt Ciphertext Data

Use a REST-API client to decrypt a ciphertext data.

Request POST Parameters

Sample POST request data for decryption:

{
    "ciphertext": "WPn2Py8oC7kM1MRTtf4xYxho+UnbVYmTKmKibC9X2+o=",
    "alg": "A256CBCPAD",
    "kid": "key1",
    "params": {
        "iv": "aKcjACEIDhOx0AXOSCQoqQ=="
    }
}

Request

curl -k -u vtsuser -X POST 'https://ipaddress/vts/crypto/v1/decrypt' \
-H 'content-type: application/json' \
--data @decrypt_data.yaml

Response

{
    "plaintext":"9mBirbK+VZLR/x6gDlGioQ=="
}