Managing the key create and import access policy

After you set up your IBM Cloud® Hyper Protect Crypto Services instance, you can manage the key create and import access policy by using the Hyper Protect Crypto Services key management service API.

This policy applies only to key management service keys and related operations.

Understanding the key create and import access settings

The Key create and import access policy for Hyper Protect Crypto Services instances manage how keys are created and imported into your Hyper Protect Crypto Services instance.

When you enable this policy, Hyper Protect Crypto Services only permits the creation or importation of keys in your Hyper Protect Crypto Services instance that follow the key creation and importation settings that are listed on the key create and import access policy.

Setting and retrieving the key create and import access policy is supported through the API only. To find out more about accessing the Hyper Protect Crypto Services key management service API, check out Setting up the API.

Before you enable the key create and import access policy for your Hyper Protect Crypto Services instance, keep in mind the following considerations:

KeyCreateImportAccess policies do not affect keys that existed before policy creation.

KeyCreateImportAccess policies affect only Hyper Protect Crypto Services requests that are sent after the policy is set. You still have access to all keys that existed in your Hyper Protect Crypto Services instance before the policy is created.
KeyCreateImportAccess policies can affect your keys across various key actions.

The enforce_token attribute affects imported keys during creation, rotation, and restoration. The create_root_key, import_root_key, create_standard_key, and import_standard_key attributes affect keys only at creation time. All other Hyper Protect Crypto Services actions, such as wrap and unwrap, are not affected and can be invoked on the key as usual.

Enabling or updating the key create and import access policy for your service instance with the UI

As a security administrator, if you prefer to manage the key create and import access policy settings by using a graphical interface, you can use the UI.

After you create a Hyper Protect Crypto Services instance, complete the following steps to enable the key create and import access policy:

Log in to the UI.
Go to Menu > Resource list to view a list of your resources.
From your IBM Cloud resource list, select your provisioned instance of Hyper Protect Crypto Services.
In the UI of the selected service instance, select the Instance policies tab in the side menu.
In the Create and import key access section, check or clear the corresponding boxes to update the keyCreateImportAccess settings, and then click Save policy.
- Allow creation of root keys: Check the box to allow root keys to be created in your Hyper Protect Crypto Services instance.
- Allow creation of standard keys: Check the box to allow standard keys to be created in your Hyper Protect Crypto Services instance.
- Allow import of root keys: Check the box to allow root keys to be imported into your Hyper Protect Crypto Services instance.
- Allow import of standard keys: Check the box to allow standard keys to be imported into your Hyper Protect Crypto Services instance.
- Enable secure import: Check the box to prevent authorized users from importing key material into your Hyper Protect Crypto Services instance without using an import token.
After you check the box for Enable secure import, it is required that secure import is enabled for all key import actions. Secure import is not available in the UI, and you need to perform further actions through the CLI or API.

Any disabled key actions are not available in the Add key panel. After you check the box for Secure import, it is required that secure import is enabled for all key import actions. Key import is not available in the UI, and you need to perform further actions through the CLI or API.

Enabling and updating the key create and import access policy for your service instance with the API

As a security administrator, you can enable or update the key create and import access policy for a Hyper Protect Crypto Services instance by making a PUT call to the following endpoint.

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

If you are updating the key create and import access policy of your Hyper Protect Crypto Services instance, keep in mind that if an attribute is omitted from the request, the field is set to the default value, and the existing value for the omitted field is overwritten by the default value.

Retrieve your authentication credentials to work with the API.

To enable keyCreateImportAccess policies, you need Manager access to your Hyper Protect Crypto Services instance. To learn how IAM roles map to Hyper Protect Crypto Services actions, check out Service access roles.

Enable or update the key create and import access policy for your Hyper Protect Crypto Services instance by running the following cURL command.

$ curl -X PUT \
    "https://api.<region>.hs-crypto.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 needed to enable the key create and import access policy
Variable	Description
`region`	Required. The region abbreviation, such as `us-south` or `eu-de`, that represents the geographic area where your Hyper Protect Crypto Services 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 Hyper Protect Crypto Services 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 Hyper Protect Crypto Services instance. Set to `false` to prevent root keys from being created in your instance. If this attribute is omitted, `true` is set as the default value.
`create_standard_key`	Required. Set to `true` to allow standard keys to be created in your Hyper Protect Crypto Services instance. Set to `false` to prevent standard keys from being created in your instance. If this attribute is omitted, `true` is set as the default value.
`import_root_key`	Required. Set to `true` to allow root keys to be imported into your Hyper Protect Crypto Services instance. Set to `false` to prevent root keys from being imported into your instance. If this attribute is omitted, `true` is set as the default value.
`import_standard_key`	Required. Set to `true` to allow standard keys to be imported into your Hyper Protect Crypto Services instance. Set to `false` to prevent standard keys from being imported into your instance. If this attribute is omitted, `true` is set as the default value.
`enforce_token`	Required. Set to `true` to prevent authorized users from importing key material into your Hyper Protect Crypto Services 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 `enforce_token` is enabled, it is required that secure import is enabled for all key import actions. Key import is not available through UI, and you need to perform further actions through the CLI or API. If this attribute is omitted, `false` is set as the default value.

A successful request returns an HTTP 204 No Content response, which indicates that your Hyper Protect Crypto Services instance now has enabled. Your Hyper Protect Crypto Services instance can now only allow the creation or importation of keys from the methods that are specified in your request.

Optional: Verify that the key create and import access policy is created or updated by retrieving the policy details for your Hyper Protect Crypto Services instance.

$ curl -X GET \
    "https://api.<region>.hs-crypto.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>"

Disabling the key create and import access policy for your service instance with the key management service API

As a manager of a Hyper Protect Crypto Services instance, to disable the key create and import access policy with the key management service API, make a PUT call to the following endpoint.

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

Do not provide any attributes when you make a request to disable your key create and import access policy.

Retrieve your authentication credentials to work with the API.

To disable keyCreateImportAccess policies, you need a Manager access to your Hyper Protect Crypto Services instance. To learn how IAM roles map to Hyper Protect Crypto Services actions, check out Service access roles.

Disable the existing key create and import access policy for your Hyper Protect Crypto Services instance by running the following cURL command.

$ curl -X PUT \
    "https://api.<region>.hs-crypto.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 needed to disable the key create and import access policy
Variable	Description
`region`	Required. The region abbreviation, such as `us-south`, that represents the geographic area where your Hyper Protect Crypto Services 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 Hyper Protect Crypto Services instance. For more information, see Retrieving an instance ID.

A successful request returns an HTTP 204 No Content response, which indicates that the key create and import access policy is updated for your service instance.

Optional: Verify that the key create and import access policy is disabled by retrieving the policy details for your Hyper Protect Crypto Services instance.

$ curl -X GET \
    "https://api.<region>.hs-crypto.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>"