Managing a key create and import access policy

After you set up your IBM® Key Protect service instance, you can manage keyCreateImportAccess policies by using the IBM® Key Protect service API.

Managing keyCreateImportAccess settings

A keyCreateImportAccess policy for Key Protect instances is an access policy that you can use to restrict how keys are created and imported into your Key Protect instance.

When you enable this policy, Key Protect only permits the creation or importation of keys in your Key Protect instance that follow the key creation and importation settings listed on the keyCreateImportAccess policy.

Setting and retrieving a keyCreateImportAccess policy is supported through the application programming interface (API). KeyCreateImportAccess policy support will be added to the user interface (UI), command line interface (CLI), and software development kit (SDK) in the future. To find out more about accessing the Key Protect APIs, check out Setting up the API.

Before you enable a keyCreateImportAccess policy for your Key Protect instance, keep in mind the following considerations:

KeyCreateImportAccess policies do not affect keys that existed prior to policy creation. KeyCreateImportAccess policies only affect Key Protect requests that are sent after the policy is set. You will still have access to all keys that existed in your Key Protect instance prior to policy creation.
KeyCreateImportAccess policies can affect your keys across various key actions. The enforce_token attribute will affect imported keys during creation, rotation, and restoration. The create_root_key, import_root_key, create_standard_key, and import_standard_key attributes will only affect keys at creation time. All other Key Protect actions (wrap, unwrap, etc.) are unaffected and can be invoked on the key as usual.

Enabling and updating a keyCreateImportAccess policy for your Key Protect instance with the console

If you prefer to manage keyCreateImportAccess policy settings using Key Protect's graphical interface, you can use the IBM Cloud console.

If "enforce_token" is enabled, all import key actions will not be available in the UI. The "enforce_token" option makes Secure Import a requirement for all key imports. Secure Import support is only available in the Key Protect CLI or API.

After creating a Key Protect instance, complete the following steps to enable a keyCreateImportAccess policy:

Log in to the IBM Cloud console.
Go to Menu > Resource List to view a list of your resources.
From your IBM Cloud resource list, select your provisioned instance of Key Protect.
Click the Instance policies link on the left side of the page.
- Find the Create and import access panel (at the top of the page).
- Enable or disable any keyCreateImportAccess settings you desire. Note that any create or import key actions that have been disabled will no longer be available via the "Add Key" modal.
- Click Save or Cancel (whichever is appropriate).

Enabling and updating a keyCreateImportAccess policy for your Key Protect instance with the API

As a security admin, you can enable or update a keyCreateImportAccess policy for a Key Protect instance by making a PUT call to the following endpoint.

https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=keyCreateImportAccess

If you are updating your Key Protect instance's keyCreateImportAccess policy, keep in mind that if an attribute is omitted from the request, the field will be set to the default value and the existing value for the omitted field will be overwritten with the default value.

Retrieve your authentication credentials to work with the API.

To enable keyCreateImportAccess policies, you must be assigned a Manager access policy for your Key Protect instance. To learn how IAM roles map to Key Protect service actions, check out Service access roles.

Enable or update a keyCreateImportAccess policy for your Key Protect instance by running the following curl command.

$ curl -X PUT \
    "https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=keyCreateImportAccess" \
    -H "accept: application/vnd.ibm.kms.policy+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>" \
    -H "content-type: application/vnd.ibm.kms.policy+json" \
    -d '{
            "metadata": {
                "collectionType": "application/vnd.ibm.kms.policy+json",
                "collectionTotal": 1
            },
            "resources": [
                {
                    "policy_type": "keyCreateImportAccess",
                    "policy_data": {
                        "enabled": true,
                        "attributes": {
                            "create_root_key": <true/false>,
                            "create_standard_key": <true/false>,
                            "import_root_key": <true/false>,
                            "import_standard_key": <true/false>,
                            "enforce_token": <true/false>
                        }
                    }
                }
            ]
        }'

Replace the variables in the example request according to the following table.

