Clients: Command-Line Interface (CLI) for Fortanix Data Security Manager

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   SDKMS 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)

Supported Features

OPERATIONS ALGORITHM KEY SIZE, CURVE, OR MODE
Create or Import

Supported algorithms for importing a key:

  • AES, DES, DES3 as HEX
  • EC, RSA as PEM
  • Cert
  • Pfx
  • Secret

Supported key sizes or curves:

  • AES - 128,192, or 256 bits
  • DES - 56 bits
  • DES3 - 168 bits
  • RSA - between 1024 and 8192 bits
  • EC - SecP192K1, SecP224K1, SecP256K1, NistP192, NistP224, NistP256, NistP384, NistP521

Encrypt or Decrypt,

Batch Encrypt or Batch Decrypt

  • AES, DES, RSA

Supported modes:

  • AES - CBC, CBC (no padding), CFB, CTR, GCM, GCM (no padding), CCM, OFB, KW, KWP, FF1
  • DES, DES3 - ECB, CBC, CBC (no padding)
  • RSA - OAEP_MGF1_SHA224, OAEP_MGF1_SHA384, OAEP_MGF1_SHA512, OAEP_MGF1_SHA1, OAEP_MGF1_SHA256, PKCS1_V15

Sign or Verify

Batch Sign or Batch Verify

  • EC, RSA

Supported modes:

  • RSA - PKCS#1 v1.5, OAEP, OAEPPADDING, PSS
    • With hash algorithms (sign/verify): SHA-1, RIPEMD-160, SHA-224, SHA-256, SHA-384, SHA-512, SSL3
    • Supported mask generation functions: MGF1 with SHA-1, RIPEMD-160, SHA-224, SHA-256, SHA-384, SHA-512.
Multipart Encrypt or Multipart Decrypt
  • AES

Supported modes:

CBC, CBCNOPAD, CTR, and GCM

Key Rotation or Revoke Key
  • AES, DES, DES3, RSA, EC, ARIA, DSA, SEED, KCDSA, EC-KCDSA, LMS

Supported key sizes or curves:

  • AES and ARIA - 128,192, or 256 bits
  • DES - 56 bits
  • DES3 - 168 bits
  • RSA - between 1024 and 8192 bits
  • EC - SecP192K1, SecP224K1, SecP256K1, NistP192, NistP224, NistP256, NistP384, NistP521
  • EC-KCDSA - NIST P-192, NIST P-224, NIST P-256, NIST P-384, NIST P-521, SecP192K1, SecP224K1, SecP256K1
  • LMS - SHA-256 M32 H5/H10/H15/H20/H25
  • SEED - 128 bits
Message Digest  

Supported hash algorithms:

SHA1, SHA256, SHA384, and SHA512

Wrap Key
  • AES, DES, HMAC, RSA, EC, ARIA, SEED

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
  • AES, DES, DES3, HMAC, ARIA, SEED

Supported key sizes or curves:

  • AES and ARIA - 128,192, or 256 bits
  • DES - 56 bits
  • DES3 - 168 bits
  • HMAC - between 1024 and 8192 bits
  • SEED - 128 bits
Agree Key
  • AES, EC

Supported key sizes or curves:

  • AES - 128,192, or 256 bits
  • EC - SecP192K1, SecP224K1, SecP256K1, NistP192, NistP224, NistP256, NistP384, NistP521
Export Key
  • AES, DES, DES3, RSA, EC, ARIA, DSA, SEED, KCDSA, EC-KCDSA, LMS

Supported key sizes or curves:

  • AES and ARIA - 128,192, or 256 bits
  • DES - 56 bits
  • DES3 - 168 bits
  • HMAC - between 1024 and 8192 bits
  • RSA - between 1024 and 8192 bits
  • EC - SecP192K1, SecP224K1, SecP256K1, NistP192, NistP224, NistP256, NistP384, NistP521
  • EC-KCDSA - NIST P-192, NIST P-224, NIST P-256, NIST P-384, NIST P-521, SecP192K1, SecP224K1, SecP256K1
  • LMS - SHA-256 M32 H5/H10/H15/H20/H25
  • SEED - 128 bits

Download

Check out the Downloads section for more details on downloads and installation.

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=<sdkms-server-url>or provide the server URL on the command line using the --api-endpoint option.

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: user@example.com
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

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.

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

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 stderr

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://sdkms.fortanix.com
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,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

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 SDKMS

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 sdkms update plugin

delete-plugin
Invoke sdkms delete plugin

create-plugin
Invoke sdkms update plugin

server-version
Check sdkms server version

server-health
Check sdkms 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

 

Comments

Please sign in to leave a comment.

Was this article helpful?
0 out of 0 found this helpful