thalesgroup.ciphertrust.vault_keys2_save module – Create or update keys in CipherTrust Manager managed vault

Note

This module is part of the thalesgroup.ciphertrust collection (version 1.0.0).

To install it, use: ansible-galaxy collection install thalesgroup.ciphertrust.

To use it in a playbook, specify: thalesgroup.ciphertrust.vault_keys2_save.

New in thalesgroup.ciphertrust 1.0.0

Synopsis

  • This is a Thales CipherTrust Manager module for working with the CipherTrust Manager APIs, more specifically with keys management API

Parameters

Parameter

Comments

activationDate

string

Date/time the object becomes active

algorithm

string

Cryptographic algorithm this key is used with.

Defaults to 'aes'

Choices:

  • "aes" ← (default)

  • "tdes"

  • "rsa"

  • "ec"

  • "hmac-sha1"

  • "hmac-sha256"

  • "hmac-sha384"

  • "hmac-sha512"

  • "seed"

  • "aria"

  • "opaque"

aliases

list / elements=dictionary

Aliases associated with the key.

The alias and alias-type must be specified.

The alias index is assigned by this operation, and need not be specified.

alias

string / required

An alias for a key name

index

integer

Index associated with alias. Each alias within an object has a unique index

type

string

Type of alias (allowed values are string and uri)

allVersions

boolean

To update the group permissions/custom attribute or both in metadata of all versions of the key. By default it is set to false. Set to true, only when to update the group/custom attribute or both permissions of all versions of the key.

Only applicable for op_type “patch”

Choices:

  • false ← (default)

  • true

archiveDate

string

Date/time the object becomes archived

certType

string

This specifies the type of certificate object that is being created. Valid values are 'x509-pem' and 'x509-der'. At present, we only support x.509 certificates. The cerfificate data is passed in via the 'material' field. The certificate type is infered from the material if it is left blank.

Choices:

  • "x509-pem"

  • "x509-der"

cm_key_id

string

CM ID of the key that needs to be patched.

Only required if the op_type is patch or create_version

compromiseDate

string

Date/time the object entered into the compromised state.

compromiseOccurrenceDate

string

Date/time when the object was first believed to be compromised, if known. Only valid if the revocation reason is CACompromise or KeyCompromise, otherwise ignored.

curveid

string

Cryptographic curve id for elliptic key.

Key algorithm must be 'EC'

Choices:

  • "secp224k1"

  • "secp224r1"

  • "secp256k1"

  • "secp384r1"

  • "secp521r1"

  • "prime256v1"

  • "brainpoolP224r1"

  • "brainpoolP224t1"

  • "brainpoolP256r1"

  • "brainpoolP256t1"

  • "brainpoolP384r1"

  • "brainpoolP384t1"

  • "brainpoolP512r1"

  • "brainpoolP512t1"

deactivationDate

string

Date/time the object becomes inactive

defaultIV

string

Deprecated. This field was introduced to support specific legacy integrations and applications. New applications are strongly recommended to use a unique IV for each encryption request. Refer to Crypto encrypt endpoint for more details. Must be a 16 byte hex encoded string (32 characters long). If specified, this will be set as the default IV for this key.

destroyDate

string

Date/time the object was destroyed.

encoding

string

Specifies the encoding used for the 'material' field.

This parameter is used during importing keys when key material is not empty or while returning the key material after the key is created ('includeMaterial' is true)

For wrapping scenarios and PKCS12 format, the only valid option is base64. In case of “Symmetric Keys” when 'format' parameter has 'base64' value and 'encoding' parameter also contains some value. The encoding parameter takes the priority. Following are the options for Symmetric Keys are hex or base64

format

string

This parameter is used while importing keys ('material' is not empty), and also when returning the key material after the key is created ('includeMaterial' is true).

For Asymmetric keys, When this parameter is not specified, while importing keys, the format of the material is inferred from the material itself. When this parameter is specified, while importing keys, the only allowed format is 'pkcs12', and this only applies to the 'rsa' algorithm (the 'material' should contain the base64 encoded value of the PFX file in this case). Options are pkcs1, pkcs8 (default) or pkcs12

For Symmetric keys, When importing keys if specified, the value must be given according to the format of the material. Options are raw or opaque

generateKeyId

boolean

If specified as true, the key's keyId identifier of type long is generated. Defaults to false.

Choices:

  • false ← (default)

  • true

hkdfCreateParameters

dictionary

Information which is used to create a Key using HKDF.

hashAlgorithm

string

Hash Algorithm is used for HKDF.

This is required if ikmKeyName is specified, default is hmac-sha256.

