Initializing Dedicated Key Protect by creating an instance, credentials, and a master key

Before you begin

If you do not have the latest version of the IBM Cloud CLI, you might not be able to initialize your instance. Help ensure your initialization succeeds by updating to the latest version of the CLI plugin.

You must use the latest version of the CLI to complete the initialization, even if you deploy your instance using the console. If you receive the - Unable to obtain plug-in's metadata error, while installing the latest version of KP CLI plugin, see troubleshooting steps.

Provisioning your instance in the console

To provision your instance in the console, follow the instructions here and select the "Dedicated" tile in the catalog. The provisioning process can take several minutes.

Once your instance is provisioned, you are ready to generate admin credentials and claim your crypto units.

If you do not specify a number of crypto units, your instance is provisioned with two. You can also specify three crypto units using the drop down. Whether you specify two or three crypto units, note that the value cannot be changed later.

Provisioning your instance in the CLI

Before crypto units can be created and your instance initialized, your instance must be created. First, set a resource group to target by issuing:

ibmcloud target -c <resource-group>

If you don't know your resource group, you can find out which ones you have by issuing:

ibmcloud resource groups

After you have your resource group set, create the instance by issuing:

ibmcloud resource service-instance-create <INSTANCE_NAME> kms dedicated us-south 
ibmcloud resource service-instance-create <INSTANCE_NAME> kms dedicated us-south 

Where:

• <INSTANCE_NAME> is the name you give your instance.

Note that this command defaults you to two crypto units. You can specify three crypto units by issuing:

ibmcloud resource service-instance-create <INSTANCE_NAME> kms dedicated us-south -p '{"crypto_units": 3}'
ibmcloud resource service-instance-create <INSTANCE_NAME> kms dedicated us-south -p '{"crypto_units": 3}'

If you specify a number of crypto units other than 2 or 3, an error is returned. You cannot change the number of crypto units later.

Provisioning a Dedicated instance can take several minutes. You can check on the status on your instance by issuing:

ibmcloud resource service-instance <INSTANCE_NAME>

Where:

• <INSTANCE_NAME> is the name you gave your instance in the previous step.

The instance can have one of two states, active or in progress. Note that an active instance has nevertheless not yet been initialized, as that requires completing the remaining steps in this topic. Until you initialize your instance, it cannot be used, as your identities have not yet been configured with your crypto units to create the master key.

Getting the endpoint

Once your instance is active, get the endpoint and GUID by issuing:

ibmcloud resource service-instance <INSTANCE_NAME> -o json 

Where:

• <INSTANCE_NAME> is the name you gave your instance in the previous step.

The endpoint is the public parameter value in the endpoints stanza of the json output above. It takes the format https://<instance-id>.api.<region>.kms.appdomain.cloud. The GUID is the GUID parameter value in the output above. It takes the format of UUID.

You can get the endpoint by issuing: ibmcloud resource service-instance <\kp-instance-id\> --output json | jq -r '.[].extensions.endpoints'.

Save the full endpoint as an environment variable by issuing:

export KP_TARGET_ADDR=<ST_INSTANCE_ENDPOINT>

And:

export KP_INSTANCE_ID=<GUID>

Where:

• <ST_INSTANCE_ENDPOINT> is the full endpoint of your instance, taking the format of https://<instance-id>.api.<region>.kms.appdomain.cloud.
• <GUID> is the instance ID from above output.

You are now ready to generate admin credentials.

You might have to wait for a few minutes after provisioning before your crypto units are available.

For more information on the states a crypto unit can be in, check out Crypto unit states.

Generating admin credentials and claiming your crypto units

A crypto unit is managed by an admin or admins, which means you either need to have identities available or create them. If you have properly formatted admin identities (a symmetric 256-bit AES key using RSA-2048), you can skip down to Create the master key.

ibmcloud kp crypto-unit sig-key generate --file <ADMIN_KEY_FILE> --passphrase <PWD> --algo RSA-2048 

ibmcloud kp crypto-units

*******************************************************  
Id                                     InstanceID                             State  
6e0aead3-9d44-4c92-a4c4-f7a1ab415420   c28a8939-3980-4697-a80c-50b1f8bbf160   reserved  
3bb363fc-b1f9-4237-b37b-2c9e07784e3c   c28a8939-3980-4697-a80c-50b1f8bbf160   reserved  
*******************************************************  

ibmcloud kp crypto-unit claim --credential <ADMIN_KEY_FILE>

Generating and importing the master key

Because you are importing your master key credentials, Key Protect has no access or backups of that key. Keep records of your master key in a safe location.

Now that you have created your instance and your admin identity, you can use them to create your master key. The master key, also known as HSM master key, is used to encrypt the service instance for key storage. It is a symmetric 256-bit AES key. With the master key, you take the ownership of the cloud HSM and own the root of trust that encrypts the entire hierarchy of encryption keys, including root keys and standard keys in the key management keystore. One service instance can have only one master key. If you delete the master key of the service instance, you can effectively crypto-shred all data that was encrypted with the keys that are managed in the service.

