Batching Commands with Tokens

As described in Tokens, a token is returned after logging in to the CipherTrust Manager, for example, using the config.yaml file or the –-user and –-password command line parameters. This token, when used with subsequent commands, can improve performance with the CipherTrust Manager, since verifying the token is much faster than looking up the user and password on each invocation.

If the user wishes to perform batched commands and desires greater performance, you can use this token as described in this section.

Download and install the jq program

Since we are dealing with .json responses, the first step is to download and install the jq program from https://stedolan.github.io/jq/download/. This program parses information from returned json parameters, allowing the user to manipulate them as needed. Follow the instructions on this page for installation on your operating system and be sure that jq is in your PATH.

Using tokens to perform operations

You can now retrieve a token for a user on the platform and by utilizing this information, perform operations on the CipherTrust Manager. We will detail connecting as a user that has already been created and using the token from that user to perform a key creation on the CipherTrust Manager.

The environment variable KSCTL_JWT is utilized by ksctl for accessing the token used. Refer to the CLI Installation for other variables utilized by ksctl, available either in the environment or the config.yaml file.
In addition, the examples below are specific to *nix operating systems; small differences will be necessary if running under Windows. The CLI Installation has sections that detail these differences.

We will now get a token and user_id from a previously created user, Sarah. These will be used to create a key. The key creation step can be repeated numerous times to create as many keys as you want and are able to support.

Get Sarah’s token

1. To retrieve a user’s token:

   $ ksctl tokens create --user sarah --password Sarah_pw1
   

   Returns the following response:

   {
     "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiIzNjU3OWYyYi03ZmUyLTRlYWYtOTQ3Ni03ZGU0MmNjYjFlYTkiLCJzdWIiOiJsb2NhbHw3N2JmMTI0Yy1jNGYyLTRhODktYTc3Ny1iZTlmOGM2NmQwOTkiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6InNhcmFoIiwiY3VzdCI6eyJncm91cHMiOlsiS2V5IFVzZXJzIl19LCJqd3RpZCI6ImJlNTI5NTIzLWE0YzktNGMzZS05ZTdhLTNjZDJmNzA4Y2I5YiIsImlhdCI6MTUyOTY5NDMzMywiZXhwIjoxNTI5Njk0NjMzfQ.0z-x_lIue37Jju94ZsU1UvTR0s09ick7BT2N6uPmAoo",
     "duration": 300,
     "token_type": "Bearer"
   }
   

2. To assign the token to the KSCTL_JWT environment variable, enter:

   $ export KSCTL_JWT=$(ksctl tokens create --user sarah --password Sarah_pw1 | jq -r ".jwt")
   

   If you have user sarah defined in your config.yaml file, the –-user and –-password variables are not needed.

For the purposes of this example, Sarah’s user_id must be retrieved; it is used in the creation of a key.

Get Sarah's ID

1. To retrieve Sarah's user_id, enter:

   $ ksctl users list --name sar
   

   Returns the following response:

   {
     "skip": 0,
     "limit": 10,
     "total": 1,
     "resources": [
       {
         "created_at": "2017-06-22T16:25:56.441357Z",
         "email": "",
         "last_login": "2017-06-22T18:34:15.835436Z",
         "logins_count": 2,
         "name": "sarah",
         "nickname": "sarah",
         "updated_at": "2017-06-22T18:34:15.835436Z",
         "user_id": "local|77bf124c-c4f2-4a89-a777-be9f8c66d099",
         "username": "sarah",
         "failed_logins_count": 0,
         "account_lockout_at": null,
         "failed_logins_initial_attempt_at": null,
         "last_failed_login_at": null,
         "password_changed_at": "2017-06-22T16:25:56.441806Z",
         "password_change_required": false
       }
     ]
   }
   

2. To assign Sarah's user_id to an environment variable, enter:

   $ export SARAH=$(ksctl users list --name sarah | jq -r ".resources[0]"|jq -r ".user_id")
   

Create a key

$ ksctl keys create --autoname –ownerid $SARAH --jsonfile keyparams.json

This command can be run in a loop to automatically create as many keys as desired. If your loop runs longer than the lifetime of your JWT, you can periodically refresh the token with a new create. The lifetime of your JWT is returned in the create call; see the duration field. The valued is in seconds.

Refresh the token

$ export KSCTL_JWT=$(ksctl tokens create --user sarah --password Sarah_pw1 | jq -r ".jwt")

As you can see, there is some setup effort involved in these commands. However, the payoff in ease-of-use and performance is worth the time spent.