Get Certificate Properties

The Get Certificate Properties operation retrieves the properties of a single Certificate object. This operation is supported using the BCPii interface. [Added by feature secure-boot-with-certificates]

HTTP method and URI

GET /api/certificates/{certificate-id}

In this request, the URI variable {certificate-id} is the value of the object-id of the Certificate object.

Query parameters

Name Type Rqd/Opt Description
properties List of String Enum Optional Filter string to limit returned properties to those that are identified here. This is a list of comma-separated strings where each string is a property name defined in the Certificate object's data model.

Response body contents

On successful completion, the response body is a JSON object with the following fields:

Field Name Type Description
object-uri String/ URI The canonical URI path of the Certificate object, of the form /api/certificates/{certificate-id} where {certificate-id} is the value of the object-id property of the Certificate object.
parent String/ URI The parent of a certificate, whose type is "secure boot", is conceptually the CPC that it is imported to, and so the parent value is the canonical URI path for the CPC.
parent-name String (1 - 64) The name of the object identified by the parent property.
name String (1 - 64) The display name specified for the certificate. The character requirements on this property are the same as those of the name property described in the Base managed object properties schema. Names must be unique among all Certificates with the same parent and type values.
description String (0 - 1024) The description of the certificate.
class String (11) The class of a Certificate object is "certificate".
type String Enum The type of certificate with regards to its intended usage, associated task, or associated action.

Valid values:

  • "secure-boot" - The certificate is used for the Secure Boot Certificate Management task.
sha-256-fingerprint String The SHA-256 fingerprint of the certificate.
assigned Boolean For certificates of type secure-boot, identifies if the certificate is assigned to one or more logical partitions, partitions, or image activation profiles.

Description

If the properties query parameter is specified, the response body contains only the requested properties. The presence and value of each requested property is the same as it is when the properties query parameter is not specified. That is, it may be omitted or contain a special value, such as null, -1, or an empty string, if a prerequisite condition is not met. If the properties parameter is omitted, no such filtering is performed.

On successful execution, HTTP status code 200 (OK) is returned and the response body contains all of the current properties as defined by the data model for the Certificate object.

A 404 (Not Found) status code is returned if the request URI does not designate an existing Certificate object, or if the API user does not have object-access permission to the object. A 400 (Bad Request) status code is returned if an unrecognized, unsupported, malformed or invalid query parameter was specified.

Authorization requirements

This operation has the following authorization requirements:

For the web services interface:
  • Object-access permission to the Certificate object whose object-id is {certificate-id}.
For the BCPii interface:
  • The source partition must have receive BCPii security controls permissions for the CPC object designated by target-name property that accompanies the request.

HTTP status and reason codes

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in Response body contents

The following HTTP status codes are returned for the indicated errors, and the response body is a standard error response body providing the reason code indicated and associated error message.

HTTP error status code Reason code Description
400 (Bad Request) Various Errors were detected during common request validation. See Common request validation reason codes for a list of the possible reason codes.
1 The request included an unrecognized or unsupported query parameter.
14 Query parameters on the request are malformed or specify a value that is invalid for this operation.
403 (Forbidden) 0 The request used the BCPii interface and the source CPC object does not have receive BCPii security controls permission.
404 (Not Found) 1 The object ID in the URI ({certificate-id}) does not designate an existing Certificate object, or the API user does not have object-access permission to the object.

Additional standard status and reason codes can be returned, as described in Invoking API operations.

Example HTTP interaction

Figure 1. Get Certificate Properties: Request
GET /api/certificates/471a0dfe-4031-11ed-a545-fa163e6f7e7e HTTP/1.1
x-api-session: d4fwcg8f4jdwfkyzjfuhh5igbmk0efz1glxrszia7b0a0r3j5
Figure 2. Get Certificate Properties: Response
200
Server: Hardware management console API web server / 2.0
Cache-control: no-cache
Date: Mon, 10 Oct 2022 19:23:35 GMT
Content-Type: application/json
Content-Length: 482
{
   "assigned":true,
   "class":"certificate",
   "description":"Certificate for secure boot with new z/OS",
   "name":"zOS validated boot certificate",
   "object-id":"471a0dfe-4031-11ed-a545-fa163e6f7e7e",
   "object-uri":"/api/certificates/471a0dfe-4031-11ed-a545-fa163e6f7e7e",
   "parent":"/api/cpcs/bab1c46f-17ca-3e5b-b93b-2669b2f344a4",
   "parent-name":"HJVS2EKN",
   "sha-256-fingerprint":"0C ED 78 C4 80 2B 2B 9A 3D 19 0F 75 8A 79 F0 05 87 EF 22 94 69 D6 80 
      A0 C6 3B 2F EE D3 12 0D 83",
   "type":"secure-boot"
}