Introduction
IBM Cloud Hyper Protect Crypto Services helps you encrypt your data at the safety and security level of System z cryptography in a convenient and cost competitive manner.
Hyper Protect Crypto Services is integrated with the IBM® Key Protect for IBM Cloud REST API, so that you can store, retrieve, and generate encryption keys. For details about using Hyper Protect Crypto Services, see the IBM Cloud docs.
API endpoint
https://<region>.hs-crypto.cloud.ibm.com/
For the Retrieve the connection info API, the endpoint is
https://zcryptobroker.mybluemix.net/crypto_v1/
For other APIs, the endpoint is
https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/
- Always call the Retrieve the connection info API before you proceed with other APIs.
- Replace
<region>with the prefix that represents the geographic area where your service instance resides. For more informaton, see Regions and locations. - Replace
<port>with the port number of the API endpoint.
API endpoint
https://<region>.hs-crypto.cloud.ibm.com/
For the Retrieve the connection info API, the endpoint is
https://zcryptobroker.mybluemix.net/crypto_v1/
For other APIs, the endpoint is
https://<region>.hs-crypto.cloud.ibm.com: <port>/api/v2/keys/
Replace
<region>with the prefix that represents the geographic area where your service instance resides. For more informaton, see Regions and locations.Replace
<port>with the port number of the API endpoint.
API endpoint
https://<region>.hs-crypto.cloud.ibm.com/
For the Retrieve the connection info API, the endpoint is
https://zcryptobroker.mybluemix.net/crypto_v1/
For other APIs, the endpoint is
https://<region>.hs-crypto.cloud.ibm.com: <port>/api/v2/keys/
Replace
<region>with the prefix that represents the geographic area where your service instance resides. For more informaton, see Regions and locations.Replace
<port>with the port number of the API endpoint.
Authentication
To work with the API, authenticate your app or service by including your IBM Cloud IAM access token in API requests.
You can retrieve an access token by first creating an API key, and then exchanging your API key for a IBM Cloud IAM token. For more information, see Accessing the API.
To retrieve your access token:
curl -X POST
https://iam.cloud.ibm.com/identity/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
-d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=<API_KEY>"
Replace <API_KEY> with your service credentials. Then use the full IAM token value, prefixed by the Bearer token type, to authenticate your API requests.
To retrieve your instance ID:
ibmcloud resource service-instance <instance_name> --id
Replace <instance_name> with the unique alias that you assigned to service instance.
To retrieve your access token:
var settings = {
"async": true,
"crossDomain": true,
"url": "https://iam.cloud.ibm.com/identity/token",
"method": "POST",
"headers": {
"Content-Type": "application/x-www-form-urlencoded",
"Accept": "application/json"
},
"data": "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=<API_KEY>"
}
$.ajax(settings).done(function (response) {
console.log(response);
});
Replace <API_KEY> with your service credentials. Then use the full IAM token value, prefixed by the Bearer token type, to authenticate your API requests.
To retrieve your instance ID:
ibmcloud resource service-instance <instance_name> --id
Replace <instance_name> with the unique alias that you assigned to your service instance.
To retrieve your access token:
import requests
url = "https://iam.cloud.ibm.com/identity/token"
headers = {
"Content-Type": "application/x-www-form-urlencoded",
"Accept": "application/json",
}
data = [
("grant_type", "urn:ibm:params:oauth:grant-type:apikey"),
("apikey", "<API_KEY>"),
]
response = requests.request("POST", url, headers=headers, data=data)
Replace <API_KEY> with your service credentials. Then use the full IAM token value, prefixed by the Bearer token type, to authenticate your API requests.
To retrieve your instance ID:
ibmcloud resource service-instance <instance_name> --id
Replace <instance_name> with the unique alias that you assigned to your service instance.
Error handling
This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.
| HTTP Error Code | Description | Recovery |
|---|---|---|
200 |
Success | The request was successful. |
400 |
Bad Request | The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request. |
401 |
Unauthorized | You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions. |
403 |
Forbidden | The supplied authentication is not authorized to access '{namespace}'. |
404 |
Not Found | The requested resource could not be found. |
408 |
Request Timeout | The connection to the server timed out. Wait a few minutes, then try again. |
409 |
Conflict | The entity is already in the requested state. |
500 |
Internal Server Error | offering_name is currently unavailable. Your request could not be processed. Wait a few minutes and try again. |
Metadata
When you create or store keys in Hyper Protect Crypto Services, you can attach key-value data to your resources for easy identification of your keys.
The name, description, and tag parameters are useful for storing information on your resources. For example, you can store corresponding unique identifiers from your app or system on a Hyper Protect Crypto Services key.
To protect your privacy, do not store any personally identifiable information, such as your name or location, as metadata for your keys.
Methods
Retrieve the API endpoint URL
Retrieves the URL for the dedicated API endpoint for key management operations on a Hyper Protect Crypto Services instance.
GET /instances/{id}Custom Headers
Your IBM Cloud access token.
Path Parameters
The IBM Cloud UUID that uniquely identifies the instance.
curl -X GET \ https://zcryptobroker.mybluemix.net/crypto_v1/instances/{id} \ -H 'Authorization: Bearer {access_token}'
var settings = { "url": "https://zcryptobroker.mybluemix.net/crypto_v1/instances/{id}", "method": "GET", "headers": { 'Authorization: Bearer {access_token}' } } $.ajax(settings).done(function (response) { console.log(response); });
import requests url = 'https://zcryptobroker.mybluemix.net/crypto_v1/instances/{id}' headers = { 'Authorization': 'Bearer {access_token}', } response = requests.request('GET', url, headers=headers) print(response.text)
The v4 UUID used to uniquely identify the instance in IBM Cloud.
Specifies the URI (url:port) where the API can be used.
Status Code
The instance connection info was successfully retrieved.
Your access token is invalid or does not have the necessary permissions to access this resource.
The instance could not be found. Verify that the instance ID specified is valid.
IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-IDin the response header and contact IBM Cloud support.
{ "instance_id": "4ec51d44-d94d-4200-bc2c-fcfb04b1287c", "apiConnectionInfo": "us-south.hs-crypto.cloud.ibm.com:9201" }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your access token is invalid or does not have the necessary permissions to access this resource.'" ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Internal Server Error: IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Create a new key
Creates a new key with specified key material.
Hyper Protect Crypto designates the resource as either a root key or a standard key based on the extractable value that you specify. A successful POST /keys operation adds the key to the service and returns the details of the request in the response entity-body, if the Prefer header is set to return=representation.
POST /keysCustom Headers
Your IBM Cloud access token.
The IBM Cloud instance ID that identifies your Crypto service instance.
The v4 UUID used to correlate and track transactions.
Alters server behavior for POST or DELETE operations. A header with
return=minimalcauses the service to return only the key identifier, or metadata. A header containingreturn=representationreturns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Hyper Protect Crypto may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequentGET /keys/{id}request.Allowable values: [
return=representation,return=minimal]
The base request for creating a new key.
The metadata that describes the resource array.
An array of resources.
curl -X POST \ https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2 \ -H 'authorization: Bearer <IAM_token>' \ -H 'bluemix-instance: <instance_ID>' \ -H 'content-type: application/vnd.ibm.kms.key+json' \ -d '{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "name": "Root-key", "description": "...", "extractable": false } ] }'
var settings = { "async": true, "crossDomain": true, "url": "https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys", "method": "POST", "headers": { "authorization": "Bearer <IAM_token>", "bluemix-instance": "<instance_ID>", "prefer": "return=representation", "content-type": "application/vnd.ibm.kms.key+json" }, "processData": false, "data": { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "name": "Root-key", "description": "...", "extractable": false } ] } } $.ajax(settings).done(function (response) { console.log(response); });
import requests url = "https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys" payload = { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "name": "Root-key", "description": "...", "extractable": false } ] } headers = { "authorization": "Bearer <IAM_token>", "bluemix-instance": "<instance_ID>", "prefer": "return=representation", "content-type": "application/vnd.ibm.kms.key_action+json" } response = requests.request("POST", url, data=payload, headers=headers) print(response.text)
The metadata that describes the resource array.
An array of resources.
Status Code
The key was successfully created.
The key is missing a required field.
Your access token is invalid or does not have the necessary permissions to access this resource.
The instance ID is malformed or invalid.
Too many requests. Please wait a few minutes and try again.
IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-IDin the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.collection+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "name": "Root-key", "description": "...", "state": 1, "extractable": false, "crn": "..." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: The key is missing a required field." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your access token is invalid or does not have the necessary permissions to access this resource.'" ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Forbidden: The instance ID is malformed or invalid." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Please wait a few minutes and try again." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Internal Server Error: IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Retrieve a list of keys
Retrieves a list of keys that are stored in your Hyper Protect Crypto service instance.
Note: GET /keys will not return the key material in the response body. You can retrieve the key material for a standard key with a subsequent GET /keys/{id} request.
GET /keysCustom Headers
Your IBM Cloud access token.
The IBM Cloud instance ID that identifies your Crypto service instance.
The v4 UUID used to correlate and track transactions.
Query Parameters
The number of keys to retrieve. By default,
GET /keysreturns the first 2000 keys. To retrieve a different set of keys, uselimitwithoffsetto page through your available resources. The maximum value forlimitis 5000. Usage: If you have 20 keys in your instance, and you want to retrieve only the first 5 keys, use../keys?limit=5.Constraints: 1 ≤ value ≤ 5000
Default:
2000The number of keys to skip. By specifying
offset, you retrieve a subset of keys that starts with theoffsetvalue. Useoffsetwithlimitto page through your available resources. Usage: If you have 100 keys in your instance, and you want to retrieve keys 26 through 50, use../keys?offset=25&limit=50.Constraints: value ≥ 0
Default:
0
curl -X GET \ https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys \ -H 'authorization: Bearer <IAM_token>' \ -H 'bluemix-instance: <instance_ID>' \ -H 'accept: application/vnd.ibm.collection+json'
var settings = { "async": true, "crossDomain": true, "url": "https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys", "method": "GET", "headers": { "authorization": "Bearer <IAM_token>", "bluemix-instance": "<instance_ID>" } } $.ajax(settings).done(function (response) { console.log(response); });
import requests url = "https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys" headers = { "authorization": "Bearer <IAM_token>", "bluemix-instance": "<instance_ID>", "accept": "application"vnd.ibm.collection+json", } response = requests.request('GET', url, headers=headers) print(response.text)
The metadata that describes the resource array.
An array of resources.
Example:
Status Code
The list of keys was successfully retrieved.
Your access token is invalid or does not have the necessary permissions to access this resource.
The instance ID is malformed or invalid.
Too many requests. Please wait a few minutes and try again.
IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-IDin the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.collection+json", "collectionTotal": 2 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "name": "Root-key", "id": "...", "description": "...", "state": 1, "extractable": false, "createdBy": "...", "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "crn": "..." }, { "type": "application/vnd.ibm.kms.key+json", "name": "Standard-key", "id": "...", "description": "...", "state": 1, "extractable": true, "createdBy": "...", "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "crn": "..." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your access token is invalid or does not have the necessary permissions to access this resource.'" ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Forbidden: The instance ID is malformed or invalid." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Please wait a few minutes and try again." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Internal Server Error: IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Retrieve the number of keys
Returns the same HTTP headers as a GET request without returning the entity-body. This operation returns the number of keys in your instance in a header called Key-Total.
HEAD /keysCustom Headers
Your IBM Cloud access token.
The IBM Cloud instance ID that identifies your Crypto service instance.
The v4 UUID used to correlate and track transactions.
curl -X HEAD \ https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys \ -H 'authorization: Bearer <IAM_token>' \ -H 'bluemix-instance: <instance_ID>' \ -H 'accept: application/vnd.ibm.kms.key+json'
var settings = { "async": true, "crossDomain": true, "url": "https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys", "method": "HEAD", "headers": { "authorization": "Bearer <IAM_token>", "bluemix-instance": "<instance_ID>" } } $.ajax(settings).done(function (response) { console.log(response); });
import requests url = "https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys" headers = { "authorization": "Bearer <IAM_token>", "bluemix-instance": "<instance_ID>", "accept": "application/vnd.ibm.kms.key+json", } response = requests.request('HEAD', url, headers=headers) print(response.text)
Status Code
The metadata was successfully retrieved.
Your access token is invalid or does not have the necessary permissions to access this resource.
The instance ID is malformed or invalid.
Too many requests. Please wait a few minutes and try again.
IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-IDin the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your access token is invalid or does not have the necessary permissions to access this resource.'" ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Forbidden: The instance ID is malformed or invalid." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Please wait a few minutes and try again." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Internal Server Error: IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Custom Headers
Your IBM Cloud access token.
The IBM Cloud instance ID that identifies your Crypto service instance.
The v4 UUID used to correlate and track transactions.
Path Parameters
The v4 UUID that uniquely identifies the key.
curl -X GET \ https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID> \ -H 'authorization: Bearer <IAM_token>' \ -H 'bluemix-instance: <instance_ID>' \ -H 'accept: application/vnd.ibm.kms.key+json'
var settings = { "async": true, "crossDomain": true, "url": "https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>", "method": "GET", "headers": { "authorization": "Bearer <IAM_token>", "bluemix-instance": "<instance_ID>" } } $.ajax(settings).done(function (response) { console.log(response); });
import requests url = 'https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>' headers = { 'authorization': 'Bearer <IAM_token>', 'bluemix-instance': '<instance_ID>', 'accept': 'application/vnd.ibm.kms.key+json', } response = requests.request('GET', url, headers=headers) print(response.text)
The metadata that describes the resource array.
An array of resources.
Example:
Status Code
The key was successfully retrieved.
The key could not be retrieved due to a malformed, invalid, or missing ID.
Your access token is invalid or does not have the necessary permissions to access this resource.
The instance ID is malformed or invalid.
The key could not be found. Verify that the key ID specified is valid.
Too many requests. Please wait a few minutes and try again.
IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-IDin the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.collection+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "name": "Standard-key", "id": "...", "description": "...", "state": 1, "extractable": true, "createdBy": "...", "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "crn": "...", "payload": "..." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: The key could not be retrieved due to a malformed, invalid, or missing ID." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your access token is invalid or does not have the necessary permissions to access this resource.'" ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Forbidden: The instance ID is malformed or invalid." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: The key could not be found. Verify that the key ID specified is valid." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Please wait a few minutes and try again." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Internal Server Error: IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Invoke an action on a key
Invokes an action, such as a wrap, unwrap, or rotate operation, on a specified root key.
Note: When you unwrap a wrapped data encryption key (WDEK) by using a rotated root key, the service returns a new ciphertext in the response entity-body. Each ciphertext remains available for unwrap actions. If you unwrap a DEK with a previous ciphertext, the service also returns the latest ciphertext in the response. Use the latest ciphertext for future unwrap operations.
POST /keys/{id}Custom Headers
Your IBM Cloud access token.
The IBM Cloud instance ID that identifies your Crypto service instance.
The v4 UUID used to correlate and track transactions.
Alters server behavior for POST or DELETE operations. A header with
return=minimalcauses the service to return only the key identifier, or metadata. A header containingreturn=representationreturns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Hyper Protect Crypto may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequentGET /keys/{id}request.Allowable values: [
return=representation,return=minimal]
Path Parameters
The root key that is used as the wrapping key. It must be a v4 UUID for an active key.
Query Parameters
The action to perform on the specified key.
Allowable values: [
wrap,unwrap,rotate]
The request to perform a key wrap operation.
The data encryption key (DEK) used in wrap actions when the query parameter is set to
wrap. The system returns a base64 encoded plaintext in the response entity-body when you perform anunwrapaction on a key. To wrap an existing DEK, provide a base64 encoded plaintext during awrapaction. To generate a new DEK, omit theplaintextproperty. Hyper Protect Crypto generates a random plaintext (32 bytes) that is rooted in an HSM and then wraps that value.Constraints: length ≤ 4096
The additional authentication data (AAD) used to further secure the key. If you supply AAD when you make a
wrapcall, you must specify the same AAD during a subsequentunwrapcall.Constraints: 0 ≤ number of items ≤ 126, 0 ≤ length ≤ 255
The wrapped data encryption key (DEK) used in wrap actions when the query parameter is set to
unwrap. The system requires a base64 encoded ciphertext and returns a base64 encoded plaintext in the response entity-body when you perform anunwrapaction on a key. Note: When you unwrap a wrapped data encryption key (WDEK) by using a rotated root key, the service returns a new ciphertext in the response entity-body. Each ciphertext remains available forunwrapactions. If you unwrap a DEK with a previous ciphertext, the service also returns the latest ciphertext in the response. Use the latest ciphertext for future unwrap operations.The key material that you want to import into the service for rotating an existing root key. This value is required for a
rotateaction if you initially imported the key material when you created the key. To rotate an imported root key, provide a base64 encoded payload in the request entity-body. To rotate a root key that was initially generated by Hyper Protect Crypto, omit thepayloadproperty and pass in an empty request entity-body.
curl -X POST \ https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>?action=wrap \ -H 'authorization: Bearer <IAM_token>' \ -H 'bluemix-instance: <instance_ID>' \ -H 'accept: application/vnd.ibm.kms.key_action+json' \ -H 'content-type: application/vnd.ibm.kms.key_action+json' \ -d '{ 'plaintext': '<data_key>', 'aad': ['<additional_data>', '<additional_data>'] }'
var settings = { "async": true, "crossDomain": true, "url": "https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>?action=wrap", "method": "POST", "headers": { "authorization": "Bearer <IAM_token>", "bluemix-instance": "<instance_ID>", "prefer": "return=representation", "accept": "application/vnd.ibm.kms.key_action+json", "content-type": "application/vnd.ibm.kms.key_action+json" }, "processData": false, "data": { "plaintext": "<data_key>", "aad": [ <additional_data>, <additional_data> ] } } $.ajax(settings).done(function (response) { console.log(response); });
import requests url = "https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>" querystring = { "action": "wrap" } payload = { "plaintext": "string", "aad": [ <additional_data>, <additional_data> ] } headers = { "authorization": "Bearer <IAM_token>", "bluemix-instance": "<instance_ID>", "prefer": "return=representation", "accept": "application/vnd.ibm.kms.key_action+json", "content-type": "application/vnd.ibm.kms.key_action+json" } response = requests.request("POST", url, data=payload, headers=headers, params=querystring) print(response.text)
The base request for key actions.
The data encryption key (DEK) used in wrap actions when the query parameter is set to
wrap. The system returns a base64 encoded plaintext in the response entity-body when you perform anunwrapaction on a key. To wrap an existing DEK, provide a base64 encoded plaintext during awrapaction. To generate a new DEK, omit theplaintextproperty. Hyper Protect Crypto generates a random plaintext (32 bytes) that is rooted in an HSM and then wraps that value.Constraints: length ≤ 4096
The wrapped data encryption key (DEK) used in wrap actions when the query parameter is set to
unwrap. The system requires a base64 encoded ciphertext and returns a base64 encoded plaintext in the response entity-body when you perform anunwrapaction on a key. Note: When you unwrap a wrapped data encryption key (WDEK) by using a rotated root key, the service returns a new ciphertext in the response entity-body. Each ciphertext remains available forunwrapactions. If you unwrap a DEK with a previous ciphertext, the service also returns the latest ciphertext in the response. Use the latest ciphertext for future unwrap operations.
Status Code
Successful key operation.
Successful key operation. Your key was successfully rotated.
Your authentication data or key is invalid, or the entity-body is missing a required field.
Your access token is invalid or does not have the necessary permissions to access this resource.
The instance ID is malformed or invalid.
The key is not in an active state, so any KeyAction will fail. Check the key's
nonactiveStateReasonto understand how to proceed.The requested key was previously deleted and is no longer available. Please delete references to this key.
The ciphertext provided for the unwrap operation was not wrapped by this key.
Too many requests. Please wait a few minutes and try again.
IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-IDin the response header and contact IBM Cloud support.
{ "plaintext": "...", "ciphertext": "..." }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Bad Request: Your authentication data or key is invalid, or the entity-body is missing a required field.'" ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your access token is invalid or does not have the necessary permissions to access this resource.'" ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Forbidden: The instance ID is malformed or invalid." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Conflict: The key is not in an active state, so any KeyAction will fail. Check the key's nonactiveStateReason to understand how to proceed.'" ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Gone: The requested key was previously deleted and is no longer available. Please delete references to this key.'" ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unprocessable Entity: The ciphertext provided for the unwrap operation was not wrapped by this key.'" ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Please wait a few minutes and try again." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Internal Server Error: IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Delete a key by ID
Deletes a key by specifying the ID of the key. Important: When you delete a key, you permanently shred its contents and associated data. The action cannot be reversed.
DELETE /keys/{id}Custom Headers
Your IBM Cloud access token.
The IBM Cloud instance ID that identifies your Crypto service instance.
The v4 UUID used to correlate and track transactions.
Alters server behavior for POST or DELETE operations. A header with
return=minimalcauses the service to return only the key identifier, or metadata. A header containingreturn=representationreturns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Hyper Protect Crypto may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequentGET /keys/{id}request.Allowable values: [
return=representation,return=minimal]
Path Parameters
The v4 UUID that uniquely identifies the key.
curl -X DELETE \ https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID> \ -H 'authorization: Bearer <IAM_token>' \ -H 'bluemix-instance: <instance_ID>' \ -H 'accept: application/vnd.ibm.kms.key+json'
var settings = { "async": true, "crossDomain": true, "url": "https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>", "method": "DELETE", "headers": { "authorization": "Bearer <IAM_token>", "bluemix-instance": "<instance_ID>" } } $.ajax(settings).done(function (response) { console.log(response); });
import requests url = "https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>" headers = { "authorization": "Bearer <IAM_token>", "bluemix-instance": "<instance_ID>", "accept": "application/vnd.ibm.kms.key+json", } response = requests.request("DELETE", url, headers=headers) print(response.text)
The metadata that describes the resource array.
An array of resources.
Status Code
The key was successfully deleted.
The key was deleted.
The key cannot be deleted due to a malformed, invalid, or missing ID.
Your access token is invalid or does not have the necessary permissions to access this resource.
The instance ID is malformed or invalid.
The key could not be found.
The requested key was previously deleted and is no longer available. Please delete references to this key.
Too many requests. Please wait a few minutes and try again.
IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-IDin the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.collection+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "name": "Root-key", "description": "...", "state": 5, "extractable": false, "crn": "...", "deleted": true, "deletionDate": "YYYY-MM-DDTHH:MM:SSZ", "deletedBy": "..." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: The key cannot be deleted due to a malformed, invalid, or missing ID." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your access token is invalid or does not have the necessary permissions to access this resource.'" ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Forbidden: The instance ID is malformed or invalid." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: They key could not be found." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Gone: The requested key was previously deleted and is no longer available. Please delete references to this key.'" ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Please wait a few minutes and try again." } ] }{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Internal Server Error: IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later.'" ] }