lskeygrp

The lskeygrp command displays a list of the key server key group entries on a specified storage image.

Read syntax diagramSkip visual syntax diagram lskeygrp  -dev  storage_image_ID  -s  -l  -state accessible inaccessible  unconfigured  rekeying -reckeystate  configured  newkeyveripend  newkeyauthpend  rekeyveripend  rekeyauthpend  recovauthpend  deconfauthpend disabled  enableauthpend  disableauthpend  -grpstatus  critical  degraded  failed  normal  not_normal  -mgrstatus  critical  degraded  failed  normal  not_normal  -type dar tct  endpoint  key_group_ID  ...  "-"

Parameters

-dev storage_image_ID
Displays the storage image ID, which includes manufacturer, machine type, and serial number. For example, IBM.2107-75FA120. The storage image ID is required if you do not specify a fully qualified key group ID, do not set the devid variable in your profile or through the setenv command, and the storage system is aware of more than one storage image.

Using the -dev parameter temporarily overrides any defined value for devid for the current command.

-s
(Optional). Displays only the attributes that are identified as short output. You cannot use the -s and the -l parameters together.
-l
(Optional). Displays the default output and extra attributes that are identified as long output. You cannot use the -l and the -s parameters together.
-state accessible | inaccessible | unconfigured | rekeying
(Optional) Displays the state of the key group.
-reckeystate configured | newkeyveripend | newkeyauthpend | rekeyveripend | rekeyauthpend | recovauthpend | deconfauthpend | disabled | enableauthpend | disableauthpend
(Optional) Displays the key groups with the specified recovery key state.
-grpstatus critical | degraded | failed | normal | not_normal
(Optional) Displays the key access status for all key servers that are associated with the specified key group. The value not_ normal displays for all key groups whose key access status is not "normal" or the state is inactive.
Note: The key groups with LOCAL keyprotocol are contained within the storage system rather than managed by an external key server.
-mgrstatus critical | degraded | failed | normal | not_normal
(Optional) Displays the key server path access status for all key servers that are associated with the specified key group. The value not_ normal displays for all key groups whose key server path summary status is not "normal" or the state is inactive.
Note: The key groups with LOCAL keyprotocol are contained within the storage system rather than managed by an external key server.
-type dar | tct | endpoint
(Optional) Displays the type of encryption that is used by the key group:
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.
key_group_ID ... | -
(Optional) Displays the ID for the key group that you want to view. The ellipsis (...) indicates that, optionally, you can specify multiple values. If you use the dash (-), the specified value is read from standard input. You cannot use the dash (-) while you are in the DS CLI interactive command mode.

Example 1: Displaying a list of the key server key group entries on a specified storage image.

dscli> lskeygrp

Output:

ID   state        reckeystate   reckeydate    datakeydate 
=========================================================
1    accessible   configured    04/28/2015    03/18/2018

keyprotocol  type   name        
============================
 KMIP        DAR    dar_encr      

Example 2: Displaying a list of the key server key group entries on a specified storage image.

dscli> lskeygrp -dev IBM.2107-75FA120 -l 0001
Output:
ID   state        reckeystate   reckeydate    datakeydate 
=========================================================
1    accessible   configured    04/28/2015    03/18/2018


grpstatus    mgrstatus   label        label2         keyprotocol
==========================================================================
critical     normal      CompanyABC   CompanyABC2    KMIP

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.
grpstatus
One of the following values of the key group access status:
Note: The grpstatus parameter is refreshed by either a background process that runs every 8 hours or after the managekeygrp command with -action testaccess processes. The following values that display depend on either process to determine when the grpstatus parameter is refreshed.

For example, if all key servers were recovered from an abnormal status, the grpstatus parameter displays failed because the status reflects either process that last completed unless a background process started or the 2 command with -action testaccess has processed again.

In addition, when a key group is created, the status always displays a "-" to indicate that the background process has not started or the managekeygrp command with -action testaccess has not processed.

critical
The key group has access to the key on a single key server and it represents a potential single point of failure. Use the showkeygrp command with the -access parameter to determine the access status for each key server on the HMCs.
degraded
The key group has access to the encryption key on two or more key servers, but not all key servers. Use the showkeygrp command with the -access parameter to determine the access status for each key server.
failed
The key group does not have access to the encryption key on any key server. Use the showkeygrp command with the -access parameter to determine the access status for each key server on the HMCs.
normal
The key group has access to the encryption key on all key servers.
"-"
The dash ( - ) indicates that the key group state is either unconfigured, rekeying, or was created but the background process has not started or the managekeygrp command with -action testaccess has not processed.
Note: The key groups with LOCAL keyprotocol are not configured on external key servers.
mgrstatus
One of the following values of the key server path access status:
critical
At least one key server for this key group reported an access status of normal, degraded, or critical.. Use the showkeymgr command with the -access parameter to determine the access status of each HMC.
Note: A system with only one HMC configured displays status as normal.
degraded
At least two key servers for the specified key group reported an access status of normal or degraded. Use the showkeygrp command with the -access parameter to determine the access status of each HMC.
failed
All key servers for this key group reported an access status of failed. Use the showkeymgr command with the -access parameter to determine the access status of each HMC.
normal
All key servers for this key group reported an access status of normal.
"-"
The dash ( - ) indicates that the state of the key group is either unconfigured or all key servers report a state of inactive.
Note: The key groups with LOCAL keyprotocol are not configured on external key servers.
label
The label for the key server key group. Because of the possible length of the label value, this column is the second to last column even as new columns are added to the output. Example MyCompany
label2
The second label for the key server key group. Because of the possible length of the label2 value, this column is the last column even as new columns are added to the output. Example MyCompany2
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).
LOCAL
The storage system scrambles the data key using a cryptographic algorithm and stores it locally, rather than obtaining the data key as a secret managed by an external key server. If Local Data-at-Rest Encryption is used, it is not necessary to configure external key servers.
type
The type of encryption that is used by the key group:
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.