CLI Reference - Encryption Keys

Encryption Keys

create-dfc-key

Creates a new DFC key

Usage

akeyless create-dfc-key
--name <Key name> \
--alg <Key type> \
--generate-self-signed-certificate <True/False> \
--certificate-ttl <Certificate TTL> \
--certificate-common-name <Certificate common name>

Parameters

Parameter	Description
`-n, --name`	(Mandatory) DFCKey name
`-a, --alg`	(Mandatory) DFCKey type; options: [AES128GCM, AES256GCM, AES128SIV, AES256SIV, AES128CBC, AES256CBC, RSA1024, RSA2048, RSA3072, RSA4096]
`--description`	DFC key description
`--generate-self-signed-certificate[=false]`	Whether to generate a self signed certificate with the key. If set, `--certificate-ttl` must be provided.
`--certificate-ttl`	TTL in days for the generated certificate. Required only for generate-self-signed-certificate.
`--certificate-common-name`	Common name for the generated certificate. Relevant only for generate-self-signed-certificate.
`--certificate-organization`	Organization name for the generated certificate. Relevant only for generate-self-signed-certificate.
`--certificate-country`	Country name for the generated certificate. Relevant only for generate-self-signed-certificate.
`--certificate-locality`	Locality for the generated certificate. Relevant only for generate-self-signed-certificate.
`--certificate-province`	Province name for the generated certificate. Relevant only for generate-self-signed-certificate.
`-t, --tag`	List of the tags attached to this DFC key. To specify multiple tags use the argument multiple times: -t Tag1 -t Tag2
`-s, --split-level[=2]`	The number of fragments that the item will be split into (not including customer fragment)
`-f, --customer-frg-id`	The customer fragment ID that will be used to create the DFC key (if empty, the key will be created independently of a customer fragment)
`--delete-protection`	Protection from accidental deletion of this item, [true/false]

create-classic-key

Creates a new Classic Key

Usage

akeyless create-classic-key \
--name <Key Name> \
--alg <Key type> \
--gateway-url <API Gateway URL:8000> \
--key-file-path <Path to file with the classic key value provided by user> \
--key-data <Base64-encoded classic key value provided by user> \
--cert <Path to a file that contain the certificate in a PEM format> \
--cert-file-data <PEM Certificate in a Base64 format> \
--delete-protection <Protection from accidental deletion of this item, [true/false]>

Parameters

Parameter	Description
`-n, --name`	(Mandatory) Classic key name/path.
`-a, --alg`	(Mandatory) Key type; options: `[AES128GCM, AES256GCM, AES128SIV, AES256SIV, RSA1024, RSA2048, RSA3072, RSA4096, EC256, EC384, GPG]`
`--gpg-alg`	Relevant only if GPG key type selected; options: [RSA1024, RSA2048, RSA3072, RSA4096, Ed25519]
`-u, --gateway-url[=http://localhost:8000]`	API Gateway URL (Configuration Management port)
`-p, --key-file-path`	Path to file with the classic key value provided by user
`--key-data`	Base64-encoded classic key value provided by user
`-c, --cert`	Path to a file that contain the certificate in a PEM format.
`--cert-file-data`	PEM Certificate in a Base64 format.
`--description`	Classic key description
`--generate-self-signed-certificate[=false]`	Whether to generate a self signed certificate with the key. If set, `--certificate-ttl` must be provided.
`--certificate-ttl`	TTL in days for the generated certificate. Required only for generate-self-signed-certificate.
`--certificate-common-name`	Common name for the generated certificate. Relevant only for generate-self-signed-certificate.
`--certificate-organization`	Organization name for the generated certificate. Relevant only for generate-self-signed-certificate.
`--certificate-country`	Country name for the generated certificate. Relevant only for generate-self-signed-certificate.
`--certificate-locality`	Locality for the generated certificate. Relevant only for generate-self-signed-certificate.
`--certificate-province`	Province name for the generated certificate. Relevant only for generate-self-signed-certificate.
`-t, --tag`	List of the tags attached to this secret. To specify multiple tags use argument multiple times: -t Tag1 -t Tag2
`-k, --protection-key-name`	The name of the key that protects the classic key value (if empty, the account default key will be used)
`--delete-protection`	Protection from accidental deletion of this item, [true/false]

