thalesgroup.ciphertrust.vault_keys2_op module – Perform operations on keys

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_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. If the algorithm is 'rsa' or 'ec'. The value can be one of 'pkcs1', 'pkcs8' , 'pkcs12', or 'jwe'. The default value is 'pkcs8'. If algorithm is 'rsa' and format is 'pkcs12', the key material will contain the base64-encoded value of the PFX file. The value 'base64' is used for symmetric keys, for which the format of the returned key material is base64-encoded if wrapping is applied (i.e., either 'wrapKeyName' or 'wrapPublicKey' is specified),otherwise, the format is hex-encoded, unless 'base64' is given. If the “format” is 'jwe' then the “material” for the symmetric key, asymmetric key or certificate will be wrapped in JWE format. “wrapKeyName”(should be a public key) or “wrapPublicKey” and “wrapJWE” parameters are required for 'jwe' format. The value 'opaque' is supported for symmetric keys with 'opaque' format only.

Only applicable for op_type “export”

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

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

macSignKeyIdentifier

string

This parameter specifies the identifier of the key used for generating the MAC or signature(“macSignBytes”) 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"

message

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

The reason the key is being revoked. Choices are Unspecified, KeyCompromise, CACompromise, AffiliationChanged, Superseded, CessationOfOperation or PrivilegeWithdrawn

The reason the key is being reactivated. Choices are DeactivatedToActive, ActiveProtectStopToActive or DeactivatedToActiveProtectStop

Required if op_type is either revoke or reactivate

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 the “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

string

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. (JWT ID (JTI) provides a unique identifier for the JWT. JTI will be automatically included in JWE if it is available in JWT identity token.)

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. The “material” property in the response will be base64 encoded ciphertext. If the “wrappingMethod” field is set to “encrypt”, then the wrapping key must be an AES key, RSA private key or RSA public key. For the export of symmetric keys with the “encrypt” method, the three key types are allowed but for the export of a private key if the “wrapRSAAES” parameters are not set, the wrapping key has to be an AES key with a size of 256 bits. If “wrapRSAAES” parameters are set, then the wrapping key has to either be an RSA private or public key. You can set either “wrapKeyName” parameter or “wrapPublicKey” at a time. The wrapping key should be active with a protect stop date that is not expired.

Only applicable for op_type “export”

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.

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

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, Developer Advocate Thales Group