Encryption/clients: PUT

Replaces a valid or an expired client certificate in a specified key client.

Availability

Available on all IBM Storage Scale editions.

Description

The PUT scalemgmt/v2/encryption/clients request replaces a client certificate, which has either expired or is still valid, for a specified key client. For more information about the fields in the data structures that are returned, see the mmkeyserv command.

Request URL

https://<IP address or host name of API server>:<port>scalemgmt/v2/encryption/clients
where
clients
Specifies the target of the PUT request.

Request headers

Accept: application/json

Request data

The following list of attributes is available in the request data: 

{
  "clientName": "Client name",
  "newClientname": "New client name",
  "passwordFile": "Password file name",
  "daysToExpiration": Days till expiry,
  "keyStorePwdFile": "Keystore password file name"
  "clientCertFile": "Client certification file",
  "clientPrivateKeyFile": "Client private key file",
  "caCertFilePrefix": "Path and file name of certifcate prefix",
  "caCertChainFile": "CA certificates file 
  "forceFlag":  true | false
  }
The details of the parameters are given in the following list.
"clientName": "Client name"
Specifies the name of the key client where you want to update the client certificate.
"newClientName": "New client name"
Specifies the new name of the key client. The name must be within 1 - 16 characters in length. It must be unique within the IBM Storage Scale cluster. If you do not provide a value for this parameter, then the certificate is not replaced with the new name.
"serverName": "Server name"
Specifies the name of the RKM server to which the key client belongs.
"passwordFile": "Password file"
The password file that comprises a password for accessing the RKM server.
"daysToExpiration": "Number of days till expiration"
The number of days until the new client certificate expires. The valid range is 1 - 18262. The default value is 1095.
"keyStorePwdFile" : "Keystore password file"
The password file that contains a client keystore password.
"clientCertFile": "Client certificate file"
The file that contains a client certificate from a certificate authority (CA).
"clientPrivateKeyFile" : "Client private key file"
The file that contains a client private key that matches the client certificate.
"caCertFilePrefix" : "Path and file name of Certificate prefix"
The path and file name prefix of non-self-signed certificate files in a certificate chain.
"caCertChainFile": "CA Certificate file"
The file that contains the certificates of the CA that signed the client certificate.
"forceflag": "true | false"
Specifies whether a self-signed client certificate is generated for the key client.

Response data

{
  "jobs": [
    {
      "jobId": ID of the job,
      "status": "Job status",
      "submitted": "Date and time when job was submitted",
      "completed": "Date and time when job was completed",
      "runtime": Time when Job ran,
      "request": {
        "type": "Request Type",
        "url": "Resource URL"
      },
      "result": {},
      "pids": []
    }
  ],
  "status": {
    "code": return status code,
    "message": "Return message."
  }
}

For more information about the fields in the following data structures, see the links at the end of the topic.

"jobs":
An array of elements that describe jobs. Each element describes one job.
"jobId": "ID",
The unique ID of the job.
"submitted": "Time"
The time at which the job was submitted.
"completed": "Time"
The time at which the job was completed.
"runtime": "Time"
The duration for which the job ran.
"status": "RUNNING | COMPLETED | FAILED"
Status of the job.
"result"
Array of commands that are run in this job.
"pids": list
A list of process IDs for this job.
"request"
"type": "{GET | POST | PUT | DELETE}"
HTTP request type.
"url": "URL"
The URL through which the job is submitted.
"status":
Return status.
"message": "ReturnMessage",
The return message.
"code": ReturnCode
The return code.

Examples

The following example replaces the client certificate.

Request data: 
curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Basic YWRtaW46VHJhY2VAMjAyMQ==' -d '{ \ 
    "clientName": "myclient1", \ 
   "newClientname": "myclient1", \ 
   "passwordFile": "/tmp/password", \ 
   "daysToExpiration": 1095, \ 
   "keyStorePwdFile": "/tmp/password", \ 
   "clientCertFile": "/tmp/cert", \ 
   "clientPrivateKeyFile": "/tmp/CA/certfiles.1.cert", \ 
   "caCertFilePrefix": "/tmp/cert", \ 
   "caCertChainFile": "/tmp/CA/certfiles.0.cert", \ 
   "forceFlag": false \     
   }' 'https://198.51.100.1:443/scalemgmt/v2/encryption/clients'
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": 3000000000012,
            "status": "COMPLETED",
            "submitted": "2021-06-21 05:30:06,455",
            "completed": "2021-06-21 05:30:23,457",
            "runtime": 17002,
            "request": {
                "data": {
                    "clientName": "myclient2",
                    "daysToExpiration": 1095,
                    "keyStorePwdFile": "/home/passfile1",
                    "newClientname": "myclient1",
                    "passwordFile": "/home/passfile1" 
                    "clientCertFile": "/tmp/cert", \ 
                    "clientPrivateKeyFile": "/tmp/CA/certfiles.1.cert", \ 
                    "caCertFilePrefix": "/tmp/cert", \ 
                    "caCertChainFile": "/tmp/CA/certfiles.0.cert", \ 
                    "forceFlag": false
                },
                "type": "PUT",
                "url": "/scalemgmt/v2/encryption/clients"
            },
            "result": {
                "progress": [],
                "commands": [
                    "mmkeyserv client update 'myclient2' --client 'myclient1' --days 1095 --keystore-pwd '/home/passfile1' --server-pwd '/home/passfile1' "
                ],
                "stdout": [
                    "mmkeyserv: [I] Client currently does not have access to the key.  Continue the registration process ...",
                    "mmkeyserv: Successfully accepted client certificate",
                    "mmkeyserv: Propagating the cluster configuration data to all",
                    "  affected nodes.  This is an asynchronous process.",
                    "mmkeyserv: Deleting the following KMIP certificate with label: 9842179411678971055_devG1_1624267300",
                    "info: mmkeyserv: [I] Client currently does not have access to the key.  Continue the registration process ...\nmmkeyserv: Successfully accepted client certificate\nmmkeyserv: Deleting the following KMIP certificate with label: 9842179411678971055_devG1_1624267300\n"
                ],
                "stderr": [],
                "exitCode": 0
            },
            "pids": []
        }
    ],
    "status": {
        "code": 200,
        "message": "The request finished successfully."
    }
}