Message

Collection total does not match number of resources

Reason code: COLLECTION_TOTAL_MISMATCH_ERR

HTTP status code

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.

Context

This error occurs when an instance policy 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
                    }
                }
            ]
        }'

{
    "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"
                }
            ]
        }
    ]
}

Message

Data in body does not match data required by query parameter

Reason code: BODY_QUERY_PARAM_MISMATCH_ERR

HTTP status code

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.

Context

This error occurs when an instance policy 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
                    }
                }
            ]
        }'

{
    "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"
                }
            ]
        }
    ]
}

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

HTTP status code

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.

Context

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"

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.

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

Message

Invalid body data was passed: Please ensure the data passed had valid formatting with no invalid characters

Reason code: BAD_BODY_ERR

HTTP status code

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.

Context

Some examples of this error are:

• Create an instance policy

  • Only one of each policy can be created
  • No resources section was provided
  • Extraneous fields in the resources section (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

# 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"
                }
            ]
        }'

{
    "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"
                }
            ]
        }
    ]
}

# 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
                }
            ]
        }'

{
    "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"
                }
            ]
        }
    ]
}

# 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
                }
            ]
        }'

{
    "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"
                }
            ]
        }
    ]
}

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.

HTTP status code

400

Context

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;",
}'

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"
                    }
                }
            ]
        }
    ]
}

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"
}'

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"
                    }
                }
            ]
        }
    ]
}

HTTP status code

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.

Context

The message returns a reason in the message that provides the specific context.

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.

{
    "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"
                }
            ]
        }
    ]
}

{
    "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"
                }
            ]
        }
    ]
}

{
    "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"
                }
            ]
        }
    ]
}

Message

Key has already been deleted: Please delete references to this key

Reason code: KEY_DELETED_ERR

HTTP status code

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.

Context

The delete key request fails because the key was previously deleted. You cannot delete a key more than once.

# 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"

{
    "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"
                }
            ]
        }
    ]
}

Message

Key is not in a valid state

Reason code: KEY_ACTION_INVALID_STATE_ERR

HTTP status code

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.

Context

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)

# 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"

{
    "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"
                }
            ]
        }
    ]
}

# 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
                }
            ]
        }'

{
    "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
        }
    ]
}

# 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"

{
    "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"
                }
            ]
        }
    ]
}

Message

Key is not in a valid state

Reason code: KEY_INVALID_STATE_ERR

HTTP status code

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.

Context

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.

Message

Key is protecting one or more cloud resources

Reason code: PROTECTED_RESOURCE_ERR

HTTP status code

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.

Context

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"
}

Message

Key metadata became corrupted: Please delete this key

Reason code: INCOMPLETE_METADATA_ERR

HTTP status code

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.

Context

This error is returned when there is an internal error.

If you get this error please contact IBM support

Message

Key restoration has expired

Reason code: KEY_RESTORE_EXPIRED

HTTP status code

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.

Context

This error occurs when you try to restore a key that was deleted more than 30 days ago.

Message

KeyCreateImportAccess instance policy does not allow this action

Reason code: KEY_CREATE_IMPORT_ACCESS_ERR

HTTP status code

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.

Context

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.

# 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
                }
            ]
        }'

{
    "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"
                }
            ]
        }
    ]
}

# 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
                }
            ]
        }'

{
    "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
        }
    ]
}

Message

Missing body in request

Reason code: NO_BODY_ERR

HTTP status code

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.

Context

This error occurs when you "rewrap" or "unwrap" a key and there is no body.

# 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"

{
    "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"
                }
            ]
        }
    ]
}

# 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'"
        }'

{
    "plaintext": "2eLAD3LyD3H2bq8dIDAy0A/lN9DSE/Ne3bwu40CdErs=",
    "keyVersion": {
        "id": "66ffaf5b-86c8-4a50-8a2a-920ae71f86dc"
    }
}

Message

Number of authorizations required to delete is not met

Reason code: AUTHORIZATIONS_NOT_MET

HTTP status code

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.

Context

A key with a dual authorization policy cannot be deleted without an authorization from two users.

# 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"

{
    "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"
                }
            ]
        }
    ]
}

Message

Only a single instance policy may be created per query parameter: Please pass single resource object

Reason code: NUM_COLLECTION_RESOURCE_ERR

HTTP status code

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.

Context

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.

# 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
                    }
                }
            ]
        }'

