1.0 Introduction
sdkms-cli is a cross-platform Fortanix-Data-Security-Manager (DSM) client command-line utility written in Python.
NOTE
For all the commands listed in this article, use the "help" argument [
-h] to know the syntax and the optional arguments of the command.
For example:$ sdkms-cli user-login -h usage: sdkms-cli user-login [-h] [--username USERNAME] optional arguments: -h, --help show this help message and exit --username USERNAME DSM username to log in with --account-name ACCOUNT_NAME Account name or account UUID to use for user actions (only necessary if the user has more than one account)
2.0 Operating System (OS) Compatibility Matrix
For details on the Command-Line Interface (CLI) client OS compatibility matrix, refer to Clients: Compatibility Matrix.
3.0 Supported Features
OPERATIONS | ALGORITHM | KEY SIZE, CURVE, OR MODE |
|---|---|---|
Create or Import | Supported algorithms for importing a key:
| Supported key sizes or curves:
|
Encrypt or Decrypt, Batch Encrypt or Batch Decrypt |
| Supported modes:
|
Sign or Verify Batch Sign or Batch Verify |
| Supported modes:
|
Multipart Encrypt or Multipart Decrypt |
| Supported modes: CBC, CBCNOPAD, CTR, and GCM |
Key Rotation or Revoke Key |
| Supported key sizes or curves:
|
Message Digest |
| Supported hash algorithms: SHA1, SHA256, SHA384, and SHA512 |
Wrap Key |
| Symmetric keys, HMAC keys, opaque objects, and secret objects may be wrapped with symmetric or asymmetric keys. Asymmetric keys may be wrapped with symmetric keys. But wrapping an asymmetric key with another asymmetric key is not supported. |
Derive Key |
| Supported key sizes or curves:
|
Agree Key |
| Supported key sizes or curves:
|
Export Key |
| Supported key sizes or curves:
|
4.0 Download
Check out the Downloads section for more details on downloads and installation.
5.0 API Endpoint
By default, sdkms-cli makes REST API calls to the Fortanix DSM server at https://apps.smartkey.io. To make calls to a different Fortanix DSM server, either set the environment variable FORTANIX_API_ENDPOINT, For example: FORTANIX_API_ENDPOINT=<dsm-server-url>or provide the server URL on the command line using the --api-endpoint option.
6.0 Authentication
The Fortanix DSM Server supports two types of authentication: user authentication and application authentication. A user is authenticated with a password, followed by Two Factor Authentication. Applications are authenticated with an API Key or with a certificate.
Each action performed in Fortanix DSM requires some form of authorization. Encrypting or decrypting data is performed with application credentials. Creating new groups, creating applications, and changing group membership is done with user credentials. Creating new security objects is performed with either user credentials or application credentials.
The sdkms-cli 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.
sdkms-cli user-login authenticates a user account using its Fortanix DSM username and password.
sdkms-cli app-login authenticates an application with an API key.
In both cases, persistent session information is stored in a hidden file .token in the current directory.
sdkms-cli logout logs out of the Fortanix DSM server and clears .token. You may also use sdkms-cli user-logout or sdkms-cli app-logout to log out of just the current user session or just the current application session.
For example,
$ sdkms-cli user-login
Please enter your Fortanix DSM username: [email protected]
Fortanix DSM Password:
Successfully logged in
$ sdkms-cli list-apps
bf105894-f004-4c75-b4ba-f51168674355 test app This is a test application Groups(5893a573-ed9c-4e38-a3bc-ad72a1820bc1)
$ sdkms-cli app-login
Please enter your API Key: <paste a Fortanix DSM KMS API Key>
Successfully logged in
$ sdkms-cli logout
User logged out
App logged out
7.0 Importing Keys and Certificates
sdkms-cli import-key expect keys in PEM format or Base64 values. It can also accept DER format with this flag --der.
sdkms-cli import-cert expect certificates to be in PEM format only.
8.0 Examples
Creating an app to use with Fortanix DSM:
$ sdkms-cli user-login
Please enter your Fortanix DSM username:
Fortanix DSM Password:
Successfully logged in
$ sdkms-cli create-group --name "My group" --description "Test group"
47e173b6-c993-476e-af3f-013509428c78
$ sdkms-cli list-groups
47e173b6-c993-476e-af3f-013509428c78 "My group" "Test group" 7bbb7a0b-de6b-4311-a7fa-053de7eabced
$ sdkms-cli create-app --name "My app" --description "Test app" --groups 47e173b6-c993-476e-af3f-013509428c78
2b9a6296-3ed7-47a6-8ab2-5ddf92935f6e
$ sdkms-cli list-apps
2b9a6296-3ed7-47a6-8ab2-5ddf92935f6e "My app" "Test app" Groups(47e173b6-c993-476e-af3f-013509428c78)
$ sdkms-cli get-app-api-key --name "My app"
O522CZVDF5BwQHaG+hP3K/HH+uYLgEKoUD................................HAHT6hLjAGKTB++kyOoT0kbG5TyiqUl1kZTnjhU4JkOAyLfdqcq2D8MsCWbYgjVOsgmMcPo4o28eNetQuzW+DnDyueHrH29e0
$ sdkms user-logout
User logged out
Creating a key using the app credentials:
$ sdkms-cli app-login
Please enter your API Key: O522CZVDF5BwQHaG+hP3K/HH+uYLgEKoU............................6hLjAGKTB++kyOoT0kbG5TyiqUl1kZTnjhU4JkOAyLfdqcq2D8MsCWbYgjVOsgmMcPo4o28eNetQuzW+DnDyueHrH29e0
Successfully logged in
$ sdkms-cli create-key --name "New key" --obj-type RSA --key-size 2048 --custom-metadata '{ "zone" : "West" }'
Created Key "New key"
$ sdkms-cli import-key --name "Existing key" --in existing_key.key --obj-type RSA
Imported key "Existing key"
$ sdkms-cli list-keys
3d9065b2-e847-4b9a-ba31-8b1f5545004a "New key" Created by sdkms-client 2048 RSA
7a0dc06a-0646-415a-8cf4-87576e14f940 "Existing key" Created by sdkms-client 2048 RSA
$ sdkms-cli show-object --kid 3d9065b2-e847-4b9a-ba31-8b1f5545004a
id: 3d9065b2-e847-4b9a-ba31-8b1f5545004a
name: New key
description: Created by sdkms-client
type: RSA
key size: 2048
origin: FortanixHSM
operations: SIGN, VERIFY, ENCRYPT, DECRYPT, WRAPKEY, UNWRAPKEY, DERIVEKEY
custom metadata:
{
"zone": "West"
} // end custom metadata
$ sdkms-cli delete-key --kid 7a0dc06a-0646-415a-8cf4-87576e14f940
Deleted Key 7a0dc06a-0646-415a-8cf4-87576e14f940
$ sdkms app-logout
App logged out
9.0 Log Management
The sdkms-cli allows to maintain audit logs using the audit-log parameter.
usage: sdkms-cli audit-log [-h] --account-id ACCOUNT_ID --days DAYS
[--batch-size BATCH_SIZE]
optional arguments:
-h, --help show this help message and exit
--account-id ACCOUNT_ID
account id of an account
--days DAYS No. of days
--batch-size BATCH_SIZE
Batch size for audit-log
Output:
Write audit-log data in output file
Exit Status:
Zero on success and 1 on error. Error message is printed on stderr10.0 Fortanix Data Security Manager CLI Manual
NAME
sdkms-cli - manual page for sdkms-cli 3.20.1363
DESCRIPTION
usage: sdkms-cli [-h] [--version] [--api-endpoint API_ENDPOINT] [--no-verify-ssl]
[--ssl-ca-cert SSL_CA_CERT] [--debug-http] [--debug-errors]
[--prefer-user-auth] [--prefer-app-auth] [--proxy PROXY]
CMD
The following environment variables may be set to control application behavior:
FORTANIX_API_ENDPOINT: The Fortanix DSM server instance to talk to.
Defaultvalue is https://
FORTANIX_API_KEY*: The API key of the application to use for application authenticated operations.
Variables marked with * contain security-sensitive information and are intended for use in testing and development.
They should not be used in secure deployments.
Optional arguments:
-h, --help
show this help message and exit
--version
show program's version number and exit
--api-endpoint API_ENDPOINT
Fortanix DSM API endpoint to connect to
--no-verify-ssl
Do not verify server certificate
--ssl-ca-cert SSL_CA_CERT
Path to CA certificate for SSL verification
--debug-http
Turn on verbose HTTP request debugging
--debug-errors
Turn on more verbose error output
--prefer-user-auth
Prefer using user authentication for APIs that accept both
--prefer-app-auth
Prefer using app authentication for APIs that accept both
--proxy PROXY
URL of the proxy to be used
CMD:
{app-login,user-login,app-logout,user-logout,select-account,logout,rotate-key,create-key,
persist-key,import-key,import-cert,import-secret,rotate-secret,update-object,delete-key,list-keys,list-objects,
show-sobject,export-object,activate-object,revoke-object,encrypt,encrypt-init,encrypt-update,
encrypt-final,decrypt-init,decrypt-update,decrypt-final,decrypt,wrap-key,unwrap-key,derive-key,
list-accounts,list-apps,create-app,get-app-api-key,regenerate-app-api-key,delete-app,list-groups,
create-group,delete-group,sign,batch-sign,batch-encrypt,batch-decrypt,batch-verify,verify,
message-digest,hmac-digest,hmac-verify,agree-key,invoke-plugin,update-plugin,delete-plugin,
create-plugin,server-version,server-health,app-certificate-login,show-app,show-group,show-user,
show-account,task-result}
app-login
Log in to Fortanix DSM with an application API key for performing crypto operations and key management
user-login
Log in to Fortanix DSM with a username and password for performing crypto operations and key management
app-logout
Log out of application credentials
user-logout
Log out of user credentials
select-account
Switch to another account
logout
Log out of both application and user credentials
rotate-key
Rotate a key
create-key
Create a key
persist-key
Persist a transient key
import-key
Import a key into Fortanix DSM
import-cert
Import a certificate
import-secret
Import a secret into Fortanix DSM
rotate-secret
Rotate a secret in Fortanix DSM
update-object
Update metadata of a security object
delete-key
Delete a key
list-keys
List keys
list-objects
List objects (keys, certificates, and other opaque objects)
show-sobject
Show details about a Security Object
export-object
Show value of a Security Object.
This works only if the object is marked exportable.
activate-object
Activate a Security Object.
This works only if the object is in Preactive state.
revoke-object
Revoke a Security Object.
encrypt
Encrypt with key
encrypt-init
Multipart encryption initialization
encrypt-update
Multipart encryption update
encrypt-final
Multipart encryption final
decrypt-init
Multipart decryption initialization
decrypt-update
Multipart decryption update
decrypt-final
Multipart encryption final
decrypt
Decrypt with key
wrap-key
Wrap a key with another key
unwrap-key
Unwrap a key that has been wrapped with another key
derive-key
Derive a new key from existing (base) key.
list-accounts
List associated accounts
list-apps
List Applications in Fortanix DSM
create-app
Create a new Application in Fortanix DSM
get-app-api-key
Get the API key for an Application.
Specify the application with --name or --app-id (but not both)
regenerate-app-api-key
Reset the API key for an Application. This will invalidate any previous API keys.
Specify the application with --name or --app-id (but not both)
delete-app
Delete an Application. The Application to be deleted may be specified by name or by app id.
If both name and app id are provided, the Application will only be deleted if both name and app id match
list-groups
List groups in DSM
create-group
Create a new security group
delete-group
Delete a security group.
sign
Signature generation with RSA and EC keys
batch-sign
Signature generation with RSA and EC keys in batch
batch-encrypt
Encryption in batch
batch-decrypt
Decryption in batch
batch-verify
Signature verification with RSA and EC keys in batch
verify
Signature verification with RSA and EC keys
message-digest
Message Digest
hmac-digest
Compute HMAC digest. Computed digest is hex encoded
hmac-verify
Verify HMAC digest
agree-key
Agree key
invoke-plugin
Invoke Fortanix DSM plugin
update-plugin
Invoke DSM update plugin
delete-plugin
Invoke DSM delete plugin
create-plugin
Invoke DSM update plugin
server-version
Check DSM server version
server-health
Check DSM server health
app-certificate-login
Log in to Fortanix Fortanix DSM with a certificate for performing account tasks
show-app
Display app properties
show-group
Display group properties
show-user
Display user properties
show-account
Display account properties
task-result
Display result of an approval task