thalesgroup.ciphertrust.vault_keys2_op module – Perform operations on keys

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_op.

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 key operations API

Parameters

Parameter

Comments

cm_key_id

string / required

CM ID of the key that needs to be patched.

combineXts

boolean

If set to true, then full material of XTS/CBC-CS1 key will be exported.

Only applicable for op_type “export”

Choices:

  • false ← (default)

  • true

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.

Defaults to key’’s creation time.

encoding

string

Specifies the encoding used for the material field.

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.

Options for Symmetric Keys are hex or base64

Only applicable for op_type “export”

id_type

string

Query Parameter

Type of identifier for the key

Choices:

  • "name"

  • "id"

  • "uri"

  • "alias"

idSize

integer

Size of the ID for the key

Only applicable for op_type “clone”

includeMaterial

boolean

Query Parameter

weather to include the key material if the op_type is clone

applicable only if op_type is clone

Choices:

  • false ← (default)

  • true

key_version

integer

Query Parameter

Key version

Defaults to the latest version

Valid only if id_type is “name”

keyFormat

string

The format of the returned key material

Choices:

  • "pkcs1"

  • "pkcs8"

  • "pkcs12"

  • "jwe"

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

macSignKeyIdentifier

string

This parameter specifies the identifier of the key used for generating the MAC or signature of the key whose key material is to be exported

The “wrappingMethod” should be “mac/sign” to generate the MAC/signature.

To generate a MAC, the key should be a HMAC key.

To generate a signature, the key should be an RSA private key.

Only applicable for op_type “export”

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

Only applicable for op_type “export”

Choices:

  • "name"

  • "id"

  • "alias"

messageStr

string

Message explaining revocation.

Message explaining reactivation.

meta

dictionary

Optional end-user or service data stored with the key

Only applicable for op_type “clone”

newKeyName

string

Key name for the new cloned key.

Only applicable for op_type “clone”

op_type

string / required

Operation to be performed

Choices:

  • "destroy"

  • "archive"

  • "recover"

  • "revoke"

  • "reactivate"

  • "export"

  • "clone"

padded

boolean

This parameter determines the padding for the wrap algorithm while exporting 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 wrapping the material for the symmetric key.

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

This parameter defaults to false.

Only applicable for op_type “export”

Choices:

  • false ← (default)

  • true

password

string

For pkcs12 format, if the pkcs12passwordLink is not present in the Key (RSA keys), specify either password or secretDataLink.

This should be the base64 encoded value of the password.

Only applicable for op_type “export”

pemWrap

boolean

If the parameter is set to true, it wraps the PEM encoding of the private key (asymmetric) otherwise, the DER encoding of the key is wrapped.

Only valid when private keys (asymmetric) and certificates are to be wrapped for “mac/sign” and “encrypt” values for “wrappingMethod” parameter.

This parameter defaults to false.

Only applicable for op_type “export”

Choices:

  • false ← (default)

  • true

reason

string

If the reason the key is being revoked, choices are

Unspecified

KeyCompromise

CACompromise

AffiliationChanged

Superseded

CessationOfOperation

PrivilegeWithdrawn

If the reason the key is being reactivated, choices are

DeactivatedToActive

ActiveProtectStopToActive

DeactivatedToActiveProtectStop

Required if op_type is either revoke or reactivate

Choices:

  • "Unspecified"

  • "KeyCompromise"

  • "CACompromise"

  • "AffiliationChanged"

  • "Superseded"

  • "CessationOfOperation"

  • "PrivilegeWithdrawn"

  • "DeactivatedToActive"

  • "ActiveProtectStopToActive"

  • "DeactivatedToActiveProtectStop"

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.

Only applicable for op_type “export”

string

For pkcs12 format, either secretDataLink or password should be specified

The value can be either ID or name of Secret Data.

Only applicable for op_type “export”

signingAlgo

string

This parameter specifies the algorithm to be used for generating the signature for the verification of

macSignBytes during import of key material

The “wrappingMethod” should be “mac/sign” to verify the signature(“macSignBytes”) of the key material(“material”)

Only applicable for op_type “export”

Choices:

  • "RSA"

  • "RSA-PSS"

wrapHKDF

dictionary

Information which is used to wrap a Key using HKDF.

Only applicable for op_type “export”

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.

wrapJWE

dictionary

Information which is used to wrap a Key using JWE

Only applicable for op_type “export”

contentEncryptionAlgorithm

string

Content Encryption Algorithm is symmetric encryption algorithm used to encrypt the data

default is AES_256_GCM.

Choices:

  • "AES_128_CBC_HMAC_SHA_256"

  • "AES_192_CBC_HMAC_SHA_384"

  • "AES_256_CBC_HMAC_SHA_512"

  • "AES_128_GCM"

  • "AES_192_GCM"

  • "AES_256_GCM" ← (default)

jwtIdentifier

string

JWT identifier (JTI) is unique identifier for the JWT used by SFDC for cache key replay detection.

keyEncryptionAlgorithm

string

Key Encryption Algorithm is used to encrypt the Content Encryption Key (CEK), default is RSA_OAEP_SHA1

Algorithm should correspond to type of public key provided for wrapping.

Choices:

  • "RSA1_5"

  • "RSA_OAEP_SHA1" ← (default)

  • "RSA_OAEP_SHA256"

  • "ECDH_ES"

  • "ECDH_ES_AES_128_KEY_WRAP"

  • "ECDH_ES_AES_192_KEY_WRAP"

  • "ECDH_ES_AES_256_KEY_WRAP"

keyIdentifier

string

Key identifier to be used as “kid” parameter in JWE material and JWE header. Defaults to key id.

wrapKeyIDType

string

IDType specifies how the wrapKeyName should be interpreted.

Only applicable for op_type “export”

Choices:

  • "name"

  • "id"

  • "alias"

wrapKeyName

string

The key material will be wrapped with material of the specified key name

Only applicable for op_type “export”

wrapPBE

dictionary

WrapPBE produces a derived key from a password and other parameters

PBE is currently only supported to wrap symmetric keys (AES), private Keys and certificates.

Only applicable for op_type “export”

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

Only applicable for op_type “export”

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

Only applicable for op_type “export”

wrappingMethod

string

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

Only applicable for op_type “export”

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.

Only applicable for op_type “export”

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.

Only applicable for op_type “export”

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.

Only applicable for op_type “export”

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"

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

Authors

  • Anurag Jain (@anugram)