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

   

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.

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

      Tip

      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.

   Note

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

      Tip

      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> 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)
--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)
--trusted-ca-file (replaces KSCTL_TRUSTED_CA_FILE)

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 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.
       --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": ""
   }