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
ParameterDescription
-n, --name(Mandatory) DFCKey name
-a, --alg(Mandatory) DFCKey type; options: [AES128GCM, AES256GCM, AES128SIV, AES256SIV, AES128CBC, AES256CBC, RSA1024, RSA2048, RSA3072, RSA4096]
--descriptionDFC 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-ttlTTL in days for the generated certificate. Required only for generate-self-signed-certificate.
--certificate-common-nameCommon name for the generated certificate. Relevant only for generate-self-signed-certificate.
--certificate-organizationOrganization name for the generated certificate. Relevant only for generate-self-signed-certificate.
--certificate-countryCountry name for the generated certificate. Relevant only for generate-self-signed-certificate.
--certificate-localityLocality for the generated certificate. Relevant only for generate-self-signed-certificate.
--certificate-provinceProvince name for the generated certificate. Relevant only for generate-self-signed-certificate.
-t, --tagList 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-idThe 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-protectionProtection 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
ParameterDescription
-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-algRelevant 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-dataBase64-encoded classic key value provided by user
-c, --certPath to a file that contain the certificate in a PEM format.
--cert-file-dataPEM Certificate in a Base64 format.
--descriptionClassic 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-ttlTTL in days for the generated certificate. Required only for generate-self-signed-certificate.
--certificate-common-nameCommon name for the generated certificate. Relevant only for generate-self-signed-certificate.
--certificate-organizationOrganization name for the generated certificate. Relevant only for generate-self-signed-certificate.
--certificate-countryCountry name for the generated certificate. Relevant only for generate-self-signed-certificate.
--certificate-localityLocality for the generated certificate. Relevant only for generate-self-signed-certificate.
--certificate-provinceProvince name for the generated certificate. Relevant only for generate-self-signed-certificate.
-t, --tagList of the tags attached to this secret. To specify multiple tags use argument multiple times: -t Tag1 -t Tag2
-k, --protection-key-nameThe name of the key that protects the classic key value (if empty, the account default key will be used)
--delete-protectionProtection 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

