keysvrmgr Command

Purpose

Manages the Object Data Manager (ODM) database entries that are associated with the encryption key server when the logical or physical volume uses the key server key-protection method for encryption.

Syntax

keysvrmgr action -t server_type [-h] { -a attribute=value ... } server_name

Description

An encryption key server is used to securely store encryption key information. The key servers: keyserv (IBM Security Key Lifecycle Manager), Key Protect (IBM Cloud Key Protect), and hpcs (IBM Cloud Hyper Protect Crypto Services) are supported by the AIX 7.3 operating system. Access to the keyserv server is secured by certificate exchanges between the client and the server. Access to the Key Protect (KP) and hpcs servers are secured by the Key Protect / HPCS credentials (API key and access token). When a logical volume (LV) uses the key server key-protection method for encryption, the information about the encryption key server is stored in the ODM database. You can use the keysvrmgr command to manage the ODM database entries that are associated with the encryption key server.

The server_name identifies an ODM record in the ODM database.

Flags

-t

Specifies the type of key servers that are supported by the keysvrmgr command.

keyserv

IBM Security Key Lifecycle Manager

hpcs

IBM Cloud IBM Key Protect or IBM Cloud Hyper Protect Crypto Services

-a

Specifies an attribute_name=attribute_value pair. The attribute_name is the name of the ODM attribute and the attribute_value is the value of the specified ODM attribute that is saved in the ODM database record.

Key server ODM attributes

Key Protect and hpcs server ODM attributes

action parameters

add

Syntax:

To add the hpcs server entry to the HpcsSvr ODM database, run the following command:

keysvrmgr add -t hpcs [-h] -a svr_name=value -a inst_id=value -a api_key=value -a svr_region=value

To add the keyserv server entry to the KeySvr ODM database, run the following command:

keysvrmgr add -t keyserv [-h] -a svr_name=value [ -a dev_grp=value ] -a svr_ip=value [ -a svr_port=value ] -a svr_cert=value -a cli_cert=value [ -a cert_pwd=[y|Y|n|N|p|P] ]

The key server ID is created in the svr_name[:dev_grp] format:

Starting from AIX 7.3, Technology Level 1, the following syntax is deprecated:

keysvrmgr add [-h] -i server_ip [-p server_port] [-g sklm_device_group] -s server_cert_path -c client_cert_path [-P type] server_id

This action parameter can be specified with the following flags:

-i

Specifies the IP address of the encryption key server in the following format:

a.b.c.d

where each value of a, b, c, and d are in the range 0 - 255.

-p

(Optional) Specifies the port of the encryption key server. You can specify a port value in the range 0 – 65535. The default value is 5696.

-g

(Optional) Specifies the device group name associated with IBM Security Key Lifecycle Manager.

-s

Specifies the absolute path to the X.509 server certificate associated with the encryption key server.

-c

Specifies the absolute path of the Public Key Cryptography Standards #12 (PKCS #12) client certificate associated with your system.

-P

Specifies the type of password protection for the client certificate. You can specify the following values for this flag:

• y|Y – The password of the client certificate will be prompted during the command run time.
• n|N – The client certificate is not protected by a password. This is the default value.
• p|P – The password of the client certificate is stored in platform keystore (PKS).

server_id

Specifies the ID of the encryption key server entry that you want to create in the following format:

server_name[:device_group]

where server_name is the name of the key server entry and device_group is the name of the device group associated with IBM Security Key Lifecycle Manager.

modify

Syntax:

To modify the HpcsSvr ODM entry that is identified by the value of the svr_name attribute by using the new values from inst_id, api_key and svr_region attributes, run the following command:

keysvrmgr modify -t hpcs [-h] -a svr_name=value [ -a inst_id=value ] [ -a api_key=value ] [ -a svr_region=value ]

To modify the HpcsSvr ODM entry that is identified by the value of svr_name attribute by using the new values from dev_grp, svr_ip, svr_port, svr_cert, cli_cert, and cert_pwd attributes, run the following command:

keysvrmgr modify -t keyserv [-h] -a svr_id=value [ -a dev_grp=value ] -a svr_ip=value [ -a svr_port=value ] [ -a svr_cert=value ] [ -a cli_cert=value ] [ -a cert_pwd=[y|Y|n|N|p|P] ]

Starting from AIX 7.3, Technology Level 1, the following syntax is deprecated:

keysvrmgr modify [-h] -i server_ip [-p server_port] [-s server_cert_path] [-c client_cert_path] [-P type] server_id

This action parameter can be specified with the following flags and values:

-i

Specifies the IP address of the encryption key server in the following format:

a.b.c.d

where each value of a, b, c, and d are in the range 0 - 255.

-p

(Optional) Specifies the port of the encryption key server. You can specify a port value in the range 0 – 65535. The default value is 5696.

-s

Specifies the absolute path to the X.509 server certificate associated with the encryption key server.

-c

Specifies the absolute path of the PKCS #12 client certificate associated with your system.

-P

Specifies the type of password protection for the client certificate. You can specify the following values for this flag:

• y|Y – The password of the client certificate will be prompted during the command run time.
• n|N – The client certificate is not protected by a password. This is the default value.
• p|P – The password of the client certificate is stored in platform keystore (PKS).

server_id

Specifies the ID of the key server entry that you want to modify in the following format:

server_name[:device_group]

where server_name is the name of the encryption key server and device_group is the name of the device group associated with IBM Security Key Lifecycle Manager.

remove

Syntax:

To remove an hpcs server entry from the HpcsSvr ODM database, run the following command:

