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.

API endpoint

Use the Retrieve the API endpoint URL method first to retrieve the URL for the dedicated API endpoint for key management operations. The endpoint 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/

Sydney:

https://au-syd.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 following endpoint URL that is returned by calling the Retrieve the API endpoint URL method:

https://api.<region>.hs-crypto.cloud.ibm.com:<port>

Tips:

  • You need to call the Retrieve the API endpoint URL API first so as to retrieve the endpoint URL of the other APIs.
  • 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.

API endpoint

Use the Retrieve the API endpoint URL method first to retrieve the URL for the dedicated API endpoint for key management operations. The endpoint 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/

Sydney:

https://au-syd.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 following endpoint URL that is returned by calling the Retrieve the API endpoint URL method:

https://api.<region>.hs-crypto.cloud.ibm.com:<port>

Tips:

  • You need to call the Retrieve the API endpoint URL API first so as to retrieve the endpoint URL of the other APIs.
  • 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.

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

API endpoint

Use the Retrieve the API endpoint URL method first to retrieve the URL for the dedicated API endpoint for key management operations. The endpoint 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/

Sydney:

https://au-syd.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 following endpoint URL that is returned by calling the Retrieve the API endpoint URL method:

https://api.<region>.hs-crypto.cloud.ibm.com:<port>

Tips:

  • You need to call the Retrieve the API endpoint URL API first so as to retrieve the endpoint URL of the other APIs.
  • 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.

The code examples on this tab use the client library that is provided for Python.

pip install -U keyprotect

GitHub

API endpoint

Use the Retrieve the API endpoint URL method first to retrieve the URL for the dedicated API endpoint for key management operations. The endpoint 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/

Sydney:

https://au-syd.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 following endpoint URL that is returned by calling the Retrieve the API endpoint URL method:

https://api.<region>.hs-crypto.cloud.ibm.com:<port>

Tips:

  • You need to call the Retrieve the API endpoint URL API first so as to retrieve the endpoint URL of the other APIs.
  • 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.

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

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 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 managemwent 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 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 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 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 key management 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")
)

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.

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.

Event tracking

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 summary
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.

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/
  • Sydney: https://au-syd.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 public or private endpoint, choose the proper endpoint URL in the kms section returned for all API methods in this API reference doc.

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))
    }
  • 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

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.

Example responses
  • {
      "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.'"
      ]
    }

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • hs-crypto.secrets.create

Auditing

Calling this method generates the following event for the Activity Tracker with LogDNA service.

  • hs-crypto.secrets.create

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 containing return=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 subsequent GET /keys/{id} request.

    Allowable values: [return=representation,return=minimal]

The base request for creating a new key.

Example:
  • 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'   -d '{
        "metadata": {
          "collectionType": "application/vnd.ibm.kms.key+json",
          "collectionTotal": 1
        },
        "resources": [
        {
          "type": "application/vnd.ibm.kms.key+json",
          "name": "Root-key",
          "description": "...",
          "extractable": false
          }
        ]
      }'
  • package main
    
    import (
    "context"
    "encoding/json"
    "fmt"
    
    "github.com/IBM/keyprotect-go-client" )
    
    func main() {
    
      // Initialize the key management service 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))
    }
  • import os
    import keyprotect
    from keyprotect import bxauth
    # Initialize the key management service client as specified in Authentication
    key = kp.create(name="<key_name>")
    print("Created key '%s'" % key['id'])
  • 
    //Initialize the key management service 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.

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 or expirationDate, and it is no longer available for operations. To create a new import token, use POST /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 to 409 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.

Example responses
  • {
      "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.'"
      ]
    }

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • hs-crypto.secrets.list

Auditing

Calling this method generates the following event for the Activity Tracker with LogDNA service.

  • hs-crypto.secrets.list

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.

Query Parameters

  • The number of keys to retrieve. By default, GET /keys returns the first 200 keys. To retrieve a different set of keys, use limit with offset to page through your available resources. The maximum value for limit 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.

    Constraints: 1 ≤ value ≤ 5000

    Default: 200

  • The number of keys to skip. By specifying offset, you retrieve a subset of keys that starts with the offset value. Use offset with limit 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.

    Constraints: 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]

  • 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 management service 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))
      }
  • import os
    import keyprotect
    from keyprotect import bxauth
    # Initialize the key management service client as specified in Authentication
    keys = kp.keys()
    for key in kp.keys():
      print("%s\t%s" % (key["id"], key["name"]))
  • 
    //Initialize the key management service 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.

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.

