Introduction
IBM® Key Protect for IBM Cloud® helps you provision encrypted keys for apps across IBM Cloud. As you manage the lifecycle of your keys, you can benefit from knowing that your keys are secured by cloud-based FIPS 140-2 Level 3 hardware security modules (HSMs) that protect against the theft of information.
Key Protect provides a REST API that you can use with any programming language to store, retrieve, and generate encryption keys. For details about using Key Protect, see the IBM Cloud docs.
API endpoint
https://<region>.kms.cloud.ibm.com
Replace <region>
with the prefix that represents the geographic area where
your Key Protect service instance resides.
For more information, see
Regions and locations.
The code examples on this tab use the client library that is provided for Go.
go get -u github.com/IBM/keyprotect-go-client
GitHub:
The code examples on this tab use the client library that is provided for NodeJS.
npm install @ibm-cloud/ibm-key-protect
GitHub:
The code examples on this tab use the client library that is provided for Python.
pip install -U keyprotect
GitHub:
The code examples on this tab use the client library that is provided for Java.
git clone https://github.com/IBM/keyprotect-java-client
cd keyprotect-java-client
mvn install
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 Key Protect.
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. For example, if you created a
Key Protect service instance for the
us-south
region, use the following endpoint and API headers to browse keys in
your service:
curl -X GET \
https://us-south.kms.cloud.ibm.com/api/v2/keys \
-H "accept: application/vnd.ibm.collection+json" \
-H "authorization: Bearer <access_token>" \
-H "bluemix-instance: <instance_ID>"
Replace <access_token>
with your Cloud IAM token, and <instance_ID>
with the
IBM Cloud instance ID that identifies your
Key Protect service instance.
You can retrieve an access token by first creating an API key, and then exchanging your API key for a Cloud IAM token. For more information, see Retrieving an access token programmatically.
To find out more about setting up the Key Protect API, see Accessing the API.
IBM Cloud Identity and Access Management (IAM) is the primary method to
authenticate to the Key Protect API. The SDK
provides client config initialization method in which you will need to replace
<key_protect_url>
with the appropriate service endpoint,
the <api_key>
with the API key
associated with your application, and <instance_ID>
with the IBM Cloud
instance ID that identifies your Key Protect
service instance.
The value kp.DefaultTokenURL
for TokenURL
defaults to the IAM production URL,
but you may need to alter the value to be associated with virtual private networks.
Use the client config options in the method to create a new
Key Protect 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 Key Protect API. The SDK provides a client config setup in which you will need to export
environment variables to match the IBMCLOUD_API_KEY
term with the API key associated with your service credentials, another term, IAM_AUTH_URL
with the appropriate URL like 'https://iam.cloud.ibm.com/identity/token', another term, KP_SERVICE_URL
with the endpoint, including the region, such as https://us-south.kms.cloud.ibm.com
, and KP_INSTANCE_ID
with the IBM Cloud instance ID that identifies your Key Protect service instance.
To retrieve your instance ID:
ibmcloud resource service-instance <instance_name> --output JSON
IBM Cloud Identity and Access Management (IAM) is the primary method to
authenticate to the Key Protect API. The SDK
provides a client config setup in which you will 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
Key Protect service instance.
IBM Cloud Identity and Access Management (IAM) is the primary method to
authenticate to the Key Protect API. The SDK
provides a client config setup in which you will 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
Key Protect service instance.
IBM Cloud Identity and Access Management (IAM) is the primary method to
authenticate to the Key Protect API.
The SDK provides a client config setup in which you will need to replace the
IAM_API_KEY
with the API key associated with your application, IAM_AUTH_URL
with your Cloud IAM token,KEY_PROTECT_URL
with a service endpoint, and
INSTANCE_ID
with the IBM Cloud instance ID that identifies your
Key Protect service instance.
To retrieve your access token:
curl -X POST https://iam.cloud.ibm.com/identity/token -H "accept: application/json" -H "content-type: application/x-www-form-urlencoded" -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
Key Protect service instance. The GUID
value in the JSON output represents the instance ID for the service.
To authenticate to Key Protect API:
import (
"context"
"encoding/json"
"fmt"
kp "github.com/IBM/keyprotect-go-client"
)
func getConfigAPIKey() kp.ClientConfig {
return kp.ClientConfig{
BaseURL: <key_protect_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
}
}
To access the API through your service endpoint, you will need to use the following format.
API endpoint format:
https://<region>.kms.cloud.ibm.com
Replace <region>
with the prefix that represents the geographic area where
your Key Protect service instance resides.
For more informaton, see
Regions and locations.
To retrieve your instance ID, run the following command using the CLI:
ibmcloud resource service-instance <instance_name> --output JSON
Replace <instance_name>
with the unique alias that you assigned to your
Key Protect service instance. The GUID
value in the JSON output represents the <instance_ID>
for the service.
To authenticate to Key Protect API:
const KeyProtectV2 = require('@ibm-cloud/ibm-key-protect/ibm-key-protect-api/v2');
const { IamAuthenticator } = require('@ibm-cloud/ibm-key-protect/auth');
// using external configuration of environment variables
const envConfigs = {
apiKey: process.env.IBMCLOUD_API_KEY,
iamAuthUrl: process.env.IAM_AUTH_URL,
serviceUrl: process.env.KP_SERVICE_URL,
bluemixInstance: process.env.KP_INSTANCE_ID,
};
// Create an IAM authenticator.
const authenticator = new IamAuthenticator({
apikey: envConfigs.apiKey,
url: envConfigs.iamAuthUrl,
});
// Construct the service client.
const keyProtectClient = new KeyProtectV2({
authenticator,
serviceUrl: envConfigs.serviceUrl,
});
For more information on the regional endpoint where your data can be accessed, see Regions and locations.
To authenticate to Key Protect 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 <KP_INSTANCE_ID>
with the UUID that identifies your
Key Protect instance.
To retrieve your instance ID:
ibmcloud resource service-instance <instance_name> --output JSON
Replace <region>
with the prefix that represents the geographic area where
your Key Protect service instance resides.
For more information, see
Regions and locations.
To authenticate to Key Protect API:
import com.ibm.cloud.ibm_key_protect_api.v2.IbmKeyProtectApi;
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.*;
public class KPClient {
private static IbmKeyProtectApi testClient;
public static void main(String[] args) {
IamAuthenticator authenticator = new IamAuthenticator("<IAM_API_KEY>");
authenticator.setURL("<IAM_AUTH_URL>");
authenticator.validate();
testClient = new IbmKeyProtectApi("<INSTANCE_ID>", authenticator);
testClient.setServiceUrl("<KEY_PROTECT_URL>");
}
}
Replace <INSTANCE_ID>
with the UUID that identifies your Key Protect instance.
Replace <IAM_API_KEY>
with your service credentials.
Replace <IAM_AUTH_URL>
with https://iam.cloud.ibm.com/identity/token
.
Replace <KEY_PROTECT_URL>
with the service endpoint for your instance that handles your requests.
To retrieve your instance ID, replace <instance_name> in the command as shown:
ibmcloud resource service-instance <instance_name> --output JSON
Your endpoint is specific to the geographic area where your Key Protect service instance resides. For more information, see Regions and locations.
Auditing
You can monitor API activity within your account. Whenever an API method is called, an event is generated that you can then track and audit. The specific event type is listed for each method that generates auditing events. For methods that don't list any events, no events are generated.
For more information about how to track Key Protect activity, see Auditing the events for Key Protect.
Error handling
The Key Protect service uses standard HTTP
response codes to indicate whether a method completed successfully. A 200
response always indicates success. A 400
type response is some sort of
failure, and a 500
type response usually indicates an internal system error.
Status code | Description |
---|---|
200 OK |
Everything worked as expected. |
201 OK |
Everything worked as expected; no content. |
400 Bad Request |
The request was unsuccessful; ensure no required parameters are missing. |
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 Key Protect's end. |
Metadata
When you create or store keys in Key Protect, 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
Key Protect 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.
There are optional operations that can effect pagination and the resulting list of keys returned by the service. Some operations may still be in development, and will be listed as "Beta" while that is the case.
Search
When used, this operation performs a search, possibly limiting the number of keys returned. If you want to narrow the number of results returned by a search, try using one or a combination of the following values as a prefix for the term you wish to have searched:
not:
when specified, inverts the logic the search uses (for example,not:foo
will search for keys that have aliases or names that do not containfoo
).escape:
everything after this option is take as plaintext (example:escape:not:
will search for keys that have an alias or name containing the substringnot:
).exact:
only looks for exact matches.alias:
only looks for key aliases.name:
only looks for key names.
Sort
When used, this operation sorts the list of keys returned based on one or more key properties. The key properties that can be sorted at this time are:
id
state
extractable
imported
creationDate
lastUpdateDate
lastRotateDate
deletionDate
expirationDate
The list of keys returned is sorted on id by default, if this parameter is not provided.
Rate Limiting
Rate limits for API requests are enforced on a per-service-instance basis. If the number of requests for a particular method and endpoint reaches the request limit within the specified time window, no further requests are accepted until the timer expires. After the timer expires, a new time window begins with the next accepted request.
An HTTP status code of 429 indicates that the rate limit has been exceeded.
Change log
Important changes, such as additions, updates, and breaking changes, are marked with a change notice in this reference.
New features will be initially released as "beta" implementations.
"Beta" means that the specification is subject to change, with limited support in different environments (from partial support to none at all, depending on the specifics), in order to test new features that are not yet stable for use in production environments.
As part of continued migration and improvement, the algorithmBitSize
, algorithmMode
,
algorithmType
and algorithmMetadata
fields are deprecated within the Key Protect API.
Key Protect announces several changes to both the structure and to particular names of certain events to better conform with IBM naming conventions.
The alias
parameter in the event generated with a key alias
added to a key at creation time is being moved from the response data section to the request data section.
Also, to better conform with IBM standards, the names of certain events are changing.
Old event name | New event name |
---|---|
kms.secrets.eventack | kms.secrets-event.ack |
kms.secrets.readmetadata | kms.secrets-metadata.read |
kms.secrets.listkeyversions | kms.secrets-key-versions.list |
kms.secrets.defaultalias | kms.secrets-alias.default |
kms.secrets.createalias | kms.secrets-alias.create |
kms.secrets.deletealias | kms.secrets-alias.delete |
kms.importtoken.create | kms.import-token.create |
kms.importtoken.default | kms.import-token.default |
kms.importtoken.read | kms.import-token.read |
kms.instancepolicies.write | kms.instance-policies.write |
kms.instancepolicies.default | kms.instance-policies.default |
kms.instancepolicies.read | kms.instance-policies.read |
kms.instance.readallowedipport | kms.instance-allowed-ip-port.read |
kms.instance.readipwhitelistport | kms.instance-ip-whitelist-port.read |
kms.keyrings.create | kms.key-rings.create |
kms.keyrings.delete | kms.key-rings.delete |
kms.keyrings.list | kms.key-rings.list |
kms.keyrings.default | kms.key-rings.default |
kms.governance.configread | kms.governance-config.read |
Methods
Create a key
Creates a new key with specified key material.
Key Protect designates the resource as either a root key or a standard
key based on the extractable
value that you specify. A successful
POST /keys
operation adds the key to the service and returns the
details of the request in the response entity-body, if the Prefer header
is set to return=representation
.
POST /api/v2/keys
Request
Custom Headers
The IBM Cloud instance ID that identifies your Key Protect service 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 as metadata. A header containingreturn=representation
returns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Key Protect may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequentGET /keys/{id}
request.Allowable values: [
return=representation
,return=minimal
]The ID of the key ring that the specified key belongs to. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.Default:
default
The base request for creating a new key.
A collection of resources.
curl -X POST https://<region>.kms.cloud.ibm.com/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": "A Key Protect key", "extractable": false } ] }'
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication // Method CreateKeyWithAliases supports creating key with aliases. To provide alias names pass array of strings to the method // otherwise pass nil. rootkey, err := api.CreateKeyWithAliases(context.Background(), <key_name>, <expiration_date>, <extractable>, <aliases>) if err != nil { fmt.Println("Error while creating key: ", err) return } b, _ := json.MarshalIndent(rootkey, "", " ") fmt.Println(string(b)) }
// Initialize the Key Protect client as specified in Authentication // Define the key parameters const body = { metadata: { collectionType: 'application/vnd.ibm.kms.key+json', collectionTotal: 1, }, resources: [ { type: 'application/vnd.ibm.kms.key+json', name: 'nodejsKey', extractable: false, }, ], }; const createParams = Object.assign({}, envConfigs); createParams.body = body; const response = keyProtectClient.createKey(createParams); const keyId = response.result.resources[0].id; console.log('Key created, id is: ' + keyId);
import os import keyprotect from keyprotect import bxauth # Initialize the Key Protect client as specified in Authentication key = kp.create(name="<key_name>") print("Created key '%s'" % key["id"])
// payload is null if not an imported key // payload should be base64 encoded string // notRootKey is false if this is a root key public static String createKey(String keyName, String keyDescription, String payload, boolean notRootKey) { InputStream inputstream = null; CreateKeyOptions createKeyOptionsModel = null; try { // build json format input stream JsonObjectBuilder resourceObjectBuilder = Json.createObjectBuilder() .add("name", keyName) .add("extractable", notRootKey) .add("description", keyDescription); // imported key if (payload != null) { resourceObjectBuilder.add("payload", payload); } JsonObjectBuilder jsonObjectBuilder = Json.createObjectBuilder() .add("metadata", Json.createObjectBuilder() .add("collectionType", "application/vnd.ibm.kms.key+json") .add("collectionTotal", 1)) .add("resources", Json.createArrayBuilder() .add(resourceObjectBuilder)); JsonObject jsonObject = jsonObjectBuilder.build(); inputstream = new ByteArrayInputStream(jsonObject.toString().getBytes()); createKeyOptionsModel = new CreateKeyOptions.Builder() .bluemixInstance("<instance_id>") .createKeyOneOf(inputstream) .prefer("return=representation") .build(); } catch(ClassCastException e) { System.out.println("Error: " + e.toString()); return "failed to create key"; } Response<Key> response = testClient.createKey(createKeyOptionsModel).execute(); List<KeyWithPayload> key = response.getResult().getResources(); return key.toString(); }
Response
Properties associated with a key response.
The metadata that describes the resource array.
A collection of resources.
Status Code
The key was successfully created.
The key is missing a required field.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.
There are three possible causes for HTTP 404 while trying to create a key, specifying a reason code (resouces[0].reasons[0].code) as follows:
KEY_RING_NOT_FOUND_ERR: The key cannot be created because the key ring does not exist. Note: the default key ring name is "default."
INSTANCE_NOT_FOUND_ERR: The key cannot be created because the instance does not exist.
IMPORT_TOKEN_NOT_FOUND_ERR: The key cannot be created because the import token does not exist.
The import token that was used to encrypt this key has reached its
maxAllowedRetrievals
orexpirationDate
, and it is no longer available for operations. To create a new import token, usePOST /import_token
.In very rare cases, the import token may expire before its expiration time. Ensure that your client application is configured with a retry mechanism for catching and responding to
409
conflict exceptions.KEY_ALIAS_QUOTA_ERR: The alias quota for this key has been reached.
KEY_ALIAS_NOT_UNIQUE_ERR: One or more aliases are already associated with a key in the instance.
KEY_CREATE_IMPORT_ACCESS_ERR: KeyCreateImportAccess instance policy is enabled. Key Protect only permits the creation or import of keys in your Key Protect instance that follow the key creation and import settings listed on the keyCreateImportAccess policy.
IMPORT_TOKEN_EXPIRED_ERR: The key cannot be created because the import token has expired.
Too many requests. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "fadedbee-0000-0000-0000-1234567890ab", "name": "Root-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 1, "extractable": false, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:fadedbee-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "YYYY-MM-DDTHH:mm:SSZ", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "YYYY-MM-DDTHH:mm:SSZ", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab", "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: The user does not have access to the specified resource." } ] }
{ "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 Key Protect. [Learn more](/docs/key-protect?topic=key-protect-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: Wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later." } ] }
List keys
Retrieves a list of keys that are stored in your Key Protect service instance.
Important: When a user of Key Protect on Satellite views lists of keys through the IBM Console, or programmatically via this API, keys with "fine grain" permissions won't appear due to the manner in which the service aggregates the collection. While the user can still use the key resource, only by using the CLI or API and passing the specific key ID can a user access the metadata and other details of the key.
Note: GET /keys
will not return the key material in the response
body. You can retrieve the key material for a standard key with a
subsequent GET /keys/{id}
request.
GET /api/v2/keys
Request
Custom Headers
The IBM Cloud instance ID that identifies your Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the target key ring. If unspecified, all resources in the instance that the caller has access to will be returned. When the header is specified, only resources within the specified key ring, that the caller has access to, will be returned. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Query Parameters
The number of keys to retrieve. By default,
GET /keys
returns the first 200 keys. To retrieve a different set of keys, uselimit
withoffset
to page through your available resources. The maximum value forlimit
is 5,000. Usage: If you have 20 keys in your instance, and you want to retrieve only the first 5 keys, use../keys?limit=5
.Possible values: 1 ≤ value ≤ 5000
Default:
200
The number of keys to skip. By specifying
offset
, you retrieve a subset of keys that starts with theoffset
value. Useoffset
withlimit
to page through your available resources. Usage: If you have 100 keys in your instance, and you want to retrieve keys 26 through 50, use../keys?offset=25&limit=25
.Possible values: value ≥ 0
Default:
0
The state of the keys to be retrieved. States must be a list of integers from 0 to 5 delimited by commas with no whitespace or trailing commas. Valid states are based on NIST SP 800-57. States are integers and correspond to the Pre-activation = 0, Active = 1, Suspended = 2, Deactivated = 3, and Destroyed = 5 values. Usage: If you want to retrieve active and deleted keys, use
../keys?state=1,5
.Allowable values: [
0
,1
,2
,3
,5
]Default:
[0,1,2,3]
The type of keys to be retrieved. Filters keys based on the
extractable
property. You can use this query parameter to search for keys whose material can leave the service. If set totrue
, standard keys will be retrieved. If set tofalse
, root keys will be retrieved. If omitted, both root and standard keys will be retrieved. Usage: If you want to retrieve standard keys, use../keys?extractable=true
.When provided, performs a search, possibly limiting the number of keys returned. Examples:
foobar
- find keys where the name or any of its aliases containfoobar
, case insentive (i.e. matchesxfoobar
,Foobar
).fadedbee-0000-0000-0000-1234567890ab
(a valid key id) - find keys where the id the key isfadedbee-0000-0000-0000-1234567890ab
, or the name or any of its aliases containfadedbee-0000-0000-0000-1234567890ab
, case insentive.
May prepend with options:
not:
= when specified, inverts matching logic (example:not:foo
will search for keys that have aliases or names that do not containfoo
)escape:
= everything after this option is take as plaintext (example:escape:not:
will search for keys that have an alias or name containing the substringnot:
)exact:
= only looks for exact matches
May prepend with search scopes:
alias:
= search in key aliases for search queryname:
= search in key names for search query
Examples:
not:exact:foobar
/exact:not:foobar
- find keys where the name nor any of its aliases are not exactlyfoobar
(i.e. matchesxfoobar
,bar
,foo
)exact:escape:not:foobar
- find keys where the name or any of its aliases are exactlynot:foobar
not:alias:foobar
/alias:not:foobar
- find keys where any of its aliases do not containfoobar
name:exact:foobar
/exact:name:foobar
- find keys where the name is exactlyfoobar
Note:
By default, if no scopes are provided, search will be performed in both
name
andalias
scopes.Search is only possible on a intial searchable space of at most 5000 keys. If the initial seachable space is greater than 5000 keys, the API returns HTTP 400 with the property resouces[0].reasons[0].code equals to 'KEY_SEARCH_TOO_BROAD'. Use the following filters to reduce the initial searchable space:
state
(query parameter)extractable
(query parameter)X-Kms-Key-Ring
(HTTP header)
If the total intial searchable space exceeds the 5000 keys limit and when providing a fully specified key id or when searching within the
alias
scope, a lookup will be performed and if a key is found, the key will be returned as the only resource and in the response metadata the propertyincompleteSearch
will betrue
.When providing a fully specified key id or when searching within the
alias
scope, a key lookup is performed in addition to the search. This means search will try to lookup a single key that is uniquely identified by the key id or provided alias, this key will be included in the response as the first resource, before other matches.Search scopes are disjunctive, behaving in an OR manner. When using more than one search scope, a match in at least one of the scopes will result in the key being returned.
Possible values: length ≤ 256
When provided, sorts the list of keys returned based on one or more key properties. To sort on a property in descending order, prefix the term with "-". To sort on multiple key properties, use a comma to separate each properties. The first property in the comma-separated list will be evaluated before the next. The key properties that can be sorted at this time are:
id
state
extractable
imported
creationDate
lastUpdateDate
lastRotateDate
deletionDate
expirationDate
The list of keys returned is sorted on id by default, if this parameter is not provided.
Possible values: length ≤ 256
Default:
id
When provided, returns the list of keys that match the queried properties. Each key property to be filtered on is specified as the property name itself, followed by an “=“ symbol, and then the value to filter on, followed by a space if there are more properties to filter only. Note: Anything between
<
and>
in the examples or descriptions represent placeholder to specify the value Basic format:= = - The value to filter on may contain a value related to the property itself, or an operator followed by a value accepted by the operator - Only one operator and value, or one value is accepted per property at a time Format with operator/value pair: = : Up to three of the same property may be specified at a time. The key properties that can be filtered at this time are: creationDate
- Date in RFC 3339 format in double-quotes: “YYYY-MM-DDTHH:mm:SSZ”
deletionDate
- Date in RFC 3339 format in double-quotes: “YYYY-MM-DDTHH:mm:SSZ”
expirationDate
- Date in RFC 3339 format in double-quotes: “YYYY-MM-DDTHH:mm:SSZ”
extractable
- Boolean true or false without quotes, case-insensitive
lastRotateDate
- Date in RFC 3339 format in double-quotes: “YYYY-MM-DDTHH:mm:SSZ”
lastUpdateDate
- Date in RFC 3339 format in double-quotes: “YYYY-MM-DDTHH:mm:SSZ”
state
- A list of comma-separated integers with no space in between: 0,1,2,3,5 Comparison operations (operators) that can be performed on date values are:
lte:<value>
Less than or equal to -lt:<value>
Less than -gte:<value>
Greater than or equal to -gt:<value>
Greater than A special keyword for date,none
(case-insensitive), may be used to retreive keys that do not have that property. This is useful forlastRotateDate
, where only keys that have never been rotated can be retreived. Examples:lastRotateDate="2022-02-15T00:00:00Z"
Filter keys that were last rotated on February 15, 2022 -lastRotateDate=gte:"2022-02-15T00:00:00Z"
Filter keys that were last rotated after or on February 15, 2022 -lastRotateDate=gte:"2022-02-15T00:00:00Z" lastRotateDate=lt:"2022-03-15T00:00:00Z"
Filter keys that were last rotated after or on February 15, 2022 but before (not including) March 15, 2022 -lastRotateDate="2022-02-15T00:00:00Z" state=0,1,2,3,5 extractable=false
Filter root keys that were last rotated on February 15, 2022, with any state Note: When you filter bystate
orextractable
in this query parameter, you will not be able to use the deprecatedstate
orextractable
independent query parameter. You will get a 400 response code if you specify a value for one of the two properties in both this filter query parameter and the deprecated independent query of the same name (the same applies vice versa).
Possible values: length ≤ 512
curl -X GET https://<region>.kms.cloud.ibm.com/api/v2/keys -H 'accept: application/vnd.ibm.kms.key+json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication keys, err := api.GetKeys(context.Background(), <limit>, <offset>) if err != nil { fmt.Println("Error while retrieving keys: ", err) return } b, _ := json.MarshalIndent(keys, "", " ") fmt.Println(string(b)) }
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication limit := uint32(5) offset := uint32(0) extractable := false keyStates := []kp.KeyState{kp.KeyState(kp.Active), kp.KeyState(kp.Suspended)} listKeysOptions := &kp.ListKeysOptions{ Limit : &limit, Offset : &offset, Extractable : &extractable, State : keyStates, } keys, err := client.ListKeys(ctx, listKeysOptions) if err != nil { fmt.Println(err) } fmt.Println(keys) }
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication srtStr, _ := kp.GetKeySortStr(kp.WithCreationDate(), WithImportedDesc()) listKeysOptions := &kp.ListKeysOptions{ Sort:srtStr, } keys, err := client.ListKeys(ctx, listKeysOptions) if err != nil { fmt.Println(err) } fmt.Println(keys) }
import os import keyprotect from keyprotect import bxauth # Initialize the Key Protect client as specified in Authentication keys = kp.keys() for key in kp.keys(): print("%s\t%s" % (key["id"], key["name"]))
// Initialize the Key Protect client as specified in Authentication const response = keyProtectClient.getKeys(envConfigs); console.log('Get keys result:'); for (let resource of response.result.resources){ console.log(resource); }
public static List<KeyRepresentation> getKeys() { GetKeysOptions getKeysOptionsModel = new GetKeysOptions.Builder() .bluemixInstance("<instance_id>") .build(); Response<ListKeys> response = testClient.getKeys(getKeysOptionsModel).execute(); List<KeyRepresentation> keys = response.getResult().getResources(); return keys; }
Response
The base schema for listing keys.
The metadata that describes the list keys response
A collection of resources.
Status Code
The list of keys was successfully retrieved.
If reason code (resouces[0].reasons[0].code) is present and is equal to 'KEY_SEARCH_TOO_BROAD', the total searchable space is more than 5000 keys. Try using a filter to reduce the seachable space.
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. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 2 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "fadedbee-0000-0000-0000-1234567890ab", "name": "Root-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 1, "extractable": true, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:fadedbee-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "YYYY-MM-DDTHH:mm:SSZ", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "YYYY-MM-DDTHH:mm:SSZ", "lastRotateDate": "YYYY-MM-DDTHH:mm:SSZ", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab", "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": "addedace-0000-0000-0000-1234567890ab", "name": "Standard-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 1, "extractable": true, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:addedace-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "YYYY-MM-DDTHH:mm:SSZ", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "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": "beadcafe-0000-0000-0000-1234567890ab", "name": "Deleted-Standard-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 5, "extractable": true, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:beadcafe-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "YYYY-MM-DDTHH:mm:SSZ", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "YYYY-MM-DDTHH:mm:SSZ", "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:mm:SSZ" }, "deleted": true, "deletionDate": "YYYY-MM-DDTHH:mm:SSZ", "restoreAllowed": true, "restoreExpirationDate": "YYYY-MM-DDTHH:mm:SSZ", "purgeAllowed": false, "purgeAllowedFrom": "YYYY-MM-DDTHH:mm:SSZ", "purgeScheduledOn": "YYYY-MM-DDTHH:mm:SSZ" } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unauthorized: The user does not have access to the specified resource." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later." } ] }
Retrieve key total
Returns the same HTTP headers as a GET request without returning the entity-body. This operation returns the number of keys in your instance in a header called Key-Total
.
HEAD /api/v2/keys
Request
Custom Headers
The IBM Cloud instance ID that identifies your Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the target key ring. If unspecified, all resources in the instance that the caller has access to will be returned. When the header is specified, only resources within the specified key ring, that the caller has access to, will be returned. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Query Parameters
The state of the keys to be retrieved. States must be a list of integers from 0 to 5 delimited by commas with no whitespace or trailing commas. Valid states are based on NIST SP 800-57. States are integers and correspond to the Pre-activation = 0, Active = 1, Suspended = 2, Deactivated = 3, and Destroyed = 5 values. Usage: If you want to retrieve active and deleted keys, use
../keys?state=1,5
.Allowable values: [
0
,1
,2
,3
,5
]Default:
[0,1,2,3]
The type of keys to be retrieved. Filters keys based on the
extractable
property. You can use this query parameter to search for keys whose material can leave the service. If set totrue
, standard keys will be retrieved. If set tofalse
, root keys will be retrieved. If omitted, both root and standard keys will be retrieved. Usage: If you want to retrieve standard keys, use../keys?extractable=true
.When provided, returns the list of keys that match the queried properties. Each key property to be filtered on is specified as the property name itself, followed by an “=“ symbol, and then the value to filter on, followed by a space if there are more properties to filter only. Note: Anything between
<
and>
in the examples or descriptions represent placeholder to specify the value Basic format:= = - The value to filter on may contain a value related to the property itself, or an operator followed by a value accepted by the operator - Only one operator and value, or one value is accepted per property at a time Format with operator/value pair: = : Up to three of the same property may be specified at a time. The key properties that can be filtered at this time are: creationDate
- Date in RFC 3339 format in double-quotes: “YYYY-MM-DDTHH:mm:SSZ”
deletionDate
- Date in RFC 3339 format in double-quotes: “YYYY-MM-DDTHH:mm:SSZ”
expirationDate
- Date in RFC 3339 format in double-quotes: “YYYY-MM-DDTHH:mm:SSZ”
extractable
- Boolean true or false without quotes, case-insensitive
lastRotateDate
- Date in RFC 3339 format in double-quotes: “YYYY-MM-DDTHH:mm:SSZ”
lastUpdateDate
- Date in RFC 3339 format in double-quotes: “YYYY-MM-DDTHH:mm:SSZ”
state
- A list of comma-separated integers with no space in between: 0,1,2,3,5 Comparison operations (operators) that can be performed on date values are:
lte:<value>
Less than or equal to -lt:<value>
Less than -gte:<value>
Greater than or equal to -gt:<value>
Greater than A special keyword for date,none
(case-insensitive), may be used to retreive keys that do not have that property. This is useful forlastRotateDate
, where only keys that have never been rotated can be retreived. Examples:lastRotateDate="2022-02-15T00:00:00Z"
Filter keys that were last rotated on February 15, 2022 -lastRotateDate=gte:"2022-02-15T00:00:00Z"
Filter keys that were last rotated after or on February 15, 2022 -lastRotateDate=gte:"2022-02-15T00:00:00Z" lastRotateDate=lt:"2022-03-15T00:00:00Z"
Filter keys that were last rotated after or on February 15, 2022 but before (not including) March 15, 2022 -lastRotateDate="2022-02-15T00:00:00Z" state=0,1,2,3,5 extractable=false
Filter root keys that were last rotated on February 15, 2022, with any state Note: When you filter bystate
orextractable
in this query parameter, you will not be able to use the deprecatedstate
orextractable
independent query parameter. You will get a 400 response code if you specify a value for one of the two properties in both this filter query parameter and the deprecated independent query of the same name (the same applies vice versa).
Possible values: length ≤ 512
curl -I HEAD https://<region>.kms.cloud.ibm.com/api/v2/keys -H 'accept: application/vnd.ibm.kms.key+json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
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 Key Protect. Learn more.
Too many requests. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
Create a key with policy overrides
Creates a new key with specified key material and key policies. This API overrides the policy configurations set at instance level with policies provided in the payload.
Key Protect designates the resource as a root key or a standard key based on the extractable value that you specify.
A successful POST /keys_with_policy_overrides
operation adds the key and key policies 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_with_policy_overrides
Request
Custom Headers
The IBM Cloud instance ID that identifies your Key Protect service 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 as metadata. A header containingreturn=representation
returns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Key Protect may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequentGET /keys/{id}
request.Allowable values: [
return=representation
,return=minimal
]The ID of the key ring that the specified key belongs to. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.Default:
default
The base request for creating a new key with policies.
A collection of resources.
Specifies the MIME type that represents the key resource. Currently, only the default is supported.
A human-readable name assigned to your key for convenience. To protect your privacy do not use personal data, such as your name or location, as the name for your key.
Possible values: 2 ≤ length ≤ 90, Value must match regular expression
[*]{2,90}
One or more, up to a total of five, human-readable unique aliases assigned to your key. To protect your privacy do not use personal data, such as your name or location, as an alias for your key. Each alias must be alphanumeric and cannot contain spaces or special characters other than
-
or_
. The alias cannot be a UUID and must not be a Key Protect reserved name:allowed_ip
,key
,keys
,metadata
,policy
,policies
,registration
,registrations
,ring
,rings
,rotate
,wrap
,unwrap
,rewrap
,version
,versions
.Possible values: 0 ≤ number of items ≤ 5, 2 ≤ length ≤ 90, Value must match regular expression
[a-zA-Z0-9-_]{2,90}
A text field used to provide a more detailed description of the key. The maximum length is 240 characters. To protect your privacy, do not use personal data, such as your name or location, as a description for your key.
Possible values: 2 ≤ length ≤ 240
Up to 30 tags can be created. Tags can be between 0-30 characters, including spaces. Special characters not permitted include angled brackets, comma, colon, ampersand, and vertical pipe character (|). To protect your privacy, do not use personal data, such as your name or location, as a tag for your key.
The date the key material expires. The date format follows RFC 3339. You can set an expiration date on any key on its creation. If you create a key without specifying an expiration date, the key does not expire.
Example:
YYYY-MM-DDTHH:mm:SSZ
A boolean that determines whether the key material can leave the service. If set to
false
, Key Protect designates the key as a nonextractable root key used forwrap
andunwrap
actions. If set totrue
, Key Protect designates the key as a standard key that you can store in your apps and services. Once set tofalse
it cannot be changed totrue
.Default:
true
resources
curl -X POST https://<region>.kms.cloud.ibm.com/api/v2/keys_with_policy_overrides -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": "A Key Protect key", "extractable": false, "dualAuthDelete": { "enabled": true }, "rotation":{ "enabled": true, "interval_month": 6 } } ] }'
Response
Properties associated with a key response.
The metadata that describes the resource array.
A collection of resources.
Status Code
The key was successfully created.
The key is either missing a required field or it may contain an invalid or malformed input.
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 Key Protect. Learn more.
There are three possible causes for HTTP 404 while trying to create a key, specifying a reason code (resouces[0].reasons[0].code) as follows:
KEY_RING_NOT_FOUND_ERR: The key cannot be created because the key ring does not exist. Note the default key ring name is "default." INSTANCE_NOT_FOUND_ERR: The key cannot be created because the instance does not exist. IMPORT_TOKEN_NOT_FOUND_ERR: The key cannot be created because the import token does not exist.
The import token that was used to encrypt this key has reached its
maxAllowedRetrievals
orexpirationDate
, and it is no longer available for operations. To create a new import token, usePOST /import_token
. In very rare cases, the import token may expire before its expiration time. Ensure that your client application is configured with a retry mechanism for catching and responding to409
conflict exceptions. KEY_ALIAS_QUOTA_ERR: The alias quota for this key has been reached. KEY_ALIAS_NOT_UNIQUE_ERR: One or more aliases are already associated with a key in the instance. KEY_CREATE_IMPORT_ACCESS_ERR: KeyCreateImportAccess instance policy is enabled. Key Protect only permits the creation or import of keys in your Key Protect instance that follow the key creation and import settings listed on the keyCreateImportAccess policy. IMPORT_TOKEN_EXPIRED_ERR: The key cannot be created because the import token has expired.Too many requests. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "fadedbee-0000-0000-0000-1234567890ab", "name": "Root-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 1, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:fadedbee-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "YYYY-MM-DDTHH:mm:SSZ", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "YYYY-MM-DDTHH:mm:SSZ", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab", "creationDate": "YYYY-MM-DDTHH:mm:SSZ" }, "rotation": { "interval_month": 3 }, "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: The user does not have access to the specified resource." } ] }
{ "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 Key Protect. [Learn more](/docs/key-protect?topic=key-protect-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: Wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later." } ] }
Retrieve a key
Retrieves a key and its details by specifying the ID or alias of the key.
GET /api/v2/keys/{id}
Request
Custom Headers
The IBM Cloud instance ID that identifies your Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID or alias that uniquely identifies the key.
curl -X GET https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias> -H 'accept: application/vnd.ibm.kms.key+json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication key, err := api.GetKey(context.Background(), <key_ID_or_alias>) if err != nil { fmt.Println("Error while retrieving the key: ", err) return } b, _ := json.MarshalIndent(key, "", " ") fmt.Println(string(b)) }
// Initialize the Key Protect client as specified in Authentication const getKeyParams = Object.assign({}, envConfigs); getKeyParams.id = "<key_id>"; const response = keyProtectClient.getKey(getKeyParams); console.log('Get key result: '); console.log(response.result.resources[0]);
import os import keyprotect from keyprotect import bxauth # Initialize the Key Protect client as specified in Authentication key = kp.get("<key_id>") print("%s\t%s" % (key["id"], key["name"]))
public static List<KeyWithPayload> getKey(String keyId) { GetKeyOptions getKeyOptionsModel = new GetKeyOptions.Builder() .bluemixInstance("<instance_id>") .id(keyId) .build(); Response<GetKey> response = testClient.getKey(getKeyOptionsModel).execute(); List<KeyWithPayload> key = response.getResult().getResources(); return key; }
Response
The base schema for retrieving keys.
The metadata that describes the resource array.
A collection of resources.
Status Code
The key was successfully retrieved. If the key was previously deleted,
keyVersion.creationDate
is omitted from the request response.The key could not be retrieved due to a malformed, invalid, or missing ID.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.
The key could not be found. Verify that the key ID specified is valid.
Too many requests. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "fadedbee-0000-0000-0000-1234567890ab", "name": "Standard-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 1, "extractable": true, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:fadedbee-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "YYYY-MM-DDTHH:mm:SSZ", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab", "creationDate": "YYYY-MM-DDTHH:mm:SSZ" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:mm:SSZ" }, "deleted": false, "payload": "x089YbmN9GSvpxEKe0LaqA==" } ] }
{ "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: The user does not have access to the specified resource." } ] }
{ "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 Key Protect. [Learn more](/docs/key-protect?topic=key-protect-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: Wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later." } ] }
Invoke an action on a key
Note: This API has been deprecated and transitioned to
individual request paths. Existing actions using this API will continue
to be supported, but new actions will no longer be added to it. We
recommend, if possible, aligning your request URLs to the new API path.
The generic format of actions 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:
disable
: Disable operations for a keyenable
: Enable operations for a keyrestore
: Restore a root keyrewrap
: Use a root key to rewrap or reencrypt a data encryption keyrotate
: Create a new version of a root keysetKeyForDeletion
: Authorize deletion for a key with a dual authorization policyunsetKeyForDeletion
: [Remove an authorization]((/docs/key-protect?topic=key-protect-delete-dual-auth-keys#unset-key-deletion-api) for a key with a dual authorization policyunwrap
: Use a root key to unwrap or decrypt a data encryption keywrap
: Use a root key to wrap or encrypt a data encryption key
Note: If you unwrap a wrapped data encryption key (WDEK) that was not wrapped by the latest version of the key, the service also returns the a new WDEK, wrapped with the latest version of the key as the ciphertext field. The recommendation is to store and use that WDEK, although older WDEKs will continue to work.
POST /api/v2/keys/{id}
Request
Custom Headers
The IBM Cloud instance ID that identifies your Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.Alters server behavior for POST or DELETE operations. A header with
return=minimal
causes the service to return only the key identifier as metadata. A header containingreturn=representation
returns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Key Protect may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequentGET /keys/{id}
request.Allowable values: [
return=representation
,return=minimal
]
Path Parameters
The v4 UUID that uniquely identifies the key.
Query Parameters
The action to perform on the specified key.
Allowable values: [
disable
,enable
,restore
,rewrap
,rotate
,setKeyForDeletion
,unsetKeyForDeletion
,unwrap
,wrap
]
The base request for key actions.
The data encryption key (DEK) used in wrap actions when the query parameter is set to
wrap
. The system returns a base64 encoded plaintext in the response entity-body when you perform anunwrap
action on a key. To wrap an existing DEK, provide a base64 encoded plaintext during awrap
action. To generate a new DEK, omit theplaintext
property. Key Protect generates a random plaintext (32 bytes) that is rooted in an HSM and then wraps that value. Note: When you unwrap a wrapped data encryption key (WDEK) by using a rotated root key, the service returns a new ciphertext in the response entity-body. Each ciphertext remains available forunwrap
actions. If you unwrap a DEK with a previous ciphertext, the service also returns the latest ciphertext in the response. Use the latest ciphertext for future unwrap operations.Possible values: length ≤ 4096
The additional authentication data (AAD) used to further secure the key. If you supply AAD when you make a
wrap
call, you must specify the same AAD during a subsequentunwrap
call.Possible values: 0 ≤ number of items ≤ 126, 0 ≤ length ≤ 255
Response
Properties that are associated with the response body of a wrap action.
The wrapped data encryption key (WDEK) that you can export to your app or service. The ciphertext contains the DEK wrapped by the latest version of the key (WDEK). It is recommended to store and use this WDEK in future calls to Key Protect. The value is base64 encoded.
The data encryption key (DEK) used in wrap actions when the query parameter is set to
wrap
. The system returns a base64 encoded plaintext in the response entity-body when you perform anunwrap
action on a key. To wrap an existing DEK, provide a base64 encoded plaintext during awrap
action. To generate a new DEK, omit theplaintext
property. Key Protect generates a random plaintext (32 bytes) that is rooted in an HSM and then wraps that value. Note: When you unwrap a wrapped data encryption key (WDEK) by using a rotated root key, the service returns a new ciphertext in the response entity-body. Each ciphertext remains available forunwrap
actions. If you unwrap a DEK with a previous ciphertext, the service also returns the latest ciphertext in the response. Use the latest ciphertext for future unwrap operations.Possible values: length ≤ 4096
The key version that was used to wrap the DEK. This key version is associated with the
ciphertext
value that was used in the request.The ID of the key version.
Example:
fadedbee-0000-0000-0000-1234567890ab
keyVersion
Status Code
Successful key operation.
The imported key was successfully restored.
Successful key operation.
Your authentication data or key is invalid, or the entity-body is missing a required field.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. 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. Delete references to this key.
The ciphertext provided for the unwrap operation was not wrapped by this key.
Too many requests. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "plaintext": "tF9ss0W9HQUVkddcjSeGg/MqZFs2CVh/FFKLPLLnOwY=", "ciphertext": "eyJjaXBoZXJ0ZXh0Ijoic1ZZRnZVcjdQanZXQ0tFakMwRFFWZktqQ3AyRmtiOFJOSDJSTkpZRzVmU1hWNDJScD\\ RDVythU0h3Y009IiwiaGFzaCI6IjVWNzNBbm9XdUxxM1BvZEZpd1AxQTdQMUZrTkZOajVPMmtmMkNxdVBxL0NRdFlOZnBvemp\\ iYUxjRDNCSWhxOGpKZ2JNR0xhMHB4dDA4cTYyc0RJMGRBPT0iLCJpdiI6Ilc1T2tNWFZuWDFCTERDUk51M05EUlE9PSIsInZl\\ cnNpb24iOiIzLjAuMCIsImhhbmRsZSI6IjRkZjg5ZGVlLWU3OTMtNGY5Ny05MGNjLTc1ZWQ5YjZlNWM4MiJ9", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab" } }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "fadedbee-0000-0000-0000-1234567890ab", "name": "Root-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 1, "extractable": false, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:fadedbee-0000-0000-0000-1234567890ab", "imported": true, "creationDate": "YYYY-MM-DDTHH:mm:SSZ", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "YYYY-MM-DDTHH:mm:SSZ", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab", "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: The user does not have access to the specified resource." } ] }
{ "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 Key Protect. [Learn more](/docs/key-protect?topic=key-protect-integrate-services#grant-access)" } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: The key could not be found. KEY_NOT_FOUND_ERR: Key does not exist" } ] }
{ "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. 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: Wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later." } ] }
Update (patch) a key
Update attributes of a key. Currently only the following attributes are applicable for update: - keyRingID Note: If provided, the X-Kms-Key-Ring
header should specify the key's current key ring. To change the key ring of the key, specify the new key ring in the request body.
PATCH /api/v2/keys/{id}
Request
Custom Headers
The IBM Cloud instance ID that identifies your Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID that uniquely identifies the key.
The base request for patch key.
The target key ring to move the targeted key to.
curl -X PATCH https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias> -H 'accept: application/vnd.ibm.kms.key+json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'content-type: application/vnd.ibm.kms.key+json' -d '{ "keyRingID": "new-key-ring" }'
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication keyDetails, err := api.SetKeyRing(context.Background(), <key_ID>, <new_key_ring_name>) if err != nil { fmt.Println("Error while updating the key: ", err) return } b, _ := json.MarshalIndent(keyDetails, "", " ",) fmt.Println(string(b)) }
Response
The base schema for patch key response body.
The metadata that describes the resource array.
An array of resources.
Status Code
Successful key update.
The request is missing a required field.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
The key could not be found.
The requested key was previously deleted and is no longer available. Delete references to this key.
Too many requests. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "fadedbee-0000-0000-0000-1234567890ab", "name": "Root-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 1, "extractable": false, "keyRingID": "new-key-ring-id", "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:fadedbee-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "YYYY-MM-DDTHH:mm:SSZ", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "YYYY-MM-DDTHH:mm:SSZ", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab", "creationDate": "YYYY-MM-DDTHH:mm:SSZ" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:mm:SSZ" }, "deleted": false } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unauthorized: The user does not have access to the specified resource." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: The key could not be found. KEY_NOT_FOUND_ERR: Key does not exist" } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: The requested key was previously deleted and is no longer available. Delete references to this key." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later." } ] }
Delete a key
Deletes a key by specifying the ID or alias of the key.
By default, Key Protect 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: After a key has been deleted, any data that is encrypted by the key becomes inaccessible, though this can be reversed if the key is restored within the 30-day time frame. After 30 days, key metadata, registrations, and policies are available for up to 90 days, at which point the key becomes eligible to be purged. Note that once a key is no longer restorable and has been purged, its associated data can no longer be accessed.
Note: By default, Key Protect blocks the deletion of a key that's
protecting a cloud resource, such as a Cloud Object Storage bucket. Use
GET keys/{id}/registrations
to verify if the key has an active
registration to a resource. To delete the key and its associated
registrations, set the optional force
parameter to true
.
DELETE /api/v2/keys/{id}
Request
Custom Headers
The IBM Cloud instance ID that identifies your Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.Alters server behavior for POST or DELETE operations. A header with
return=minimal
causes the service to return only the key identifier as metadata. A header containingreturn=representation
returns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Key Protect may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequentGET /keys/{id}
request.Allowable values: [
return=representation
,return=minimal
]
Path Parameters
The v4 UUID that uniquely identifies the key.
Query Parameters
If set to
true
, Key Protect 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, Key Protect cannot delete the key. UseGET keys/{id}/registrations
to review registrations between the key and its associated cloud resources. To enable deletion, contact an account owner to remove the retention policy on each resource that is associated with this key.Default:
false
curl -X DELETE https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias> -H 'accept: application/vnd.ibm.kms.key+json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication force := false // set this to true if force-delete is needed delKey, err := client.DeleteKey(context.Background(), key.ID, kp.ReturnRepresentation, kp.ForceOpt{Force: force}) if err != nil { fmt.Println("Error while deleting the key: ", err) return } b, _ := json.MarshalIndent(delKey, "", " ") fmt.Println(string(b)) }
// Initialize the Key Protect client as specified in Authentication const deleteKeyParams = Object.assign({}, envConfigs); deleteKeyParams.id = "<key_ID_or_alias>"; deleteKeyParams.prefer = 'return=representation'; const response = keyProtectClient.deleteKey(deleteKeyParams); console.log('Delete key response status: ' + response.status);
import os import keyprotect from keyprotect import bxauth # Initialize the Key Protect client as specified in Authentication deletedKey = kp.delete("<key_id>") print("Deleted key '%s'" % key_id)
public static DeleteKey deleteKey(String keyId, Boolean forceDelete) { Boolean deleteForceParam = false; if (forceDelete != null) { deleteForceParam = forceDelete; } DeleteKeyOptions deleteKeyOptionsModel = new DeleteKeyOptions.Builder() .bluemixInstance("<instance_id>") .id(keyId) .force(deleteForceParam) .build(); Response<DeleteKey> response = testClient.deleteKey(deleteKeyOptionsModel).execute(); DeleteKey result = response.getResult(); return result; // null result on success }
Response
The base schema for deleting keys.
The metadata that describes the resource array.
A collection of resources.
Status Code
The key was successfully deleted. The status code is the only response, unless the
prefer
parameter containsreturn=representation
.The key was successfully deleted. No content. The status code is the only response, unless the
prefer
parameter containsreturn=representation
.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 Key Protect. Learn more.
The key could not be found.
There are three possible causes for HTTP 409 while trying to delete a key, specifying a reason code (resouces[0].reasons[0].code) as follows:
AUTHORIZATIONS_NOT_MET: The key cannot be deleted because it failed the dual authorization request. Before you delete this key, make sure dual authorization procedures are followed. See the topic, Deleting keys using dual authorization.
PROTECTED_RESOURCE_ERR: The key cannot be deleted because the key has one or more associated resources. See the topic, Considerations before deleting and purging a key.
PREV_KEY_DEL_ERR: 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. See the topic, Considerations before deleting and purging a key.
The requested key was previously deleted and is no longer available. Delete references to this key.
Too many requests. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "fadedbee-0000-0000-0000-1234567890ab", "name": "Root-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 5, "extractable": false, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:fadedbee-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "YYYY-MM-DDTHH:mm:SSZ", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "YYYY-MM-DDTHH:mm:SSZ", "lastRotateDate": "YYYY-MM-DDTHH:mm:SSZ", "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:mm:SSZ" }, "deleted": true, "deletionDate": "YYYY-MM-DDTHH:mm:SSZ", "deletedBy": "IBMid-0000000000", "restoreAllowed": true, "restoreExpirationDate": "YYYY-MM-DDTHH:mm:SSZ", "purgeAllowed": false, "purgeAllowedFrom": "YYYY-MM-DDTHH:mm:SSZ", "purgeScheduledOn": "YYYY-MM-DDTHH:mm:SSZ" } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: The key cannot be deleted due to a malformed, invalid, or missing ID." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unauthorized: The user does not have access to the specified resource." } ] }
{ "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 Key Protect. [Learn more](/docs/key-protect?topic=key-protect-integrate-services#grant-access)" } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: The key could not be found. KEY_NOT_FOUND_ERR: Key does not exist" } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Key could not be deleted. See '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/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: The requested key was previously deleted and is no longer available. Delete references to this key." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. 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 Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID or alias that uniquely identifies the key.
curl -X GET https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/metadata -H 'accept: application/vnd.ibm.kms.key+json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication keyMetadata, err := api.GetKeyMetadata(context.Background(), <key_ID|alias>) if err != nil { fmt.Println("Error while retrieving key metadata: ", err) return } b, _ := json.MarshalIndent(keyMetadata, "", " ") fmt.Println(string(b)) }
public static GetKeyMetadata getKeyMetadata(String keyId) { GetKeyMetadataOptions getKeyMetadataOptionsModel = new GetKeyMetadataOptions.Builder() .id(keyId) .bluemixInstance("<instance_id>") .build(); Response<GetKeyMetadata> response = testClient.getKeyMetadata(getKeyMetadataOptionsModel).execute(); GetKeyMetadata metadata = response.getResult(); return metadata; }
Response
The base schema for retrieving key metadata.
The metadata that describes the resource array.
A collection of resources.
Status Code
The key metadata was successfully retrieved.
The key metadata could not be retrieved due to a malformed, invalid, or missing ID or alias.
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 Key Protect. Learn more.
The key metadata for the key with specified ID could not be found.
Too many requests. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "fadedbee-0000-0000-0000-1234567890ab", "name": "Standard-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 1, "extractable": true, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:fadedbee-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "YYYY-MM-DDTHH:mm:SSZ", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "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: The user does not have access to the specified resource." } ] }
{ "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 Key Protect. [Learn more](/docs/key-protect?topic=key-protect-integrate-services#grant-access)" } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Key metadata could not be retrieved. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later." } ] }
Purge a deleted key
Purges all key metadata and registrations associated with the specified key. This method requires setting the KeyPurge permission that is not enabled by default. Purging a key can only be applied to a key in the Destroyed (5) state. After a key is deleted, there is a wait period of up to four hours before purge key operation is allowed. Important: When you purge a key, you permanently shred its contents and associated data. The action cannot be reversed.
DELETE /api/v2/keys/{id}/purge
Request
Custom Headers
The IBM Cloud instance ID that identifies your Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.Alters server behavior for POST or DELETE operations. A header with
return=minimal
causes the service to return only the key identifier as metadata. A header containingreturn=representation
returns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Key Protect may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequentGET /keys/{id}
request.Allowable values: [
return=representation
,return=minimal
]
Path Parameters
The v4 UUID or alias that uniquely identifies the key.
curl -X DELETE https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/purge -H 'accept: application/vnd.ibm.kms.key+json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication purgedKey, err := api.PurgeKey(context.Background(), <key_ID>, kp.ReturnRepresentation) if err != nil { fmt.Println("Error while purging key : ", err) return } b, _ := json.MarshalIndent(purgedKey, "", " ") fmt.Println(string(b)) }
Response
The base schema for purged key.
The metadata that describes the resource array.
A collection of resources.
Status Code
The key was successfully purged.
The key was successfully purged. No content.
The key cannot be purged due to a malformed ID.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.
The key could not be found.
There are two possible causes for HTTP 409 while trying to delete a key, specifying a reason code (resouces[0].reasons[0].code) as follows: REQ_TOO_EARLY_ERR: The key could not be purged due to wait period of four hours has not been reached. KEY_ACTION_INVALID_STATE_ERR: The key could not be purged because it is not in the Destroyed (5) state.
Too many requests. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "fadedbee-0000-0000-0000-1234567890ab", "name": "Root-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 5, "extractable": false, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:fadedbee-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "YYYY-MM-DDTHH:mm:SSZ", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "YYYY-MM-DDTHH:mm:SSZ", "lastRotateDate": "YYYY-MM-DDTHH:mm:SSZ", "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:mm:SSZ" }, "deleted": true, "deletionDate": "YYYY-MM-DDTHH:mm:SSZ", "deletedBy": "IBMid-0000000000", "purgeAllowed": true, "purgeAllowedFrom": "YYYY-MM-DDTHH:mm:SSZ", "purgeScheduledOn": "YYYY-MM-DDTHH:mm:SSZ" } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: The key cannot be purged due to a malformed ID." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unauthorized: The user does not have access to the specified resource." } ] }
{ "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 Key Protect. [Learn more](/docs/key-protect?topic=key-protect-integrate-services#grant-access)" } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: The key could not be found. KEY_NOT_FOUND_ERR: Key does not exist" } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Key could not be purged. See 'reasons' for more details.", "reasons": [ { "code": "KEY_INVALID_STATE_ERR", "message": "Key is not in a valid state.", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later." } ] }
Request
Custom Headers
The IBM Cloud instance ID that identifies your Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.Alters server behavior for POST or DELETE operations. A header with
return=minimal
causes the service to return only the key identifier as metadata. A header containingreturn=representation
returns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Key Protect may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequentGET /keys/{id}
request.Allowable values: [
return=representation
,return=minimal
]
Path Parameters
The v4 UUID or alias that uniquely identifies the key.
The base request parameters for restore key action.
A collection of resources.
curl -X POST https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/restore -H 'accept: application/json' -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://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/restore -H 'accept: application/json' -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" } ] }'
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication restoredKey, err := api.RestoreKey(context.Background(), <key_ID>) if err != nil { fmt.Println("Error while restoring key: ", err) return } b, _ := json.MarshalIndent(restoredKey, "", " ") fmt.Println(string(b)) }
public static KeyActionOneOfResponse restoreKey(String keyId) { InputStream inputStream = null; ActionOnKeyOptions restoreKeyOptionsModel = null; Response<KeyActionOneOfResponse> response = null; KeyActionOneOfResponse responseObj = null; try { // Only imported root keys can be restored; if the file conforms to the // SecureRestoreKeyRequestBody format, include the encryption method, // encrypted payload, encrypted nonce, and initialization vector. inputStream = new FileInputStream("/path/to/file.txt"); restoreKeyOptionsModel = new ActionOnKeyOptions.Builder() .id(keyId) .bluemixInstance("<INSTANCE_ID>") .action("restore") .keyActionOneOf(inputStream) .prefer("return=minimal") .build(); } catch(FileNotFoundException e) { System.out.println("File not found: " + e.toString()); return responseObj; } response = testClient.actionOnKey(restoreKeyOptionsModel).execute(); responseObj = response.getResult(); return responseObj; }
Response
Properties associated with a key response.
The metadata that describes the resource array.
A collection of resources.
Status Code
The key was successfully restored.
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.
There are three possible causes for HTTP 409 while trying to restore a key, specifying a reason code (resouces[0].reasons[0].code) as follows: KEY_ACTION_INVALID_STATE_ERR: The requested key is not in the
Destroyed
(5) state. REQ_TOO_EARLY_ERR: Key could not be restored. The key was updated recently, wait and try again. Restoring a key is only allowed when 30 seconds after key is deleted has passed. KEY_RING_RESOURCE_QUOTA_ERR: Key could not be restored. The resource quota for key rings in this instance has been reached and key rings cannot be created.Too many requests. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "fadedbee-0000-0000-0000-1234567890ab", "name": "Root-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 1, "extractable": false, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:fadedbee-0000-0000-0000-1234567890ab", "imported": true, "creationDate": "YYYY-MM-DDTHH:mm:SSZ", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "YYYY-MM-DDTHH:mm:SSZ", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab", "creationDate": "YYYY-MM-DDTHH:mm:SSZ" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:mm:SSZ" }, "deleted": false } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unauthorized: The user does not have access to the specified resource." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Key could not be restored. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Key could not be restored. 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/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later." } ] }
List key versions
Retrieves all versions of a root key by specifying the ID or alias 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 Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID or alias that uniquely identifies the key.
Query Parameters
The number of key versions to retrieve. By default,
GET /versions
returns the first 200 key versions. To retrieve a different set of key versions, uselimit
withoffset
to page through your available resources. The maximum value forlimit
is 5,000. Usage: If you have a key with 20 versions in your instance, and you want to retrieve only the first 5 versions, use../versions?limit=5
.Possible values: 1 ≤ value ≤ 5000
Default:
200
The number of key versions to skip. By specifying
offset
, you retrieve a subset of key versions that starts with theoffset
value. Useoffset
withlimit
to page through your available resources. Usage: If you have a key with 100 versions in your instance, and you want to retrieve versions 26 through 50, use../versions?offset=25&limit=25
.Possible values: value ≥ 0
Default:
0
If set to
true
, returnstotalCount
in the response metadata for use with pagination. ThetotalCount
value returned specifies the total number of key versions that match the request, disregarding limit and offset. The default is set to false. Usage: To return thetotalCount
value for use with pagination, use../versions?totalCount=true
.If set to
true
, returns the key versions of a key in any state. Usage: If you have deleted a key and still want to retrieve its key versions use../versions?allKeyStates=true
.Default:
false
curl -X GET https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/versions -H 'accept: application/vnd.ibm.kms.key.version+json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
public static List<KeyVersion> getKeyVersions(String keyId) { GetKeyVersionsOptions getKeyVersionsOptionsModel = new GetKeyVersionsOptions.Builder() .id(keyId) .bluemixInstance("<instance_id>") .build(); Response<ListKeyVersions> response = testClient.getKeyVersions(getKeyVersionsOptionsModel ).execute(); List<KeyVersion> details = response.getResult().getResources(); return details; }
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication limit := uint32(2) offset := uint32(0) totalCount := true listkeyVersionsOptions := &kp.ListKeyVersionsOptions{ Limit : &limit, Offset : &offset, TotalCount : &totalCount, } keyVersions, err := client.ListKeyVersions(ctx, "key_id_or_alias", listkeyVersionsOptions) if err != nil { fmt.Println(err) } fmt.Println(keyVersions) }
Response
Properties associated with a registration response.
An array of resources.
Status Code
The list of key versions was successfully retrieved.
The request is missing a required field.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
The key could not be found.
The key is not in an active state.
The requested key was previously deleted and is no longer available. Delete references to this key.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 2, "totalCount": 4 }, "resources": [ { "id": "fadedbee-0000-0000-0000-1234567890ab", "creationDate": "YYYY-MM-DDTHH:mm:SSZ" }, { "id": "addedace-0000-0000-0000-1234567890ab", "creationDate": "YYYY-MM-DDTHH:mm:SSZ" } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unauthorized: The user does not have access to the specified resource." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: The key could not be found. KEY_NOT_FOUND_ERR: Key does not exist" } ] }
{ "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. Delete references to this key." } ] }
Wrap a key
Use a root key to wrap or encrypt a data encryption key. When present, the ciphertext contains the DEK wrapped by the latest version of the key (WDEK). It is recommended to store and use this WDEK in future calls to Key Protect.
POST /api/v2/keys/{id}/actions/wrap
Request
Custom Headers
The IBM Cloud instance ID that identifies your Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID or alias that uniquely identifies the key.
The base request for wrap key action.
The data encryption key (DEK) used in wrap actions when the query parameter is set to
wrap
. The system returns a base64 encoded plaintext in the response entity-body when you perform anunwrap
action on a key. To wrap an existing DEK, provide a base64 encoded plaintext during awrap
action. To generate a new DEK, omit theplaintext
property. Key Protect generates a random plaintext (32 bytes) that is rooted in an HSM and then wraps that value. Note: When you unwrap a wrapped data encryption key (WDEK) by using a rotated root key, the service returns a new ciphertext in the response entity-body. Each ciphertext remains available forunwrap
actions. If you unwrap a DEK with a previous ciphertext, the service also returns the latest ciphertext in the response. Use the latest ciphertext for future unwrap operations.Possible values: length ≤ 4096
The additional authentication data (AAD) used to further secure the key. If you supply AAD when you make a
wrap
call, you must specify the same AAD during a subsequentunwrap
call.Possible values: 0 ≤ number of items ≤ 126, 0 ≤ length ≤ 255
curl -X POST https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/actions/wrap -H 'accept: application/json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'content-type: application/vnd.ibm.kms.key_action_wrap+json'
curl -X POST https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/actions/wrap -H 'accept: application/json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'content-type: application/vnd.ibm.kms.key_action_wrap+json' -d '{ "plaintext": "<data_key>", "aad": ["<additional_data>", "<additional_data>"] }'
package main import ( "context" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication aad := []string{"<additional_data>", "<additional_data>"} plaintext := []byte(<data_key>) ciphertext, err := api.Wrap(context.Background(), <key_ID>, plaintext, &aad) if err != nil { fmt.Println("Error wrapping the key: ", err) return } fmt.Println(string(ciphertext)) }
// Initialize the Key Protect client as specified in Authentication // Wrap and unwrap base64 encoded plaintext using key const samplePlaintext = 'dGhpcyBpcyBhIGJhc2U2NCBzdHJpbmcK'; // base64 encoded plaintext const wrapKeyParams = Object.assign({}, envConfigs); wrapKeyParams.id = "<key_ID_or_alias>"; wrapKeyParams.keyActionWrapBody = { plaintext: samplePlaintext, }; const response = keyProtectClient.wrapKey(wrapKeyParams); console.log('Wrap key response cipher: ' + response.result.ciphertext); const ciphertextResult = response.result.ciphertext; // saved for the unwrap example
import os import keyprotect from keyprotect import bxauth # Initialize the Key Protect client as specified in Authentication key = kp.create(name="MyRootKey", root=True) # payload should be a bytestring message = b'This is an important test message.' wrapped = kp.wrap(key.get('id'), message) ciphertext = wrapped.get("ciphertext")
Response
Properties that are associated with the response body of a wrap action.
The wrapped data encryption key (WDEK) that you can export to your app or service. The ciphertext contains the DEK wrapped by the latest version of the key (WDEK). It is recommended to store and use this WDEK in future calls to Key Protect. The value is base64 encoded.
The data encryption key (DEK) used in wrap actions when the query parameter is set to
wrap
. The system returns a base64 encoded plaintext in the response entity-body when you perform anunwrap
action on a key. To wrap an existing DEK, provide a base64 encoded plaintext during awrap
action. To generate a new DEK, omit theplaintext
property. Key Protect generates a random plaintext (32 bytes) that is rooted in an HSM and then wraps that value. Note: When you unwrap a wrapped data encryption key (WDEK) by using a rotated root key, the service returns a new ciphertext in the response entity-body. Each ciphertext remains available forunwrap
actions. If you unwrap a DEK with a previous ciphertext, the service also returns the latest ciphertext in the response. Use the latest ciphertext for future unwrap operations.Possible values: length ≤ 4096
The key version that was used to wrap the DEK. This key version is associated with the
ciphertext
value that was used in the request.The ID of the key version.
Example:
fadedbee-0000-0000-0000-1234567890ab
keyVersion
Status Code
The key was successfully wrapped.
The request is malformed or illegal.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
The key could not be found.
The key is not in the
Active
(1) state.The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using
POST /keys/{id}/restore
.Too many requests. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "plaintext": "tF9ss0W9HQUVkddcjSeGg/MqZFs2CVh/FFKLPLLnOwY=", "ciphertext": "eyJjaXBoZXJ0ZXh0Ijoic1ZZRnZVcjdQanZXQ0tFakMwRFFWZktqQ3AyRmtiOFJOSDJSTkpZRzVmU1hWNDJScD\\ RDVythU0h3Y009IiwiaGFzaCI6IjVWNzNBbm9XdUxxM1BvZEZpd1AxQTdQMUZrTkZOajVPMmtmMkNxdVBxL0NRdFlOZnBvemp\\ iYUxjRDNCSWhxOGpKZ2JNR0xhMHB4dDA4cTYyc0RJMGRBPT0iLCJpdiI6Ilc1T2tNWFZuWDFCTERDUk51M05EUlE9PSIsInZl\\ cnNpb24iOiIzLjAuMCIsImhhbmRsZSI6IjRkZjg5ZGVlLWU3OTMtNGY5Ny05MGNjLTc1ZWQ5YjZlNWM4MiJ9", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab" } }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Wrap with key could not be performed. 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/key-protect", "target": { "type": "field", "name": "plaintext" } } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unauthorized: The user does not have access to the specified resource." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Wrap with key could not be performed. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist.", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Wrap with key could not be performed. 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/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Wrap with key could not be performed. See 'reasons' for more details.", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Delete references to this key.", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. 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 Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID or alias that uniquely identifies the key.
The base request for unwrap key action.
The wrapped data encryption key (WDEK) that you can export to your app or service. The ciphertext contains the DEK wrapped by the latest version of the key (WDEK). It is recommended to store and use this WDEK in future calls to Key Protect. The value is base64 encoded.
The additional authentication data (AAD) used to further secure the key. If you supply AAD when you make a
wrap
call, you must specify the same AAD during a subsequentunwrap
call.Possible values: 0 ≤ number of items ≤ 126, 0 ≤ length ≤ 255
curl -X POST https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/actions/unwrap -H 'accept: application/json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'content-type: application/vnd.ibm.kms.key_action_unwrap+json' -d '{ "ciphertext": "<encrypted_data_key>", "aad": ["<additional_data>", "<additional_data>"] }'
package main import ( "context" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication aad := []string{"<additional_data>", "<additional_data>"} ciphertext := []byte(<encrypted_data_key>) pt2, err := api.Unwrap(context.Background(), <key_ID>, ciphertext, &aad) if err != nil { fmt.Println("Error while unwrapping DEK: ", err) return } b, _ := json.MarshalIndent(pt2, "", " ") fmt.Println(string(b)) }
// Initialize the Key Protect client as specified in Authentication const unwrapKeyParams = Object.assign({}, envConfigs); unwrapKeyParams.id = "<key_ID_or_alias>"; unwrapKeyParams.keyActionUnwrapBody = { ciphertext: ciphertextResult, // encrypted result from wrap key response }; const response = keyProtectClient.unwrapKey(unwrapKeyParams); console.log('Unwrap key response result: ' + response.result.plaintext); // validate that result is same as above
import os import keyprotect from keyprotect import bxauth # Continue from example for wrap key # key = kp.create(name="MyRootKey", root=True) # message = b'This is a really important message.' unwrapped = kp.unwrap(key.get('id'), ciphertext) assert message == unwrapped
Response
Properties that are associated with the response body of an unwrap action.
The data encryption key (DEK) used in wrap actions when the query parameter is set to
wrap
. The system returns a base64 encoded plaintext in the response entity-body when you perform anunwrap
action on a key. To wrap an existing DEK, provide a base64 encoded plaintext during awrap
action. To generate a new DEK, omit theplaintext
property. Key Protect generates a random plaintext (32 bytes) that is rooted in an HSM and then wraps that value. Note: When you unwrap a wrapped data encryption key (WDEK) by using a rotated root key, the service returns a new ciphertext in the response entity-body. Each ciphertext remains available forunwrap
actions. If you unwrap a DEK with a previous ciphertext, the service also returns the latest ciphertext in the response. Use the latest ciphertext for future unwrap operations.Possible values: length ≤ 4096
The wrapped data encryption key (WDEK) that you can export to your app or service. The ciphertext contains the DEK wrapped by the latest version of the key (WDEK). It is recommended to store and use this WDEK in future calls to Key Protect. The value is base64 encoded.
The key version that was used to wrap the DEK. This key version is associated with the
ciphertext
value that was used in the request.The ID of the key version.
Example:
fadedbee-0000-0000-0000-1234567890ab
keyVersion
The latest key version that was used to rewrap the DEK. This key version is associated with the
ciphertext
value that's returned in the response.The ID of the key version.
Example:
fadedbee-0000-0000-0000-1234567890ab
rewrappedKeyVersion
Status Code
Successfully unwrapped key.
The request is malformed or illegal.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
The key could not be found.
The key is not in the
Active
(1) orDeactivated
(3) state.The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using
POST /keys/{id}/restore
.The ciphertext provided was not wrapped by this key.
Too many requests. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "plaintext": "tF9ss0W9HQUVkddcjSeGg/MqZFs2CVh/FFKLPLLnOwY=", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab" } }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Unwrap with key could not be performed. See 'reasons' for more details.", "reasons": [ { "code": "MISSING_FIELD_ERR", "message": "The field 'ciphertext' is required.", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect", "target": { "type": "field", "name": "name" } } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unauthorized: The user does not have access to the specified resource." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Unwrap with key could not be performed. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Wrap action could not be performed with the key. 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/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Unwrap with key could not be performed. See 'reasons' for more details.", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Delete references to this key.", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unprocessable Entity: Unwrap with key could not be performed. 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/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later." } ] }
Rewrap a key
Use a root key to rewrap or reencrypt a data encryption key.
POST /api/v2/keys/{id}/actions/rewrap
Request
Custom Headers
The IBM Cloud instance ID that identifies your Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID or alias that uniquely identifies the key.
The base request for rewrap key action.
The wrapped data encryption key (WDEK) that you want to re-encrypt by using the latest key version. When present, the ciphertext contains the DEK wrapped by the latest version of the key (WDEK). It is recommended to use store and use this WDEK in future calls to Key Protect. The value must be base64 encoded.
The additional authentication data (AAD) used to further secure the key. If you supply AAD when you make a
wrap
call, you must specify the same AAD during a subsequentunwrap
call.Possible values: 0 ≤ number of items ≤ 126, 0 ≤ length ≤ 255
curl -X POST https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/actions/rewrap -H 'accept: application/json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'content-type: application/vnd.ibm.kms.key_action_rewrap+json' -d '{ "ciphertext": "<encrypted_data_key>", "aad": ["<additional_data>", "<additional_data>"] }'
Response
Properties that are associated with the response body of an rewrap action.
The wrapped data encryption key (WDEK) that you can export to your app or service. The ciphertext contains the DEK wrapped by the latest version of the key (WDEK). It is recommended to store and use this WDEK in future calls to Key Protect. The value is base64 encoded.
The key version that was used to wrap the DEK. This key version is associated with the
ciphertext
value that was used in the request.The ID of the key version.
Example:
fadedbee-0000-0000-0000-1234567890ab
keyVersion
The latest key version that was used to rewrap the DEK. This key version is associated with the
ciphertext
value that's returned in the response.The ID of the key version.
Example:
fadedbee-0000-0000-0000-1234567890ab
rewrappedKeyVersion
Status Code
The key was successfully rewrapped.
The request is malformed or illegal.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
The key could not be found.
The key is not in the
Active
(1) orDeactivated
(3) state.The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using
POST /keys/{id}/restore
.The ciphertext provided was not wrapped by this key.
Too many requests. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "ciphertext": "eyJjaXBoZXJ0ZXh0Ijoic1ZZRnZVcjdQanZXQ0tFakMwRFFWZktqQ3AyRmtiOFJOSDJSTkpZRzVmU1hWNDJScD\\ RDVythU0h3Y009IiwiaGFzaCI6IjVWNzNBbm9XdUxxM1BvZEZpd1AxQTdQMUZrTkZOajVPMmtmMkNxdVBxL0NRdFlOZnBvemp\\ iYUxjRDNCSWhxOGpKZ2JNR0xhMHB4dDA4cTYyc0RJMGRBPT0iLCJpdiI6Ilc1T2tNWFZuWDFCTERDUk51M05EUlE9PSIsInZl\\ cnNpb24iOiIzLjAuMCIsImhhbmRsZSI6IjRkZjg5ZGVlLWU3OTMtNGY5Ny05MGNjLTc1ZWQ5YjZlNWM4MiJ9", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab" }, "rewrappedKeyVersion": { "id": "addedace-0000-0000-0000-1234567890ab" } }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Rewrap with key could not be performed. 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/key-protect", "target": { "type": "field", "name": "ciphertext" } } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unauthorized: The user does not have access to the specified resource." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Rewrap with key could not be performed. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Rewrap with key could not be performed. 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/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Rewrap with key could not be performed. See 'reasons' for more details.", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Delete references to this key.", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unprocessable Entity: Rewrap with key could not be performed. 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/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later." } ] }
Request
Custom Headers
The IBM Cloud instance ID that identifies your Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.Alters server behavior for POST or DELETE operations. A header with
return=minimal
causes the service to return only the key identifier as metadata. A header containingreturn=representation
returns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Key Protect may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequentGET /keys/{id}
request.Allowable values: [
return=representation
,return=minimal
]
Path Parameters
The v4 UUID or alias that uniquely identifies the key.
The base request for rotate key action.
The key material that you want to import into the service for rotating an existing root key. This value is required for a
rotate
action if you initially imported the key material when you created the key. To rotate an imported root key, provide a base64 encoded payload in the request entity-body. To rotate a root key that was initially generated by Key Protect, omit thepayload
property and pass in an empty request entity-body.
curl -X POST https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/actions/rotate -H 'accept: application/json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
curl -X POST https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/actions/rotate -H 'accept: application/json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'content-type: application/vnd.ibm.kms.key_action_rotate+json' -d '{ "payload": "<new_key_material>" }'
curl -X POST https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/actions/rotate -H 'accept: application/json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'content-type: application/vnd.ibm.kms.key_action_rotate+json' -d '{ "payload": "<encrypted_new_key_material>", "encryptedNonce": "<encrypted_nonce>", "iv": "<iv>", "encryptionAlgorithm": "RSAES_OAEP_SHA_256" }'
package main import ( "context" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication // Set the payload to a base64 encoded string if your key is an imported root key // Skip setting payload if your key is a generated root key payload := "<new_key_material>" err = api.Rotate(context.Background(), <key_ID> , payload) if err != nil { fmt.Println("Error rotating the key: ", err) return } fmt.Println("Key successfully rotated") }
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.
There are three possible causes for HTTP 404 while trying to rotate a key, specifying a reason code (resouces[0].reasons[0].code) as follows: KEY_NOT_FOUND_ERR: The key could not be found. INSTANCE_NOT_FOUND_ERR: Key could not be rotated, specified instance does not exist. IMPORT_TOKEN_NOT_FOUND_ERR: Key could not be rotated, import_token does not exist.
There are four possible causes for HTTP 409 while trying to rotate a key, specifying a reason code (resouces[0].reasons[0].code) as follows: KEY_ACTION_INVALID_STATE_ERR: The requested key is not in the
Active
(1) orDeactivated
(3) state. KEY_ROTATION_NOT_PERMITTED: Key could not be rotated, this key has been rotated within the last hour, only one rotate action per hour is permitted. KEY_CREATE_IMPORT_ACCESS_ERR: Instance policy does not allow this action. IMPORT_TOKEN_EXPIRED_ERR: Key could not be rotated, the import token has expired.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. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Key could not be rotated. 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/key-protect", "target": { "type": "field", "name": "payload" } } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unauthorized: The user does not have access to the specified resource." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Key could not be rotated. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Key could not be rotated. 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/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Key could not be rotated. See 'reasons' for more details.", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Delete references to this key.", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. 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 Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID or alias that uniquely identifies the key.
curl -X POST https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/actions/setKeyForDeletion -H 'accept: application/json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication err := api.InitiateDualAuthDelete(context.Background(), <key_ID>) if err != nil { fmt.Println("Error while initiating dual auth delete for key: ", err) return } fmt.Println("Key successfully initiated for dual auth delete") }
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.
There are two possible causes for HTTP 404 while trying to set a key for deletion, specifying a reason code (resouces[0].reasons[0].code) as follows: KEY_NOT_FOUND_ERR: The key could not be found. DUAL_AUTH_POLICY_NOT_FOUND_ERR: Dual authorization policy is not enabled for this key.
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. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unauthorized: The user does not have access to the specified resource." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Key deletion could not be scheduled. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Key deletion could not be scheduled. 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/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Key deletion could not be scheduled. See 'reasons' for more details.", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Delete references to this key.", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. 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 Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID or alias that uniquely identifies the key.
curl -X POST https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/actions/unsetKeyForDeletion -H 'accept: application/json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication err := api.CancelDualAuthDelete(context.Background(), <key_ID>) if err != nil { fmt.Println("Error while cancelling dual auth delete for key: ", err) return } fmt.Println("Key successfully cancelled for dual auth delete") }
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.
There are two possible causes for HTTP 404 while trying to unset a key for deletion, specifying a reason code (resouces[0].reasons[0].code) as follows: KEY_NOT_FOUND_ERR: The key could not be found. DUAL_AUTH_POLICY_NOT_FOUND_ERR: Dual authorization policy is not enabled for this key.
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. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unauthorized: The user does not have access to the specified resource." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Key deletion could not be cancelled. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Key deletion could not be cancelled. 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/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Key deletion could not be cancelled. See 'reasons' for more details.", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Delete references to this key.", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later." } ] }
Request
Custom Headers
The IBM Cloud instance ID that identifies your Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID or alias that uniquely identifies the key.
curl -X POST https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/actions/enable -H 'accept: application/json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication err := api.EnableKey(context.Background(), <key_ID>) if err != nil { fmt.Println("Error while enabling the key: ", err) return } fmt.Println("Key successfully enabled") }
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.
There are two possible causes for HTTP 409 while trying to enable a key, specifying a reason code (resouces[0].reasons[0].code) as follows: KEY_ACTION_INVALID_STATE_ERR: The requested key is not in the
Suspended
(2) state or the state of the key has changed within the last 30 seconds. REQ_TOO_EARLY_ERR: Key could not be enabled, as the key was updated recently. After key is disabled, the event must fully propagate before enabling key operations. Wait and try again.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. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Key could not be enabled. 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/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unauthorized: The user does not have access to the specified resource." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Key could not be enabled. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist.", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Key could not be enabled. 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/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Key could not be enabled. See 'reasons' for more details.", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Delete references to this key.", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later." } ] }
Request
Custom Headers
The IBM Cloud instance ID that identifies your Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID or alias that uniquely identifies the key.
curl -X POST https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/actions/disable -H 'accept: application/json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication err := api.DisableKey(context.Background(), <key_ID>) if err != nil { fmt.Println("Error while disabling the key: ", err) return } fmt.Println("Key successfully disabled") }
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
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. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Key could not be disabled. 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/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unauthorized: The user does not have access to the specified resource." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Key could not be disabled. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Key could not be disabled. 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/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Key could not be disabled. See 'reasons' for more details.", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Delete references to this key.", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later." } ] }
Sync associated resources
Initiate a manual data synchronization request to the associated
resources of a key. Regular key lifecycle events automatically notify
integrated services of any change. However, in the case a service does
not respond to a key lifecycle event notification after four hours, the
sync
API may be used to initiate a renotification to the integrated
services that manage the associated resources linked to the key.
Note: The services that manage the associated resources linked to
the key are responsible for maintaining current records of the key
state and version. Key Protect does not have the ability to force data
synchronization for other services, which may take up to four hours to
complete. The sync
API is meant to initiate a request for all
associated resources to synchronize their key records with the
information returned from the Key Protect API.
POST /api/v2/keys/{id}/actions/sync
Request
Custom Headers
The IBM Cloud instance ID that identifies your Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID or alias that uniquely identifies the key.
curl -X POST https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/actions/sync -H 'accept: application/json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
Response
Status Code
The sync of associate resources for a key has been initiated. No content.
The request is malformed or illegal.
Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.
There are two possible causes for HTTP 404 for the synchronization request, the reason code (resources[0].reasons[0].code) as follows: KEY_NOT_FOUND: The specified key could not be found. NOT_SUPPORTED_IN_SATELLITE_LOCATION: The synchronization request for the specified key is not supported in this location.
The key has been synced or updated (i.e. rotated, restored, disabled, enabled, deleted) within the last hour.
Too many requests. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Associated resources could not be synced. 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/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unauthorized: The user does not have access to the specified resource." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Associated resources could not be synced. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Associated resources could not be synced. See 'reasons' for more details.", "reasons": [ { "code": "REQ_TOO_EARLY_ERR", "message": "The key was updated recently. Wait and try again.", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later." } ] }
Set key policies
Creates or updates one or more policies for the specified key.
You can set policies for a key, such as an
automatic rotation policy
or a
dual authorization policy
to protect against the accidental deletion of keys. Use
PUT /keys/{id}/policies
to create new policies for a key or update an
existing policy.
PUT /api/v2/keys/{id}/policies
Request
Custom Headers
The IBM Cloud instance ID that identifies your Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID or alias that uniquely identifies the key.
Query Parameters
The type of policy that is associated with the specified key.
Allowable values: [
dualAuthDelete
,rotation
]
The base request for key policy create or update.
A collection of resources.
curl -X PUT https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/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": { "enabled": <true|false>, "interval_month": <rotation_interval> } }, { "type": "application/vnd.ibm.kms.policy+json", "dualAuthDelete": { "enabled": <true|false> } } ] }'
curl -X PUT https://<region>.kms.cloud.ibm.com/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://<region>.kms.cloud.ibm.com/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": { "enabled": <true|false>, "interval_month": <rotation_interval> } } ] }'
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication // Pass setRotationPolicy as true if setting rotation policy otherwise false // Pass setDualAuthDeletePolicy as true if setting dual authorization policy otherwise false // Pass dualAuthEnabled as true to enable or false to disable the dual auth delete policy. policies, err := api.SetPolicies(context.Background(), <key_ID>, <setRotationPolicy>, <rotation_interval>, <setDualAuthDeletePolicy>, <dualAuthEnabled>) if err != nil { fmt.Println("Error while setting the policies: ", err) return } b, _ := json.MarshalIndent(policies, "", " ") fmt.Println(string(b)) }
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication policy, err := api.SetRotationPolicy(context.Background(), <key_ID>, <rotation_interval>) if err != nil { fmt.Println("Error while setting rotation policy: ", err) return } b, _ := json.MarshalIndent(policy, "", " ") fmt.Println(string(b)) }
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication // Pass enabled as true to set the policy and false to unset the policy policy, err := api.SetDualAuthDeletePolicy(context.Background(), <key_ID>, <enabled>) if err != nil { fmt.Println("Error while setting dual auth delete policy: ", err) return } b, _ := json.MarshalIndent(policy, "", " ") fmt.Println(string(b)) }
Response
The base schema for retrieving a dual authorization key policy.
A collection of resources.
The v4 UUID used to uniquely identify the policy resource, as specified by RFC 4122.
Specifies the MIME type that represents the policy resource. Currently, only the default is supported.
Possible values: [
application/vnd.ibm.kms.policy+json
]Example:
application/vnd.ibm.kms.policy+json
The Cloud Resource Name (CRN) that uniquely identifies your cloud resources.
Example:
crn:v1:bluemix:public:kms:<region>:a/<account-id>:<service-instance>:policy:<policy-id>
The date the policy was created. The date format follows RFC 3339.
Example:
YYYY-MM-DDTHH:mm:SSZ
The unique identifier for the resource that created the policy.
Updates when the policy is replaced or modified. The date format follows RFC 3339.
Example:
YYYY-MM-DDTHH:mm:SSZ
The unique identifier for the resource that updated the policy.
resources
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 Key Protect. Learn more.
The requested key was previously deleted and is no longer available. Delete references to this key.
The key with specified ID is invalid for use with policies.
A key must be a root key (non-extractable) in the Activated (1) state.
Too many requests. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 2 }, "resources": [ { "id": "feddecaf-0000-0000-0000-1234567890ab", "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:policy:feddecaf-0000-0000-0000-1234567890ab", "rotation": { "enabled": "<true|false>", "interval_month": 3 }, "createdBy": "IBMid-0000000000", "creationDate": "YYYY-MM-DDTHH:mm:SSZ", "updatedBy": "IBMid-0000000000", "lastUpdateDate": "YYYY-MM-DDTHH:mm:SSZ" }, { "id": "beadcafe-0000-0000-0000-1234567890ab", "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:policy:beadcafe-0000-0000-0000-1234567890ab", "dualAuthDelete": { "enabled": "<true|false>" }, "createdBy": "IBMid-0000000000", "creationDate": "YYYY-MM-DDTHH:mm:SSZ", "updatedBy": "IBMid-0000000000", "lastUpdateDate": "YYYY-MM-DDTHH:mm:SSZ" } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "id": "feddecaf-0000-0000-0000-1234567890ab", "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:policy:feddecaf-0000-0000-0000-1234567890ab", "dualAuthDelete": { "enabled": "<true|false>" }, "createdBy": "IBMid-0000000000", "creationDate": "YYYY-MM-DDTHH:mm:SSZ", "updatedBy": "IBMid-0000000000", "lastUpdateDate": "YYYY-MM-DDTHH:mm:SSZ" } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "id": "beadcafe-0000-0000-0000-1234567890ab", "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:policy:beadcafe-0000-0000-0000-1234567890ab", "rotation": { "enabled": "<true|false>", "interval_month": 3 }, "createdBy": "IBMid-0000000000", "creationDate": "YYYY-MM-DDTHH:mm:SSZ", "updatedBy": "IBMid-0000000000", "lastUpdateDate": "YYYY-MM-DDTHH:mm:SSZ" } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unauthorized: The user does not have access to the specified resource." } ] }
{ "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 Key Protect. [Learn more](/docs/key-protect?topic=key-protect-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. Delete references to this key." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Key policy could not be created. See `reasons` for more details.", "reasons": [ { "code": "KEY_INVALID_STATE_ERR", "message": "Key is not in a valid state", "status": 422, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. 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
Request
Custom Headers
The IBM Cloud instance ID that identifies your Key Protect service instance.
The v4 UUID used to correlate and track transactions.
The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an
X-Kms-Key-Ring
header is:default
.
Path Parameters
The v4 UUID or alias that uniquely identifies the key.
Query Parameters
The type of policy that is associated with the specified key.
Allowable values: [
dualAuthDelete
,rotation
]
curl -X GET https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/policies -H 'accept: application/vnd.ibm.kms.policy+json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
curl -X GET https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/policies?policy=dualAuthDelete -H 'accept: application/vnd.ibm.kms.policy+json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
curl -X GET https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/policies?policy=rotation -H 'accept: application/vnd.ibm.kms.policy+json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>'
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication policies, err := api.GetPolicies(context.Background(), <key_ID>) if err != nil { fmt.Println("Error while getting policies: ", err) return } b, _ := json.MarshalIndent(policies, "", " ") fmt.Println(string(b)) }
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication policy, err := api.GetRotationPolicy(context.Background(), <key_ID>) if err != nil { fmt.Println("Error while getting rotation policy: ", err) return } b, _ := json.MarshalIndent(policy, "", " ") fmt.Println(string(b)) }
package main import ( "context" "encoding/json" "fmt" kp "github.com/IBM/keyprotect-go-client" ) func main() { // Initialize the Key Protect client as specified in Authentication policy, err := api.GetDualAuthDeletePolicy(context.Background(), <key_ID>) if err != nil { fmt.Println("Error while getting dual auth delete policy: ", err) return } b, _ := json.MarshalIndent(policy, "", " ") fmt.Println(string(b)) }
Response
The base schema for retrieving a dual authorization key policy.
A collection of resources.
The v4 UUID used to uniquely identify the policy resource, as specified by RFC 4122.
Specifies the MIME type that represents the policy resource. Currently, only the default is supported.
Possible values: [
application/vnd.ibm.kms.policy+json
]Example:
application/vnd.ibm.kms.policy+json
The Cloud Resource Name (CRN) that uniquely identifies your cloud resources.
Example:
crn:v1:bluemix:public:kms:<region>:a/<account-id>:<service-instance>:policy:<policy-id>
The date the policy was created. The date format follows RFC 3339.
Example:
YYYY-MM-DDTHH:mm:SSZ
The unique identifier for the resource that created the policy.
Updates when the policy is replaced or modified. The date format follows RFC 3339.
Example:
YYYY-MM-DDTHH:mm:SSZ
The unique identifier for the resource that updated the policy.
resources
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 Key Protect. Learn more.
The key could not be found.
Too many requests. Wait a few minutes and try again.
IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the
correlation-ID
in the response header and contact IBM Cloud support.
{ "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 2 }, "resources": [ { "id": "feddecaf-0000-0000-0000-1234567890ab", "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:policy:feddecaf-0000-0000-0000-1234567890ab", "rotation": { "enabled": "<true|false>", "interval_month": 3 }, "createdBy": "IBMid-0000000000", "creationDate": "YYYY-MM-DDTHH:mm:SSZ", "updatedBy": "IBMid-0000000000", "lastUpdateDate": "YYYY-MM-DDTHH:mm:SSZ" }, { "id": "beadcafe-0000-0000-0000-1234567890ab", "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:policy:beadcafe-0000-0000-0000-1234567890ab", "dualAuthDelete": { "enabled": "<true|false>" }, "createdBy": "IBMid-0000000000", "creationDate": "YYYY-MM-DDTHH:mm:SSZ", "updatedBy": "IBMid-0000000000", "lastUpdateDate": "YYYY-MM-DDTHH:mm:SSZ" } ] }