Chapter 1: About This Manual

KMIP compliance

Alliance Key Manager supports and implements the Key Management Interoperability Protocol (KMIP) version 1.0. This implementation guide summarizes the KMIP support present in the Townsend Security server presented at the RSA OASIS KMIP Interop conference in February of 2013.

Please note that future releases of Alliance Key Manager may support later versions of KMIP. Please check with Townsend Security for the latest version of this document.

Change log

The following table provides information on the changes to this documentation:

Version Date Description
3.0.0.001 1/14/2014 Initial release.
3.0.0.002 8/20/2014 Updates. Add supported states, object types, and custom attribute types.

Chapter 2: KMIP Standard Support

Implementation notes

The Townsend Security server is a KMIP 1.0 server.

TLS connections with an X.509 client certificate are required for all KMIP operations.

  • Non-TLS connections for the Query operation are not supported.

  • Credential objects are not supported.

Symmetric Key objects and Template Objects are supported.

  • Other cryptographic objects and Certificate objects are not supported.

Symmetric Key objects can be registered using Raw or Transparent Symmetric Key formats.

  • Key Wrapping Data is not supported.

Supported operations:

  • Activate

  • Add Attribute

  • Check

  • Create

  • Delete Attribute

  • Destroy

  • Get

  • Get Attribute List

  • Get Attributes

  • Locate

  • Modify Attribute

  • Query

  • Register

  • Re-key

  • Revoke

These operations are not supported:

  • Archive

  • Cancel

  • Certify

  • Create Key Pair

  • Derive Key

  • Discover Versions

  • Get Usage Allocation

  • Notify

  • Obtain Lease

  • Poll

  • Put

  • Re-certify

  • Recover

  • Rekey Key Pair

  • Validate

Supported KMIP 1.0 attributes:

  • Activation Date

  • Application Specific Information

  • Compromise Date

  • Compromise Occurrence Date

  • Contact Information

  • Cryptographic Algorithm

  • Cryptographic Length

  • Cryptographic Parameters

  • Cryptographic Usage Mask

  • Deactivation Date

  • Digest

  • Initial Date

  • Last Change Date

  • Link

  • Name

  • Object Group

  • Object Type

  • Operation Policy Name

  • Process Start Date

  • Protect Stop Date

  • Revocation Reason

  • State

  • Unique Identifier

These KMIP 1.0 attributes are not supported:

  • Archive Date

  • Certificate Identifier

  • Certificate Issuer

  • Certificate Subject

  • Certificate Type

  • Cryptographic Domain Parameters

  • Destroy Date

  • Lease Time

  • Usage Limits

Supported KMIP states:

  • Pre-active

  • Active

  • Deactivated

  • Compromised

These KMIP states are not supported:

  • Destroyed

  • Destroyed Compromised

Supported KMIP object types:

  • Symmetric Key

  • Template

These KMIP object types are not supported:

  • Certificate

  • Public Key

  • Private Key

  • Opaque Object

  • Split Key

  • Secret Data

The following custom attribute types are supported:

  • Structure

  • Integer

  • Long Integer

  • Big Integer

  • Enumeration

  • Boolean

  • Text String

  • Byte String

  • Date-Time

  • Interval

The following Townsend Security custom server attributes are available:

  • y-SQL Server Thumbprint: This is the thumbprint used by SQL Server to identify this key when using the EKM provider.

  • y-Key Name: This corresponds to the “Key Name” in the AKM Administrative Console (Admin Console). This name is shared by all instances (versions) of the key.

  • y-Instance: This corresponds to the “Key Instance” in the Admin Console. Each KMIP key corresponds to one AKM Key Instance.

  • y-Current: This corresponds to the “Current” instance of the key in the Admin Console. This is the most recently generated key instance.

  • y-Destroy Permitted: When y-Destroy Permitted is false, you cannot delete this key. This corresponds to the “Deletable” key policy in the Admin Console.

  • y-Mirrored: This corresponds to the “Mirror Key” policy in the Admin Console.

  • y-Auto Re-key Interval In Days: This corresponds to the “Automatic” Rollover Code in the Admin Console. If set to 30, for example, the key will automatically roll in 30 days. Each key (i.e. instance) rolls once. The new key instance inherits the same policy (i.e. will itself roll in another 30 days.)

  • y-Re-key Permitted: When false, you are not allowed to roll this key instance. This corresponds to the “Never” Rollover Code in the Admin Console.

  • y-Access Check: This corresponds to the “Get Key Access Flag” in the Admin Console.

  • y-Metadata: An optional structure containing up to 16 text fields. This corresponds to the “Metadata” field options in the Admin Console.

