Import CPC Certificate

The Import CPC Certificate operation imports a certificate based on its type to a CPC. This operation is supported using the BCPii interface. [Added by feature secure-boot-with-certificates]

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/import-certificate

In this request, the URI variable {cpc-id} is the object ID of the CPC object.

Request body contents

The request body is expected to contain a JSON object with the following fields:

Field name Type Rqd/Opt Description
name String Required The value to be set as the certificate's name property.
description String Optional The value to be set as the certificate's description property.
certificate String Required The Base64-encoded string form of the CPC certificate to import.
type String Enum Required The value to be set as the certificate's type property.

Response body contents

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

Field name Type Description
certificate-uri String/ URI The URI of the newly created Certificate object.

Description

This operation imports a certificate based on its type to a CPC. An Inventory Change notification is emitted asynchronously to this operation.

If the Certificate being imported has the same name as an existing certificate or there was a problem with the certificate or the file being imported contained multiple certificates, a 400 (Bad Request) status code is returned. A 404 (Not Found) status code is returned if the request URI does not designate an existing CPC, or if the API user does not have object-access permission to the object. If the API user does not have action/task permission to Import Secure Boot Certificates task, 403 (Forbidden) status code is returned. If attempting to import a certificate to an unmanaged CPC, or if importing the Certificate would exceed the Certificate limit of 100 per CPC, a 409 (Conflict) status code is returned. A 503 (Service Unavailable) status code is returned if the Console is not communicating with the CPC.

Authorization requirements

This operation has the following authorization requirements:
  • For the web services interface:
    • Object-access permission to the CPC object designated by {cpc-id}
    • Action/task permission for the Import Secure Boot Certificates task.
  • For the BCPii interface the source partition must have receive BCPii security controls permissions for the CPC object.

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.
8 The value of a field does not provide a unique value for the corresponding data model property as required.
368 There was a problem with the certificate. This could be due to bad formatting, not being able to decode the certificate, etc.
369 The operation cannot be completed because the certificate string being imported contains multiple certificates. Only one certificate can be imported at a time.
381 The operation cannot be completed because the certificate is expired.
403 (Forbidden) 0 The request used the BCPii interface and the source CPC does not have receive BCPii security controls permission.
1 The user under which the API request was authenticated does not have the required authority to perform the requested action.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object, or the API user does not have object-access permission to the object.
4 The object designated by the request URI does not support the requested operation.
409 (Conflict) 329 The operation cannot be performed because the CPC identified by the request URI is an unmanaged CPC, which is not supported by this operation.
371 The operation could not be performed because importing this certificate would exceed the limit of 100 certificates per CPC.
503 (Service Unavailable) 1 The request could not be processed because the HMC is not currently communicating with an SE needed to perform the requested operation.

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

Example HTTP interaction

Figure 1. Import CPC Certificate: Request
POST /api/cpcs/bab1c46f-17ca-3e5b-b93b-2669b2f344a4/operations/import-certificate HTTP/1.1
x-api-session: 67fbo5w4o1wwpkv2juhbrpux5k0rc5cbmt9594r6fxkl0v5xtv
Content-Type: application/json
Content-Length: 1385
{
   "certificate":"MIIDtDCCApygAwIBAgIUZItvCP3Qvs4XyplEsXl/g344spAwDQYJKoZIhvcNAQELBQAwWjEpMCcGA1UEAwwgTGludXggU2VjdXJlIEJvb3QgKGJyaW5nLXVwIGtleSkxLTArBgkqhkiG9w0BCQEWHnBldGVyLm9iZXJwYXJsZWl0ZXJAZGUuaWJtLmNvbTAeFw0yMjAyMTExNzQ3NDBaFw0zMTExMTExNzQ3NDBaMFoxKTAnBgNVBAMMIExpbnV4IFNlY3VyZSBCb290IChicmluZy11cCBrZXkpMS0wKwYJKoZIhvcNAQkBFh5wZXRlci5vYmVycGFybGVpdGVyQGRlLmlibS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCs3IVBAHIBQHCm4KL/8tIyMpOMWTQi9lsSz4J/OXGfuW+IwKZnUpxCoGM+3xi6qXvTf5jgZxvLCSxM4Qut303l/4nG7pyNBQ8IFQBwmeibV04HkVFlHVZVPawanKJlSfIZyq7a9VOqHtWD1go81UchVOnjzSrj4fMHtB0AuidjUAQYY5HXSVEjeEFgv+af1urg1VvhWNGnYPkAzqFQhPgki/EA1ydlQLfTAWgDlnvfgLaDVRnf83vo7PpRpY5gsRUu/eTF5CkrKO2+QUc5OsgaHQXJ7Hv51ad10JEYyHELSuoCVQxD0dfwf8XMqbs4DO1lvDY6HGa6xf8+cmT0n8g3AgMBAAGjcjBwMB0GA1UdDgQWBBQURrE+E08OW/buPUlnIQvpPi3aaDAfBgNVHSMEGDAWgBQURrE+E08OW/buPUlnIQvpPi3aaDAMBgNVHRMBAf8EAjAAMAsGA1UdDwQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDAzANBgkqhkiG9w0BAQsFAAOCAQEAW+XXxWd7dQU68YapkzNY9XiGOCJdHBZ9yrNBjAqi5KfG4ASjyZE67fmdqo5fzf3SFX0kIMx/9FUz3CsQbDBK7eMZO3ZagelLTR3BkiiCi9tzTLEVrOFkFB3m9Vz7YbPLssjoGMLo7VagMIZSRUDb+XDA8NJemaYLocPShNxBwCtEdU6yn5Rc3GxkVHKaljubLV93QwvqF+ObMv3QAmKB/mci9z+ZObZWN8MgCLXJebRQAPlmvaxS+y0vXNd7getApyfXWWyd63PalU/Ie8aGXNsdJj0MAQu8Ku1Fd8BRDdyqQyYxKSTJCYV108aw29DhRSBOGLAS2tOK/BJ5S2r70w==",
   "description":"Certificate for Linux",
   "name":"Linux certificate",
   "type":"secure-boot"
}
Figure 2. Import CPC Certificate: Response
200
Server: Hardware management console API web server / 2.0
Cache-control: no-cache
Date: Mon, 10 Oct 2022 19:50:55 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 76
{
   "certificate-uri":"/api/certificates/dab30826-48d4-11ed-87c1-fa163e6f7e7e"
}