Creating key templates

Creating key templates from scratch with the UI

You can create a key template from scratch with full control by yourself. To create a key template by using the UI, complete the following steps:

1. Log in to the Hyper Protect Crypto Services instance.

2. Click Key templates from the navigation to view all the available key templates.

3. To create a key template, click Create key template.

4. To control access to keys that are to be created with the key template, under Vault, select a vault and then click Next. All keys to be created with the key template will be managed in the selected vault.

   If you want to manage key access in a new vault, click Create vault. For more instructions, see Creating vaults.

5. Under Keystores, perform the following steps:

   • Under Keystore type, select one of the following keystore types, which determines the available key template properties and the type of key that you are going to create with the key template:

     • AWS Key Management Service: Create a key template for keys to be used and stored in an AWS Key Management Service instance.
     • Azure Key Vault: Create a key template for keys to be used and stored in an Azure Key Vault.
     • Google Cloud KMS: Create a key template for keys to be used and stored in a Google Cloud KMS keystore.
     • IBM Cloud KMS: Create a key template for keys to be used and stored in an IBM Cloud Hyper Protect Crypto Services keystore.
     • IBM Key Protect: Create a key template for keys to be used and stored in an IBM Key Protect key ring.

     For more information about the keystores, see Components.

   • (Optional) Decide where your keys to be created with the key template are going to be activated or stored under Keystores. Activating a key in multiple keystores enables redundancy.

     If there are no existing keystores, click Add keystore to create internal KMS keystores or connect to external keystores.

     After a keystore type is selected, you can create keys in keystores of this type only.

6. Click Next to continue.