ParameterDescribrion
-n, --name(Mandatory) Classic key name
-v, --versionClassic 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
ParameterDescription
-n, --name(Mandatory) Key name
-u, --gateway-url[=http://localhost:8000]API Gateway URL (Configuration Management port). Relevant only for Classic Key.
--new-key-dataThe 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

ParameterDescription
-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

ParameterDescription
-t, --target-name(Mandatory) The target to associate
-n, --name(Mandatory) The item to associate
--vault-nameName of the vault used. (Relevant only for Classic Key and target association. Required for azure targets)
--key-operationsA list of allowed operations for the key. (Relevant only for Classic Key and target association. Required for azure targets)
--project-idProject id of the GCP KMS. (Relevant only for Classic Key and target association. Required for gcp targets)
--location-idLocation id of the GCP KMS. (Relevant only for Classic Key and target association. Required for gcp targets)
--keyring-nameKeyring name of the GCP KMS. (Relevant only for Classic Key and target association. Required for gcp targets)
--purposePurpose if the key in GCP KMS. (Relevant only for Classic Key and target association. Required for gcp targets)
--kms-algorithmAlgorithm of the key in GCP KMS. (Relevant only for Classic Key and target association, Required for gcp targets)
--tenant-secret-typeSet 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
ParameterDescription
-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
ParameterDescription
-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
--descriptionKey description
-t, --tagList 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-idThe customer fragment ID that will be used to split the key (if empty, the key will be created independently of a customer fragment)
-c, --certPath 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
ParameterDescription
-n, --name(Mandatory) Name of key to be created
-a, --alg(Mandatory) Key type. options: [RSA1024, RSA2048, RSA3072, RSA4096]
-p, --rsa-key-file-pathRSA private key file path.
--rsa-key-dataRSA private key data, base64 encoded
-c, --certPath to a file that contain the certificate in a PEM format
--cert-file-dataPEM Certificate in a Base64 format
--descriptionKey description
-t, --tagList 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-idThe 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-protectionProtection 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

ParameterDescription
-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-intervalThe 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
ParameterDescription
-k, --key-nameThe name of the key to use in the encryption process
-d, --display-idThe display id of the key to use in the encryption process
-I, --item-idThe item id of the key to use in the encryption process
-i, --inPath to the file to be encrypted in base64 format
-o, --outPath to the output file. If not provided, the output will be printed as base64
-p, --plaintextData to be encrypted, if a file was not provided
-X, --encryption-contextname-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-formatIf 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
ParameterDescription
-k, --key-name(Mandatory) The name of the key to use in the encryption process
-d, --display-idThe display id of the key to use in the encryption process
-I, --item-idThe 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-contextname-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
ParameterDescription
-k, --key-name(Mandatory)The name of the key to use in the encryption process
-d, --display-idThe display id of the key to use in the encryption process
-I, --item-idThe item id of the key to use in the encryption process
-p, --plaintext(Mandatory) Data to be encrypted
--profile, --tokenUse a specific profile (located at $HOME/.akeyless/profiles) or a temp access token
--uid-tokenThe 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
ParameterDescription
-k, --key-name(Mandatory) The name of the key to use in the encryption process
-d, --display-idThe display id of the key to use in the encryption process
-I, --item-idThe item id of the key to use in the encryption process
-i, --inPath to the file to be encrypted in base64 format
-o, --outPath to the output file. If not provided, the output will be printed as base64
-p, --plaintextData to be encrypted, if a file was not provided
-F, --input-formatIf 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
ParameterDescription
-k, --key-name(Mandatory) The name of the key to use in the decryption process.
-d, --display-idThe display id of the key to use in the decryption process
-I, --item-idThe item id of the key to use in the decryption process
-i, --inPath to the file to be decrypted (base64 encoded)
-o, --outPath to the output file. If not provided, the output will be printed as text.
-c, --ciphertextCiphertext to be decrypted in base64 encoded format, if a file was not provided
-X, --encryption-contextThe encryption context. If this was specified in the encrypt command, it must be specified here or the decryption operation will fail
-F, --output-formatIf 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
ParameterDescription
--key-name(Mandatory) The name of the key to use in the decryption process
-d, --display-idThe display id of the key to use in the decryption process
-I, --item-idThe item id of the key to use in the decryption process
-i, --inPath to the file to be decrypted. If not provided, the content will be taken from stdin
-o, --outPath 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-contextThe 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
ParameterDescription
-k, --key-name(Mandatory) The name of the key to use in the decryption process
-d, --display-idThe display id of the key to use in the decryption process
-I, --item-idThe item id of the key to use in the decryption process
-c, --ciphertext(Mandatory) Ciphertext to be decrypted in base64 encoded format
-F, --output-formatIf 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
ParameterDescription
-k, --key-name(Mandatory) The name of the key to use in the decryption process.
-d, --display-idThe display id of the key to use in the decryption process
-I, --item-idThe item id of the key to use in the decryption process
-i, --inPath to the file to be decrypted (base64 encoded)
-o, --outPath to the output file. If not provided, the output will be printed as text.
-c, --ciphertextCiphertext to be decrypted in base64 encoded format, if a file was not provided
-p, --passphrasePassphrase to decrypt the message
-F, --output-formatIf 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
ParameterDescription
-k, --key-name(Mandatory) The name of the RSA key to use in the signing process
-d, --display-idThe display id of the key to use in the signing process
-I, --item-idThe item id of the key to use in the signing process
-m, --message(Mandatory) The message to be signed
--profile, --tokenUse a specific profile (located at $HOME/.akeyless/profiles) or a temp access token
--uid-tokenThe 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
ParameterDescription
-k, --key-name(Mandatory) The name of the RSA key to use in the verification process
-d, --display-idThe display id of the key to use in the verification process
-I, --item-idThe 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
ParameterDescription
-k, --key-name(Mandatory) The name of the RSA key to use in the signing process
-d, --display-idThe display id of the key to use in the signing process
-I, --item-idThe item id of the key to use in the signing process
-m, --message(Mandatory) The message to be signed
-p, --passphrasePassphrase 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
ParameterDescription
-k, --key-nameThe name of the RSA key to use in the verification process
-d, --display-idThe display id of the key to use in the verification process
-I, --item-idThe 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, --passphrasePassphrase 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
ParameterDescription
-k, --key-name(Mandatory) The name of the key to use in the encryption process
-d, --display-idThe display id of the key to use in the encryption process
-I, --item-idThe item id of the key to use in the encryption process
-i, --inPath to the input file
-o, --outPath to the output file. If not provided, the output will be printed as base64
-p, --plaintextData to perform hmac on, if a file was not provided
-f, --hash-function[=sha-256]Hash function [sha-256,sha-512]
-F, --input-formatSelect 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
ParameterDescription
-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
ParameterDescription
-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-nameAES key name to use in vaultless tokenization
--tweak-typeThe tweak type to use in vaultless tokenization [Supplied, Generated, Internal, Masking]
--alphabetAlphabet to use in custom vaultless tokenization, such as '0123456789' for credit cards.
--patternPattern to use in custom vaultless tokenization
--encoding-templateThe Encoding output template to use in custom vaultless tokenization
--decoding-templateThe Decoding output template to use in custom vaultless tokenization
--descriptionTokenizer description
--tagList of the tags attached to this key. To specify multiple tags use argument multiple times: --tag Tag1 --tag Tag2
--delete-protectionProtection 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
ParameterDescription
-n, --tokenizer-name (Mandatory) The name of the tokenizer to use in the encryption process
-p, --plaintext(Mandatory) Data to be encrypted
--tweakBase64 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
ParameterDescription
-n, --tokenizer-name(Mandatory) The name of the tokenizer to use in the decryption process
-c, --ciphertext(Mandatory) Data to be decrypted
--tweakBase64 encoded tweak for vaultless encryption