Introduction
IBM Cloud Hyper Protect Crypto Services is a dedicated key management service and hardware security module (HSM). It is designed to enable you to take control of your cloud data encryption keys and cloud hardware security models, and is the only service in the industry built on FIPS 140-2 Level 4-certified hardware. 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 more information about using Hyper Protect Crypto Services, see the IBM Cloud docs.
The code examples on this tab use the client library that is provided for Go.
go get -u github.com/IBM/keyprotect-go-client
GitHub
The code examples on this tab use the client library that is provided for NodeJS.
npm require keyprotect-nodejs-client
GitHub:
The code examples on this tab use the client library that is provided for Python.
pip install -U keyprotect
GitHub
The code examples on this tab use the client library that is provided for Java.
Installation via Maven
<dependency>
<groupId>com.ibm.cloud</groupId>
<artifactId>key-protect-api</artifactId>
<version>0.1.0</version>
</dependency>
Installation via Gradle
'com.ibm.cloud:key-protect-api:0.1.0'
GitHub
Endpoint URLs
Use the Retrieve the API endpoint URL method first to retrieve the URL for the dedicated API endpoint for key management operations. When you call the API, use the URL that corresponds to the region where your service instance is deployed.
- Dallas:
https://us-south.broker.hs-crypto.cloud.ibm.com/crypto_v2/
- Frankfurt:
https://eu-de.broker.hs-crypto.cloud.ibm.com/crypto_v2/
- London:
https://eu-gb.broker.hs-crypto.cloud.ibm.com/crypto_v2/
- São-Paulo:
https://br-sao.broker.hs-crypto.cloud.ibm.com/crypto_v2/
- Sydney:
https://au-syd.broker.hs-crypto.cloud.ibm.com/crypto_v2/
- Tokyo:
https://jp-tok.broker.hs-crypto.cloud.ibm.com/crypto_v2/
- Toronto:
https://ca-tor.broker.hs-crypto.cloud.ibm.com/crypto_v2/
- Washington DC:
https://us-east.broker.hs-crypto.cloud.ibm.com/crypto_v2/
To call other API methods, use the endpoint URL that is returned in the kms section when you call the Retrieve the API endpoint URL method. The returned URL contains the region and port information. Note the URLs vary depending on whether you are using the public or private endpoint.
"public": "api.<region>.hs-crypto.cloud.ibm.com:<port>"
"private": "api.private.<region>.hs-crypto.cloud.ibm.com:<port>"
Authentication
To call each method, you'll need to be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles, see Managing access for Hyper Protect Crypto Services.
To work with the API, authenticate your app or service by including your IBM Cloud IAM access token and instance ID in API requests.
You can build your API request by pairing a service endpoint with your authentication credentials:
curl -X GET \
"https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys" \
-H "accept: application/vnd.ibm.collection+json" \
-H "authorization: Bearer <access_token>" \
-H "bluemix-instance: <instance_ID>"
Replace <region>
with the prefix that represents the geographic area where your service instance resides. For more information, see Regions and locations.
Replace <port>
with the port number of the API endpoint.
Replace <access_token>
with your Cloud IAM token, and <instance_ID>
with the IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
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 Retrieving an access token programmatically.
To find out more about setting up the Hyper Protect Crypto Services key management service API, see Accessing the API.
IBM Cloud Identity and Access Management (IAM) is the primary method to authenticate to the Hyper Protect Crypto Services API.
The SDK provides client configuration initialization method in which you will need to replace Key management endpoint URL
with a service endpoint, the API_KEY
with the API key associated with your application, the TokenURL
with your Cloud IAM token, and InstanceID
with the IBM Cloud instance ID that identifies your Hyper Protect Crypto Services
instance. The value kp.DefaultTokenURL
for TokenURL
defaults to IAM production URL. Use the client configuration options in the method to create a new Hyper Protect Crypto Services client. The method handles the authentication procedure with
the provided API_KEY.
IBM Cloud Identity and Access Management (IAM) is the primary method to authenticate to the Hyper Protect Crypto Services API. The SDK provides a client config setup in which you will need to export
environment variables to match the IBMCLOUD_API_KEY
term with the API key associated with your service credentials, the IAM_AUTH_URL
term with the appropriate URL like 'https://iam.cloud.ibm.com/identity/token', the KP_SERVICE_URL
term with the endpoint including the region and port, such as https://api.us-south.hs-crypto.cloud.ibm.com:9371
, and the KP_INSTANCE_ID
term with the instance ID that identifies your Hyper Protect Crypto Services service instance.
To retrieve your instance ID:
ibmcloud resource service-instance <instance_name> --output JSON
IBM Cloud Identity and Access Management (IAM) is the primary method to authenticate to the Hyper Protect Crypto Services API. The SDK provides a client configuration setup, in which, you need to replace the IBMCLOUD_API_KEY
with the API key associated with your application, and KP_INSTANCE_ID
with the IBM Cloud instance ID that identifies your Hyper Protect Crypto Services service
instance.
IBM Cloud Identity and Access Management (IAM) is the primary method to authenticate to the Hyper Protect Crypto Services key management service API.
The software development kit provides a client configuration setup, in which, you need to replace the IAM_API_KEY
with the API key
associated with your application, IAM_AUTH_URL
with your Cloud IAM token, KEY_MANAGEMENT_ENDPOINT_URL
with a service endpoint, and INSTANCE_ID
with the IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
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>" > token.json
Replace <API_KEY>
with your service credentials. Then use the full
access_token
value, prefixed by the _Bearer_token type, to authenticate your API requests.
To retrieve your instance ID:
ibmcloud resource service-instance <instance_name> --output JSON
Replace <instance_name>
with the unique alias that you assigned to your Hyper Protect Crypto Services instance. The GUID
value in the JSON output represents the instance ID for the service.
To authenticate to Hyper Protect Crypto Services key management service API:
import (
"context"
"encoding/json"
"fmt"
"github.com/IBM/keyprotect-go-client"
)
func getConfigAPIKey() kp.ClientConfig {
return kp.ClientConfig{
BaseURL: <key_management_endpoint_url>,
APIKey: <api_key>,
TokenURL: kp.DefaultTokenURL,
InstanceID: <instance_ID>,
Verbose: kp.VerboseFailOnly,
}
}
func main() {
options := getConfigAPIKey()
api, err := kp.New(options, kp.DefaultTransport())
if err != nil {
fmt.Println("Error creating kp client")
return
}
}
Replace the <key_management_endpoint_url>
with the API endpoint.
API endpoint
https://api.<region>.hs-crypto.cloud.ibm.com:<port>
Replace <region>
with the prefix that represents the geographic area where your Hyper Protect Crypto Services instance resides. For more informaton, see Regions and locations.
Replace <port>
with the port number of the API endpoint.
Replace <api_key>
with your service credentials.
Replace the <instance_ID>
with the Hyper Protect Crypto Services instance ID.
To retrieve your instance ID:
ibmcloud resource service-instance <instance_name> --output JSON
Replace <instance_name>
with the unique alias that you assigned to your Hyper Protect Crypto Services instance. The GUID
value in the JSON output represents the instance ID for the service.
To authenticate to Hyper Protect Crypto Services API:
const KeyProtectV2 = require('ibm-key-protect-api/v2');
const { IamAuthenticator } = require('auth');
// using external configuration of environment variables
const envConfigs = {
apiKey: process.env.IBMCLOUD_API_KEY,
iamAuthUrl: process.env.IAM_AUTH_URL,
serviceUrl: process.env.KP_SERVICE_URL,
bluemixInstance: process.env.KP_INSTANCE_ID,
};
// Create an IAM authenticator.
const authenticator = new IamAuthenticator({
apikey: envConfigs.apiKey,
url: envConfigs.iamAuthUrl,
});
// Construct the service client.
const keyProtectClient = new KeyProtectV2({
authenticator,
serviceUrl: envConfigs.serviceUrl,
});
For more information on the regional endpoint where your data can be accessed, see Regions and locations.
To authenticate to Hyper Protect Crypto Services key management service API:
import os
import keyprotect
from keyprotect import bxauth
tm = bxauth.TokenManager(api_key=os.getenv("IBMCLOUD_API_KEY"))
kp = keyprotect.Client(
credentials=tm,
region="<region>",
service_instance_id=os.getenv("KP_INSTANCE_ID")
endpoint_url="<key_management_endpoint_url>"
)
Replace <IBMCLOUD_API_KEY>
with your service credentials.
Replace <region>
with the prefix that represents the geographic area where your Hyper Protect Crypto Services instance resides. For more information, see Regions and locations.
Replace KP_INSTANCE_ID
with the UUID that identifies your Hyper Protect Crypto Services instance.
To retrieve your instance ID:
ibmcloud resource service-instance <instance_name> --output JSON
Replace <instance_name>
with the unique alias that you assigned to your Hyper Protect Crypto Services instance. The GUID
value in the JSON output represents the instance ID for the service.
Replace <key_management_endpoint_url>
with your service instance endpoint URL.
To authenticate to Hyper Protect Crypto Services API:
import com.ibm.cloud.ibm_key_protect_api.v2.model.*;
import com.ibm.cloud.sdk.core.http.Response;
import com.ibm.cloud.sdk.core.security.*;
import java.lang.*;
import java.util.List;
public class sampleGetKeys {
public static void main(String[] args) {
String bluemixInstance = <INSTANCE_ID>;
IbmKeyProtectApi testService;
IamAuthenticator authenticator = new IamAuthenticator(<IAM_API_KEY>);
authenticator.setURL(<IAM_AUTH_URL>);
authenticator.validate();
testService = IbmKeyProtectApi.newInstance(authenticator);
testService.setServiceUrl(<KEY_MANAGEMENT_ENDPOINT_URL>);
}
}
Replace <INSTANCE_ID>
with the UUID that identifies your Hyper Protect Crypto Services instance.
Replace <IAM_API_KEY>
with your service credentials.
Replace <IAM_AUTH_URL>
with your IAM token.
Replace <KEY_MANAGEMENT_ENDPOINT_URL>
with the service endpoint that you want to make requests to.
To retrieve your instance ID:
ibmcloud resource service-instance <instance_name> --output JSON
Replace <instance_name>
with the unique alias that you assigned to your Hyper Protect Crypto Services instance. The GUID
value in the JSON output represents the instance ID for the service.
Auditing
You can monitor API activity within your account by using the Activity Tracker service. Whenever an API method is called, an event is generated that you can then track and audit from within Activity Tracker. The specific event type is listed for each individual method.
For more information about how to track Hyper Protect Crypto Services activity, see Auditing Events for Hyper Protect Crypto Services.
Error handling
Hyper Protect Crypto Services uses standard HTTP response codes to indicate whether a method completed successfully. A 200
response always indicates success. A 400
type response is some sort of failure, and a 500
type response usually indicates an internal system error.
Status code | Description |
---|---|
200 OK | Everything worked as expected. |
201 OK | Everything worked as expected. No content |
400 Bad Request | The request was unsuccessful, often due to a missing required parameter. |
401 Unauthorized | The parameters were valid but the request failed due insufficient permissions. |
404 Not Found | The requested resource doesn't exist. |
410 Gone | The requested resource was deleted and no longer exists. |
429 Too Many Requests | Too many requests hit the API too quickly. |
500 Server Error | Something went wrong on Hyper Protect Crypto Services's end. |
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.
Pagination
Some API requests might return a large number of results. By specifying the limit
and offset
parameters at query time, you can retrieve a subset of your keys, starting with the offset value that you specify.
For more information, see Retrieving a subset of keys.
Change log
Important changes, such as additions, updates, and breaking changes, are marked with a change notice in this reference.
For a complete list of changes and improvements to this API, see the Hyper Protect Crypto Services key management service API change log.
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. The endpoint URL varies depending on which regional service endpoint you are using.
- Dallas:
https://us-south.broker.hs-crypto.cloud.ibm.com/crypto_v2/
- Frankfurt:
https://eu-de.broker.hs-crypto.cloud.ibm.com/crypto_v2/
- London:
https://eu-gb.broker.hs-crypto.cloud.ibm.com/crypto_v2/
- São-Paulo:
https://br-sao.broker.hs-crypto.cloud.ibm.com/crypto_v2/
- Sydney:
https://au-syd.broker.hs-crypto.cloud.ibm.com/crypto_v2/
- Tokyo:
https://jp-tok.broker.hs-crypto.cloud.ibm.com/crypto_v2/
- Toronto:
https://ca-tor.broker.hs-crypto.cloud.ibm.com/crypto_v2/
- Washington DC:
https://us-east.broker.hs-crypto.cloud.ibm.com/crypto_v2/
Depending on whether you are using the public or private endpoint, choose the proper endpoint URL in the kms section that is returned in the following formats. Refer to the right-side example pane for an example:
"public": "api.<region>.hs-crypto.cloud.ibm.com:<port>"
"private": "api.private.<region>.hs-crypto.cloud.ibm.com:<port>"
GET /instances/{id}
Request
Path Parameters
The IBM Cloud UUID that uniquely identifies the instance. For how to retrieve your instance ID, see Retrieving your instance ID for instructions.
curl -X GET https://us-south.broker.hs-crypto.cloud.ibm.com/crypto_v2/instances/{id} -H 'Authorization: Bearer {access_token}'
package main import ( "fmt" "io/ioutil" "net/http" ) func main() { instanceID := "<INSTANCE_ID>" region := "<REGION>" bearerToken := "Bearer <TOKEN>" method := "GET" url := fmt.Sprintf("https://%s.broker.hs-crypto.cloud.ibm.com/crypto_v2/instances/%s", region, instanceID) client := &http.Client{} req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } req.Header.Add("Authorization", bearerToken) res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) }
let fetch = require('node-fetch'); fetch('https://us-south.broker.hs-crypto.cloud.ibm.com/crypto_v2/instances/{id}', { method: ‘GET’, headers: {'Content-Type': 'application/json'}, body: '{}' }).then(response => { return response.json(); }).catch(err => {console.log(err);});
import requests url = "https://us-south.broker.hs-crypto.cloud.ibm.com/crypto_v2/instances/{id}" headers = { 'Authorization': 'Bearer {access_token}', } response = requests.request('GET', url, headers=headers) print(response.text)
package hpcs; import java.io.IOException; import com.squareup.okhttp.*; public class sampleGetInstanceEndpoints { public static void main(String[] args) { String instanceID = "<INSTANCE_ID>"; String region = "<REGION>"; String bearerToken = "Bearer <TOKEN>"; String url = String.format("https://%s.broker.hs-crypto.cloud.ibm.com/crypto_v2/instances/%s", region, instanceID); OkHttpClient client = new OkHttpClient(); Request request = new Request.Builder() .url(url) .method("GET", null) .addHeader("Authorization", bearerToken) .build(); try { Response response = client.newCall(request).execute(); System.out.println(response.body().string()); } catch (IOException e) { e.printStackTrace(); } } }
Response
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 credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
The instance could not be found. Verify that the instance ID specified is valid.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "instance_id": "4ec51d44-d94d-4200-bc2c-fcfb04b1287c", "kms": { "public": "api.us-south.hs-crypto.cloud.ibm.com:9371", "private": "api.private.us-south.hs-crypto.cloud.ibm.com:9372" }, "ep11": { "public": "ep11.us-south.hs-crypto.cloud.ibm.com:9371", "private": "ep11.private.us-south.hs-crypto.cloud.ibm.com:9372" } }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Internal Server Error: IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
List keys
Retrieves a list of keys that are stored in your Hyper Protect Crypto Services 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 /api/v2/keys
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the target key ring. If unspecified, all resources in the instance that the caller has access to will be returned. When the header is specified, only resources within the specified key ring, that the caller has access to, will be returned. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Query Parameters
The number of keys to retrieve. By default,
GET /keys
returns the first 200 keys. To retrieve a different set of keys, uselimit
withoffset
to page through your available resources. The maximum value forlimit
is 5000. Usage: If you have 20 keys in your instance, and you want to retrieve only the first 5 keys, use../keys?limit=5
.Possible values: 1 ≤ value ≤ 5000
Default:
200
The number of keys to skip. By specifying
offset
, you retrieve a subset of keys that starts with theoffset
value. Useoffset
withlimit
to 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=25
.Possible values: value ≥ 0
Default:
0
The state of the keys to be retrieved. States must be a list of integers from 0 to 5 delimited by commas with no whitespace or trailing commas. Valid states are based on NIST SP 800-57. States are integers and correspond to the Pre-activation = 0, Active = 1, Suspended = 2, Deactivated = 3, and Destroyed = 5 values. Usage: If you want to retrieve active and deleted keys, use
../keys?state=1,5
.Allowable values: [
0
,1
,2
,3
,5
]Default:
[0,1,2,3]
The type of keys to be retrieved. Filters keys based on the
extractable
property. You can use this query parameter to search for keys whose material can leave the service. If set totrue
, standard keys will be retrieved. If set tofalse
, root keys will be retrieved. If omitted, both root and standard keys will be retrieved.Usage: If you want to retrieve standard keys, use
../keys?extractable=true
.
curl GET https://api.<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'
package main import ( "context" "encoding/json" "fmt" "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the key protect client as specified in Authentication keys, err := api.GetKeys(context.Background(), <limit>, <offset>) if err != nil { fmt.Println("Get Keys failed with error: ", err) return } b, _ := json.MarshalIndent(keys, "", " ") fmt.Println(string(b)) }
// Initialize the key protect client as specified in Authentication const response = keyProtectClient.getKeys(envConfigs); console.log('Get keys result:'); for (let resource of response.result.resources){ console.log(resource); }
import os import keyprotect from keyprotect import bxauth # Initialize the key protect client as specified in Authentication keys = kp.keys() for key in kp.keys(): print("%s\t%s" % (key["id"], key["name"]))
//Initialize the key protect client as specified in Authentication GetKeysOptions getKeysOptionsModel = new GetKeysOptions.Builder() .bluemixInstance(bluemixInstance) .build(); Response<ListKeys> response = testService.getKeys(getKeysOptionsModel).execute(); List<KeyRepresentation> keys = response.getResult().getResources();
Response
The base schema for listing keys.
The metadata that describes the resource array.
A collection of resources.
Status Code
The list of keys was successfully retrieved.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
Too many requests. Please wait a few minutes and try again.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 2 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "...", "name": "Root-key", "description": "...", "state": 1, "expirationDate": "YYYY-MM-DDTHH:MM:SSZ", "extractable": true, "crn": "...", "imported": false, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "AES", "algorithmMetadata": { "bitLength": 256, "mode": "CBC_PAD" }, "algorithmBitSize": 256, "algorithmMode": "CBC_PAD", "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ", "lastRotateDate": "YYYY-MM-DDTHH:MM:SSZ", "keyVersion": { "id": "...", "creationDate": "YYYY-MM-DDTHH:MM:SSZ" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "deleted": false }, { "type": "application/vnd.ibm.kms.key+json", "id": "...", "name": "Standard-key", "description": "...", "state": 1, "extractable": true, "crn": "...", "imported": false, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "AES", "algorithmMetadata": { "bitLength": 256, "mode": "CBC_PAD" }, "algorithmBitSize": 256, "algorithmMode": "CBC_PAD", "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ", "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "deleted": false } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Create a key
Creates a new key with specified key material.
Hyper Protect Crypto Services 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 /api/v2/keys
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
Alters server behavior for POST or DELETE operations. A header with
return=minimal
causes the service to return only the key identifier, or metadata. A header containingreturn=representation
returns 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 Services 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 ID of the target key ring. This header is only required if the caller does not have access to the
default
key ring.Default:
default
The base request for creating a new key.
A collection of resources.
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'content-type: application/vnd.ibm.kms.key+json' -H 'x-kms-key-ring: <key_ring_ID>' -H 'correlation-id: <correlation_ID>' -d '{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "name": "Root-key", "description": "...", "aliases": [alias_list], "extractable": false } ] }'
package main import ( "context" "encoding/json" "fmt" "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the key protect client as specified in Authentication rootkey, err := api.CreateKey(context.Background(), <key_name>, <expiration_date>, <extractable>) if err != nil { fmt.Println("Error while creating key: ", err) return } b, _ := json.MarshalIndent(rootkey, "", " ") fmt.Println(string(b)) }
// Initialize the key protect client as specified in Authentication // Define the key parameters const body = { metadata: { collectionType: 'application/vnd.ibm.kms.key+json', collectionTotal: 1, }, resources: [ { type: 'application/vnd.ibm.kms.key+json', name: 'nodejsKey', extractable: false, }, ], }; const createParams = Object.assign({}, envConfigs); createParams.body = body; const response = keyProtectClient.createKey(createParams); const keyId = response.result.resources[0].id; console.log('Key created, id is: ' + keyId);
import os import keyprotect from keyprotect import bxauth # Initialize the key protect client as specified in Authentication key = kp.create(name="<key_name>") print("Created key '%s'" % key['id'])
//Initialize the key protect client as specified in Authentication InputStream inputstream = new FileInputStream(<PATH_TO_Create_Key_Body>) CreateKeyOptions createKeyOptionsModel = new CreateKeyOptions.Builder() .bluemixInstance(bluemixInstance) .createKeyOneOf(inputstream) .correlationId("testString") .prefer("return=representation") .build(); // Invoke operation with valid options model (positive test) Response<Key> response = testService.createKey(createKeyOptionsModel).execute();
Response
Properties associated with a key response.
The metadata that describes the resource array.
A collection of resources.
Status Code
The key was successfully created.
The key is missing a required field.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
Your service is not authorized to make this request. Ensure that an authorization exists between your service and Hyper Protect Crypto Services. Learn more
The import token that was used to encrypt this key has reached its
maxAllowedRetrievals
orexpirationDate
, and it is no longer available for operations. To create a new import token, usePOST /import_token
. In very rare cases, the import token may expire before its expiration time. Ensure that your client application is configured with a retry mechanism for catching and responding to409
conflict exceptions.Too many requests. Please wait a few minutes and try again.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "...", "name": "Root-key", "description": "...", "state": 1, "expirationDate": "YYYY-MM-DDTHH:MM:SSZ", "extractable": false, "crn": "...", "imported": false, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "AES", "algorithmMetadata": { "bitLength": 256, "mode": "CBC_PAD" }, "algorithmBitSize": 256, "algorithmMode": "CBC_PAD", "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ", "keyVersion": { "id": "...", "creationDate": "YYYY-MM-DDTHH:MM:SSZ" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "deleted": false } ] }
{ "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 credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Your service is not authorized to make this request. Ensure that an authorization exists between your service and Hyper Protect Crypto Services. [Learn more](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-integrate-services#grant-access)'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Conflict: The import token that was used to encrypt this key has reached its `maxAllowedRetrievals` or `expirationDate`, and it is no longer available for key operations. To create a new import token, use `POST /import_token`." ] }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Retrieve key total
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 /api/v2/keys
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the target key ring. If unspecified, all resources in the instance that the caller has access to will be returned. When the header is specified, only resources within the specified key ring, that the caller has access to, will be returned. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Query Parameters
The state of the keys to be retrieved. States must be a list of integers from 0 to 5 delimited by commas with no whitespace or trailing commas. Valid states are based on NIST SP 800-57. States are integers and correspond to the Pre-activation = 0, Active = 1, Suspended = 2, Deactivated = 3, and Destroyed = 5 values. Usage: If you want to retrieve active and deleted keys, use
../keys?state=1,5
.Allowable values: [
0
,1
,2
,3
,5
]Default:
[0,1,2,3]
The type of keys to be retrieved. Filters keys based on the
extractable
property. You can use this query parameter to search for keys whose material can leave the service. If set totrue
, standard keys will be retrieved. If set tofalse
, root keys will be retrieved. If omitted, both root and standard keys will be retrieved.Usage: If you want to retrieve standard keys, use
../keys?extractable=true
.
curl -I HEAD https://api.<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'
Response
Response Headers
The number of keys in your service instance.
Status Code
The metadata was successfully retrieved.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
Your service is not authorized to make this request. Ensure that an authorization exists between your service and Hyper Protect Crypto Services. Learn more
Too many requests. Please wait a few minutes and try again.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
Retrieve a key
Retrieves a key and its details by specifying the ID or alias of the key.
GET /api/v2/keys/{id-or-alias}
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID or alias that uniquely identifies the key
curl GET https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID_or_alias> -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'accept: application/vnd.ibm.kms.key+json'
package main import ( "context" "encoding/json" "fmt" "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the key protect client as specified in Authentication key, err := api.GetKey(context.Background(), <key_ID>) if err != nil { fmt.Println("Get Key failed with error: ", err) return } b, _ := json.MarshalIndent(key, "", " ") fmt.Println(string(b)) }
// Initialize the key protect client as specified in Authentication const getKeyParams = Object.assign({}, envConfigs); getKeyParams.id = "<key_ID_or_alias>"; const response = keyProtectClient.getKey(getKeyParams); console.log('Get key result: '); console.log(response.result.resources[0]);
import os import keyprotect from keyprotect import bxauth # Initialize the key protect client as specified in Authentication key = kp.get('id') print("%s\t%s" % (key["id"], key["name"]))
Response
The base schema for retrieving keys.
The metadata that describes the resource array.
A collection of resources.
Status Code
The key was successfully retrieved. If the key was previously deleted,
keyVersion.creationDate
is omitted from the request response.The key could not be retrieved due to a malformed, invalid, or missing ID.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
Your service is not authorized to make this request. Ensure that an authorization exists between your service and Hyper Protect Crypto Services. Learn more
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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "...", "name": "Standard-key", "description": "...", "state": 1, "expirationDate": "YYYY-MM-DDTHH:MM:SSZ", "extractable": true, "crn": "...", "imported": false, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "AES", "algorithmMetadata": { "bitLength": 256, "mode": "CBC_PAD" }, "algorithmBitSize": 256, "algorithmMode": "CBC_PAD", "keyVersion": { "id": "...", "creationDate": "YYYY-MM-DDTHH:MM:SSZ" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "deleted": false, "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 credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Your service is not authorized to make this request. Ensure that an authorization exists between your service and Hyper Protect Crypto Services. [Learn more](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-integrate-services#grant-access)'" ] }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Retrieve key metadata
Retrieves the details of a key by specifying the ID or alias of the key.
GET /api/v2/keys/{id-or-alias}/metadata
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID or alias that uniquely identifies the key
curl GET https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID_or_alias>/metadata -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'accept: application/vnd.ibm.kms.key+json'
Response
The base schema for retrieving key metadata.
The metadata that describes the resource array.
A collection of resources.
Status Code
The key metadata was successfully retrieved.
The key metadata could not be retrieved due to a malformed, invalid, or missing ID.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
Your service is not authorized to make this request. Ensure that an authorization exists between your service and Hyper Protect Crypto Services. Learn more
The key metadata for key with specified ID could not be found.
Too many requests. Please wait a few minutes and try again.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "...", "name": "Standard-key", "description": "...", "state": 1, "expirationDate": "YYYY-MM-DDTHH:MM:SSZ", "extractable": true, "crn": "...", "imported": false, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "AES", "algorithmMetadata": { "bitLength": 256, "mode": "CBC_PAD" }, "algorithmBitSize": 256, "algorithmMode": "CBC_PAD", "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ", "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "deleted": false } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: The key metadata 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 credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Your service is not authorized to make this request. Ensure that an authorization exists between your service and Hyper Protect Crypto Services. [Learn more](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-integrate-services#grant-access)'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": { "errorMsg": "Key metadata could not be retrieved. Please see `reasons` for more details.", "reasons": [ { "code": "KEY_NOT_FOUND", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
List key versions
Retrieves all versions of a root key by specifying the ID of the key. When you rotate a root key, you generate a new version of the key. If you're using the root key to protect resources across IBM Cloud, the registered cloud services that you associate with the key use the latest key version to wrap your data. Learn more
GET /api/v2/keys/{id}/versions
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID that uniquely identifies the key.
Query Parameters
The number of key versions to retrieve. By default,
GET /versions
returns the first 200 key versions. To retrieve a different set of key versions, uselimit
withoffset
to page through your available resources. The maximum value forlimit
is 5000. Usage: If you have a key with 20 versions in your instance, and you want to retrieve only the first 5 versions, use../versions?limit=5
.Possible values: 1 ≤ value ≤ 5000
Default:
200
The number of key versions to skip. By specifying
offset
, you retrieve a subset of key versions that starts with theoffset
value. Useoffset
withlimit
to page through your available resources. Usage: If you have a key with 100 versions in your instance, and you want to retrieve versions 26 through 50, use../versions?offset=25&limit=25
.Possible values: value ≥ 0
Default:
0
curl GET https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/versions -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'accept: application/vnd.ibm.kms.key.version+json'
Response
Properties associated with a registration response.
The metadata that describes the resource array.
An array of resources.
Status Code
The list of key versions was successfully retrieved.
The request is missing a required field.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
The key could not be found.
The key is not in an active state.
The requested key was previously deleted and is no longer available. Please delete references to this key.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 2 }, "resources": [ { "id": "...", "creationDate": "YYYY-MM-DDTHH:MM:SSZ" }, { "id": "...", "creationDate": "YYYY-MM-DDTHH:MM:SSZ" } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: The key could not be found." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Conflict: The key is not in an active state.'" ] }
{ "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.'" ] }
Update a key
Update attributes of a key. Currently only the following attributes are applicable for update:
- keyRingID
Note: If provided, the X-Kms-Key-Ring
header should specify the key's current key ring. To change the key ring of the key, specify the new key ring in the request body.
PATCH /api/v2/keys/{id}
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID that uniquely identifies the key.
The base request for patching a key.
The target key ring to move the targeted key to.
curl -X PATCH https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID> -H 'accept: application/vnd.ibm.kms.key+json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'content-type: application/vnd.ibm.kms.key+json' -H "x-kms-key-ring: <original_key_ring_ID>" -d '{ "keyRingID": "new-key-ring" }'
Response
The base schema for patch key response body.
The metadata that describes the resource array.
An array of resources.
Status Code
Successful key update.
The request is missing a required field.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "...", "name": "Root-key", "description": "...", "state": 1, "extractable": false, "keyRingID": "new-key-ring-id", "crn": "...", "imported": false, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "AES", "algorithmMetadata": { "bitLength": 256, "mode": "CBC_PAD" }, "algorithmBitSize": 256, "algorithmMode": "CBC_PAD", "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ", "keyVersion": { "id": "...", "creationDate": "YYYY-MM-DDTHH:MM:SSZ" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "deleted": false } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: The 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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Delete a key
Deletes a key by specifying the ID of the key.
By default, Hyper Protect Crypto Services requires a single authorization to delete keys. For added protection, you can enable a dual authorization policy to safely delete keys from your service instance.
Note: By default, Hyper Protect Crypto Services blocks the deletion of a key that's protecting a cloud resource, such as a
Cloud Object Storage bucket. Use GET keys/{id}/registrations
to verify if the key has an active registration
to a resource. To delete the key and its associated registrations, set the optional force
parameter to true
.
DELETE /api/v2/keys/{id}
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.Alters server behavior for POST or DELETE operations. A header with
return=minimal
causes the service to return only the key identifier, or metadata. A header containingreturn=representation
returns 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 Services 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.
Query Parameters
If set to
true
, Hyper Protect Crypto Services forces deletion on a key that is protecting a cloud resource, such as a Cloud Object Storage bucket. The action removes any registrations that are associated with the key. Note: If a key is protecting a cloud resource that has a retention policy, Hyper Protect Crypto Services cannot delete the key. UseGET keys/{id}/registrations
to review registrations between the key and its associated cloud resources. To enable deletion, contact an account owner to remove the retention policy on each resource that is associated with this key.Default:
false
curl -X DELETE https://api.<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'
package main import ( "context" "encoding/json" "fmt" "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the key protect client as specified in Authentication delKey, err := api.DeleteKey(context.Background(), <key_ID>, kp.ReturnRepresentation) if err != nil { fmt.Println("Error while deleting: ", err) return } b, _ := json.MarshalIndent(delKey, "", " ") fmt.Println(string(b)) }
// Initialize the key protect client as specified in Authentication const deleteKeyParams = Object.assign({}, envConfigs); deleteKeyParams.id = "<key_ID>"; deleteKeyParams.prefer = 'return=representation'; const response = keyProtectClient.deleteKey(deleteKeyParams); console.log('Delete key response status: ' + response.status);
import os import keyprotect from keyprotect import bxauth # Initialize the key protect client as specified in Authentication deletedKey = kp.delete(<key_id>) print("Deleted key '%s'" % key_id)
Response
The base schema for deleting keys.
The metadata that describes the resource array.
A collection of resources.
Status Code
The key was successfully deleted.
The key was successfully deleted. No content.
The key cannot be deleted due to a malformed, invalid, or missing ID.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
Your service is not authorized to make this request. Ensure that an authorization exists between your service and Hyper Protect Crypto Services. Learn more
The key could not be found.
The key could not be deleted because it is protecting one or more cloud resources that have a retention policy. Use
GET /keys/{id}/registrations
to learn which resources this key is associated with. A registration with”preventKeyDeletion”: true
indicates that the associated resource has a retention policy. To enable deletion, contact an account owner to remove the retention policy on each resource that is associated with this key.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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "...", "name": "Root-key", "description": "...", "state": 5, "expirationDate": "YYYY-MM-DDTHH:MM:SSZ", "extractable": false, "crn": "...", "imported": false, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "AES", "algorithmMetadata": { "bitLength": 256, "mode": "CBC_PAD" }, "algorithmBitSize": 256, "algorithmMode": "CBC_PAD", "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ", "lastRotateDate": "YYYY-MM-DDTHH:MM:SSZ", "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "deleted": false, "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 credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Your service is not authorized to make this request. Ensure that an authorization exists between your service and Hyper Protect Crypto Services. [Learn more](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-integrate-services#grant-access)'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: The key could not be found." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": { "errorMsg": "Key could not be deleted. Please `reasons` for more details.", "reasons": [ { "code": "PREV_KEY_DEL_ERR", "message": "The key cannot be deleted because it's protecting a cloud resource that has a retention policy. Before you delete this key, contact an account owner to remove the retention policy on each resource that is associated with the key", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Purge a deleted key
Purge all key metadata and registrations associated with the specified key. Purge key can only be applied to a key in the Destroyed (5) state. After a key is deleted, there is a wait period of up to 4 hours before purge key operation is allowed.
Important: When you purge a key, you permanently shred its contents and associated data. The action cannot be reversed.
DELETE /api/v2/keys/{id}/purge
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.Alters server behavior for POST or DELETE operations. A header with
return=minimal
causes the service to return only the key identifier, or metadata. A header containingreturn=representation
returns 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 Services 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://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/purge -H 'accept: application/vnd.ibm.kms.key+json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
Response
The base schema for purged key.
The metadata that describes the resource array.
A collection of resources.
Status Code
The key was successfully purged.
The key was successfully purged. No content.
The key cannot be purged due to a malformed ID.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
Your service is not authorized to make this request. Ensure that an authorization exists between your service and Hyper Protect Crypto Services. Learn more
The key could not be found.
The key could not be purged because it is not in the Destroyed (5) state or purge is not allowed due to wait period of four hours has not been reached.
Too many requests. Please wait a few minutes and try again.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "...", "name": "Root-key", "description": "...", "state": 5, "extractable": false, "keyRingID": "default", "crn": "...", "imported": false, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "AES", "algorithmMetadata": { "bitLength": 256, "mode": "CBC_PAD" }, "algorithmBitSize": 256, "algorithmMode": "CBC_PAD", "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ", "lastRotateDate": "YYYY-MM-DDTHH:MM:SSZ", "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "deleted": true, "deletionDate": "YYYY-MM-DDTHH:MM:SSZ", "deletedBy": "...", "purgeAllowed": true, "purgeAllowedFrom": "YYYY-MM-DDTHH:MM:SSZ", "purgeScheduledOn": "YYYY-MM-DDTHH:MM:SSZ" } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: The key cannot be purged due to a malformed ID." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Your service is not authorized to make this request. Ensure that an authorization exists between your service and Hyper Protect Crypto Services. [Learn more](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-integrate-services#grant-access)'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: The key could not be found." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Key could not be purged. Please 'reasons' for more details", "reasons": [ { "code": "KEY_INVALID_STATE_ERR", "message": "Key is not in a valid state", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Restore a key
Restore a previously deleted key. You can only restore a key that was deleted within 30 days.
POST /api/v2/keys/{id}/restore
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.Alters server behavior for POST or DELETE operations. A header with
return=minimal
causes the service to return only the key identifier, or metadata. A header containingreturn=representation
returns 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 Services 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 POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/restore -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'content-type: application/vnd.ibm.kms.key_action_restore+json' -H 'x-kms-key-ring: <key_ring_ID>'
Response
Properties associated with a key response.
The metadata that describes the resource array.
A collection of resources.
Status Code
The key was successfully restored.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
The key could not be found.
The requested key is not in the
Destroyed
(5) state or the state of the key has changed within the last 30 seconds.Too many requests. Please wait a few minutes and try again.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "...", "name": "Root-key", "description": "...", "state": 1, "extractable": false, "keyRingID": "default", "crn": "...", "imported": true, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "AES", "algorithmMetadata": { "bitLength": 256, "mode": "CBC_PAD" }, "algorithmBitSize": 256, "algorithmMode": "CBC_PAD", "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ", "keyVersion": { "id": "...", "creationDate": "YYYY-MM-DDTHH:MM:SSZ" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "deleted": false } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Key could not be restored: Please see `reasons` for more details", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Key could not be restored: Please see `reasons` for more details", "reasons": [ { "code": "KEY_ACTION_INVALID_STATE_ERR", "message": "Key is not in a valid state", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Invoke an action on a key
Note: This API has been deprecated and transitioned to individual request paths. Existing actions using this API will continue to be supported,
but new actions will no longer be added to it. We recommend, if possible, aligning your request URLs to the new API path.
The generic format of actions (except restore key API) is now the following: /api/v2/keys/<key_ID>/actions/<action>
where key_ID
is the key you want to operate on/with and action
is the same action that was passed as
a query parameter previously.
Invokes an action on a specified key. This method supports the following actions:
wrap
: Use a root key to wrap or encrypt a data encryption keyunwrap
: Use a root key to unwrap or decrypt a data encryption keyrewrap
: Use a root key to rewrap or reencrypt a data encryption keyrotate
: Create a new version of a root keydisable
: Disable operations for a keyenable
: Enable operations for a keysetKeyForDeletion
: Authorize deletion for a key with a dual authorization policyunsetKeyForDeletion
: Remove an authorization for a key with a dual authorization policyrestore
: Restore a previously deleted 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 and latest key version in the response.
Use the latest ciphertext for future unwrap operations.
POST /api/v2/keys/{id}
Auditing
Calling this method generates the following auditing events.
hs-crypto.secrets.wrap
hs-crypto.secrets.unwrap
hs-crypto.secrets.rotate
hs-crypto.secrets.rewrap
hs-crypto.secrets.setkeyfordeletion
hs-crypto.secrets.unsetkeyfordeletion
hs-crypto.secrets.disable
hs-crypto.secrets.enable
hs-crypto.secrets.restore
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.Alters server behavior for POST or DELETE operations. A header with
return=minimal
causes the service to return only the key identifier, or metadata. A header containingreturn=representation
returns 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 Services 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.
Query Parameters
The action to perform on the specified key.
Allowable values: [
wrap
,unwrap
,rotate
,rewrap
,setKeyForDeletion
,unsetKeyForDeletion
,disable
,enable
,restore
]
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 anunwrap
action on a key. To wrap an existing DEK, provide a base64 encoded plaintext during awrap
action. To generate a new DEK, omit theplaintext
property. Hyper Protect Crypto Services generates a random plaintext (32 bytes) that is rooted in an HSM and then wraps that value. 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 forunwrap
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.Possible values: length ≤ 4096
curl -X POST https://api.<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>" }'
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>?action=unwrap -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 '{ "ciphertext": "<encrypted_data_key>" }'
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>?action=unwrap -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 '{ "ciphertext": "<encrypted_data_key>" }'
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>?action=rotate -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 '{ "payload": "<new_key_material>" }'
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>?action=disable -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'
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>?action=enable -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'
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>?action=restore -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -d '{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "payload": "<key_material>" } ] }'
package main import ( "context" "fmt" "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the key protect client as specified in Authentication plaintext := []byte(<data_key>) ciphertext, err := api.Wrap(context.Background(), <key_ID>, plaintext) if err != nil { fmt.Println("Error wrapping the key: ", err) return } fmt.Println(string(ciphertext)) }
package main import ( "context" "encoding/json" "fmt" "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the key protect client as specified in Authentication ciphertext := []byte(<encrypted_data_key>) pt2, err := api.Unwrap(context.Background(), <key_ID>, ciphertext) if err != nil { fmt.Println("Error while unwrapping DEK: ", err) return } b, _ := json.MarshalIndent(pt2, "", " ") fmt.Println(string(b)) }
package main import ( "context" "fmt" "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the key protect client as specified in Authentication // Set the payload to a base64 encoded string if your key is an imported root key // Skip setting payload if your key is a generated root key payload := "<new_key_material>" err = api.Rotate(context.Background(), <key_ID>, payload) if err != nil { fmt.Println("Error rotating the key: ", err) return } fmt.Println("Key successfully rotated") }
import os import keyprotect from keyprotect import bxauth # Initialize the key protect client as specified in Authentication # payload should be a bytestring if python3 message = b'This is a really important message.' wrapped = kp.wrap(key.get('id'), message) ciphertext = wrapped.get("ciphertext")
import os import keyprotect from keyprotect import bxauth # Initialize the key protect client as specified in Authentication unwrapped = kp.unwrap(key.get('<key_id>'), ciphertext) assert message == unwrapped
import os import keyprotect from keyprotect import bxauth # Initialize the key protect client as specified in Authentication rotatedKey = kp.rotate(key.get('<key_id>'), payload=<new_key_material>) print("Key successfully rotated")
Response
Properties that are associated with the response body of a wrap action.
The wrapped data encryption key (WDEK) that you can export to your app or service. The value is base64 encoded.
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 anunwrap
action on a key. To wrap an existing DEK, provide a base64 encoded plaintext during awrap
action. To generate a new DEK, omit theplaintext
property. Hyper Protect Crypto Services generates a random plaintext (32 bytes) that is rooted in an HSM and then wraps that value. 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 forunwrap
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.Possible values: length ≤ 4096
The key version that was used to wrap the DEK. This key version is associated with the
ciphertext
value that was used in the request.The ID of the key version.
Example:
4a0225e9-17a0-46c1-ace7-f25bcf4237d4
The date that the version of the key was created.
Example:
2010-01-12T05:23:19+0000
keyVersion
Status Code
Successful key operation.
The imported key was successfully restored.
Successful key operation.
Your authentication data or key is invalid, or the entity-body is missing a required field.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
Your service is not authorized to make this request. Ensure that an authorization exists between your service and Hyper Protect Crypto Services. Learn more
The key could not be found.
The key is not in an appropriate state, so the KeyAction has failed.
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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "plaintext": "tF9ss0W9HQUVkddcjSeGg/MqZFs2CVh/FFKLPLLnOwY=", "ciphertext": "eyJjaXBoZXJ0ZXh0Ijoic1ZZRnZVcjdQanZXQ0tFakMwRFFWZktqQ3AyRmtiOFJOSDJSTkpZRzVmU1hWNDJScDRDVythU0h3Y009IiwiaGFzaCI6IjVWNzNBbm9XdUxxM1BvZEZpd1AxQTdQMUZrTkZOajVPMmtmMkNxdVBxL0NRdFlOZnBvempiYUxjRDNCSWhxOGpKZ2JNR0xhMHB4dDA4cTYyc0RJMGRBPT0iLCJpdiI6Ilc1T2tNWFZuWDFCTERDUk51M05EUlE9PSIsInZlcnNpb24iOiIzLjAuMCIsImhhbmRsZSI6IjRkZjg5ZGVlLWU3OTMtNGY5Ny05MGNjLTc1ZWQ5YjZlNWM4MiJ9", "keyVersion": { "id": "..." } }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "...", "name": "Root-key", "description": "...", "state": 1, "extractable": false, "crn": "...", "imported": true, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "AES", "algorithmMetadata": { "bitLength": 256, "mode": "CBC_PAD" }, "algorithmBitSize": 256, "algorithmMode": "CBC_PAD", "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ", "keyVersion": { "id": "...", "creationDate": "YYYY-MM-DDTHH:MM:SSZ" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "deleted": false } ] }
{ "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 credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Your service is not authorized to make this request. Ensure that an authorization exists between your service and Hyper Protect Crypto Services. [Learn more](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-integrate-services#grant-access)'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: The key could not be found." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Conflict: The key is not in an appropriate state, so the KeyAction has failed." ] }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Wrap a key
Use a root key to wrap or encrypt a data encryption key.
POST /api/v2/keys/{id}/actions/wrap
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID that uniquely identifies the key.
The base request for wrap key action.
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 anunwrap
action on a key. To wrap an existing DEK, provide a base64 encoded plaintext during awrap
action. To generate a new DEK, omit theplaintext
property. Hyper Protect Crypto Services generates a random plaintext (32 bytes) that is rooted in an HSM and then wraps that value. 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 forunwrap
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.Possible values: length ≤ 4096
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/wrap -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'accept: application/vnd.ibm.kms.key_action_wrap+json' -H 'content-type: application/vnd.ibm.kms.key_action+json'
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/wrap -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'accept: application/vnd.ibm.kms.key_action_wrap+json' -H 'content-type: application/vnd.ibm.kms.key_action+json' -d '{ "plaintext": "<data_key>", }'
package main import ( "context" "fmt" "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the key protect client as specified in Authentication plaintext := []byte(<data_key>) ciphertext, err := api.Wrap(context.Background(), <key_ID>, plaintext) if err != nil { fmt.Println("Error wrapping the key: ", err) return } fmt.Println(string(ciphertext)) }
// Initialize the key protect client as specified in Authentication // Wrap and unwrap base64 encoded plaintext using key const samplePlaintext = 'dGhpcyBpcyBhIGJhc2U2NCBzdHJpbmcK'; // base64 encoded plaintext const wrapKeyParams = Object.assign({}, envConfigs); wrapKeyParams.id = "<key_id>"; wrapKeyParams.keyActionWrapBody = { plaintext: samplePlaintext, }; const response = keyProtectClient.wrapKey(wrapKeyParams); console.log('Wrap key response cipher: ' + response.result.ciphertext); const ciphertextResult = response.result.ciphertext; // saved for the unwrap example
import os import keyprotect from keyprotect import bxauth # Initialize the key protect client as specified in Authentication # payload should be a bytestring if python3 message = b'This is a really important message.' wrapped = kp.wrap(key.get('id'), message) ciphertext = wrapped.get("ciphertext")
Response
Properties that are associated with the response body of a wrap action.
The wrapped data encryption key (WDEK) that you can export to your app or service. The value is base64 encoded.
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 anunwrap
action on a key. To wrap an existing DEK, provide a base64 encoded plaintext during awrap
action. To generate a new DEK, omit theplaintext
property. Hyper Protect Crypto Services generates a random plaintext (32 bytes) that is rooted in an HSM and then wraps that value. 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 forunwrap
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.Possible values: length ≤ 4096
The key version that was used to wrap the DEK. This key version is associated with the
ciphertext
value that was used in the request.The ID of the key version.
Example:
4a0225e9-17a0-46c1-ace7-f25bcf4237d4
The date that the version of the key was created.
Example:
2010-01-12T05:23:19+0000
keyVersion
Status Code
The key was successfully wrapped.
The request is malformed or illegal.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
The key could not be found.
The key is not in the
Active
(1) state.The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using
POST /keys/{id}/restore
.Too many requests. Please wait a few minutes and try again.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "plaintext": "tF9ss0W9HQUVkddcjSeGg/MqZFs2CVh/FFKLPLLnOwY=", "ciphertext": "eyJjaXBoZXJ0ZXh0Ijoic1ZZRnZVcjdQanZXQ0tFakMwRFFWZktqQ3AyRmtiOFJOSDJSTkpZRzVmU1hWNDJScDRDVythU0h3Y009IiwiaGFzaCI6IjVWNzNBbm9XdUxxM1BvZEZpd1AxQTdQMUZrTkZOajVPMmtmMkNxdVBxL0NRdFlOZnBvempiYUxjRDNCSWhxOGpKZ2JNR0xhMHB4dDA4cTYyc0RJMGRBPT0iLCJpdiI6Ilc1T2tNWFZuWDFCTERDUk51M05EUlE9PSIsInZlcnNpb24iOiIzLjAuMCIsImhhbmRsZSI6IjRkZjg5ZGVlLWU3OTMtNGY5Ny05MGNjLTc1ZWQ5YjZlNWM4MiJ9", "keyVersion": { "id": "...", "creationDate": "2010-01-12T05:23:19+0000" } }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Wrap with key could not be performed: Please see `reasons` for more details", "reasons": [ { "code": "INVALID_FIELD_ERR", "message": "The field `plaintext` must be: a base64 encoded key material", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto", "target": { "type": "field", "name": "plaintext" } } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Wrap with key could not be performed: Please see `reasons` for more details", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Wrap with key could not be performed: Please see `reasons` for more details", "reasons": [ { "code": "KEY_ACTION_INVALID_STATE_ERR", "message": "Key is not in a valid state", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Wrap with key could not be performed: Please see `reasons` for more details", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Please delete references to this key", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Unwrap a key
Use a root key to unwrap or decrypt a data encryption 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 and latest key version in the response.
Use the latest ciphertext for future unwrap operations.
POST /api/v2/keys/{id}/actions/unwrap
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID that uniquely identifies the key.
The base request for unwrap key action.
The wrapped data encryption key (WDEK) that you can export to your app or service. The value is base64 encoded.
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/unwrap -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'accept: application/vnd.ibm.kms.key_action_unwrap+json' -H 'content-type: application/vnd.ibm.kms.key_action+json' -d '{ "ciphertext": "<encrypted_data_key>", }'
package main import ( "context" "fmt" "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the key protect client as specified in Authentication ciphertext := []byte(<encrypted_data_key>) pt2, err := api.Unwrap(context.Background(), <key_ID>, ciphertext) if err != nil { fmt.Println("Error while unwrapping DEK: ", err) return } b, _ := json.MarshalIndent(pt2, "", " ") fmt.Println(string(b)) }
// Initialize the key protect client as specified in Authentication const unwrapKeyParams = Object.assign({}, envConfigs); unwrapKeyParams.id = "<key_id>"; unwrapKeyParams.keyActionUnwrapBody = { ciphertext: ciphertextResult, // encrypted result from wrap key response }; const response = keyProtectClient.unwrapKey(unwrapKeyParams); console.log('Unwrap key response result: ' + response.result.plaintext); // validate that result is same as above
import os import keyprotect from keyprotect import bxauth # Initialize the key protect client as specified in Authentication unwrapped = kp.unwrap(key.get('<key_id>'), ciphertext) assert message == unwrapped
Response
Properties that are associated with the response body of an unwrap action.
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 anunwrap
action on a key. To wrap an existing DEK, provide a base64 encoded plaintext during awrap
action. To generate a new DEK, omit theplaintext
property. Hyper Protect Crypto Services generates a random plaintext (32 bytes) that is rooted in an HSM and then wraps that value. 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 forunwrap
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.Possible values: length ≤ 4096
The wrapped data encryption key (WDEK) that you can export to your app or service. The value is base64 encoded.
The key version that was used to wrap the DEK. This key version is associated with the
ciphertext
value that was used in the request.The ID of the key version.
Example:
4a0225e9-17a0-46c1-ace7-f25bcf4237d4
The date that the version of the key was created.
Example:
2010-01-12T05:23:19+0000
keyVersion
The latest key version that was used to rewrap the DEK. This key version is associated with the
ciphertext
value that's returned in the response.The ID of the key version.
Example:
4a0225e9-17a0-46c1-ace7-f25bcf4237d4
The date that the version of the key was created.
Example:
2010-01-12T05:23:19+0000
rewrappedKeyVersion
Status Code
Successfully unwrapped key.
The request is malformed or illegal.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
The key could not be found.
The key is not in the
Active
(1) orDeactivated
(3) state.The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using
POST /keys/{id}/restore
.The ciphertext provided was not wrapped by this key.
Too many requests. Please wait a few minutes and try again.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "plaintext": "tF9ss0W9HQUVkddcjSeGg/MqZFs2CVh/FFKLPLLnOwY=", "keyVersion": { "id": "...", "creationDate": "2010-01-12T05:23:19+0000" } }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Unwrap with key could not be performed: Please see `reasons` for more details", "reasons": [ { "code": "MISSING_FIELD_ERR", "message": "The field `ciphertext` is required", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto", "target": { "type": "field", "name": "name" } } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Unwrap with key could not be performed: Please see `reasons` for more details", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Wrap action could not be performed with the key: Please see `reasons` for more details", "reasons": [ { "code": "KEY_ACTION_INVALID_STATE_ERR", "message": "Key is not in a valid state", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Unwrap with key could not be performed: Please see `reasons` for more details", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Please delete references to this key", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unprocessable Entity: Unwrap with key could not be performed: Please see `reasons` for more details", "reasons": [ { "code": "UNPROCESSABLE_CIPHERTEXT_ERR", "message": "The provided ciphertext is invalid or corrupted", "status": 422, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Rewrap a key
Use a root key to rewrap or reencrypt a data encryption key.
POST /api/v2/keys/{id}/actions/rewrap
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID that uniquely identifies the key.
The base request for rewrap key action.
The wrapped data encryption key (WDEK) that you want to re-encrypt by using the latest key version. The value must be base64 encoded.
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/rewrap -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'accept: application/vnd.ibm.kms.key_action_rewrap+json' -H 'content-type: application/vnd.ibm.kms.key_action+json' -d '{ "ciphertext": "<encrypted_data_key>", }'
Response
Properties that are associated with the response body of an rewrap action.
The wrapped data encryption key (WDEK) that you can export to your app or service. The value is base64 encoded.
The key version that was used to wrap the DEK. This key version is associated with the
ciphertext
value that was used in the request.The ID of the key version.
Example:
4a0225e9-17a0-46c1-ace7-f25bcf4237d4
The date that the version of the key was created.
Example:
2010-01-12T05:23:19+0000
keyVersion
The latest key version that was used to rewrap the DEK. This key version is associated with the
ciphertext
value that's returned in the response.The ID of the key version.
Example:
4a0225e9-17a0-46c1-ace7-f25bcf4237d4
The date that the version of the key was created.
Example:
2010-01-12T05:23:19+0000
rewrappedKeyVersion
Status Code
The key was successfully rewrapped.
The request is malformed or illegal.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
The key could not be found.
The key is not in the
Active
(1) orDeactivated
(3) state.The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using
POST /keys/{id}/restore
.The ciphertext provided was not wrapped by this key.
Too many requests. Please wait a few minutes and try again.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "ciphertext": "eyJjaXBoZXJ0ZXh0Ijoic1ZZRnZVcjdQanZXQ0tFakMwRFFWZktqQ3AyRmtiOFJOSDJSTkpZRzVmU1hWNDJScDRDVythU0h3Y009IiwiaGFzaCI6IjVWNzNBbm9XdUxxM1BvZEZpd1AxQTdQMUZrTkZOajVPMmtmMkNxdVBxL0NRdFlOZnBvempiYUxjRDNCSWhxOGpKZ2JNR0xhMHB4dDA4cTYyc0RJMGRBPT0iLCJpdiI6Ilc1T2tNWFZuWDFCTERDUk51M05EUlE9PSIsInZlcnNpb24iOiIzLjAuMCIsImhhbmRsZSI6IjRkZjg5ZGVlLWU3OTMtNGY5Ny05MGNjLTc1ZWQ5YjZlNWM4MiJ9", "keyVersion": { "id": "...", "creationDate": "2010-01-12T05:23:19+0000" }, "rewrappedKeyVersion": { "id": "...", "creationDate": "2010-01-12T05:23:19+0000" } }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Rewrap with key could not be performed: Please see `reasons` for more details", "reasons": [ { "code": "INVALID_FIELD_ERR", "message": "The field `ciphertext` must be: the original base64 encoded ciphertext from the wrap operation", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto", "target": { "type": "field", "name": "ciphertext" } } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Rewrap with key could not be performed: Please see `reasons` for more details", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Rewrap with key could not be performed: Please see `reasons` for more details", "reasons": [ { "code": "KEY_ACTION_INVALID_STATE_ERR", "message": "Key is not in a valid state", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Rewrap with key could not be performed: Please see `reasons` for more details", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Please delete references to this key", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unprocessable Entity: Rewrap with key could not be performed: Please see `reasons` for more details", "reasons": [ { "code": "UNPROCESSABLE_CIPHERTEXT_ERR", "message": "The provided ciphertext is invalid or corrupted", "status": 422, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.Alters server behavior for POST or DELETE operations. A header with
return=minimal
causes the service to return only the key identifier, or metadata. A header containingreturn=representation
returns 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 Services 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.
The base request for rotate key action.
The key material that you want to import into the service for rotating an existing root key. This value is required for a
rotate
action 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 Services, omit thepayload
property and pass in an empty request entity-body.
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/rotate -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'accept: application/vnd.ibm.kms.key_action_rotate+json' -H 'content-type: application/vnd.ibm.kms.key_action+json' \
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/rotate -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'accept: application/vnd.ibm.kms.key_action_rotate+json' -H 'content-type: application/vnd.ibm.kms.key_action+json' -d '{ "payload": "<new_key_material>", }'
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/rotate -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'accept: application/vnd.ibm.kms.key_action_rotate+json' -H 'content-type: application/vnd.ibm.kms.key_action+json' -d '{ "payload": "<encrypted_new_key_material>", "encryptedNonce": "<encrypted_nonce>", "iv": "<iv>", "encryptionAlgorithm": "RSAES_OAEP_SHA_1" }'
package main import ( "context" "fmt" "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the key protect client as specified in Authentication //Set the payload to a base64 encoded string if your key is an imported root key //Skip setting payload if your key is a generated root key payload := "<new_key_material>" err = api.Rotate(context.Background(), <key_ID>, payload) if err != nil { fmt.Println("Error rotating the key: ", err) return } fmt.Println("Key successfully rotated") }
import os import keyprotect from keyprotect import bxauth # Initialize the key protect client as specified in Authentication rotatedKey = kp.rotate(key.get('<key_id>'), payload=<new_key_material>) print("Key successfully rotated")
Response
Status Code
The key was successfully rotated. No content.
The request is malformed or illegal.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
The key could not be found.
The requested key is not in the
Active
(1) state or has been rotated within the last hour.The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using
POST /keys/{id}/restore
.Too many requests. Please wait a few minutes and try again.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Key could not be rotated: Please see `reasons` for more details", "reasons": [ { "code": "INVALID_FIELD_ERR", "message": "The field `payload` must be: a base64 encoded value", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto", "target": { "type": "field", "name": "payload" } } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Key could not be rotated: Please see `reasons` for more details", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Key could not be rotated: Please see `reasons` for more details", "reasons": [ { "code": "KEY_ACTION_INVALID_STATE_ERR", "message": "Key is not in a valid state", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Key could not be rotated: Please see `reasons` for more details", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Please delete references to this key", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Set a key for deletion
Authorize deletion for a key with a dual authorization policy.
POST /api/v2/keys/{id}/actions/setKeyForDeletion
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID that uniquely identifies the key.
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/setKeyForDeletion -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
Response
Status Code
The key was successfully set for deletion. No content.
The request is missing a required field.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
The key could not be found.
The key does not have a dual-authorization delete policy.
The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using
POST /keys/{id}/restore
.Too many requests. Please wait a few minutes and try again.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Key deletion could not be scheduled: Please see `reasons` for more details", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Key deletion could not be scheduled: Please see `reasons` for more details", "reasons": [ { "code": "NOT_DUAL_AUTH_ERR", "message": "The key is not dual auth enabled and cannot be set for deletion", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Key deletion could not be scheduled: Please see `reasons` for more details", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Please delete references to this key", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Unset a key for deletion
Remove an authorization for a key with a dual authorization policy.
POST /api/v2/keys/{id}/actions/unsetKeyForDeletion
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID that uniquely identifies the key.
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/unsetKeyForDeletion -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
Response
Status Code
The key was successfully unset for deletion. No content.
The request is missing a required field.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
The key could not be found.
The key does not have a dual-authorization delete policy.
The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using
POST /keys/{id}/restore
.Too many requests. Please wait a few minutes and try again.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Key deletion could not be cancelled: Please see `reasons` for more details", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Key deletion could not be cancelled: Please see `reasons` for more details", "reasons": [ { "code": "NOT_DUAL_AUTH_ERR", "message": "The key is not dual auth enabled and cannot be set for deletion", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Key deletion could not be cancelled: Please see `reasons` for more details", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Please delete references to this key", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID that uniquely identifies the key.
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/enable -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
Response
Status Code
The key was successfully enabled. No content.
The request is malformed or illegal.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
The key could not be found.
The requested key is not in the
Active
(1) state or the state of the key has changed within the last 30 seconds.The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using
POST /keys/{id}/restore
.Too many requests. Please wait a few minutes and try again.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Key could not be enabled: Please see `reasons` for more details", "reasons": [ { "code": "KEY_ROOT_REQ_ERR", "message": "Requested action can only be completed with a root key", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Key could not be enabled: Please see `reasons` for more details", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Key could not be enabled: Please see `reasons` for more details", "reasons": [ { "code": "KEY_ACTION_INVALID_STATE_ERR", "message": "Key is not in a valid state", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Key could not be enabled: Please see `reasons` for more details", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Please delete references to this key", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID that uniquely identifies the key.
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/disable -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
Response
Status Code
The key was successfully disabled. No content.
The request is malformed or illegal.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
The key could not be found.
The requested key is not in the
Suspended
(2) state.The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using
POST /keys/{id}/restore
.Too many requests. Please wait a few minutes and try again.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Key could not be disabled: Please see `reasons` for more details", "reasons": [ { "code": "KEY_ROOT_REQ_ERR", "message": "Requested action can only be completed with a root key", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Key could not be disabled: Please see `reasons` for more details", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Key could not be disabled: Please see `reasons` for more details", "reasons": [ { "code": "KEY_ACTION_INVALID_STATE_ERR", "message": "Key is not in a valid state", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Key could not be disabled: Please see `reasons` for more details", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Please delete references to this key", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Sync associated resources
Initiate a manual data synchronization request to the associated
resources of a key. Regular key lifecycle events automatically notify
integrated services of the change, however, in the case a service does
not respond to a key lifecycle event notification, the sync
API may be
used to initiate a renotification to the integrated services that manage
the associated resources linked to the key.
Note: The services that manage the associated resources linked to
the key are responsible for maintaining up-to-date records of the key
state and version. Hyper Protect Crypto Services does not have the ability to force data
synchronization for other services. The sync
API is purely to
initiate a request for all associated resources to synchronize their
key records with what the key management service API returns.
POST /api/v2/keys/{id}/actions/sync
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID that uniquely identifies the key.
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/sync -H 'accept: application/json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
Response
Status Code
The sync of associate resources for a key has been initiated. No content.
The request is malformed or illegal.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
The key could not be found.
The key has been synced or updated (i.e. rotated, restored, disabled, enabled, deleted) within the last hour.
Too many requests. Please wait a few minutes and try again.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Associated resources could not be synced: Please see 'reasons' for more details", "reasons": [ { "code": "KEY_ROOT_REQ_ERR", "message": "Requested action can only be completed with a root key", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Associated resources could not be synced: Please see 'reasons' for more details", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Associated resources could not be synced: Please see 'reasons' for more details", "reasons": [ { "code": "REQ_TOO_EARLY_ERR", "message": "The key was updated recently: Please wait and try again", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID that uniquely identifies the key.
An alias that identifies a key. Each alias is unique only within the given instance and is not reserved across the Key Protect service. Each key can have up to five aliases. There is a limit of 1000 aliases per instance. Alias must be alphanumeric and cannot contain spaces or special characters other than '-' or '_'.
The alias cannot be a version 4 UUID and must not be a Hyper Protect Crypto Services reserved name:
allowed_ip
,key
,keys
,metadata
,policy
,policies
,registration
,registrations
,ring
,rings
,rotate
,wrap
,unwrap
,rewrap
,version
,versions
. Alias size can be between 2 - 90 characters.
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/aliases/<alias> -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'content-type: application/json'
Response
Properties associated with a specific key alias.
The metadata that describes the resource array.
A collection of resources.
Status Code
An identical alias was previously created for the specified key.
A new alias was successfully created.
The alias could not be created due to a malformed
alias
or an invalid key IDYour credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
The key with specified ID could not be found.
The alias is already associated with a key in the kms.
The alias quota for this key or instance has been reached and alias can not be created.
Too many requests. Please wait a few minutes and try again.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Alias could not be created. Please see 'reasons' for more details", "reasons": [ { "code": "INVALID_PATH_PARAM_ERR", "message": "The path_param 'alias' must be: alphanumeric, and no spaces or special characters other than '-' or '_', and can not be a version 4 UUID", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto", "target": { "type": "path_param", "name": "aliases" } } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Alias could not be created. Please see 'reasons' for more details", "reasons": [ { "code": "KEY_NOT_FOUND", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Key alias could not be created: Please see 'reasons' for more details", "reasons": [ { "code": "KEY_ALIAS_NOT_UNIQUE_ERR", "message": "One or more aliases are already associated with a key in the instance", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Delete an alias
Deletes an alias from the associated key.
Delete alias does not delete the key.
DELETE /api/v2/keys/{id}/aliases/{alias}
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID that uniquely identifies the key.
An alias that identifies a key. Each alias is unique only within the given instance and is not reserved across the Key Protect service. Each key can have up to five aliases. There is a limit of 1000 aliases per instance. Alias must be alphanumeric and cannot contain spaces or special characters other than '-' or '_'.
The alias cannot be a version 4 UUID and must not be a Hyper Protect Crypto Services reserved name:
allowed_ip
,key
,keys
,metadata
,policy
,policies
,registration
,registrations
,ring
,rings
,rotate
,wrap
,unwrap
,rewrap
,version
,versions
. Alias size can be between 2 - 90 characters.
curl -X DELETE https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/aliases/<alias> -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'content-type: application/json'
Response
Status Code
An alias was successfully deleted. No content.
The alias could not be deleted due to a malformed
alias
or an invalid key ID.Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
The alias with specified key ID could not be found.
Too many requests. Please wait a few minutes and try again.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Alias could not be deleted. Please see 'reasons' for more details", "reasons": [ { "code": "INVALID_PATH_PARAM_ERR", "message": "The param 'alias' must be: alphanumeric, and no spaces or special characters other than '-' or '_', and can not be a version 4 UUID", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto", "target": { "type": "param", "name": "aliases" } } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Alias could not be deleted. Please see 'reasons' for more details", "reasons": [ { "code": "ALIAS_NOT_FOUND", "message": "Alias does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
curl -X GET https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/key_rings -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
Response
The base schema for listing key rings.
The metadata that describes the resource array.
A collection of resources.
Status Code
The list of key rings was successfully retrieved.
The request is missing a required field.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
Too many requests. Please wait a few minutes and try again.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key_ring+json", "collectionTotal": 3 }, "resources": [ { "id": "default" }, { "id": "example-key-ring", "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "..." }, { "id": "key-ring-name-2", "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "..." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Create a key ring
Create a key ring in the instance with the specified name. The key ring ID default
is a reserved key ring ID and cannot be created or destroyed. The default key ring is an initial key ring that is generated with each newly created instance. All keys not associated with a specified key ring exist within the default key ring.
POST /api/v2/key_rings/{key-ring-id}
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
Path Parameters
The ID that identifies the key ring. Each ID is unique only within the given instance and is not reserved across the Hyper Protect Crypto Services service.
Possible values: 2 ≤ length ≤ 100, Value must match regular expression
^[a-zA-Z0-9-]*$
curl -X POST https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/key_rings/<key_ring_id> -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
Response
Status Code
The key ring was successfully created.
The key ring already exists. No content.
The key ring could not be created due to invalid request data.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
Key ring resource quota has been reached.
Too many requests. Please wait a few minutes and try again.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Key ring could not be created. Please see `reasons` for more details.", "reasons": [ { "code": "INVALID_PATH_PARAM_ERR", "message": "The path_param `id` must be: a string matching pattern `^[a-zA-Z0-9-]*$`", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto", "target": { "type": "path_param`", "name": "key-ring-id" } } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Key ring could not be created. Please see `reasons` for more details.", "reasons": [ { "code": "KEY_RING_RESOURCE_QUOTA_ERR", "message": "The resource quota for key rings in this instance has been reached/exceeded and key rings cannot be created", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Delete a key ring
Delete the key ring from the instance. key ring ID default
cannot be deleted. Currently, only key rings with 0 (zero) keys, in any state [Active (1), Suspended (2), Deactivated (3), Destroyed (5)], may be deleted.
DELETE /api/v2/key_rings/{key-ring-id}
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
Path Parameters
The ID that identifies the key ring. Each ID is unique only within the given instance and is not reserved across the Hyper Protect Crypto Services service.
Possible values: 2 ≤ length ≤ 100, Value must match regular expression
^[a-zA-Z0-9-]*$
curl -X DELETE https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/key_rings/<key_ring_id> -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
Response
Status Code
The key ring was successfully deleted. No content.
The key ring could not be deleted due to invalid request data.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
The specified key ring contains at least one key (in any state)
Too many requests. Please wait a few minutes and try again.
IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Key ring could not be created. Please see `reasons` for more details.", "reasons": [ { "code": "INVALID_PATH_PARAM_ERR", "message": "The path_param `id` must be: a string matching pattern `^[a-zA-Z0-9-]*$`", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto", "target": { "type": "path_param`", "name": "key-ring-id" } } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Key ring could not be created. Please see `reasons` for more details.", "reasons": [ { "code": "KEY_RING_NOT_EMPTY_ERR", "message": "The specified key ring contains at least one key (in any state)", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] }
{ "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'" ] }
Set key policies
Creates or updates one or more policies for the specified key.
You can set policies for a key, such as an automatic rotation policy or a dual authorization policy to protect against the accidental deletion of keys. Use PUT /keys/{id}/policies
to create new policies for a key or update an existing policy.
PUT /api/v2/keys/{id}/policies
Request
Custom Headers
The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID that uniquely identifies the key.
Query Parameters
The type of policy that is associated with the specified key.
Allowable values: [
dualAuthDelete
,rotation
]
The base request for key policy create or update.
A collection of resources.
Specifies the MIME type that represents the policy resource. Currently, only the default is supported.
Allowable values: [
application/vnd.ibm.kms.policy+json
]Example:
application/vnd.ibm.kms.policy+json
Data associated with the dual authorization delete policy.
If set to
true
, Hyper Protect Crypto Services enables a dual authorization policy on a single key. After you enable the policy, Hyper Protect Crypto Services requires an authorization from two users to delete this key. For example, you can authorize the deletion first by using the SetKeyForDeletion action. Then, a different user provides a second authorization implicitly by callingDELETE /keys
to delete the key. Note: Once the dual authorization policy is set on the key, it cannot be reverted.Example:
true
dualAuthDelete
Specifies the key rotation time interval in months, with a minimum of 1, and a maximum of 12.
Specifies the key rotation time interval in months
Possible values: 1 ≤ value ≤ 12
Example:
1
rotation
resources
curl -X PUT https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/policies -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'content-type: application/vnd.ibm.kms.policy+json' -d '{ "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 2 }, "resources": [ { "type": "application/vnd.ibm.kms.policy+json", "rotation": { "interval_month": <rotation_interval> } }, { "type": "application/vnd.ibm.kms.policy+json", "dualAuthDelete": { "enabled": <true|false> } } ] }'
curl -X PUT https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/policies?policy=dualAuthDelete -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'content-type: application/vnd.ibm.kms.policy+json' -d '{ "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.policy+json", "dualAuthDelete": { "enabled": <true|false> } } ] }'
curl -X PUT https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/policies?policy=rotation -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'content-type: application/vnd.ibm.kms.policy+json' -d '{ "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.policy+json", "rotation": { "interval_month": <rotation_interval> } } ] }'
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the key protect client as specified in Authentication policy, err := api.SetPolicy(context.Background(), <key_ID>, kp.ReturnRepresentation, <rotation_interval>) if err != nil { fmt.Println("Error while creating policies: ", err) return } b, _ := json.MarshalIndent(policy, "", " ") fmt.Println(string(b)) }
Response
The base schema for retrieving all key policies.
A collection of resources.
The v4 UUID used to uniquely identify the policy resource, as specified by RFC 4122.
Specifies the MIME type that represents the policy resource. Currently, only the default is supported.
Possible values: [
application/vnd.ibm.kms.policy+json
]Example:
application/vnd.ibm.kms.policy+json
The Cloud Resource Name (CRN) that uniquely identifies your cloud resources.
Example:
crn:v1:bluemix:public:hs-crypto:<region>:a/<account-id>:<service-instance:policy:<policy-id>
The date the policy was created. The date format follows RFC 3339.
Example:
2010-01-1
resources