Choices:

  • "hmac-sha1"

  • "hmac-sha224"

  • "hmac-sha256" ← (default)

  • "hmac-sha384"

  • "hmac-sha512"

ikmKeyName

string

Any existing symmetric key. Mandatory while using HKDF key generation.

info

string

Info is an optional hex value for HKDF based derivation.

salt

string

Salt is an optional hex value for HKDF based derivation.

id

string

This optional parameter specifies the identifier of the key (id). It is used only when creating keys with specific key material. If set, the key's id is set to this value.

idSize

integer

Size of the ID for the key

keyId

string

Additional identifier of the key. The format of this value is of type long. This is optional and applicable for import key only. If set, the value is imported as the key's keyId.

labels

dictionary

Optional key/value pairs used to group keys. APIs that list keys can use labels to filter the set of matching resources. A label's key has an optional prefix up to 253 characters followed by a forward slash and a required name up to 63 characters. For example, sales.widgets.com/region is a label key with the prefix sales.widgets.com and the name region, while region is a label key without a prefix. A label's value may be empty and may be up to 63 characters. Each part of the label (i.e. the prefix, name, and value) must begin and end with an alphanumeric character (a-zA-Z0-9). Characters in between the beginning and end may contain alphanumeric characters, dots (.), dashes (-) and underscores (_). A Label can be a simple tag by specifying a key with no value

localNode

dictionary / required

this holds the connection parameters required to communicate with an instance of CipherTrust Manager (CM)

holds IP/FQDN of the server, username, password, and port

password

string / required

admin password of CM

server_ip

string / required

CM Server IP or FQDN

server_port

integer / required

Port on which CM server is listening

Default: 5432

server_private_ip

string / required

internal or private IP of the CM Server, if different from the server_ip

user

string / required

admin username of CM

verify

boolean / required

if SSL verification is required

Choices:

  • false ← (default)

  • true

macSignBytes

string

This parameter specifies the MAC/Signature bytes to be used for verification while importing a key. The “wrappingMethod” should be “mac/sign” and the required parameters for the verification must be set.

macSignKeyIdentifier

string

This parameter specifies the identifier of the key to be used for generating MAC or signature of the key material. The “wrappingMethod” should be “mac/sign” to verify the MAC/signature(“macSignBytes”) of the key material(“material”). For verifying the MAC, the key has to be a HMAC key. For verifying the signature, the key has to be an RSA private or public key.

macSignKeyIdentifierType

string

This parameter specifies the identifier of the key(“macSignKeyIdentifier”) used for generating MAC or signature of the key material. The “wrappingMethod” should be “mac/sign” to verify the mac/signature(“macSignBytes”) of the key material(“material”)

Choices:

  • "name"

  • "id"

  • "alias"

material

string

If set, the value will be imported as the key's material. If not set, new key material will be generated on the server (certificate objects must always specify the material). The format of this value depends on the algorithm. If the algorithm is 'aes', 'tdes', 'hmac-*', 'seed' or 'aria', the value should be the hex-encoded bytes of the key material. If the algorithm is 'rsa', and the format is 'pkcs12', it should be the base64 encoded PFX file. If the algorithm is 'rsa' or 'ec', and format is not 'pkcs12', the value should be a PEM-encoded private or public key using PKCS1 or PKCS8 format. For a X.509 DER encoded certificate, certType equals 'x509-der' and the material should equal the hex encoded certificate. The material for a X.509 PEM encoded certificate (certType = 'x509-pem') should equal the certificate itself. When placing the PEM encoded certificate inside a JSON object (as in the playground), be sure to change all new line characters in the certificate to the string newline char.

meta

dictionary

Optional end-user or service data stored with the key

ownerId

string

Optional owner information for the key, required for non-admin. Value should be the user's user_id

muid

string

Additional identifier of the key. This is optional and applicable for import key only. If set, the value is imported as the key's muid.

name

string

Optional friendly name, The key name should not contain special characters such as angular brackets (<,>) and backslash ().

objectType

string

This specifies the type of object that is being created. Valid values are 'Symmetric Key', 'Public Key', 'Private Key', 'Secret Data', 'Opaque Object', or 'Certificate'. The object type is inferred for many objects, but must be supplied for the certificate object.

Choices:

  • "Symmetric Key"

  • "Public Key"

  • "Private Key"

  • "Secret Data"

  • "Opaque Object"

  • "Certificate"

offset

integer

An Offset MAY be used to indicate the difference between the Creation Date and the Activation Date of the replacement key. If no Offset is specified, the Activation Date, Process Start Date, Protect Stop Date and Deactivation Date values are copied from the existing key. If Offset is set and dates exist for the existing key, then the dates of the replacement key are set based on the dates of the existing key by adding the offset.

