SmartKey CLI

Updated: July 25, 2017

Download

The CLI utility can be downloaded here.

smartkey-client is a simple, cross-platform SmartKey client command line utility written in Python.

API endpoint

By default, smartkey-client makes REST API calls to the SmartKey server at https://www.smartkey.io. To make calls to a different SmartKey server, either set the environment variable FORTANIX_API_ENDPOINT, e.g., FORTANIX_API_ENDPOINT=<smartkey-server-url>, or provide the server url on command line using the --api-endpoint option.

Authentication

The SmartKey Server supports two types of authentication: user authentication and application authentication. Users are authenticated with passwords and perhaps second factors. Applications are authenticated with an API Key or with a certificate.

Each action that may be performed in SmartKey requires some form of authorization. Some actions, such as encrypting or decrypting data, may only be performed with application credentials. Some actions, like creating new groups, creating applications, and changing group membership, may only be done with user credentials. Some actions, such as creating new security objects (keys) may be performed with either user credentials or application credentials.

smartkey-client supports both user authentication and application authentication. It may have an active session for a user, an application, or both simultaneously. See the Developer guide for more details on these concepts.

smartkey-client user-login authenticates a user account using its SmartKey username and password.

smartkey-client app-login authenticates an application with an API key.

In both cases, persistent session information is stored in in a hidden file .token in the current directory.

smartkey-client logout logs out of the SmartKey server and clears .token. You may also use smartkey-client user-logout or smartkey-client app-logout to log out of just the current user session or just the current application session.

For example,

$ smartkey-client user-login
Please enter your SmartKey username: user@example.com
SmartKey Password:
Successfully logged in
$ smartkey-client list-apps
bf105894-f004-4c75-b4ba-f51168674355 test app This is a test application Groups(5893a573-ed9c-4e38-a3bc-ad72a1820bc1)
$ smartkey-client app-login
Please enter your API Key: <paste an SmartKey API Key>
Successfully logged in
$ smartkey-client logout
User logged out
App logged out

Importing keys and certificates

smartkey-client import-key and smartkey-client import-cert expect keys and certificates to be in PEM format.

Examples

Creating an app to use with SmartKey:

$ smartkey-client user-login
Please enter your SmartKey username:
SmartKey Password:
Successfully logged in
$ smartkey-client create-group --name "My group" --description "Test group"
47e173b6-c993-476e-af3f-013509428c78
$ smartkey-client list-groups
47e173b6-c993-476e-af3f-013509428c78 "My group" "Test group" 7bbb7a0b-de6b-4311-a7fa-053de7eabced
$ smartkey-client create-app --name "My app" --description "Test app" --groups 47e173b6-c993-476e-af3f-013509428c78
2b9a6296-3ed7-47a6-8ab2-5ddf92935f6e
$ smartkey-client list-apps
2b9a6296-3ed7-47a6-8ab2-5ddf92935f6e "My app" "Test app" Groups(47e173b6-c993-476e-af3f-013509428c78)
$ smartkey-client get-app-api-key --name "My app"
O522CZVDF5BwQHaG+hP3K/HH+uYLgEKoUDCCKOtVa7YFkluhkCZFwPK1wVnpz8lE5L+msHAHT6hLjAGKTB++kyOoT0kbG5TyiqUl1kZTnjhU4JkOAyLfdqcq2D8MsCWbYgjVOsgmMcPo4o28eNetQuzW+DnDyueHrH29e0
$ smartkey user-logout
User logged out

Creating a key using the app credentials:

$ smartkey-client app-login
Please enter your API Key: O522CZVDF5BwQHaG+hP3K/HH+uYLgEKoUDCCKOtVa7YFkluhkCZFwPK1wVnpz8lE5L+msHAHT6hLjAGKTB++kyOoT0kbG5TyiqUl1kZTnjhU4JkOAyLfdqcq2D8MsCWbYgjVOsgmMcPo4o28eNetQuzW+DnDyueHrH29e0
Successfully logged in
$ smartkey-client create-key --name "New key" --obj-type RSA --key-size 2048 --custom-metadata '{ "zone" : "West" }'
Created Key "New key"
$ smartkey-client import-key --name "Existing key" --in existing_key.key --obj-type RSA
Imported key "Existing key"
$ smartkey-client list-keys
3d9065b2-e847-4b9a-ba31-8b1f5545004a "New key" Created by smartkey-client 2048 RSA
7a0dc06a-0646-415a-8cf4-87576e14f940 "Existing key" Created by smartkey-client 2048 RSA
$ smartkey-client show-object --kid 3d9065b2-e847-4b9a-ba31-8b1f5545004a
id: 3d9065b2-e847-4b9a-ba31-8b1f5545004a
name: New key
description: Created by smartkey-client
type: RSA
key size: 2048
origin: FortanixHSM
operations: SIGN, VERIFY, ENCRYPT, DECRYPT, WRAPKEY, UNWRAPKEY, DERIVEKEY
custom metadata:
{
	"zone": "West"
} // end custom metadata
$ smartkey-client delete-key --kid 7a0dc06a-0646-415a-8cf4-87576e14f940
Deleted Key 7a0dc06a-0646-415a-8cf4-87576e14f940
$ smartkey app-logout
App logged out