Chapter 3: KMIP Conformance

Conformance summary

The following table summarizes the KMIP conformance of Alliance Key Manager. The table was created by the OASIS support team at the RSA conference and is used here by permission.

image alt text

*The numbers in the right column represent a fractional coverage of the KMIP operations, states, etc.

Chapter 4: Alliance Key Manager Interfaces

Communications interfaces

Alliance Key Manager implements the KMIP service on port 5696 (the standard KMIP port) using TLS secure communication. This port number is configurable in the Alliance Key Manager configuration file. In the configuration file you must enable the KMIP service, define the local IP address for the TLS service, and define the port number as 5696, the default KMIP port.

Here is an example of enabling KMIP in the AKM configuration file (akm.conf):

KmipPortEnabled=Y
KmipIP=192.168.1.129
KmipPort=5696

See the AKM Server Management Guide for information on modifying the AKM configuration file.

Chapter 5: Implementation Notes

KMIP does not require a key name, but the AKM server does. When a key is created on the KMIP interface without a key name, the AKM server will automatically generate a key name based on the new instance ID (i.e. KMIP unique identifier). The name will be based on a hexadecimal representation of the original instance, for example:

Instance: iiX1WZ/GQs9I7nUs0VDbjwAA
Automatic key name: KEY-8a25f5599fc642cf48ee752cd150db8f

From the KMIP interface, this key name will remain fixed when the key is rolled (re-keyed). The name is removed from the original key (i.e. original instance) and passed to the new key (i.e. rollover instance). The original key will no longer have this name, but the new key will. From the AKM interface, the original key and all rollover key instances will also share the original instance name.

Using a hexadecimal representation of the original instance creates a unique name which can be used by AKM (instance names could have characters such as ‘/’ which are illegal in AKM names). The name should also not be tied to the original instance, since in KMIP the name moves from key to key as the keys are rolled. Allowing a KMIP Create without a name parameter helps support interoperating clients and use-case tests that do not pass a name.

Keep the following considerations in mind when implementing KMIP for AKM:

1) When an Authentication object is received in the Request Header, the entire Request Message is rejected out of hand and the client receives “Operation Failed” status with an “Authentication Not Successful” result reason.

From page 12 of the KMIP Usage Guide Version 1.0:

“KMIP implementations that support the KMIP-defined Credential Types or use other vendor-specific mechanisms for authentication may use the optional Authentication field specified inside the Request Header to include additional identification information. Depending on the server’s configuration, the server may interpret the identity of the requestor from the Credential object, contained in the Authentication structure if it is not provided during the channel-level authentication. For example, in addition to performing mutual authentication during a TLS handshake, the client passes the Credential object (e.g., a username and password) in the request. If the requestor’s username is not specified inside the client certificate and is instead specified in the Credential object, the server interprets the identity of the requestor from the Credential object. This supports use cases where channel-level authentication authenticates a machine or service that is used by multiple users of the KMIP server. If the client provides the username of the requestor in both the client certificate and the Credential object, the server verifies that the usernames are the same. If they differ, the authentication fails and the server returns an error. If no Credential object is included in the request, the username of the requestor is expected to be provided inside the certificate. If no username is provided in the client certificate and no Credential object is included in the request message, the server is expected to refuse authentication and return an error.

If authentication is unsuccessful, and it is possible to return an “authentication not successful” error, this error should be returned in preference to any other result status. This prevents status code probing by a client that is not able to authenticate.”

2) The Batch Order Continuation Option, if specified in the Request Header, must be Stop. Continue and Undo are not supported.

3) Message Extension in a Batch Item is not recognized for any vendor. If specified, Criticality Indicator must be False. If True, the Batch Item will fail.

4) You are not allowed to delete the Name Attribute at index 0.

5) There is no historical record kept of destroyed objects. This is not a requirement of a KMIP server.

6) Metadata fields of skeys are accessible using the custom server attribute y-Metadata. This attribute is only available for symmetric keys, representing the sixteen Metadata fields in skeys as fields in a structure attribute. Client may modify, but not delete Metadata fields.