Only applicable for op_type “create_version”

Default: false

op_type

string / required

Operation to be performed

Choices:

  • "create"

  • "patch"

  • "create_version"

padded

boolean

This parameter determines the padding for the wrap algorithm while unwrapping a symmetric key

If true, the RFC 5649(AES Key Wrap with Padding) is followed and if false, RFC 3394(AES Key Wrap) is followed for unwrapping the material for the symmetric key.

If a certificate is being unwrapped with the “wrappingMethod” set to “encrypt”, the “padded” parameter has to be set to true.

Choices:

  • false ← (default)

  • true

processStartDate

string

Date/time when a Managed Symmetric Key Object MAY begin to be used to process cryptographically protected information (e.g., decryption or unwrapping)

protectStopDate

string

Date/time after which a Managed Symmetric Key Object SHALL NOT be used for applying cryptographic protection (e.g., encryption or wrapping)

publicKeyParameters

list / elements=dictionary

Information needed to create a public key

activationDate

string

Date/time the object becomes active

aliases

list / elements=dictionary

Aliases associated with the key.

The alias and alias-type must be specified.

The alias index is assigned by this operation, and need not be specified.

archiveDate

string

Date/time the object becomes archived

deactivationDate

string

Date/time the object becomes inactive

meta

dictionary

Optional end-user or service data stored with the key

name

string

Optional friendly name, The key name should not contain special characters such as angular brackets (<,>) and backslash ().

state

string

Optional initial key state (Pre-Active) upon creation. Defaults to Active. If set, activationDate and processStartDate can not be specified during key creation. In case of import, allowed values are “Pre-Active”, “Active”, “Deactivated”, “Destroyed”, “Compromised” and “Destroyed Compromised”. If key material is not specified, it will not be autogenerated if input parameters correspond to either of these states - “Deactivated”, “Destroyed”, “Compromised” and “Destroyed Compromised”. Key in “Destroyed” or “Destroyed Compromised” state would not have key material even if specified during key creation.

undeletable

boolean

Key is not deletable. Defaults to false.

Choices:

  • false ← (default)

  • true

unexportable

boolean

Key is not exportable. Defaults to false.

Choices:

  • false ← (default)

  • true

usageMaske

integer

Cryptographic usage mask. Add the usage masks to allow certain usages. Sign (1), Verify (2), Encrypt (4), Decrypt (8), Wrap Key (16), Unwrap Key (32), Export (64), MAC Generate (128), MAC Verify (256), Derive Key (512), Content Commitment (1024), Key Agreement (2048), Certificate Sign (4096), CRL Sign (8192), Generate Cryptogram (16384), Validate Cryptogram (32768), Translate Encrypt (65536), Translate Decrypt (131072), Translate Wrap (262144), Translate Unwrap (524288), FPE Encrypt (1048576), FPE Decrypt (2097152). Add the usage mask values to allow the usages. To set all usage mask bits, use 4194303. Equivalent usageMask values for deprecated usages 'fpe' (FPE Encrypt + FPE Decrypt = 3145728), 'blob' (Encrypt + Decrypt = 12), 'hmac' (MAC Generate + MAC Verify = 384), 'encrypt' (Encrypt + Decrypt = 12), 'sign' (Sign + Verify = 3), 'any' (4194303 - all usage masks).

revocationMessage

string

Message explaining revocation.

revocationReason

string

The reason the key is being revoked.

Choices:

  • "Unspecified"

  • "KeyCompromise"

  • "CACompromise"

  • "AffiliationChanged"

  • "Superseded"

  • "CessationOfOperation"

  • "PrivilegeWithdrawn"

rotationFrequencyDays

string

Number of days from current date to rotate the key. It should be greater than or equal to 0. Default is an empty string. If set to 0, rotationFrequencyDays set to an empty string and auto rotation of key will be disabled.

secretDataEncoding

string

For pkcs12 format, this field specifies the encoding method used for the secretDataLink material. Ignore this field if secretData is created from REST and is in plain format. Specify the value of this field as HEX format if secretData is created from KMIP.

string

For pkcs12 format, either secretDataLink or password should be specified. The value can be either ID or name of Secret Data.

signingAlgo

string

This parameter specifies the algorithm to be used for generating the signature for the verification of the “macSignBytes” during import of key material. The “wrappingMethod” should be “mac/sign” to verify the signature(“macSignBytes”) of the key material(“material”).

Choices:

  • "RSA"

  • "RSA-PSS"

