Interfaces

This section provides an overview of the CipherTrust Manager interfaces.

CLI

The CipherTrust Manager includes a CLI tool, named ksctl, that can be downloaded and run locally to control a remote CipherTrust Manager appliance. ksctl exclusively uses the REST API to communicate with the CipherTrust Manager, so anything that you can do with the tool, you can also do directly with the REST API. Conversely, ksctl exposes most of the functionality of the REST API. It can perform management functions, such as managing registration tokens and clients.

Note

ksctl is designed to be run from a remote system, not on the CipherTrust Manager itself.

To use the CLI:

1. Open the CipherTrust Manager URL in a browser.

2. Click the API & CLI Documentation link. The API playground is displayed.

3. At the top left, click CLI Guide. The CLI documentation is displayed.

4. At the top right, click the CLI download button. This downloads the ksctl_images.zip file.

5. Unzip the ksctl_images.zip file. The extracted files contain platform specific files. For example, the file for Windows is ksctl-win-amd64, and for Linux, the file is ksctl-linux-amd64.

6. Set up the ksctl-<os> file for your system. Refer to the CipherTrust Manager CLI documentation for details.

7. Run ksctl cte to run CipherTrust Transparent Encryption specific commands.

Refer to the CipherTrust Manager documentation for details. For details on commands related to CipherTrust Transparent Encryption, refer to the online documentation of ksctl cte.

Authenticating to the Embedded API Guide

The embedded API Guide shares authentication with the CipherTrust Web UI. To authenticate to both the API Guide and the CipherTrust Web UI, visit https://<ciphertrust_manager_IP_or_hostname> in a web browser. Alternatively, click the Log In link in the top right corner of the API Guide when you are unauthenticated.

The simplest login is with a username and password. This authenticates a local user to the root domain. There can be additional login options to authenticate to another domain, authenticate with a certificate, authenticate using LDAP, or authenticate using OIDC. These options require additional user management configuration from a user in the User Admins group.

After login, the API Guide is accessible through the API button in the upper right corner.

There, you can make API calls in the established authentication context. You are logged out after 10 minutes of inactivity with the API Guide open. If you close the browser window, you are logged out after 30 minutes of your last login.

Manual API Token Generation for User Credentials

You can generate an API token with a user's username and password for a given domain, outside of the embedded API guide. This is useful if you have created a custom REST API client.

To copy and paste the following example commands, set an environment variable to point to your CipherTrust Manager instance:

$ export KSCTL_URL=https://{addr}               # sh/bash
$ set -x KSCTL_URL=https://{addr}               # fish

For example, this command will use the root admin's credentials to create an API token:

$ curl -k -X POST $KSCTL_URL/api/v1/auth/tokens/ \
     -H "Content-Type: application/json" \
     -d "{\"name\":\"admin\",\"password\":\"admin\"}"

Note

By default, this command creates a token for the root domain. You can specify a child domain to log in to with "{\"name\":\"domain_user\",\"password\":\"domain_user_password\", \"domain\":\"domain_name\"}"

The response:

{
  "jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJkMzEzYzcwZS01NmYyLTQ5MTUtOGJkNy01ZmMyYmUyNzk2YzEiLCJzdWIiOiJsb2NhbHxiM2ZjOGZlNy1hN2ZlLTQ1YzEtOWU1OS0zYmUxNTRkMTZjYmQiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsImN1c3QiOnsiZ3JvdXBzIjpbImFkbWluIl19LCJpYXQiOjE0ODExMjQxMzcsImV4cCI6MTQ4MTEyNDQzN30.Z9GU0YyOImHMdPmbZx66vL0NLQfeLvNGkyGkZpVbfx4",
  "duration":300
}

Copy the value of the jwt property into another environment variable:

(sh)  $ export KSCTL_JWT=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJkMzEzYzcwZS01NmYyLTQ5MTUtOGJkNy01ZmMyYmUyNzk2YzEiLCJzdWIiOiJsb2NhbHxiM2ZjOGZlNy1hN2ZlLTQ1YzEtOWU1OS0zYmUxNTRkMTZjYmQiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsImN1c3QiOnsiZ3JvdXBzIjpbImFkbWluIl19LCJpYXQiOjE0ODExMjQxMzcsImV4cCI6MTQ4MTEyNDQzN30.Z9GU0YyOImHMdPmbZx66vL0NLQfeLvNGkyGkZpVbfx4
(fish)$ set -x KSCTL_JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJkMzEzYzcwZS01NmYyLTQ5MTUtOGJkNy01ZmMyYmUyNzk2YzEiLCJzdWIiOiJsb2NhbHxiM2ZjOGZlNy1hN2ZlLTQ1YzEtOWU1OS0zYmUxNTRkMTZjYmQiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsImN1c3QiOnsiZ3JvdXBzIjpbImFkbWluIl19LCJpYXQiOjE0ODExMjQxMzcsImV4cCI6MTQ4MTEyNDQzN30.Z9GU0YyOImHMdPmbZx66vL0NLQfeLvNGkyGkZpVbfx4

Using the jq tool, we can fetch, extract, and export the token in a single shell command:

