Encryption/keys: GET

Displays information about the encryption keys in a tenant.

Availability

Available on all IBM Storage Scale editions.

Description

The GET scalemgmt/v2/encryption/keys request displays information about the encryption keys in a tenant. For more information about the fields in the data structures that are returned, see the mmkeyserv command in the IBM Storage Scale documentation.

Request URL

https://IP address of API server:<port>/scalemgmt/v2/encryption/keys
where
keys
Specifies the resource of this GET call.

Request headers

Content-Type: application/json
Accept: application/json

Parameters

Table 1. List of parameters
Parameter name Description and applicable keywords Required/Optional
body Body of the request that contains the parameters that need to be passed on to the IBM Storage Scale Erasure Code Edition system to complete the requested operation. Required

Request data

The following list of attributes is available in the request data:
{
  "serverName": "string",
  "tenantName": "string",
  "passwordFile": "string"
}
The details of the parameters are given in the following list:
"serverName": Server name
Specifies the host name or IP address of the RKM server to which the tenant belongs.
"tenantName": "Tenant name
Specifies the name of the tenant that comprises the encryption keys.
"passwordFile": "Password file name"
Specifies the password file that contains a password for accessing the RKM server. If you do not provide a password, then you are prompted for a password when the request is sent. A password must be 1 - 20 characters in length. For more information, see the mmkeyserv command in the IBM Storage Scale documentation.

Response data

{ 
    "jobs": [
        {
            "jobId": Job ID,
            "status": "RUNNING | COMPLETED | FAILED",
            "submitted": "Time and date",
            "completed": "Time and date",
            "runtime": Time,
            "request": {
                "type": "GET | POST | PUT | DELETE",
                "url": "Request URL"
            },
            "result": {
                "progress": [],
                "commands": [
                    "Command name "
                ],
                "stdout": [
                ],
                "stderr": [],
                "exitCode": Code            },
            "pids": []
        }
    ],
    "status": {
        "code": Status code,
        "message": "Status message"
    }
}
    }
For more information about the fields in the following data structures, see the links at the end of the topic.
"jobId": "Job ID"
The unique ID of the job.
"status": "RUNNING | COMPLETED | FAILED"
The status of the job.
"submitted": "Time and date"
The time and date when the job was submitted.
"completed": "Time and date"
The time at which the job was completed.
"runtime": "Time and date"
The time that the job took to run.
"request"
"type": "GET | POST | PUT | DELETE"
The request type.
"URL": "Request URL"
The URL through which the job is submitted.
"result"
"progress": Job progress
Progress information for the request.
"commands": "Command name
Array of commands that are run in this job.
"stdout": "message
Request Information.
"info":"Key details"
The encryption key details.
"exitCode":"Exit code"
Exit code of command. Zero indicates success and any other value denotes failure.
"stderr":"Error"
CLI messages from stderr.
"pids": "Process IDs
The process IDs for the job.
"status":
Return status.
"message": "ReturnMessage"
The return message.
"code": ReturnCode
The return code.

Examples

The following example gets information on the encryption key.

Request data:
curl -k -u admin:admin001 -X GET --header 'accept:application/json'  -d '{ \ 
   "serverName": "lodestar1.fyre.ibm.com",
  "tenantName": "devG1",
  "passwordFile": "/var/lib/mmfs/gui/passfile" \ 
 }' 'https://198.51.100.1:443/scalemgmt/v2/encryption/keys'
Response data:
Note: In the JSON data that is returned, the return code indicates whether the command is successful. The response code 200 indicates that the command successfully retrieved the information. Error code 400 represents an invalid request and 500 represents internal server error. 
{
    "jobs": [
        {
            "jobId": 1000000000001,
            "status": "COMPLETED",
            "submitted": "2021-06-18 16:50:17,335",
            "completed": "2021-06-18 16:50:19,999",
            "runtime": 2664,
            "request": {
                "type": "GET",
                "url": "/scalemgmt/v2/encryption/keys"
            },
            "result": {
                "progress": [],
                "commands": [
                    "mmkeyserv key show --server 'lodestar1.fyre.ibm.com' --server-pwd '/root/passfile1' --tenant 'devG1' "
                ],
                "stdout": [
                    "KEY-fa079f5-9e276a98-4d51-4df0-aeff-f296a3cbd7d2",
                    "info: KEY-fa079f5-9e276a98-4d51-4df0-aeff-f296a3cbd7d2\n"
                ],
                "stderr": [],
                "exitCode": 0
            },
            "pids": []
        }
    ],
    "status": {
        "code": 200,
        "message": "The request finished successfully."
    }
}

Related information

mmkeyserv command in the IBM Storage Scale documentation.