Zeroize Crypto Domain

The Zeroize Crypto Domain operation clears a domain configured for "control-usage" on a specific crypto adapter for the given partition.

HTTP method and URI

POST /api/partitions/{partition-id}/operations/zeroize-crypto-domain

In this request, the URI variable {partition-id} is the object-id of the Partition object.

Request body contents

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

Field name Type Rqd/Opt Description
crypto-adapter-uri String/ URI Required The canonical URI path of the crypto adapter containing the domain to be zeroized.
domain-index Integer Required The index of the domain to be zeroized.

Description

This operation clears the cryptographic keys and non-compliance mode settings within the given domain (which must have an access-mode of "control-usage") of the given crypto adapter.

If the API user does not have action/task permission to the Zeroize Crypto Domain (API only) task, a 403 (Forbidden) status code is returned. A 404 (Not found) status code is returned if the object-id {partition-id} does not identify a partition object for which the API user has object-access permission or if the crypto-adapter-uri field does not identify a crypto adapter object for which the API user has object-access permission.

A 409 (Conflict) status code is returned if the status of the CPC, partition, or adapter is not valid to perform the operation.

Both the adapter identified by crypto-adapter-uri and the domain identified by domain-index must be part of the crypto configuration of the partition. The identified domain must also be configured for access-mode "control-usage". If any of these preconditions is not met, a 409 (Conflict) status code is returned.

If the request body fails to validate, a 400 (Bad Request) status code is returned.

When this operation completes with HTTP status code 204 (No Content), the domain was successfully zeroized on the adapter.

When this operation completes with HTTP status code 409 (Conflict) with reason code 124, the clearing of keys and settings was initiated, but it might or might not have completed. If the adapter status is not "active" after receiving HTTP status code 409 (Conflict) with reason code 124, it is recommended to repeat this operation as soon as the status of the adapter becomes "active" again.

Although this operation is accepted for all kinds of crypto adapters, it has no effect for adapters of type "accelerator".

Authorization requirements

This operation has the following authorization requirements:
  • Object-access permission to the partition designated by {partition-id}.
  • Object-access permission to all crypto adapters specified in the request body.
  • Action/task permission to the Zeroize Crypto Domain (API only) task.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned and no response body is provided.

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.

Table 1. Zeroize Crypto Domain: HTTP status and reason codes
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.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The partition with object-id {partition-id} does not exist, or the API user does not have object-access permission for it.
2 The crypto adapter specified by crypto-adapter-uri in the request body does not exist or the API user does not have object-access permission for it.
4 The partition does not support this operation.
409 (Conflict) 1 The status of the partition is not valid to perform the operation (must be one of "active", "degraded", "paused", or "terminated").
6 The state of the CPC hosting the partition is not valid to perform the operation (must be in one of the following states: "active", "service-required", "degraded", or "exceptions").
10 The operation cannot be performed because the SE is in the process of being shut down.
120 The status of the adapter designated in the request body is not valid to perform the operation (must be "active").
121 The adapter designated in the request body is not part of the crypto configuration of the partition.
122 The domain index designated in the request body is not part of the crypto configuration of the partition.
123 The domain index designated in the request body is configured as "control" (must be "control-usage").
124 The clearing of keys and settings was initiated, but it might or might not have completed.
500 (Server Error) 273 An unexpected error occurred during the operation.
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. Zeroize Crypto Domain: Request
POST /api/partitions/5c6ce80a-e402-11e8-8c9d-fa163ebe78b2/operations/zeroize-
   crypto-domain HTTP/1.1
x-api-session: 27daquoih13tq89tkzpivbq28hmghxegydzoa8pxwata3jrpgh
content-type: application/json
content-length: 95
{
   "crypto-adapter-uri":"/api/adapters/196a234a-e3ff-11e8-a662-fa163ebe78b2",
   "domain-index":0
}
Figure 2. Zeroize Crypto Domain: Response
204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 12 Nov 2018 11:47:29 GMT

<No response body>