vania-janet/multiturn-rag-retrieval-data huggingface dataset:
"rotate_keys": true
},
"bundle_certs": true,
"custom_metadata": {
"metadata_custom_key": "metadata_custom_value"
},
"version_custom_metadata": {
"custom_version_key": "custom_version_value"
}
}' 
"https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets"

When you submit your certificate details, Secrets Manager sends your request to the selected certificate authority. After a certificate is issued, you can deploy it to your integrated apps, download it, or rotate it manually. Your private key for SSL/TLS is generated directly in Secrets Manager and stored securely. For more information about the required and optional request parameters, see [Create a secret](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2create-secret).

Need to check your order status? Use the [Get secret metadata](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2get-secret-metadata) API to check the resources.issuance_info field for issuance details on your certificate.





 Ordering public certificates with integrated DNS providers by using Terraform 

The following example shows a configuration that you can use to order a public certificate.

resource "ibm_sm_public_certificate" "sm_public_certificate" {
instance_id = local.instance_id
region = local.region
name = "test-public-certificate"
secret_group_id = "default"
ca = ibm_sm_public_certificate_configuration_ca_lets_encrypt.my_lets_encrypt_config.name
dns = ibm_sm_public_certificate_configuration_dns_cis.my_cis_dns_config.name
rotation {
auto_rotate = true
rotate_keys = false
}
}







 Ordering public certificates with your own DNS provider in the UI
Schedule the automatic rotation for private certificates by using the Secrets Manager CLI plug-in.

ibmcloud secrets-manager secret-metadata-update --id=SECRET_ID --rotation='{"auto_rotate": true,"interval": 30,"unit": "day"}'





 Setting an automatic rotation policy for IAM credentials 

Schedule the automatic rotation for IAM credentials by using the Secrets Manager CLI plug-in.

ibmcloud secrets-manager secret-metadata-update --id=SECRET_ID --rotation='{"auto_rotate": true,"interval": 30,"unit": "day"}'

To remove a policy, keep the resources block empty.







 Scheduling automatic rotation with the API 

You can schedule the automatic rotation of secrets by using the Secrets Manager API.



 Setting an automatic rotation policy for user credentials 

The following example request creates an automatic rotation policy for a user credentials (username_password) secret. When you call the API, replace the ID variables and IAM token with the values that are specific to your Secrets Manager instance.

curl -X PATCH
-H "Authorization: Bearer {iam_token}" -H "Accept: application/json" -H 'Content-Type: application/merge-patch+json' -d '{
"rotation": {
"auto_rotate": true,
"interval": 1,
"unit": "month"
}
}' 
"https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/metadata"

A successful response returns the ID value for the secret, along with other metadata. For more information about the required and optional request parameters, see the [API reference](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2update-secret).

To remove a policy, keep the resources block empty.





 Setting an automatic rotation policy for public certificates 

If you prefer to schedule your certificates to be automatically renewed, you can enable automatic rotation for certificates when you order them, or by editing the details of an existing certificate.
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
: The ability to schedule an automatic rotation policy is now available for IAM credentials that are configured for reuse. For more information, see [Automatically rotating secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-automatic-rotation).

Manually configure your own DNS provider
: 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 API 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](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-certificatesorder-certificates-manual-api).





 12 September 2022 

CLI plug-in version 0.1.22
: Version 0.1.22 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).

New custom metadata fields
: The documentation for creating secrets and managing versions of a secret is now updated to include custom_metadata and version_custom_metadata fields.
To rotate a key-value secret by using Terraform for Secrets Manager, modify the value of the data attribute in your ibm_sm_kv_secret resource configuration, and run terraform apply to apply the change. If you're using an input variable for the payload, modify its value in the variables.tf file.

You can also modify other attributes of the key-value secret at the same time, including metadata attributes such as description, custom_metadata or version_custom_metadata.





 Rotating imported certificates 

You can rotate imported certificates by using Terraform for Secrets Manager.

To rotate an imported certificate, modify the values of the certificate, intermediate (optional) and private_key (optional) attributes in your ibm_sm_imported_certificate resource configuration, and run terraform apply to apply the change.

