Skip to content

Open source Python implementation of the KMIP specification.

License

Notifications You must be signed in to change notification settings

Robert-Campbell-256/PyKMIP

 
 

Repository files navigation

PyKMIP

Latest Version travis-status codecov-status python-versions

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

Usage

Client

The KMIP client, kmip.pie.client.ProxyKmipClient, provides support for the following operations:

  • Create
  • CreateKeyPair
  • Register
  • DeriveKey
  • Locate
  • Get
  • GetAttributes
  • GetAttributeList
  • Activate
  • Revoke
  • Destroy
  • Encrypt
  • Decrypt
  • Sign
  • SignatureVerify
  • MAC

For examples of how to create and use the client, see the scripts in kmip/demos/pie.

Configuration

The 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'
)

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

Server

In addition to the KMIP client, 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:

  • Create
  • CreateKeyPair
  • Register
  • DeriveKey
  • Locate
  • Get
  • GetAttributes
  • Activate
  • Revoke
  • Destroy
  • Query
  • DiscoverVersions
  • Encrypt
  • Decrypt
  • Sign
  • SignatureVerify
  • MAC

Configuration

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
policy_path=/path/to/policy/file
enable_tls_client_auth=True
tls_cipher_suites=
    TLS_RSA_WITH_AES_128_CBC_SHA256
    TLS_RSA_WITH_AES_256_CBC_SHA256
    TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
logging_level=DEBUG

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',
    policy_path='/etc/pykmip/policies',
    enable_tls_client_auth=True,
    tls_cipher_suites=[
        'TLS_RSA_WITH_AES_128_CBC_SHA256',
        'TLS_RSA_WITH_AES_256_CBC_SHA256',
        'TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384'
    ],
    logging_level='DEBUG'
)

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 5696 according 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_path and the certificate_path should 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 Basic and TLS1.2. Note: TLS1.2 can 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 KmipServer constructor. 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 KmipServer constructor. Defaults to /var/log/pykmip/server.log.
  • policy_path
    A string representing a path to the filesystem directory containing PyKMIP server operation policy JSON files.
  • enable_tls_client_auth
    A boolean indicating whether or not extension checks should be performed on client certificates to verify that they can be used to derive client identity. This setting is enabled by default for backwards compatibility and must be explicitly disabled if this behavior is not desired.
  • tls_cipher_suites
    A list of strings representing the set of cipher suites to use when establishing TLS connections with new clients. Enable debug logging for more information on the cipher suites used by the client and server.
  • logging_level
    A string indicating what the base logging level should be for the server. Options include: DEBUG, INFO, WARNING, ERROR, CRITICAL. The DEBUG log level logs the most information, the CRITICAL log level logs the least.

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.

Usage

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.

Identity & Ownership

The software server determines client identity using the client's TLS certificate. Specifically, the common name of the certificate subject is used as the client ID. Additionally, the client certificate must have an extended key usage extension marked for client authentication. If this extension is not included in the client certificate and/or the client does not define a subject and common name, the server will fail to establish a client session. For more information on certificates and their use in authentication, see RFC 5280.

The client identity described above is used to anchor object ownership. Object ownership and access is governed by an object's operation policy, defined on object creation. By default the KMIP specification defines two operation policies, a default policy covering all objects and a public policy applied only to Template objects.

For example, if user A creates a symmetric key, user B will only be able to retrieve that key if the key's operation policy indicates that the key is accessible to all users. If the operation policy specifies that the key is only available to the owner, only user A will be able to access it.

Users can create their own operation policies by placing operation policy JSON files in the policy directory pointed to by the policy_path configuration option. The server will load all policies from that directory upon start up, allowing users to use those policies for their objects. A template for the operation policy JSON file can be found under examples. Note that the default and public policies are reserved and cannot be redefined by a user's policy.

Development

Testing

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.

Platforms

PyKMIP has been tested and runs on the following platform(s):

  • Ubuntu: 12.04 LTS, 14.04 LTS, 16.04 LTS

PyKMIP is supported by Python 2.7 and 3.3 - 3.6.

References

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:

About

Open source Python implementation of the KMIP specification.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Python 100.0%