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

TLS 1.0 and 1.1 are deprecated and support will be discontinued in a future release.

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, it 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:

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

2. Using New Certificate

   You can create a new certificate using the local CA on the CipherTrust Manager. You can also register new KMIP client using a certificate signed by an external CA. For detailed steps, refer to the section To Register a new KMIP Client.

Specifying LDAP and Multi-Domain Client Usernames in KMIP Certificates

The connection and/or username can be specified in 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 local user in a specific domain. For example, domain||joe.

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)

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

2. 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 to true, then providing registration token in -r is mandatory.

   A new KMIP interface can also be created with the -a and -r parameters.

   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 and tls-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"
   }
   

   cert_user_field specifies how the user name is extracted from the client certificate. The default value is CN. 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

3. Connect to the KMIP interface using the client certificate you want to register. It will automatically register the KMIP client corresponding to that certificate.

   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

1. Create a json file for specifying properties to create a KMIP Client Profile. A KMIP client profile contains a set of properties, on basis of which, the KMIP client gets registered. There are two ways to create a 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.

   The profile.json is just a place holder for name of file, user can choose any name for this file.

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

   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 is CN. This user must already exist. For more information, click here.

     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.

     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.

2. (Optional Step) Create a json file (for example, device_cred.json) for specifying device credential properties.

   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.

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

   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"
   }
   

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

   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>
   

   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"
           }
       }
   

5. 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": ""
   }
   
   To register a client using an external CA, the cert parameter should specify the path of the client certificate.
   

6. Use Client Certificate and Client Private Key to connect with the server.

Supported Objects, Operations, and Attributes

The following KMIP Objects Types, Attributes, and Operations supported on CipherTrust Manager are in accordance with KMIP Specification Version 1.4.

Supported Object Types

Supported Operations

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

For information on the above listed object Types, Operations, and Attributes, refer to the OASIS KMIP Documentation.

Fresh Attribute, Custom Attribute, Application Specific Information, and Digest Attribute are stored in the Key Meta.

If you are creating a key through UI, use Alias (KMIP Name) available in the Key Properties section to specify the KMIP key name.

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": "TestASi") 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":{

    }
}

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.

Only Symmetric and Private keys can be wrapped/unwrapped in KMIP

Supported wrapping methods are:

• Encrypt

• MACSign

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.

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

MACSign Wrapping Method for Symmetric and Private Keys

Supported Encodings

• NoEncoding

• TTLVEncoding

For more information, visit OASIS Key Management Interoperability Protocol Documentation.

Cryptographic Operations for KMIP

Using KMIP interface, you can perform following cryptographic operations:

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.

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.

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.

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"
}

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.

To modify TLS version of an interface:

$ ksctl interfaces modify  -n  -e 

Here:

• <interface name> is KMIP interface name.

• <minimum tls version> can be tls_1_0, tls_1_1, or tls_1_2. tls_1_1 and tls_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 service

• setlevel: 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

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 or ERR

• info or INF

• debug or DBG

• 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 from debug logs is masked. To unmask the sensitive data, contact Customer Support.

Any ssl connection related error message can be filtered from the log file based on ERR and tls tags.