| copyright | years | lastupdated | keywords | subcollection |
|---|---|---|---|---|
2020, 2025 |
2025-01-15 |
Key Protect, error messages, error codes |
key-protect |
{:shortdesc: .shortdesc} {:screen: .screen} {:pre: .pre} {:table: .aria-labeledby="caption"} {:external: target="_blank" .external} {:codeblock: .codeblock} {:tip: .tip} {:note: .note} {:important: .important} {:term: .term}
{: #error-messages}
These error messages are created by {{site.data.keyword.keymanagementserviceshort}} and shown in the user interface (UI). {: shortdesc}
Most error messages have one or more examples, usually curl, that show the
request and response.
This is not a complete list of error messages. Some messages are created by other systems, such as identity and access management (IAM), where the error message is passed from another system, such as IAM, to {{site.data.keyword.keymanagementserviceshort}} to the user. {: note}
{: #error-messages-table-of-contents}
The table of contents is sorted by the error message.
-
The first list sorts the error messages by HTTP status code
-
Another list sorts the error messages by reason code
Some error messages occur more than once, in those cases the HTTP status code is included at the end of the error message.
- Collection total does not match number... details
- Data in body does not match data required... details
- Extracting the subject from the bearer... details
- Invalid body data was passed... details
- Invalid field error... details
- Key could not be deleted... details
- Key has already been deleted... details
- Key is not in a valid state (409) details
- Key is not in a valid state (422) details
- Key is protecting one or more cloud... details
- Key metadata became corrupted... details
- Key restoration has expired details
- KeyCreateImportAccess instance policy... details
- Missing body in request details
- Number of authorizations required to... details
- Only a single instance policy may be... details
- Only imported keys may be restored details
- Requested action can only be completed with a root key (400) details
- Requested action can only be completed with a root key (422) details
- Requested change is not compliant with configuration rules details
- Signature is invalid details
- The action could not be performed on... details
- The encrypted nonce given does not match... details
- The import token has expired details
- The key cannot be deleted because it's... details
- The key is not dual auth enabled and... details
- The key was updated recently details
- The provided ciphertext is invalid or... details
- The provided encrypted nonce was not... details
- The resource(s) queried does not belong to the service. details
- This action can only be done by a service... details
- This action is not permitted on this... details
- This request requires that the key version... details
- This root key has been rotated within... details
- This root key was created with user-supplied... details
- Unauthorized: The user does not have... details
{: #error-messages-collection-total-mismatch-err}
{: #error-messages-collection-total-mismatch-err-message}
Collection total does not match number of resources
Reason code: COLLECTION_TOTAL_MISMATCH_ERR
{: #error-messages-collection-total-mismatch-err-http}
400 - Bad Request
The HTTP 400 Bad Request response status code indicates that the server cannot
or will not process the request due to something that is perceived to be a
client error (e.g., malformed request syntax, invalid request message framing,
or deceptive request routing).
The client should not repeat this request without modification.
{: #error-messages-collection-total-mismatch-err-context}
This error occurs when an instance policy{: external} is created.
The value of the metadata.collectionTotal field does not match the number of
resources in the resources array.
The create instance policy request fails because the
metadata.collectionTotal is 2, while 1 (one) resource was provided in the
resources array.
# this request fails because the collectionTotal is 2 and there is 1 (one) resource
$ curl -X PUT \
"https://us-south.kms.cloud.ibm.com/api/v2/instance/policies?policy=dualAuthDelete" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.policy+json" \
-d '{
"metadata": {
"collectionType": "application/vnd.ibm.kms.policy+json",
"collectionTotal": 2
},
"resources": [
{
"policy_type": "dualAuthDelete",
"policy_data": {
"enabled": false
}
}
]
}'{: codeblock}
{: #error-messages-collection-total-mismatch-err-cxt-json}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources":[
{
"errorMsg": "Bad Request: Instance policy could not be created. Please see `reasons` for more details.",
"reasons": [
{
"code": "COLLECTION_TOTAL_MISMATCH_ERR",
"message": "Collection total does not match number of resources",
"status": 400,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: screen}
{: #error-messages-body-query-param-mismatch-err}
{: #error-messages-body-query-param-mismatch-err-message}
Data in body does not match data required by query parameter
Reason code: BODY_QUERY_PARAM_MISMATCH_ERR
{: #error-messages-body-query-param-mismatch-err-http}
400 - Bad Request
The HTTP 400 Bad Request response status code indicates that the server cannot
or will not process the request due to something that is perceived to be a
client error (e.g., malformed request syntax, invalid request message framing,
or deceptive request routing).
The client should not repeat this request without modification.
{: #error-messages-body-query-param-mismatch-err-cxt}
This error occurs when an instance policy{: external} is created.
The query parameter, which specifies the policy (dualAuthDelete, allowedNetwork,
or allowedIP), does not match the first policy_type in the resources
array.
The create instance policy request fails because the policy query parameter
(dualAuthDelete) does not match the resources.policy_type (badName).
# this request fails because the query parameter does not match the resource
$ curl -X PUT \
"https://us-south.kms.cloud.ibm.com/api/v2/instance/policies?policy=dualAuthDelete" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.policy+json" \
-d '{
"metadata": {
"collectionType": "application/vnd.ibm.kms.policy+json",
"collectionTotal": 1
},
"resources": [
{
"policy_type": "badName",
"policy_data": {
"enabled": false
}
}
]
}'{: codeblock}
{: #error-messages-body-query-param-mismatch-err-cxt-json}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Bad Request: Instance policy could not be created. Please see `reasons` for more details.",
"reasons": [
{
"code": "BODY_QUERY_PARAM_MISMATCH_ERR",
"message": "Data in body does not match data required by query parameter",
"status": 400,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: screen}
{: #error-messages-bearer-sub-extraction-err}
{: #error-messages-bearer-sub-extraction-err-message}
Extracting the subject from the bearer token failed: Make sure the bearer token passed is the correct one (and correct format) and is allowed to perform requested actions
Reason code: BEARER_SUB_EXTRACTION_ERR
{: #error-messages-bearer-sub-extraction-err-http}
400 - Bad Request
The HTTP 400 Bad Request response status code indicates that the server cannot
or will not process the request due to something that is perceived to be a
client error (e.g., malformed request syntax, invalid request message framing,
or deceptive request routing).
The client should not repeat this request without modification.
{: #error-messages-bearer-sub-extraction-err-cxt}
The identify and access management (IAM) access token, or format, was invalid. If this is a curl request then the authorization header needs to be set using this format:
-H "authorization: Bearer $ACCESS_TOKEN"{: screen}
Depending on which platform (Linux, Mac, Windows) or shell (bash, sh, zsh) you
are using, you need to be aware of using single versus double quotes. Some
systems will not interpret variables inside single quotes. For example,
('Bearer $ACCESS_TOKEN') may not replace $ACCESS_TOKEN with the value.
{: note}
Make sure you specify a valid IAM token. You may need to login (again) if your token has expired. Here are a few lines of command line interface (CLI) code to login and set the access token.
# login with single sign on (sso)
$ ibmcloud login --sso
# set the region (-r) and resource group (-g)
$ ibmcloud target -r us-south -g Default
# set the ACCESS_TOKEN environment variable (with Bearer)
$ export ACCESS_TOKEN=`ibmcloud iam oauth-tokens | grep IAM | cut -d \: -f 2 | sed 's/^ *//'`
# show the access token
$ echo $ACCESS_TOKEN
Bearer eyJraWQiOiIyMDIwMDcyNDE4MzEiLCJh...<redacted>...o4qlcKjl9sVqLa8Q
# set the ACCESS_TOKEN environment variable (without Bearer)
$ export ACCESS_TOKEN=`ibmcloud iam oauth-tokens | grep IAM | cut -d ' ' -f 5 | sed 's/^ *//'`
eyJraWQiOiIyMDIwMDcyNDE4MzEiLCJh...<redacted>...o4qlcKjl9sVqLa8Q{: codeblock}
{: #error-messages-bad-body-err}
{: #error-messages-bad-body-err-message}
Invalid body data was passed: Please ensure the data passed had valid formatting with no invalid characters
Reason code: BAD_BODY_ERR
{: #error-messages-bad-body-err-http}
400 - Bad Request
The HTTP 400 Bad Request response status code indicates that the server cannot
or will not process the request due to something that is perceived to be a
client error (e.g., malformed request syntax, invalid request message framing,
or deceptive request routing).
The client should not repeat this request without modification.
{: #error-messages-bad-body-err-cxt}
Some examples of this error are:
-
Create an instance policy
- Only one of each policy can be created
- No
resourcessection was provided - Extraneous fields in the
resourcessection (see example 1)
-
Create a key
- One resource is required (see example 2)
- Metadata is empty (see example 3)
- Key has zero value or it's empty
{: #error-messages-bad-body-err-cxt-ex-1}
The create instance policy request fails because the resource contains an
extra field (extra_field).
# this request fails because there is an extra field in the body
$ curl -X PUT \
"https://us-south.kms.cloud.ibm.com/api/v2/instance/policies?policy=dualAuthDelete" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.policy+json" \
-d '{
"metadata": {
"collectionType": "application/vnd.ibm.kms.policy+json",
"collectionTotal": 1
},
"resources": [
{
"policy_type": "dualAuthDelete",
"policy_data": {
"enabled": false
},
"extra_field": "junk data"
}
]
}'{: codeblock}
{: #error-messages-bad-body-err-cxt-ex-1-json}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Bad Request: Instance policy could not be created. Please see `reasons` for more details.",
"reasons":[
{
"code": "BAD_BODY_ERR",
"message": "Invalid body data was passed. Please ensure the data passed had valid formatting with no invalid characters: json: unknown field \"extra_field\"",
"status": 400,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: screen}
{: #error-messages-bad-body-err-cxt-ex-2}
The create key request fails because there is more than 1 (one) resource.
# this request fails because there is more than 1 (one) resource
$ curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_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-1",
"description": "example-key",
"extractable": false
},
{
"type": "application/vnd.ibm.kms.key+json",
"name": "Root-key-2",
"description": "example-key",
"extractable": false
}
]
}'{: codeblock}
{: #error-messages-bad-body-err-cxt-ex-2-json}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Bad Request: Key could not be created. Please see `reasons` for more details.",
"reasons": [
{
"code": "BAD_BODY_ERR",
"message": "Invalid body data was passed. Please ensure the data passed had valid formatting with no invalid characters: Only creation of one key per request is supported",
"status": 400,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: screen}
{: #error-messages-bad-body-err-cxt-ex-3}
This create key request fails because the metadata is empty.
# this request fails because the metadata is empty
$ curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.key+json" \
-d '{
"metadata": {},
"resources": [
{
"type": "application/vnd.ibm.kms.key+json",
"name": "Root-key-1",
"description": "example-key",
"extractable": false
}
]
}'{: codeblock}
{: #error-messages-bad-body-err-cxt-ex-3-json}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Bad Request: Key could not be created. Please see `reasons` for more details.",
"reasons": [
{
"code": "BAD_BODY_ERR",
"message": "Invalid body data was passed. Please ensure the data passed had valid formatting with no invalid characters: CollectionMetadata is empty",
"status": 400,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: screen}
{: #error-messages-invalid-field-err}
{: #error-messages-invalid-field-err-message}
When wrapping a key, the message, The field 'plaintext' must be: a base64 encoded key material will be shown if invalid plaintext is passed in the request.
When unwrapping a key, the message, The field 'ciphertext' must be: the original base64 encoded ciphertext from the wrap operation if invalid ciphertext is passed.
{: #error-messages-invalid-field-err-http}
400
{: #error-messages-invalid-field-err-cxt}
A sample request to wrap a key that fails:
curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys/$KEY_ID/actions/wrap" \
-H "authorization: Bearer <ACCESS_TOKEN>" \
-H "bluemix-instance: <KP_INSTANCE_ID>" \
-H "application/vnd.ibm.kms.key_action+json" \
-d '{
"plaintext": "q+x3Qi.../BVb8bPj....vVD;",
}'{: pre}
The response:
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Bad Request: Wrap with key could not be performed: Please see `reasons` for more details (INVALID_FIELD_ERR)",
"reasons": [
{
"code": "INVALID_FIELD_ERR",
"message": "The field `plaintext` must be: a base64 encoded key material: illegal base64 data at input byte 38",
"status": 400,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
"target": {
"type": "field",
"name": "plaintext"
}
}
]
}
]
}{: screen}
A sample request to unwrap a key that fails:
request:
curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys/$KEY_ID/actions/unwrap" \
-H "authorization: Bearer <ACCESS_TOKEN>" \
-H "bluemix-instance: <KP_INSTANCE_ID>" \
-H "application/vnd.ibm.kms.key_action+json" \
-d '{
"ciphertext": "eyJjaXBoZXJ0ZXh0IjoiUnl...hYTUtNDNmMi05NTc5LWM2NjAzN2EwNjhkNyJ"
}'{: pre}
The response:
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Bad Request: Unwrap with key could not be performed: Please see 'reasons' for more details (INVALID_FIELD_ERR)",
"reasons": [
{
"code": "INVALID_FIELD_ERR",
"message": "The field 'ciphertext' must be: the original base64 encoded ciphertext from the wrap operation: illegal base64 data at input byte 208",
"status": 400,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
"target": {
"type": "field",
"name": "ciphertext"
}
}
]
}
]
}
{: screen}
{: #error-messages-key-delete-err}
{: #error-messages-key-delete-err-http}
409 - Conflict
The HTTP 409 Conflict client error response code indicates that an error in the client request can be resolved per the specified reason code returned.
{: #error-messages-key-delete-err-cxt}
The message returns a reason in the message that provides the specific context.
{: #error-messages-key-delete-err-message}
Reason code: 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.
Reason code: 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.
Reason code: 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.
{: #error-messages-key-delete-err-example-1}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Key could not be deleted. Please 'reasons' for more details.",
"reasons": [
{
"code": "AUTHORIZATIONS_NOT_MET",
"message": "The key cannot be deleted because it failed the dual authorization request.",
"status": 409,
"moreInfo":"https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: #error-messages-key-delete-err-example-2}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Key could not be deleted. Please 'reasons' for more details.",
"reasons": [
{
"code": "PROTECTED_RESOURCE_ERR",
"message": "The key cannot be deleted because the key has one or more associated resources.",
"status": 409,
"moreInfo":"https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: #error-messages-key-delete-err-example-3}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Key could not be deleted. Please 'reasons' for more details.",
"reasons": [
{
"code": "PREV_KEY_DEL_ERR",
"message": "The key cannot be deleted because it's protecting a cloud resource that has a retention policy.",
"status": 409,
"moreInfo":"https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: #error-messages-key-deleted-err}
{: #error-messages-key-deleted-err-message}
Key has already been deleted: Please delete references to this key
Reason code: KEY_DELETED_ERR
{: #error-messages-key-deleted-err-http}
410 - Gone
The HTTP 410 Gone client error response code indicates that access to the
target resource is no longer available at the origin server and that this
condition is likely to be permanent.
If you don't know whether this condition is temporary or permanent, a 404 status code should be used instead.
A 410 response is cacheable by default.
{: #error-messages-key-deleted-err-cxt}
The delete key request fails because the key was previously deleted. You
cannot delete a key more than once.
{: #error-messages-key-deleted-err-cxt-ex}
# delete an existing key
$ ibmcloud kp key delete $KEY_ID -i $KP_INSTANCE_ID
Deleting key: '0c17...<redacted>...5c34', from instance: 'a192...<redacted>...7411'...
OK
Deleted Key
0c17...<redeacted>...5c34
# this request fails because the key was previously deleted
$ curl -X DELETE \
"https://us-south.kms.cloud.ibm.com/api/v2/keys/$KEY_ID" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.key+json"{: codeblock}
{: #error-messages-key-deleted-err-cxt-ex-json}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Gone: Key could not be deleted. Please see `reasons` for more details.",
"reasons": [
{
"code": "KEY_DELETED_ERR",
"message": "Key has already been deleted. Please delete references to this key.",
"status": 410,
"moreInfo":"https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: screen}
{: #error-messages-key-action-invalid-state-err}
{: #error-messages-key-action-invalid-state-err-message}
Key is not in a valid state
Reason code: KEY_ACTION_INVALID_STATE_ERR
{: #error-messages-key-action-invalid-state-err-http}
409 - Conflict
The HTTP 409 Conflict response status code indicates a request conflict with
current state of the server.
Conflicts are most likely to occur in response to a PUT request. For example,
you may get a 409 response when uploading a file which is older than the one
already on the server resulting in a version control conflict.
{: #error-messages-key-action-invalid-state-err-cxt}
This error occurs when an "action" is performed on a key and the key state is not valid.
Some actions to consider:
-
The key state must be active (state value is 1) to wrap, unwrap, rotate, set key for deletion (dual auth), unset key for deleteion (dual auth), or disable the key
-
This error occurs when you try to enable an expired key (state value is 3) or restore a key that has been destroyed (state value is 5)
{: #act-invld-state-err-cxt-ex-1}
The key disable request fails because you cannot disable a key that was
previously disabled.
# disable a key the first time
$ ibmcloud kp key disable $KEY_ID -i $KP_INSTANCE_ID
Disabling key: '6933...<redacted>...5dbf', in instance: 'a192...<redacted>...7411'...
OK
# this CLI request fails because the key is deleted a second time
$ ibmcloud key disable $KEY_ID -i $KP_INSTANCE_ID
Disabling key: '69332...<redacted>...5dbf', in instance: 'a192...<redacted>...7411'...
FAILED
kp.Error:
correlation_id='aca1...<redacted>...66e9',
msg='Conflict:
Key is not in active state:
Key could not be disabled.
Please see `reasons` for more details.',
reasons='[KEY_ACTION_INVALID_STATE_ERR:
Key is not in a valid state -
FOR_MORE_INFO_REFER: https://cloud.ibm.com/apidocs/key-protect]'
# this API request fails because the key is deleted a third time
$ curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys/$KEY_ID/actions/disable" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.key_action+json"{: codeblock}
{: #act-invld-state-err-cxt-ex-1-json}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Conflict: Key is not in active state: Key could not be disabled. Please see `reasons` for more details.",
"reasons": [
{
"code": "KEY_ACTION_INVALID_STATE_ERR",
"message": "Key is not in a valid state",
"status": 409,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: screen}
{: #act-invld-state-err-cxt-ex-2}
The key disable request fails because the key has expired and you are
attempting to change the key state from disabled (state value is 3) to enabled
(state value is 1).
The following steps return a key has been disabled error.
-
Create a key with an expiration date
-
Allow the expiration date to pass
-
Enable the key
# on a Mac, add 1 (one) minute to the current time
$ EXPIRE=$(date -u -v+1M "+%Y-%m-%dT%H:%M:%SZ")
$ echo $EXPIRE
# step 1 - create a key with an expiration date
$ curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_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-1",
"description": "example-key",
"expirationDate": "'$EXPIRE'",
"extractable": false
}
]
}'{: codeblock}
{: #act-invld-state-err-cxt-ex-2-json-1}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.key+json",
"collectionTotal": 1
},
"resources": [
{
"type": "application/vnd.ibm.kms.key+json",
"id": "88d649f8-41b8-4426-b52b-45c88953d5b8",
"name": "Root-key-1",
"description": "example-key",
"state": 1,
"expirationDate": "2020-08-12T23:38:09Z",
"extractable": false,
"crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:a192d603-0b8d-452f-aac3-f9e1f95e7411:key:88d649f8-41b8-4426-b52b-45c88953d5b8",
"imported": false,
"deleted": false
}
]
}{: screen}
# capture the key id
$ KEY_ID=88d649f8-41b8-4426-b52b-45c88953d5b8
# step 2 - allow the expiration date to pass by sleeping for 1 (one) minute
$ sleep 60
# step 3 - fails because you cannot enable a key after the expiration date
$ curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys/$KEY_ID/actions/enable" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.key_action+json"{: codeblock}
{: #act-invld-state-err-cxt-ex-2-json-2}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Conflict: Key is not in suspended state: Key could not be enabled. Please see `reasons` for more details.",
"reasons": [
{
"code":" KEY_ACTION_INVALID_STATE_ERR",
"message": "Key is not in a valid state",
"status": 409,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: screen}
{: #error-messages-key-invalid-state-err}
{: #error-messages-key-invalid-state-err-message}
Key is not in a valid state
Reason code: KEY_INVALID_STATE_ERR
{: #error-messages-key-invalid-state-err-http}
422 - Unprocessable Entity
The HTTP 422 Unprocessable Entity response status code indicates that the
server understands the content type of the request entity, and the syntax of the
request entity is correct, but it was unable to process the contained
instructions.
The client should not repeat this request without modification.
{: #error-messages-key-invalid-state-err-cxt}
This error applies to keys used for "Registrations."
The key state must be active (state value is 1) when registering the key with a cloud resource.
Registrations are associations between root keys and other cloud resources, such as Cloud Object Storage (COS) buckets or Cloud Databases deployments.
For more information about Registrations, see viewing associations between root keys and encrypted IBM Cloud resources.
{: #error-messages-protected-resource-err}
{: #error-messages-protected-resource-err-message}
Key is protecting one or more cloud resources
Reason code: PROTECTED_RESOURCE_ERR
{: #error-messages-protected-resource-err-http}
409 - Conflict
The HTTP 409 Conflict response status code indicates a request conflict with
current state of the server.
Conflicts are most likely to occur in response to a PUT request. For example,
you may get a 409 response when uploading a file which is older than the one
already on the server resulting in a version control conflict.
{: #error-messages-protected-resource-err-cxt}
This error applies to keys used for "Registrations."
A key that is registered for a cloud resource cannot be deleted unless the
force option is specified.
You must use the force option to delete a root key that is registered with
another cloud resource.
Registrations are associations between root keys and other cloud resources, such as Cloud Object Storage (COS) buckets or Cloud Databases deployments.
For more information about Registrations, see viewing associations between root keys and encrypted IBM Cloud resources.
See this explanation
of deleting keys that are registered with another cloud resource (look at the
force option).
# this CLI request fails because the registration was not deleted
$ ibmcloud kp key delete $KEY_ID -i $KP_INSTANCE_ID
Deleting key: 52a9d772-8982-4620-bfb4-b070dd812a0c, from instance: b0d84b32-09d0-4314-8049-da78e3b9ab6f...
FAILED
kp.Error:
correlation_id='c27b7948-4a1f-4cbd-8770-cb3616888e27',
msg='Conflict:
Key could not be deleted.
Please see "reasons" for more details.',
reasons='[PROTECTED_RESOURCE_ERR:
Key is protecting one or more cloud resources -
FOR_MORE_INFO_REFER: https://cloud.ibm.com/docs/key-protect?topic=key-protect-troubleshooting#unable-to-delete-keys]'
# this CLI request succeeds when using the --force option
# the registration between Key Protect and the cloud resource exists
$ ibmcloud kp key delete $KEY_ID -i $KP_INSTANCE_ID --force --output json
{
"id": "52a9d772-8982-4620-bfb4-b070dd812a0c"
}{: codeblock}
{: #error-messages-incomplete-metadata-err}
{: #error-messages-incomplete-metadata-err-message}
Key metadata became corrupted: Please delete this key
Reason code: INCOMPLETE_METADATA_ERR
{: #error-messages-incomplete-metadata-err-http}
500 - Internal Server Error
The HTTP 500 Internal Server server error response code indicates that the
server encountered an unexpected condition that prevented it from fulfilling the
request.
This error response is a generic "catch-all" response. Usually, this indicates the server cannot find a better 5xx error code to response. Sometimes, server administrators log error responses like the 500 status code with more details about the request to prevent the error from happening again in the future.
{: #error-messages-incomplete-metadata-err-cxt}
This error is returned when there is an internal error.
If you get this error please contact IBM support{: external}
{: #error-messages-key-restore-expired}
{: #error-messages-key-restore-expired-message}
Key restoration has expired
Reason code: KEY_RESTORE_EXPIRED
{: #error-messages-key-restore-expired-http}
400 - Bad Request
The HTTP 400 Bad Request response status code indicates that the server cannot
or will not process the request due to something that is perceived to be a
client error (e.g., malformed request syntax, invalid request message framing,
or deceptive request routing).
The client should not repeat this request without modification.
{: #error-messages-key-restore-expired-context}
This error occurs when you try to restore a key that was deleted more than 30 days ago.
{: #error-messages-key-create-import-access-err}
{: #error-messages-key-create-import-access-err-message}
KeyCreateImportAccess instance policy does not allow this action
Reason code: KEY_CREATE_IMPORT_ACCESS_ERR
{: #error-messages-key-create-import-access-err-http}
409 - Conflict
The HTTP 409 Conflict response status code indicates a request conflict with
current state of the server.
Conflicts are most likely to occur in response to a PUT request. For example,
you may get a 409 response when uploading a file which is older than the one
already on the server resulting in a version control conflict.
{: #error-messages-key-create-import-access-err-cxt}
The KeyCreateImportAccess instance policy was enabled and a request to create
or import a key was not allowed.
For example, the instance policy does not allow creating a standard key and a request to create a standard key was rejected.
{: #error-messages-key-create-import-access-err-example}
The following steps return this error.
-
Enable the instance policy and prevent creating standard keys
-
Attempt to create a standard key, which fails
-
Remove (disable) the instance policy, which allows creating standard keys
-
Create a standard key, which succeeds
# step 1 - enable an instance policy, which prevents creating standard keys
$ curl -X PUT \
"https://us-south.kms.cloud.ibm.com/api/v2/instance/policies?policy=keyCreateImportAccess" \
-H "accept: application/vnd.ibm.kms.policy+json" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.policy+json" \
-d '{
"metadata": {
"collectionType": "application/vnd.ibm.kms.policy+json",
"collectionTotal": 1
},
"resources": [
{
"policy_type": "keyCreateImportAccess",
"policy_data": {
"enabled": true,
"attributes": {
"create_root_key": true,
"create_standard_key": false,
"import_root_key": true,
"import_standard_key": true,
"enforce_token": true
}
}
}
]
}'
# step 2a - fails when using the ibmcloud CLI
# because the instance policy prevents creating standard keys
$ ibmcloud kp key create my-standard-key --standard-key
FAILED
kp.Error:
correlation_id='43c45c85-7a1f-478c-b235-49decec8c88f',
msg='Conflict:
Key could not be created:
Please see `reasons` for more details (KEY_CREATE_IMPORT_ACCESS_ERR)',
reasons='[KEY_CREATE_IMPORT_ACCESS_ERR:
KeyCreateImportAccess instance policy does not allow this action -
FOR_MORE_INFO_REFER: https://cloud.ibm.com/apidocs/key-protect]'
# step 2b - fails when using the the ibmcloud API
# because the instance policy prevents creating standard keys
$ curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_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": "my-standard-key",
"description": "my-standard-key",
"extractable": true
}
]
}'{: codeblock}
{: #error-messages-key-create-import-access-err-example-json-1}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Conflict: Key could not be created: Please see `reasons` for more details (KEY_CREATE_IMPORT_ACCESS_ERR)",
"reasons": [
{
"code": "KEY_CREATE_IMPORT_ACCESS_ERR",
"message": "KeyCreateImportAccess instance policy does not allow this action",
"status": 409,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: screen}
Steps 3-4 disables the keyCreateImportAccess policy and successfully creates a
standard key.
# step 3 - disable the policy, that is, enable creating standard keys
$ curl -X PUT \
"https://us-south.kms.cloud.ibm.com/api/v2/instance/policies?policy=keyCreateImportAccess" \
-H "accept: application/vnd.ibm.kms.policy+json" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.policy+json" \
-d '{
"metadata": {
"collectionType": "application/vnd.ibm.kms.policy+json",
"collectionTotal": 1
},
"resources": [
{
"policy_type": "keyCreateImportAccess",
"policy_data": {
"enabled": false
}
}
]
}'
# step 4a - create a standard key using the ibmcloud CLI
$ ibmcloud kp key create my-standard-key --standard-key -o json
{
"id": "3511e0bc-e32d-40b8-b6c2-96cd651858a4",
"name": "my-standard-key",
"type": "application/vnd.ibm.kms.key+json",
"extractable": true,
"state": 1,
"crn": "crn:v1:bluemic:public:kms:us-south:a/819bdf4436ef4c198fdf4f0b81d53116:87fa68d0-fa10-47d0-a201-603949808530:key:3511e0bc-e32d-40b8-b6c2-96cd651858a4",
"deleted": false
}
# step 4b - create a standard key using the ibmcloud API
curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_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": "my-standard-key",
"description": "my-standard-key",
"extractable": true
}
]
}'{: codeblock}
{: #key-create-import-access-err-ex-json-2}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.key+json",
"collectionTotal": 1
},
"resources": [
{
"type": "application/vnd.ibm.kms.key+json",
"id": "60d72058-ec53-4d77-b7ef-ba56443e76d5",
"name": "my-standard-key",
"description": "my-standard-key",
"state": 1,
"extractable": true,
"crn":"crn:v1:bluemix:public:kms:us-south:a/819bdf4436ef4c198fdf4f0b81d53116:87fa68d0-fa10-47d0-a201-603949808530:key:60d72058-ec53-4d77-b7ef-ba56443e76d5",
"imported": false,
"deleted": false
}
]
}{: screen}
{: #error-messages-no-body-err}
{: #error-messages-no-body-err-message}
Missing body in request
Reason code: NO_BODY_ERR
{: #error-messages-no-body-err-http}
400 - Bad Request
The HTTP 400 Bad Request response status code indicates that the server cannot
or will not process the request due to something that is perceived to be a
client error (e.g., malformed request syntax, invalid request message framing,
or deceptive request routing).
The client should not repeat this request without modification.
{: #error-messages-no-body-err-cxt}
This error occurs when you "rewrap" or "unwrap" a key and there is no body.
{: #error-messages-no-body-err-cxt-ex}
The following steps return a missing body in request error.
-
Create a root key
-
Create a data encryption key (DEK), this is the
plaintext -
Wrap the DEK with the root key, this creates a
ciphertext -
Request fails to unwrap the new ciphertext to reveal the original DEK (plaintext) because of a missing body
-
Request succeeds to unwrap the new ciphertext to reveal the original DEK (plaintext) because the body is specified
# step 1 - create a root key
$ KEY_ID=$(ibmcloud kp key create example-key -i $KP_INSTANCE_ID --output json | jq -r '.["id"]')
$ echo $KEY_ID
66ffaf5b-86c8-4a50-8a2a-920ae71f86dc
# step 2 - create a random, base64-encoded, 32-byte data encryption key (DEK)
$ PLAINTEXT=$(openssl rand -base64 32)
$ echo $PLAINTEXT
2eLAD3LyD3H2bq8dIDAy0A/lN9DSE/Ne3bwu40CdErs=
# step 3 - wrap the DEK (plaintext key) with the root key, creating the ciphertext
$ CIPHERTEXT=$(ibmcloud kp key wrap $KEY_ID -i $KP_INSTANCE_ID -p $PLAINTEXT --output json | jq -r '.["Ciphertext"]')
$ echo $CIPHERTEXT
eyJjaXBoZXJ0ZXh0IjoiR0VnTFZGSmpK...<redacted>...YWU3MWY4NmRjIn0=
# step 4 - fails to unwrap the ciphertext, which reveals the original DEK
# (plaintext), because there is no body (the -d option)
$ curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys/$KEY_ID/actions/unwrap" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.key_action+json"{: codeblock}
{: #error-messages-no-body-err-cxt-ex-json-1}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Bad Request: Action could not be performed on key. Please see `reasons` for more details.",
"reasons": [
{
"code": "NO_BODY_ERR",
"message": "Missing body in request",
"status": 400,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: screen}
# step 5 - succeeds to unwrap the ciphertext because the request is complete
$ curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys/$KEY_ID/actions/unwrap" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.key_action+json" \
-d '{
"ciphertext": "'$CIPHERTEXT'"
}'{: codeblock}
{: #no-body-err-cxt-ex-json-2}
{
"plaintext": "2eLAD3LyD3H2bq8dIDAy0A/lN9DSE/Ne3bwu40CdErs=",
"keyVersion": {
"id": "66ffaf5b-86c8-4a50-8a2a-920ae71f86dc"
}
}{: screen}
{: #error-messages-authorizations-not-met}
{: #error-messages-authorizations-not-met-message}
Number of authorizations required to delete is not met
Reason code: AUTHORIZATIONS_NOT_MET
{: #error-messages-authorizations-not-met-http}
409 - Conflict
The HTTP 409 Conflict response status code indicates a request conflict with
current state of the server.
Conflicts are most likely to occur in response to a PUT request. For example,
you may get a 409 response when uploading a file which is older than the one
already on the server resulting in a version control conflict.
{: #error-messages-authorizations-not-met-context}
A key with a dual authorization policy cannot be deleted without an
authorization from two users.
{: #error-messages-authorizations-not-met-context-example}
These steps illustrate how to create the error message.
-
Create a root key
-
Enable the dual authorization policy
-
List the policies (verify dual authorization is enabled)
-
Delete the key, which fails because not enough authorizations are met to delete the key
# step 1 - create a root key
$ KEY_ID=$(ibmcloud kp key create example-key -i $KP_INSTANCE_ID --output json | jq -r '.["id"]')
$ echo $KEY_ID
8f97b016-bc31-4e3d-9cd6-a0a1c7caffdb
# step 2 - enable the dual authorization policy
$ ibmcloud kp key policy-update dual-auth-delete $KEY_ID -i $KP_INSTANCE_ID --enable
Setting a rotation interval for key ID: 8f97b016-bc31-4e3d-9cd6-a0a1c7caffdb...
OK
Key ID 8f97b016-bc31-4e3d-9cd6-a0a1c7caffdb
Created By IBMid-...<redacted>...
Creation Date 2020-08-13T22:33:50Z
Last Updated 2020-08-13T22:33:50Z
Updated By IBMid-...<redacted>...
Enabled true
# step 3 - list the policies (verify dual authorization is enabled)
$ ibmcloud kp key policies $KEY_ID -i $KP_INSTANCE_ID --output json
[
{
"createdBy": "IBMid-...<redacted>...",
"creationDate": "2020-08-13T22:33:50Z",
"crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:a192d603-0b8d-452f-aac3-f9e1f95e7411:policy:0b93cd65-8359-4891-9289-8701f4c6ad9c",
"lastUpdateDate": "2020-08-13T22:33:50Z",
"updatedBy": "IBMid-...<redacted>...",
"dualAuthDelete": {
"enabled": true
}
}
]
# step 4 - fails because not enough authorizations are met to delete the key
$ curl -X DELETE \
"https://us-south.kms.cloud.ibm.com/api/v2/keys/$KEY_ID" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.key+json"{: codeblock}
{: #error-messages-authorizations-not-met-context-example-json}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Conflict: 1 prior authorization(s) are required for deletion: Key could not be deleted. Please see `reasons` for more details.",
"reasons": [
{
"code": "AUTHORIZATIONS_NOT_MET",
"message": "Number of authorizations required to delete is not met",
"status": 409,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: screen}
{: #error-messages-num-collection-resource-err}
{: #error-messages-num-collection-resource-err-message}
Only a single instance policy may be created per query parameter: Please pass single resource object
Reason code: NUM_COLLECTION_RESOURCE_ERR
{: #error-messages-num-collection-resource-err-http}
400 - Bad Request
The HTTP 400 Bad Request response status code indicates that the server cannot
or will not process the request due to something that is perceived to be a
client error (e.g., malformed request syntax, invalid request message framing,
or deceptive request routing).
The client should not repeat this request without modification.
{: #error-messages-num-collection-resource-err-cxt}
The create instance policy request fails because the same policy was
specified more than once.
You may specify multiple policies in the request as long as each policy is
unique. For example, you could create instance policies for dualAuthDelete and
allowedIP in the same request.
{: #error-messages-num-collection-resource-err-cxt-ex}
This request fails because more than one instance policy was provided.
# this request fails because the dualAuthDelete policy was specified more than once
$ curl -X PUT \
"https://us-south.kms.cloud.ibm.com/api/v2/instance/policies?policy=dualAuthDelete" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.policy+json" \
-d '{
"metadata": {
"collectionType": "application/vnd.ibm.kms.policy+json",
"collectionTotal": 2
},
"resources": [
{
"policy_type": "dualAuthDelete",
"policy_data": {
"enabled": false
}
},
{
"policy_type": "dualAuthDelete",
"policy_data": {
"enabled": false
}
}
]
}'{: codeblock}
{: #error-messages-num-collection-resource-err-cxt-ex-json}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Bad Request: Instance policy could not be created. Please see `reasons` for more details.",
"reasons": [
{
"code": "NUM_COLLECTION_RESOURCE_ERR",
"message": "Only a single instance policy may be created per query parameter. Please pass single resource object",
"status": 400,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: screen}
{: #error-messages-key-impt-req-err}
{: #error-messages-key-impt-req-err-message}
Only imported keys may be restored
Reason code: KEY_IMPT_REQ_ERR
{: #error-messages-key-impt-req-err-http}
400 - Bad Request
The HTTP 400 Bad Request response status code indicates that the server cannot
or will not process the request due to something that is perceived to be a
client error (e.g., malformed request syntax, invalid request message framing,
or deceptive request routing).
The client should not repeat this request without modification.
{: #error-messages-key-impt-req-err-cxt}
{{site.data.keyword.keymanagementserviceshort}} can restore a previously deleted root key, which restores access to its associated data in the cloud.
As an admin, you might need to restore a root key that was imported into {{site.data.keyword.keymanagementserviceshort}} to access data the key previously protected.
When you restore a key, you move the key from the Destroyed (state value is 5) to the Active (state value is 1) key state, and you restore access to any data that was previously encrypted with the key.
You can restore a deleted key within 30 days of its deletion. This capability is
available only for root keys that were created with a key material, also known
as the "payload."
You can only restore root keys that were created with a key material, using
the kp key create command with the -k, --key-material option. You cannot
restore a root key if the --key-material option was not specified.
If you want to restore a deleted root key then you must save the
key material that was used to create the root key. You cannot restore a
deleted key without provided the original key material.
{: #error-messages-key-impt-req-err-cxt-ex}
Follow these steps to create the only imported keys may be restored error.
-
Create a root key without a key material (payload)
-
Delete the key
-
Sleep 30 seconds
-
Create a key material
-
Restore the key and provide a key material (payload)
# step 1 - create a root key without a key material (payload)
$ KEY_ID=$(ibmcloud kp key create example-key -i $KP_INSTANCE_ID --output json | jq -r '.["id"]')
$ echo $KEY_ID
e631925f-affb-457e-886d-57cb2a5f565b
# step 2 - delete the key
$ ibmcloud kp key delete $KEY_ID -i $KP_INSTANCE_ID
Deleting key: 'e631925f-affb-457e-886d-57cb2a5f565b', from instance: 'a192d603-0b8d-452f-aac3-f9e1f95e7411'...
OK
Deleted Key
e631925f-affb-457e-886d-57cb2a5f565b
# step 3 - sleep 30 seconds
$ sleep 30
# step 4 - create a key material
$ KEY_MATERIAL=$(openssl rand -base64 32)
$ echo $KEY_MATERIAL
lZM/guRnn/VklwRBoNOP/AUdCtpDNSo3+xXXhwrnO7c=
# step 5 - this CLI request fails because you can only restore keys
# that were imported (created with a key material or an import token)
$ ibmcloud kp key restore $KEY_ID -i $KP_INSTANCE_ID --key-material $KEY_MATERIAL
Restoring key: 'e631925f-affb-457e-886d-57cb2a5f565b', in instance: 'a192d603-0b8d-452f-aac3-f9e1f95e7411'...
FAILED
kp.Error:
correlation_id='6d000f60-47f2-4a49-ba72-f02a8efa2945',
msg='Bad Request:
Key could not be restored.
Please see `reasons` for more details.',
reasons='[KEY_IMPT_REQ_ERR:
Only imported keys may be restored. -
FOR_MORE_INFO_REFER: https://cloud.ibm.com/apidocs/key-protect]'
# step 5 - this API request fails because you can only restore keys
# that were imported (created with a key material or an import token)
$ curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys/$KEY_ID/restore" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.key_action+json" \
-d '{
"metadata": {
"collectionType": "application/vnd.ibm.kms.key+json",
"collectionTotal": 1
},
"resources": [
{
"payload": "'$KEY_MATERIAL'"
}
]
}'{: codeblock}
{: #error-messages-key-impt-req-err-cxt-ex-json}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Bad Request: Key could not be restored. Please see `reasons` for more details.",
"reasons": [
{
"code": "KEY_IMPT_REQ_ERR",
"message": "Only imported keys may be restored.",
"status": 400,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: screen}
{: #error-messages-key-root-req-err}
{: #error-messages-key-root-req-err-message}
Requested action can only be completed with a root key
Reason code: KEY_ROOT_REQ_ERR
{: #error-messages-key-root-req-err-http}
400 - Bad Request
The HTTP 400 Bad Request response status code indicates that the server cannot
or will not process the request due to something that is perceived to be a
client error (e.g., malformed request syntax, invalid request message framing,
or deceptive request routing).
The client should not repeat this request without modification.
{: #error-messages-key-root-req-err-cxt}
Many key "actions" can only be performed on "root" keys. This is a list of commands that can only be performed on root keys.
- disable key
- enable key
- restore key
- rotate key
- unwrap key
- wrap key
{: #error-messages-key-root-req-err-cxt-ex}
This example creates a "standard" key then attempts to disable it. This fails because only "root" keys can be disabled.
# create a standard key
$ KEY_ID=$(ibmcloud kp key create example-key -i $KP_INSTANCE_ID --output json --standard-key | jq -r '.["id"]')
$ echo $KEY_ID
b2dae7bb-2da5-493e-99d2-a6379e35e58c
# this request fails because a standard key cannot be disabled
$ curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys/$KEY_ID/actions/disable" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.key_action+json"{: codeblock}
{: #error-messages-key-root-req-err-cxt-ex-json}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Bad Request: Key could not be disabled. Please see `reasons` for more details.",
"reasons": [
{
"code": "KEY_ROOT_REQ_ERR",
"message": "Requested action can only be completed with a root key.",
"status": 400,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: screen}
{: #error-messages-key-root-req-reg-err}
{: #error-messages-key-root-req-reg-err-message}
Requested action can only be completed with a root key
Reason code: KEY_ROOT_REQ_REG_ERR
{: #error-messages-key-root-req-reg-err-http}
422 - Unprocessable Entity
The HTTP 422 Unprocessable Entity response status code indicates that the
server understands the content type of the request entity, and the syntax of the
request entity is correct, but it was unable to process the contained
instructions.
The client should not repeat this request without modification.
{: #error-messages-key-root-req-reg-err-cxt}
This error applies to keys used for "Registrations." A "root" key is required to create a registration. This error is returned when a create registration API request{: external} is made.
Registrations are associations between root keys and other cloud resources, such as Cloud Object Storage (COS) buckets or Cloud Databases deployments.
For more information about Registrations, see viewing associations between root keys and encrypted IBM Cloud resources.
{: #error-config_rule_conflict_err}
{: #error-config-rule-conflict-err-message}
Requested change is not compliant with configuration rules
Reason code: CONFIG_RULE_CONFLICT_ERR
{: #error-config-rule-conflict-err-http}
403 - Forbidden
The HTTP 403 Forbidden client error status response code indicates that the
server understood the request but refuses to authorize it.
This status is similar to 401, but in this case, re-authenticating will make
no difference. The access is permanently forbidden and tied to the application
logic, such as insufficient rights to a resource.
{: #error-config-rule-conflict-err-cxt}
This error message occurs when an instance policy prevents access to a resource. For example, if the request originated from a public IP address and the instance policy prohibits access from a public IP address, then you will receive this error message.
{: #error-invalid_sig_exp_err}
{: #error-invalid-sig-exp-err-message}
Signature is invalid
Reason code: INVALID_SIG_EXP_ERR
{: #error-invalid-sig-exp-err-http}
422 - Unprocessable Entity
The HTTP 422 Unprocessable Entity response status code indicates that the
server understands the content type of the request entity, and the syntax of the
request entity is correct, but it was unable to process the contained
instructions.
The client should not repeat this request without modification.
{: #error-invalid-sig-exp-err-cxt}
An error occurred when a key was rewrapped.
If you get this error please contact IBM support{: external}
{: #error-messages-key-expired-err}
{: #error-messages-key-expired-err-message}
The action could not be performed on the key because the key is expired
Reason code: KEY_EXPIRED_ERR
{: #error-messages-key-expired-err-http}
400 - Bad Request
The HTTP 400 Bad Request response status code indicates that the server cannot
or will not process the request due to something that is perceived to be a
client error (e.g., malformed request syntax, invalid request message framing,
or deceptive request routing).
The client should not repeat this request without modification.
{: #error-messages-key-expired-err-cxt}
This error occurs when restoring a deleted key after the key has expired.
{: #error-messages-key-expired-err-cxt-ex}
A key restore request fails because the key is delete and the key has expired.
The following steps will create this error.
-
Create a key material (payload) and an expiration date
-
Create a root key using the key material and the expiration date
-
Capture the key id
-
Allow the expiration date to pass
-
Delete the key
-
Restore the key, which fails because you cannot restore a deleted key after the expiration date
# step 1 - create a key material (payload) and an expiration date
# create an expiration date, on a Mac, add 1 (one) minute to the current time
$ KEY_MATERIAL=$(openssl rand -base64 32)
$ EXPIRE=$(date -u -v+1M "+%Y-%m-%dT%H:%M:%SZ")
# step 2 - Create a root key using the key material and the expiration date
$ curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_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-1",
"payload": "'$KEY_MATERIAL'",
"description": "example-key",
"expirationDate": "'$EXPIRE'",
"extractable": false
}
]
}'{: codeblock}
{: #error-messages-key-expired-err-cxt-ex-json-1}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.key+json",
"collectionTotal": 1
},
"resources": [
{
"type": "application/vnd.ibm.kms.key+json",
"id": "aa713df1-857c-4c46-be80-3051756280c9",
"name": "Root-key-1",
"description": "example-key",
"state": 1,
"expirationDate": "2020-08-14T19:33:47Z",
"extractable": false,
"crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:a192d603-0b8d-452f-aac3-f9e1f95e7411:key:aa713df1-857c-4c46-be80-3051756280c9",
"imported": true,
"deleted": false
}
]
}{: screen}
# step 3 - capture the key id
$ KEY_ID=aa713df1-857c-4c46-be80-3051756280c9
# step 4 - allow the expiration date to pass by sleeping for 1 (one) minute
$ sleep 60
# step 5 - delete the key
$ ibmcloud kp key delete $KEY_ID
Deleting key: 'aa713df1-857c-4c46-be80-3051756280c9', from instance: 'a192d603-0b8d-452f-aac3-f9e1f95e7411'...
OK
Deleted Key
aa713df1-857c-4c46-be80-3051756280c9
# step 6 - fails because you cannot restore a deleted key after the expiration date
$ curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys/$KEY_ID/restore" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.key_action+json" \
-d '{
"metadata": {
"collectionType": "application/vnd.ibm.kms.key+json",
"collectionTotal": 1
},
"resources": [
{
"payload": "'$KEY_MATERIAL'"
}
]
}'{: codeblock}
{: #key-expired-err-cxt-ex-json-2}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Bad Request: The key expired on 2020-08-14 19:33:47 +0000 UTC: Key could not be restored. Please see `reasons` for more details.",
"reasons": [
{
"code": "KEY_EXPIRED_ERR",
"message": "The action could not be performed on the key because the key is expired.",
"status": 400,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: screen}
{: #error-messages-incorrect-nonce-err}
{: #error-messages-incorrect-nonce-err-message}
The encrypted nonce given does not match existing record: Please ensure the correct nonce was given in the request
Reason code: INCORRECT_NONCE_ERR
{: #error-messages-incorrect-nonce-err-http}
400 - Bad Request
The HTTP 400 Bad Request response status code indicates that the server cannot
or will not process the request due to something that is perceived to be a
client error (e.g., malformed request syntax, invalid request message framing,
or deceptive request routing).
The client should not repeat this request without modification.
{: #error-messages-incorrect-nonce-err-cxt}
This error message is applicable to the restore and rotate key interfaces.
This example is based on the restore key command and it uses the
CLI
because the output is easier to follow than the
API{: external}.
Step 1 - setup the problem by creating a root key using an import token and then delete the key
# create an import token that expires in 15 minutes (900 seconds) and allows 10 retrievals
$ ibmcloud kp import-token create -e 900 -m 10
Created Expires Max Retrievals Remaining Retrievals
2020-08-18 19:05:51 +0000 UTC 2020-08-18 19:20:51 +0000 UTC 10 10
# create a random, base64-encoded, 32-byte key material
$ KEY_MATERIAL=$(openssl rand -base64 32)
$ echo $KEY_MATERIAL
DL4Avc1yL7DhclfV9Uksvzy8VkYIKWZA9InYQv/iiro=
# extract the nonce that was created by the "kp import-token create" command
$ NONCE=$(ibmcloud kp import-token show | jq -r '.["nonce"]')
$ echo $NONCE
6SB0nQ8ROUCPUiyF
# extract the public key that was created by the "kp import-token create" command
$ PUBLIC_KEY=$(ibmcloud kp import-token show | jq -r '.["payload"]')
$ echo $PUBLIC_KEY
LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0t ...<redacted>... QyBLRVktLS0tLQo=
# encrypt the key material using the public key
$ ibmcloud kp import-token key-encrypt -k $KEY_MATERIAL -p $PUBLIC_KEY
Encrypted Key
rATe0oyYy+793MDlxQi2kJxf5BqLbmVY ...<redacted>... gNVJ5oxm7KX94iE=
# capture the encrypted key material
$ ENCRYPTED_KEY=rATe0oyYy+793MDlxQi2kJxf5BqLbmVY ...<redacted>... gNVJ5oxm7KX94iE=
# encrypt the nonce
$ ibmcloud kp import-token nonce-encrypt -k $KEY_MATERIAL -n $NONCE
Encrypted Nonce IV
+KjUDFD38r8zlXKJkn+dOR4/xNYN5ozpvKCiIQ== CSPZwm2qJ5mL00oP
# capture the encrypted nonce and the initialization vector (IV)
$ ENCRYPTED_NONCE=+KjUDFD38r8zlXKJkn+dOR4/xNYN5ozpvKCiIQ==
$ IV=CSPZwm2qJ5mL00oP
# create a root key using an import token, provide an encrypted key, nonce, and initialization vector (IV)
$ KEY_ID=$(ibmcloud kp key create my-imported-root-key -k $ENCRYPTED_KEY -n $ENCRYPTED_NONCE -v $IV --output json | jq -r '.["id"]')
$ echo $KEY_ID
fa0a7d81-a947-4bac-883d-952f6288f0a9
# delete the root key
$ ibmcloud kp key delete $KEY_ID
Deleting key: 'fa0a7d81-a947-4bac-883d-952f6288f0a9', from instance: 'a192d603-0b8d-452f-aac3-f9e1f95e7411'...
OK
Deleted Key
fa0a7d81-a947-4bac-883d-952f6288f0a9{: codeblock}
Step 2 - trigger the error by creating an import token, which is required to restore the key, and restore the key, then restore the key
# NOTE: the "kp key restore" requires an import token to complete the process,
# if you follow this example, the import token created above may still exist and
# the example works; otherwise, if the import token has expired then you need to
# create a new import token prior to restoring the key
# create an import token that expires in 15 minutes (900 seconds) and allows 10 retrievals
$ ibmcloud kp import-token create -e 900 -m 10
Created Expires Max Retrievals Remaining Retrievals
2020-08-18 19:12:35 +0000 UTC 2020-08-18 19:27:35 +0000 UTC 10 10
# extract the nonce that was created by the "kp import-token create" command
$ NONCE=$(ibmcloud kp import-token show | jq -r '.["nonce"]')
$ echo $NONCE
N3x8F0ihAZ51nj6M
# extract the public key that was created by the "kp import-token create" command
$ PUBLIC_KEY=$(ibmcloud kp import-token show | jq -r '.["payload"]')
$ echo $PUBLIC_KEY
LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0t ...<redacted>... QyBLRVktLS0tLQo=
# encrypt the key material using the public key
$ ibmcloud kp import-token key-encrypt -k $KEY_MATERIAL -p $PUBLIC_KEY
Encrypted Key
qkhpyERrqgU+q6M0ulCyFLP4/uAyTRNJ ...<redacted>... RvVRAyhPP9civbU=
# capture the encrypted key material
$ ENCRYPTED_KEY=qkhpyERrqgU+q6M0ulCyFLP4/uAyTRNJ ...<redacted>... RvVRAyhPP9civbU=
# encrypt the nonce
$ ibmcloud kp import-token nonce-encrypt -k $KEY_MATERIAL -n $NONCE
Encrypted Nonce IV
nrrCczvYXvc6T7J2G+EOLjHZO1cpPyu/nhsIlA== N6oLJnUqaKF3v5Sd
# Normally, you would capture the last encrypted nonce and the initialization
# vector (IV) (from the import token). Then use those new values with the
# "key restore" command.
# To force an error we are using the old (original) encrypted nonce and IV to
# restore the key, which fails because the ENCRYPTED_NONCE does not match the
# value in the import token
# we skipped these steps to force an error
# $ ENCRYPTED_NONCE=nrrCczvYXvc6T7J2G+EOLjHZO1cpPyu/nhsIlA==
# $ IV=N6oLJnUqaKF3v5Sd
# use the CLI to restore the deleted key
# this fails because the ENCRYPTED_NONCE does not match the value in the import token
$ ibmcloud kp key restore $KEY_ID -k $ENCRYPTED_KEY -n $ENCRYPTED_NONCE -v $IV --output json
FAILED
kp.Error:
correlation_id='a9412941-7986-421d-a67f-b22892e7634d',
msg='Bad Request:
Key could not be restored.
Please see `reasons` for more details.',
reasons='[INCORRECT_NONCE_ERR:
The encrypted nonce given does not match existing record,
please ensure the correct nonce was given in the request -
FOR_MORE_INFO_REFER: https://cloud.ibm.com/apidocs/key-protect]'{: codeblock}
{: #error-messages-import-token-expired-err}
{: #error-messages-import-token-expired-err-message}
The import token has expired
Reason code: IMPORT_TOKEN_EXPIRED_ERR
{: #error-messages-import-token-expired-err-http}
409 - Conflict
The HTTP 409 Conflict response status code indicates a request conflict with
current state of the server.
Conflicts are most likely to occur in response to a PUT request. For example,
you may get a 409 response when uploading a file which is older than the one
already on the server resulting in a version control conflict.
{: #error-messages-import-token-expired-err-cxt}
{: #error-messages-import-token-expired-err-cxt-ex-1}
Using the API, create an import token, allow it to expire, then attempt to retrieve it.
# create an import token
$ curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/import_token" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/json" \
-d '{
"expiration": 300,
"maxAllowedRetrievals": 2
}'{: codeblock}
{: #error-messages-import-token-expired-err-cxt-ex-1-json-1}
{
"maxAllowedRetrievals": 2,
"creationDate": "2020-08-18T19:54:57Z",
"expirationDate": "2020-08-18T19:59:57Z",
"remainingRetrievals":2
}{: screen}
# retrieve the import token after it expires
$ curl -X GET \
"https://us-south.kms.cloud.ibm.com/api/v2/import_token" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.import_token+json"{: codeblock}
{: #token-expired-err-cxt-ex-1-json-2}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Conflict: Import Token could not be retrieved. Please see `reasons` for more details.",
"reasons":[
{
"code": "IMPORT_TOKEN_EXPIRED_ERR",
"message": "The import token has expired.",
"status": 409,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: screen}
{: #import-token-expired-err-cxt-ex-2}
Using the CLI, create an import token, allow it to expire, then attempt to retrieve it.
# create an import token that expires in 5 minutes (300 seconds) and allows 2 retrievals
$ ibmcloud kp import-token create -e 300 -m 2
Created Expires Max Retrievals Remaining Retrievals
2020-08-18 19:39:06 +0000 UTC 2020-08-18 19:44:06 +0000 UTC 2 2
# sleep 300 seconds, which allows the import token to expire
$ sleep 300
# show the import token
$ ibmcloud kp import-token show
FAILED
kp.Error:
correlation_id='fb677c6e-9bfa-422e-a14b-0e221bbad32b',
msg='Conflict:
Import Token could not be retrieved.
Please see `reasons` for more details.',
reasons='[IMPORT_TOKEN_EXPIRED_ERR:
The import token has expired. -
FOR_MORE_INFO_REFER: https://cloud.ibm.com/apidocs/key-protect]'{: codeblock}
{: #error-messages-prev-key-del-err}
{: #error-messages-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
Reason code: PREV_KEY_DEL_ERR
{: #error-messages-prev-key-del-err-http}
409 - Conflict
The HTTP 409 Conflict response status code indicates a request conflict with
current state of the server.
Conflicts are most likely to occur in response to a PUT request. For example,
you may get a 409 response when uploading a file which is older than the one
already on the server resulting in a version control conflict.
{: #error-messages-prev-key-del-err-cxt}
This error occurs when a key, used for "Registrations", is deleted.
In most cases, a key with registrations can be deleted using the --force
option.
If the registered resource has preventKeyDeletion set to true, then a force
delete will fail and this error mesage will be shown.
In other words, all registrations must have preventKeyDeletion set to false.
Registrations are associations between root keys and other cloud resources, such as Cloud Object Storage (COS) buckets or Cloud Databases deployments.
For more information about Registrations, see viewing associations between root keys and encrypted IBM Cloud resources.
{: #error-messages-not-dual-auth-err}
{: #error-messages-not-dual-auth-err-message}
The key is not dual auth enabled and cannot be set for deletion
Reason code: NOT_DUAL_AUTH_ERR
{: #error-messages-not-dual-auth-err-http}
409 - Conflict
The HTTP 409 Conflict response status code indicates a request conflict with
current state of the server.
Conflicts are most likely to occur in response to a PUT request. For example,
you may get a 409 response when uploading a file which is older than the one
already on the server resulting in a version control conflict.
{: #error-messages-not-dual-auth-err-cxt}
This error occurs when you try to authorize a deletion or remove an
authorization and the key does not have a dual authorization policy.
These examples show the error using the API and the CLI.
{: #error-messages-not-dual-auth-err-cxt-ex-1}
This example attempts to authorize a deletion and remove an authorization using the API.
# create a root key
$ curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_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-example-key",
"description": "root-example-key",
"extractable": false
}
]
}'{: codeblock}
{: #error-messages-not-dual-auth-err-cxt-ex-1-json-1}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.key+json",
"collectionTotal": 1
},
"resources": [
{
"type": "application/vnd.ibm.kms.key+json",
"id": "eb086d96-3b2c-48b5-bf31-c8f0305eea77",
"name": "root-example-key",
"description": "root-example-key",
"state": 1,
"extractable": false,
"crn":"crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:a192d603-0b8d-452f-aac3-f9e1f95e7411:key:eb086d96-3b2c-48b5-bf31-c8f0305eea77",
"imported": false,
"deleted": false
}
]
}{: screen}
Authorize deletion for a key with a dual authorization policy.
# set the KEY_ID
$ KEY_ID=eb086d96-3b2c-48b5-bf31-c8f0305eea77
# this request fails because the key DOES NOT have a dual authorization policy
$ curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys/$KEY_ID/actions/setKeyForDeletion" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.key_action+json"{: codeblock}
{: #not-dual-auth-err-cxt-ex-1-json-2}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Conflict: Action could not be performed on key. Please see `reasons` for more details.",
"reasons": [
{
"code": "NOT_DUAL_AUTH_ERR",
"message":"The key is not dual auth enabled and cannot be set for deletion",
"status": 409,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: screen}
Remove an authorization for a key with a dual authorization policy.
# this request fails because the key DOES NOT have a dual authorization policy
$ curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys/$KEY_ID/actions/unsetKeyForDeletion" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.key_action+json"{: codeblock}
{: #not-dual-auth-err-cxt-ex-1-json-3}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Conflict: Action could not be performed on key. Please see `reasons` for more details.",
"reasons": [
{
"code": "NOT_DUAL_AUTH_ERR",
"message": "The key is not dual auth enabled and cannot be set for deletion",
"status": 409,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: screen}
{: #error-messages-not-dual-auth-err-cxt-ex-2}
This example attempts to authorize a deletion and remove an authorization using the CLI.
Note: the $KEY_ID was set in the previous example.
# this request fails because the key DOES NOT have a dual authorization policy
$ ibmcloud kp key schedule-delete $KEY_ID
Scheduling key for deletion...
FAILED
kp.Error:
correlation_id='3d941968-c599-43b3-b681-306422079412',
msg='Conflict:
Action could not be performed on key.
Please see `reasons` for more details.',
reasons='[NOT_DUAL_AUTH_ERR:
The key is not dual auth enabled and cannot be set for deletion -
FOR_MORE_INFO_REFER: https://cloud.ibm.com/apidocs/key-protect]'
# this request fails because the key DOES NOT have a dual authorization policy
$ ibmcloud kp key cancel-delete $KEY_ID
Cancelling key for deletion...
FAILED
kp.Error:
correlation_id='5b04a667-573c-44d1-82d5-39730af56a75',
msg='Conflict:
Action could not be performed on key.
Please see `reasons` for more details.',
reasons='[NOT_DUAL_AUTH_ERR:
The key is not dual auth enabled and cannot be set for deletion -
FOR_MORE_INFO_REFER: https://cloud.ibm.com/apidocs/key-protect]'{: codeblock}
{: #error-messages-req-too-early-err}
{: #error-messages-req-too-early-err-message}
The key was updated recently: Please wait and try again
Reason code: REQ_TOO_EARLY_ERR
{: #error-messages-req-too-early-err-http}
409 - Conflict
The HTTP 409 Conflict response status code indicates a request conflict with
current state of the server.
Conflicts are most likely to occur in response to a PUT request. For example,
you may get a 409 response when uploading a file which is older than the one
already on the server resulting in a version control conflict.
{: #error-messages-req-too-early-err-cxt}
This error occurs when you enable or restore a key within 30 seconds of the
last action.
You must wait at least 30 seconds between the last "action" and enabling or restoring a key.
This example fails because the key was enabled too soon after disabling a key.
# create a root key
$ KEY_ID=$(ibmcloud kp key create example-key -i $KP_INSTANCE_ID --output json | jq -r '.["id"]')
$ echo $KEY_ID
54f53384-b563-4466-860a-c42ce42f7ac9
# disable the key
$ ibmcloud kp key disable $KEY_ID -i $KP_INSTANCE_ID
Disabling key: '54f53384-b563-4466-860a-c42ce42f7ac9', in instance: 'a192d603-0b8d-452f-aac3-f9e1f95e7411'...
OK
# this request fails because the key was enabled too soon
$ ibmcloud kp key enable $KEY_ID -i $KP_INSTANCE_ID
Enabling key: '54f53384-b563-4466-860a-c42ce42f7ac9', in instance: 'a192d603-0b8d-452f-aac3-f9e1f95e7411'...
FAILED
kp.Error:
correlation_id='59c343a7-c20f-43ea-9e50-da45cecbc8a6',
msg='Conflict:
Key could not be enabled.
Please see `reasons` for more details.',
reasons='[REQ_TOO_EARLY_ERR:
The key was updated recently.
Please wait and try again. -
FOR_MORE_INFO_REFER: https://cloud.ibm.com/apidocs/key-protect]'
# this request succeeds because the key was disabled at least 30 seconds ago
$ ibmcloud kp key enable $KEY_ID -i $KP_INSTANCE_ID
Enabling key: '54f53384-b563-4466-860a-c42ce42f7ac9', in instance: 'a192d603-0b8d-452f-aac3-f9e1f95e7411'...
OK{: codeblock}
{: #error-messages-unprocessable-ciphertext-err}
{: #error-messages-unprocessable-ciphertext-err-message}
The provided ciphertext is invalid or corrupted
Reason code: UNPROCESSABLE_CIPHERTEXT_ERR
{: #error-messages-unprocessable-ciphertext-err-http}
422 - Unprocessable Entity
The HTTP 422 Unprocessable Entity response status code indicates that the
server understands the content type of the request entity, and the syntax of the
request entity is correct, but it was unable to process the contained
instructions.
The client should not repeat this request without modification.
{: #error-messages-unprocessable-ciphertext-err-cxt}
This typically means the hardware security module (HSM) could not process the data because the input was invalid.
This error is returned when there is an internal error.
If you get this error please contact IBM support{: external}
{: #error-messages-incorrect-nonce-iv-err}
{: #error-messages-incorrect-nonce-iv-err-message}
The provided encrypted nonce was not encrypted with the key material given OR the provided IV does not match the encrypted nonce
Reason code: INCORRECT_NONCE_IV_ERR
{: #error-messages-incorrect-nonce-iv-err-http}
400 - Bad Request
The HTTP 400 Bad Request response status code indicates that the server cannot
or will not process the request due to something that is perceived to be a
client error (e.g., malformed request syntax, invalid request message framing,
or deceptive request routing).
The client should not repeat this request without modification.
{: #error-messages-incorrect-nonce-iv-err-cxt}
This typically means the hardware security module (HSM) could not process the data because the input was invalid.
This error is returned when there is an internal error.
If you get this error please contact IBM support{: external}
{: #error-messages-resource-owner-err}
{: #error-messages-resource-owner-err-message}
The resource(s) queried does not belong to the service
Reason code: RESOURCE_OWNER_ERR
{: #error-messages-resource-owner-err-http}
403 - Forbidden
The HTTP 403 Forbidden client error status response code indicates that the
server understood the request but refuses to authorize it.
This status is similar to 401, but in this case, re-authenticating will make
no difference. The access is permanently forbidden and tied to the application
logic, such as insufficient rights to a resource.
{: #error-messages-resource-owner-err-cxt}
This error message occurs in a service-to-service request. The service attempts to delete a key, which is not allowed. That is, another service cannot delete a {{site.data.keyword.keymanagementserviceshort}} key.
One example of using service-to-service access is a user configuring a Cloud Object Storage (COS) bucket to encrypt their data using a {{site.data.keyword.keymanagementserviceshort}} key.
Using the COS example, COS cannot delete the key used to encrypt data.
{: #error-messages-service-only-err}
{: #error-messages-service-only-err-message}
This action can only be done by a service (service to service)
Reason code: SERVICE_ONLY_ERR
{: #error-messages-service-only-err-http}
403 - Forbidden
The HTTP 403 Forbidden client error status response code indicates that the
server understood the request but refuses to authorize it.
This status is similar to 401, but in this case, re-authenticating will make
no difference. The access is permanently forbidden and tied to the application
logic, such as insufficient rights to a resource.
{: #error-messages-service-only-err-cxt}
Some actions, such as creating a "registration", can only be performed by another service, in what is known as a service-to-service request.
For example, if you configuring a Cloud Object Storage (COS) bucket to encrypt data using a {{site.data.keyword.keymanagementserviceshort}} key, then the COS service need to create the registration.
A service-to-service request is required to create, delete, replace, or update a registration.
See this resources for more information about registrations.
- API documentation{: external}
{: #error-messages-feature-restricted-err}
{: #error-messages-feature-restricted-err-message}
This action is not permitted on this resource: Please contact IBM Key Protect or open a service ticket to enable this feature
Reason code: FEATURE_RESTRICTED_ERR
{: #error-messages-feature-restricted-err-http}
403 - Forbidden
The HTTP 403 Forbidden client error status response code indicates that the
server understood the request but refuses to authorize it.
This status is similar to 401, but in this case, re-authenticating will make
no difference. The access is permanently forbidden and tied to the application
logic, such as insufficient rights to a resource.
{: #error-messages-feature-restricted-err-cxt}
You are attempting to create, update, or use an instance policy with a feature that is not supported.
For example, instance policy was created for an allowedIp address range, which
only supports IPv4 addresses. You then made a request to the instance with an
IPv6 address, which returns this error.
{: #error-messages-key-version-invalid}
{: #error-messages-key-version-invalid-message}
This request requires that the key version is later than current registration key version
Reason code: KEY_VERSION_INVALID
{: #error-messages-key-version-invalid-http}
422 - Unprocessable Entity
The HTTP 422 Unprocessable Entity response status code indicates that the
server understands the content type of the request entity, and the syntax of the
request entity is correct, but it was unable to process the contained
instructions.
The client should not repeat this request without modification.
{: #error-messages-key-version-invalid-context}
This error applies to keys used for "Registrations."
When a service, such as Cloud Object Storage (COS), tries to replace or restore a key it checks the timestamp of the key.
If the key timestamp is less than the timestamp of the key used by the registration then this error occurs.
The key used buy the service must have a timestamp equal to or greater than the registration's key.
Registrations are associations between root keys and other cloud resources, such as Cloud Object Storage (COS) buckets or Cloud Databases deployments.
For more information about Registrations, see viewing associations between root keys and encrypted IBM Cloud resources.
{: #error-messages-key-rotation-not-permitted}
{: #error-messages-key-rotation-not-permitted-message}
This root key has been rotated within the last hour: Only one 'rotate' action per hour is permitted
Reason code: KEY_ROTATION_NOT_PERMITTED
{: #error-messages-key-rotation-not-permitted-http}
409 - Conflict
The HTTP 409 Conflict response status code indicates a request conflict with
current state of the server.
Conflicts are most likely to occur in response to a PUT request. For example,
you may get a 409 response when uploading a file which is older than the one
already on the server resulting in a version control conflict.
{: #error-messages-key-rotation-not-permitted-context}
A root key can be rotated, at most, once an hour. Attempting to rotate a root key any sooner than one hour returns this error message.
# step 1 - create a root key and provide a key material
$ KEY_MATERIAL=$(openssl rand -base64 32)
$ echo $KEY_MATERIAL
dlYulSKD5cEG/XoAV8vv4QiQe/s3SlBzPY+PKgq92/0=
$ KEY_ID=$(ibmcloud kp key create rotate-example-key -i $KP_INSTANCE_ID --key-material $KEY_MATERIAL --output json | jq -r '.["id"]')
$ echo $KEY_ID
1604b4f3-6ba0-459c-8f65-400ed981a5eb
# step 2 - this request succeeds because there is no time
# restriction when rotating the key the first time
$ KEY_MATERIAL_NEW_1=$(openssl rand -base64 32)
$ echo $KEY_MATERIAL_NEW_1
rK9CCRHxr8RpVvKQSEvud1zHAPnXl3PvhaPwx2aRxGE=
$ curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys/$KEY_ID/actions/rotate" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.key_action+json" \
-d '{
"payload": "'$KEY_MATERIAL_NEW_1'"
}'
# step 3 - this request fails because the key was
# last rotated less than one hour ago
$ KEY_MATERIAL_NEW_2=$(openssl rand -base64 32)
$ echo $KEY_MATERIAL_NEW_2
pQX+ghaaH/r/s54ICWuwq3jQDPWlHQMDhAV0mwpBf2w=
$ curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys/$KEY_ID/actions/rotate" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.key_action+json" \
-d '{
"payload": "'$KEY_MATERIAL_NEW_2'"
}'{: codeblock}
{: #error-messages-key-rotation-not-permitted-context-json}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Conflict: Action could not be performed on key: Please see `reasons` for more details (KEY_ROTATION_NOT_PERMITTED)",
"reasons": [
{
"code": "KEY_ROTATION_NOT_PERMITTED",
"message": "This root key has been rotated within the last hour: Only one 'rotate' action per hour is permitted",
"status": 409,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}{: screen}
{: #error-messages-key-payload-req-err}
{: #error-messages-key-payload-req-err-message}
This root key was created with user-supplied key material: Key material is required to perform a 'rotate' action
Reason code: KEY_PAYLOAD_REQ_ERR
{: #error-messages-key-payload-req-err-http}
400 - Bad Request
The HTTP 400 Bad Request response status code indicates that the server cannot
or will not process the request due to something that is perceived to be a
client error (e.g., malformed request syntax, invalid request message framing,
or deceptive request routing).
The client should not repeat this request without modification.
{: #error-messages-key-payload-req-err-cxt}
If a root key was created with a key material (payload), then a key material must be specified to rotate the key.
# step 1 - create a root key and provide a key material
$ KEY_MATERIAL=$(openssl rand -base64 32)
$ echo $KEY_MATERIAL
HpHM2YG9PMLBo4fZmV2WODZTTWlwaKmy496MoCE7w7U=
$ KEY_ID=$(ibmcloud kp key create rotate-example-key -i $KP_INSTANCE_ID --key-material $KEY_MATERIAL --output json | jq -r '.["id"]')
$ echo $KEY_ID
e52ee578-af71-4cd7-ba19-f1a8020d6a10
# step 2 - rotate the key without a new key material
$ curl -X POST \
"https://us-south.kms.cloud.ibm.com/api/v2/keys/$KEY_ID/actions/rotate" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.key_action+json"{: codeblock}
{: #error-messages-key-payload-req-err-cxt-json}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Bad Request: Action could not be performed on key: Please see `reasons` for more details (KEY_PAYLOAD_REQ_ERR)",
"reasons": [
{
"code": "KEY_PAYLOAD_REQ_ERR",
"message": "This root key was created with user-supplied key material: Key material is required to perform a 'rotate' action",
"status": 400,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
"target": {
"type": "field",
"name": "payload"
}
}
]
}
]
}{: screen}
{: #error-messages-unauthorized-err}
{: #error-messages-unauthorized-err-message}
Unauthorized: The user does not have access to the specified resource
Reason code: UNAUTHORIZED_ERR
{: #error-messages-unauthorized-err-http}
401 - Unauthorized
The HTTP 401 Unauthorized client error status response code indicates that the
request has not been applied because it lacks valid authentication credentials
for the target resource.
This status is sent with a WWW-Authenticate header that contains information
on how to authorize correctly.
This status is similar to 403, but in this case, authentication is possible.
{: #error-messages-unauthorized-err-cxt}
This error message is returned when the user does not have access to a resource.
This example applies an instance policy that limits access to a range of IP addresses. When a request from outside the allowed range is received it returns an error.
# limit access to a range of IP addresses
$ curl -X PUT \
"https://us-south.kms.cloud.ibm.com/api/v2/instance/policies?policy=allowedIP" \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "bluemix-instance: $KP_INSTANCE_ID" \
-H "content-type: application/vnd.ibm.kms.policy+json" \
-d '{
"metadata": {
"collectionType": "application/vnd.ibm.kms.policy+json",
"collectionTotal": 1
},
"resources": [
{
"policy_type": "allowedIP",
"policy_data": {
"enabled": true,
"attributes": {
"allowed_ip": [
"65.128.226.252/24"
]
}
}
}
]
}'Retrieving keys will fail because the request is outside the allowed range of IP addresses.
# this fails because the request is outside the allowed range of IP addresses
$ curl -X GET \
"https://us-south.kms.cloud.ibm.com/api/v2/keys" \
-H "authorization: Bearer $ACCESS_TOKEN"
-H "bluemix-instance: $KP_INSTANCE_ID"{: codeblock}
{: #error-messages-unauthorized-err-cxt-json}
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Unauthorized: The user does not have access to the specified resource"
}
]
}{: #error-messages-sorted-by-http-status-code}
These are the error messages, sorted the the HTTP status code.
{: #error-messages-http-400}
-
Collection total does not match number of resources - details
-
Data in body does not match data required by query parameter - details
-
Extracting the subject from the bearer token failed: Make sure the bearer token passed is the correct one (and correct format) and is allowed to perform requested actions - details
-
Invalid body data was passed: Please ensure the data passed had valid formatting with no invalid characters - details
-
Invalid field error: for wrap
The field 'plaintext' must be: a base64 encoded key materialif invalid plaintext is passed in the request; andThe field 'ciphertext' must be: the original base64 encoded ciphertext from the wrap operationfor unwrap if invalid ciphertext is passed. - details -
Key restoration has expired - details
-
Missing body in request - details
-
Only a single instance policy may be created per query parameter: Please pass single resource object - details
-
Only imported keys may be restored - details
-
Requested action can only be completed with a root key - details
-
The action could not be performed on the key because the key is expired - details
-
The encrypted nonce given does not match existing record: Please ensure the correct nonce was given in the request - details
-
The provided encrypted nonce was not encrypted with the key material given OR the provided IV does not match the encrypted nonce - details
-
This root key was created with user-supplied key material: Key material is required to perform a 'rotate' action - details
{: #error-messages-http-401}
- Unauthorized: The user does not have access to the specified resource - details
{: #error-messages-http-403}
-
Requested change is not compliant with configuration rules - details
-
The resource(s) queried does not belong to the service - details
-
This action can only be done by a service (service to service) - details
-
This action is not permitted on this resource: Please contact IBM Key Protect or open a service ticket to enable this feature - details
{: #error-messages-http-409}
-
Key is not in a valid state - details
-
Key is protecting one or more cloud resources - details
-
KeyCreateImportAccess instance policy does not allow this action - details
-
Number of authorizations required to delete is not met - details
-
The import token has expired - details
-
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 - details
-
The key is not dual auth enabled and cannot be set for deletion - details
-
The key was updated recently: Please wait and try again - details
-
This root key has been rotated within the last hour: Only one 'rotate' action per hour is permitted - details
{: #error-messages-http-410}
- Key has already been deleted: Please delete references to this key - details
{: #error-messages-http-422}
-
Key is not in a valid state - details
-
Requested action can only be completed with a root key - details
-
Signature is invalid details
-
The provided ciphertext is invalid or corrupted - details
-
This request requires that the key version is later than current registration key version - details
{: #error-messages-http-500}
- Key metadata became corrupted: Please delete this key - details
{: #error-messages-sorted-by-reason-code}
This section sorts error messages by the reason code.
- AUTHORIZATIONS_NOT_MET - details
- BAD_BODY_ERR - details
- BEARER_SUB_EXTRACTION_ERR - details
- BODY_QUERY_PARAM_MISMATCH_ERR - details
- COLLECTION_TOTAL_MISMATCH_ERR - details
- CONFIG_RULE_CONFLICT_ERR details
- FEATURE_RESTRICTED_ERR - details
- IMPORT_TOKEN_EXPIRED_ERR - details
- INCOMPLETE_METADATA_ERR - details
- INCORRECT_NONCE_ERR - details
- INCORRECT_NONCE_IV_ERR - details
- INVALID_FIELD_ERR - details
- INVALID_SIG_EXP_ERR details
- KEY_ACTION_INVALID_STATE_ERR - details
- KEY_CREATE_IMPORT_ACCESS_ERR - details
- KEY_DELETED_ERR - details
- KEY_EXPIRED_ERR - details
- KEY_IMPT_REQ_ERR - details
- KEY_INVALID_STATE_ERR - details
- KEY_PAYLOAD_REQ_ERR - details
- KEY_RESTORE_EXPIRED - details
- KEY_ROOT_REQ_ERR - details
- KEY_ROOT_REQ_REG_ERR - details
- KEY_ROTATION_NOT_PERMITTED - details
- KEY_VERSION_INVALID - details
- NO_BODY_ERR - details
- NOT_DUAL_AUTH_ERR - details
- NUM_COLLECTION_RESOURCE_ERR - details
- PREV_KEY_DEL_ERR - details
- PROTECTED_RESOURCE_ERR - details
- REQ_TOO_EARLY_ERR - details
- RESOURCE_OWNER_ERR - details
- SERVICE_ONLY_ERR - details
- UNAUTHORIZED_ERR - details
- UNPROCESSABLE_CIPHERTEXT_ERR - details