Example responses
  • {
      "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.'"
      ]
    }

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • hs-crypto.secrets.head

Auditing

Calling this method generates the following event for the Activity Tracker with LogDNA service.

  • hs-crypto.secrets.head

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.

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]

  • 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 of the key.

GET /api/v2/keys/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • hs-crypto.secrets.read

Auditing

Calling this method generates the following event for the Activity Tracker with LogDNA service.

  • hs-crypto.secrets.read

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 v4 UUID that uniquely identifies the key.

  • curl GET   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 management service 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))
      }
  • import os
    import keyprotect
    from keyprotect import bxauth
    # Initialize the key management service client as specified in Authentication
    key = kp.get('id')
    print("%s\t%s" % (key["id"], key["name"]))

Response

The base schema for retrieving keys.

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.

Example responses
  • {
      "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.'"
      ]
    }

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.

Important: When you delete a key, you permanently shred its contents and associated data. The action cannot be reversed.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • hs-crypto.secrets.delete

Auditing

Calling this method generates the following event for the Activity Tracker with LogDNA service.

  • hs-crypto.secrets.delete

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 containing return=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 subsequent GET /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. Use GET 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 management service 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))
    }
  • import os
    import keyprotect
    from keyprotect import bxauth
    # Initialize the key management service client as specified in Authentication
    deletedKey = kp.delete(<key_id>)
    print("Deleted key '%s'" % key_id)

Response

The base schema for deleting keys.

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.

Example responses
  • {
      "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.'"
      ]
    }

Retrieve key metadata

Retrieves the details of a key by specifying the ID of the key.

GET /api/v2/keys/{id}/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.

Path Parameters

  • The v4 UUID that uniquely identifies the key.

  • curl GET   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/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.

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.

Example responses
  • {
      "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.'"
      ]
    }

Restore a Key

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.

  • 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 containing return=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 subsequent GET /keys/{id} request.

    Allowable values: [return=representation,return=minimal]

Path Parameters

  • The v4 UUID that uniquely identifies the key.

The base request for restore key action.

Example:
  • 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'   -d '{
        "metadata": {
          "collectionType": "application/vnd.ibm.kms.key_action_restore+json",
          "collectionTotal": 1
        },
        "resources": [
          {
            "payload": "<key_material>"
          }
        ]
      }'
  • 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'   -d '{
        "metadata": {
          "collectionType": "application/vnd.ibm.kms.key_action_restore+json",
          "collectionTotal": 1
        },
        "resources": [
          {
            "payload": "<encrypted_key_material>",
            "encryptedNonce": "<encrypted_nonce>",
            "iv": "<iv>",
            "encryptionAlgorithm": "RSAES_OAEP_SHA_256"
          }
        ]
      }'

Response

Properties associated with a key response.

Status Code

  • The key was successfully restored.

  • 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 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.

Example responses
  • {
      "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: Key could not be restored: Please see `reasons` for more details",
          "reasons": [
            {
              "code": "INVALID_FIELD_ERR",
              "message": "The field `payload` must be: of length 16, 24, 32 bytes When using secure import token, payload size must be of length 512 bytes: Supplied payload has length 18",
              "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: 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.'"
      ]
    }

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.

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, use limit with offset to page through your available resources. The maximum value for limit 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.

    Constraints: 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 the offset value. Use offset with limit 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.

    Constraints: 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.

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.

Example responses
  • {
      "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.'"
      ]
    }

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:

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > name > Access policies.

  • 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

Auditing

Calling this method generates the following events for the Activity Tracker with LogDNA service.

  • 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.

  • 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 containing return=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 subsequent GET /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.

Example:
  • 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 management service 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 management service 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 management service 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 management service 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 management service 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 management service 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.

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.

