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 |
---|---|
Date/time the object becomes active |
|
Cryptographic algorithm this key is used with. Defaults to 'aes' Choices:
|
|
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. |
|
An alias for a key name |
|
Index associated with alias. Each alias within an object has a unique index |
|
Type of alias (allowed values are string and uri) |
|
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:
|
|
Date/time the object becomes archived |
|
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:
|
|
CM ID of the key that needs to be patched. Only required if the op_type is patch or create_version |
|
Date/time the object entered into the compromised state. |
|
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. |
|
Cryptographic curve id for elliptic key. Key algorithm must be 'EC' Choices:
|
|
Date/time the object becomes inactive |
|
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. |
|
Date/time the object was destroyed. |
|
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 |
|
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 |
|
If specified as true, the key's keyId identifier of type long is generated. Defaults to false. Choices:
|
|
Information which is used to create a Key using HKDF. |
|
Hash Algorithm is used for HKDF. This is required if ikmKeyName is specified, default is hmac-sha256. Choices:
|
|
Any existing symmetric key. Mandatory while using HKDF key generation. |
|
Info is an optional hex value for HKDF based derivation. |
|
Salt is an optional hex value for HKDF based derivation. |
|
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. |
|
Size of the ID for the key |
|
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. |
|
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 |
|
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 |
|
admin password of CM |
|
CM Server IP or FQDN |
|
Port on which CM server is listening Default: |
|
internal or private IP of the CM Server, if different from the server_ip |
|
admin username of CM |
|
if SSL verification is required Choices:
|
|
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. |
|
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. |
|
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:
|
|
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. |
|
Optional end-user or service data stored with the key |
|
Optional owner information for the key, required for non-admin. Value should be the user's user_id |
|
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. |
|
Optional friendly name, The key name should not contain special characters such as angular brackets (<,>) and backslash (). |
|
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:
|
|
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: |
|
Operation to be performed Choices:
|
|
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:
|
|
Date/time when a Managed Symmetric Key Object MAY begin to be used to process cryptographically protected information (e.g., decryption or unwrapping) |
|
Date/time after which a Managed Symmetric Key Object SHALL NOT be used for applying cryptographic protection (e.g., encryption or wrapping) |
|
Information needed to create a public key |
|
Date/time the object becomes active |
|
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. |
|
Date/time the object becomes archived |
|
Date/time the object becomes inactive |
|
Optional end-user or service data stored with the key |
|
Optional friendly name, The key name should not contain special characters such as angular brackets (<,>) and backslash (). |
|
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. |
|
Key is not deletable. Defaults to false. Choices:
|
|
Key is not exportable. Defaults to false. Choices:
|
|
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). |
|
Message explaining revocation. |
|
The reason the key is being revoked. Choices:
|
|
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. |
|
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. |
|
For pkcs12 format, either secretDataLink or password should be specified. The value can be either ID or name of Secret Data. |
|
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:
|
|
Bit length for the key. |
|
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. |
|
Key is not deletable. Defaults to false. Choices:
|
|
Key is not exportable. Defaults to false. Choices:
|
|
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). |
|
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. |
|
Information which is used to wrap a Key using HKDF. |
|
Hash Algorithm is used for HKDF Wrapping. Choices:
|
|
Info is an optional hex value for HKDF based derivation. |
|
The desired output key material length in integer. |
|
Salt is an optional hex value for HKDF based derivation. |
|
IDType specifies how the wrapKeyName should be interpreted. Choices:
|
|
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 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. |
|
Intended length in octets of the derived key. dklen must be in range of 14 bytes to 512 bytes. |
|
Underlying hashing algorithm that acts as a pseudorandom function to generate derive keys. Choices:
|
|
Iteration count increase the cost of producing keys from a password. Iteration must be in range of 1 to 1,00,00,000. |
|
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. |
|
Secret password identifier for password. It cannot be used in conjunction with password. |
|
Type of the Passwordidentifier. If not set then default value is name. Choices:
|
|
User defined purpose. If specified will be prefixed to pbeSalt. pbePurpose must not be greater than 128 bytes. |
|
A Hex encoded string. pbeSalt must be in range of 16 bytes to 512 bytes. |
|
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:
|
|
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 |
|
This parameter specifies the wrapping method used to wrap/mac/sign the key material. Choices:
|
|
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 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:
|
|
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. |
|
Size of AES key for RSA AES KWP. Choices:
|
|
Padding specifies the type of padding scheme that needs to be set when exporting the Key using RSA AES wrap Choices:
|
|
If set to true, then key created will be XTS/CBC-CS1 Key. Defaults to false. Key algorithm must be 'AES'. Choices:
|
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