Certificate Generate Request REST Service

Use Certificate Generate Request REST Service to create a PKCS #10 certificate request file. This service creates certificate request file, such as SKLM_HOME/080419154137–sslcert001.csr. You must manually send the request to a certificate authority.

When the certificate authority returns a certificate in response to this request, copy the certificate to a file. Use Certificate Import REST Service to load the response file. You must specify the same alias name that was used with Certificate Generate Request REST Service to generate the request.

After you generate the certificate request, the certificate activation date and creation date are identical. This certificate is available to the key server and drive.

Operation: POST
URL: https://<host>:<port>/SKLM/rest/v1/certificates

By default, Guardium® Key Lifecycle Manager server listens to non-secure port 9080 (HTTP) and secure port 9443 (HTTPS) for communication. During IBM® Security Guardium Key Lifecycle Manager installation, you can modify these default ports.

Note: The non-secure port 9080 is not applicable when IBM Security Guardium Key Lifecycle Manager is deployed in a containerized environment.

Request

Request Parameters

Parameter	Description
host	Specify the IP address or host name of the IBM Security Guardium Key Lifecycle Manager server.
port	Specify the port number on which the IBM Security Guardium Key Lifecycle Manager server listens for requests.

Request Headers

Header name	Value
Content-Type	`application/json`
Accept	`application/json`
Authorization	`SKLMAuth userAuthId=<authIdValue>`
Accept-Language	Any valid locale that is supported by IBM Security Guardium Key Lifecycle Manager. For example: `en` or `de`

Request body

JSON object with the following specification:

Property name	Description
type	Required. Specify a value such as `certreq` to create a certificate generate request.
algorithm	Required. Specify the algorithm with the following values: `RSA` `ECDSA`
alias	Required. Specify a unique name for the certificate. Retain a record of the alias value of the certificate request, for use when you import the returned certificate.
cn	Required. Specify the common name.
country	Specify a country as a two-letter country code.
fileName	Required. Specify the name of the certificate request file, which is created on the IBM Security Guardium Key Lifecycle Manager server, relative to the SKLM_HOME directory. SKLM_HOME is the base directory that contains the IBM Security Guardium Key Lifecycle Manager code and configuration.
locality	Specify a locality, such as `city`.
o	Specify the organization name. For example: `o=myCompanyName`
ou	Specify the organizational unit name. For example: `ou=marketing`
state	Specify the full name of a state or province.
usage	Specify the target application usage, such as `SSLSERVER`, with the following values: 3592 Specifies the `3592` device group. DS8000® Specifies the `DS8000` device group. PEER_TO_PEER Specifies the PEER_TO_PEER device group. GENERIC Specifies a device family that uses the Key Management Interoperability Protocol to interact with IBM Security Guardium Key Lifecycle Manager. The `GENERIC` device group enables management of KMIP objects. Do not use the REST Service interface to add a device to the `GENERIC` device group or to change a `GENERIC` device group attribute. SSLCLIENT Specifies the client-side certificate that is used in secure communication by using Transport Layer Security protocol to authenticate the client device. SSLSERVER Specifies the server-side certificate that is used in secure communication by using Transport Layer Security protocol. userdevicegroup Specifies a user-defined group that is based on a supported device family.
validity	Required. Specify a time interval in days during which the certificate is valid. The interval can range between 1 day and 9000 days.

Response

Response Headers

Header name	Value and description
Status Code	200 OK The request was successful. The response body contains the requested representation. 400® Bad Request The authentication information was not provided in the correct format. 401 Unauthorized The authentication credentials were missing or incorrect. 404 Not Found Error The processing of the request fails. 500 Internal Server Error The processing of the request fails because of an unexpected condition on the server.
Content-Type	`application/json`
Content-Language	Locale for the response message.

Success response body

JSON object with the following specification:

JSON property name	Description
code	Returns the code that is specified by the status property.
status	Returns the status to indicate whether the creation of certificate generate request was successful.

Error Response Body

JSON object with the following specification.

JSON property name	Description
code	Returns the application error code.
message	Returns a message that describes the error.

Examples

Service request to create certificate generation request

POST https://localhost:<port>/SKLM/rest/v1/certificates
Content-Type: application/json
Accept: application/json
Authorization: SKLMAuth userAuthId=139aeh34567m
{"type":"certreq","alias":"sklmCert","cn":"sklm","ou":"sales","o":
"myCompanyName","usage":"3592","country":"US","validity":"999","fileName":
"myCertRequest1.crt","algorithm":"ECDSA"}

Success response

 Status Code: 200 OK
{"code":"0","status":"Succeeded"}

Error response

Status Code: 400 Bad Request
{"code":"CTGKM0525E","message":"CTGKM0525E Parameter value(s) are not 
valid., validity=9999"}

Table 1. Topic change log
Date	Change description
03 Sept 2021	Removed `GPFS` from the values list of the usage parameter.
10 Feb 2021	Corrected instances of 'TLSServer' to 'SSLServer', and 'TLSClient' to 'SSLClient'. Refreshed only the English language content.
08 Dec 2020	Initial version.