export-classic-key

Returns the Classic Key material

Please note: mandatory values for this command: -n, --name

Usage

akeyless export-classic-key \
--name <Key name> \
--version <Key version> \
--gateway-url <API Gateway URL:8000>

Parameters

Parameter	Describrion
`-n, --name`	(Mandatory) Classic key name
`-v, --version`	Classic key version
`--export-public-key[=false]`	Export only the public key
`-u, --gateway-url[=http://localhost:8000]`	API Gateway URL (Configuration Management port)
`--ignore-cache[=false]`	Retrieve the Secret value without checking the Gateway's cache. This flag is only relevant when using the RestAPI

rotate-key

Rotates an existing key, by creating a new version of the key.

Usage

akeyless rotate-key \
--name <Key name> \
--gateway-url <API Gateway URL:8000> \ 
--new-key-data <The new value of the key, base64 encoded>

Parameters

Parameter	Description
`-n, --name`	(Mandatory) Key name
`-u, --gateway-url[=http://localhost:8000]`	API Gateway URL (Configuration Management port). Relevant only for Classic Key.
`--new-key-data`	The new value of the key, base64 encoded. Relevant only for Classic Key provided by the user (BYOK).

refresh-key

Refresh a key

Usage

akeyless refresh-key --name <Key name>

Parameters

Parameter	Description
`-n, --name`	(Mandatory) Key name

assoc-target-item

Create an association between a Target and a Classic Key for External KMS Integration

Usage

akeyless assoc-target-item \
--target-name <Target to associate> \
--name <Item to associate> \
--vault-name <Name of the vault used> \
--key-operations <A list of allowed operations for the key> \
--project-id <Project id of the GCP KMS> \
--location-id <Location id of the GCP KMS> \
--keyring-name <Keyring name of the GCP KMS> \
--purpose <Purpose if the key in GCP KMS>

Parameters

Parameter	Description
`-t, --target-name`	(Mandatory) The target to associate
`-n, --name`	(Mandatory) The item to associate
`--vault-name`	Name of the vault used. (Relevant only for Classic Key and target association. Required for azure targets)
`--key-operations`	A list of allowed operations for the key. (Relevant only for Classic Key and target association. Required for azure targets)
`--project-id`	Project id of the GCP KMS. (Relevant only for Classic Key and target association. Required for gcp targets)
`--location-id`	Location id of the GCP KMS. (Relevant only for Classic Key and target association. Required for gcp targets)
`--keyring-name`	Keyring name of the GCP KMS. (Relevant only for Classic Key and target association. Required for gcp targets)
`--purpose`	Purpose if the key in GCP KMS. (Relevant only for Classic Key and target association. Required for gcp targets)
`--kms-algorithm`	Algorithm of the key in GCP KMS. (Relevant only for Classic Key and target association, Required for gcp targets)
`--tenant-secret-type`	Set to 'true' to create a multi-region managed key. (Relevant only for Classic Key AWS targets)
`--multi-region[=false]`	The list of regions in which to create a copy of the key. (Relevant only for Classic Key AWS targets). To specify multiple regions use argument multiple times: --regions us-east-1 --regions us-west-1

get-rsa-public

Obtain the public key from a specific RSA private key

Usage

akeyless get-rsa-public --name <Key name>

Parameters

Parameter	Description
`-n, --name`	(Mandatory) Name of RSA key to extract the public key from

upload-pkcs12

Upload a PKCS#12 key and certificates

Usage