7. Under Key template properties, specify the following details of the key template. Click Next to continue when you are done.

   Table 1. AWS Key templates properties

   Property	Description
   Key template name	A unique, human-readable name for easy identification of your key template. It must be 1–100 characters in length.
   Description	(Optional) An extended description for your key template, with up to 200 characters in length.
   Naming scheme	(Optional) Enter strings or placeholders to enforce the key naming scheme. After defining the key naming scheme, you can then create a group of keys with the same key naming conventions but you cannot edit the key naming scheme any more. For more information, see Defining key naming schemes.
   Managed key name example	Read only. An example of the managed key name based on the key naming scheme is populated automatically for your reference.
   Algorithm	The encryption algorithm to encrypt data for the key to be created with the template.
   Length	The number of bits that represents the encryption strength of the key to be created with the template.
   State	The initial key state to be created with the key template, including Pre-active and Active. Pre-active keys are not activated in keystores for encryption. Active keys are automatically activated in the keystores. For more information about key states, see Monitoring the lifecycle of encryption keys in Unified Key Orchestrator.
   Activate keys after	(Optional) Plan a date to activate the Pre-active keys to be created since the key creation. It is for planning purpose only.
   Deactivate keys after	(Optional) Plan a date to deactivate the keys to be created since the key creation. It is for planning purpose only.

   Table 2. Azure Key templates properties

   Property	Description
   Key template name	A unique, human-readable name for easy identification of your key template. It must be 1–100 characters in length.
   Description	(Optional) An extended description for your key template, with up to 200 characters in length.
   Naming scheme	(Optional) Enter strings or placeholders to enforce the key naming scheme. After defining the key naming scheme, you can then create a group of keys with the same key naming conventions but you cannot edit the key naming scheme any more. For more information, see Defining key naming schemes.
   Managed key name example	Read only. An example of the managed key name based on the key naming scheme is populated automatically for your reference.
   Protection level	Data protection level of keys to be created with the key template. HSM-protected key is stored and generated in a FIPS-certified Hardware Security Module. It is available in Azure Key Vault (Premium) only. This type of keys ensures the highest security. Software-protected key is available in both Azure Key Valut (Standard) and Key Vault (Premium). You can choose this level to reduce cost. Note: If you connect to an external keystore of type Azure Key Vault, you can distribute both HSM-protected keys and software-protected keys to Azure Key Vault (Premium). However, you can distribute only software-protected keys to Azure Key Vault (Standard).
   Algorithm	The encryption algorithm to encrypt data for the key to be created with the template.
   Length	The number of bits that represents the encryption strength of the key to be created with the template.
   State	The initial key state to be created with the key template, including Pre-active and Active. Pre-active keys are not activated in keystores for encryption. Active keys are automatically activated in the keystores. For more information about key states, see Monitoring the lifecycle of encryption keys in Unified Key Orchestrator.
   Activate keys after	(Optional) Plan a date to activate the Pre-active keys to be created since the key creation. It is for planning purpose only.
   Deactivate keys after	(Optional) Plan a date to deactivate the keys to be created since the key creation. It is for planning purpose only.

   Table 3. Google Key templates properties

   Property	Description
   Key template name	A unique, human-readable name for easy identification of your key template. It must be 1–100 characters in length.
   Description	(Optional) An extended description for your key template, with up to 200 characters in length.
   Naming scheme	(Optional) Enter strings or placeholders to enforce the key naming scheme. After defining the key naming scheme, you can then create a group of keys with the same key naming conventions but you cannot edit the key naming scheme any more. For more information, see Defining key naming schemes.
   Managed key name example	Read only. An example of the managed key name based on the key naming scheme is populated automatically for your reference.
   Protection level	Data protection level of keys to be created with the key template. HSM-protected key protection level applies to keys that are protected by FIPS 140-2 Level 3 Hardware Security Modules (HSMs) in Google Cloud. This type of keys ensures the higher security. Software-protected key protection level applies to keys that are protected by software. You can choose this level to reduce cost. For more information, see Cloud KMS software backend: SOFTWARE protection level and Cloud KMS HSM backend: HARDWARE protection level. Note: Software-protected keys don't support the Elliptic curve secp256k1 algorithm.
   Purpose	The cryptographic capabilities of the key, which is what you are going to do with this key. The purpose also determines the available key algorithms. The supported key purposes are Symmetric encrypt/decrypt, Asymmetric sign, Asymmetric decrypt, and MAC signing/verification. For more information, see Key purpose.
   State	The initial key state to be created with the key template, including Pre-active and Active. Pre-active keys are not activated in keystores for encryption. Active keys are automatically activated in the keystores. For more information about key states, see Monitoring the lifecycle of encryption keys in Unified Key Orchestrator.
   Activate keys after	(Optional) Plan a date to activate the Pre-active keys to be created since the key creation. It is for planning purpose only.
   Deactivate keys after	(Optional) Plan a date to deactivate the keys to be created since the key creation. It is for planning purpose only.

   Table 4. IBM Cloud KMS Key templates properties

   Property	Description
   Key template name	A unique, human-readable name for easy identification of your key template. It must be 1–100 characters in length.
   Description	(Optional) An extended description for your key template, with up to 200 characters in length.
   Naming scheme	(Optional) Enter strings or placeholders to enforce the key naming scheme. After defining the key naming scheme, you can then create a group of keys with the same key naming conventions but you cannot edit the key naming scheme any more. For more information, see Defining key naming schemes.
   Managed key name example	Read only. An example of the managed key name based on the key naming scheme is populated automatically for your reference.
   Algorithm	The encryption algorithm to encrypt data for the key to be created with the template.
   Length	The number of bits that represents the encryption strength of the key to be created with the template.
   State	The initial key state to be created with the key template, including Pre-active and Active. Pre-active keys are not activated in keystores for encryption. Active keys are automatically activated in the keystores. For more information about key states, see Monitoring the lifecycle of encryption keys in Unified Key Orchestrator.
   Activate keys after	(Optional) Plan a date to activate the Pre-active keys to be created since the key creation. It is for planning purpose only.
   Deactivate keys after	(Optional) Plan a date to deactivate the keys to be created since the key creation. It is for planning purpose only.

   Table 5. IBM Key Protect Key templates properties

   Property	Description
   Key template name	A unique, human-readable name for easy identification of your key template. It must be 1–100 characters in length.
   Description	(Optional) An extended description for your key template, with up to 200 characters in length.
   Naming scheme	(Optional) Enter strings or placeholders to enforce the key naming scheme. After defining the key naming scheme, you can then create a group of keys with the same key naming conventions but you cannot edit the key naming scheme any more. For more information, see Defining key naming schemes.
   Managed key name example	Read only. An example of the managed key name based on the key naming scheme is populated automatically for your reference.
   Algorithm	The encryption algorithm to encrypt data for the key to be created with the template.
   Length	The number of bits that represents the encryption strength of the key to be created with the template.
   State	The initial key state to be created with the key template, including Pre-active and Active. Pre-active keys are not activated in keystores for encryption. Active keys are automatically activated in the keystores. For more information about key states, see Monitoring the lifecycle of encryption keys in Unified Key Orchestrator.
   Activate keys after	(Optional) Plan a date to activate the Pre-active keys to be created since the key creation. It is for planning purpose only.
   Deactivate keys after	(Optional) Plan a date to deactivate the keys to be created since the key creation. It is for planning purpose only.

8. Under Summary, view the summary of your key template, and then click Create key template to confirm.

You have successfully created a key template.

Creating key templates from scratch through the API

To create a key template from scratch through the API, follow these steps:

1. Retrieve your service and authentication credentials to work with key templates in the service.

