Install the CLI Toolkit

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. The default value is false.>
KSCTL_CONNECTION: <LDAP connection name>
KSCTL_VERBOSITY: <true or false for verbosity>
KSCTL_TRUSTED_CA_FILE: <Filename of the Trusted CA. 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_SERVER_NAME: <Used to verify the hostname on the server certificate. Required when KSCTL_NOSSLVERIFY is set to false, the hostname is not present on the client workstation `etc/hosts` file, or the hostname is not mapped on the local DNS server>

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=false)
--verbose=false (replaces KSCTL_VERBOSITY=true)
--jwt (replaces KSCTL_JWT)
--respfmt (replaces KSCTL_RESPFMT)
--timeout int (replaces KSCTL_TIMEOUT)
--nosslverify (replaces KSCTL_NOSSLVERIFY=false)
--nosslverify=false (replaces KSCTL_NOSSLVERIFY=true)
--trusted-ca-file (replaces KSCTL_TRUSTED_CA_FILE)
--server-name (replaces KSCTL_SERVER_NAME)

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:
     akeyless        Akeyless Gateway
     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.
     .
     .
     .
   
   Flags:
     --auth-domain string       The CipherTrust Manager Domain Where the user is created.
                                By default the auth domain is root or provide the domain where user created.
     --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 except 'tokens create' command.
                                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")
   --server-name string         Name of the Server which is used to verify the hostname on the returned certificates unless nosslverify is given.
     --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": ""
   }