|
Developer's Guide
|
|
|
Developer's Guide
|
|
P6R's KMIP command line tool is a scriptable KMIP client that can be used during development and production. This tool provides many basic functions required for any application (e.g., listing existing keys, certificats, adding / modifying object attributes). Below is a list of all currently provided functions the p6kmiptool can perform:
For the most up to date commands and options type "p6kmiptool" or "p6kmiptool -h" on the command line to get the complete usage description.
Note that the following commands require the server to support KMIP version 1.4 or greater: "-create-password", and "-exportpkcs12". Also note all servers will support the "-derivekey" command. In addition, the following commands require the server to support KMIP version 1.3 or greater: "-encrypt", "-decrypt", "-sign", and "-verify" since these commands use streaming encryption.
The "-genkey", "-genkeypair", and "-import" commands will often need to specify the value of several KMIP attributes. It is not possible to add these attributes all on the command line so a special configuration file is associated with our p6kmiptool. The "p6kmiptemplatesX.conf", where X is a number from 1..n, file defines tables of KMIP attributes to be used with a tool command.
The user can specify '-t <number>' onto the "-genkey", "-genkeypair", "derivekey", and "-import" commands. This option allows the user to select one out of many defined template files to apply to the operation. For example, '-t 5' selects the "p6kmiptemplates5.conf" file. Thus the number specified as part of the '-t' option is appended to the end of the file name to select a template file. Note that 'number' can have the value {1..n}. If '-t' is not specified on the command line, then no template file is used during the command.
The '-t <number>' parameter can also be used for the "-encrypt" and "-decrypt" commands in order to define how the encryption should be performed (e.g., what cipher mode to use). This is described in detail later in this section.
Here is an example of a p6kmiptemplatesX.conf file. Note that all numeric values presented below are defined in the KMIP specification and can also be found in the p6kmip.h file.
All the currently allowed attributes that can appear in a template file are listed below.
The Cryptographic Usage Mask KMIP attribute can be specified in a template file. The values in the example above are the integer values of bit mask value. The values for the Usage Mask is defined in the p6kmip.h file, Section 9.1.3.3.1 Cryptographic Usage Mask (Bit mask). If no Cryptographic Usage Mask is define in the template file then the following default values are assigned by managed object type:
If all the values in the "ENCRYPTION" section (see above) are commented out or empty than the "-encrypt" and "-decrypt" operations will default to using: block cipher mode as ECB, padding method as PKCS5, and no IV. This is the same default values that will be used if the encrypt/decrypt operations do not specify a template on the command line (i.e., a "-t <number>").
The "blockCipherMode" parameter can take one of the values specified in the p6kmip.h file, Section 9.1.3.2.14 Block Cipher Mode Enumeration (e.g., CBC is 1). Also the "paddingMethod" parameter can take one of the values specified in the p6kmip.h file, Section 9.1.3.2.15 Padding Method Enumeration (e.g., PKCS5 is 3). If the chosen block cipher mode requires an IV value, then the "iv" parameter must be set with a hexadecimal encoded numeric string (max 100 digits). See the example above in the Encryption section.
The "-derivekey" operation requires the use of a template, that is a "-t" command line parameter must be present. A template is required since there are no good default values for these options. Possible options can be set in the "DERIVEKEY" section (see above). To enable an option just uncomment it and provide the desired value. Based on the value chosen for the "-method" command line parameter one or more of the following template options can be used:
The "-sign" and "-verify" operations require the use of a template, that is a "-t" command line parameter must be present. Possible options can be set in the "SIGN" section (see above). To enable an option just uncomment it and provide the desired value. In the example above, the values used for paddingMethod, hashAlgorithm, and cryptographicAlgorithm when used with a RSA key pair result in a valid digital signature.
In the next section, Basic Configuration Parameters, it is described how to define a KMIP server for this command line tool to communicate with. Looking at the examples below, namely "kmip44.example.com", you will notice the following parameters: KMIPPrivPEM, KMIPRootPEM, and KMIPCertPEM. These three files contain the TLS credentials to connect to the server, in this example, kmip44.example.com. These credentials are obtained by working with your server provider or IT staff.
All of these three files contain a "single" PEM certificate or private key. Some KMIP server providers will make available their server credentials as a single file or as a PKCS#12 file. This KMIP command line tool requires that those credentials be broken into three separate files with no extraneous text. Here is an example of a KMIPCertPEM certificate file in the proper format:
Notice that above example contains only the PEM encoded certificate starting and ending with the "--- ... ---" lines. Also please note that the KMIPPrivPEM private key file cannot be password protected.
Again looking at the example below of the p6kmiptool.conf file we notice that each server has its own "section" that starts with either the servers fully qualified domain name (FQDN) or IP address. (Note that for production only FQDN should be used.) The FQDN is on its own file with a pair of "[" "]" around it, thus "[kmip44.example.com]" For this command line tool to do anything meaningful at least one KMIP server has to be defined in the p6kmiptool.conf file.
This command line tool is made to work with KMIP servers that support the following KMIP protocol versions: 1.0, 1.1, 1.2. 1.3, and 1.4. Some of the commands in the tool like "-encrypt" and "-decrypt" require that the server support KMIP 1.3, and if the server in use does not then this tool will simply return an error output indicating that the feature is not available.
P6R's KMIP command line tool can be configured to work witn one or more KMIP servers at the same time. This section documents its possible conifguration parameters. Note that to configure the location of KMIP logging that parameter is set in the p6kmip.conf file. Here is a sample p6kmiptool.conf file as an example:
Note that there is no limit to the number of KMIP servers that can be defined in the p6kmiptool.conf file. The user specifies which server to use as a command line parameter (e.g., "p6kmiptool -export -server kmip44.example.com" )
Other possible token configuration items:
This contains the following KMIP command line tool wide configuration parameters:
The "baseKeyPath" configuration parameter (string value), is the symmetric key protecting the KMIP command line tool 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 KMIP command line tool 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 "locale" configuration parameter (string value), is optional and defaults to "en_us" if not set. This parameter is used to select the P6R language file to be used when displaying output to the user. The default P6R language file is p6kmiptool.en_us. For example, for French this parameter would be set to "fr_fr" and then the language file p6kmiptool.fr_fr would be used. The command line tool comes with the p6kmiptool.en_us language file. Customers who want to support different languages have to translage the p6kmiptool.en_us file to whatever language desired and rename that file with the proper file extension (e.g., ca_fr for French Canadian) where the first 2 characters represent the language and the last 2 characters represent the country. Note, that these files are encoded in UTF-8.
The "keystorePath" configuration parameter (string value), is optional and can be either the full path to a directory where the KMIP command line tool library wide keystore is to be created or a database URI of the standard for: "postgresql8://..." (see Keystore documentation). When this parameter is not provided then a default location is used. Otherwise, when using the full path to a local directory then a Sqlite database will be used. This keystore holds all the keys and certificates used to communicate to KMIP servers and all keys used to protect all other keystores created for software tokens.
Each section with a Fully Qualified Domain Nname defines parameters for a separate KMIP server:
The "KMIPPort" configuration parameter (positive numeric value), is optional with the default value of 5696 defined. It is passed to the Secure KMIP Client (SKC) library. ( The "KMIPMaxVersion" configuration parameter (string value), this parameter defines the maximum KMIP protocol that should be used to communicate with a remote KMIP server. This is an optional field and if not set the code will select the largest supporting protocol version. This automaically library calls the KMIP Discover Version operation to select the "best" protocol version to use.
The "KMIPsslOptions" configuration parameter (bit mask), is optional and maps to the SKC setSSLOptions( const P6WCHAR* pCiphers, P6SECURESOCKETFLAGS fSecureFlags ) API call's fSecureFlags parameter (see file p6kmpclient.h). This allows the caller to customize how it makes an TLS connection to a remote KMIP server. The default setting for this parameter is (P6SSF_METHOD_NEGOTIATE | P6SSF_SECURE_CLIENT | P6SSF_SECURE_CLIENT_AUTH | P6SSF_LOG_X509SUBJECTLOOKUPS) (see file p6net.h) and see below is a list of values that can be used to create a bit mask value for this parameter.
The "KMIPsslCiphers" configuration parameter (string value), is optional and is used to override the default library's TLS cipher settings. This string contains the OpenSSL cipher command (see https://www.openssl.org/docs/man1.0.2/apps/ciphers.html). If not defined then the following secure default will be used: "TLSv1+HIGH:TLSv1.2+HIGH:!SSLv2:!aNULL:!eNULL:!3DES:@STRENGTH" which enables SSLv3 and TLSv1, disables SSLv2, disables ciphers that do not use authentication, disables 3DES, and prefers the strongest ciphers fist.
The "KMIPInitFlags" configuration parameter (bit mask), is optional and maps to the SKC initialize( P6KMIPFLAGS flags, p6IKeystore* pCerts, P6KMIP_PREF preferences ) API calls's flags parameter (see file p6kmipclient.h. This has the default value of P6KMIPFLG_NOFLAGS. Note, that this parameter is how the user can control KMIP message logging (e.g., using the P6KMIPFLG_TRACE_MSGS flag value). The following values can be used to create a bit mask value for this parameter.
The "KMIPCertPEM" configuration parameter (string value), is the full path to a client side certificate (in PEM format) that was issued by a KMIP server to allow a KMIP client to authenticate itself. This certificate is copied into the command line tool wide keystore for use by SKC to create a TLS connection to a KMIP server. This is a required parameter per server.
The "KMIPPrivPEM" configuration parameter (string value), is the full path to the client's private key (in PEM format) that was issued by a KMIP server to allow a KMIP client to authenticate itself. This key is copied into the command line tool wide keystore for use by SKC to create a TLS connection to a KMIP server. This is a required parameter per server.
The "KMIPPrivSize" configuration parameter (positive numeric value), is the number of bits of the private key defined by the tokenKMIPPrivPEM configuration parameter. This is an optional parameter.
The "KMIPRootPEM" configuration parameter (string value), is the full path to the KMIP server's root certificate that was provided by a KMIP server to allow the Secure KMIP Client to create a TLS connection to the remote KMIP server. This is a required parameter per server.
The "KMIPconnectTimeout", "KMIPsendTimeout", and "KMIPreceiveTimeout" configuration parameters (positive numeric values), are units of time in milliseconds (e.g., 2000 is 2 seconds). All these parameters are optional and the library has a reasonable set of default values for each parameter.
The "KMIPcompatibility1" configuration parameter (bit mask), allows the user to modify the KMIP client's bahavior. If not define the client has reasonable internal defaults. The following values can be used to create a bit mask value for this parameter.
The "KMIPMaxBufSize" configuration paramter (positive numeric value), is the size of each allocated server buffer. The default value is 10000 bytes.
The "KMIPInitialBufCount" configuration parameter (positive numeric value), is the number of buffers the server should allocate on start up. The default value is 5 if not defined.
The "KMIPGrowBufsBy" 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 5 if not defined.
The "KMIPPrvKeyEncode", "KMIPPubKeyEncode", and "KMIPSymKeyEncode", configuration parameters (positive numeric values), are all optional and map to KMIP constants defined in the KMIP 1.2/1.3 specification under Section Section 9.1.3.2.3, Key Format Type Enumeration (also see p6kmip.h file). As an example, "PKCS8" key format has the value of 0x00000008.
The "KMIPUserName" and "KMIPPassword" configuration parameters (string values), are optional and map to KMIP user credentials (see SKC documentation p6kmipclient.h P6KMIP_CREDENTIAL definition).
The "KMIPPassword", "KMIPSerialNum", "KMIPDeviceId", "KMIPNetworkId", "KMIPMachineId", and "KMIPMediaId" configuration parameters (string values), are optional and map to KMIP device credentials (see SKC documentation p6kmipclient.h P6KMIP_CREDENTIAL definition).
The "logDir" configuration parameter (string value), is optional and when not provided a default value of "KMIP_TOOL" is used. Otherwise, the value defines the name the subdirectory to be created for logging under the main KMIP server's directory. For example, if this value was "TEST", then all the KMIP logs for the kmip44.example.com would be logged in the directory "../kmip44.example.com/TEST", the full path of this directory also takes into account the log directory defined in the p6kmip.conf file.
The "KMIPUseFlags" configuration parameter (bit mask), allows the user to modify how the KMIP client uses the KMIP protocol. If not defined the client has reasonable internal defaults. The following values can be used to create a bit mask value for this parameter.
The information defined in the p6kmiptool.conf file is loaded into a secure P6R keystore. The KMIP tool uses the information out of its keystore to process commands and only uses the p6kmiptool.conf to initialize that keystore. When the KMIP command line tool starts it checks to see if its keystore exists and if not then automatically creates it from the p6kmiptool.conf file.
One way to modify the values stored in the command line keystore is to delete it, modify the p6kmiptool.conf file, and then re-run the command line tool (e.g., p6kmiptool -h will do it). This update method will allow the user to remove existing KMIP server(s), add new KMIP server(s), and update an existing KMIP server's TLS parameters (i.e., certificates and private key). To delete the command line keystore remove the following 3 files: KMIP_CMD, KMIP_CMD.sig, kmipbasekey.txt (or whatever file name is used in the p6kmiptool.conf file under COMMAND-TOOL section, baseKeyPath parameter).
However, if all you want to do is to add a new KMIP server then just add that server to the p6kmiptool.conf file and run the command "p6kmiptool -config -add-server <FQDN>", where the "FQDN" is the new section add to the p6kmiptool.conf file. The result of this command will be to add the new server to the tool's keystore and then display all the configured KMIP servers.
When setting up a p6kmiptool.conf file please be aware that no two servers can have the same TLS credentials. The TLS cerfificate credentials are inserted into the P6R keystore using the unique values inside the certificate. Multiple copies of the same certificiate cannot exist in the same keystore for TLS credentials for the KMIP client.
For the use case where multiple clients use the same KMIP server but have different client TLS credentials the "-conf-file" parameter can be used. Some KMIP servers use the client TLS credentials to assign different access rights to KMIP groups etc. It is possible for a KMIP application to need to connect to the same KMIP server with different client authentication. This can be done by defining additional p6kmiptool.conf files (different file names and/or different paths from the default) where each new p6kmiptool.conf file must have the "keystorePath" configuration set to a unique path. Each additional p6kmiptool.conf file is set up to support the different KMIP client scenarios desired. Then all the user has to do is to include the "-conf-file <full file path conf file>" to all commands they which to use the different TLS credentials for. For each of these commands are different:
In the above example, the first command using "-config" uses the default configuration file "p6kmiptool.conf" in the same directory the code is running out of. However, the second command uses the configuration file at: "E:\skc-2016.2.16606\alternatives\p6kmiptool2.conf", which defines the user of a different keystore: keystorePath="e:\keystores\". The "-conf-file" parameter can be used on p6kmiptool command. And there is no limit on the number of different configuration / keystores that can be used.
Thus the user has flexibility to have multiple servers configured in just one configuration file or across several.
The fillowing curve names are supported in the "-genkeypair ... -curve <curve name>" command:
P_192, K_163, B_163, P_224, K_233, B_233, P_256, K_283, B_283, P_384, K_409, B_409, P_521, K_571, B_571, SECP112R1, SECP112R2, SECP128R1, SECP128R2, SECP160K1, SECP160R1, SECP160R2, SECP192K1, SECP224K1, SECP256K1, SECT113R1, SECT113R2, SECT131R1, SECT131R2, SECT163R1, SECT193R1, SECT193R2, SECT239K1, ANSIX9P192V2, ANSIX9P192V3, ANSIX9P239V1, ANSIX9P239V2, ANSIX9P239V3, ANSIX9C2PNB163V1, ANSIX9C2PNB163V2, ANSIX9C2PNB163V3, ANSIX9C2PNB176V1, ANSIX9C2TNB191V1, ANSIX9C2TNB191V2, ANSIX9C2TNB191V3, ANSIX9C2PNB208W1, ANSIX9C2TNB239V1, ANSIX9C2TNB239V2, ANSIX9C2TNB239V3, ANSIX9C2PNB272W1, ANSIX9C2PNB304W1, ANSIX9C2TNB359V1, ANSIX9C2PNB368W1, ANSIX9C2TNB431R1, BRAINPOOL_P160R1, BRAINPOOL_P160T1, BRAINPOOL_P192R1, BRAINPOOL_P192T1, BRAINPOOL_P224R1, BRAINPOOL_P224T1, BRAINPOOL_P256R1, BRAINPOOL_P256T1, BRAINPOOL_P320R1, BRAINPOOL_P320T1, BRAINPOOL_P384R1, BRAINPOOL_P384T1, BRAINPOOL_P512R1, BRAINPOOL_P512T1
