Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo
back

CLI Toolkit

CLI Toolkit Installation

search

Please Note:

CLI Toolkit Installation

CipherTrust Manager includes a CLI toolkit, named ksctl, that can be downloaded and run locally to control a remote CipherTrust Manager.

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

ksctl exclusively uses the REST API to communicate with CipherTrust Manager, so anything you can do with the CLI 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 adding users and groups, and end-user functions, such as creating keys.

To get started with ksctl you must do the following:

  1. Download and unzip the ksctl_images.zip file.

  2. Setup the ksctl-os file for your system. This includes setting some basic configuration variables for ksctl authentication.

  3. (Optional) Further set ksctl configuration variables, if desired.

  4. Run ksctl.

Download and unzip the ksctl_images.zip file

  1. Enter the IP address of your CipherTrust Manager system in your browser.

  2. If you are logged into CipherTrust Manager, select the API link at the top right. If you are logged out, select API & CLI Documentation at the bottom right.

  3. Select the CLI Guide page and click on Download CLI button:

    Download CLI

  4. Unzip the ksctl_images.zip file.

    Example set of available images in ksctl_images.zip file:

    ksctl-darwin-amd64
ksctl-linux-amd64
ksctl-win-amd64.exe

Setup the ksctl-os for your system

The ksctl utility can be set up on Windows, Linux, and macOS.

Windows

  1. After unzipping, rename ksctl-win-amd64.exe to ksctl.exe.

    ksctl.exe is a single executable with no dependencies, so it can be run from anywhere.

  2. Move the ksctl.exe file to a folder easily accessed by the local command prompt.

    You can also add the location of the ksctl.exe file to your PATH variable or copy ksctl.exe to a location already in your PATH.

  3. Create a ksctl configuration file using the local command prompt cmd.exe:

    1. Create a .ksctl directory in your %HOMEPATH% directory:

      mkdir %HOMEPATH%\.ksctl
cd %HOMEPATH%\.ksctl

    2. In the %HOMEPATH%.ksctl directory, create a config.yaml file with the following items:

      KSCTL_USERNAME: admin
KSCTL_PASSWORD: <your password>
KSCTL_URL: https://<ciphertrust manager ipaddress>
KSCTL_NOSSLVERIFY: true

      Enter set homepath to find or confirm your %HOMEPATH% directory.

Linux

  1. After unzipping, rename the file of choice to ksctl and move it to a directory within your PATH.

    ksctl can be run from any directory.

  2. Create a ksctl configuration file:

    1. Create a .ksctl directory in your $HOME directory:

      mkdir $HOME/.ksctl
cd $HOME/.ksctl

    2. In the $HOME/.ksctl directory create a config.yaml file with the following items:

      KSCTL_USERNAME: admin
KSCTL_PASSWORD: <your password>
KSCTL_URL: https://<ciphertrust manager ipaddress>
KSCTL_NOSSLVERIFY: true

  3. Bash completions can be generated by typing ksctl bashcomp at the bash prompt and following the instructions.

macOS

  1. After unzipping, rename ksctl-darwin-amd64 to ksctl and move it to a directory within your PATH.

  2. In Finder, right-click or control-click the ksctl executable and select Open. You cannot open the executable by double-clicking.

    Note

    For some versions of macOS, a prompt appears indicating that macOS cannot verify the developer. You need to dismiss the prompt and navigate into Security & Privacy settings to manually allow ksctl.

  3. On the prompt, click Open to proceed.

  4. Create a ksctl configuration file:

    1. Create a .ksctl directory in your $HOME directory:

      mkdir $HOME/.ksctl
cd $HOME/.ksctl

    2. In the $HOME/.ksctl directory create a config.yaml file with the following items:

      KSCTL_USERNAME: admin
KSCTL_PASSWORD: <your password>
KSCTL_URL: https://<ciphertrust manager ipaddress>
KSCTL_NOSSLVERIFY: true

      Enter env | grep HOME to find your $HOME directory.

ksctl Configuration Variables

Summary of ksctl configuration variables for the config.yaml configuration file:

KSCTL_USERNAME: <your username>
KSCTL_PASSWORD: <your password>
KSCTL_URL: https://<ciphertrust manager ipaddress>
KSCTL_NOSSLVERIFY: <true or false>
KSCTL_CONNECTION: <LDAP connection name>
KSCTL_VERBOSITY: <true or false for verbosity>
KSCTL_JWT: <JWT>
KSCTL_RESPFMT: <response output format, the default "json" is the only supported value at present>
KSCTL_TIMEOUT: <timeout in seconds for TCP connection attempts>

ksctl is easiest to use with the configuration file (config.yaml). However, those parameters can be overridden by using these flags on the command line:

--user (replaces KSCTL_USERNAME)
--password (replaces KSCTL_PASSWORD)
--url (replaces KSCTL_URL)
--connection (replaces KSCTL_CONNECTION)
--verbose (replaces KSCTL_VERBOSITY)
--jwt (replaces KSCTL_JWT)
--respfmt (replaces KSCTL_RESPFMT)
--timeout int (replaces KSCTL_TIMEOUT)
--nosslverify (replaces KSCTL_NOSSLVERIFY)

If you wish to override KSCTL_NOSSLVERIFY it must be set to false in the configuration file.

Run ksctl

This is an example only; not all supported CLI commands and flags are shown.

  1. At the command line prompt, enter ksctl. You will get the following example output:

    ksctl

This command line utility can be used to interface with a CipherTrust Manager device.

Configuration parameters can be used to pass in the username, URL, etc.
These parameters can be passed to the application in several ways.

When the configuration parameters are available from multiple sources,
the order of precedence (highest to lowest) is:

1. Command line arguments
2. Configuration file passed via the command line
3. Environmental variables
4. Configuration file in the default location

The parameters passed in as command line arguments override
everything else.

The structure of the configuration file must be based on
'config_example.yaml'. The name of the default configuration file is
'config.yaml'. It should be located in the '.ksctl' subdirectory of the
user's home directory.

On Linux, this file should be located in: '~/.ksctl/config.yaml'.

On Windows, this file should be located in: 'C:/.ksctl/config.yaml'.

If defined, proxy environment variables (i.e. 'http_proxy') will be honored
for all functions except 'init getpw'. 'init getpw' internally uses ssh
which means that ssh must be configured to be proxy aware for the users
local operating system.

Usage:
  ksctl [command]

Available Commands:
  alarms          Manage Alarms. List, state and clear commands.
  backup          Perform system or domain database backups.
  backupkeys      Manage Backup keys. Used for securing backups.
  banners         Manage Login Banners.
  bashcomp        Generate bash completion script file for all commands and flags.
  ca              Manage Certificate Authorities and Certificates.
  cckm            Manage CipherTrust Cloud Key Manager.
  changepw        Change a user password.
  client-records  Get client record(s).
  clientmgmt      Create Client Tokens and Register Clients.
  cluster         Manage Clusters.
  connectionmgmt  Manage AWS, Azure connections.
  connections     Manage authentication connections
  .
  .
  .

Flags:
    --configfile string   Full path and name to a file that     contains the
                          configuration parameters (optional).
    --connection string   The friendly name of the server you want to
                          authenticate against. (default "local_account")
    --domain string       The CipherTrust Manager Domain that the command will operate in. Can be used only with user/password and
                          not with token.
                          By default the command will operate in the root domain or the domain the user is logged-in.
-h, --help                help for ksctl
    --jwt string          The JSON Web Token (JWT) - access token can be passed instead
                          of user/password (optional). 'ksctl tokens
                          create' creates a JWT.
    --nosslverify         Do not verify the certificate for SSL/HTTPS
                          authentication (not recommended)
    --password string     CipherTrust Manager Server User Password. Do not use this flag to enter the password (masked) from terminal.
    --respfmt string      Response Output format (json is the only supported
                          value at present, optional) (default "json")
    --timeout int         Timeout in seconds for TCP connection attempts
    --token string        The refresh token returned from the login command to be
                          passed instead of user/password (optional).
                          'ksctl login' creates a token and writes
                          it to the config file.
    --url string          CipherTrust Manager Server URL
    --user string         CipherTrust Manager Server User Name
-v, --verbose             Provide verbose output while executing command
                          (optional)

Use "ksctl [command] --help" for more information about a command.

  2. Try creating a key by entering the command ksctl keys create –autoname:

    ksctl keys create --autoname

    This will create output similar to the following:

    {
"id": "b979d9c7-1374-4b97-a274-dfaa20f8139b",
"uri": "kylo:kylo:vault:keys:keys-f0f3ellhqh5r7xavk3l0-rx-ktkmwgzf3-rudppxrw4-v0",
"account": "kylo:kylo:admin:accounts:kylo",
"application": "ncryptify:gemalto:admin:apps:kylo",
"devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
"createdAt": "2016-12-15T15:35:51.322996318Z",
"name": "Keys-f0F3eLlhQh5R7XAVK3l0_rx-KtkmWGzF3-rUDPpXRW4",
"updatedAt": "2016-12-15T15:35:51.322996318Z",
"material": "",
"usage": "blob",
"meta": null,
"version": 0,
"algorithm": "AES",
"size": 256,
"format": "raw",
"unexportable": false,
"undeletable": false,
"publickey": ""
}