KMIP Server

Introduction

KeyControl supports a fully functional KMIP Server implementation. When enabled, KMIP clients can connect and perform all standard KMIP operations.

Current limitations

  • Server clustering of updates is manual. KMIP objects are fully replicated across the cluster, but servers running on nodes other than where a given object was created will need to be re-enabled to recognize the new object. Click Apply to re-enable the server at any time that you make changes.
  • Similarly, if the KMIP server is enabled after a node has joined the cluster it will need to be manually enabled on all nodes. A node joining or rebooting when the KMIP server is enabled will have the server enabled and access to all existing objects automatically.
  • Object count (for example, keys) is limited to 1000.
  • Users cannot be partitioned. That is, all users have access to all KMIP objects.

Accessing the KMIP Server Settings

In the GUI, click the Settings icon at the top of the screen, and then click KMIP Server Settings. There are two tabs: Basic, which enables the server and its options, and Users, which allows user certificate bundles to be created and downloaded.

Enabling the Server

In its simplest form, you can leave the defaults in place and simply enable the server. The following image gives you context, starting on the Basic tab:

To enable the KMIP server:

  1. In the KMIP Server Settings dialog box, on the Basic tab, in the line labeled State, click DISABLED and then click the checkbox to change it to ENABLED.
  2. Click Save, and then click Apply.

The server will be enabled on the KeyControl to which you are connected, using the default connection options. If you need to change the defaults, you can do so. Values in general are taken from the KMIP standard and/or security recommendations:

  • Port: the default is from the KMIP standard: 5696.
  • Auto-Reconnect: the default is OFFChange to ONONif you want your client to automatically attempt reconnects.
  • Verify: the default is on: Yes. Client identity is verified. This setting should be set to Yes.
  • Protocol: the version of the KMIP protocol supported. The default is Version 1. If you need to use a different protocol, either scroll to it or add a custom protocol value..
  • Nbio: OFF or ON, definingwhether non-blocking I/O is required. The default value is OFF..
  • Timeout: the timeout, in seconds, for a client operation. The default is Infinite, although you can change it by unchecking the box.
  • Log Level: Sets the level of settings that are logged to the Audit Log.There are three different levels possible: ALL, CREATE-GET, OFF. ALL will log all requests and responses that come to the KMIP server. CREATE-GET will log only object creation and object fetch requests and responses. OFF will disable the logging. The default is ALL.

Using the Apply button: clicking Apply will update the settings for the server. The server will be enabled or disabled as appropriate. If the server is already set to ENABLED, it will restart and refresh all of its settings and object list. When you click Apply, you will be prompted to confirm that you want to "Overwrite all existing KMIP Server settings." Click Proceed or Cancel.

Using the Revert button: Revert is used when settings have been changed but not applied, and you want to return to the original settings without making any changes.

Using the Reset KMIP Server button: Reset KMIP Server is used to disable the KMIP server, remove all its settings, AND destroy all current KMIP objects. It should be used with extreme caution.

Authorizing Users and Certificates

Certificates are used by the KMIP client to communicate securely with the KMIP server. At a minimum, the client needs:

  • A User certificate
  • A User key
  • A CA certificate

To obtain these you need to create a KMIP user, and download a certificate bundle. The bundle will contain a combined user certificate/key file and a CAcert file. The user certificate/key can have an optional password. These certificates are then used by a client to connect.

To create a user and certificate bundle:

  1. In the KMIP Server Settings dialog box, click the Users tab, and under Actions, click Create User.
  2. Fill in a Username for the user you are adding.
  3. (Optional) Modify the Cert Expiration. The default is one year.
  4. Enter a Password and confirm it.
  5. Click Create.

To download a user certificate bundle:

  1. Click to highlight the user for whom you want to download the bundle.
  2. Under Actions, click Download Certificate. A bundle named <username>.zip will be downloaded.
  3. Unzip the downloaded file, and you will see both a user cert/key file <username>.pem and a server cert/key file (cacert.pem). These can be used by clients to connect to the server.

KMIP Client/Server Errors and Troubleshooting

KMIP Client Logs

  • /var/log/hcs/kmipcmd.log: Full-formatted KMIP protocol output. Key values are redacted.
  • /var/log/ht_kmip.log: Output from the KMIP client implementation. Includes operations attempted and appropriate error codes.

KMIP Server Logs

  • /var/log/hcs/kmipsrv.log: Transactions for server stop/start, mostly debugging.
  • /var/log/hcs/traffic.log: Full-formatted KMIP protocol output. Key values are redacted.
  • Audit log: Logs either a) all KMIP request/response, b) create/get request/response, or c) none. The output is configurable in Server Options.

Troubleshooting

