KMIPclient

Created: 12 July 2013
Updated: 01 November 2013
Contributors: Bill Becker,

Summary

The volume encryption blueprint [1] and specification [2] describe a key manager interface that allows different types of key managers to be used. This blueprint proposes to use the defined key management interface to communicate with a key manager that supports the OASIS Key Management Interoperability Protocol (KMIP). Any KMIP Key Manager that supports the defined interfaces will be able to manage the encryption keys used in the volume encryption feature. This approach of adding a KMIP client to OpenStack provides a secure key management option for the volume encryption keys while also allowing OpenStack integration into KMIP compliant enterprise key management systems which are already managing keys for other systems and applications.

System Architecture

As described in the Volume Encryption Specification [2], one goal was to support a key manager that implements OASIS KMIP. To support a KMIP key manager, a KMIP client needs to be implemented at the key manager interface. The below diagram is a copied from the volume encryption specification [2] with the addition of a KMIP Client for communication with an external key management appliance.

To add support for an external KMIP key manager, the following need to be implemented:

A KMIP client needs to be added to OpenStack.
A “Mock KMIP Key Manager” needs to be added to OpenStack to simulate the Key Management Appliance shown the diagram. This mock key manager should be used for testing purposes only and would be replaced with fully featured Key Management server or appliance that supports the same interfaces used by the Mock KMIP Key Manager.
A method to configure the KMIP client with parameters needed to allow communications with the key manager.

The following diagram shows the relationship between the 3 items defined in this KMIP Client blueprint, the existing key manager interface defined in the volume encryption blueprint, and an external KMIP key manager. {note: I need to update diagram to show auth token validation between KMIP Key Manager and Keystone}

System Design

KMIP Client

The following diagram is copied from the Volume Encryption Specification [2] for convenience:

A KMIP client written in python would be implemented to support the KeyManager interface (i.e. it is the KMIPKeyManager shown in above diagram). Currently (29 Oct 2013) the KeyManager interface [3] defines five methods:

create_key( )
store_key( )
get_key( )
delete_key( )
copy_key( )

The above methods would be implemented using with the following equivalent operations defined in section 4 (Client-to-Server Operations) of the KMIP standard [6]:

create
register
get
destroy
'get' followed by 'register'

Detailed design will map the parameters defined in the OpenStack key manager interface methods to the KMIP object types, template attributes, and attributes. For example, how do all the items in OpenStack create_key (below) relate to KMIP create operation which includes Object Type and Template-Attribute payloads?

def create_key(self, ctxt, algorithm='AES', length=256, expiration=None,**kwargs)

Mock KMIP Key Manager

The “Mock KMIP Key Manager” is modeled after the existing MockKeyManager [3] in complexity / functionality but also implements the KMIP server protocol. Like the MockKeyManager, the Mock KMIP Key Manager should not be used for anything but integration testing.

The Mock KMIP Key Manager would be python code. Similar to the MockKeyManager [3], it would implement the KMIP equivalents of create_key, store_key, get_key, delete_key, and copy_key.

KMIP Config

It is expected that the OpenStack KMIP client could be configured to communicate with any KMIP compliant key manager. The configuration parameters needed to establish secure communications to the KMIP Key Manager will be stored in the KMIP section of nova.conf config file. The type of parameters maintained in KMIP Config include {preliminary list which needs to be updated}:

Network location (e.g. IPv4 address) of KMIP Key Manager
Port number for KMIP Key Manager
KMIP client authentication data: location of client SSL private key and certificate files.
KMIP Key Manager authentication data: location of trusted CA cert file.
Others TBD.

Authentication

As required in the KMIP Spec [6] and further defined in the KMIP Profiles [7], KMIP clients and server are mutually authenticated. As defined in the KMIP Profiles [7] and KMIP Usage Guidance [8], TLS will be used between the OpenStack KMIP client and KMIP Key Manager.

In addition, the key manager interface will pass a Keystone token to the KMIP client. This can be used by KMIP Key Manager as part of its authorization processing.

KMIP Authentication Capabilities

The KMIP Usage Guide [8] accurately describes the authentication and security model implemented in KMIP. A few of the relevant points are summarized here for convenience:

Message Security (section 2.2) describes how KMIP relies on the chosen authentication suite as specified in KMIP-Prof [7] to authenticate the client and on the underlying transport protocol to provide confidentiality, integrity, message authentication and protection against replay attack.

