Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

kmipcfg (8)

Name

kmipcfg - configure the PKCS#11 KMIP provider

Synopsis

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> [-o property=<value>[...]]]
kmipcfg help [subcommand]
kmipcfg list [-c] [-s] [-H [-v]] [-o <property>] [server_group]
kmipcfg set [-f ] <-o property=value> ... <server_group>

Description

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(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.

Private KMIP Client Configuration

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.

Shared KMIP Client Configuration

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.

Sub Commands

The following subcommands are supported:

kmipcfg create [–i] <–o property=value> ... <server_group>

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:

state=enabled | disabled

The optional state of the server group. If not specified, the state is set to enabled.

server_list=<ip_address|host_name>[:<port_number],..

The mandatory, coma-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.

connection_timeout=<connection_timeout>

The optional number of seconds after which connection to the KMIP server times out. Default connection timeout is 5 seconds.

encode_type=TTLV

The optional format of encoding of the data transported by the KMIP protocol. The only supported value is TTLV.

failover_limit=<allowed_number_of_failovers>

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.

client_keystore=<path_to_the_keystore>

The optional path to the KMIP token directory. The default value of the property is the concatenated string $KMIPTOKEN_DIR/<server_group>.

p12_bundle=<path_to_pkcs#12_bundle>

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.

cache_ttl=<object_cache_entry_time_to_live_seconds>

The Time-To-Live value of the pkcs11_kmip(7) object cache entries. The cache_ttl defaults to 300 seconds.

server_cert_subj_cn_verify=enabled | disabled

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.


Note -  Due to security reasons, it is generally not recommended to change this option.
secondary_authentication=none | username-password, <username-password-parameters> | device, <device-parameters>

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:

prompt

Command prompts for the password.

file://<filename>

Passphrase file location in a file system.

https://<location>

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.

token_state=enabled | disabled

Enables or disables the respective PKCS#11 token.

kmipcfg destroy [–f] [server_group]

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.

–f

Specifies force removal of a KMIP server group. If no server group is specified, the option forces removal of all the server groups.

kmipcfg disable [–f] [server_group]

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.

–f

Specifies force disabling of all KMIP server groups. This option has no effect if server_group is specified.


Note -  This command is equivalent to kmipcfg set -o state=disabled.
kmipcfg enable [–f] [server_group]

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.

–f

Specifies force disabling of all KMIP server groups. This option has no effect if server_group is specified.


Note -  This command is equivalent to kmipcfg set -o state=enabled.
kmipcfg extract [–p <filename>] [–s] [–t <all | pkcs11libkmip>] <server_group>

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.

–p <filename>

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.

–s

This option extracts sensitive information. For example, encoded certificates, and PKCS#12 bundle pin.

–t <all | pkcs11 | libkmip>

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.

<server_group>

Existing server group whose configuration is used in the extracted AI profile.

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> [–o property=<value>[...]]]

Generates an SMF profile, based on the parameters provided in the option arguments.

–i

Asks interactively for the configuration properties.

–N <property_group_name>

If not specified, the default property group name, kmip_client_default, is used.

–T <property_group_type>

If not specified, the default property group type, kmip_client_config, is used.

–o cred_source_type=raw | path

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.

–o private_key=<path>

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.

–o cert=<path>

Path to the certificate of the client.

If a relative path is specified, the path will be resolved relatively to the client_keystore directory.

–o ca_cert=<path>

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.

–o p12_bundle=<path>

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.

–o p12_bundle_pass=<locator>

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.

–o property=<value>

This option sets the remaining server group specific properties specified in the kmipcfg create command.

For the remaining options, see the kmipcfg extract section.

kmipcfg help [subcommand]

Prints the help for all the subcommands, or a specified subcommand.

kmipcfg list [–c] [–s] [–o property[,property,..]] [server_group]

Lists parameters configured using kmipcfg create command. If server_group is specified, only configuration parameters of theserver_group are listed.

–c

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.

–s

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.

–H

Lists configuration in parsable form using a semicolon as a delimiter.

–v

This option prints a header line with the respective property names, along with the output provided by the –H option (values).

–o

Lists a specific configuration parameter. Use comma to delimit multiple parameters.

kmipcfg set [–f] <–o property=value> ... <server_group>

Sets configuration parameters of the server_group. For a list of the configuration parameters refer to the kmipcfg create command.

–f

Specifies force setting the properties in all KMIP server groups. This option has no effect if server_group is specified.

Exit Status

The following exit values are returned:

0

Successful completion.

1

A fatal error occurred.

2

An usage error occurred.

Examples

Example 1 Creating a KMIP Server Group Non-Interactively

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]:
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: /tmp/kmip_cluser_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]: y
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: enabled
Hosts: kmip-server-1.example.com:5696
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
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: /tmp/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
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: /tmp/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: 10
Example 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=/tmp/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"

Note -  The output of the command is not included.
Example 9 Generate an SMF Profile Interactively

The following example generates an SMF profile interactively.

# kmipcfg extract -s -i -p /tmp/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]:
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: /tmp/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]:
#

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/library/security/pkcs11_kmip
Interface Stability
Uncommitted
Utility Output Format
Not-an-Interface

See Also

pktool(1), attributes(7), pkcs11_kmip(7)

Notes

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.