Example responses
  • {
      "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

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.

Path Parameters

  • The v4 UUID that uniquely identifies the key.

The base request for wrap key action.

Example:
  • 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 management service 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))
    }
  • import os
    import keyprotect
    from keyprotect import bxauth
    # Initialize the key management service 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.

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.

Example responses
  • {
      "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.

Path Parameters

  • The v4 UUID that uniquely identifies the key.

The base request for unwrap key action.

Example:
  • 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 management service 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))
    }
  • import os
    import keyprotect
    from keyprotect import bxauth
    # Initialize the key management service 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.

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) or Deactivated (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.

Example responses
  • {
      "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

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.

Path Parameters

  • The v4 UUID that uniquely identifies the key.

The base request for rewrap key action.

Example:
  • 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.

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) or Deactivated (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.

Example responses
  • {
      "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.'"
      ]
    }

Rotate a Key

Create a new version of a root key.

POST /api/v2/keys/{id}/actions/rotate

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 containing return=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 subsequent GET /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.

Example:
  • 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_256"
      }'
  • package main
    import (
     "context"
     "fmt"
     "github.com/IBM/keyprotect-go-client"
    )
    func main() {
      // Initialize the key management service 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 management service 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.

Example responses
  • {
      "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.

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.

Example responses
  • {
      "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.

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.

Example responses
  • {
      "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.'"
      ]
    }

Enable a Key

Enable operations for a key.

POST /api/v2/keys/{id}/actions/enable

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 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.

Example responses
  • {
      "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.'"
      ]
    }

Disable a Key

Disable operations for a key.

POST /api/v2/keys/{id}/actions/disable

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 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.

Example responses
  • {
      "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.'"
      ]
    }

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • hs-crypto.policies.write

Auditing

Calling this method generates the following event for the Activity Tracker with LogDNA service.

  • hs-crypto.policies.write

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 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.

Example:
  • 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 management service 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.

Status Code

  • The policy or policies were successfully created or updated.

  • The policy or policies were successfully created or updated. No content.

  • The policy or policies cannot be created or updated 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 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.

Example responses
  • Example response of multiple key policies

    {
      "metadata": {
        "collectionType": "application/vnd.ibm.kms.policy+json",
        "collectionTotal": 2
      },
      "resources": [
        {
          "id": "...",
          "crn": "...",
          "rotation": {
            "interval_month": 3
          },
          "createdBy": "...",
          "creationDate": "...",
          "updatedBy": "...",
          "lastUpdateDate": "..."
        },
        {
          "id": "...",
          "crn": "...",
          "dualAuthDelete": {
            "enabled": "<true|false>"
          },
          "createdBy": "...",
          "creationDate": "...",
          "updatedBy": "...",
          "lastUpdateDate": "..."
        }
      ]
    }
  • Example response of dual authorization policy

    {
      "metadata": {
        "collectionType": "application/vnd.ibm.kms.policy+json",
        "collectionTotal": 1
      },
      "resources": [
        {
          "id": "...",
          "crn": "...",
          "dualAuthDelete": {
            "enabled": "<true|false>"
          },
          "createdBy": "...",
          "creationDate": "...",
          "updatedBy": "...",
          "lastUpdateDate": "..."
        }
      ]
    }
  • Example response of key rotation policy

    {
      "metadata": {
        "collectionType": "application/vnd.ibm.kms.policy+json",
        "collectionTotal": 1
      },
      "resources": [
        {
          "id": "...",
          "crn": "...",
          "rotation": {
            "interval_month": 3
          },
          "createdBy": "...",
          "creationDate": "...",
          "updatedBy": "...",
          "lastUpdateDate": "..."
        }
      ]
    }
  • {
      "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: '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.'"
      ]
    }

List key policies

Retrieves a list of policies that are associated with a 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 GET /keys/{id}/policies to browse the policies that exist for a specified key.

GET /api/v2/keys/{id}/policies

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • hs-crypto.policies.read

Auditing

Calling this method generates the following event for the Activity Tracker with LogDNA service.

  • hs-crypto.policies.read

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 v4 UUID that uniquely identifies the key.