Authentication (section 3.1) describes the optional client authentication that can be done via KMIP objects in addition to the channel level (e.g. TLS) authentication. An example is provided with username / password at KMIP level in addition to channel level authentication with conclusion “This supports use cases where channel-level authentication authenticates a machine or service that is used by multiple users of the KMIP server.”

Credential (section 3.1.1) describes how the Credential structure can be used to provide additional identification information beyond that provided by the channel level (e.g. TLS). It describes how this supports use cases where channel-level authentication may only authenticate a machine or service that is used by multiple clients of the KMIP server. It focuses on the two currently defined credential types, but this is extensible.

Application Specific Information (section 3.28) allows storing data as an attribute of a managed object. Examples provided such as: SMIME, 'someuser@company.com'

The KMIP Spec [6] provides details on the different objects and attributes. A few of the relevant points are summarized here for convenience:

Section 6.6 describes the optional authentication object which includes the credential structure defined in section 2.1.2. As of v1.1 of the KMIP spec, there are only two credential types defined (section 9.1.3.2.1): username and password and device, although extensions are allowed. Server policy determines whether the authentication object is required.

Provisions are included for Application Specific Information attributes (section 3.36) on each managed object and also Custom Attrributes (section 3.39). These may be useful in conveying OpenStack specific information (such as the user context or Keystone token of the key owner) from to client to the key manager.

The KMIP Profiles spec [7] provides details on the different combinations of authentication methods, objects, and attributes that make up commonly used “profiles”. A few of the relevant points are summarized here for convenience:

The Basic Authentication Suite (section 3.1) requires that “KMIP client and server SHALL use TLS to negotiate a mutually-authenticated connection”. The client authenticity can be determined from the Credential information, if present. If not present, the client identity information is taken from the channel authentication (i.e. TLS).

Sections 4 and 5 define profiles based on the type of objects being managed (e.g. symmetric keys, certificates, etc.), key management server capabilities, and authentication suite. There are probably one or two profiles that align with the needs of OpenStack.

OpenStack Request Context

Currently the request context contains, among other items, the user_id and auth_token. Here is the structure that is passed as the request context:

RequestContext.py

     def __init__(self, user_id, project_id, is_admin=None, read_deleted="no",
                roles=None, remote_address=None, timestamp=None,
                request_id=None, auth_token=None, overwrite=True,
                quota_class=None, user_name=None, project_name=None,
                service_catalog=None, instance_lock_checked=False, **kwargs):

Keystone Integration

There are a few ways of integrating and interacting with Keystone. One method is installation and configuration of Keystone middleware [10] to authenticate the user based on information passed in via the user request context. Using the middleware, the external key manager could authenticate the user before authorizing the requested function (e.g. get_key) to complete.

The Keystone client can also be used by a calling service to validate a user’s auth token. Given that the calling client includes the auth_token in the user context sent to the external key manager, the key manager could use an installed Keystone client to make a call to keystone service to validate the token.

Similar to using the Keystone client, the key manager could use the keystone APIs [11] directly to determine if the user auth token is valid.

Proposed Design

The TLS session must be validated (KMIP requirement) during establishment of the secure channel. The identity information from the TLS authentication would NOT be used as the KMIP client identity, rather the Credential object will be used as client identity.

The KMIP client receives the above OpenStack request context structure in the call to the Key Manager interface. In the context of KMIP, this will be treated as a Credential object. It does not match the currently defined Credential types, so we can either use a custom type and/or approach KMIP TC to define a new one for OpenStack. The KMIP client passes the “context” to the KMIP server as a Credential object.

The Key Mgmt Server uses the Credential object to hook into the OpenStack identity and authorization infrastructure. If Keystone PKI tokens are used, the Key Mgmt server would validate the token included in the Credential object by contacting the Keystone service using the Keystone client or Keystone API to validate the identity information (user or auth token) contained in the Credential.

Key Management Server Recommendations

Design of external key management servers is outside the scope of this specification. However this specification will provide a set of recommended capabilities that should be implemented to support KMIP client in OpenStack.

Integrated Key Management Server

The key management server should support use of OpenStack identities in a method consistent with the OpenStack architecture. In the context of KMIP, the key management server would support separation of the TLS secure channel from the KMIP authentication.

