kmipcfg - configure the PKCS#11 KMIP provider
kmipcfg create [-i] <-o property=value> ... <server_group>
kmipcfg disable [-f] [server_group]
kmipcfg enable [-f] [server_group]
kmipcfg destroy [-f] [server_group]
kmipcfg list [-c] [-s] [-o propetry[,property,..]] [server_group]
kmipcfg set [-f ] <-o property=value> ... <server_group>
kmipcfg help [subcommand]
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) provides the system with access to the 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(1M) 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 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 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, colon-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.
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(5) object cache entries. The cache_ttl defaults to 300 seconds.
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 pass phrase 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.
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.
Destroys the KMIP server_group. If no server_group is specified, all server groups will be destroyed. Any components populated with 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 server groups.
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'.
Prints sensitive information stored in the KMIP server group configuration, for example, passwords used in secondary authentication. The –s option cannot be used with –p option.
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.
Prints the help for all subcommands or a specified subcommand.
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 client_p12=kmip-server-1_keys.p12 KMIP_serverExample 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 server port [5696]:
Add another KMIP server [y|N]: y
KMIP server: kmip-server-2.example.com
KMIP server port [5696]: 5697
Add another KMIP server [y|N]:
Connection timeout [5]:
Cache object time to live [300]:
Encoding [TTLV]: TTLV
Error: unknow encoding format.
Encoding [TTLV]:
Failover limit [3]: 1
Client keystore [/var/user/jf/kmip/KMIP_cluster]:
PKCS#12 bundle: /tmp/kmip_cluser_credentials.p12
Secondary authentication [none]: username-password
Username: jf_kmip
Password locator [prompt]:
Password: ********
Disable server group [y|N]:
Example 3 Disabling a KMIP Server Group
The following example disables a single KMIP server group.
$ kmipcfg disable
Do you want to disable all server groups [y|N]?
$ kmipcfg disable KMIP_server
Example 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: disabled
Hosts: kmip-server-1.example.com:5696
Connection timeout: 5
Cache object time to live [300]:
Encoding: TTLV
Failover limit: 3
Client keystore: /var/user/jf/kmip/KMIP_server
Client PKCS#12 bundle: kmip-server-1_keys.p12
Secondary authentication: none
Server group: KMIP_cluster
State: enabled
Hosts: kmip-server-1.example.com:5696
kmip-server-2.example.com:5697
Connection timeout: 5
Cache object time to live: 300
Encoding: TTLV
Failover limit: 1
Client keystore: /var/user/jf/kmip/KMIP_cluster
Client PKCS#12 bundle: kmip_cluser_credentials.p12
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
Connection timeout: 5
Cache object time to live: 300
Encoding: TTLV
Failover limit: 1
Client keystore: /var/user/jf/kmip/KMIP_cluster
Client PKCS#12 bundle: kmip_cluser_credentials.p12
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: 10
See attributes(5) for descriptions of the following attributes:
|
pktool(1), attributes(5), pkcs11_kmip(5)
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.