PyKMIP is a Python implementation of the Key Management Interoperability Protocol (KMIP). KMIP is a client/server communication protocol for the storage and maintenance of key, certificate, and secret objects. The standard is governed by the Organization for the Advancement of Structured Information Standards (OASIS). PyKMIP supports a subset of features in versions 1.0 - 1.2 of the KMIP specification.
For a high-level overview of KMIP, check out the KMIP Wikipedia page. For comprehensive documentation from OASIS and information about the KMIP community, visit the KMIP Technical Committee home page.
There are two implementations of the KMIP client. The first,
kmip.services.kmip_client.KMIPProxy, is the original client and provides
support for the following operations:
CreateCreateKeyPairRegisterLocateGetGetAttributeListActivateRevokeDestroyQueryDiscoverVersions
The second client, kmip.pie.client.ProxyKmipClient, wraps the original
KMIPProxy and provides a simpler interface. It provides support for the
following operations:
CreateCreateKeyPairRegisterGetGetAttributeListDestroy
For examples of how to create and use the different clients, see the scripts
in kmip/demos.
A KMIP client can be configured in different ways to connect to a KMIP server. The first method is the default approach, which uses settings found in the PyKMIP configuration file. The configuration file can be stored in several different locations, including:
<user home>/.pykmip/pykmip.conf/etc/pykmip/pykmip.conf<PyKMIP install>/kmip/pykmip.conf<PyKMIP install>/kmip/kmipconfig.ini
These locations are searched in order. For example, configuration data found
in /etc will take priority over configuration information found in the
PyKMIP installation directory. The kmipconfig.ini file name is supported
for legacy installations. Users can specify the connection configuration
settings to use on client instantiation, allowing applications to support
multiple key storage backends simultaneously, one client per backend.
An example client configuration settings block is shown below:
[client] host=127.0.0.1 port=5696 keyfile=/path/to/key/file certfile=/path/to/cert/file cert_reqs=CERT_REQUIRED ssl_version=PROTOCOL_SSLv23 ca_certs=/path/to/ca/cert/file do_handshake_on_connect=True suppress_ragged_eofs=True username=user password=password
The second configuration approach allows developers to specify the
configuration settings when creating the client at run time. The following
example demonstrates how to create the ProxyKmipClient, directly
specifying the different configuration values:
client = ProxyKmipClient(
hostname='127.0.0.1',
port=5696,
cert='/path/to/cert/file/',
key='/path/to/key/file/',
ca='/path/to/ca/cert/file/',
ssl_version='PROTOCOL_SSLv23',
username='user',
password='password',
config='client')
A KMIP client will load the configuration settings found in the client
settings block by default. Settings specified at runtime, as in the above
example, will take precedence over the default values found in the
configuration file.
Many of these settings correspond to the settings for ssl.wrap_socket,
which is used to establish secure connections to KMIP backends. For more
information, check out the Python SSL library documentation.
In addition to the KMIP clients, PyKMIP provides a basic software
implementation of a KMIP server, kmip.services.server.KmipServer.
However, the server is intended for use only in testing and demonstration
environments. The server is not intended to be a substitute for a secure,
hardware-based key management appliance. The PyKMIP client should be used for
operational purposes only with a hardware-based KMIP server.
The KMIP server provides support for the following operations:
CreateCreateKeyPairRegisterGetDestroyQueryDiscoverVersions
The PyKMIP software server can be configured via configuration file, by
default located at /etc/pykmip/server.conf. An example server
configuration settings block, as found in the configuration file, is shown
below:
[server] hostname=127.0.0.1 port=5696 certificate_path=/path/to/certificate/file key_path=/path/to/certificate/key/file ca_path=/path/to/ca/certificate/file auth_suite=Basic
The server can also be configured manually. The following example shows how
to create the KmipServer in Python code, directly specifying the
different configuration values:
server = KmipServer(
hostname='127.0.0.1',
port=5696,
certificate_path='/path/to/certificate/file/',
key_path='/path/to/certificate/key/file/',
ca_path='/path/to/ca/certificate/file/',
auth_suite='Basic',
config_path='/etc/pykmip/server.conf',
log_path='/var/log/pykmip/server.log'
)
NOTE: The kmip_server.KMIPServer implementation of the software
server is deprecated and will be removed in a future version of PyKMIP.
The different configuration options are defined below:
hostname- A string representing either a hostname in Internet domain notation or an IPv4 address.
port- An integer representing a port number. Recommended to be
5696according to the KMIP specification.
certificate_path- A string representing a path to a PEM-encoded server certificate file. For more information, see the Python SSL library documentation.
key_path- A string representing a path to a PEM-encoded server certificate key file.
The private key contained in the file must correspond to the certificate
pointed to by
certificate_path. For more information, see the Python SSL library documentation.
ca_path- A string representing a path to a PEM-encoded certificate authority
certificate file. If using a self-signed certificate, the
ca_pathand thecertificate_pathshould be identical. For more information, see the Python SSL library documentation.
auth_suite- A string representing the type of authentication suite to use when
establishing TLS connections. Acceptable values are
BasicandTLS1.2. Note:TLS1.2can only be used with versions of Python that support TLS 1.2 (e.g,. Python 2.7.9+ or Python 3.4+). If you are running on an older version of Python, you will only be able to use basic TLS 1.0 authentication. For more information, see the Python SSL library documentation and the Key Management Interoperability Protocol Profiles Version 1.1 documentation.
config_path- A string representing a path to a server configuration file, as shown
above. Only set via the
KmipServerconstructor. Defaults to/etc/pykmip/server.conf.
log_path- A string representing a path to a log file. The server will set up a
rotating file logger on this file. Only set via the
KmipServerconstructor. Defaults to/var/log/pykmip/server.log.
NOTE: When installing PyKMIP and deploying the KMIP software server, you
must manually set up the server configuration file. It will not be placed
in /etc/pykmip automatically.
The software server can be run using the bin/run_server.py startup script.
If you are currently in the PyKMIP root directory, use the following command:
$ python bin/run_server.py
If you need more information about running the startup script, pass -h
to it:
$ python bin/run_server.py -h
NOTE: You may need to run the server as root, depending on the permissions of the configuration, log, and certificate file directories.
If PyKMIP is installed and you are able to import kmip in Python, you can
copy the startup script and run it from any directory you choose.
The KMIP standard includes various profiles that tailor the standard for specific use cases (e.g., symmetric key storage with TLS 1.2). These profiles specify conformance to certain operations and attributes.
The PyKMIP KMIPProxy client provides full support for the following
profile(s):
- Basic Discover Versions Client KMIP Profile
The development plan for PyKMIP follows the requirements for the following KMIP profiles. The foundation for symmetric and asymmetric key operation support is already built into the library.
Client profiles:
- Basic Baseline Client KMIP Profile
- Basic Symmetric Key Store Client KMIP Profile
- Basic Symmetric Key Foundry Client KMIP Profile
- Basic Asymmetric Key Store Client KMIP Profile
- Basic Asymmetric Key Foundry Client KMIP Profile
Server profiles:
- Basic Discover Versions Server KMIP Profile
- Basic Baseline Server KMIP Profile
- Basic Symmetric Key Store and Server KMIP Profile
- Basic Symmetric Key Foundry and Server KMIP Profile
- Basic Asymmetric Key Store Server KMIP Profile
- Basic Asymmetric Key Foundry and Server KMIP Profile
The PyKMIP test suite is composed of two parts, a unit test suite and an
integration test suite that runs various tests against instantiations of the
software KMIP server and real KMIP appliances. The tests are managed by a
combination of the tox, pytest, and flake8 libraries.
There are several ways to run different versions of the tests. To run, use one of the following commands in the PyKMIP root directory.
To run all of the unit tests:
$ tox
To run the Python syntax and format compliance tests:
$ tox -e pep8
To run the unit test suite against Python 2.7:
$ tox -e py27
The integration tests require a configuration flag whose value corresponds to
the name of a client configuration section in the pykmip.conf
configuration file. See the Usage section for more information.
To run the integration test suite with a specific configuration setup:
$ tox -e integration -- --config <section-name>
For more information and a list of supported tox environments, see
tox.ini in the PyKMIP root directory.
PyKMIP has been tested and runs on the following platform(s):
- Ubuntu 12.04 LTS
PyKMIP is supported by Python 2.6, 2.7, 3.3, and 3.4.
NOTE: Support for Python 2.6 will be deprecated in a future release of PyKMIP.
The source code for PyKMIP is hosted on GitHub and the library is available for installation from the Python Package Index (PyPI):
For more information on KMIP version 1.1, see the following documentation: