Crate kmip_protocol

source · [−]
Expand description

KMIP protocol library

This library provides:

  • Strongly-typed interfaces for a subset of the Oasis Key Management Interoperability Protocol aka KMIP.
  • A pluggable Client interface for sending KMIP TTLV requests to and receiving responses from a KMIP server.
  • Sample “plugins” for the Client interface for connecting to the KMIP server (a)synchronously via TCP+TLS.

WARNING: Although this crate aims to offer a production quality KMIP client capability it is still immature and being constantly evolved and improved. The provided TLS “plugins” are intended primarily for use by the example demo to demonstrate that the library can be successfully integrated with sample client code. Please submit any feedback regarding this crate to the project issue tracker. Use of this code is at your own risk.

Usage

The exact features to use depend on your needs, read below to learn more about the available features. In this example the Client interface will read & write messages synchronously to/from a Rustls managed TCP+TLS connection:

[dependencies]
kmip-protocol = { version = "0.4.3", features = ["tls-with-rustls"] }

Using this library you can then connect to a KMIP server and send a KMIP request something like this:

ⓘ
// Where 'settings' defines the hostname, port number, and other settings needed to establish a connection.
let client = kmip_protocol::client::tls::rustls::connect(&settings)?;

let bit_len = 2048;
let private_key_name = "priv".to_string();
let public_key_name = "pub".to_string();
let some_bytes_to_sign = [1u8, 2u8, 3u8, 4u8, 5u8];

if let Ok(res) = client.create_rsa_key_pair(bit_len, private_key_name, public_key_name) {
    let (private_key_id, public_key_id) = res;
    if client.activate_key(&private_key_id).is_ok() {
        if let Ok(payload) = client.sign(&private_key_id, &some_bytes_to_sign) {
            // ...
        }
        client.revoke_key(&private_key_id).ok();
    }
    client.destroy_key(&public_key_id).ok();
    client.destroy_key(&private_key_id).ok();
}

Advanced usage

If none of the helper functions offered by the Client struct fit your needs you can use Client::do_request directly to handle the request construction and response parsing yourself, for example:

ⓘ
let payload = RequestPayload::Query(vec![QueryFunction::QueryOperations]);
let result = client.do_request(payload)?;

if let ResponsePayload::Query(payload) = result {
    ...
}

Selecting a TLS plugin to use

See the client::tls module for information about selecting a TLS plugin to use.

KMIP operations supported

Note: Supported operations may lack support for some attribute or managed object types. Vendor specific extensions are ignored.

KMIP VersionOperationSupport
1.0Create✓
1.0Create Key Pair✓ (lacks response public/private key attribute lists support)
1.0Register✓ (only supports a subset of managed object types at present)
1.0Re-key
1.1Re-key Key Pair
1.0Derive Key
1.0Certify
1.0Re-certify
1.0Locate✓ (lacks Maximum Items and Storage Status Mask support)
1.0Check
1.0Get✓ (lacks Key Wrapping Specification, TransparentXXX, SplitKey, Template, SecretData and OpaqueObject support)
1.0Get Attributes✓ (lacks Big Integer and Interval support)
1.0Get Attribute List✓
1.0Add Attribute✓ (lacks Big Integer and Interval support)
1.0Modify Attribute✓ (lacks Big Integer and Interval support)
1.0Delete Attribute✓
1.0Obtain Lease
1.0Get Usage Allocation
1.0Activate✓
1.0Revoke✓
1.0Destroy✓
1.0Archive
1.0Recover
1.0Validate
1.0Query✓ (lacks Query Application Namespaces support)
1.1Discover Versions✓
1.0Cancel
1.0Poll
1.2Encrypt
1.2Decrypt
1.2Sign✓
1.2Signature Verify
1.2MAC
1.2MAC Verify
1.2RNG Retrieve✓
1.2RNG Seed
1.2Hash
1.2Create Split Key
1.2Join Split Key

KMIP use/test case coverage

Each KMIP specification document is accompanied by a separate document that defines a set of use cases, renamed in KMIP 1.1 to test cases. These show complete KMIP requests and responses. In the v1.0 and v1.1 versions each test case is broken down into its constituent TTLV parts with the matching numeric values and an accompanying hexadecimal representation of the serialized form. From v1.2 onwards the test case representation was changed from TTLV/hex based to XML based.