size

integer

Bit length for the key.

state

string

Optional initial key state (Pre-Active) upon creation. Defaults to Active. If set, activationDate and processStartDate can not be specified during key creation. In case of import, allowed values are “Pre-Active”, “Active”, “Deactivated”, “Destroyed”, “Compromised” and “Destroyed Compromised”. If key material is not specified, it will not be autogenerated if input parameters correspond to either of these states - “Deactivated”, “Destroyed”, “Compromised” and “Destroyed Compromised”. Key in “Destroyed” or “Destroyed Compromised” state would not have key material even if specified during key creation.

undeletable

boolean

Key is not deletable. Defaults to false.

Choices:

  • false ← (default)

  • true

unexportable

boolean

Key is not exportable. Defaults to false.

Choices:

  • false ← (default)

  • true

usageMaske

integer

Cryptographic usage mask. Add the usage masks to allow certain usages. Sign (1), Verify (2), Encrypt (4), Decrypt (8), Wrap Key (16), Unwrap Key (32), Export (64), MAC Generate (128), MAC Verify (256), Derive Key (512), Content Commitment (1024), Key Agreement (2048), Certificate Sign (4096), CRL Sign (8192), Generate Cryptogram (16384), Validate Cryptogram (32768), Translate Encrypt (65536), Translate Decrypt (131072), Translate Wrap (262144), Translate Unwrap (524288), FPE Encrypt (1048576), FPE Decrypt (2097152). Add the usage mask values to allow the usages. To set all usage mask bits, use 4194303. Equivalent usageMask values for deprecated usages 'fpe' (FPE Encrypt + FPE Decrypt = 3145728), 'blob' (Encrypt + Decrypt = 12), 'hmac' (MAC Generate + MAC Verify = 384), 'encrypt' (Encrypt + Decrypt = 12), 'sign' (Sign + Verify = 3), 'any' (4194303 - all usage masks).

uuid

string

Additional identifier of the key. The format of this value is 32 hexadecimal lowercase digits with 4 dashes. This is optional and applicable for import key only. If set, the value is imported as the key's uuid. If not set, new key uuid is generated on the server.

wrapHKDF

dictionary

Information which is used to wrap a Key using HKDF.

hashAlgorithm

string

Hash Algorithm is used for HKDF Wrapping.

Choices:

  • "hmac-sha1"

  • "hmac-sha224"

  • "hmac-sha256"

  • "hmac-sha384"

  • "hmac-sha512"

info

string

Info is an optional hex value for HKDF based derivation.

okmLen

string

The desired output key material length in integer.

salt

string

Salt is an optional hex value for HKDF based derivation.

wrapKeyIDType

string

IDType specifies how the wrapKeyName should be interpreted.

Choices:

  • "name"

  • "id"

  • "alias"

wrapKeyName

string

While creating a new key, If 'includeMaterial' is true, then only the key material will be wrapped with material of the specified key name. The response “material” property will be the base64 encoded ciphertext. For more details, view “wrapKeyName” in export parameters.

While importing a key, the key material will be unwrapped with material of the specified key name. The only applicable “wrappingMethod” for the unwrapping is “encrypt” and the wrapping key has to be an AES key or an RSA private key.

wrapPBE

dictionary

WrapPBE produces a derived key from a password and other parameters like salt, iteration count, hashing algorithm and derived key length. PBE is currently only supported to wrap symmetric keys (AES), private Keys and certificates.

dklen

integer

Intended length in octets of the derived key. dklen must be in range of 14 bytes to 512 bytes.

hashAlgorithm

string

Underlying hashing algorithm that acts as a pseudorandom function to generate derive keys.

Choices:

  • "hmac-sha1"

  • "hmac-sha224"

  • "hmac-sha256"

  • "hmac-sha384"

  • "hmac-sha512"

  • "hmac-sha512/224"

  • "hmac-sha512/256"

  • "hmac-sha3-224"

  • "hmac-sha3-256"

  • "hmac-sha3-384"

  • "hmac-sha3-512"

iteration

integer

Iteration count increase the cost of producing keys from a password. Iteration must be in range of 1 to 1,00,00,000.

password

string

Base password to generate derive keys. It cannot be used in conjunction with passwordidentifier. password must be in range of 8 bytes to 128 bytes.

passwordIdentifier

string

Secret password identifier for password. It cannot be used in conjunction with password.

passwordIdentifierType

string

Type of the Passwordidentifier. If not set then default value is name.

Choices:

  • "id"

  • "name"

  • "slug"

purpose

string

User defined purpose. If specified will be prefixed to pbeSalt. pbePurpose must not be greater than 128 bytes.