You can also modify other attributes of the imported certificate at the same time, including metadata attributes such as description, custom_metadata or version_custom_metadata.
{
"rotation": {
"interval": 10,
"unit": "day"
},
"type": "application/vnd.ibm.secrets-manager.secret.policy+json"
}
]
}'

Set a rotation policy on a username_password secret in an existing secret group.

curl -X PUT "https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/username_password/secrets/groups/{group_id}/{secret_id}/policies" -H 'X-Vault-Token: {Vault-Token}' -H 'Content-Type: application/json' -d '{
"policies": [
{
"rotation": {
"interval": 10,
"unit": "day"
},
"type": "application/vnd.ibm.secrets-manager.secret.policy+json"
}
]
}'





 Example response 

{
"request_id": "89698bdc-d787-4a74-eb2f-53e055ddc7f3",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"policies": [
{
"created_by": "iam-ServiceId-c0c7cfa4-b24e-4917-ad74-278f2fee5ba0",
"creation_date": "2021-06-21T14:30:17Z",
In the Secrets table, view a list of your existing Private certificates.
2. In the row for the certificate that you want to edit, click the Actions menu ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/actions-icon-vertical.svg)> Edit details.
3. Use the Automatic rotation option to add or remove a rotation policy for the secret.









 Setting an automatic rotation policy for IAM credentials 

If you prefer to schedule your API key to be automatically rotated at regular intervals, you can enable automatic rotation for your IAM credentials at their creation. You can also enable auto rotation by editing the details of an existing secret. Choose between a 30, 60, or 90-day rotation interval.

If you need more control over the rotation frequency of a secret, you can use the Secrets Manager API to set a custom interval by using day or month units of time. For more information, see the [API reference](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2put-policy).



1. If you're [adding a secret](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam-credentialsiam-credentials-ui), enable the rotation option by selecting a 30, 60, or 90-day rotation interval.
2. If you're editing an existing secret, enable automatic rotation by updating its details.



1. In the Secrets table, view a list of your existing secrets.
2. In the row for the secret that you want to edit, click the Actions menu ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/actions-icon-vertical.svg)> Edit details.
3.
[Menu icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/icon_hamburger.svg)> Resource List.
2. From the list of services, select your instance of Secrets Manager.
3. In the Secrets Manager UI, go to the Secrets list.
4. In the row for the secret that you want to rotate, click the Actions menu ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/actions-icon-vertical.svg)> Rotate.
5. Determine whether to enter your own password or generate a new one.

If you choose to generate a new password, Secrets Manager replaces the existing value with a randomly generated 32-character password that contains uppercase letters, lowercase letters, digits, and symbols.
6. Optional: Add metadata to your secret or to a specific version of your secret.



1. Upload a file or enter the metadata and the version metadata in JSON format.



7. To rotate the secret immediately, click Rotate.
8. Optional: Check the version history to view the latest updates.

In the row of the secret that you rotated, click the Actions menu ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/actions-icon-vertical.svg)> Version history to verify that a new version was created successfully.







 Creating new versions of imported certificates 

When it's time to renew a certificate that was initially imported to the service, you can use the Secrets Manager UI to manually reimport it. After a certificate is rotated, the previous version is retained in case you need it.
For more information about the required and optional request parameters, see the [API reference](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2update-secret).

To remove a policy, keep the resources block empty.





 Setting an automatic rotation policy for public certificates 

If you prefer to schedule your certificates to be automatically renewed, you can enable automatic rotation for certificates when you order them, or by editing the details of an existing certificate. In the certificate's next rotation cycle, Secrets Manager reorders the certificate 31 days before its expiry date.



 Ordering a public certificate that renews automatically 

The following example request orders a certificate with automatic rotation enabled. When you call the API, set the auto_rotate property to true. Optionally, you can set rotate_keys to true to request a new private key for the certificate on each rotation.

curl -X POST
-H "Authorization: Bearer {iam_token}" -H "Accept: application/json" -H "Content-Type: application/json" -d '{
"custom_metadata": {
"metadata_custom_key": "metadata_custom_value"
},
"rotation": {
"auto_rotate": true,
"rotate_keys": true
},
"version_custom_metadata": {
"custom_version_key": "custom_version_value"
}
}' 
"https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets"

