Your suggested change has been received. Thank you.

close

Suggest A Change

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

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.

  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:

    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.

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

Linux

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

    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_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>
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)
--nosslverify (replaces KSCTL_NOSSLVERIFY)

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

--connection (replaces KSCTL_CONNECTION
--verbose (replaces KSCTL_VERBOSITY)
--jwt (replaces KSCTL_JWT)
--respfmt (replaces KSCTL_RESPFMT)
--timeout int (replaces KSCTL_TIMEOUT)
To 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 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
          --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": ""
    }