2. Create a key template by making a POST call to the following endpoint.

   https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/templates
   

   For detailed instructions and code examples about using the API method, check out the Hyper Protect Crypto Services Unified Key Orchestrator API reference doc.

Creating a copy of an existing key template with the UI

If you want to customize a key template based on an existing template, create a copy of the key template, and then edit the template properties. You can copy from either an active or archived key template. To do so through the UI, complete the following steps:

1. Log in to the Hyper Protect Crypto Services instance.

2. Click Key templates from the navigation to view all the available key templates.

   You can view archived key templates by clicking the Show archived templates icon on the table.

3. Locate the key template that you want to copy from the list, click the Actions icon , and select Copy.

   Alternatively, click the Actions icon , and select Show details. And then, on the template details page, select Actions > Copy.

4. All properties are preconfigured based on the copied key template. You can still make the following changes if needed:

   • Vault
   • Keystore type
   • Keystores
   • Key template properties

   Refer to Creating key templates from scratch with the UI for detailed explanations.

5. Under Summary, view the summary of your key template, and then click Create key template to confirm.

You have successfully created a copy of an existing key template.

Creating key templates from an existing key template through the API

To make a copy from an existing key template through the API, follow these steps:

1. Retrieve your service and authentication credentials to work with key templates in the service.

2. Create a key template by making a POST call to the following endpoint.

   https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/templates
   

   For detailed instructions and code examples about using the API method, check out the Hyper Protect Crypto Services Unified Key Orchestrator API reference doc.

Defining key naming schemes

By defining the key naming scheme for the key template, you can create a group of keys with the same key naming conventions. You can specify different naming scheme placeholders. The naming schemes consist of fixed strings, custom placeholders, and system placeholders, which will be populated during the creation of each key.

When you define a key naming scheme, an example of a managed key name based on the key naming scheme is populated automatically for your reference under Managed key naming example. For example, if you enter akms-<PROJECT>-<LOCATION>-<ENV>-appdata for your key naming scheme, an example of a managed key name is displayed akms-XYZ-XYZ-XYZ-appdata. In this example, akms and appdata are the fixed strings, and XYZ is the value for PROJECT, LOCATION, and ENV that you need to provide each time during the key creation with this key template.

Note that you need to keep in mind of the following considerations:

• Depending on the keystore type, key naming requirements can be different:

  • AWS Key Management Service: It must be 1–250 characters in length. The characters can be letters (case-sensitive), digits (0–9), or symbols (/_-). However, do not start the name with AWS/.
  • Azure Key Vault: It must be 1–127 characters in length. The characters can be letters (case-sensitive), digits (0–9), or hyphens (-).
  • Google Cloud KMS: It must be 1–63 characters in length. The characters can be letters (case-sensitive), digits (0–9), or symbols (_-).
  • IBM Cloud KMS: It must 2–50 characters in length. The characters can be letters (case-sensitive), digits (0–9), or spaces.
  • IBM Key Protect: It must 2–50 characters in length. The characters can be letters (case-sensitive), digits (0–9), or spaces.

• Enter fixed strings or placeholders for the key naming scheme. Each placeholder must be within 1-20 characters in length. Note that you need to use the angle brackets (<>) to insert placeholders.

• Enter an opening angle bracket (<) or click the system placeholder tag to insert a system placeholder. Each system placeholder consists of letters (case-sensitive), digits (0-9), or a forward slash (/). The following table lists the system placeholders:

  If the key names contain system placeholders, keys to be created cannot be rotated.

  Table 6. System placeholders for naming scheme

  System placeholder	Alternative spelling	Description
  lastActiveYear	lay lastActiveYear/yyyy lay/yyyy lastActiveYear/4 lay/4	A 4-digit format of the year when the key is expired.
  lastActiveYear/yy	lay/2 lastActiveYear/2 lay/yy	A 2-digit format of the year when the key is expired.
  lastActiveMonth	lam	A 2-digit format of the month when the key is expired.
  yy		A 2-digit format of the year when the key is created.
  yyyy		A 4-digit format of the year when the key is created.
  mm		A 2-digit format of the month when the key is created.

• Do not use the following reserved placeholders for your key naming scheme.

  Table 7. Reserved placeholders for naming scheme

  Reserved placeholder	Alternative spelling
  SEQUENCENUMBER	seqno sqn sequenceNumber SEQNO SQN
  hierarchy	h hier
  keyType	kt
  institutionId	iid

• You can enter an opening angle bracket (<) to insert a custom placeholder. Each custom placeholder consists of letters (case-sensitive) or digits (0-9). To apply the naming scheme to multiple keys, make sure to use at least one custom placeholder.

• If you define a custom placeholder, you need to provide a value for the placeholder during the key creation.

• You cannot edit the key name after the managed key is created with key naming schemes.