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 ID of the key that needs to be patched. |
|
If set to true, then full material of XTS/CBC-CS1 key will be exported. Only applicable for op_type “export” Choices:
|
|
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. |
|
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” |
|
Query Parameter Type of identifier for the key Choices:
|
|
Size of the ID for the key Only applicable for op_type “clone” |
|
Query Parameter weather to include the key material if the op_type is clone applicable only if op_type is clone Choices:
|
|
Query Parameter Key version Defaults to the latest version Valid only if id_type is “name” |
|
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:
|
|
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 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” |
|
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:
|
|
Message explaining revocation. Message explaining reactivation. |
|
Optional end-user or service data stored with the key Only applicable for op_type “clone” |
|
Key name for the new cloned key. Only applicable for op_type “clone” |
|
Operation to be performed Choices:
|
|
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:
|
|
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” |
|
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:
|
|
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 |
|
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” |
|
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” |
|
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:
|
|
Information which is used to wrap a Key using HKDF. Only applicable for op_type “export” |
|
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. |
|
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” |
|
Content Encryption Algorithm is symmetric encryption algorithm used to encrypt the data , default is AES_256_GCM. Choices:
|
|
JWT identifier (JTI) is unique identifier for the JWT used by SFDC for cache key replay detection. |
|
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:
|
|
Key identifier to be used as “kid” parameter in JWE material and JWE header. Defaults to key id. |
|
IDType specifies how the wrapKeyName should be interpreted. Only applicable for op_type “export” Choices:
|
|
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 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” |
|
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. Only applicable for op_type “export” 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 Only applicable for op_type “export” |
|
This parameter specifies the wrapping method used to wrap/mac/sign the key material. Only applicable for op_type “export” 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. Only applicable for op_type “export” |
|
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:
|
|
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” |
|
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:
|
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