A successful response returns the ID value for the certificate, along with other metadata. For more information about the required and optional request parameters, check out the [API reference](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2create-secret).







 Setting an automatic rotation policy for IAM credentials 

The following example request creates an automatic rotation policy for a IAM credentials (iam_credentials) secret.
To access the current version, you can [download the certificate](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-access-secrets) or retrieve it programmatically by using the [Get a secret](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2get-secret) API.









 Manually creating new versions of secrets from the CLI 

You can manually rotate your secrets and certificates by using the Secrets Manager CLI plug-in.



 Rotating arbitrary secrets 

To rotate an arbitrary secret by using the Secrets Manager CLI plug-in, run the [ibmcloud secrets-manager secret-version-create](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-cli-plugin-secrets-manager-clisecrets-manager-cli-secret-version-create-command) command. For example, the following command rotates a secret and assigns new-secret-data as its new version.

ibmcloud secrets-manager secret-version-create 
--secret-id=SECRET_ID 
--secret-version-prototype='{"payload": "updated secret credentials", "custom_metadata": {"anyKey": "anyValue"}, "version_custom_metadata": {"anyKey": "anyValue"}}'

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





 Rotating user credentials 

To rotate a user credential secret by using the Secrets Manager CLI plug-in, run the [ibmcloud secrets-manager secret-version-create](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-cli-plugin-secrets-manager-clisecrets-manager-cli-secret-version-create-command) command.
[Menu icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/icon_hamburger.svg)> Resource List.
2. From the list of services, select your instance of Secrets Manager.
3. In the Secrets Manager UI, go to the Secrets list.
4. In the row for the certificate that you want to rotate, click the Actions menu ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/actions-icon-vertical.svg)> Rotate.
5. Optional: Add metadata to your secret or to a specific version of your secret.



1. Upload a file or enter the metadata and the version metadata in JSON format.



6. Click Rotate.

A success message is displayed to indicate that your order is being processed. If the validation completes successfully, a new certificate is issued and the status of the certificate changes from Active, Rotation pending back to Active. If the validation doesn't complete successfully, the status of the certificate changes to Active, Rotation failed.
7. Optional: Check the issuance details of a certificate.

You can check the issuance details of a public certificate by clicking the Actions icon ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/actions-icon-vertical.svg)> Details. If there was an issue with the request, the Status field provides information about why the rotation did not complete successfully.
8. Redeploy the latest certificate version to your TLS termination point.
Replace new lines in the certificate, intermediate, and private key data with n.

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





 Rotating KV secrets 

To rotate a KV secret by using the Secrets Manager CLI plug-in, run the [ibmcloud secrets-manager secret-version-create](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-cli-plugin-secrets-manager-clisecrets-manager-cli-secret-version-create-command) command. For example, the following command rotates a secret and assigns new-secret-data as its new version.

ibmcloud secrets-manager secret-version-create 
--secret-id=SECRET_ID 
--secret-version-prototype='{"data": {"key":"value"}, "custom_metadata": {"anyKey": "anyValue"}, "version_custom_metadata": {"anyKey": "anyValue"}}'

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







 Manually rotating secrets with the API 

You can manually rotate your secrets and certificates by using the Secrets Manager API.



 Rotating arbitrary secrets 

You can rotate arbitrary secrets by calling the Secrets Manager API.

The following example request creates a new version of your secret. When you call the API, replace the ID variables and IAM token with the values that are specific to your Secrets Manager instance.
Master key rotation - Unified Key Orchestrator Plan 

After you load a master key to your Hyper Protect Crypto Services with Unified Key Orchestrator instance, you can rotate the master key on demand to meet industry standards and cryptographic best practices.

A master key is used to wrap encryption keys that are managed in the service instance. With the master key rotation, you retire the original master key and load a new master key that reencrypts the entire key storage.

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.



 How master key rotation works 

Master key rotation works by securely transferring the value between two types of master key registers in crypto units: new master key register and current master key register. Depending on [the approach that you use to initialize your service instance](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-instance-mode), the rotation process is slightly different.

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. For detailed information, see

