|
Developer's Guide
|
|
|
Developer's Guide
|
|
The KSG is a special purpose KMIP Server application that sits in front of existing HSMs (Hardware Security Modules). It provides an OASIS KMIP protocol interface to existing HSMs by translating KMIP protocol requests into PKCS#11 calls and then translating the PKCS#11 responses back into KMIP. The possible KMIP operations that are supported via KSG depend upon the limitations of the backend HSMs. KSG supports most commercially available HSMs. KSG also supports a local PKCS#11 software token.
KSG supports KMIP versions 1.0, 1.1, 1.2, 1.3, 1.4, 2.0 and 2.1. KSG supports all KMIP message formats: TTLV, TTLV over HTTPS, JSON, and XML. KSG is however limited in what KMIP operations it can support due to limitations enforced by the backend HSM in use (e.g., if the HSM is in FIPS mode many restrictions exist on its use). Currently, the following KMIP operations are supported:
The following KMIP object types are supported: Symmetric Key, Secret Data, Public Key, Private Key, and Certificate.
The following limitations exist:
KSG can run with the P6R PKCS#11 software token that does not run in FIPS mode. In this configuration, many of the limitations above do not exist, however, no HSM is in use.
For this version of KSG the user must configure KSG's PKCS#11 module to talk to the user's HSM. In addition, the user must set up a TLS proxy to take incoming TLS requests and forward them to KSG (e.g., Stunnel) [in a future release KSG will have its own TLS server protocol handling as an option]. Here are the KSG set up steps.
Note, to run the p6pkcs11tool on Linux currently requires setting LD_LIBRARY_PATH the to "<installed path>../components" directory so it can dynamically load libp6pkcs11.so, which is P6R's PKCS#11 library implementation. Otherwise, an error that the shared library cannot be found will be returned.
Note, that if you are upgrading your version of KSG please check the section "Are you running an older version of KSG?" below.
The first version of KSG relies on Stunnel (https://www.stunnel.org/) as its front end TLS proxy. (An equivalent TLS proxy can also be used.) Future versions of KSG will implement its own TLS server protocol. Of course, a customer can choose to use a different TLS proxy in front of KSG, but Stunnel is what has been used during testing.
To use Stunnel the customer needs access to a local CA in order to create the required server and client side authentication certificates required by the KMIP's use of the TLS protocol. During testing P6R has used OpenSSL to provide this set of features. Thus all TLS interactions between a KMIP client and KSG will be handled by Stunnel. Stunnel simply forwards the unencrypted KMIP requests to the KSG process.
For example, below is the contents of a stunnel.conf file that has been used in integration testing.
Other possible configuration parameters
The above configuration is used to define a single HSM that sits behind a KSG instance and is defined in the ksg.conf file. In the example, above that HSM is an AWS CloudHSM.
The "baseKeyPath" configuration parameter (string value), is the symmetric key protecting the PKCS 11 keystore is to be written to after it is generated by the library. This parameter can be either a full path to the key file or just the name of the key file. If it is just a file name then it will be treated as relative to the directory the library runs out of. Essentially, this is the one key that is kept in the clear. Either this parameter OR the "customerKeyPath" parameter is defined. If both are defined, then the customerKeyPath parameter will be used.
The "customerKeyPath" configuration parameter (string value), is the symmetric key protecting the PKCS 11 keystore. The difference between this parameter and the "baseKeyPath" is that the baseKeyPath key is generated by this command line tool while the customerKeyPath key is provided by the customer. The customer must provide an AES 256 bit PEM encoded file.
The "HSM_name" configuration parameter (string value), is used to store meta data into the P6R keystore for any key or other managed object in an HSM. This provides a way to segregate object meta data.
The "HSM_slotid" configuration parameter (positive integer value), is the PKCS#11 slot number expected by the HSM in use in order to open a PKCS#11 session.
The "HSM_addr" configuration parameter (string value), is the network address to connect to a network attached HSM.
The "HSM_type", optional, configuration parameter (positive integer value), is used to distinguish different HSMs which may require slightly different client side behavior. The current allowed values for this parameter are: { 0x0001 AWS CloudHSM, 0x0002 Cavium LiquidSecurity HSM, 0x0004 Entrust nShield HSM (formerly nCipher) }. The default value for this parameter is zero which results in no special behavior.
The "gateFlags", optional, configuration parameter (positive integer value), is used as a bit mask to define specific Gateway wide behavior. The current allowed values for this parameter are:
The default value for this parameter is zero which results in no special behavior.
The "AWSCloudHSM_KEKHandle", configuration parameter (positive integer value), is the HSM object handle for the application KEK AES 256 bit key that has been loaded into the CloudHSM in order to export CloudHSM generated keys. This application KEK is either provided by the customer or generated via OpenSSL command line as part of the KSG initialization process. This application KEK is loaded into the CloudHSM using the AWS "key_mgmt_util" program following the sequence defined below. Note, that AWS CloudHSM object handles stay valid across PKCS#11 sessions.
The "CaviumLiquidSec_KEKHandle", configuration parameter (positive integer value), is the HSM object handle for the application KEK AES 256 bit key that has been loaded into the Cavium LiquidSecurity HSM in order to export HSM generated keys. This application KEK is either provided by the customer or generated via OpenSSL command line as part of the KSG initialization process. This application KEK is loaded into the HSM using the Cavium "Cfm3Util" program following the sequence defined below. Note, that Cavium LiquidSecurity HSMobject handles stay valid across PKCS#11 sessions.
The "KEKKeyPath", configuration parameter (string value), is the full path to the customer's AES 256 bit KEK stored in binary format. Note if no path is given then the file is assumed to be in the KSG data directory.
The "serverLogFlags", optional, configuration parameter (bit mask), defines the format the server should log all incoming and outgoing messages. The default value for this parameter is zero which disables all KMIP message logging. The following values can be used to create a bit mask value for this parameter.
To future control logging from PKCS#11 you can edit the "install directory".en_us. For example one line in this file is:
The above is the default setting for this logging data. The "info" field can also be changed to "error", "warn", or "debug". The number after "info" is the log level to print that log data and the value of 0 means verbose. So to turn this logging data off one could change the zero to a 3. Out of the box these setting are set to log all PKCS#11 data so the customer can view what is happening during integration testing. After this testing many of the "info" lines in the file p6pkcs11.en_us should have their log level increased.
KSG has an internal, generic KMIP server process to receive incoming KMIP requests. This section describes how that server is configured. Basic server's configuration parameters (e.g., port to connect to) are defined in the p6kmipserver.conf file.
The "logDir" configuration parameter (string value), defines an existing, writable directory where the KMIP server can write log files. If this configuration parameter is missing then logging will be disabled. Note, that the KMIP server will create directories under this log directory.
In the above example, the KMIP server creates a "server" directory currently under localhost. All incoming KMIP requests made by clients are logged into that directory. Note, that the log file names for the server have two number parts. The first is a timestamp and the second part to their file name (e.g., kmip-1398708919378906-14844.xml), where the value after the 2nd "-" is the thread identifer that worked on the request. Since the server is multi-threaded messages will be mixed and sorted by time. To find the matching response sent for a request look for the next message with the same thread identifier, since a single thread handles the entire incoming request.
The "errorStream" configuration parameter (string value), is the name of a file to be created in the log directory that includes any XML/JSON/JsonML parsing errors and warning.
The "listenPort" configuration parameter (positive numeric value), is the port that the KMIP server component should listen on for incoming Notify / Put operations. The default value is 65524. This value can also be passed into the p6IKMIPServer::initialize() call allowing multiple instances of the KMIP server running at the same time.
The "maxBufSize" configuration paramter (positive numeric value), is the size of each allocated server buffer. The default value is 40000 bytes if not defined in the p6kmipserver.conf file.
The "initialBufCount" configuration parameter (positive numeric value), is the number of buffers the server should allocate on start up. The default value is 10 if not defined in the p6kmipserver.conf file.
The "growBufBy" configuration parameter (positive numeric value), is the number of buffers the server will allocate at once time when additional buffers are required to handle incoming requests. The default value is 10 if not defined in the p6kmipserver.conf file.
The "threadCount" configuration parameter (positive numeric value), is the number of threads created whenever a p6IKMIPServer component is created to process incoming Notify and Put requests. The default value is 10 if not defined in the p6kmipserver.conf file.
The "listenIPAddr" configuration parameter (string value), allows the KMIP server to support multi-homed machines. The default value is "0.0.0.0" if not defined in the p6kmipserver.conf file.
The "receiveTimeout" configuration parameter (positive numeric value), is the number of seconds that the KMIP server component will wait to receive incoming bytes from a connected socket. That is, how long it will wait to receive the next KMIP request from a client over an existing connection. If the timeout is exceeded, then the server will close down the TCP connection (which will cause the TLS session to also close). The default value is 300 (5 minutes) if not defined in the p6kmipserver.conf file.
The "sendTimeout" configuration parameter (positive numeric value), is the number of seconds that the KMIP server component will wait to send outgoing bytes over a connected socket. That is, how long it will wait to send a KMIP response message to a client over an existing connection. The default value is 300 (5 minutes) if not defined in the p6kmipserver.conf file.
The "acceptTimeout" configuration parameter (positive numeric value), is the number of seconds that the KMIP server component will wait to receive an incoming connection request. If the timeout is exceeded, a listener thread will wake up, log a warning, and then go back to waiting for the next incoming request. The default value is 10 if not defined in the p6kmipserver.conf file.
The "KMIPMaxVersion" configuration parameter (string value), allows the user to control the maximum KMIP protocol version that KSG should handle. Currently, this value defaults to "1.4" as KMIP 2.0 support is in development. Recognized string values are: { "1.0", "1.1", "1.2", "1.3", "1.4", "2.0" }.
The "KMIPMinVersion" configuration parameter (string value), allows the user to control the minimum KMIP protocol version that KSG should handle. Currently, this value defaults to "1.0". Recognized string values are: { "1.0", "1.1", "1.2", "1.3", "1.4", "2.0" }.
A second configuration file: p6kmip_auxiliary_ksg.conf, has been added that defines the current capabilities of KSG. A customer can edit this file to remove capabilities that they wish to hide from KMIP clients during KMIP Query requests. For example, the values below are what is supported for the first release of KSG. These numbers come directly from the KMIP specification (e.g., operation "1" is Create).
The "vendorId" configuration parameter (string value), is the string returned to a KMIP client performing a Query operation against P6R's KMIP server. In this case, the contents of the vendorId parameter is returned as part of a Query response when the "Query Server Information" flag is part of the Query request. This parameter is optional, nothing is returned for vendor information if vendorId parameter is not defined.
The "operations" configuration parameter, (a comma separated list of positive numeric values), defines all client side operations supported by the P6R client SDK. Operation values are defined in file p6kmip.h, Section 9.1.3.2.27 Operation Enumeration. The integer values in the list are the integer values defined for each enumeration.
The "objects" configuration parameter, (a comma separated list of positive numeric values), defines all objects types supported by the P6R client SDK. Object values are define in file p6kmip.h, Section 9.1.3.2.12 Object Type Enumeration. The integer values in the list are the integer values defined for each enumeration.
The "profiles" configuration parameter, (a comma separated list of positive numeric values), defines all the client profiles supported by the P6R client SDK. Profile values are defined in file p6kmipprofiles.h, Section 9.1.3.2.42 Profile Name Enumeration. The integer values in the list are the integer values defined for each enumeration. Note, that Suite B profiles depending on the customer using an OpenSSL library with the proper (EC) key support (profiles: 49,50,51,55,56,57).
The "shreadingAlgorithm" configuration parameter, (positive numeric value) defines the shreadding algorithm used by the client when destroying a key. Shreading algorithms are defined in file p6kmip.h, Section 9.1.3.2.45 Shredding Algorithm Enumeration. If not defined here the value defaults to KMIP_SHREDALG_UNSPECIFIED (1) (which is what most likely the value should be returned as).
The "destroyAction" configuration parameter, (positive numeric value) defines the the destroy action used by the client when destroying a key. Destroy action enumeration is defined in the file p6kmip.h, Section 9.1.3.2.44 Destroy Action Enumeration. If not defined here the value defaults to KMIP_ONDESTROY_UNSPECIFIED (1) (which is what most likely the value should be returned as).
The "unrapMode" configuration parameter, (positive numeric value) defines how the client unraps a wrapped key. The unrap mode enumeration is defined in the file p6kmip.h, Section 9.1.3.2.43 Unwrap Mode Enumeration. If not defined here the value defaults to KMIP_UNWRAPMODE_UNSPECIFIED (1).
The "RNGMode" configuration parameter, (positive numeric value) defines how a random number generator is implemented by the client. The RNG mode enumeration is defined in the file p6kmip.h, Section 9.1.3.2.46 RNG Mode Enumeration. If not defined here the value defaults to KMIP_RNGMODE_UNSPECIFIED (1).
The "streamingEnabled" configuration parameter, ( a boolean value) defines whether or not the client supports streaming cryptographic operations. Note that the P6R client SDK does support this feature. If not defined here the value defaults to true.
The AWS CloudHSM allows a PKCS#11 client to extract a symmetric key that was generated on the CloudHSM. This extraction takes place via the use of the PKCS#11 C_WrapKey() API call. The Key Encrypting Key (KEK) used to wrap the symmetric key in the call to C_WrapKey() can be loaded into the CloudHSM and thus is known by the client. The wrapping algorithm used is the AWS Key Wrap with PKCS#5 Padding.
The above is important because it allows a KMIP GET operation, for a symmetric key created on the CloudHSM, to return the symmetric key in the clear. This allows many existing KMIP applications that expect to perform encryption locally to work with the AWS CloudHSM.
To achieve this a customer creates their own AES 256 bit key (as the known KEK) and stores that in a file in binary format (e.g., aes256.key). Then using AWS CloudHSM command line tools (to be shown below) the customer loads their KEK into the CloudHSM with a CKA_LABEL value that KSG will look for (i.e., "P6RKEK1"). Setting the CKA_LABEL as such allows KSG to locate the KEK later.
Once this setup is complete, then KSG will perform the AES Key Unwrap in its implementation of the KMIP GET operation for a symmetric key created on the CloudHSM. That is, KSG will first extract the symmetric key using PKCS#11 API call C_WrapKey() with the handle of the loaded customer KEK, and then call OpenSSL to perform the AES Unwrap function. The end result is that the symmetric key created on the CloudHSM is now in the clear to be returned to the requesting KMIP Client.
In the example below, please note that a key's handle returned by CloudHSM lasts across sessions of their command line tools and of PKCS#11 sessions. Also note that the handle value returned in step #2 is placed in the ksg.conf file as the "AWSCloudHSM_KEKHandle" parameter (see above).
The below sequence of command line operations loads the customer's KEK into the CloudHSM so it can be used to wrap a key during the PKCS#11 API call C_WrapKey(). Since KSG then knows this KEK it can locally unwrap the key. The sequence of /opt/cloudhsm/bin/key_mgmt_util command line tool calls are performed on the EC2 instance that AWS refers to as the "CloudHSM client instance" and is where KSG is installed.
Please refer to AWS documentation for a description of the commands used in the example below and what is necessary to use them.
The Cavium LiquidSecurity HSM allows a PKCS#11 client to extract a symmetric key that was generated on the HSM. This extraction takes place via the use of the PKCS#11 C_WrapKey() API call. The Key Encrypting Key (KEK) used to wrap the symmetric key in the call to C_WrapKey() can be loaded into the HSM and thus is known by the client. The wrapping algorithm used is the AWS Key Wrap with PKCS#5 Padding.
The above is important because it allows a KMIP GET operation, for a symmetric key created on the HSM, to return the symmetric key in the clear. This allows many existing KMIP applications that expect to perform encryption locally to work with the Cavium LiquidSecurity HSM.
To achieve this a customer creates their own AES 256 bit key (as the known KEK) and stores that in a file in binary format (e.g., aes256.key). Then using Cavium LiquidSecurity HSM command line tools (to be shown below) the customer loads their KEK into the HSM with a CKA_LABEL value that KSG will look for (i.e., "P6RKEK1"). Setting the CKA_LABEL as such allows KSG to locate the KEK later.
Once this setup is complete, then KSG will perform the AES Key Unwrap in its implementation of the KMIP GET operation for a symmetric key created on the HSM. That is, KSG will first extract the symmetric key using PKCS#11 API call C_WrapKey() with the handle of the loaded customer KEK, and then call OpenSSL to perform the AES Unwrap function. The end result is that the symmetric key created on the HSM is now in the clear to be returned to the requesting KMIP Client.
In the example below, please note that a key's handle returned by the HSM lasts across sessions of their command line tools and of PKCS#11 sessions. Also note that the handle value returned in step #2 is placed in the ksg.conf file as the "CaviumLiquidSec_KEKHandle" parameter (see above).
The below sequence of command line operations loads the customer's KEK into the HSM so it can be used to wrap a key during the PKCS#11 API call C_WrapKey(). Since KSG then knows this KEK it can locally unwrap the key. The sequence of /home/liquidsec_bin/bin/Cfm3Util command line tool calls are performed on a computer where KSG is installed.
Please refer to Cavium documentation for a description of the commands used in the example below and what is necessary to use them.
After installing KSG make sure to copy the cknfast-64.dll (for Windows) or libcknfast.so (for Linux) file into the KSG "components" directory. This allows KSG to find and load the Entrust PKCS#11 library and use it to talk to the HSM.
To modify the bahaivor of the nShield Connect a user can set either environment variables or create a "cknfastrc" file for the HSM to read. The cknfastrc file that we used for this integration is as follows:
Note that in addition to the parameters set above, we routinely set CKNFAST_DEBUG=9 and CKNFAST_DEBUGFILE to log the actions taken by the HSM and there results. Please refer to Entrust documentation for a description of the settings above.
The Entrust HSM uses Vendor Defined mechanisms for HMAC key generation. Instead of the PKCS#11 V2.40 standard where HMACs are created via key generation Entrust uses the C_GenerateKey() API. P6R's KSG handles this difference but requires the calling KMIP application to use the KMIP Create operation instead of the KMIP Derive Key operation to create a HMAC key when using an Entrust nShield HSM. Note, that this also requires that the "HSM_type" KSG configuration parameter must be set with the Entrust nShield defined value (see above).
Unlike the AWS CloudHSM and Cavium HSMs, the integration with the Entrust nShield Connect does not support the KMIP Get operation since we did not find anyway to inject a customer provided KEK into the HSM. Thus keys created on the nShield Connect could only be extracted from the HSM using wrapping keys created on the HSM.
We performed integration testing with the nShield Edge (which provides the same API as the Connect). Specifics of the HSM we used where discovered by calling the PKCS#11 API function C_GetTokenInfo():
Upgrading to KSG 2020.x requires a keystore with database schema version "M1.5". Previous versions of KSG used keystore database schema version "1.4". Please apply the appropriate SQL upgrade commands defined below depending on the database in use.
FIRST before performing any of the SQL commands below make a backup of the SQlite or Postgres database being used by KSG.
[A] SQlite database SQlite has limited support for the "ALTER TABLE ..." command. Thus the following steps are required to change the SQL UNIQUE constraint. Use a SQL command line (e.g, SQLiteSpy).
Step 1: Verify schema in use
If you see name: "P6R Schema Version", value: "1.4", then run step two below. Otherwise, if you see "M1.5" the database scheme is correct and you are done.
Step 2: SQLite does not support all of "Alter table".
[B] Postgres database This database has a full "ALTER table" support.
Step 1: Verify schema in use
If you see name: "P6R Schema Version", value: "1.4", then run step two below. Otherwise, if you see "M1.5" the database scheme is correct and you are done.
Step 2: Run several Alter table commands
