Server

Warning

The PyKMIP server is intended for testing and demonstration purposes only. It is not a replacement for a secure, hardened, hardware-based key management appliance. It should not be used in a production-level environment, nor for critical operations.

The PyKMIP server is a software implementation of a KMIP-compliant key management appliance. It supports over a dozen key management operations, including key lifecycle management, object metadata access, and cryptographic functions like encrypting and signing data.

The server is used to test the functionality of the PyKMIP client and library and is primarily intended as a testing and demonstration tool.

Configuration

The server settings can be managed by a 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
database_path=/tmp/pykmip.db

The server can also be configured manually via Python. The following example shows how to create the KmipServer in Python code, directly specifying the different configuration values:

>>> from kmip.services.server import KmipServer
>>> 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',
...     database_path='/tmp/pykmip.db'
... )

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 ssl 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 ssl 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 ssl 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 ssl 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, and CRITICAL. The DEBUG log level logs the most information, the CRITICAL log level logs the least.

  • database_path

    A string representing a path to a SQLite database file. The server will store all managed objects (e.g., keys, certificates) in this file.

Note

When installing PyKMIP and deploying the server, you must manually set up the server configuration file. It will not be placed in /etc/pykmip automatically. See /examples in the PyKMIP repository for a boilerplate configuration file to get started.

Third-Party Authentication

To configure third-party authentication plugins, separate configuration blocks must be specified in the server configuration file.

Note

Third-party authentication settings can only be set in the server configuration file. There is no way to set them using the KmipServer constructor in Python code.

An example authentication plugin configuration settings block is shown below:

[auth:slugs]
enabled=False
url=http://127.0.0.1:8080/slugs/

All authentication plugin configuration settings blocks must begin with the string auth:. For more information on third-party authentication integration, see Third-Party Integration.

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:

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.

PyKMIP also defines a system-wide entry point that can be used to run the PyKMIP server once PyKMIP is installed. You can use the entry point like this:

$ pykmip-server

Storage

All data storage for the server is managed via SQLAlchemy. The current backend leverages SQLite, storing managed objects in a flat file. The file location can be configured using the database_path configuration setting. By default this file will be located at /tmp/pykmip.database. If this database file is deleted, the stored objects will be gone for good. If this file is preserved across server restarts, object access will be maintained.

Note

Updates to the server data model will generate errors if the server is run with a pykmip.database file adhering to an older data model. There is no upgrade path.

Long term, the intent is to add support for more robust database and storage backends available through SQLAlchemy. If you are interested in this work, please see Development for more information.

Authentication

Client authentication for the PyKMIP server is currently enforced by the validation of the client certificate used to establish the client/server TLS connection. If the client connects to the server with a certificate that has been signed by a certificate authority recognized by the server, the initial connection is allowed. If the server cannot validate the client’s certificate, the connection is blocked and the client cannot access any objects stored on the server.

If client authentication succeeds, the identity of the client is obtained from the client’s certificate. The server will extract the common name from the certificate’s subject distinguished name and use the common name as the identity of the client. If the enable_tls_client_auth configuration setting is set to True, the server will check the client’s certificate for the extended key usage extension (see RFC 5280). In this case the certificate must have the extension marked for client authentication, which indicates that the certificate can be used to derive client identity. If the extension is not present or is marked incorrectly, the server will not be able to derive the client’s identity and will close the connection. If the enable_tls_client_auth configuration setting is set to False, the certificate extension check is omitted.

Once the client’s identity is obtained, the client’s request is processed. Any objects created or registered by the client will be marked as owned by the client identity. This identity is then used in conjunction with KMIP operation policies to enforce object access control (see Access Control).

Third-Party Integration

Beyond validating the client’s certificate and extracting the client identity from the certificate’s subject distinguished name, the server also supports a configurable framework for third-party authentication. This allows the server to integrate with existing authentication systems.