Query Parameters

  • The type of policy that is associated with the specified key.

    Allowable values: [dualAuthDelete,rotation]

  • curl GET   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 'accept: application/vnd.ibm.kms.policy+json'
  • curl GET   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 'accept: application/vnd.ibm.kms.policy+json'
  • curl GET   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 'accept: application/vnd.ibm.kms.policy+json'
  • package main
    
    import (
      "context"
      "encoding/json"
      "fmt"
    
      kp "github.com/IBM/keyprotect-go-client"
    )
    
    func main() {
    
      // Initialize the key management service client as specified in Authentication
    
      policy, err := api.GetPolicy(context.Background(), <key_ID>)
      if err != nil {
        fmt.Println("Error while getting policies: ", err)
        return
      }
    
      b, _ := json.MarshalIndent(policy, "", "  ")
      fmt.Println(string(b))
    }

Response

The base schema for retrieving all key policies.

Status Code

  • The policy resources were successfully retrieved.

  • The request is missing a required field or contains invalid values.

  • 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.

  • 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.

Example responses
  • Example response of multiple key policies

    {
      "metadata": {
        "collectionType": "application/vnd.ibm.kms.policy+json",
        "collectionTotal": 2
      },
      "resources": [
        {
          "id": "...",
          "crn": "...",
          "rotation": {
            "interval_month": 3
          },
          "createdBy": "...",
          "creationDate": "...",
          "updatedBy": "...",
          "lastUpdateDate": "..."
        },
        {
          "id": "...",
          "crn": "...",
          "dualAuthDelete": {
            "enabled": "<true|false>"
          },
          "createdBy": "...",
          "creationDate": "...",
          "updatedBy": "...",
          "lastUpdateDate": "..."
        }
      ]
    }
  • Example response of dual authorization policy

    {
      "metadata": {
        "collectionType": "application/vnd.ibm.kms.policy+json",
        "collectionTotal": 1
      },
      "resources": [
        {
          "id": "...",
          "crn": "...",
          "dualAuthDelete": {
            "enabled": "<true|false>"
          },
          "createdBy": "...",
          "creationDate": "...",
          "updatedBy": "...",
          "lastUpdateDate": "..."
        }
      ]
    }
  • Example response of key rotation policy

    {
      "metadata": {
        "collectionType": "application/vnd.ibm.kms.policy+json",
        "collectionTotal": 1
      },
      "resources": [
        {
          "id": "...",
          "crn": "...",
          "rotation": {
            "interval_month": 3
          },
          "createdBy": "...",
          "creationDate": "...",
          "updatedBy": "...",
          "lastUpdateDate": "..."
        }
      ]
    }
  • {
      "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": "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 instance policies

Creates or updates one or more policies for the specified service instance.

Note: When you set an instance policy, Hyper Protect Crypto Services associates the policy information with keys that you add to the instance after the policy is updated. This operation does not affect existing keys in the instance.

PUT /api/v2/instance/policies

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • hs-crypto.instancepolicies.write

Auditing

Calling this method generates the following event for the Activity Tracker with LogDNA service.

  • hs-crypto.instancepolicies.write

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.

Query Parameters

  • The type of policy that is associated with the specified instance.

    Allowable values: [dualAuthDelete,allowedNetwork,keyCreateImportAccess]

The base request for the create or update of instance level policies.

Example:
  • curl -X PUT   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/instance/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": 3
        },
        "resources": [
          {
            "policy_type": "dualAuthDelete",
            "policy_data": {
              "enabled": <true|false>
            }
          },
          {
            "policy_type": "allowedNetwork",
            "policy_data": {
              "enabled": <true|false>
              "attributes": {
                "allowed_network": <public-and-private|private-only>
              }
            }
          },
          {
            "policy_type": "keyCreateImportAccess",
            "policy_data": {
              "enabled": <true|false>
              "attributes": {
                "create_root_key" : <true|false>,
                "create_standard_key" : <true|false>,
                "import_root_key": <true|false>,
                "import_standard_key":<true|false>,
                "enforce_token": <true|false>
              }
            }
        ]
      }'
  • curl -X PUT   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/instance/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": [
          {
            "policy_type": "dualAuthDelete",
            "policy_data": {
              "enabled": <true|false>
            }
          }
        ]
      }'
  • curl -X PUT   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/instance/policies?policy=allowedNetwork   -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": [
          {
            "policy_type": "allowedNetwork",
            "policy_data": {
              "enabled": <true|false>,
              "attributes": {
                  "allowed_network": "<public-and-private|private-only"
              }
            }
          }
        ]
      }'
  • curl -X PUT   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/instance/policies?policy=keyCreateImportAccess   -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": [
          {
            "policy_type": "keyCreateImportAccess",
            "policy_data": {
              "enabled": <true|false>
              "attributes": {
                "create_root_key" : <true|false>,
                "create_standard_key" : <true|false>,
                "import_root_key": <true|false>,
                "import_standard_key":<true|false>,
                "enforce_token": <true|false>
              }
            }
          }
        ]
      }'
  • curl -X PUT   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/instance/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": 3
        },
        "resources": [
          {
            "policy_type": "allowedNetwork",
            "policy_data": {
              "enabled": <true|false>,
              "attributes": {
                  "allowed_network": "<public-and-private|private-only"
              }
            }
          },
          {
            "policy_type": "dualAuthDelete",
            "policy_data": {
              "enabled": <true|false>
            }
          },
          {
            "policy_type": "keyCreateImportAccess",
            "policy_data": {
              "enabled": <true|false>
              "attributes": {
                "create_root_key" : <true|false>,
                "create_standard_key" : <true|false>,
                "import_root_key": <true|false>,
                "import_standard_key":<true|false>,
                "enforce_token": <true|false>
              }
          },
        ]
      }'
  • package main
    
    import (
      "context"
      "fmt"
    
      "github.com/IBM/keyprotect-go-client"
    )
    
    func main() {
    
      // Initialize the key management service client as specified in Authentication
    
      err = api.SetInstancePolicies(context.Background(), <true|false>)
      if err != nil {
        fmt.Println("Error while creating policies: ", err)
        return
      }
      fmt.Println("Instance policy set successfully")
    }