Common errors seen:

  • Error 10 - Generally, our client is not talking to the server at all. This could be because of firewall issues, incorrect “Host Name” in KMIP client settings, or some other network issue. As of 3.3, connectivity can be checked with nc via console menu under “Network Diagnostic Tools”.

  • Error 29 - Seen when incomplete parameters are entered under KMIP Client Settings.

  • Error 30 - Seen when the KMIP server required Server Cert and one was not provided.

  • Error 31 - One of the passwords entered for a KMIP Client Settings is incorrect.

  • Error 32 - The CA cert argument for KMIP Client Settings is not correct.

Full List of KMIP Errors

#define KMIP_ERROR_NONE         0
#define KMIP_ERROR_FAILED         1
#define KMIP_ERROR_ALLOC         2
#define KMIP_ERROR_BAD_ARGS         3
#define KMIP_ERROR_SPACE         4
#define KMIP_ERROR_BAD_DATA         5
#define KMIP_ERROR_INCOMPLETE         6
#define KMIP_ERROR_BAD_CERT_FILE     7
#define KMIP_ERROR_BAD_KEY_FILE     8
#define KMIP_ERROR_BAD_CONNECT         9
#define KMIP_ERROR_IO             10
#define KMIP_ERROR_NOT_FOUND        11
#define KMIP_ERROR_BAD_TYPE         12
#define KMIP_ERROR_NO_DATA         13
#define KMIP_ERROR_INVALID         14
#define KMIP_ERROR_RANGE         15
#define KMIP_ERROR_CHECK         16
#define KMIP_ERROR_NOT_SUPPORTED     17
#define KMIP_ERROR_BAD_PROTOCOL     18
#define KMIP_ERROR_NO_SPACE         19
#define KMIP_ERROR_BAD_ID         20
#define KMIP_ERROR_DENIED         21
#define KMIP_ERROR_TOO_LARGE         22
#define KMIP_ERROR_GENERATE_FAILED    23
#define KMIP_ERROR_EVAL_EXPIRED        24
#define KMIP_ERROR_ARCHIVED        25
#define KMIP_ERROR_BAD_STATE        26
#define KMIP_ERROR_RETRY        27
#define KMIP_ERROR_NO_PROVIDERS        28
#define KMIP_ERROR_SSL_PARAMS        29
#define KMIP_ERROR_SSL_PEER_VALIDATION    30
#define KMIP_ERROR_BAD_PASSWORD        31
#define KMIP_ERROR_BAD_TRUSTED_FILE    32
#define KMIP_ERROR_AUTH_FAILED         33
#define KMIP_ERROR_CERT_AUTH_FAILED     34
#define KMIP_ERROR_DB_CONNECT         35
#define KMIP_ERROR_DB_GENERAL         36
#define KMIP_ERROR_AGAIN         37
#define KMIP_ERROR_NOT_UNIQUE         38
#define KMIP_ERROR_DB_INSERT        39
#define KMIP_ERROR_DB_UPDATE        40
#define KMIP_ERROR_SINGLE_INSTANCE    41
#define KMIP_ERROR_SERVER_TRUST        42
#define KMIP_ERROR_PROTECT         43
#define KMIP_ERROR_REPLICATE        44
#define KMIP_ERROR_SERIALISE        45
#define KMIP_ERROR_PROXY        46
#define KMIP_ERROR_SSL_VALIDATION    47
#define KMIP_ERROR_SSL_VERIFY_HOST      48
#define KMIP_ERROR_SPECIFICATION_ERROR  49
#define KMIP_ERROR_POOL_FAILURE        50
#define KMIP_ERROR_DB_TRANSACTION    51
#define KMIP_ERROR_DB_LIMIT        52
#define KMIP_ERROR_DB_LOCK        53
#define KMIP_ERROR_CRYPTO        54
#define KMIP_ERROR_INVALID_FIELD    55
#define KMIP_ERROR_ATTESTATION_REQUIRED    56
#define KMIP_ERROR_ATTESTATION_FAILED    57
#define KMIP_ERROR_BAD_INDEX        58
#define KMIP_ERROR_NAMESPACE        59
#define KMIP_ERROR_FEATURE_DISABLED     60
#define KMIP_ERROR_VERIFY             61
#define KMIP_ERROR_DB_READ_ONLY         62
#define KMIP_ERROR_FIPS140             63
#define KMIP_ERROR_HSM             64
#define KMIP_ERROR_TOKEN             65
#define KMIP_ERROR_NO_KEY             66
#define KMIP_ERROR_HEARTBEAT_BLOCKED    67
#define KMIP_ERROR_SSL_HANDSHAKE    68
#define KMIP_ERROR_SSL_BAD_TIMEOUT    69
#define KMIP_ERROR_HSM_OFFLINE         70
#define KMIP_ERROR_CERT_KEY_MISMATCH    71