For each enabled third-party authentication plugin, the server will query the associated third-party service to verify that the user identified by the client certificate is a valid user. If validation succeeds, the server will also query the service for information pertaining to any groups the user may belong to. This information is leveraged for fine-grained access control (see Access Control). No other plugins are queried once a validation success has occurred. If validation fails, the server will attempt to authenticate with the next enabled plugin. If validation fails for all enabled plugins, the server will reject the client’s request and close the connection. Validation only needs to succeed for one authentication plugin for client authentication to succeed.

If no third-party authentication plugins are enabled, the server will skip third-party authentication and will rely solely on client certificate validation for client authentication. Note that in this case, no user group information is available for fine-grained access control.

For more information on configuring third-party authentication plugins, see Third-Party Authentication.

Supported third-party authentication plugins are discussed below.

SLUGS

The Simple, Lightweight User Group Services (SLUGS) library is an open-source web service that serves user/group membership data over a basic REST interface. It is intended as an easy-to-use stopgap for developers and deployers interested in leveraging third-party authentication with the PyKMIP server.

All SLUGS plugin configuration settings blocks must begin with the string auth:slugs. Multiple SLUGS plugins can be configured at once; simply add a unique suffix to the block name to distinguish it from other blocks (e.g., auth:slugs:primary, auth:slugs:secondary).

The different configuration options supported by the SLUGS plugin are defined below:

  • enabled
    A boolean indicating whether or not the authentication plugin should be used for authentication.
  • url
    A string representing the URL at which to access a SLUGS REST interface.

For more information on SLUGS, see SLUGS.

Access Control

Access control for server objects is managed through KMIP operation policies. An operation policy is a set of permissions, indexed by object type and operation. For any KMIP object type and operation pair, the policy defines who is allowed to conduct the operation on the object type.

There are three basic permissions currently supported by KMIP:

  • Allow All
    This permission indicates that any client authenticated with the server can conduct the corresponding operation on any object of the corresponding type.
  • Allow Owner
    This permission restricts the operation to any client authenticated and identified as the owner of the object.
  • Disallow All
    This permission blocks any client from conducting the operation on the object and is usually reserved for static public objects or tasks that only the server itself is allowed to perform.

For example, let’s examine a simple use case where a client wants to retrieve a symmetric key from the server.

  1. The client submits a Get request to the server (see Get), including the UUID of the symmetric key it wants to retrieve.
  2. The server will derive the client’s identity and then lookup the object with the corresponding UUID.
  3. If the object is located, the server will check the object’s operation policy attribute for the name of the operation policy associated with the object.
  4. The server will then use the operation policy, the client’s identity, the object’s type, the object’s owner, and the operation to determine if the client can retrieve the symmetric key.
  5. If the operation policy has symmetric keys and the Get operation mapped to Allow All, the operation is allowed for the client regardless of the client’s identity and the symmetric key is returned to the client. If the permission is set to Allow Owner, the server will return the symmetric key only if the client’s identity matches the object’s owner. If the permission is set to Disallow All, the server will refuse to return the symmetric key, regardless of the client’s identity.

While an operation policy can cover every possible combination of object type and operation, it does not have to. If a policy does not cover a specific object type or operation, the server defaults to the safest option and acts as if the permission was set to Disallow All.

Each KMIP object is assigned an operation policy and owner upon creation. If no operation policy is included in the creation request, the server automatically assigns it the default operation policy. The default operation policy is defined in the KMIP specification and is built into the PyKMIP server; it cannot be redefined or overridden by the user or server administrator. For more information on reserved policies, see Reserved Operation Policies.

Policy Files

In addition to the built-in operation policies, the PyKMIP server allows users to define their own operation policies via policy files. A policy file is a basic JSON file that maps names for policies to tables of access controls. The server dynamically loads policy files from the policy directory, which is defined by the policy_path configuration setting. The server tracks any changes made to the policy directory, supporting the addition, modification, and/or removal of policy files and/or policies within those files. This allows users and administrators to modify and update their policies while the server is running, without any downtime. Note that it is up to the server administrator to ensure that user-defined policies do not overwrite each other by using identical policy names. Should this occur, the server will cache older policies, dynamically restoring them should the naming collision be corrected.

An example policy file, policy.json, is included in the examples directory of the PyKMIP repository. Let’s take a look at the first few lines from the policy:

{
    "example": {
        "preset": {
            "CERTIFICATE": {
                "LOCATE": "ALLOW_ALL",
                "CHECK":  "ALLOW_ALL",
...

The first piece of information in the policy file is the name of the policy, in this case example. The name maps to collections of operation policies, grouped into two sets. The first set, shown here, is the preset collection. The preset collection contains rules that are used when user group information is unavailable; this is usually the case when third-party authentication is disabled. The preset collection rules consist of a set of object types, which in turn are mapped to a set of operations with associated permissions. In the snippet above, the first object type supported is CERTIFICATE followed by two supported operations, LOCATE and CHECK. Both operations are mapped to the ALLOW_ALL permission. Putting this all together, all clients are allowed to use the LOCATE and CHECK operations with certificate objects under the example policy, regardless of who owns the certificate being accessed. If you examine the full example file, you will see more operations listed, along with additional object types.

The second collection of operation policies that can be found in an operation policy file is the groups collection. This collection is used to provide group-based access control to objects. The following snippet is similar to the above snippet, reworked to use groups instead of preset:

{
    "example": {
        "groups": {
            "group_A": {
                "CERTIFICATE": {
                    "GET": "ALLOW_ALL",
                    "DESTROY": "ALLOW_ALL",
                    ...
            },
            "group_B": {
                "CERTIFICATE": {
                    "GET": "ALLOW_ALL",
                    "DESTROY": "DISALLOW_ALL",
                    ...

Like the prior snippet, the policy name is example. However, unlike the preset collection shown before, the groups collection first maps to a series of group names, in this case group_A and group_B. Each group maps to a set of object types and then access controls, following the same structure used by preset. The controls mapped under each group are distinct. This allows the policy to provide segregated access controls for groups of users, making it easy to share objects managed by the server while retaining fine-grained access control. In this case, any user belonging to group_A will be able to retrieve and destroy certificates using the example policy. Users in group_B will also be able to retrieve these certificates, but they will be unable to destroy them. Users belonging to both groups will receive the most permissive permissions available across the set of controls, meaning these users will be able to retrieve and destroy certificates since the controls under group_A are the most permissive.

The preset and groups collections can be included in the same policy. For example:

{
    "example": {
        "preset": {
            "CERTIFICATE": {
                "DESTROY": "DISALLOW_ALL",
                ...
        },
        "groups": {
            "group_A": {
                "CERTIFICATE": {
                    "DESTROY": "ALLOW_ALL",
                ...
            },
            "group_B": {
                "CERTIFICATE": {
                    "DESTROY": "DISALLOW_ALL",
                    ...
            }
        }
    }
}

As stated above, the controls belonging to the groups collection are only enforced if user group information is available after client authentication. If client authentication succeeds but no group information is available, the controls belonging to the preset collection are enforced. This allows users to effectively enable/disable group-level access controls if applicable to their use case. If group information is provided but only preset controls are defined, the preset controls will be enforced. If group information is not provided but only groups controls are defined, Disallow All will be the only enforced control for the policy. This ensures that the policy behaves according to user expectations.

Finally, a single policy file can contain multiple policies:

{
    "example_1": {
        "preset": {
            "CERTIFICATE": {
                "DESTROY": "DISALLOW_ALL",
                ...
        }
    },
    "example_2": {
        "groups": {
            "group_A": {
                "CERTIFICATE": {
                    "DESTROY": "ALLOW_ALL",
                ...
            },
            "group_B": {
                "CERTIFICATE": {
                    "DESTROY": "DISALLOW_ALL",
                    ...
            }
        }
    }
}

The above snippet shows two policies, example_1 and example_2. Each contains a different set of rules, one leveraging a preset collection and the other using the groups collection. While defined in the same JSON block, these policies are distinct from one another and are treated as separate entities. All of the previously defined rules and conventions for policies still apply.

Reserved Operation Policies

The PyKMIP server defines two reserved, built-in operation policies: default and public. Both of these policies are defined in the KMIP specification. Neither can be renamed or overridden by user-defined policies. The default policy is used for newly created objects that are not assigned a policy by their creators, though it can be used by creators intentionally. The public policy is intended for use with template objects that are public to the entire user-base of the server.

The following tables define the permissions for each of the built-in policies.

default policy

Object Type Operation Permission
Certificate Locate Allow All
Certificate Check Allow All
Certificate Get Allow All
Certificate Get Attributes Allow All
Certificate Get Attribute List Allow All
Certificate Add Attribute Allow Owner
Certificate Modify Attribute Allow Owner
Certificate Delete Attribute Allow Owner
Certificate Obtain Lease Allow All
Certificate Activate Allow Owner
Certificate Revoke Allow Owner
Certificate Destroy Allow Owner
Certificate Archive Allow Owner
Certificate Recover Allow Owner
Symmetric Key Rekey Allow Owner
Symmetric Key Rekey Key Pair Allow Owner
Symmetric Key Derive Key Allow Owner
Symmetric Key Locate Allow Owner
Symmetric Key Check Allow Owner
Symmetric Key Get Allow Owner
Symmetric Key Get Attributes Allow Owner
Symmetric Key Get Attribute List Allow Owner
Symmetric Key Add Attribute Allow Owner
Symmetric Key Modify Attribute Allow Owner
Symmetric Key Delete Attribute Allow Owner
Symmetric Key Obtain Lease Allow Owner
Symmetric Key Get Usage Allocation Allow Owner
Symmetric Key Activate Allow Owner
Symmetric Key Revoke Allow Owner
Symmetric Key Destroy Allow Owner
Symmetric Key Archive Allow Owner
Symmetric Key Recover Allow Owner
Public Key Locate Allow All
Public Key Check Allow All
Public Key Get Allow All
Public Key Get Attributes Allow All
Public Key Get Attribute List Allow All
Public Key Add Attribute Allow Owner
Public Key Modify Attribute Allow Owner
Public Key Delete Attribute Allow Owner
Public Key Obtain Lease Allow All
Public Key Activate Allow Owner
Public Key Revoke Allow Owner
Public Key Destroy Allow Owner
Public Key Archive Allow Owner
Public Key Recover Allow Owner
Private Key Rekey Allow Owner
Private Key Rekey Key Pair Allow Owner
Private Key Derive Key Allow Owner
Private Key Locate Allow Owner
Private Key Check Allow Owner
Private Key Get Allow Owner
Private Key Get Attributes Allow Owner
Private Key Get Attribute List Allow Owner
Private Key Add Attribute Allow Owner
Private Key Modify Attribute Allow Owner
Private Key Delete Attribute Allow Owner
Private Key Obtain Lease Allow Owner
Private Key Get Usage Allocation Allow Owner
Private Key Activate Allow Owner
Private Key Revoke Allow Owner
Private Key Destroy Allow Owner
Private Key Archive Allow Owner
Private Key Recover Allow Owner
Split Key Rekey Allow Owner
Split Key Rekey Key Pair Allow Owner
Split Key Derive Key Allow Owner
Split Key Locate Allow Owner
Split Key Check Allow Owner
Split Key Get Allow Owner
Split Key Get Attributes Allow Owner
Split Key Get Attribute List Allow Owner
Split Key Add Attribute Allow Owner
Split Key Modify Attribute Allow Owner
Split Key Delete Attribute Allow Owner
Split Key Obtain Lease Allow Owner
Split Key Get Usage Allocation Allow Owner
Split Key Activate Allow Owner
Split Key Revoke Allow Owner
Split Key Destroy Allow Owner
Split Key Archive Allow Owner
Split Key Recover Allow Owner
Template Locate Allow Owner
Template Get Allow Owner
Template Get Attributes Allow Owner
Template Get Attribute List Allow Owner
Template Add Attribute Allow Owner
Template Modify Attribute Allow Owner
Template Delete Attribute Allow Owner
Template Destroy Allow Owner
Secret Data Rekey Allow Owner
Secret Data Rekey Key Pair Allow Owner
Secret Data Derive Key Allow Owner
Secret Data Locate Allow Owner
Secret Data Check Allow Owner
Secret Data Get Allow Owner
Secret Data Get Attributes Allow Owner
Secret Data Get Attribute List Allow Owner
Secret Data Add Attribute Allow Owner
Secret Data Modify Allow Owner
Secret Data Delete Attribute Allow Owner
Secret Data Obtain Lease Allow Owner
Secret Data Get Usage Allocation Allow Owner
Secret Data Activate Allow Owner
Secret Data Revoke Allow Owner
Secret Data Destroy Allow Owner
Secret Data Archive Allow Owner
Secret Data Recover Allow Owner
Opaque Data Rekey Allow Owner
Opaque Data Rekey Key Pair Allow Owner
Opaque Data Derive Key Allow Owner
Opaque Data Locate Allow Owner
Opaque Data Check Allow Owner
Opaque Data Get Allow Owner
Opaque Data Get Attributes Allow Owner
Opaque Data Get Attribute List Allow Owner
Opaque Data Add Attribute Allow Owner
Opaque Data Modify Attribute Allow Owner
Opaque Data Delete Attribute Allow Owner
Opaque Data Obtain Lease Allow Owner
Opaque Data Get Usage Allocation Allow Owner
Opaque Data Activate Allow Owner
Opaque Data Revoke Allow Owner
Opaque Data Destroy Allow Owner
Opaque Data Archive Allow Owner
Opaque Data Recover Allow Owner
PGP Key Rekey Allow Owner
PGP Key Rekey Key Pair Allow Owner
PGP Key Derive Key Allow Owner
PGP Key Locate Allow Owner
PGP Key Check Allow Owner
PGP Key Get Allow Owner
PGP Key Get Attributes Allow Owner
PGP Key Get Attribute List Allow Owner
PGP Key Add Attribute Allow Owner
PGP Key Modify Attribute Allow Owner
PGP Key Delete Attribute Allow Owner
PGP Key Obtain Lease Allow Owner
PGP Key Get Usage Allocation Allow Owner
PGP Key Activate Allow Owner
PGP Key Revoke Allow Owner
PGP Key Destroy Allow Owner
PGP Key Archive Allow Owner
PGP Key Recover Allow Owner

public policy

Object Type Operation Permission
Template Locate Allow All
Template Get Allow All
Template Get Attributes Allow All
Template Get Attribute List Allow All
Template Add Attribute Disallow All
Template Modify Attribute Disallow All
Template Delete Attribute Disallow All
Template Destroy Disallow All

Objects

The following is a list of KMIP managed object types supported by the server.

Symmetric Keys

A symmetric key is an encryption key that can be used to both encrypt plain text data and decrypt cipher text.

Creating a symmetric key object would look like this:

>>> from kmip import enums
>>> from kmip.pie.objects import SymmetricKey
>>> key = SymmetricKey(
...     enums.CryptographicAlgorithm.AES,
...     128,
...     (
...         b'\x00\x01\x02\x03\x04\x05\x06\x07'
...         b'\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F'
...     ),
...     [
...         enums.CryptographicUsageMask.ENCRYPT,
...         enums.CryptographicUsageMask.DECRYPT
...     ],
...     "Example Symmetric Key"
... )

Public Keys

A public key is a cryptographic key that contains the public components of an asymmetric key pair. It is often used to decrypt data encrypted with, or to verify signatures produced by, the corresponding private key.

Creating a public key object would look like this:

>>> from kmip import enums
>>> from kmip.pie.objects import PublicKey
>>> key = PublicKey(
...     enums.CryptographicAlgorithm.RSA,
...     2048,
...     (
...         b'\x30\x82\x01\x0A\x02\x82\x01\x01...'
...     ),
...     enums.KeyFormatType.X_509,
...     [
...         enums.CryptographicUsageMask.VERIFY
...     ],
...     "Example Public Key"
... )

Private Keys

A private key is a cryptographic key that contains the private components of an asymmetric key pair. It is often used to encrypt data that may be decrypted by, or generate signatures that may be verified by, the corresponding public key.

Creating a private key object would look like this:

>>> from kmip import enums
>>> from kmip.pie.objects import PrivateKey
>>> key = PrivateKey(
...     enums.CryptographicAlgorithm.RSA,
...     2048,
...     (
...         b'\x30\x82\x04\xA5\x02\x01\x00\x02...'
...     ),
...     enums.KeyFormatType.PKCS_8,
...     [
...         enums.CryptographicUsageMask.SIGN
...     ],
...     "Example Private Key"
... )

Split Keys

A split key is a secret value representing a key composed of multiple parts. The parts of the key can be recombined cryptographically to reconstitute the original key.

Creating a split key object would look like this:

>>> from kmip import enums
>>> from kmip.pie.objects import SplitKey
>>> key = SplitKey(
...     cryptographic_algorithm=enums.CryptographicAlgorithm.AES,
...     cryptographic_length=128,
...     key_value=b'\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99\xAA\xBB\xCC\xDD\xEE\xFF',
...     name="Split Key",
...     split_key_parts=3,
...     key_part_identifier=1,
...     split_key_threshold=3,
...     split_key_method=enums.SplitKeyMethod.XOR
... )

Certificates

A certificate is a cryptographic object that contains a public key along with additional identifying information. It is often used to secure communication channels or to verify data signatures produced by the corresponding private key.

Creating a certificate object would look like this:

>>> from kmip import enums
>>> from kmip.pie.objects import X509Certificate
>>> cert = X509Certificate(
...     (
...         b'\x30\x82\x03\x12\x30\x82\x01\xFA...'
...     ),
...     [
...         enums.CryptographicUsageMask.VERIFY
...     ],
...     "Example X.509 Certificate"
... )

Secret Data

A secret data object is a cryptographic object that represents a shared secret value that is not a key or certificate (e.g., a password or passphrase).

Creating a secret data object would look like this:

>>> from kmip import enums
>>> from kmip.pie.objects import SecretData
>>> data = SecretData(
...     (
...         b'\x53\x65\x63\x72\x65\x74\x50\x61'
...         b'\x73\x73\x77\x6F\x72\x64'
...     ),
...     enums.SecretDataType.PASSWORD,
...     [
...         enums.CryptographicUsageMask.DERIVE_KEY
...     ],
...     "Example Secret Data Object"
... )

Opaque Objects

An opaque data object is a binary blob that the server is unable to interpret into another well-defined object type. It can be used to store any arbitrary data.

Creating an opaque object would look like this:

>>> from kmip import enums
>>> from kmip.pie.objects import OpaqueObject
>>> oo = OpaqueObject(
...     (
...         b'\x53\x65\x63\x72\x65\x74\x50\x61'
...         b'\x73\x73\x77\x6F\x72\x64'
...     ),
...     enums.OpaqueDataType.NONE,
...     "Example Opaque Object"
... )

Operations

The following is a list of KMIP operations supported by the server. All supported cryptographic functions are currently implemented using the pyca/cryptography library, which in turn leverages OpenSSL. If the underlying backend does not support a specific feature, algorithm, or operation, the PyKMIP server will not be able to support it either.

If you are interested in adding a new cryptographic backend to the PyKMIP server, see Development for more information.

Activate

The Activate operation updates the state of a managed object, allowing it to be used for cryptographic operations. Specifically, the object transitions from the pre-active state to the active state (see state).

Errors may be generated during the activation of a managed object. These may occur in the following cases:

  • the managed object is not activatable (e.g., opaque data object)
  • the managed object is not in the pre-active state

Create

The Create operation is used to create symmetric keys for a variety of cryptographic algorithms.

Algorithm Key Sizes
3DES 64, 128, 192
AES 128, 256, 192
Blowfish 128, 256, 384, and more
Camellia 128, 256, 192
CAST5 64, 96, 128, and more
IDEA 128
ARC4 128, 256, 192, and more

All users are allowed to create symmetric keys. There are no quotas currently enforced by the server.

Various KMIP-defined attributes are set when a symmetric key is created. These include:

Errors may be generated during the creation of a symmetric key. These may occur in the following cases:

  • the cryptographic algorithm, length, and/or usage mask are not provided
  • an unsupported symmetric algorithm is requested
  • an invalid cryptographic length is provided for a specific cryptographic algorithm

CreateKeyPair

The CreateKeyPair operation is used to create asymmetric key pairs.

Algorithm Key Sizes
RSA 512, 1024, 2048

All users are allowed to create asymmetric keys. There are no quotas currently enforced by the server.

Various KMIP-defined attributes are set when an asymmetric key pair is created. For both public and private keys, the following attributes are identical:

Other attributes will differ between public and private keys. These include:

Errors may be generated during the creation of an asymmetric key pair. These may occur in the following cases:

  • the cryptographic algorithm, length, and/or usage mask are not provided
  • an unsupported asymmetric algorithm is requested
  • an invalid cryptographic length is provided for a specific cryptographic algorithm

Decrypt

The Decrypt operations allows the client to decrypt data with an existing managed object stored by the server. Both symmetric and asymmetric decryption are supported. See Encrypt above for information on supported algorithms and the types of errors to expect from the server.

DeleteAttribute

The DeleteAttribute operation allows the client to delete an attribute from an existing managed object.

Errors may be generated during the attribute deletion process. These may occur in the following cases:

  • the specified managed object does not exist
  • the specified attribute may not be applicable to the specified managed object
  • the specified attribute is not supported by the server
  • the specified attribute cannot be deleted by the client
  • the specified attribute could not be located for deletion on the specified managed object

DeriveKey

The DeriveKey operation is used to create a new symmetric key or secret data object from an existing managed object stored on the server. The derivation method and the desired length of the new cryptographic object must be specified with the request. If the generated cryptographic object is longer than the requested length, it will be truncated to match the request length.

Various KMIP-defined attributes are set when a new cryptographic object is derived. These include:

Errors may be generated during the key derivation process. These may occur in the following cases:

  • the base object is not accessible to the user
  • the base object is not an object type usable for key derivation
  • the base object does not have the DeriveKey bit set in its usage mask
  • the cryptographic length is not provided with the request
  • the requested cryptographic length is longer than the generated key

Destroy

The Destroy operation deletes a managed object from the server. Once destroyed, the object can no longer be retrieved or used for cryptographic operations. An object can only be destroyed if it is in the pre-active or deactivated states.

Errors may be generated during the destruction of a managed object. These may occur in the following cases:

  • the managed object is not destroyable (e.g., the object does not exist)
  • the managed object is in the active state

DiscoverVersions

The DiscoverVersions operation allows the client to determine which versions of the KMIP specification are supported by the server.

Encrypt

The Encrypt operation allows the client to encrypt data with an existing managed object stored by the server. Both symmetric and asymmetric encryption are supported:

Symmetric Key Algorithms

Asymmetric Key Algorithms

Errors may be generated during the encryption. These may occur in the following cases:

  • the encryption key is not accessible to the user
  • the encryption key is not in the active state and must be activated
  • the encryption key does not have the Encrypt bit set in its usage mask
  • the requested encryption algorithm is not supported
  • the specified encryption key is not compatible with the requested algorithm
  • the requested encryption algorithm requires a block cipher mode
  • the requested block cipher mode is not supported

Get

The Get attribute is used to retrieve a managed object stored on the server. The unique_identifier of the object is used to retrieve it.

It is possible to request that the managed object be cryptographically wrapped before it is returned to the client. Right now only encryption-based wrapping is supported.

Errors may be generated during the retrieval of a managed object. These may occur in the following cases:

  • the managed object is not accessible to the user
  • a desired key format was specified that cannot be converted by the server
  • key compression was specified and the server cannot compress objects
  • the wrapping key specified is not accessible to the user
  • the wrapping key is not applicable to key wrapping
  • the wrapping key does not have the WrapKey bit set in its usage mask
  • wrapped attributes were specified and the server cannot wrap attributes
  • a wrapping encoding was specified and the server does not support it
  • incomplete wrapping specifications were provided with the request

GetAttributes

The GetAttributes operation is used to retrieve specific attributes for a specified managed object. Multiple attribute names can be specified in a single request.

The following names should be used to access the corresponding attributes:

Attribute Name Attribute
Cryptographic Algorithm cryptographic_algorithm
Cryptographic Length cryptographic_length
Cryptographic Usage Mask cryptographic_usage_mask
Initial Date initial_date
Object Type object_type
Operation Policy Name operation_policy_name
State state
Unique Identifier unique_identifier

GetAttributeList

The GetAttributeList operation is used to identify the attributes currently available for a specific managed object. Given the unique_identifier of a managed object, the server will return a list of attribute names for attributes that can be accessed using the GetAttributes operation.

Locate

The Locate operation is used to identify managed objects that the user has access to, according to specific filtering criteria. Currently, the server only support object filtering based on the object name attribute.

If no filtering values are provided, the server will return a list of unique_identifier values corresponding to all of the managed objects the user has access to.

MAC

The MAC operation allows the client to compute a message authentication code on data using an existing managed object stored by the server. Both HMAC and CMAC algorithms are supported:

HMAC Hashing Algorithms

CMAC Symmetric Algorithms

Errors may be generated during the authentication code creation process. These may occur in the following cases:

  • the managed object to use is not accessible to the user
  • the managed object to use is not in the active state and must be activated
  • the managed object does not have the Generate bit set in its usage mask
  • the requested algorithm is not supported for HMAC/CMAC generation

ModifyAttribute

The ModifyAttribute operation allows the client to modify an existing attribute on an existing managed object.

Errors may be generated during the attribute modification process. These may occur in the following cases:

  • the specified managed object does not exist
  • the specified attribute may not be applicable to the specified managed object
  • the specified attribute is not supported by the server
  • the specified attribute cannot be modified by the client
  • the specified attribute is not set on the specified managed object
  • the specified attribute is multivalued and the current attribute field must be specified
  • the specified attribute index does not correspond to an existing attribute

Query

The Query operation allows the client to determine what KMIP capabilities are supported by the server. This set of information may include the following types of information, depending upon which items the client requests:

The PyKMIP server currently only includes the supported operations and the server information in Query responses.

Register

The Register operation is used to store an existing KMIP object with the server. For examples of the objects that can be stored, see Objects.

All users are allowed to register objects. There are no quotas currently enforced by the server.

Various KMIP-defined attributes may be set when an object is registered. These may include:

Revoke

The Revoke operation updates the state of a managed object, effectively deactivating but not destroying it. The client provides a specific revocation_reason_code indicating why revocation is occurring.

If revocation is due to a key or CA compromise, the managed object is moved to the compromised state if it is in the pre-active, active, or deactivated states. If the object has already been destroyed, it will be moved to the destroyed compromised state. Otherwise, if revocation is due to any other reason, the managed object is moved to the deactivated state if it is in the active state.

Errors may be generated during the revocation of a managed object. These may occur in the following cases:

  • the managed object is not revokable (e.g., opaque data object)
  • the managed object is not active when revoked for a non-compromise

SetAttribute

The SetAttribute operation allows the client to set the value of an attribute on an existing managed object.

Errors may be generated during the attribute setting process. These may occur in the following cases:

  • the specified managed object does not exist
  • the specified attribute may not be applicable to the specified managed object
  • the specified attribute is not supported by the server
  • the specified attribute cannot be set by the client
  • the specified attribute is multivalued and cannot be set with this operation

Sign

The Sign operation allows the client to sign data with an existing private key stored by the server. The following hashing algorithms are supported with RSA for signing support.

Hashing Algorithms

Errors may be generated during the encryption. These may occur in the following cases:

  • the signing key is not accessible to the user
  • the signing key is not a private key
  • the signing key is not in the active state and must be activated
  • the signing key does not have the Sign bit set in its usage mask
  • the requested signing algorithm is not supported
  • the signing key is not compatible with the requested signing algorithm
  • a padding method is required for the algorithm and was not specified

SignatureVerify

The SignatureVerify operation allows the client to verify a data signature with an existing public key stored by the server. See Sign above for information on supported algorithms and the types of errors to expect from the server.