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.
- -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
keyserv
server, you can use the
following ODM attributes:- svr_name
- Specifies the name of the
keyserv
server entry in the ODM record. The svr_name attribute is used to generate the value of the svr_id attribute. - svr_id
- Specifies the ID of the
keyserv
server entry in the ODM record in the following format:svr_name[:dev_grp]
The svr_name attribute is the name of the
keyserv
server entry and dev_grp attribute is the name of the device group that is associated with the IBM Security Key Lifecycle Manager.
- dev_grp
- Specifies the name of the device group that is associated with the IBM Security Key Lifecycle Manager.
- svr_ip
-
Specifies the IP address of the encryption key server in the following format:
a.b.c.d
The value of a, b, c, and d must be in the range 0 - 255.
- svr_port
- Specifies the port value of the encryption key server. You can specify a port value in the range 0 - 65535. The default port value of the encryption key server is 5696.
- svr_cert
- Specifies the absolute path to the X.509 digital server certificate that is associated with the encryption key server.
- cli_cert
- Specifies the absolute path of the Public Key Cryptography Standards #12 (PKCS #12) client certificate that is associated with the AIX operating system.
- cert_pwd
- Specifies the type of the password protection for the client certificate. You can specify the
following values for this attribute:
- y or Y
- Specifies that the AIX operating system prompts you for the password of the client certificate during the command run time.
- n or N
- Specifies that the client certificate is not protected by a password. The cert_pwd attribute value is n or N by default.
- p or P
- Specifies that the password of the client certificate is stored in platform keystore (PKS).
Key Protect and hpcs
server ODM attributes
hpcs
server, you can use the following ODM attributes:- svr_name
- Specifies the name of the Key Protect or
hpcs
server entry in the ODM records. - inst_id
- Specifies the instance ID that is used to communicate with the Key Protect or
hpcs
server. - api_key
- Specifies the API key that is used to communicate with the Key Protect or
hpcs
server. - svr_region
-
Specifies the URL that is queried to obtain the actual API endpoint. The Key Protect and
hpcs
server has the following URL format:https://[region endpoint]/crypto_v2
The hostname in the URL specified by the svr_region attribute varies for Key Protect and
hpcs
server. The hostname must be as specified in the product documentation for Key Protect andhpcs
server.For more information about the endpoint specific to your instance region for Key Protect, see the Service endpoints section in the Regions and endpoints page.
For more information about the region-endpoint mapping in the
hpcs
server, see the Endpoint URLs section in the IBM Cloud Hyper Protect Crypto Services KMS API page.
hpcs
server ODM entry:iam-identity.serviceid-apikey.login
iam-identity.user-apikey.login
iam-identity.apikey.get
iam-identity.apikey.create
iam-identity.apikey.delete
hs-crypto.secrets.read (for hpcs server)
hs-crypto.secrets.create (for hpcs server)
hs-crypto.secrets.list (for hpcs server)
hs-crypto.secrets.delete (for hpcs server)
kms.secrets.read (for Key Protect server)
kms.secrets.create (for Key Protect server)
kms.secrets.delete (for Key Protect server)
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 thekeyserv
server entry to the KeySvr ODM database, run the following command:
The key server ID is created in thekeysvrmgr 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] ]
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:
where each value of a, b, c, and d are in the range 0 - 255.a.b.c.d
- -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:
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.server_name[:device_group]
- 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:
- remove
-
- Syntax:
-
To remove an
hpcs
server entry from the HpcsSvr ODM database, run the following command:
You must specify the name of thekeysvrmgr remove -t hpcs [-h] -a svr_name=value
hpcs
server that you want to remove from the ODM database.To remove akeyserv
server entry from the KeySvr ODM database, use the following code:
You must specify the ID of thekeysvrmgr remove -t keyserv [-h] -a svr_id=value
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 thekeyserv
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. Thehpcs
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 thehpcs
server.
Examples
-
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
-
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
-
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.
-
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
-
To remove an existing Key Protect ODM entry, run the following command:
# keysvrmgr remove -t hpcs kp-aix HPCS server kp-aix successfully removed
-
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
-
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
-
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
-
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.