{
    "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"
                }
            ]
        }
    ]
}

Message

Only imported keys may be restored

Reason code: KEY_IMPT_REQ_ERR

HTTP status code

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.

Context

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

# 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'"
                }
            ]
        }'

{
    "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"
                }
            ]
        }
    ]
}

Message

Requested action can only be completed with a root key

Reason code: KEY_ROOT_REQ_ERR

HTTP status code

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.

Context

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

# 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"

{
    "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"
                }
            ]
        }
    ]
}

Message

Requested action can only be completed with a root key

Reason code: KEY_ROOT_REQ_REG_ERR

HTTP status code

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.

Context

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

Message

Requested change is not compliant with configuration rules

Reason code: CONFIG_RULE_CONFLICT_ERR

HTTP status code

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.

Context

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.

Message

Signature is invalid

Reason code: INVALID_SIG_EXP_ERR

HTTP status code

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.

Context

An error occurred when a key was rewrapped.

If you get this error please contact IBM support

Message

The action could not be performed on the key because the key is expired

Reason code: KEY_EXPIRED_ERR

HTTP status code

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.

Context

This error occurs when restoring a deleted key after the key has expired.

# 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
                }
            ]
        }'

{
    "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
        }
    ]
}

# 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'"
                }
            ]
        }'

{
    "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"
                }
            ]
        }
    ]
}

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

HTTP status code

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.

Context

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.

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

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]'

Message

The import token has expired

Reason code: IMPORT_TOKEN_EXPIRED_ERR

HTTP status code

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.

Context

# 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
        }'

{
    "maxAllowedRetrievals": 2,
    "creationDate": "2020-08-18T19:54:57Z",
    "expirationDate": "2020-08-18T19:59:57Z",
    "remainingRetrievals":2
}

# 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"

{
    "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"
                }
            ]
        }
    ]
}

# 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]'

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

HTTP status code

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.

Context

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.

Message

The key is not dual auth enabled and cannot be set for deletion

Reason code: NOT_DUAL_AUTH_ERR

HTTP status code

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.

Context

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.

# 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
                }
            ]
        }'

{
    "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
        }
    ]
}

# 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"

{
    "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"
                }
            ]
        }
    ]
}

# 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"

{
    "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"
                }
            ]
        }
    ]
}

# 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]'

Message

The key was updated recently: Please wait and try again

Reason code: REQ_TOO_EARLY_ERR

HTTP status code

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.

Context

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

Message

The provided ciphertext is invalid or corrupted

Reason code: UNPROCESSABLE_CIPHERTEXT_ERR

HTTP status code

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.

Context

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

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

HTTP status code

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.

Context

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

Message

The resource(s) queried does not belong to the service

Reason code: RESOURCE_OWNER_ERR

HTTP status code

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.

Context

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 Key Protect 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 Key Protect key.

Using the COS example, COS cannot delete the key used to encrypt data.

Message

This action can only be done by a service (service to service)

Reason code: SERVICE_ONLY_ERR

HTTP status code

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.

Context

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 Key Protect 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

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

HTTP status code

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.

Context

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.

Message

This request requires that the key version is later than current registration key version

Reason code: KEY_VERSION_INVALID

HTTP status code

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.

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.

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

HTTP status code

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.

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'"
        }'

{
    "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"
                }
            ]
        }
    ]
}

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

HTTP status code

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.

Context

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"

{
    "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"
                    }
                }
            ]
        }
    ]
}

Message

Unauthorized: The user does not have access to the specified resource

Reason code: UNAUTHORIZED_ERR

HTTP status code

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.

Context

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"

{
    "metadata": {
        "collectionType": "application/vnd.ibm.kms.error+json",
        "collectionTotal": 1
    },
    "resources": [
        {
            "errorMsg": "Unauthorized: The user does not have access to the specified resource"
        }
    ]
}

HTTP 400 - Bad Request

• 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 material if invalid plaintext is passed in the request; and The field 'ciphertext' must be: the original base64 encoded ciphertext from the wrap operation for 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

HTTP 401 - Unauthorized

• Unauthorized: The user does not have access to the specified resource - details

HTTP 403 - Forbidden

• 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

HTTP 409 - Conflict

• 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

HTTP 410 - Gone

• Key has already been deleted: Please delete references to this key - details

HTTP 422 - Unprocessable Entity

• 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

HTTP 500 - Internal Server Error

• Key metadata became corrupted: Please delete this key - details