vania-janet/multiturn-rag-retrieval-data huggingface dataset:
Rotating master keys by using smart cards and the Management Utilities 

You need to rotate the master key for your IBM Cloud® Hyper Protect Crypto Services instance regularly to meet industry standards and cryptographic best practices. This topic guides you through the steps to rotate the master key by using smart cards and the Management Utilities.

When the master key is being rotated, you can still perform some KMS key actions such as listing keys, retrieving key metadata, or deleting keys, but you cannot create or rotate keys. You cannot call either the PKCS #11 API or GREP11 API during the master key rotation.

Rotating the master key reencrypts the keys in key storage by using the new master key value. After the keys in key storage are reencrypted, the value in the new master key register is promoted to the current master key register. Before you start rotating the master key, you need to:



* Understand how a master key is rotated [for the standard plan](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-master-key-rotation-intro) or [for the Unified Key Orchestrator plan](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-master-key-rotation-intro).
* Assign the Manager service access role or the crypto unit administrator role to perform TKE CLI operations. For more information about the access management, see Managing user access [for the standard plan](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-access) or [for the Unified Key Orchestrator plan](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-manage-access).
* Configure all crypto units in the service instance the same.



Key objects in the in-memory keystore are not automatically rotated after the master key rotation. If PKCS #11 keystores are enabled in your service instance, you need to restart all active PKCS #11 applications to clear the in-memory keystore after the master key rotation is complete.
"alt_name1", "alt_name2"
],
"algorithm": "sha256WithRSAEncryption",
"key_algorithm": "rsaEncryption 2048 bit",
"rotation": {
"enabled": false,
"rotate_keys":false
},
"custom_metadata" : {
"anyKey" : "anyValue"
},
"version_custom_metadata" : {
"anyKey" : "anyValue"
},
"expiration_date" : "2030-01-01T00:00:00Z",
}
]

The command outputs the ID value of the secret, along with other metadata. For more information about the command options, see [ibmcloud secrets-manager secret-create](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-cli-plugin-secrets-manager-clisecrets-manager-cli-secret-create-command).
: A collection of resources. Required.





 Examples 

ibmcloud secrets-manager secret-create --secret-type=arbitrary --metadata='{"collection_type": "application/vnd.ibm.secrets-manager.secret+json", "collection_total": 1}' --resources='[{"name": "example-arbitrary-secret", "description": "Extended description for this secret.", "secret_group_id": "bc656587-8fda-4d05-9ad8-b1de1ec7e712", "labels": "dev","us-south"], "custom_metadata": {"anyKey": "anyValue"}, "version_custom_metadata": {"anyKey": "anyValue"}, "expiration_date": "2030-01-01T00:00:00Z", "payload": "secret-data"}]'







 ibmcloud secrets-manager secrets 

List the secrets in your Secrets Manager instance based on the type that you specify.

ibmcloud secrets-manager secrets --secret-type SECRET-TYPE [--limit LIMIT] [--offset OFFSET]



 Command options 

--secret-type (string)
: The secret type. Required.

Allowable values are: arbitrary, iam_credentials, imported_cert, public_cert, private_cert, username_password, kv.

--limit (int64)
: The number of secrets to retrieve. By default, list operations return the first 200 items. To retrieve a different set of items, use limit with offset to page through your available resources.

Usage: If you have 20 secrets in your instance, and you want to retrieve only the first 5 secrets, use ../secrets/{secret_type}?limit=5.

The maximum value is 5000. The minimum value is 1.

--offset (int64)
: The number of secrets to skip. By specifying offset, you retrieve a subset of items that starts with the offset value. Use offset with limit to page through your available resources.
* UI
* API







 Manually rotating keys 

You can rotate your root keys manually by using IBM® Key Protect for IBM Cloud®.

