kmipcfg - configure the PKCS#11 KMIP provider
kmipcfg create [-i] -o property=value ... server_group
kmipcfg destroy [-f] [server_group]
kmipcfg disable [-f] [server_group]
kmipcfg enable [-f] [server_group]
kmipcfg extract [-p filename] [-s][-t all|pkcs11|libkmip] server_group
kmipcfg extract [-p filename] [-s] [-i] [-t all|pkcs11|libkmip]
[{-S service_instance_fmri [-N property_group_name]
[-T property_group_type] [-o cred_source_type=raw|path]
[{-o private_key=path -o cert=path [-o ca_cert=path]} |
{-o p12_bundle=path -o p12_bundle_pass=locator}]
[-o property=value] ...}]
kmipcfg help [subcommand]
kmipcfg info [-n] [-H [-v]] [-o property[,property,...]] [server_group]
kmipcfg list [-c] [-s] [-H [-v]] [-o property[,property,...]]
[server_group]
kmipcfg set [-f] -o property=value ... server_group
The kmipcfg command is used to initialize and manage states of the PKCS#11 Key Management Interoperability Protocol (KMIP) provider in the Solaris Cryptographic Framework (SCF).
The KMIP provider, pkcs11_kmip(7), provides the system with access to remote KMIP servers. The communication between the client and the server is secured with TLS. Multiple remote KMIP systems can be grouped into server groups. It is assumed that a KMIP client using the same credentials is able to communicate with any of the servers in the server group. All servers in the server group must support the same KMIP protocol versions. Communication with any of the KMIP server group members provides information about the supported KMIP protocol version of any other server group member.
In the PKCS#11 framework, the KMIP provider functions as a slot, and each KMIP server group functions as a token. A system administrator uses cryptoadm(8) to enable the KMIP provider and the kmipcfg command to configure KMIP tokens. The pktool(1) command can be used to review the state of the tokens from the PKCS#11 perspective.
The user specific (private) KMIP configuration is file based. The configuration files of the individual Solaris KMIP client components are stored in user specific directories. Access to the configuration is determined by the access control mechanisms of the respective target filesystem with the configuration store.
The KMIPTOKEN_DIR environment variable points to the base directory with KMIP tokens. The KMIP token is represented by a subdirectory in the KMIPTOKEN_DIR environment variable. When configured, each of the token directories contains KMIP configuration and credentials required for communication with the KMIP server.
The KMIPTOKEN_DIR environment variable defaults to: /var/user/$USERNAME/kmip. The USERNAME environment variable is the respective username associated with the RUID of the executed kmipcfg command.
The user independent (shared) KMIP client configuration is stored in smf service instances representing Solaris KMIP client components. Only authorized users can access information from these instances. The used authorization model follows rbac implementation described in the smf_security(7) man page. For more information, see the smf(7) and rbac(7) man pages.
The users who are granted access to the shared KMIP configuration can find the Default KMIP token server group in the output of kmipcfg list. A token with the same name is also listed in the output of the pktool tokens command.
The following subcommands are supported:
Creates a new server_group (KMIP token). A directory in the path KMIPTOKEN_DIR/<server_group> is created and populated with the KMIP client configuration and credentials.
The server group name is restricted to any alphanumeric, dash and underscore characters. Maximum length of the server group name is 32 bytes.
The –i option specifies the interactive configuration of the KMIP server group.
Configuration and the credentials can be specified using property=value pairs. The following properties can be set:
The optional state of the server group. If not specified, the state is set to enabled.
The mandatory, comma-delimited list of IP addresses or host names of the KMIP servers. If an IPv6 address and port are specified, the IPv6 address must be enclosed in the square brackets. If port_number is not specified, the default port 5696 is used.
Required KMIP protocol version. If auto is set the best match with the server is applied. Default value is auto.
The optional number of seconds after which connection to the KMIP server times out. Default connection timeout is 5 seconds.
The optional format of encoding of the data transported by the KMIP protocol. The only supported value is TTLV.
The optional upper boundary of allowed failovers between KMIP servers defined in server_list. If failover_limit is not specified or is set to 0, the failover limit defaults to 2. If failover_limit is set to -1, the failover will be disabled.
The optional path to the KMIP token directory. The default value of the property is the concatenated string $KMIPTOKEN_DIR/server_group.
The mandatory path to the PKCS#12 bundle. If a relative path is specified, the path will be resolved relatively to the client_keystore directory.
The Time-To-Live value of the pkcs11_kmip(7) object cache entries. The cache_ttl defaults to 300 seconds.
Enables or disables subject CN verification in the server certificate. Some KMIP server implementation incorrectly fills in the CN in the server's certificate provided by the server, during the TLS hand shake. This option workarounds it, and continues establishing the TLS session. By default, the server_cert_subj_cn_verify is enabled.
The optional type of the secondary authentication. If none is specified, no secondary authentication parameters will be configured. If the chosen type of secondary authentication is username-password or device, comma-delimited configuration properties must be appended.
username-password-parameters: username, password
device-parameters: device_serial_number, password,
device_identifier, network_identifier,
machine_identifier, media_identifier
'password' property requires a locator string:
password=prompt | file:// | https://
where:
Command prompts for the password.
Passphrase file location in a file system.
The passphrase file location on a secure server. The GET on the URL returns only the password string. The certificate presented by the server must be the one trusted by libcurl and OpenSSL.
Secondary authentication defaults to none.
Enables or disables the respective PKCS#11 token.
Destroys the KMIP server_group. If no server_group is specified, all server groups will be destroyed. Any components populated with the kmipcfg create command will be removed from the system. The KMIP token represented by the KMIP server_group will be removed from the list of PKCS#11 tokens.
Specifies force removal of a KMIP server group. If no server group is specified, the option forces removal of all the server groups.
Disables the KMIP server_group. If no server_group is specified, all server groups will be disabled. The KMIP token represented by the KMIP server_group is removed from the list of PKCS#11 tokens.
Specifies force disabling of all KMIP server groups. This option has no effect if server_group is specified.
Enables the KMIP server_group. If no server_group is specified, all server groups will be enabled. The KMIP token represented by the KMIP server_group reappears in the list of PKCS#11 tokens.
Specifies force disabling of all KMIP server groups. This option has no effect if server_group is specified.
Generates an SMF profile based on the existing server group configuration. The SMF profile is usable in a variety of installation and configuration contexts. For more information, see the service_bundle(5), smf(7), installadm(8), sysconfig(8), and zoneadm(8) man pages.
The extracted profile will be stored in filename. If the extract subcommand is executed without specifying the –p option, the generated profile is printed out to the standard output.
The SMF profiles must have the .xml extension.
This option extracts sensitive information. For example, encoded certificates, and PKCS#12 bundle PIN.
Extracts profile for the svc:/system/pkcs11:kmip service instance (pkcs11), svc:/system/kmip/client:default service instance (libkmip), or both of them (all). By default all profiles are extracted.
Existing server group whose configuration is used in the extracted AI profile.
Generates an SMF profile, based on the parameters provided in the option arguments.
Asks interactively for the configuration properties.
If not specified, the default property group name, kmip_client_default, is used.
If not specified, the default property group type, kmip_client_config, is used.
Sets whether the data stored in the private_key, cert, ca_cert, and p12_bundle properties will be paths to the given files in the filesystem (path), or whether the files will be read, Base64 encoded, indexed and stored into the respective property values (raw). If not specified, the option defaults to raw.
Path to the private key of the client.
If a relative path is specified, the path will be resolved relatively to the client_keystore directory.
Path to the certificate of the client.
If a relative path is specified, the path will be resolved relatively to the client_keystore directory.
If not set, the certificate of the server will be verified using the CA certificate bundled with the operating system. If the path points to a directory instead of a file, files in that directory must be CA certificates in PEM format. All such certificates are loaded and trusted. Use c_rehash (1openssl) to calculate hashes of the certificates and create symbolic links to the files with certificates.
If a relative path is specified, the path will be resolved relatively to the client_keystore directory.
If specified, the provided PKCS#12 bundle should contain the client key, the client certificate, and the CA certificate.
If a relative path is specified, the path will be resolved relatively to the client_keystore directory.
Locator points to the source of the PKCS#12 bundle passphrase. For locator details, see the description of password in the secondary_authentication property section of the kmipcfg create command.
This option sets the remaining server group specific properties specified in the kmipcfg create command.
For the remaining options, see the kmipcfg extract section.
Prints the help for all the subcommands, or a specified subcommand.
Connect to the server_group and show supported versions and its capabilities.
Show numeric values for supported operations and objects instead of names.
Lists configuration in parsable form using a semicolon as a delimiter.
This option prints a header line with the respective property names, along with the output provided by the –H option (values).
Lists a specific configuration parameter. Use comma to delimit multiple parameters.
Lists parameters configured using kmipcfg create command. If server_group is specified, only configuration parameters of the server_group are listed.
Lists configuration parameters in a format that can be used by the non-interactive kmipcfg create command. Sensitive information is not printed. The password locator string is always set to prompt. The –c option cannot be used with the –H option.
Prints sensitive information stored in the KMIP server group configuration, for example, passwords used in secondary authentication. The –s option cannot be used with the –c option.
Lists configuration in parsable form using a semicolon as a delimiter.
This option prints a header line with the respective property names, along with the output provided by the –H option (values).
Lists a specific configuration parameter. Use comma to delimit multiple parameters.
Sets configuration parameters of the server_group. For a list of the configuration parameters refer to the kmipcfg create command.
Specifies force setting the properties in all KMIP server groups. This option has no effect if server_group is specified.
The following exit values are returned:
Successful completion.
A fatal error occurred.
An usage error occurred.
The following command will create a server group "KMIP_server" with only one KMIP server. Credentials used to authenticate and secure the communication are provided in the kmip-server-1_keys.p12 PKCS#12 bundle.
% kmipcfg create -o server_list=kmip-server-1.example.com:5696 \
-o p12_bundle=kmip-server-1_keys.p12 KMIP_server
Example 2 Creating a KMIP Server Group Interactively
The following command will configure a server group "KMIP_cluster" in the interactive mode. To confirm a default property value, press enter.
% kmipcfg create -i KMIP_cluster KMIP server: kmip-server-1.example.com KMIP port [5696]: Add another KMIP server [y|N]: y KMIP server: kmip-server-2.example.com KMIP port [5696]: 5697 Add another KMIP server [y|N]: Required version [auto]: Connection timeout [5]: Cache object time to live [300]: Encode type [TTLV]: TTLV Failover limit [3]: 1 Client keystore [/var/user/jf/kmip/KMIP_cluster]: PKCS#12 bundle: /var/user/jf/kmip/kmip_cluster_credentials.p12 Verify CN in the subject of the server certificate [Y|n]: Secondary authentication [none]: username-password Username: jf_kmip Password locator [prompt]: Disable the respective PKCS#11 token [y|N]: 'username-password' password: *********Example 3 Disabling a KMIP Server Group
The following example disables a single KMIP server group.
# kmipcfg disable Do you really want to disable server group 'Default KMIP token' [y|N]: y Do you really want to disable all user specific server groups [y|N]: yExample 4 Listing Configuration Parameters
The following command lists the configuration of all the KMIP server groups (KMIP tokens) in the KMIPTOKEN_DIR path.
% kmipcfg list
Server group: KMIP_server
State: enabled
Hosts: kmip-server-1.example.com:5696
Required version: auto
Connection timeout: 5
Cache object time to live: 300
Encode type: TTLV
Failover limit: 1
Client keystore: /var/user/jf/kmip/KMIP_server
Client PKCS#12 bundle: kmip-server-1_keys.p12
Server certificate subject CN verification: enabled
Secondary authentication type: none
Server group: KMIP_cluster
State: enabled
Hosts: kmip-server-1.example.com:5696
kmip-server-2.example.com:5697
Required version: 1.4
Connection timeout: 5
Cache object time to live: 300
Encode type: TTLV
Failover limit: 1
Client keystore: /var/user/jf/kmip/KMIP_cluster
Client PKCS#12 bundle: /var/user/jf/kmip/kmip_cluser_credentials.p12
Server certificate subject CN verification: enabled
Secondary authentication type: username-password
Username: jf_kmip
Password:
Example 5 Listing Configuration Parameters of a Server Group
The following command lists configuration of a single server group and any sensitive information.
% kmipcfg list -s KMIP_cluster
Server group: KMIP_cluster
State: enabled
Hosts: kmip-server-1.example.com:5696
kmip-server-2.example.com:5697
Required version: 1.4
Connection timeout: 5
Cache object time to live: 300
Encode type: TTLV
Failover limit: 1
Client keystore: /var/user/jf/kmip/KMIP_cluster
Client PKCS#12 bundle: /var/user/jf/kmip/kmip_cluser_credentials.p12
Server certificate subject CN verification: enabled
Secondary authentication type: username-password
Username: jf_kmip
Password: changeme
Example 6 Setting Configuration Parameters
The following example lists and sets a configuration parameter of a specific KMIP server group.
% kmipcfg list -o connection_timeout KMIP_server Connection timeout: 5 % kmipcfg set -o connection_timeout=10 KMIP_server % kmipcfg list -o connection_timeout KMIP_server Connection timeout: 10Example 7 List KMIP Client Certificate Stored in the Configuration of "Default KMIP token"
The following example lists the KMIP client certificate stored in the configuration of "Default KMIP token".
# kmipcfg list -o cred_source_type "Default KMIP token" TLS credentials source type: raw # kmipcfg set -o cert=/var/user/jf/kmip/cert.pem "Default KMIP token" # kmipcfg list -o cert -s "Default KMIP token" Client certificate: 1612 Bytes 0 : <client_cert_data_Base64_encoded> 73 : <client_cert_data_Base64_encoded> 1533 : <client_cert_data_Base64_encoded> 1606 : <client_cert_data_Base64_encoded>
The Base64 encoded data can be easily transformed to the human readable form using the following command pipeline:
# kmipcfg list -s -o cert -H "Default KMIP token" | base64 -d | \
openssl x509 -noout -text
Example 8 Generate an SMF Profile
The following command generates an SMF profile based on the values configured from an existing server group, and also includes sensitive information.
# kmipcfg extract -s "Default KMIP token"
The following example generates an SMF profile interactively.
# kmipcfg extract -s -i -p ./profile.xml Extract service instance [all]: Libkmip configuration in service instance [svc:/system/kmip/client:default]: Property group name [kmip_client_default]: Property group type [kmip_client_config]: KMIP server: kmip-server-1.example.com KMIP port [5696]: Add another KMIP server [y|N]: Required version [auto]: Connection timeout [5]: Cache object time to live [300]: Encode type [TTLV]: Failover limit [3]: Client keystore [/var/user/root/kmip/]: Credentials source type [raw]: Private key: Certificate: CA certificate: PKCS#12 bundle: /var/user/jf/kmip/kmip_cred_bundle.p12 PKCS#12 bundle password locator [prompt]: 'p12_bundle_pass' password: ******** Verify CN in the subject of the server certificate [Y|n]: Secondary authentication [none]: Disable the respective PKCS#11 token [y|N]: Enable svc:/system/pkcs11:kmip service instance [y|N]: #Example 10 Get information about server capabilities.
Following example shows configured server capabilities.
# kmipcfg info kmip_vbox
Enter PIN for kmip_vbox:
Server group:
kmip_vbox
Supported versions:
1.4, 1.3, 1.2, 1.1, 1.0
Server info:
Gemalto, Inc.
Operations:
Create, Create Keypair, Register, Locate, Get,
Get Attributes, Get Attribute List, Add Attribute, Modify
Attribute, Delete Attribute, Activate, Revoke, Destroy, Query,
Rekey, Rekey Keypair, Check, Discover Versions
Object types: Symmetric Key, Public Key, Private Key, Secret Data,
Opaque
Attestation types:
NONE
Rng params:
NONE
Profiles:
NONE
Validations:
NONE
Capabilities:
NONE
Client registration methods:
NONE
See attributes(7) for descriptions of the following attributes:
|
pktool(1), attributes(7), pkcs11_kmip(7)
PKCS#11 clients require a KMIP server supporting Key Management Interoperability Protocol Specification Version 1.1.
The minimal contents of the PKCS#12 bundle are the client's certificate and private key. If the client's certificate cannot be verified using the default CA certificates, the respective CA certificate must be included.