KMIP Reference
The Key Management Interoperability Protocol (KMIP) is a communication protocol that facilitates key management and cryptographic operations on a key management server. This section provides additional user information and specifications applicable to the KMIP interface of CipherTrust Manager.
Setting up a KMIP Client
Here are the prerequisites for allowing KMIP clients to connect to CipherTrust Manager:
The CipherTrust Manager server's KMIP port 5696 should be open from the client.
The CipherTrust Manager server supports the following TLS versions:
TLS version 1.0
TLS version 1.1
TLS version 1.2 (default minimum)
TLS version 1.3
Caution
TLS 1.0 and 1.1 are deprecated and support will be discontinued in a future release.
Configure the KMIP service to trust the external CAs. Refer to Trusted CAs (NAE, KMIP, and WEB) for details. .
KMIP Parameter: kmip_enable_hard_delete
This optional parameter enables a hard delete of keys on a "KMIP Destroy" operation. This means that both meta-data and material are removed from CipherTrust Manager for the key being deleted. By default, only key material is removed and meta-data is preserved with the updated key state. This setting applies only to the KMIP interface. Should be set to '1' for enabling this feature or '0' for returning to the default behavior.
KMIP Licensing
The KMIP interface is active for a 90-day trial period after CipherTrust Manager is installed. After the trial period expires, a new purchased KMIP license must be installed to use the KMIP interface. Contact Thales Customer Support for assistance in obtaining a license.
To activate a license using the GUI
Activating a KMIP license requires a license string for the CipherTrust Manager with which the clients will be registered. This string is generated when a license is activated on the Sentinel EMS License Portal.
Refer to Activating a Connector License for details.
After the KMIP license is activated, its state becomes Active on the Features tab of the Licensing page of the CipherTrust Manager GUI. The license is displayed with the feature name KMIP.
KMIP Client Registration
CipherTrust Manager recognizes only registered KMIP clients.
For registering a KMIP client, a certificate is required. The certificate facilitates authentication and communication between CipherTrust Manager and the client.
You can register KMIP clients using following methods:
Using Auto Registration (using an existing certificate)
Auto registration is useful when the clients are having certificates from the Classic KeySecure, or from older versions of CipherTrust Manager, or certificates issued by External CAs.
If you are already having one of the above certificate, you can utilize it to register your KMIP client, or to upgrade to a newer version of CipherTrust Manager. For detailed steps, refer to the section KMIP Client Registration for existing CipherTrust Manager and external CA(s).
Using Manual Registration
Before proceeding to manual registration, make sure that a client profile is created on the CipherTrust Manager. A client profile contains a set of properties, on basis of which, the KMIP client gets registered. KMIP clients can be registered manually by:
Creating a new certificate using local CA on the CipherTrust Manager.
Using a certificate signed by an external CA.
Refer to To Register a new KMIP Client for details.
Note
CipherTrust Manager 2.2.0 onward, it is mandatory to register the KMIP clients.
For KMIP client administration, the user must be a member of
Key Users
andClient Admins
groups.
Specifying LDAP and Multi-Domain Client Usernames in KMIP Certificates
The connection and/or username can be specified in the following formats:
<username>
- A local user in the root domain. For example, joe.<ldap-connection>|<username>
An LDAP user in the root domain. For example, ldap-connection|joe.
<domain>|<ldap-connection>|<username>
An LDAP user in a specific domain. For example, domain|ldap-connection|joe.
<domain>||<username>
A root domain user assigned in a specific domain. For example, domain||joe.
<domain>|<auth-domain>||<username>
A local user created inside a specific domain, named "auth-domain". For example, domain|auth-domain||joe.
Note
To authenticate a domain user:
Add the trusted CA of the domain to the root domain's external CAs list.
Add that external CA of the root domain to the KMIP interface's trusted external CAs list.
When browsing the GUI, users can be identified from the source property. The user is displayed in either of the formats listed above. A local user is displayed as local|<username>
.
KMIP Client Registration for existing CipherTrust Manager and external CA(s)
Create a registration token to register KMIP clients.
Request
ksctl clientmgmt tokens create --configfile config_example.yaml
Response
{ "id": "dd8289f4-adbe-412f-9191-320bf2bac847", "uri": "kylo:kylo:munshi:tokens:dd8289f4-adbe-412f-9191-320bf2bac847", "account": "kylo:kylo:admin:accounts:kylo", "application": "ncryptify:gemalto:admin:apps:kylo", "devAccount": "ncryptify:gemalto:admin:accounts:gemalto", "createdAt": "2019-12-19T05:52:36.590956451Z", "updatedAt": "2019-12-19T05:52:36.590956451Z", "token": "RwIgd6RfXd7kzri12ydzoeFXsA2R9ju2YDxMv2xM9duQbqAhcKcyMQO2OpqZesti", "valid_until": "0001-01-01T00:00:00Z", "max_clients": -1, "cert_duration": 730, "clients_registered": 0, "ca_id": "713172e0-02be-48c2-be60-6aae964ce943", "label": null }
Update the KMIP Interface for which you want to allow Auto registration of KMIP clients. For auto registration, the client certificate which is to registered should be signed by the trusted CA for the interface. To update the KMIP interface, run the ksctl interfaces modify command with the following parameters.
-a
(true
|false
) is for enabling or disabling auto registration-r
is for providing registration token as input
If
-a
is set totrue
, then providing registration token in-r
is mandatory.Note
A new KMIP interface can also be created with the
-a
and-r
parameters.Note
If the client is auto registered using the
tls-pw-opt
mode, then that certificate cannot be used to connect via the other two modes,tls-cert-pw-opt
andtls-cert-and-pw
.Request to update interface with auto registration on:
ksctl interfaces modify -n kmip -a true -r RwIgd6RfXd7kzri12ydzoeFXsA2R9ju2YDxMv2xM9duQbqAhcKcyMQO2OpqZesti --configfile config_example.yaml
Response
{ "id": "54523325-62d0-40d4-a45e-f45b9e1679e7", "name": "kmip", "mode": "tls-cert-pw-opt", "cert_user_field": "CN", "auto_gen_ca_id": "kylo:kylo:naboo:localca:713172e0-02be-48c2-be60-6aae964ce943", "trusted_cas": { "local": [ "kylo:kylo:naboo:localca:713172e0-02be-48c2-be60-6aae964ce943" ] }, "createdAt": "2019-12-13T03:27:28.767622Z", "updatedAt": "2019-12-19T05:55:26.362558Z", "default_connection": "local_account", "port": 5696, "network_interface": "all", "interface_type": "kmip", "minimum_tls_version": "tls_1_2", "local_auto_gen_attributes": { "cn": "kmip.keysecure.local", "email_addresses": [ "support@gemalto.com" ], "names": [ { "C": "US", "ST": "MD", "L": "Belcamp", "O": "Gemalto", "OU": "" } ], "generated": false }, "auto_registration": true, "registration_token": "RwIgd6RfXd7kzri12ydzoeFXsA2R9ju2YDxMv2xM9duQbqAhcKcyMQO2OpqZesti" }
Note
cert_user_field
specifies how the user name is extracted from the client certificate. The default value isCN
. This user must already exist. This parameter must be one of the following:CN: common name
OU: organizational unit
SN: surname
E: Email address
UID: User ID
E_ND: Email without domain; the data to the left of the @ sign in the email address is taken as the user name
Connect to the KMIP interface using the client certificate you want to register. It will automatically register the KMIP client corresponding to that certificate.
Note
If the client is mistakenly registered without a username, then you need to manually delete the registered client, before creating a new client. To delete a registered client, log into the console, navigate to KMIP > Registered Clients, and delete the client.
To Register a new KMIP Client
Create a json file for specifying properties to create a KMIP client profile. There are two ways to create a client profile:
Using csr
Using csr parameter
A detailed explanation of input parameters is provided after the examples.
profile.json: This file is a user input to CLI for providing profile parameters.
Note
The profile.json is just a place holder for name of file, user can choose any name for this file.
Note
To register a KMIP client using a client certificate generated by an external CA, during profile creation, the
cert_user_field
parameter is mandatory; whereas, the csr and csr parameters are not required.To register a KMIP client in a domain, first, authenticate the client in that domain using any of the domain authentication methods.
The authentication of the registered client certificate is based on the Subject DN of the certificate.
Example 1
{ "cert_user_field": "CN", "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIBCDCBjwIBADAQM...T0KnChXGc6JazA==\n-----END CERTIFICATE REQUEST-----\n" }
Example 2
{ "cert_user_field": "CN", "csr_cn": "user1", "csr_org_name": "Thales", "csr_org_unit": "Security", "csr_email": "abc@example.com", "csr_city": "Noida", "csr_state": "UP", "csr_country": "IN" }
** Parameter Explanation**
cert_user_field
: Specifies how the user name is extracted from the client certificate. The default value isCN
. This user must already exist. For more information, click here.Note
After registering the new KMIP client, cert_user_field setting of profile is used instead of the setting present in the interface.
csr: This is certificate signing request. The common name specified in CSR will be used to authenticate KMIP request.
Note
If the user is not present, then profile registration will fail.
Other parameters
If CSR is not provided, then CipherTrust Manager creates CSR using below input parameters from
profile.json
:csr_cn
: Common Name used to create CSR.csr_org_name
: Organization name to be used in CSR.csr_uid
: User ID used to create CSR.csr_org_unit
: Organizational unit to be used in CSR.csr_email
: Email address to be used in CSR.csr_city
: City name to be used in CSR.csr_state
: State name to be used in CSR.csr_country
: Country name to be used in CSR.
(Optional Step) Create a json file (for example,
device_cred.json
) for specifying device credential properties.Note
This step is optional and should be performed only when it is desired to authenticate the KMIP Client using device credentials.
Example 1
All fields in the example are optional, however, at least one field must be specified for a successful authentication using device credentials.
{ "serial_no": "12345", "password": "example_password_123", "device_id": "example_device_ID", "network_id": "sample_Network_ID", "machine_id": "MAC123456789", "media_id": "Media123456789" }
Parameters
serial_no
: Serial number of the device, for example the hardware serial number of the device.password
: Password for the device.device_id
: Device Identifier of the device.network_id
: Network identifier of the device, for example the MAC address for Ethernet connected devices.machine_id
: Machine identifier of the device, for example the client aggregator identifier, such as a tape library aggregating tape drives.media_id
: Media identifer of the device, for example the volume identifier used for a tape cartridge.
(Optional Step) Specify
do_not_modify_subject_dn
orsubject_dn_field_to_modify
:do_not_modify_subject_dn
: Specifies whether Subject DN in the CSR is allowed to be modified or not. If this flag is set totrue
, then Subject DN must be unique across all the CipherTrust Manager clients, otherwise client registration will not be allowed. The default value isfalse
. For details, refer to Renew Local CA Client Certificates.subject_dn_field_to_modify
: Makes Subject DN unique so that the client can be identified uniquely. The default value isUID
. For details, refer to Renew Local CA Client Certificates.
Example 1
ksctl kmip createprofile -p kmipprofile1 -c profile.json --configfile config_example.yaml --do_not_modify_subject_dn true
Example 2
ksctl kmip createprofile -p kmipprofile1 -c profile.json --configfile config_example.yaml --subject_dn_field_to_modify 'DNQ'
Create the KMIP profile using the json file created in step 1.
Request
ksctl kmip createprofile -p kmipprofile1 -c profile.json --configfile config_example.yaml
Note
If using device credentials, use the following request instead:
ksctl kmip createprofile -p kmipprofile1 -c profile.json -d device_cred.json --configfile config_example.yaml
Here,
device_cred.json
is the device credential file created in previous step.Response
{ "account": "kylo:kylo:admin:accounts:kylo", "application": "ncryptify:gemalto:admin:apps:kylo", "createdAt": "2019-12-18T10:19:32.745104774Z", "devAccount": "ncryptify:gemalto:admin:accounts:gemalto", "id": "70d92635-7e9f-4a9b-9161-d7f41b4e0109", "name": "kmipprofile1", "properties": { "csr_cn": "rajesh" }, "updatedAt": "2019-12-18T10:19:32.745104774Z", "uri": "kylo:kylo:nae:kmip_profile:kmipprofile1" }
Create a registration token using the profile created in the previous step.
If client registration is through local CA:
Request
ksctl kmip createkmipregtoken –p kmipprofile1 --configfile config_example.yaml
Note
The
profile_name
is required and must be present in the system before creating a registration token.Response
{ "id": "6b8f5397-b738-4160-8c39-7979bae280aa", "uri": "kylo:kylo:munshi:tokens:6b8f5397-b738-4160-8c39-7979bae280aa", "account": "kylo:kylo:admin:accounts:kylo", "application": "ncryptify:gemalto:admin:apps:kylo", "devAccount": "ncryptify:gemalto:admin:accounts:gemalto", "createdAt": "2019-12-18T10:29:26.701363932Z", "updatedAt": "2019-12-18T10:29:26.701363932Z", "token": "LW0heyZNXHE9sEKmu7B0zVqnwHns42tahMVWJYUkP6I5CI67RQLS0EDkZ96UiocI", "valid_until": "0001-01-01T00:00:00Z", "max_clients": -1, "cert_duration": 730, "clients_registered": 0, "ca_id": "efe1d302-7ff4-46ca-a2a4-c4d9236cc0f8", "label": { "KmipClientProfile": "kmipprofile1" } }
If client registration is through external CA:
Request
ksctl kmip createkmipregtoken –p kmipprofile1 --configfile <config_example.yaml> --ca_id <CA-Id-of-the-External-CA>
Note
To register a client using external CA, make sure to upload the external CA to CipherTrust Manager, and the
ca_id
parameter must be set to the ID of the uploaded external CA.Response
{ "id": "6b8f5397-b738-4160-8c39-7979bae280aa", "uri": "kylo:kylo:munshi:tokens:6b8f5397-b738-4160-8c39-7979bae280aa", "account": "kylo:kylo:admin:accounts:kylo", "application": "ncryptify:gemalto:admin:apps:kylo", "devAccount": "ncryptify:gemalto:admin:accounts:gemalto", "createdAt": "2019-12-18T10:29:26.701363932Z", "updatedAt": "2019-12-18T10:29:26.701363932Z", "token": "LW0heyZNXHE9sEKmu7B0zVqnwHns42tahMVWJYUkP6I5CI67RQLS0EDkZ96UiocI", "valid_until": "0001-01-01T00:00:00Z", "max_clients": -1, "cert_duration": 730, "clients_registered": 0, "ca_id": "efe1d302-7ff4-46ca-a2a4-c4d9236cc0f8", "label": { "KmipClientProfile": "kmipprofile1" } }
Register the new KMIP client using the registration token generated in the previous step.
If client registration is through local CA:
Request
ksctl kmip register -n KmipClient2 -t LW0heyZNXHE9sEKmu7B0zVqnwHns42tahMVWJYUkP6I5CI67RQLS0EDkZ96UiocI --kmipCertOutFile ClientCert.pem --kmipKeyOutFile ClientKey.pem --configfile config_example.yaml
Response
{ "cert": "-----BEGIN CERTIFICATE-----4xq+8sZ6PuwxePopPD2HWB+uxjLjdaKbO1wz5AEk...- N3e2ajOow/ZC2FxtkipCIyYdlTJ7P\n-----END CERTIFICATE-----\n", "client_ca": "-----BEGIN CERTIFICATE-----\kXLCgQWnp2Kp445v2ZAyf3CUwWnBBUzLZdpDkUkQpaloJaMkNXU2KFVxjyDT7cXM... v5jwHaYfqXImDs0bC/UZyEo+bnwFlA==\n-----END CERTIFICATE-----\n", "client_id": "ac8c7131-7dc4-4b1e-ab42-3529b4c4a497", "csr": "-----BEGIN CERTIFICATE REQUEST-----\nwSnPtpvJZU9kac0...2LfMJxmbnmAug2YM/\n-----END CERTIFICATE REQUEST-----\n", "key": "-----BEGIN RSA PRIVATE KEY-----zMTurUlUu9S9dc89ajkKJ...TlkMA/Gx0IOkpH1zMbJLf6NEgaOZbC1tCLjxB6YjQIgHfrTqupc=\n-----END RSA PRIVATE KEY-----\n" }
If client registration is through external CA:
Request
ksctl kmip register -n KmipClient2 -t LW0heyZNXHE9sEKmu7B0zVqnwHns42tahMVWJYUkP6I5CI67RQLS0EDkZ96UiocI --configfile config_example.yaml --cert <Path-to-External-Client-Certificate>
Response
{ "cert": "-----BEGIN CERTIFICATE-----4xq+8sZ6PuwxePopPD2HWB+uxjLjdaKbO1wz5AEk...- N3e2ajOow/ZC2FxtkipCIyYdlTJ7P\n-----END CERTIFICATE-----\n", "client_ca": "-----BEGIN CERTIFICATE-----\kXLCgQWnp2Kp445v2ZAyf3CUwWnBBUzLZdpDkUkQpaloJaMkNXU2KFVxjyDT7cXM... v5jwHaYfqXImDs0bC/UZyEo+bnwFlA==\n-----END CERTIFICATE-----\n", "client_id": "ac8c7131-7dc4-4b1e-ab42-3529b4c4a497", "csr": "", "key": "" }
Note
To register a client using an external CA, the
cert
parameter should specify the path of the client certificate.Use Client Certificate and Client Private Key to connect with the server.
User Impersonation
The CipherTrust Manager allows a client to impersonate a user for a client, meaning, the client can connect to the CipherTrust Manager as a user without providing the user credentials, on NAE and KMIP interfaces. By default, the user impersonation functionality is limited to impersonate users of the clients' domain (where the client is registered) only. Hence, user impersonation applies only to the users created in the clients' domain or assigned users (users created in the clients' domain and assigned to some other domain).
If you set the ALLOW_USER_IMPERSONATION_ACROSS_DOMAIN
property to true
, clients belonging to the root domain are allowed to impersonate the users created within sub-domains. The property is only applicable to NAE and KMIP interfaces. The default value of this property is false
.
ksctl properties modify --name ALLOW_USER_IMPERSONATION_ACROSS_DOMAIN --value true
Note
Make sure to restart the NAE service when you change the value of "ALLOW_USER_IMPERSONATION_ACROSS_DOMAIN" property.
KMIP Client Renewal
The CipherTrust Manager allows you to renew the certificate of a registered KMIP Client.
Note
The KMIP clients should use Admin's Renew Route for renewal. For details, refer to Renewing Client Certificates.
Supported Objects, Operations, Attributes, and Key Formats
The following KMIP Objects Types, Attributes, and Operations supported on CipherTrust Manager are in accordance with KMIP Specification Version 1.4.
Supported Object Types
Object | Object | Object |
---|---|---|
Symmetric Key | Public Key | Private Key |
Secret Data | Opaque Object | Certificate |
Supported Operations
Operation | Operation | Operation | Operation |
---|---|---|---|
Activate | Delete Attribute | Get Attributes List | Register |
Add Attribute | Destroy | Locate | Re-key |
Check | Discover Versions | MAC | Re-key Key Pair |
Create | Encrypt | MACV | Revoke |
Create Key Pair | Get | Modify Attribute | Sign |
Decrypt | Get Attributes | Query | SignV |
Note
CipherTrust Manager supports Wrapping and Unwrapping of Keys for Get and Register operations. To read more, go to Wrap/Unwrap support in KMIP for details.
Supported Attributes
Attribute | Attribute | Attribute |
---|---|---|
Unique Identifier | Name | Object Type |
Cryptographic Algorithm | Cryptographic Length | Cryptographic Parameters |
Cryptographic Domain Parameters | Cryptographic Usage Mask | Digital Signature |
State | Initial Date | Activation Date |
Process Start Date | Protect Stop Date | Deactivation Date |
Destroy Date | Compromise Occurrence Date | Compromise Date |
Revocation Reason | Link | Application Specific Information |
Contact Information | Object Group | Custom Attribute |
Fresh Attribute | Alternate Name | Digest Attribute |
Certificate Type | Certificate Length | X.509 Certificate Identifier |
X.509 Certificate Subject | X.509 Certificate Issuer | Certificate Identifier |
Certificate Subject | Certificate Issuer | Never Extractable |
Extractable | Operation Policy Name |
Note
For information on the above listed object Types, Operations, and Attributes, refer to the OASIS KMIP Documentation.
Note
The Operation Policy Name
attribute supports only 'default' value.
Note
The Fresh Attribute
, Custom Attribute
, Application Specific Information
, and Digest Attribute
are stored in the Key Meta.
Example 1
If a custom attribute (for example, AttributeName : x-attribute1, AttributeValue: value1
) is added to the key k1, then the attribute is stored in Key Meta as:
{
"kmip": {
"custom": [
{
"type": "TextString",
"x-attribute1": "Value1"
}
]
},
"ownerId": "local|261d8e87-73bb-4106-aa3d-06ed92e2f010",
"permissions": {}
}
Example 2
If an application specific attribute (for example, application_data": "data", "application_namespace": "Test"
) is added to a key, then the attribute is stored in Key Meta as:
{
"kmip": {
"app_specific_info": [
{
"application_data": "data",
"application_namespace": "TestASi"
}
]
},
"ownerId": "local|261d8e87-73bb-4106-aa3d-06ed92e2f010",
"permissions": {}
}
Supported Key Formats
Object Type | Key Formats |
---|---|
Symmetric | • Raw • Opaque |
Private Key | • PKCS_1 • PKCS_8 • PKCS_12 |
Public Key | • PKCS_1 • PKCS_8 |
Certificate | • PKCS_12 • X.509 |
Opaque | • Raw |
Secret | • Opaque |
Wrap/Unwrap support in KMIP
Key wrapping is used for encrypting data keys. This provides an additional layer of security in protecting keys when they are at rest or are being transmitted over insecure networks. A variety of key wrapping algorithms can be used to encrypt the data keys. Similarly, unwrap mechanisms are used to decrypting the data keys.
CipherTrust Manager supports wrapping/unwrapping of keys under Get and Register operations.
Note
Only Symmetric and Private keys can be wrapped/unwrapped in KMIP.
Supported wrapping methods are:
Encrypt
MACSign
Note
For Encrypt Wrapping Method:
Only AES and RSA keys can be used to wrap the symmetric keys.
Only AES-256 keys can be used to wrap private keys.
Note
For MACSign Wrapping Method:
Only HMAC keys can be used for MAC request.
Only RSA keys can be used for Sign request.
Encrypt Wrapping Method
Symmetric Data Keys | Symmetric Data Keys | Private Data Keys |
---|---|---|
Supported BlockCipher Modes for AES wrap keys | Supported padding methods for RSA wrap keys | Supported BlockCipher Mode for AES wrap keys |
• NISTKeyWrap (RFC-3394) • AESKeyWrapPadding (RFC-5649) | • PKCS1V1_5 • OAEP Supported Hash Algorithms for OAEP padding method: • SHA_1 • SHA_256 • SHA_384 • SHA_512 | • AESKeyWrapPadding (RFC-5649) |
MACSign Wrapping Method for Symmetric and Private Keys
MAC Request | Sign Request | Sign Request |
---|---|---|
Supported HMAC algorithms for HMAC wrap keys | Supported padding methods for RSA wrap keys | Supported DigitalSignatureAlgorithms for RSA wrap keys |
• HMAC_SHA_1 • HMAC_SHA_256 • HMAC_SHA_384 • HMAC_SHA_512 | • PKCS1V1_5 (Default) • PSS Supported Hash Algorithms for above padding methods: • SHA_1 • SHA_256 • SHA_384 • SHA_512 | • SHA_1WithRSAEncryption • SHA_256WithRSAEncryption • SHA_384WithRSAEncryption • SHA_512WithRSAEncryption |
Supported Encodings
NoEncoding
TTLVEncoding
For more information, visit OASIS Key Management Interoperability Protocol Documentation.
Opaque Key Format for Symmetric Keys
The CipherTrust Manager supports opaque key format type for symmetric keys in the REST/KMIP interface. The opaque key format type can be used during importing keys when key material is not raw. For more details, refer to OASIS Key Management Interoperability Protocol Documentation.
Example Request
<RequestMessage>
<RequestHeader>
<ProtocolVersion>
<ProtocolVersionMajor type="Integer" value="1"/>
<ProtocolVersionMinor type="Integer" value="2"/>
</ProtocolVersion>
<BatchCount type="Integer" value="1"/>
</RequestHeader>
<BatchItem>
<Operation type="Enumeration" value="Register"/>
<RequestPayload>
<ObjectType type="Enumeration" value="SymmetricKey"/>
<TemplateAttribute>
<Attribute>
<AttributeName type="TextString" value="Name"/>
<AttributeValue>
<NameValue type="TextString" value="OpaqueKey_AES128_1"/>
<NameType type="Enumeration" value="UninterpretedTextString"/>
</AttributeValue>
</Attribute>
<Attribute>
<AttributeName type="TextString" value="Cryptographic Usage Mask"/>
<AttributeValue type="Integer" value="Decrypt Encrypt"/>
</Attribute>
</TemplateAttribute>
<SymmetricKey>
<KeyBlock>
<KeyFormatType type="Enumeration" value="Opaque"/>
<KeyValue>
<KeyMaterial type="ByteString" value="000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f0e0f000102030741000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f0e0f000102030741"/>
</KeyValue>
<CryptographicAlgorithm type="Enumeration" value="AES"/>
<CryptographicLength type="Integer" value="128"/>
</KeyBlock>
</SymmetricKey>
</RequestPayload>
</BatchItem>
</RequestMessage>
Example Response
<ResponseMessage>
<ResponseHeader>
<ProtocolVersion>
<ProtocolVersionMajor type="Integer" value="1" />
<ProtocolVersionMinor type="Integer" value="2" />
</ProtocolVersion>
<TimeStamp type="DateTime" value="2022-02-15T07:31:37+00:00" />
<BatchCount type="Integer" value="1" />
</ResponseHeader>
<BatchItem>
<Operation type="Enumeration" value="Register" />
<ResultStatus type="Enumeration" value="Success" />
<ResponsePayload>
<UniqueIdentifier type="TextString" value="88021e1314ca4e03a6dac2ffd593ac91f801970257f240599224075c3e3f5d6d" />
</ResponsePayload>
</BatchItem>
</ResponseMessage>
Cryptographic Operations for KMIP
Using KMIP interface, you can perform following cryptographic operations:
Operations | Algorithms | Modes | Padding |
---|---|---|---|
Encrypt/Decrypt | AES | • ECB (default) • CBC • GCM • PKCS5 (default) • None | |
Encrypt/Decrypt | TDES | • ECB (default) • CBC | • PKCS5 (default) • None |
Encrypt/Decrypt | RSA | not applicable | • PKCS1V1_5 (default) • OAEP |
MAC/MACV | HMAC_SHA1 | not applicable | not applicable |
MAC/MACV | HMAC_SHA256 | not applicable | not applicable |
MAC/MACV | HMAC_SHA384 | not applicable | not applicable |
MAC/MACV | HMAC_SHA512 | not applicable | not applicable |
MAC/MACV | AES | CMAC | not applicable |
Caution
We recommend that you set the RandomIV
object in the Cryptographic Parameters
attribute to true for AES CBC, AES GCM, and TDES CBC encryption requests to have CipherTrust Manager generate a unique random IV with each request. The size of a generated random IV is always fixed to the cipher block size. CipherTrust Manager does not use Cryptographic Parameter objects such as Fixed Field Length
, Invocation Field Length
or Counter Length
to construct the random IV.
Otherwise, you can provide your own IV in the Request Payload as an IV/Counter/Nonce
object. If you or your KMIP vendor are providing IVs, follow NIST SP800-38A and NIST SP800-38D to ensure IVs are sufficiently unique and secure.
Recommended Curve Mappings
The recommended Curve mappings along with the respective Curve IDs are listed in the following table.
Curve | Curve ID |
---|---|
P-224 | secp224r1 |
P-256 | prime256v1 |
P-384 | secp384r1 |
P-521 | secp521r1 |
KMIP Interface Mode
The "interface mode" configuration parameter specifies the KMIP Interface mode, and must be one of the following:
tls-pw-opt: TLS, allow anonymous logins.
Username is not extracted from the client certificate.
If authentication request is sent in KMIP request, Username will be the owner of the key.
If authentication request is not sent in KMIP request, the Key Owner will be the ‘global’ user.
tls-cert-pw-opt: TLS, user name taken from client cert, auth request is optional.
Username is extracted from the registered client's Common Name specified during client's registration.
If authentication request is sent in KMIP request, then the Username in the authentication request will be the owner of the key.
tls-cert-and-pw: TLS, password is needed, user name specified during client's registration must match user name in authentication request.
Username is extracted from the registered client's Common Name specified during client's registration.
The inclusion of the authentication request in KMIP request is mandatory.
The Username in the authentication request must match with the registered client's Common Name specified during client's registration.
Tip
The interface mode can be changed using the API or the CLI "ksctl interfaces modify" command.
KMIP Interface mode mapping
Following table provides a mapping between the KMIP interfaces mode from SafeNet KeySecure Classic and CipherTrust Manager.
Safenet KeySecure Classic | CipherTrust Manager |
---|---|
Password authentication: Not Used Client cert authentication: SSL only | tls-pw-opt TLS, allow anonymous logins, verify client cert |
Password authentication: Optional Client cert authentication: SSL only | tls-pw-opt TLS, allow anonymous logins, verify client cert |
Password authentication: Required Client cert authentication: SSL only | tls-pw-req |
Password authentication: Not Used Client cert authentication: SSL with CN | tls-cert-pw-opt Verify client cert, user name taken from client cert, auth request is optional |
Password authentication: Optional Client cert authentication: SSL with CN | tls-cert-pw-opt Verify client cert, user name taken from client cert, auth request is optional |
Password authentication: Required Client cert authentication: SSL with CN | tls-cert-and-pw Verify client cert, password is needed, user name in cert must match user name in authentication request |
Managing KMIP Interface
You can add, remove, or modify KMIP interfaces.
To create a new KMIP interface:
Example
ksctl interfaces create -o 5697 -y kmip
Response
{
"id": "90b3b131-d6d8-4985-abdd-539162c136c3",
"name": "kmip_all_5697",
"mode": "tls-cert-pw-opt",
"cert_user_field": "CN",
"auto_gen_ca_id": "kylo:kylo:naboo:localca:c729ffe0-f6ad-49ad-8558-2db435b112c7",
"trusted_cas": {
"local": [
"kylo:kylo:naboo:localca:c729ffe0-f6ad-49ad-8558-2db435b112c7"
]
},
"createdAt": "2019-08-22T10:10:28.05794Z",
"updatedAt": "2019-08-22T10:10:28.05794Z",
"default_connection": "local_account",
"port": 5697,
"network_interface": "all",
"interface_type": "kmip"
}
Note
Interface can only be created in Root domain. To use interfaces in other domains, add the domain certificate to the Local Trusted CA of the domain.
Adding domain CA to the interface as external CA
To add domain CA to the interface as external CA:
Log on to the CipherTrust Manager GUI.
Switch to the desired domain.
Tip
To create a new domain, click here.
Navigate to CA > Local. The list of available CAs is displayed.
Click the ellipsis icon corresponding to the CA.
Click Copy/Download the local CA.
Switch to Root domain.
Navigate to CA > External.
Click Add External CA. The Add External Certificate screen appears.
Provide Display name.
Either upload or paste the Certificate that you copied/downloaded in the step 5.
Click Add External CA. The newly created external CA appears on the External Certificate Authorities page.
Navigate to Admin Settings > Interfaces.
Click kmip and select the external CA created in step 11 from the External Trusted CAs drop-down list.
Click Update.
To modify TLS version of an interface:
ksctl interfaces modify -n <interface name> -e <minimum tls version>
Here:
<interface name>
is KMIP interface name.<minimum tls version>
can betls_1_0
,tls_1_1
, ortls_1_2
.tls_1_1
andtls_1_0
are deprecated and will be discontinued in a future release.
Example
ksctl interfaces modify -n kmip_all_5697 -e tls_1_2
Response
{
"id": "6199c8d1-f59a-4bd1-8dfd-cf4d43900264",
"name": "kmip_all_5697",
"mode": "tls-cert-and-pw",
"cert_user_field": "CN",
"auto_gen_ca_id": "kylo:kylo:naboo:localca:afdebde8-a5ff-4cbd-9bb2-6dc5186e4c03",
"trusted_cas": {
"local": [
"kylo:kylo:naboo:localca:0a4bf97b-1294-41d2-93cd-d19e6290cfa3",
"kylo:kylo:naboo:localca:b7860db1-b7d1-4163-996e-22b14090d55a",
"kylo:kylo:naboo:localca:afdebde8-a5ff-4cbd-9bb2-6dc5186e4c03"
]
},
"createdAt": "2019-08-28T05:21:05.36768Z",
"updatedAt": "2019-08-28T07:41:38.62511Z",
"default_connection": "local_account",
"port": 5697,
"network_interface": "all",
"interface_type": "kmip",
"kmip_enable_hard_delete": 0,
"minimum_tls_version": "tls_1_2"
}
Viewing and Setting Log Level
You can view or change the log level of KMIP service using the "ksctl" CLI tool.
There are two subcommands in the logs command:
getlevel
: used for viewing the current log level of a servicesetlevel
: used for setting log level of a service
Using getlevel
To view the current log level for KMIP service, use the following request in CLI:
Request
ksctl logs getlevel --service kmip
Response
{
"level": "INF",
"service": "kmip"
}
Using setlevel
Note
Debug-level logging can generate a significant amount of detailed information that can impact the application's performance. Therefore, it is recommended not to configure the log level to "debug" mode.
To set current log level to debug for KMIP service, use the following request in CLI:
Request
ksctl logs setlevel --service kmip --level debug
Response
{
"level": "DBG",
"service": "kmip"
}
Supported levels are:
error
orERR
info
orINF
debug
orDBG
Note
To view the logs, go to
/opt/keysecure/logs
directory on appliance.To download the logs, use ksctl logs download command.
Only users with administrator privileges can change or set the log level.
When the log level is set to
debug
, sensitive data fromdebug
logs is masked. To unmask the sensitive data, contact Customer Support.
Note
Any ssl
connection related error message can be filtered from the log file based on ERR
and tls
tags.