When you rotate your root key, you add new key material to the key. This process creates a new key version that you can use for [rewrapping or reencrypting your data](https://cloud.ibm.com/docs/key-protect?topic=key-protect-rewrap-keys).

To learn how key rotation helps you meet industry standards and cryptographic best practices, see [Rotating your encryption keys](https://cloud.ibm.com/docs/key-protect?topic=key-protect-key-rotation).

Rotation is available only for root keys. To learn more about your key rotation options in Key Protect, check out [Comparing your key rotation options](https://cloud.ibm.com/docs/key-protect?topic=key-protect-key-rotationcompare-key-rotation-options).



 Rotating root keys in the console 

[After you create a root key](https://cloud.ibm.com/docs/key-protect?topic=key-protect-create-root-keys), complete the following steps to rotate the key:



1. [Log in to the IBM Cloud console](https://cloud.ibm.com/login/).
2. Go to Menu > Resource List to view a list of your resources.
3. From your IBM Cloud resource list, select your provisioned instance of Key Protect.
4. On the application details page, use the Keys table to browse the keys in your service. If you have many keys, you can narrow your search by using the search bars to only search for enabled keys (since other kinds of keys cannot be rotated), keys in a particular key ring, and keys with a particular alias.
5. Once the key has been found, click the ⋯ icon to open a list of options for the key that you want to rotate.
6. From the options menu, click Rotate to open the Rotation side panel.
7.
* UI
* CLI
* API







 Key rotation for VPC resources 

For IBM Cloud VPC resources such as volumes, file shares, and custom images that are protected by your customer root key (CRK), you can rotate the root keys for more security. When you rotate a root key by schedule or on demand, the original key material is replaced. The old key remains active to decrypt existing resources but can't be used to encrypt new ones.



 Key rotation overview 

Customer-managed encrypted resources such as volumes, file shares, and custom images use your root key (CRK) as the root-of-trust key. The root key's function is to encrypt a LUKS passphrase that encrypts a data encryption key (DEK) protecting the resource. You can import your CRK to a key management service (KMS) instance or have the KMS generate one for you. Supported key management services are Key Protect and Hyper Protect Crypto Services. Root keys are rotated in your KMS instance.

When you rotate a root key, a new version of the key is created by generating or importing new cryptographic key material. The old root key is retired, which means its key material remains available for decrypting existing resources but not for encrypting new ones.

You can have several root keys in each KMS instance available for key rotation. These root keys can be a combination of keys that you imported to the cloud or ones that were automatically generated in the KMS instance.

You can set up a [rotation policy](https://cloud.ibm.com/docs/vpc?topic=vpc-vpc-key-rotationvpc-key-rotation-policies) to schedule automatic key rotation. The KMS generates a new root key at the rotation interval and automatically replaces the root key with new key material.

For any root keys that you import to the KMS instance because you're providing new key material that is not in the KMS, you can't set up automatic key rotation.
Why can't I rotate master keys by using smart cards? 

When you run smart cards and the Management Utilities to rotate master keys, you might be not able to complete the rotation.

 What’s happening 

During master key rotation, the new master key registers are loaded with the new master key value to be used. The contents of key storage are reencrypted by using the current and new master key values. When the reencryption of key storage is complete, the new master key value is promoted to the current master key registers, and the new master key registers are cleared.

For detailed instructions on how to rotate the master key, see [Rotating master keys by using key part files](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-master-key-cli-key-part).

If an error occurs during master key rotation, the action you take to recover depends on how much of the process is completed. An incorrect recovery action can cause the master key value for key storage to be lost and contents of key storage to become unusable. You need to carefully check the command output before the error occurred to determine what recovery action to take.

Some errors are detected before the command starts to work with key storage or the master key registers. For example, if your authentication token is expired, an error is reported. To recover, you need to log in to the IBM Cloud. Similarly, if the initial conditions needed to run the command are not met, an error is reported. Correct the initial conditions and run the command again.

The following initial conditions can be reported as an error when you click the Rotate button on the Master keys tab of the Trusted Key Entry application:



* Not all crypto units in a single service instance are selected. Or, crypto units in more than one service instance are selected.
* One or more crypto units are in imprint mode.
* Signature thresholds on the crypto units are not set the same.
* A common set of administrators is not selected and installed in all crypto units large enough to meet the signature threshold value.
* The current master key registers are not all in the Valid state with the same verification pattern.
The Secrets Manager tool integration supports the following configuration parameters that you can use with the [Toolchain HTTP API and SDKs](https://cloud.ibm.com/apidocs/toolchain) when you [create](https://cloud.ibm.com/apidocs/toolchaincreate-tool), [read](https://cloud.ibm.com/apidocs/toolchainget-tool-by-id), and [update](https://cloud.ibm.com/apidocs/toolchainupdate-tool) tool integrations.

You must specify the tool_type_id property in the request body with the secretsmanager value.



Table 1. Secrets Manager tool integration parameters

 Parameter Usage Type Terraform argument Description 

 name required, updatable String name The name of this tool integration. Name-based secret references include this name to identify the secrets store where the secrets reside. All of the secrets store tools that are integrated into a toolchain must have a unique name to allow secret resolution to function properly. 
 instance-id-type required, updatable Enum instance_id_type The type of service instance identifier. Accepted values are instance-name and instance-crn. By default, this value is set to instance-name. 
 instance-crn required, updatable String instance_crn The CRN of the Secrets Manager service instance. This parameter is used only when you use instance-crn as the instance_id_type. 
 region required, updatable String location The IBM Cloud location where the Secrets Manager service instance is located. This parameter is used only when you use instance-name as the instance_id_type. 
 resource-group required, updatable String resource_group_name The name of the resource group where the Secrets Manager service instance is located. This parameter is used only when you use instance-name as the instance_id_type. 
 instance-name required, updatable String instance_name The name of the Secrets Manager service instance. This parameter is used only when you use instance-name as the instance_id_type. 







 Learn more about Secrets Manager
After you configure the Secrets Manager tool integration and [authorize your toolchain](https://cloud.ibm.com/docs/services/ContinuousDelivery?topic=ContinuousDelivery-secretsmanagerauthorizing-your-toolchain-to-access-secrets) to access secrets in that account, you can use it to apply secrets anywhere that they are required by the toolchain.

You can use either of the following methods to select a CRN secret for use in your toolchain:



* Copy the CRN of the secret from the Secrets Manager service instance and paste it into the edit box of secret field. The secret must reside in the Secrets Manager service instance that was configured when you added the Secrets Manager tool integration to your toolchain.
* Use the Secrets dialog. For information about how to use this method, see [Identifying secrets by name](https://cloud.ibm.com/docs/services/ContinuousDelivery?topic=ContinuousDelivery-secretsmanageridentify_secrets_by_name).

When you choose a CRN secret, make sure that you select the CRN-configured tool card from the Provider option.



When fields that contain a CRN secret are displayed, the Secrets Manager tool integration attempts to retrieve the name of the secret. To open the Secrets Manager service instance where the secret resides, click the secret. In the following scenarios, the secret name cannot be retrieved and a warning icon is displayed:



* The toolchain does not contain a correctly configured Secrets Manager integration.
* The toolchain authorization is incorrect.
* The field does not contain a valid CRN.









 Authorizing your toolchain to access secrets 

References to secrets that are stored in Secrets Manager are dynamically resolved when the toolchain runs. To access the required secrets, you must authorize your toolchain to access the Secrets Manager instance. If you create a toolchain that has a valid Secrets Manager tool integration that is configured to identify secrets by name, or add this tool integration to an existing toolchain, a request is automatically issued to create the required authorization.

An authorization is not created automatically for tool integrations that are configured to identify secrets by CRN.
For more information, see [kp import-token nonce-encrypt](#kp-import-token-nonce-encrypt).







 kp key rotate 

[Rotate a root key](https://cloud.ibm.com/docs/key-protect?topic=key-protect-rotate-keys) that is stored in your Key Protect service.

When you rotate your root key, you replace the key with a new key material.

If Key Protect created the key (the key was not created with the -k parameter) then Key Protect creates a new key. You cannot specify kp key rotate with the -k parameter.

If you created a key and provided the key material ( kp key create key-name -k $KEY_MATERIAL) then you must provide a new key material when you rotate the key (kp key rotate $KEY_ID -k $NEW_KEY_MATERIAL)

You cannot rotate a standard key, that is, a key created using the kp create key-name --standard-key command.

ibmcloud kp key rotate KEY_ID
-i, --instance-id INSTANCE_ID
[-k, --key-material KEY_MATERIAL]



 Examples 

These are examples of kp key rotate.



 Example 1 

Rotate a root key.

 create a root key
$ ibmcloud kp key create my-root-key

Creating key: 'my-root-key', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK
Key ID Key Name
1a6d5be8-287c-4eb3-9c44-cf0c2b0d67ad my-root-key

 rotate the key
$ ibmcloud kp key rotate 1a6d5be8-287c-4eb3-9c44-cf0c2b0d67ad

Rotating root key...
OK

 show key details
$ ibmcloud kp key rotate e55f86ab-6984-4594-ad23-3024f6440a58

Rotating root key...
FAILED





 Example 3 

This examples shows how to...



1. Create a root key
2. Create a data encryption key (DEK), this is the plaintext
3. Wrap the DEK with the root key, this creates a ciphertext
4. Rotate the root key
5. Unwrap the ciphertext to reveal the original DEK (plaintext) and a new ciphertext (the new ciphertext is the plaintext wrapped with the new rotated root key)
6. Unwrap the new ciphertext to reveal the original DEK (plaintext)



 create a root key
$ KEY_ID=$(ibmcloud kp key create my-root-key --output json | jq -r '.["id"]')

$ echo $KEY_ID

5b976173-7804-4f82-acfa-bb98098bc528

 create a random, base64-encoded, 32-byte data encryption key (DEK)
$ PLAINTEXT=$(openssl rand -base64 32)

$ echo $PLAINTEXT

UPJ4YDwbQMjQG/aqlHsPhHV1CBkpIXngLHFS5+i4UZ4=

 wrap the plaintext key with the root key, creating a DEK (this is the ciphertext)
$ CIPHERTEXT=$(ibmcloud kp key wrap $KEY_ID -p $PLAINTEXT --output json | jq -r '.["Ciphertext"]')

$ echo $CIPHERTEXT

eyJjaXBoZXJ0ZXh0IjoiQkFrTlJrS2Q0 ...<redacted>... ODA5OGJjNTI4In0=

 rotate the root key
$ ibmcloud kp key rotate $KEY_ID

Rotating root key...
OK
Why can't I rotate master keys by using key part files? 

When you run the ibmcloud tke cryptounit-mk-rotate command to rotate master keys by using key part files, you might be not able to complete the rotation.

 What’s happening 

During master key rotation, the new master key registers are loaded with the new master key value to be used. The contents of key storage are reencrypted by using the current and new master key values. When the reencryption of key storage is complete, the new master key value is promoted to the current master key registers, and the new master key registers are cleared.

For detailed instructions on how to rotate the master key, see [Rotating master keys by using key part files](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-master-key-cli-key-part).

If an error occurs during master key rotation, the action you take to recover depends on how much of the process is completed. An incorrect recovery action can cause the master key value for key storage to be lost and contents of key storage to become unusable. You need to carefully check the command output before the error occurred to determine what recovery action to take.

Some errors are detected before the command starts to work with key storage or the master key registers. For example, if your authentication token is expired, an error is reported. To recover, you need to log in to the IBM Cloud. Similarly, if the initial conditions needed to run the command are not met, an error is reported. Correct the initial conditions and run the command again.

The following initial conditions can be reported as an error by the ibmcloud tke cryptounit-mk-rotate command:



* When you rotate your master key by using key part files, an invalid set of crypto units is selected.
* One or more crypto units are in imprint mode.
* Signature thresholds on the crypto units are not set the same.
* A common set of administrators is not selected and installed in all crypto units large enough to meet the signature threshold value.
* The current master key registers are not all in the Valid state with the same verification pattern.
Configuring Secrets Manager 

IBM Cloud® Secrets Manager helps you to securely store and apply secrets for apps across IBM Cloud services.

A secret is anything that provides access to sensitive information, such as an [API key](https://cloud.ibm.com/docs/account?topic=account-manapikey). You can use the Secrets Manager tool integration to access secrets, wherever they are required in the toolchain workflow.

Before you configure a Secrets Manager tool integration, make sure that you [provision an instance of the Secrets Manager service](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-create-instancecreate-instance-ui).

You can configure the Secrets Manager tool integration to identify secrets by name or by [Cloud Resource Name (CRN)](https://cloud.ibm.com/docs/account?topic=account-crn).



 Identifying secrets by name 

When you configure the Secrets Manager tool integration to identify secrets by name, your toolchain can access the following secret types:



* Identity and Access Management (IAM) credentials secrets.
* Arbitrary secrets that are stored in the Secrets Manager.



For more information about IAM credentials secrets, and Arbitrary secrets in Secrets Manager, see [Working with secrets of different types](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-what-is-secretsecret-types).

Configure Secrets Manager to securely manage secrets that are part of your toolchain:



1. If you are configuring this tool integration as you are creating the toolchain, in the Configurable Integrations section, click Secrets Manager. If Secrets Manager is defined as an optional tool integration, it is located under More Tools.
2. If you have a toolchain and are adding this tool integration to it, from the IBM Cloud console, click the menu icon !
To rotate the root key that is used to encrypt your cluster, you can repeat the steps to enable KMS encryption from the [CLI](https://cloud.ibm.com/docs/openshift?topic=openshift-encryptionkms_cli) or [console](https://cloud.ibm.com/docs/openshift?topic=openshift-encryptionkms_ui). When you rotate a root key, you can't reuse a previous root key for the same cluster.

You can [rotate the root key](https://cloud.ibm.com/docs/key-protect?topic=key-protect-rotate-keys) from your KMS instance. This action automatically re-enables KMS in your cluster with the new root key. To manually rotate your keys, see your KMS provider docs.



* IBM® Key Protect for IBM Cloud®: See [Rotating your keys](https://cloud.ibm.com/docs/key-protect?topic=key-protect-getting-started-tutorialget-started-next-steps-best-practices-key-rotate).
* Hyper Protect Crypto Services: See [Rotating root keys manually](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-keys).









 Verifying secret encryption 

After you enable a KMS provider in your Red Hat OpenShift on IBM Cloud cluster, you can verify that your cluster secrets are encrypted by disabling the root key. When you disable the root key, the cluster can no longer decrypt the secrets and becomes unusable, which signifies that your secrets were encrypted.

Before you begin



* Make sure that you have the IBM Cloud IAM Administrator platform and Manager service access role for the cluster.



To verify secret encryption by disabling a root key



1. [Enable KMS encryption in your cluster](https://cloud.ibm.com/docs/openshift?topic=openshift-encryptionkeyprotect).
: If you work with a DNS provider that is not currently integrated with the service, you can manually configure it when you use the Secrets Manager UI to order new certificates. If you choose to manually configure a provider, you must complete a challenge to prove ownership over your domain. For more information, see [Ordering public certificates with your own DNS provider in the UI](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-public-certificatesorder-public-cert-manual-ui).

Create a leaf certificate with a certificate signing request
: You can create private leaf certificates through your public key infrastructure (PKI) by using a certificate signing request (CSR). [Learn more](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2create-configuration-action).





 18 October 2022 

Version custom metadata
: The ability to provide metadata for a specific version of a secret is now available in the UI, in addition to providing metadata for all versions. To learn more about the latest updates, see [Creating secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-arbitrary-secrets&interface=ui) and [Managing secret versions](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-version-history&interface=ui).

Automatic rotation for IAM credentials
: The ability to schedule an automatic rotation policy is now available for IAM credentials that are configured for reuse in the UI. For more information, see [Automatically rotating secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-automatic-rotation).





 19 September 2022 

CLI plug-in version 0.1.23
: Version 0.1.23 of the Secrets Manager CLI is now available for download. To learn about the latest updates, see the [CLI change log](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-cli-change-log).

Automatic rotation for IAM credentials