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

3. Run ksctl.

To download and unzip the ksctl_images.zip file:

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

2. On the CipherTrust Manager start page, select API & CLI Documentation link.

3. At the top of the API & CLI Documentation page, click on Download CLI button:

   

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

To setup the ksctl-os for your system:

Windows

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

   Note

   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.

   Note

   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. To find or confirm your %HOMEPATH% directory, enter:

      set homepath
      

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

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

   3. 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_ipaddress> or https://<ciphertrust_hostname>
      KSCTL_NOSSLVERIFY: true
      

Linux

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

   Note

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

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_ipaddress> KSCTL_URL: https://<ciphertrust_hostname>
      KSCTL_NOSSLVERIFY: true
      

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

To override ksctl configuration file

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

KSCTL_USERNAME: <your username>
KSCTL_PASSWORD: <your password>
KSCTL_URL: https://<ciphertrust_ipaddress> or https://<ciphertrust_localhost>
KSCTL_NOSSLVERIFY: <true or false>
KSCTL_CONNECTION: <LDAP connection name>
KSCTL_VERBOSITY: <true or false for verbosity>
KSCTL_TRUSTED_CA_FILE: <Filename of the Trusted CA. It is only required when KSCTL_NOSSLVERIFY is set to false.>
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)
--nosslverify (replaces KSCTL_NOSSLVERIFY)
--trusted-ca-file (replaces KSCTL_TRUSTED_CA_FILE)

--connection (replaces KSCTL_CONNECTION
--verbose (replaces KSCTL_VERBOSITY)
--jwt (replaces KSCTL_JWT)
--respfmt (replaces KSCTL_RESPFMT)
--timeout int (replaces KSCTL_TIMEOUT)

To run ksctl:

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 system.
   
   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:
   (a) command line arguments,
   (b) configuration file passed via the command line,
   (c) environmental variables, and
   (d) 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 here: '~/.ksctl/con
   fig.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.
     bashcomp    Generate bash completion script file for all commands and flags.
     ca          Manage Certificate Authorities and Certificates.
     changepw    Change a user password.
     clientmgmt  Create Client Tokens and Register Clients.
     cluster     Manage Clusters.
     connections Manage authentication connections
     crypto      Cryptographic data processing commands that use keys stored in the system.
     diskenc     Disk encryption configuration, query and unlocking commands.
     gendocs     Generate man pages and documentation for all commands and flags.
     .
     .
     .
   
   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")
     -h, --help                    help for ksctl
         --jwt string              The JSON web token (JWT) 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
         --trusted-ca-file string  Filename of the Trusted CA to be read from 
         --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": ""
   }