keysvrmgr remove -t hpcs [-h] -a svr_name=value

You must specify the name of the hpcs server that you want to remove from the ODM database.

To remove a keyserv server entry from the KeySvr ODM database, use the following code:

keysvrmgr remove -t keyserv [-h] -a svr_id=value

You must specify the ID of the keyserv server that you want to remove from the ODM database.

Starting from AIX 7.3, Technology Level 1, the following syntax is deprecated:

keysvrmgr remove [-h] server_id

You must specify the ID of the key server entry that you want to remove from the ODM database.

show

Syntax:

To display information about the hpcs server entry that is specified by the value of svr_name attribute in the HpcsSvr ODM database, use the following code:

keysvrmgr show -t hpcs [-h] [ -a svr_name=value ]

To display information about the keyserv server entry that is specified by the value of svr_id attribute in the KeySvr ODM database, use the following code:

keysvrmgr show -t keyserv [-h] [ -a svr_id=value ]

Starting from AIX 7.3, Technology Level 1, the following syntax is deprecated:

keysvrmgr show [-h] server_id

verify

Syntax:

To verify information about the hpcs server entry in the HpcsSvr ODM database, use the following command. The hpcs server name can be specified as a value of the svr_name attribute.

keysvrmgr verify -t hpcs [-h] -a svr_name=value

The verification process involves communicating with the hpcs server by using the attribute values that are added in the HpcsSvr ODM record.

rekey

Syntax:

To create an API key for an hpcs server entry in the HpcsSvr ODM, use the following command. This new API key replace the existing key.

keysvrmgr rekey -t hpcs [-h] server_name=value

The server_name attribute is used to identify the HpcsSvr ODM record. The rekey action parameter uses the existing attributes that are available in the ODM record to communicate with the hpcs server to create an API key. The existing API key in the ODM is replaced by the newly created API key if the API key is created successfully. The original API key is not deleted from the hpcs server.

Examples

1. To display information about the existing key server entries in the ODM database, run the following command:

   # keysvrmgr show -t keyserv  
   List of key servers: 
   ID                          PWD     IP:PORT
   sklm1                       Y       10.11.12.13:5696
   sklm_server2                N       210.211.212.213:569

2. To display information about the existing ODM entries for the hpcs server type that includes both HPCS and Key Protect instances, run the following command:

   # keysvrmgr show -t hpcs
   List of key servers: 
   SVR_NAME        REGION                                                          INST_ID
   kp-aix          https://us-east.kms.cloud.ibm.com/crypto_v2                     ad87c05a-79ff-4f51-a1ee-3cff2db5808b
   hpcs-aix        https://us-south.broker.hs-crypto.cloud.ibm.com/crypto_v2       f1a98698-a44f-4563-9149-d44494f5cb18

3. To add a new ODM entry for the hpcs server, run the following command:

   # keysvrmgr add -t hpcs \
    -a inst_id="f1a98698-a44f-4563-9149-d44494f5cb18" \
    -a api_key="<your IBM Cloud API Key>" \
    -a svr_region="https://us-south.broker.hs-crypto.cloud.ibm.com/crypto_v2" <name>

   The entry for the name variable is used as a value for the svr_name parameter of the keysvrmgr show command. The newly formed ODM entry is referred to by the name variable for all other operations.

4. To remove an existing ODM entry for the hpcs server, run the following command:

   # keysvrmgr remove -t hpcs hpcs-aix
   HPCS server hpcs-aix successfully removed

5. To remove an existing Key Protect ODM entry, run the following command:

   # keysvrmgr remove -t hpcs kp-aix
   HPCS server kp-aix successfully removed

6. To verify an existing ODM entry for the hpcs server, run the following command:

   # keysvrmgr verify -t hpcs hpcs-aix
   Start verifying the following ODM record:
   Server name: hpcs-aix
   Server region: https://us-south.broker.hs-crypto.cloud.ibm.com/crypto_v2
   Instance id: f1a98698-a44f-4563-9149-d44494f5cb18
   ODM record hpcs-aix passed verification

   If the verification process fails, an error message similar to the following is displayed:

   # keysvrmgr verify -t hpcs hpcs-aix
   Start verifying the following ODM record:
   Server name: hpcs-aix
   Server region: https://us-south.broker.hs-crypto.cloud.ibm.com/crypto_v2
   Instance id: f1a98698-a44f-4563-9149-d44494f5cb18
   3020-0560 curl_easy_perform() failed: Empty reply from server
   ODM record hpcs-aix failed verification

7. To regenerate an API key for an ODM entry, run the following command:

   # keysvrmgr rekey -t hpcs hpcs-aix
   Start rekey the following ODM record:
   Server name: hpcs-aix
   Server region: https://us-south.broker.hs-crypto.cloud.ibm.com/crypto_v2
   Instance id: f1a98698-a44f-4563-9149-d44494f5cb18
   Update succeeded for ODM record hpcs-aix:
           Old API_key: <old API key>
           New API_key: <new API key>
   Rekey succeeded for ODM record hpcs-aix

8. To modify any attribute of an existing ODM entry, run the keysvrmgr modify command with all the attributes you wish to change:

   # keysvrmgr modify -t hpcs \
    -a api_key=<new API key> \
    -a svr_region=<new region URL> hpcs-aix
   HPCS server hpcs-aix successfully modified

9. To verify the changes in the ODM entry, run the following command:

   keysvrmgr verify -t hpcs hpcs-aix

Files

/usr/sbin/keysvrmgr

Contains the keysvrmgr command.