The key management server should include an ability to securely communicate with the Keystone service (including having a service identity for use in TLS session).

The key management server should include an ability to establish a mutually authenticated TLS session with the OpenStack KMIP client.

It is unknown, but unlikely, if any existing KMIP compliant key management servers support the user defined credential type; so that functionality would likely need to be added to key management servers. And the ability to interpret this custom credential type as an OpenStack user context, including user id, auth token, etc.

The key management server should have the ability to interact with the Keystone service via client or API. The primary functionality should include the ability to verify the auth tokens passed via KMIP authentication with the keystone service.

Standalone Key Management Server

There may be systems in which a standalone key management server is used. In this use case the key management server would not interface with the keystone service. The key manager would perform an acceptable level of authentication based on the client identity conveyed in the TLS session with the KMIP client. The server may also process the OpenStack context in the KMIP payload via a local user authentication service.

Transport

As required in the KMIP Spec [6] and further defined in the KMIP Profiles [7], KMIP clients and server takes place over a secure transport protocol. The KMIP client will establish a TLS session to the key management server. The KMIP client will use the nova service identity (i.e. private key and certificate).

Questions / Concerns

TLS Implementation – KMIP requires the use of a secure communications protocol (i.e. TLS). Does this TLS implementation need to be part of the KMIP Client code, or is it better / possible to leverage existing TLS functionality. Answer: The KMIP client will use the underlying TLS functionality to establish the TLS session to key management server.
Authentication context token – The volume encryption key manager interface will pass a Keystone token to the KMIP client. Need to design how this can be consumed by KMIP Key Managers. It will likely differ based on the KMIP Key Manager being used, but it would be useful to provide an example of how it can be used within a KMIP Key Manager’s authorization systems. Answer: See recommendations in previous sections through the use of KMIP credential.
Key Metadata / Attributes—Need to resolve the relationship between the a parameters defined in the key manager interface and the key metadata / attributes that are typically used by KMIP key managers. Are there needed parameters that are missing? Answer: Needed parameters are defined.
Real KMIP Key Manager testing – The Mock KMIP Key Manager is only intended for testing purposes. To promote interoperability, SafeNet can make a real KMIP Key Manager appliance (and/or virtual appliance) available over the internet for interoperability testing. Is this of interest?

Future Releases

Although this design adds a KMIP client to specifically support volume encryption keys, KMIP key managers typically have broad support for a variety of different key types and thus could be used to manage the diverse set of keys used within OpenStack. Based on the adoption rate of this solution, it is expected that this KMIP client design could be enhanced and/or replicated in future releases to allow other OpenStack features to communicate with enterprise key managers via the industry standard KMIP protocol.

References

[1] https://blueprints.launchpad.net/nova/+spec/encrypt-cinder-volumes Blueprint for Encryption of Attached Cinder Volumes.

[2] https://wiki.openstack.org/wiki/VolumeEncryption OpenStack Volume Encryption Specification

[3] https://review.openstack.org/30973 code for Create Key Manager Interface

[4] https://review.openstack.org/30976 code for Add Encryption Support for Volumes

[5] https://review.openstack.org/30974 code for related cinder change to Add Encryption Metadata to Volume Table.

[6] [KMIP-v1.1] Key Management Interoperability Protocol Specification Version 1.1. 24 January 2013. OASIS Standard. http://docs.oasis-open.org/kmip/spec/v1.1/os/kmip-spec-v1.1-os.html.

[7] [KMIP-Prof] Key Management Interoperability Protocol Profiles Version 1.1. 21 September 2012. Candidate OASIS Standard 01. http://docs.oasis-open.org/kmip/profiles/v1.1/cos01/kmip-profiles-v1.1-cos01.html

[8] [KMIP-G] Key Management Interoperability Protocol Usage Guide Version 1.1. 27 July 2012. OASIS Committee Note 01.http://docs.oasis-open.org/kmip/ug/v1.1/cn01/kmip-ug-v1.1-cn01.html.

[9] https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=kmip#technical OASIS KMIP TC web site.

[10] http://docs.openstack.org/developer/keystone/middlewarearchitecture.html Keystone Middleware Architecture

[11] http://api.openstack.org/api-ref-identity.html Identity Service API