[PKCS #11 implementation components](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-pkcs11-introuko-pkcs11-components).

The following chart illustrates how the master key register state changes during the master key rotation.

Zoom

![How master key register state changes during master key rotation](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/hs-crypto//images/rotate-master-key.svg)

Figure 1.
[Actions icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/actions-icon-vertical.svg)> Rotate.
5. Select a file or enter a new secret value in JSON format.
6. Optional: Add metadata to your secret or to a specific version of your secret.



1. Upload a file or enter the metadata and the version metadata in JSON format.



7. To rotate the secret immediately, click Rotate.
8. Optional: Check the version history to view the latest updates.

In the row of the secret that you rotated, click the Actions menu ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/actions-icon-vertical.svg)> Version history to verify that a new version was created successfully.







 Creating new versions of user credentials 

You can use the Secrets Manager UI to manually rotate the password values that are associated with a user credentials secret.



1. In the console, click the Menu icon ![Menu icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/icon_hamburger.svg)> Resource List.
2. From the list of services, select your instance of Secrets Manager.
3. In the Secrets Manager UI, go to the Secrets list.
4. In the row for the secret that you want to rotate, click the Actions menu !
Rotate Keys for IBM Key Protect in Data Security Broker Manager 

In this section, you can find details on how to rotate the Master and Data Encryption Keys for IBM Key Protect Keystore in Data Security Broker Manager.



1.  Login to Data Security Broker Manager.
2.  Select Keystores from the left navigation and click on one of the IBM Key Protect Keystore.
3.  Remember to decrypt the data which has been encrypted using the keystore, before you perform the key rotation operation. Also, perform data backup of your data in the databases before the key rotation operation.
4.  In the right navigation, select the Master Key and click on the three dots. Click Rotate Key
5.  Perform the same operation for the Data Encryption Key (DEK) for the same keystore.
6.  Once the Key rotation operation is successfull, you will get a message saying "Master Key was successfully rotated" for the Master Key. For the Data Encryption Key, you will get a message saying "KeyID (ID value) was successfully rotated to KeyID (ID value), if the key rotation is successfull.
Rotate Keys for IBM Cloud Hyper Protect Crypto Services (HPCS) in Data Security Broker Manager 

In this section, you can find details on how to rotate the Master and Data Encryption Keys for HPCS Keystore in Data Security Broker Manager.



1.  Login to Data Security Broker Manager.
2.  Select Keystores from the left navigation and click on one of the IBM Cloud Hyper Protect Crypto Services Keystore.
3.  Remember to decrypt the data which has been encrypted using the keystore, before you perform the key rotation operation. Also, perform data backup of your data in the databases before the key rotation operation.
4.  In the right navigation, select the Master Key and click on the three dots. Click Rotate Key
5.  Perform the same operation for the Data Encryption Key (DEK) for the same keystore.
6.  Once the Key rotation operation is successfull, you will get a message saying Master Key was successfully rotated for the Master Key. For the Data Encryption Key, you will get a message saying KeyID (ID value) was successfully rotated to KeyID (ID value), if the key rotation is successfull.
Select a new file or enter a new secret value.
6. Optional: Add metadata to your secret or to a specific version of your secret.



1. Upload a file or enter the metadata and the version metadata in JSON format.



7. To rotate the secret immediately, click Rotate.
8. Optional: Check the version history to view the latest updates.

In the row of the secret that you rotated, click the Actions menu ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/actions-icon-vertical.svg)> Version history to verify that a new version was created successfully.







 Creating new versions of key-value secrets 

You can use the Secrets Manager UI to manually rotate your key-value secrets.



1. In the console, click the Menu icon ![Menu icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/icon_hamburger.svg)> Resource List.
2. From the list of services, select your instance of Secrets Manager.
3. In the Secrets Manager UI, go to the Secrets list.
4. In the row for the secret that you want to rotate, click the Actions menu ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/actions-icon-vertical.svg)> Rotate.
5. Select a file or enter a new secret value in JSON format.
6. Optional: Add metadata to your secret or to a specific version of your secret.



1. Upload a file or enter the metadata and the version metadata in JSON format.



7.