KMIP Key Management in C
CADP CAPI KMIP supports Key Management using KMIP protocol for communication with the KMIP compliant server. For API details, refer to the KMIP Key Management API section in the CADP for C CAPI API Guide. To use KMIP with CADP CAPI, you must set the following parameters in the properties file:
KMIP_Spec_File
KMIP_IP
KMIP_Port
Protocol
CA_File
Cert_File
Key_File
Note
Additional parameters can be set for additional features. To use the KMIP Key Management, the Protocol parameter should be set to ssl.
For details on KMIP parameters, refer to 'The Parameters'. For details on KMIP, visit:
http://www.oasis-open.org/standards#kmip
KMIP supports optional user authentication. If user chooses to authenticate a session then for every KMIP request sent within the session, authentication with valid username and password is required. Authentication will be done on the basis of Common Name (CN) in SSL client certificate.
Note
To run the KMIP Key Management sample applications, OpenSSL 1.1.1g or later must be installed on your machine.
Supported Attributes
| Attribute Name | Description |
|---|---|
| Application Specific Information | A structure used to store data specific to the application(s) using the Managed Object. It consists of two fields: an Application Namespace and Application Data specific to that application namespace. |
| Unique ID | Generated by the CipherTrust Manager to uniquely identify the managed object. |
| Name | Used to identify and locate an object. This attribute is assigned by the client and is composed of a name value and a name type. The CipherTrust Manager supports name type string. |
| Object Type | Describes the type of object: Symmetric Key, Template, or Secret Data. |
| Cryptographic Algorithm | The algorithm used by the object, e.g., DES, AES, RSA. |
| Cryptographic Length | The length, in bits, of the cleartext cryptographic key material. |
| Cryptographic Usage Mask | The cryptographic usage of a key. This is a bit mask that indicates to the client which cryptographic functions MAY be performed using the key, and which ones SHALL NOT be performed. |
| Digest (Only SHA 256) | Contains the digest value of the key or secret data. The CipherTrust Manager only creates a SHA-256 digest. Digest is composed of a hashing algorithm and a digest value. |
| Initial Date | The date and time when the managed object was first created or registered by the CipherTrust Manager. |
| Activation Date | The date and time when the managed cryptographic object may begin to be used for applying cryptographic protection to data. |
| Process Start Date | The date and time when a managed symmetric key object may begin to be used for processing cryptographically protected data. |
| Protect Stop Date | The date and time when a managed symmetric key object may no longer be used for applying cryptographic protection to data. |
| Deactivation Date | The date and time when the managed cryptographic object may no longer be used for any purpose, except for decryption, signature verification, or unwrapping, but only under extraordinary circumstances and when special permission is granted. |
| Object Group | A group of objects. An object may belong to more than one group of objects. |
| Contact Information | User-defined contact information. This information is not used for policy enforcement. |
| Custom Attribute | Client- or server-defined attributes intended for vendor-specific purposes. Custom attribute structures are not supported. |
| Link | A structure used to create a link from one Managed Cryptographic Object to another closely related target Managed Cryptographic Object. |
Supported Objects
| Object Name | Description |
|---|---|
| Symmetric Key | Contains the client-settable attributes of a managed cryptographic object. Templates are used to specify the attributes of a new managed cryptographic object in various operations and are intended to be used to specify the cryptographic attributes of new objects in a standardized, convenient way. Supported attributes are shown in the section below. |
| Asymmetric Key Public Key (with PKCS#1 key format) | The public portion of an asymmetric key pair. This is only a public 388 key, not a certificate. |
| Private Key (with PKCS#1 and PKCS#8) | The private portion of an asymmetric key pair. |
| Template | Asymmetric key. This object is composed of a key block. |
| Secret Data | Contains a shared secret value that is not a key or certificate (e.g. a password). Composed of a secret data type and a key block. |
| Certificate | The certificate. |
Note
Opaque objects are not supported.
Supported Operations
| Operation Name | Description |
|---|---|
| Register | Requests that the server register a managed object that was created by the client or obtained by the client through some other means, allowing the server to manage the object. The arguments in the request are similar to those in the Create operation, but may also contain the object itself for storage by the server. Optionally, objects that are not to be stored by the key management system (for example, private keys) may be omitted from the request. The request contains information about the type of object being registered and some of the attributes to be assigned to the object (e.g., Cryptographic Algorithm, Cryptographic Length, etc). This information may be specified by the use of a Template-Attribute object. The response contains the Unique Identifier assigned by the server to the registered object. The server copies the Unique Identifier returned by this operations into the ID Placeholder variable. The Initial Date attribute of the object is set to the current time. Templates, secret data, symmetric keys, asymmetric keys, public keys, private keys, symmetric key without key bytes, and certificates are supported. Register template operations using an existing template name are not supported. To register all the objects except asymmetric keys, use the I_KC_Register API.To register asymmetric keys, use the I_KC_RegisterAsymmetricKey API. |
| Create | Requests that the server generate a new symmetric key as a managed object. This operation is not used to create a Template object. The request contains information about the type of object being created, and some attributes to assign to the object (for example, Cryptographic Algorithm, Cryptographic Length, and so on). This information can be specified by the names of the already existing Template objects. The response contains the Unique Identifier of the created object. The server copies the Unique Identifier returned by this operation into the ID Placeholder variable. |
| CreateKeyPair | Requests that the server generates a new asymmetric key pair as a managed object. |
| Locate | Requests that the server search for one or more managed objects. The maximum number of items returned is 100,000. Wild cards are not supported. The server supports only online objects, so if the storage-status mask excludes online object, the search returns empty. All supported attributes are valid. Date matching is supported. Locate operation using wild cards and regular expressions is not supported. |
| Locate Linked Keys | Requests that the server search for one or more linked keys. The maximum number of linked keys returned is 100,000. |
| Get | Requests that the server return the managed object specified by its unique identifier. Only a single object is returned. The response contains the object’s unique identifier and the object itself. Compression and wrapping are not supported. |
| GetAttributes | Requests one or more attributes of a managed object. The object is specified by its unique identifier. Attributes are specified by their name. If the specified attribute has multiple instances, then all instances are returned. If a specified attribute does not exist, then it is not present in the returned response. If none of the attributes exist, the response consists only of the unique identifier. If no attribute name is specified in the request, the server will act as if all attributes match the request. |
| GetAttributeList | Requests a list of attribute names associated with a Managed Object. The object is specified by its Unique Identifier. The request contains the Unique Identifier of the key whose attribute list is to be retrieved. The response contains the list of all attributes present for the particular key. |
| GetWrappedKey | Requests that the server return the wrapped key bytes for a key. |
| AddAttribute | Requests that the server add a new attribute instance to a managed object and set its value. The request contains the Unique Identifier of the associated managed object, the attribute name, and its value. For non-multi-instance attributes, the attribute value is created in this way. For multi-instance attributes, the first and subsequent values are created in this way. Existing attribute values can only be changed by the modify attribute operation. Read-only attributes cannot be added using the Add Attribute operation. No Attribute Index can be specified in the request. The response returns a new Attribute Index. Although, the Attribute Index can be omitted if the index of the added attribute instance is 0. Multiple Add Attribute requests may be included in a single-batched request to add multiple attributes. |
| ModifyAttribute | Requests that the server modify the value of an existing attribute instance associated with a managed object. The request contains the Unique Identifier of the managed object whose attribute is to be modified, the attribute name, optional Attribute Index, and the new value. Only existing attributes can be changed through Modify Attribute operation. New attributes should only be added through the Add Attribute operation. If an Attribute Index is specified, then only the specified instance of the attribute is modified. If the attribute has multiple instances, and no Attribute Index is specified in the request, then the Attribute Index is assumed to be 0. If the attribute does not support multiple instances, then the Attribute Index should not be specified. Specifying an Attribute Index for which no Attribute Value exists will result in an error. |
| DeleteAttribute | Requests that an attribute associated with a Managed Object be deleted. The request contains the Unique Identifier of the Managed Object whose attribute is to be deleted, the attribute name, and optionally the Attribute Index of the attribute. Attributes that always require a value can never be deleted by this operation. If no Attribute Index is specified, and the Attribute whose name is specified has multiple instances, then the operation is REJECTED. Only a single attribute instance shall be deleted at a time. Multiple delete operations (possibly batched) are necessary to delete several attribute instances. Attempting to delete a non-existent attribute or specifying an Attribute Index for which there exists NO Attribute Value results in an error. |
| Destroy | Requests that the key material for a managed object be destroyed. Our implementation of KMIP does not retain metadata. Once the managed object is destroyed, its metadata is erased, too. Because our KMIP implementation does not support object state, there is no state requirement when destroying objects - cryptographic objects can be destroyed regardless of their state. |
| Query | Requests information about the server’s capabilities and/or protocol mechanisms. The server vendor identification is Thales. The server information contains a structure with three extension tags: • 0x541000: Device Model • 0x541001: Device ID (box ID) • 0x541002: Device Software Version |
| Revoke | Requests the key material for a managed object be revoked. In case a key is compromised or is not intended to be used in future, the user may revoke the key. For Revoke operation, It is mandatory to pass a Revocation Reason. Revocation Reason list: • Unspecified • KeyCompromise • CACompromise • AffiliationChanged • Superseded • CessationOperation • PrivilegeWithdrawn If the Revocation Reason is ‘KeyCompromise’ then it is mandatory to pass a Compromise Occurrence Date. |
| DiscoverVersions | Requests all the versions of KMIP Protocol supported by the CipherTrust Manager. |
| ReKey | Requests that the server generates a new replacement symmetric or asymmetric key as a managed object. It is same as create operation except for that attributes of replacement key are copied from the existing key. Request for creating rekey for symmetric key contains Unique Identifier of symmetric key to be rekeyed. Request for creating rekey for asymmetric key contains Unique Identifier of private key to be rekeyed. Attribute and offset can also be sent in request. Offset indicates interval between initialization date and activation date of replacement key to be created. Response contains Unique Identifier of newly created replacement symmetric or asymmetric key and also contains attributes. |
| Crypto | Requests encryption and decryption using managed object as the key for operation. Encryption request contains information about the cryptographic parameters (mode and padding method), data to be encrypted and the IV to be used. The parameters may also be provided as the associated attributes of the Managed cryptographic object. A random IV is generated on behalf of the client, if the encrypt request does not contain the IV. The response includes the key i.e. the unique identifier of the managed cryptographic object, the IV and the encrypted text. Decryption request includes information about the cryptographic parameters, mode and padding method, data to be decrypted and the IV to be used. The parameters may also be provided as the associated attributes of the Managed cryptographic object. The decrypt request may not contain the IV if the algorithm does not use an IV. The response includes the key i.e. the unique identifier of the managed cryptographic object and the decrypted text. This operation is supported by KMIP 1.2 for the following algorithms: • AES • AES/GCM • RSA For this operation, the I_KC_Crypto API is used. |
Batching
Every KMIP operation is part of a batch and there can be multiple operation requests in a single batch. It means multiple requests clubbed together in a single batch can be sent to the server.
CADP CAPI KMIP versions prior to 6.1.0 support only single operation per batch. CADP CAPI KMIP 8.6.1 supports multiple operations per batch. This feature allows the client to send single request to the server for performing multiple operations. These operations need not necessarily be related to each other. Similarly, the server sends response to client requests in batches of multiple operations. The batch is considered as an object, which facilitates better management and handling of operations under the batch.
The following functions are included to support the batching feature:
I_KC_CreateBatch(): Creates a batch and returns a pointer to the batch; the batch actually is an API level object, which initially has an empty list of operations. There are flags to specify the behavior of the batch.I_KC_ExecuteBatch(): Triggers the execution of the batch created so far. It has two responsibilities. One is to prepare the request from the batch object as specified in KMIP standards and send the batch to server for execution. The other responsibility is to parse the response received from the server, and prepare the output objects and store them in batch with respect to the operations.I_KC_AddOperation(): Allows a user to add one or more operations to the batch. The function generates and returns a unique identifier for each operation in the batch. The arguments are copied and stored in the batch along with the operation.I_KC_DeleteOperation(): Searches for the operation as specified by the operation ID and deletes the operation from the batch.I_KC_GetResponse(): Searches for the output objects with respect to the operation ID in the batch and returns a pointer to OpOutResult, which holds the result code as well as the output object list.I_KC_ResetBatch(): Resets the batch as specified by the supported flag values.I_KC_DestroyBatch(): Destroys the batch object and performs cleanup as appropriate.I_KC_FreeResultObject(): Destroys the OpOutResult object and performs cleanup as appropriate.
For details, refer to the CADP for C CAPI API Guide.
Valid Arguments
The following table lists operation codes, corresponding number of valid arguments, arguments, and the order in which they should be used:
| Operation Code | No. of Arguments | Argument 1 | Argument 2 | Argument 3 |
|---|---|---|---|---|
| I_KT_Operation_ Code_ Create | 2 | I_KT_Agr_AttributeList | I_KT_Agr_ObjectType | |
| I_KT_Operation_ Code_ Register | 2 | I_KT_Agr_AttributeList | I_KT_Agr_Object | |
| I_KT_Operation_ Code_ Locate | 3 | I_KT_Agr_AttributeList | I_KT_Agr_StorageStatusMask | I_KT_Agr_UnsignedInt |
| I_KT_Operation_ Code_Get | 2 | I_KT_Agr_AttributeList | I_KT_Agr_GetRequest | |
| I_KT_Operation_ Code_ GetAttributes | 1 | I_KT_Agr_AttributeList | ||
| I_KT_Operation_ Code_ GetAttributes | 2 | I_KT_Agr_AttributeList | I_KT_Agr_AsciiStringList | |
| I_KT_Operation_ Code_ GetAttributesList | 1 | I_KT_Agr_AttributeList | ||
| I_KT_Operation_ Code_ AddAttribute | 1 | I_KT_Agr_AttributeList | ||
| I_KT_Operation_ Code_ ModifyAttribute | 1 | I_KT_Agr_AttributeList | ||
| I_KT_Operation_ Code_ DeleteAttribute | 3 | I_KT_Agr_AttributeList | I_KT_Agr_AsciiString | I_KT_Agr_UnsignedInt |
| I_KT_Operation_ Code_ Destroy | 1 | I_KT_Agr_AttributeList | ||
| I_KT_Operation_ Code_ Query | 1 | I_KT_Agr_QueryFunction |
Note
The order of arguments must be the same as mentioned in the table above. Argument 1 must be specified before Argument 2 and Argument 3. Similarly, Argument 2 should be specified before Argument 3. For example, arguments for I_KT_Operation_Code_Locate operation should be in the following order: I_KT_Agr_AttributeList, I_KT_Agr_StorageStatusMask, I_KT_Agr_UnsignedInt.
Note
Configuring KMIP (by setting the KMIP_IP parameter in the properties file) using I_C_OpenSession with the I_T_Auth_Password parameter may not work. This happens because the Credential Base Object is not supported using I_T_Auth_Password. However, you can use the I_T_AuthNoPassword parameter for _no credentials_ and I_T_Auth_KMIP for credentials-based objects.
Limitation
Register template operations using an existing template name are not supported.
Create operation does not support HMAC algorithms and key creation from template.
Locate operations using wildcard characters and regular expressions are not supported.