Response

Status Code

  • The policy or policies were successfully created or updated. No content.

  • The policy or policies cannot be created or updated due to a malformed or invalid request.

  • 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 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.

Example responses
  • {
      "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: '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.'"
      ]
    }

Retrieve an import token

Retrieves the import token that is associated with your service instance.

When you call GET /import_token, Hyper Protect Crypto Services returns the public key that you can use to encrypt and import key material to the service, along with details about the key.

Note: After you reach the maxAllowedRetrievals or expirationDate for the import token, the import token and its associated public key can no longer be used for key operations. To create a new import token, use POST /import_token.

GET /api/v2/instance/policies

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • hs-crypto.importtoken.read

Auditing

Calling this method generates the following event for the Activity Tracker with LogDNA service.

  • hs-crypto.importtoken.read

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 GET   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/import_token   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.import_token+json'
  • package main
    
    import (
      "context"
      "encoding/json"
      "fmt"
    
      "github.com/IBM/keyprotect-go-client"
    )
    
    func main() {
    
      // Initialize the key management service client as specified in Authentication
    
      importToken, err := api.GetImportTokenTransportKey(context.Background())
      if err != nil {
        fmt.Println("Error while getting import token: ", err)
        return
      }
      b, _ := json.MarshalIndent(importToken, "", "  ")
      fmt.Println(string(b))
    }
  • 
    //Initialize the key management service client as specified in Authentication
    
    //Retrieving Import Token
    GetImportTokenOptions getImportTokenOptionsModel = new GetImportTokenOptions.Builder()
        .bluemixInstance(bluemixInstance)
        .build();
    
    Response<GetImportToken> getResponse = testService.getImportToken(getImportTokenOptionsModel).execute();
    GetImportToken getResponseObj = getResponse.getResult();

Response

The base schema for retrieving an import token.

Status Code

  • The import token 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

  • An import token was not found in the specified service instance. To create an import token, use POST /import_token

  • The import token has reached its maxAllowedRetrievals or expirationDate, and it is no longer available for use. To create a new import token, use POST /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 to 409 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.

Example responses
  • {
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "expirationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "maxAllowedRetrievals": 10,
      "remainingRetrievals": 9,
      "payload": "...",
      "nonce": "..."
    }
  • {
      "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"