zkey kms configure for the EKMF Web plug-in

Use the zkey kms configure command to configure the key-management system plug-in.

In the following, the command is described as it applies when working with the EKMF Web plug-in. For the KMIP plug-in context, see zkey kms configure for the KMIP plug-in.

Figure 1. zkey kms configure syntax for EKMF Web

TLS options

where:

-u or --ekmfweb-url <URL>

Specifies the URL of the EKMF Web server. The URL starts with https://, and can contain a port number, which is separated by a colon. The default port number is 443 for HTTPS.

-a or --apqns <adapter.domain, adapter.domain,...>

Associates cryptographic adapters (APQNs) in CCA coprocessor mode (APQNs) with the EKMF Web plug-in. You can specify multiple APQNs as a comma-separated list. Each APQN consists of an adapter and domain number separated by a period. All APQNs that you want to set, add, or replace must be online.

To add an APQN to an existing list, prefix the APQN with a plus sign (+).

To remove an APQN from the associated APQNs, prefix the APQN with a minus sign (-).

To set or replace the APQN association do not specify a prefix. You cannot mix + and - in one specification. You can either add, remove, or set the associations with one command.

-b or --tls-ca-bundle <ca_bundle>

Specifies the CA bundle PEM file, or the directory that contains the CA certificates that are used to verify the EKMF Web server certificate during the TLS handshake. If the option specifies a directory path, then this directory must be prepared with OpenSSL’s c_rehash utility.

The default is to use the system CA certificates.

--tls-client-cert <pem_file>

Specifies the PEM file that contains the client's TLS certificate for use with TLS client authentication.

--tls-client-key <priv_file>

If the PEM file is protected by a pass phrase, use this option to specify the pass phrase to unlock the PEM file that is specified with the --tls-client-key option.

--ts-client-key-passphrase <pass_phrase>

Specifies the PEM file that contains the client's private key for use with TLS client authentication.

--tls-pin-server-pubkey

For CA-signed EKMF Web server certificates: Pins the public key of the EKMF Web server. With a pinned key, it is verified that every connection uses the same EKMF Web server certificate as the one used when the connection to the EKMF Web server was configured.

--tls-trust-server-cert

Trusts the EKMF Web server's certificate even if it is a self-signed certificate, or it was not verified due to other reasons. Use this option instead of the --tls-pin-server-pubkey option when you are using self-signed EKMF Web server certificates.

--tls-dont-verify-server-cert

For self-signed key-management server certificates used in test environments: Bypasses the server certificate verification by default. For CA-signed server certificates, the default is to verify them.

This option overrides --tls-trust-server-cert.

--tls-verify-hostname

Verifies that the server certificate's Common Name field or a Subject Alternate Name field matches the hostname that is used to connect to the server.

-R or --refresh-settings

Refreshes the EKMF Web server settings. The settings are automatically refreshed when the connection to the EKMF Web server is configured or reconfigured. Use this option when the settings of the configured EKMF Web server changed.

-i or --gen-identity-key

Generates an identity key for the plug-in. An identity key is automatically generated for you when you configure the EKMF Web server connection. Use this option to generate a new identity key. If you regenerate the identity key you must also regenerate a registration certificate with the newly generated identity key, and reregister this zkey client with the EKMF Web server.

-c or --gen-csr <csr_pem>

Generates a certificate signing request (CSR) with the identity key and store it into the specified PEM file. You pass this CSR to a CA to have it issue a CA signed certificate for the plug-in. You need to register the certificate with the EKMF Web before you can access it.

-C or --gen-self-signed-cert <csr_pem>

Generates a self-signed certificate with the identity key and store it into the specified PEM file. You need to register the certificate with the EKMF Web server before you can access it.

-s or --cert-subject <rdns>

Specifies the subject name for generating a CSR or self-signed certificate, in the form <type>=<value>(;<type>=<value>)*[;] with types recognized by OpenSSL.

-e or --cert-extensions <name>=<value>

Specifies the certificate extensions for generating a CSR or self-signed certificate, as a semi-colon-separated list of the form <name>=[critical,]<value>(;<name>=[critical,]<value>),... with extension names and values recognized by OpenSSL. You can optionally include the critical attribute for any tag.

-N or --renew-cert <cert_pem>

Specifies an existing PEM file that contains the certificate to be renewed. The certificate's subject name and extensions are used to generate the CSR or renewed self-signed certificate.

-n or --csr-new-header

Adds the word NEW to the PEM file header and footer lines on the CSR. Some software and some CAs need this marking.

-d or --cert-validity-days <days>

Specifies the number of days the self-signed certificate is valid. The default is 30 days.

-D or --cert-digest <digest>

Specifies the digest algorithm to use when you generate a certificate-signing request or self-signed certificate. If this specification is omitted, the OpenSSL default is used.

-r or --register <cert_file>

Registers the zkey client with EKMF Web by generating an identity key in EKMF Web by using a certificate from the specified file. Supported certificate files formats are .pem, .crt, .cert, .cer, and .der (that is, either base64 or DER encoded).

To register a self-signed certificate that you are about to generate by using the --gen-self-signed-cert option, specify the same certificate file name here, and the generated certificate is registered immediately.

-T or --label-tags <tag>=<value>

Specifies the label tags for generating the identity key in EKMF Web when you register the zkey client. The label tags are a comma-separated list of tags and values, in the form <tag>=<value>,<tag>=<value>),... with tags as defined by the key template. Use the zkey kms info command to display the key templates. For registration, the template for identity keys is used.

Examples

To connect to the EKMF Web server on my.ekm-fweb.server, issue:
```
# zkey kms configure -u https://my.ekmfweb.server
```
To configure the connection to the EKMF Web server on my.ekmfweb.server, first pin the server’s public key from the server’s TSL certificate. Then verify that the hostname matches the server’s Common Name in the certificate, issue:
```
zkey kms configure -u https://my.ekmfweb.server --tls-pin-server-pubkey --tls-verify-hostname
```

To generate a certificate-signing request with the identity key and the specified subject name, and store it in a file named csr.pem, issue:
```
zkey kms configure -c csr.pem -s "CN=my.zkey.client;OU=Example;C=US"
```
To generate a certificate-signing request with the identity key to renew the existing certificate in the file named cert.pem and store it in a file named csr.pem, issue:
```
zkey kms configure -c csr.pem -N cert.pem
```
To generate a self-signed certificate with the identity key and the specified subject name and a validity of 50 days, and store it in a file named cert.pem, issue:
```
zkey kms configure -C cert.pem -s "CN=my.zkey.client;OU=Example;C=US" -d 50
```
To generate a self-signed certificate with the identity key and the specified subject name and a certificate extension to limit the key usage, and store it in a file named cert.pem, issue:
```
zkey kms configure -C cert.pem -s "CN=my.zkey.client;OU=Example;C=US" -e "keyUsage=critical,
digitalSignature,keyAgreement"
```
To register the zkey client with EKMF Web by using the certificate in the file named cert.pem, issue:
```
zkey kms configure -r cert.pem
```
To register the zkey client with EKMF Web by using the certificate in the cert.pem file, and the label tags ENV=TEST and APP=LINUX for the identity key, issue:
```
zkey kms configure -r cert.pem -T "ENV=TEST,APP=LINUX"
```