The subset of the TTLV/hex format test cases that this crate demonstrates compliance with are represented below by ticked boxes:

KMIP Use Cases v1.0/v1.1:

  • 3 Centralized Management
    • 3.1 Basic Functionality
      • 3.1.1 Use-case: Create / Destroy
      • 3.1.2 Use-case: Register / Create / Get attributes / Destroy
      • 3.1.3 Use-case: Create / Locate / Get / Destroy
      • 3.1.4 Use-case: Dual client use-case, ID Placeholder linked Locate & Get batch
      • 3.1.5 Use-case: Register / Destroy Secret Data
    • 3.2 Use-case: Asynchronous Locate
  • 4 Key life cycle support
    • 4.1 Use-case: Revoke scenario
  • 5 Auditing and reporting
    • 5.1 Use-case: Get usage allocation scenario
  • 6 Key Interchange, Key Exchange
    • 6.1 Use-case: Import of a Third-party Key
  • 7 Vendor Extensions
    • 7.1 Use-case: Unrecognized Message Extension with Criticality Indicator false
    • 7.2 Use-case: Unrecognized Message Extension with Criticality Indicator true
  • 8 Asymmetric keys
    • 8.1 Use-case: Create a Key Pair
    • 8.2 Use-case: Register Both Halves of a Key Pair
  • 9 Key Roll-over
    • 9.1 Use-case: Create a Key, Re-key
    • 9.2 Use-case: Existing Key Expired, Re-key with Same lifecycle
    • 9.3 Use-case: Existing Key Compromised, Re-key with same lifecycle
    • 9.4 Use-case: Create key, Re-key with new lifecycle
    • 9.5 Use-case: Obtain Lease for Expired Key
  • 10 Archival
    • 10.1 Use-case: Create a Key, Archive and Recover it
  • 11 Access Control, Policies
    • 11.1 Use-case: Credential, Operation Policy, Destroy Date (step 1 only for username/password auth test)
    • 11.2 Test Case: Device Credential, Operation Policy, Destroy Date (Added in KMIP v1.1)
  • 12 Query, Maximum Response Size
    • 12.1 Use-case: Query, Maximum Response Size (Implemented for both KMIP v1.0 and v1.1 test variants)
    • 12.2 Test Case: Query Vendor Extensions (Added in KMIP v1.1)
  • 13 Asymmetric Keys and Certificates (Added in KMIP v1.1)
    • 13.1 Test Case: Register an Asymmetric Key Pair in PKCS#1 Format
    • 13.2 Test Case: Register an Asymmetric Key Pair and a Corresponding X.509 Certificate
    • 13.3 Test Case: Create, Re-key Key Pair
    • 13.4 Test Case: Register Key Pair, Certify and Re-certify Public Key
  • 14 Key Wrapping (Added in KMIP v1.1)
    • 14.1 Test Case: Key Wrapping using AES Key Wrap and No Encoding
    • 14.2 Test Case: Key Wrapping using AES Key Wrap with Attributes
  • 15 Groups (Added in KMIP v1.1)
    • 15.1 Test Case: Locate a Fresh Object from the Default Group
    • 15.2 Test Case: Client-side Group Management
    • 15.3 Test Case: Default Object Group Member
  • 16 Discover Versions (Added in KMIP v1.1)
    • 16.1 Test Case: Discover Versions
  • 17 Attribute Handling (Added in KMIP v1.1)
    • 17.1 Test Case: Handling of Attributes and Attribute Index Values
  • 18 Digest (Added in KMIP v1.1)
    • 18.1 Test Case: Digests of Symmetric Keys
    • 18.2 Test Case: Digests of RSA Private Keys

Other (partially) implemented KMIP test cases:

Modules

auth
Support for KMIP username and password authentication.
client
For sending KMIP requests and receiving responses.
request
Serialiation of KMIP requests.
response
Deserialiation of KMIP responses.
tag_map
Pre-defined TTLV tag code to name mappings for improved diagnostic reporting.
types
Rust type definitions for kmip-ttlv based (de)serializing of KMIP message objects.

Structs

Config
Configuration settings used by the deserializer.