salt

string

A Hex encoded string. pbeSalt must be in range of 16 bytes to 512 bytes.

wrappingEncryptionAlgo

string

It indicates the Encryption Algorithm information for wrapping the key. Format is Algorithm/Mode/Padding. For example AES/AESKEYWRAP. Here AES is Algorithm, AESKEYWRAP is Mode & Padding is not specified. AES/AESKEYWRAP is RFC-3394 & AES/AESKEYWRAPPADDING is RFC-5649. For wrapping private key, only AES/AESKEYWRAPPADDING is allowed. RSA/RSAAESKEYWRAPPADDING is used to wrap/unwrap asymmetric keys using RSA AES KWP method. Refer “WrapRSAAES” to provide optional parameters.

Choices:

  • "AES/AESKEYWRAP"

  • "AES/AESKEYWRAPPADDING"

  • "RSA/RSAAESKEYWRAPPADDING"

wrappingHashAlgo

string

This parameter specifies the hashing algorithm used if “wrappingMethod” corresponds to “mac/sign”. In case of MAC operation, the hashing algorithm used will be inferred from the type of HMAC key(“macSignKeyIdentifier”).

In case of SIGN operation, the possible values are sha1, sha224, sha256, sha384 or sha512

wrappingMethod

string

This parameter specifies the wrapping method used to wrap/mac/sign the key material.

Choices:

  • "encrypt"

  • "mac/sign"

  • "pbe"

wrapPublicKey

string

If the algorithm is 'aes','tdes','hmac-*', 'seed' or 'aria', this value will be used to encrypt the returned key material. This value is ignored for other algorithms. Value must be an RSA public key, PEM-encoded public key in either PKCS1 or PKCS8 format, or a PEM-encoded X.509 certificate. If set, the returned 'material' value will be a Base64 encoded PKCS#1 v1.5 encrypted key. View “wrapPublicKey” in export parameters for more information. Only applicable if 'includeMaterial' is true.

wrapPublicKeyPadding

string

WrapPublicKeyPadding specifies the type of padding scheme that needs to be set when importing the Key using the specified wrapkey. Accepted values are “pkcs1”, “oaep”, “oaep256”, “oaep384”, “oaep512”, and will default to “pkcs1” when 'wrapPublicKeyPadding' is not set and 'WrapPublicKey' is set.

While creating a new key, wrapPublicKeyPadding parameter should be specified only if 'includeMaterial' is true. In this case, key will get created and in response wrapped material using specified wrapPublicKeyPadding and other wrap parameters will be returned.

Choices:

  • "pkcs1"

  • "oaep"

  • "oaep256"

  • "oaep384"

  • "oaep512"

wrapRSAAES

dictionary

Information which is used to wrap/unwrap asymmetric keys using RSA AES KWP method. This method internally requires AES key size to generate a temporary AES key and RSA padding. To use WrapRSAAES, algorithm “RSA/RSAAESKEYWRAPPADDING” must be specified in WrappingEncryptionAlgo.

aesKeySize

integer

Size of AES key for RSA AES KWP.

Choices:

  • 128

  • 192

  • 256 ← (default)

padding

string

Padding specifies the type of padding scheme that needs to be set when exporting the Key using RSA AES wrap

Choices:

  • "oaep"

  • "oaep256" ← (default)

  • "oaep384"

  • "oaep512"

xts

boolean

If set to true, then key created will be XTS/CBC-CS1 Key. Defaults to false. Key algorithm must be 'AES'.

Choices:

  • false ← (default)

  • true

Examples

- name: "Create Key"
  thalesgroup.ciphertrust.vault_keys2_create:
    localNode:
        server_ip: "IP/FQDN of CipherTrust Manager"
        server_private_ip: "Private IP in case that is different from above"
        server_port: 5432
        user: "CipherTrust Manager Username"
        password: "CipherTrust Manager Password"
        verify: false
    op_type: create
    name: "key_name"
    algorithm: aes
    size: 256
    usageMask: 3145740

- name: "Patch Key"
  thalesgroup.ciphertrust.vault_keys2_create:
    localNode:
        server_ip: "IP/FQDN of CipherTrust Manager"
        server_private_ip: "Private IP in case that is different from above"
        server_port: 5432
        user: "CipherTrust Manager Username"
        password: "CipherTrust Manager Password"
        verify: false
    op_type: patch
    cm_key_id: "4ae2649a705e479589ef65759d3287f6ff452a788531445fbc7f0240516d028d"
    unexportable: false

Authors

  • Anurag Jain, Developer Advocate Thales Group