Table 1. Describes the variables that are needed to enable a keyCreateImportAccess policy.
Variable	Description
region	Required. The region abbreviation, such as `us-south` or `eu-gb`, that represents the geographic area where your Key Protect instance resides. For more information, see Regional service endpoints.
IAM_token	Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the curl request. For more information, see Retrieving an access token.
instance_ID	Required. The unique identifier that is assigned to your Key Protect service instance. For more information, see Retrieving an instance ID.
create_root_key	Required. Set to true to allow root keys to be created in your Key Protect instance. Set to false to prevent root keys from being created in your instance Note: If omitted, POST /instance/policies will set this attribute to the default value (true).
create_standard_key	Required. Set to true to allow standard keys to be created in your Key Protect instance. Set to false to prevent standard keys from being created in your instance. Note: If omitted, POST /instance/policies will set this attribute to the default value (true).
import_root_key	Required. Set to true to allow root keys to be imported into your Key Protect instance. Set to false to prevent root keys from being imported into your instance Note: If omitted, POST /instance/policies will set this attribute to the default value (true).
import_standard_key	Required. Set to true to allow standard keys to be imported into your Key Protect instance. Set to false to prevent standard keys from being imported into your instance. Note: If omitted, POST /instance/policies will set this attribute to the default value (true).
enforce_token	Required. Set to `true` to prevent authorized users from importing key material into the your Key Protect instance without using an import token. Set to `false` to allow authorized users to import key material into your instance without using an import token. If enabled, this attribute will take precedence over the import_root_key and import_standard_key attributes. Note: If omitted, POST /instance/policies will set this attribute to the default value (false).

A successful request returns an HTTP 204 No Content response, which indicates that your Key Protect instance now has an enabled keyCreateImportAccess policy. Your Key Protect instance will now only allow the creation or importation of keys from the methods specified in your request.

Optional: Verify key create import access policy enablement

You can verify that a key create import access policy has been enabled by issuing a list policies request:

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=keyCreateImportAccess" \
    -H "accept: application/vnd.ibm.kms.policy+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

Where the <instance_ID> is the name of your instance and your <IAM_token> is your IAM token.

Disabling a keyCreateImportAccess policy for your Key Protect instance

As a manager of a Key Protect instance, disable an existing keyCreateImportAccess policy for your Key Protect instance by making a PUT call to the following endpoint.

https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=keyCreateImportAccess

Do not provide any attributes when making a request to disable your keyCreateImportAccess policy.

Retrieve your authentication credentials to work with the API.

To disable keyCreateImportAccess policies, you must be assigned a Manager access policy for your Key Protect instance. To learn how IAM roles map to Key Protect service actions, check out Service access roles.

Disable an existing keyCreateImportAccess policy for your Key Protect instance by running the following curl command.

$ curl -X PUT \
    "https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=keyCreateImportAccess" \
    -H "accept: application/vnd.ibm.kms.policy+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>" \
    -H "content-type: application/vnd.ibm.kms.policy+json" \
    -d '{
            "metadata": {
                "collectionType": "application/vnd.ibm.kms.policy+json",
                "collectionTotal": 1
            },
            "resources": [
                {
                    "policy_type": "keyCreateImportAccess",
                    "policy_data": {
                        "enabled": false
                    }
                }
            ]
        }'

Replace the variables in the example request according to the following table.

Table 2. Describes the variables that are needed to disable a keyCreateImportAccess policy.
Variable	Description
region	Required. The region abbreviation, such as `us-south` or `eu-gb`, that represents the geographic area where your Key Protect instance resides. For more information, see Regional service endpoints.
IAM_token	Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the curl request. For more information, see Retrieving an access token.
instance_ID	Required. The unique identifier that is assigned to your Key Protect service instance. For more information, see Retrieving an instance ID.

A successful request returns an HTTP 204 No Content response, which indicates that the keyCreateImportAccess policy was updated for your service instance.

Optional: Verify key create import access policy enablement

You can verify that a key create import access policy has been disabled by issuing a list policies request:

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=keyCreateImportAccess" \
    -H "accept: application/vnd.ibm.kms.policy+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

Where the <instance_ID> is the name of your instance and your <IAM_token> is your IAM token.