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.2).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

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

  • For 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

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

destroyDate

string

Date/time the object was destroyed.

encoding

string

Specifies the encoding used for the material field.

format

string

This parameter is used while importing keys (material is not empty)

For Asymmetric keys, When this parameter is not specified

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

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

auth_domain_path

string / required

user’’s domain path

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

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

  • 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

meta

dictionary

Optional end-user or service data stored with the key

cte

dictionary

CTE specific permissions

cte_versioned

boolean

CTE versioned

Choices:

  • false

  • true

encryption_mode

string

Specify encryption mode

persistent_on_client

boolean

Allow persisting key on the client

Choices:

  • false

  • true

ownerId

string

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

permissions

dictionary

Optional permissions associated with this key

DecryptWithKey

list / elements=string

Permission to descrypt with the key

EncryptWithKey

list / elements=string

Permission to encrypt with the key

ExportKey

list / elements=string

Permission to export key

MACVerifyWithKey

list / elements=string

Permission to verify MAC with the key

MACWithKey

list / elements=string

Permission to use MAC with key

ReadKey

list / elements=string

Permission to read key

SignVerifyWithKey

list / elements=string

Permission to verify sign with the key

SignWithKey

list / elements=string

Permission to sign with the key

UseKey

list / elements=string

Permission to use key

versionedKey

boolean

if the key is versioned

Choices:

  • false

  • true

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

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.

Only applicable for op_type create_version

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

Choices:

  • false ← (default)

  • true

password

string

For pkcs12 format, either password or secretDataLink should be specified

This should be the base64 encoded value of the password.

processStartDate

string

Date/time when a Managed Symmetric Key Object MAY begin to be used to process cryptographically protected information

protectStopDate

string

Date/time after which a Managed Symmetric Key Object SHALL NOT be used for applying cryptographic protection

publicKeyParameters

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.

alias

string

alias

index

integer

alias index

type

string

alias type

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

state

string

Optional initial key state (Pre-Active) upon creation

Defaults to Active

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

usageMask

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

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

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.

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

usageMask

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

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

integer

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 key material.

The response “material” property will be the base64 encoded ciphertext

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

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

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

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”

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 (@anugram)