(sh)  $ export KSCTL_JWT=$(curl -k -X POST $KSCTL_URL/api/v1/auth/tokens/ \
                                    -H "Content-Type: application/json" \
                                    -d "{\"name\":\"admin\",\"password\":\"admin\"}" | jq -r '.jwt')
(fish)$ set -x KSCTL_JWT (curl -k -X POST $KSCTL_URL/api/v1/auth/tokens/ \
                                   -H "Content-Type: application/json" \
                                   -d "{\"name\":\"admin\",\"password\":\"admin\"}" | jq -r '.jwt')

We can use that API token to make other calls:

$ curl -k "$KSCTL_URL/api/v1/vault/keys2?limit=20" \
     -H "Authorization: Bearer $KSCTL_JWT"

Making an API Call

To make an API call, find the API in the left pane and click it. In the right pane, specify the required parameters, and click an appropriate button (for example, POST, GET, DELETE, or Curl). For example, to create a CTE policy on CipherTrust Manager:

1. In the left pane of the API playground, click CTE/Policies.

2. Under cte/policies, click Create. The Create section of the API playground is displayed in the right pane.

3. In the body field, specify required parameters with their values, as shown below.

   {
       "name": "TestPolicy",
       "policy_type": "Standard",
       "never_deny": false,
       "security_rules": [
           {
               "effect": "permit",
               "action": "all_ops",
               "partial_match": false,
               "resource_set_id": "TestResourceSet",
               "exclude_resource_set": true
           }
       ]
   }

   Copy

   Expand schema under the body field for names and types of fields. Hover your mouse over each field to view its description. The parameter names and casing in the body field must match with those shown in the schema. Also, ensure that parameters and their values are specified in double quotes.

4. Click POST.

Alternatively, to get an equivalent curl command, click the Curl button. The curl equivalent will be shown in the text field below. Use the curl tool to run the command to make the REST API call.

Similarly, all API calls can be made by referring to the schema shown in the playground.

GUI

Use the CipherTrust Manager's GUI (also called the Management Console) to perform management functions such as managing profiles, policies, clients and client groups, and GuardPoints. These functions can also be performed using the CLI tool or the REST API.

To use the GUI:

1. Open the CipherTrust Manager URL in a browser.

2. Enter Username and Password.

3. Click Log In. By default, the Products page is displayed.

4. Click Transparent Encryption to open the application.

The Clients page of the Transparent Encryption GUI is displayed, as shown below.

The main components of a Transparent Encryption GUI are:

• Header

• Left Pane

• Page

• Notifications

Header

Element	Description
	App switcher. Click to view and switch to another application such as Access Management and Admin Settings.
	Thales logo.
	Application name. For CTE, Transparent Encryption is displayed.
	Version and Server Info icon. Click to view the name, appliance name, and version of the CipherTrust Manager.
	Link to the API playground.
	Link to the CipherTrust Manager product documentation.
	Logged in user. Click to switch domains, view and update user settings (Email address and password), and log out.

Left Pane

Contains links to manage CTE resources - clients, policies, reports, and settings etc.

Page

A page is the main working area that provides options to manage CTE resources. Depending on the selected option in the left pane, the page shows different types of information. These options are described in this document, where appropriate.

At any time, a page can either be in the list view or in the edit view. A sample screenshot of the list view of the Clients page is shown below. Most pages follow the similar pattern except that they show different content based on the resource being managed.

The sample page shown above can be divided into the following elements:

Element	Description
Title	Shows the page name.
Status bar	Shows the total number of clients added to the CipherTrust Manager, the number of clients with errors, warnings, healthy state. The status bar also shows the number of unregistered and expunged clients on the CipherTrust Manager. The status bar also acts as a filter. Click a health status to see the list of clients with that status.
Search box ()	Filters clients based on their partial or full names. Search is case-insensitive.
List	Shows the clients based on the selected health status. By default, all the clients added to the CipherTrust Manager are displayed.
Compatibility Matrix button	Provides an option to upload the kernel compatibility matrix.
Create Client button	Provides an option to add a new client even before a CTE Agent is installed on it.
Delete icon ()	Deletes the selected clients. A message is prompted to confirm the action.
Check box ()	Provides an option to select a client for deletion or modification. Multiple clients can be selected to perform the delete operation on them. Use the check box provided just under the Search box to select all clients visible on the page.
Expand icon ()	Shows mini detail view of a client in the clients list.
Custom View icon ()	Hides/shows optional columns. For example, click this icon on the Clients page shows: Select or clear the desired column and click OK.
Overflow icon ()	Shows additional options. Depending on the current state of a client, the options can vary.
Pagination	Helps configure the number of records to display. By default, 10 records per page are displayed.
Tooltip icon()	Shows the basic description about an element when the mouse pointer is moved over the tooltip icon. Click the Learn More link in the tooltip to view the related documentation.

Notifications

CTE prompts toast notifications at the top right corner of the main page area. These notifications are shown when operations such as creation or deletion of an entity is performed.

Green success toast notifications are displayed for successful operations.

Red error notifications are displayed for failed operations.