lskeymgr

Edit online

The lskeymgr command displays a list of key servers that are on the storage complex and provides status information for those key servers.

The terms key server and key manager are closely related and sometimes used interchangeably. The key manager is the program that runs on a physical server and provides key services to key clients, such as the storage system. Key services include generating, storing, and retrieving encryption keys. This command uses the term key server to indicate both the physical server and the key manager.

Parameters

-s

(Optional) Displays the key server IDs.

-l

(Optional) Displays the default output.

-serverport port_ID

(Optional) Displays the key servers that use the port ID that you specify. The key server port ID is 4 or 5 decimal characters. For example, 8100 is a valid port ID.

-state active | inactive

(Optional) Displays the key servers that are in the state that you specify.

-type dar | tct | endpoint

(Optional) Displays the registered key servers that use one of the following specified types of encryption.

dar: Encryption for data at rest, which encrypts data that is stored on your storage system. This value is the default.
tct: Encryption for transparent cloud tiering, which ensures that data is encrypted before it is transferred to cloud storage. The data remains encrypted in cloud storage and is decrypted after it is transferred back to the storage system.
endpoint: Encryption for IBM Fibre Channel Endpoint Security, which establishes authenticated communication and encryption of data in flight for Fibre Channel connections between an IBM Z® host and the storage system. The connections are secured by Fibre Channel security protocols and key server authentication that uses communication certificates. If both the host and storage system use a connection with Fibre Channel ports that support encryption, the connection will transmit encrypted data between the ports.

-keygrp key_group_ID | ...

(Optional) Displays one or more key group IDs that are associated with the specified key manager. The ellipsis (...) indicates that, optionally, you can specify multiple values.

(Optional) Displays the status of the key server path. Only key servers that display the status of the specified key server path are displayed. The value not_normal displays for all key servers whose status is not "normal" or whose state is inactive.

-addr IP_address

(Optional) Displays the key server that uses the IP address you specify. The IP address can be an IPv4 address, an IPv6 address, or a DNS name.

key_server_ID ... | -

(Optional) Displays the key servers that use the ID or IDs you specify. To include multiple IDs, separate each ID with a blank space. For example, 1 2 3 4. The ellipsis (...) indicates that, optionally, you can specify multiple values. If you use the ( - ) dash option, this value can be read from standard input.

Example 1: Displaying the key server protocol.

dscli> lskeymgr -l

Output:


ID  State     Status  Addr                  Server  Key
                                            Port    Protocol
============================================================
1   active    normal  2001:0db8:85a3:08d3:  3801    KMIP
                      1319:8a2e:0370:7334
2   active    normal  2001:0db8::1428:57ab  3801    KMIP
3   inactive  -	      ::ffff:9.11.56.78     3801    KMIP

Output definitions

ID^*

The key server identification number. For example, 4.

State

One of the following states of the key server displays:

active: The key server is configured for a key exchange with the specified HMC.
inactive: The key server is configured, but does not exchange any key with the specified HMC.

Status

One of the following statuses the key server path:

critical

Only one Hardware Management Console (HMC) has access to the specified key server and it represents a potential single point of failure. This status critical replaces hmc1_degraded and hmc2_degraded on newer systems.

Use the showkeymgr command with the -access parameter to determine the status of each HMC.

Note: A system with only one HMC configured displays the status as normal.

degraded

Two or more HMCs have access to the specified key server, but at least one other HMC does not.

failed

Neither HMC1 or HMC2 have access to the key server.

hmc1_degraded

HMC2 has access to the specified key server, but HMC1 does not.

Newer systems display this status as critical.

Use the showkeymgr command with the -access parameter to determine the status of each HMC.

hmc2_degraded

HMC1 has access to the specified key server, but HMC2 does not.

Newer models display this status as critical.

Use the showkeymgr command with the -access parameter to determine the status of each HMC.

normal

All HMCs have access to the specified key server.

"-"

The dash (-) indicates that the specified key server is not an active key server.

Addr

The IP address of the key server.

Server Port

The key server port number, which is 4 or 5 decimal characters from 1 - 65535. For example, 8100.

Keyprotocol

The key server protocol that the storage system communicates with to provide key server management operations.

IPP: The storage system communicates with the specified key server using the IBM Proprietary Protocol (IPP).
KMIP: The storage system communicates with the specified key server using the Key Management Interoperability Protocol (KMIP).

Example 2: Displaying the type associated with the key server.

dscli> lskeymgr

Output:


ID     state    reckeystate  reckeydate  datakeydate keyprotocol   type     name 
=====================================================================================
1    accessible configured   02/21/2018   3/07/2018    KMIP      Endpoint endpoint_encr

Output definitions

ID

The key group ID.

state

One of the following states of the key group:

accessible: The key group is accessible if it is configured and the storage image has the key group from the key server for the specified key group.
inaccessible: The key group is inaccessible if the storage image was unable to obtain the key group from the key server.
unconfigured: The key group is unconfigured if it has not been configured.
rekeying: The key group is accessible and rekeying if it is configured and the storage image has the encryption key from the key server for the key group and is in the middle of rekeying.

reckeystate

One of the following states of the recovery key:

configured: A new recovery key was requested, verified, and authorized.
unconfigured: A recovery key was not created.
newkeyveripend: A new recovery key was requested but not verified.
newkeyauthpend: A new recovery key was requested and verified, but not authorized.
rekeyveripend: A new recovery key action was requested but not verified.
rekeyauthpend: A new recovery key action was requested and verified, but not authorized.
recovauthpend: A recover action was requested, but not authorized.
deconfauthpend: A deconfigure action was requested, but not authorized.
disabled: A recovery key was disabled, and the key group is used without a recovery key.
enableauthpend: An enable action was requested, but not authorized.
disableauthpend: A disable action was requested, but not authorized.

reckeydate

The date of the last recovery key creation.

datakeydate

The date of the last data key creation. If the key group is unconfigured, then any displayed date is to be considered erroneous data.

keyprotocol

The key server protocol that the storage system communicates with to provide key server management operations.

IPP: The storage system communicates with the specified key server using the IBM Proprietary Protocol (IPP).
KMIP: The storage system communicates with the specified key server using the Key Management Interoperability Protocol (KMIP).

type

The type of encryption that is used by the key group. The descriptions are described

DAR: Encryption for data at rest, which encrypts data that is stored on your storage system. This value is the default.
TCT: Encryption for transparent cloud tiering, which ensures that data is encrypted before it is transferred to cloud storage. The data remains encrypted in cloud storage and is decrypted after it is transferred back to the storage system.
Endpoint: Encryption for IBM Fibre Channel Endpoint Security, which establishes authenticated communication and encryption of data in flight for Fibre Channel connections between an IBM Z host and the storage system. The connections are secured by Fibre Channel security protocols and key server authentication that uses communication certificates. If both the host and storage system use a connection with Fibre Channel ports that support encryption, the connection will transmit encrypted data between the ports.

name

The user-specified name that is used to identify the key group.