akeyless upload-pkcs12 \
--name <Key name> \
--in <Input file (private key and certificate only>  \
--passphrase <Passphrase> \
--description <Key description>

Parameters

Parameter	Description
`-n, --name`	(Mandatory) Name of key to be created
`-i, --in`	(Mandatory) PKCS#12 input file (private key and certificate only)
`-p, --passphrase`	(Mandatory) Passphrase to unlock the pkcs#12 bundle
`--description`	Key description
`-t, --tag`	List of the tags attached to this key. To specify multiple tags use argument multiple times: -t Tag1 -t Tag2
`-s, --split-level[=2]`	The number of fragments that the item will be split into
`-f, --customer-frg-id`	The customer fragment ID that will be used to split the key (if empty, the key will be created independently of a customer fragment)
`-c, --cert`	Path to a file that contain the certificate in a PEM format. If this parameter is not empty, the certificate will be taken from here and not from the PKCS#12 input file
`--delete-protection[=false]`	Protection from accidental deletion of this item, [true/false]

upload-rsa

Upload RSA key

Usage

akeyless upload-rsa \
--name <Key Name> \
--alg <Key type> \
--rsa-key-file-path <RSA private key file path> \
--rsa-key-data <RSA private key data, base64 encoded> \
--cert <Certificate in a PEM format> \
--cert-file-data <PEM Certificate in a Base64 format>

Parameters

Parameter	Description
`-n, --name`	(Mandatory) Name of key to be created
`-a, --alg`	(Mandatory) Key type. options: [RSA1024, RSA2048, RSA3072, RSA4096]
`-p, --rsa-key-file-path`	RSA private key file path.
`--rsa-key-data`	RSA private key data, base64 encoded
`-c, --cert`	Path to a file that contain the certificate in a PEM format
`--cert-file-data`	PEM Certificate in a Base64 format
`--description`	Key description
`-t, --tag`	List of the tags attached to this key. To specify multiple tags use argument multiple times: -t Tag1 -t Tag2
`-s, --split-level[=2]`	The number of fragments that the item will be split into
`-f, --customer-frg-id`	The customer fragment ID that will be used to split the key (if empty, the key will be created independently of a customer fragment)
`--overwrite[=false]`	When the overwrite flag is set, this command will only update an existing key. [true, false]
`--delete-protection`	Protection from accidental deletion of this item, [true/false]

update-rotation-settings

Updates rotation settings of an existing key

Usage

akeyless update-rotation-settings \
--name <Key name> \
--auto-rotate <True/False>

Parameters

Parameter	Description
`-n, --name`	(Mandatory) Key name
`-r, --auto-rotate[=false]`	(Mandatory) [true/false] Sets automatic rotation to be enabled or disabled, if enabled rotation will be triggered periodically based on --rotation-interval
`--rotation-interval`	The number of days to wait between every automatic key rotation (7-365)

encrypt

Encrypts plaintext into ciphertext by using an AES key

Usage

akeyless encrypt \
--key-name <Key name> \
--display-id <Display id of the key to use in the encryption process \
--item-id <Item id of the key to use in the encryption process> \
--in <Path to the file to be encrypted in base64 format>

Parameters

Parameter	Description
`-k, --key-name`	The name of the key to use in the encryption process
`-d, --display-id`	The display id of the key to use in the encryption process
`-I, --item-id`	The item id of the key to use in the encryption process
`-i, --in`	Path to the file to be encrypted in base64 format
`-o, --out`	Path to the output file. If not provided, the output will be printed as base64
`-p, --plaintext`	Data to be encrypted, if a file was not provided
`-X, --encryption-context`	name-value pair that specifies the encryption context to be used for authenticated encryption. If used here, the same value must be supplied to the decrypt command or decryption will fail
`-F, --input-format`	If specified, the plaintext input is assumed to be formatted accordingly. Current supported options: [base64]

encrypt-file

Encrypts a file by using an AES key

Usage

akeyless encrypt-file \
--key-name <Key Name> \
--in <File to be encrypted> \ 
--out <Output file> \
--display-id <Display id of the key>

Parameters

Parameter	Description
`-k, --key-name`	(Mandatory) The name of the key to use in the encryption process
`-d, --display-id`	The display id of the key to use in the encryption process
`-I, --item-id`	The item id of the key to use in the encryption process
`-i, --in`	(Mandatory) Path to the file to be encrypted. If not provided, the content will be taken from stdin
`-o, --out`	(Mandatory) Path to the output file. If not provided, the output will be sent to stdout
`-F, --output-format[=base64]`	The output will be formatted accordingly. options: [base64, raw]
`-X, --encryption-context`	name-value pair that specifies the encryption context to be used for authenticated encryption. If used here, the same value must be supplied to the decrypt command or decryption will fail

encrypt-pkcs1

Encrypts the given message with RSA and the padding scheme from PKCS#1 v1.5

Usage

akeyless encrypt-pkcs1 \
--key-name <key Name> \
--plaintext <Data to encrypt> \
--display-id <Display id of the key> \
--item-id <Item id of the key>

Parameters

Parameter	Description
`-k, --key-name`	(Mandatory)The name of the key to use in the encryption process
`-d, --display-id`	The display id of the key to use in the encryption process
`-I, --item-id`	The item id of the key to use in the encryption process
`-p, --plaintext`	(Mandatory) Data to be encrypted
`--profile, --token`	Use a specific profile (located at $HOME/.akeyless/profiles) or a temp access token
`--uid-token`	The universal identity token, Required only for universal_identity authentication

encrypt-gpg

Encrypts the given message with GPG using an RSA key

Usage

akeyless encrypt-gpg \
--key-name <Key name> \
--display-id <Display id of the key> \
--item-id <Item id of the key> \
--in <Path to the file to be encrypted in base64 format>

Parameters

Parameter	Description
`-k, --key-name`	(Mandatory) The name of the key to use in the encryption process
`-d, --display-id`	The display id of the key to use in the encryption process
`-I, --item-id`	The item id of the key to use in the encryption process
`-i, --in`	Path to the file to be encrypted in base64 format
`-o, --out`	Path to the output file. If not provided, the output will be printed as base64
`-p, --plaintext`	Data to be encrypted, if a file was not provided
`-F, --input-format`	If specified, the plaintext input is assumed to be formatted accordingly. Current supported options: [base64]

decrypt

Decrypts ciphertext into plaintext by using an AES key

Usage

akeyless decrypt \
--key-name <Key Name> \
--display-id <Display id of the key> \
--item-id <Item id of the key>

Parameters

Parameter	Description
`-k, --key-name`	(Mandatory) The name of the key to use in the decryption process.
`-d, --display-id`	The display id of the key to use in the decryption process
`-I, --item-id`	The item id of the key to use in the decryption process
`-i, --in`	Path to the file to be decrypted (base64 encoded)
`-o, --out`	Path to the output file. If not provided, the output will be printed as text.
`-c, --ciphertext`	Ciphertext to be decrypted in base64 encoded format, if a file was not provided
`-X, --encryption-context`	The encryption context. If this was specified in the encrypt command, it must be specified here or the decryption operation will fail
`-F, --output-format`	If specified, the output will be formatted accordingly. options: [base64]

decrypt-file

Decrypts a file by using an AES key

Usage

akeyless decrypt-file \
--key-name <key name> \
--in <file to decrypt> \
--out <Path to the output file> \
--display-id <Display id of the key to use in the decryption process> \ 
--item-id <Item id of the key to use in the encryption process>

Parameters

Parameter	Description
`--key-name`	(Mandatory) The name of the key to use in the decryption process
`-d, --display-id`	The display id of the key to use in the decryption process
`-I, --item-id`	The item id of the key to use in the decryption process
`-i, --in`	Path to the file to be decrypted. If not provided, the content will be taken from stdin
`-o, --out`	Path to the output file. If not provided, the output will be sent to stdout
`-F, --output-format[=base64]`	The output will be formatted accordingly. options: [base64, raw]
`-X, --encryption-context`	The encryption context. If this was specified in the encrypt command, it must be specified here or the decryption operation will fail

decrypt-pkcs1

Decrypts a plaintext using RSA and the padding scheme from PKCS#1 v1.5

Usage

akeyless decrypt-pkcs1 \
--key-name <Key Name> \
--ciphertext <Ciphertxt to decrypt> \
--display-id <Display id of the key> \ 
--item-id <Item id of the key>

Parameters

Parameter	Description
`-k, --key-name`	(Mandatory) The name of the key to use in the decryption process
`-d, --display-id`	The display id of the key to use in the decryption process
`-I, --item-id`	The item id of the key to use in the decryption process
`-c, --ciphertext`	(Mandatory) Ciphertext to be decrypted in base64 encoded format
`-F, --output-format`	If specified, the output will be formatted accordingly. options: [base64]

decrypt-gpg

Decrypts the given GPG message using an RSA key

Usage

akeyless decrypt-gpg \
--key-name <Key Name> \
--display-id <Display id of the key> \
--item-id <Item id of the key>

Parameters

Parameter	Description
`-k, --key-name`	(Mandatory) The name of the key to use in the decryption process.
`-d, --display-id`	The display id of the key to use in the decryption process
`-I, --item-id`	The item id of the key to use in the decryption process
`-i, --in`	Path to the file to be decrypted (base64 encoded)
`-o, --out`	Path to the output file. If not provided, the output will be printed as text.
`-c, --ciphertext`	Ciphertext to be decrypted in base64 encoded format, if a file was not provided
`-p, --passphrase`	Passphrase to decrypt the message
`-F, --output-format`	If specified, the output will be formatted accordingly. options: [base64]

sign-pkcs1

Calculates the signature of hashed using RSASSA-PKCS1-V1_5-SIGN from RSA PKCS#1 v1.5

Usage

akeyless sign-pkcs1 \
--key-name <RSA key > \
--message <Message to sign> \
--display-id <Display id of the key> \
--item-id <Item id of the key>

Parameters

Parameter	Description
`-k, --key-name`	(Mandatory) The name of the RSA key to use in the signing process
`-d, --display-id`	The display id of the key to use in the signing process
`-I, --item-id`	The item id of the key to use in the signing process
`-m, --message`	(Mandatory) The message to be signed
`--profile, --token`	Use a specific profile (located at $HOME/.akeyless/profiles) or a temp access token
`--uid-token`	The universal identity token, Required only for universal_identity authentication

verify-pkcs1

Verifies an RSA PKCS#1 v1.5 signature

Usage

akeyless verify-pkcs1 \
--key-name <RSA Key> \
--message <message to verify> \
--signature <message signature> \ 
--display-id <Display id of the key> \ 
--item-id <Item id of the key>

Parameters

Parameter	Description
`-k, --key-name`	(Mandatory) The name of the RSA key to use in the verification process
`-d, --display-id`	The display id of the key to use in the verification process
`-I, --item-id`	The item id of the key to use in the verification process
`-m, --message`	(Mandatory) The message to be verified.
`-s, --signature`	(Mandatory) The message's signature.

sign-gpg

Calculates the signature of a message using GPG from an RSA key

Usage

akeyless sign-gpg \
--key-name <RSA key> \
--message <Message to sign> \
--display-id <Display id of the key> \
--item-id <Item id of the key>

Parameters

Parameter	Description
`-k, --key-name`	(Mandatory) The name of the RSA key to use in the signing process
`-d, --display-id`	The display id of the key to use in the signing process
`-I, --item-id`	The item id of the key to use in the signing process
`-m, --message`	(Mandatory) The message to be signed
`-p, --passphrase`	Passphrase to decrypt the message

verify-gpg

Verifies a GPG based on RSA signature

Usage

akeyless verify-gpg \
--key-name <RSA Key> \
--signature <message signature> \ 
--message <message to verify> \
--display-id <Display id of the key> \ 
--item-id <Item id of the key>

Parameters

Parameter	Description
`-k, --key-name`	The name of the RSA key to use in the verification process
`-d, --display-id`	The display id of the key to use in the verification process
`-I, --item-id`	The item id of the key to use in the verification process
`-m, --message`	(Mandatory) The message to be verified.
`-s, --signature`	(Mandatory) The message's signature.
`-p, --passphrase`	Passphrase to decrypt the message

hmac

Generates a hash-based message authentication code (HMAC) for a message, using an HMAC algorithm

Usage

akeyless hmac \
--key-name <Key name> \
--display-id <Display id of the key> \ 
--item-id <Item id of the key>

Parameters

Parameter	Description
`-k, --key-name`	(Mandatory) The name of the key to use in the encryption process
`-d, --display-id`	The display id of the key to use in the encryption process
`-I, --item-id`	The item id of the key to use in the encryption process
`-i, --in`	Path to the input file
`-o, --out`	Path to the output file. If not provided, the output will be printed as base64
`-p, --plaintext`	Data to perform hmac on, if a file was not provided
`-f, --hash-function[=sha-256]`	Hash function [sha-256,sha-512]
`-F, --input-format`	Select the default assumed format for any plaintext input. Currently supported options: [base64]

gen-customer-fragment

Generates Customer Fragment

Usage

akeyless gen-customer-fragment --name <CF-Name> --description <Customer Fragment Description>

gateway-download-customer-fragments

Download gateway customer fragments

Usage

akeyless gateway-download-customer-fragments \
--file-folder <path to download to> \
--gateway-url <API Gateway URL:8000>

set-item-state

Set an item's state (Enabled, Disabled)

Usage

akeyless set-item-state \
--name <Item name> \
--desired-state [Enabled, Disabled]

Parameters

Parameter	Description
`-n, --name`	(Mandatory) Current item name.
`-s, --desired-state`	(Mandatory) Desired item state [Enabled, Disabled]
`--version[=0]`	The specific version you want to update: 0=item level state (default)

Tokenization

create-tokenizer

Creates a new tokenizer

Usage

akeyless create-tokenizer \
--name <Tokenizer name> \
--tokenizer-type <Tokenizer type> \
--template-type <SSN,CreditCard,USPhoneNumber,Custom> \
--tweak-type <Supplied, Generated, Internal, Masking>

akeyless create-tokenizer \
--name *<Tokenizer name> \
--tokenizer-type *<vaultless> \
--template-type *<SSN,CreditCard,USPhoneNumber,Custom> \
--tweak-type <Supplied, Generated, Internal, Masking> \
--alphabet <Symbols to use for tokenization> \
--pattern <A regexp pattern to extract tokenized parts> \
--encoding-template <An expression to alter the template of the encryption output> \
--decoding-template <An expression to alter the template of the decryption output>

Parameters

Parameter	Description
`-n, --name`	(Mandatory) Tokenizer name
`-y, --tokenizer-type[=vaultless]`	(Mandatory) Tokenizer type(vaultless)
`-T, --template-type`	(Mandatory) Which template type this tokenizer is used for [SSN,CreditCard,USPhoneNumber,Custom]
`--encryption-key-name`	AES key name to use in vaultless tokenization
`--tweak-type`	The tweak type to use in vaultless tokenization [Supplied, Generated, Internal, Masking]
`--alphabet`	Alphabet to use in custom vaultless tokenization, such as '0123456789' for credit cards.
`--pattern`	Pattern to use in custom vaultless tokenization
`--encoding-template`	The Encoding output template to use in custom vaultless tokenization
`--decoding-template`	The Decoding output template to use in custom vaultless tokenization
`--description`	Tokenizer description
`--tag`	List of the tags attached to this key. To specify multiple tags use argument multiple times: --tag Tag1 --tag Tag2
`--delete-protection`	Protection from accidental deletion of this item, [true/false]

tokenize

Encrypts text with a tokenizer.

Please note: mandatory values for this command: -n, --tokenizer-name , -p, --plaintext

Usage

akeyless tokenize \
--tokenizer-name <Tokenizer name> \
--plaintext <Data to be encrypted> \
--tweak <Base64-encoded tweak value

Parameters

Parameter	Description
`-n, --tokenizer-name`	(Mandatory) The name of the tokenizer to use in the encryption process
`-p, --plaintext`	(Mandatory) Data to be encrypted
`--tweak`	Base64 encoded tweak for vaultless encryption

detokenize

Decrypts text with a tokenizer

Usage

akeyless detokenize \
--tokenizer-name <Tokenizer name> \
--ciphertext <Data to be decrypted> \
--tweak <Base64-encoded tweak value that was used for encryption>

Parameters

Parameter	Description
`-n, --tokenizer-name`	(Mandatory) The name of the tokenizer to use in the decryption process
`-c, --ciphertext`	(Mandatory) Data to be decrypted
`--tweak`	Base64 encoded tweak for vaultless encryption