Open topic with navigation

KMIP Server

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.
  • Advanced Clustering: Experimental feature now available. When enabled, any changes in a KMIP object results in a restart of all KMIP servers not on the originating node. Enabled in the Basic tab.
• 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 webGUI, click the Settings icon at the top of the screen, and then click KMIP Server Settings. There are three tabs: Basic, which enables the server and its options, Users, which allows user certificate bundles to be created and downloaded, and Objects, which enables manipulation of KMIP objects.

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.
• State: the Enabled vs. Disabled state of the server.
• Advanced Clustering: an experimental feature that is used for KMIP objects.
• Auto-Reconnect: the default is OFF. Change to ON if you want your client to automatically attempt reconnects.
• Verify: the default is YES, which means the client identity is verified. We recommend you do not turn verification off.
• 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, defining whether 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.

Click Apply to 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.

To discard your changes and revert to the values that were last applied to the server, click Revert.

To disable the KMIP server, remove all its settings, AND destroy all current KMIP objects, click Reset KMIP Server . This option is not reversable and 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. (Optional) 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 Objects

Click the Objects tab to view the various KMIP objects in your environment:

The columns shown display the following fields for each object:

• UUID — the Universally Unique IDentifier that is associated with the KMIP object
• State — the state of the KMIP object
• Initial Date — when the object was created
• Last Change Date — when the object was last modified
• Object Type — type of the object
• Identified — Note that this field is not yet implemented
• Description — a user-settable field describing the object

Selecting an object will show additional attributes for that object. These attributes vary based on the state of the object. See the KMIP standard for more details.

The actions available to each object are as follows, all preceded by clicking the Actions button:

• Refresh: Used to refresh your display of current objects. Note that Refresh is manual for newly created objects. Existing objects that are modified will be updated without a Refresh.
• Activate: Objects are by default created in PreActive state. Clicking Activate enables more transitions for the object. Note: many KMIP clients change objects to Active state as part of the creation process.
• Revoke: Revocation is permanent. Objects that are revoked cannot be moved back to Active, but the client can still retrieve any key material. Revocation prompts for a revocation reason, which can be any string. Revocation also prompts for a Reason Code, which is one of the following, as defined by the KMIP standard:
  • 1 — Unspecified
  • 2 — Key Compromise
  • 3 — CA Compromise
  • 4 — Affiliation Changed
  • 5 — Superseded
  • 6 — Cessation of Operation
  • 7 — Privilege Withdrawn
  • KMIP extension values. Any unrecognized value will be considered the same as "1 — Unspecified."
• Archive: Objects are made to be not available for use, that is, no key material will be returned until the object itself is Recovered.
• Recover: Returns an Archived object to be available for use.
• Destroy: This is a permanent operation, removing the object entirely.

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/hcs/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 v 3.4, connectivity can be checked with netcat via the console menu under “'/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

Open topic with navigation