Dedicated Key Protect uses the process of "key spliting", in which a cryptographic key is split into multiple pieces to enhance security. At least 2 "keyshares" must be created, though more can be used depending on the use case.

To generate the master key locally, issue:

ibmcloud kp crypto-unit mk generate --keyshare-files '["<KEYSHARE_FILE_1>#<PASSWORD1>", "<KEYSHARE_FILE_2>#<PASSWORD2>"]' --keyshare-minimum 2 --algo AES-256 --key-name <KEY_NAME> --auth '[{"ADMIN": "<ADMIN_KEY_FILE>#<PASSOWRD3>"}]' 

Where:

• <KEYSHARE_FILE_1>#<PASSWORD1> is the location of one of the keyshares, along with a passphrase for the file that is created. The passphrase is mandatory and must be between 6-255 characters.
• <KEYSHARE_FILE_2>#<PASSWORD2> is the location of another keyshare, along with a passphrase for the file that is created. Note that the passphrase is optional but if one is set, it must have at least six characters.
• <KEY_NAME> is the name of your master key.
• <ADMIN_KEY_FILE>#<PASSOWRD3> is the location of your admin and its passphrase you generated earlier (if you are not bringing your own identity).

Note that the keyshare-minimum, which is set to 2 by default but can be increased, represents the minimum number of keyshares (by their locations) you must specify.

To upload your master key to the crypto units of your instance, issue:

ibmcloud kp crypto-unit mk import --keyshare-files '["<KEYSHARE_FILE_1>#<PASSWORD1>", "<KEYSHARE_FILE_2>#<PASSWORD2"]' --auth '[{"ADMIN": "<ADMIN_KEY_FILE>#<PASSWORD3>"}]'

Where:

• <KEYSHARE_FILE_1>#<PASSWORD1> is the location of one of the keyshares, along with a passphrase for the file that will be created. Note that the passphrase is optional but if one is set, it must have at least six characters.
• <KEYSHARE_FILE_2>#<PASSWORD2 is the location of another keyshare, along with a passphrase for the file that will be created. Note that the passphrase is optional but if one is set, it must have at least six characters.
• <ADMIN_KEY_FILE>#<PASSWORD3> is the location of your admin and its passphrase you generated earlier (if you are not bringing your own identity).

Now that your master key has been created, you need to allow the Key Protect service the ability to perform actions on your crypto units (for example, to create keys). Note that the level of permissions granted Key Protect is lower than that of an admin.

ibmcloud kp crypto-unit user add --type kmsCryptoUser --auth '[{"ADMIN": "<ADMIN_KEY_FILE>#<PASSWORD>"}]' 

Where:

• <ADMIN_KEY_FILE>#<PASSWORD> is the location of your admin key file and its passphrase as generated earlier (if you are not bringing your own identity).

This command can also be used to add admins to your crypto units by making your --type admin and adding a --name and --file that point to an admin identity you possess. Do not add --name or --file when adding kmsCryptoUser. For example:

ibmcloud kp crypto-unit user add --type admin --name <USERNAME> --credential "<USERNAME_KEY_FILE>" --auth '[{"ADMIN": "<ADMIN_KEY_FILE>#<PWD>"}]'

Where:

• <USERNAME> is the name of the admin identity you are adding.
• <USERNAME_KEY_FILE> is the file path of the credential to associate with the new user.
• <ADMIN_KEY_FILE>#<PWD> is the location of your existing admin and its passphrase you generated earlier (if you are not bringing your own identity).

Do not add --name or --file when adding kmsCryptoUser as an admin.

Congratulations. Your instance has been fully initialized.

It may take unto 5 to 10 minutes before you can use your instance.

Next steps

Now that your instance has been created, you have admin identities that can be used to operate it, and have created your master key and given Key Protect access to perform actions on your instance, you are ready to do things like:

• Create a root key. You can have a maximum of 500 root or standard keys that are in any state, including Destroyed.
• Create key rings. You can have a maximum of 50 key rings per service instance.
• Set a rotation policy.

Import tokens are not supported by Key Protect Dedicated.

Unsupported features

• Creating import tokens.
• Secure import key with import tokens.
• allowed_network policy.
• Deploying your instance anywhere but us-south.
• PKCS#11 keystores.
• Failover crypto units.

Troubleshooting

Installing binary...
FAILED
Unable to obtain plug-in's metadata. Error: exit status 1

FAILED
command failed with error code: e00bad05

Executing operation Generate Master Key against CryptoUnit with ID fadedbee-0000-0000-0000-1234567890ab
OK
Executing operation Generate Master Key against CryptoUnit with ID addedace-0000-0000-0000-1234567890ab
FAILED