vania-janet/multiturn-rag-retrieval-data huggingface dataset:
After you configure the Secrets Manager tool integration and [authorize your toolchain](https://cloud.ibm.com/docs/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/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.
Setting up Secrets Manager in your Red Hat OpenShift cluster 

When you integrate IBM Cloud Secrets Manager with your Red Hat OpenShift on IBM Cloud cluster, you can centrally manage Ingress subdomain certificates and other secrets.



 About Secrets Manager 

With Secrets Manager, you can use a single service to manage your secrets and control who has access to them. A Secrets Manager instance is not automatically provisioned in your cluster. However, you can use a single Secrets Manager instance across multiple clusters, and a single cluster can have more than one instance.



 What functionality can I gain with Secrets Manager? 

With Secrets Manager, you can:



* Create managed Kubernetes secrets with Ingress TLS certificates included.
* Create Kubernetes secrets of any type by using the CRN of any Secrets Manager instance you own.
* Automatically update your secrets in your cluster on a regular basis.
* Track the expiration dates of your certificates from the IBM Cloud console.
* Control who has access to your secrets by creating secret groups for approved users.



Note that to have your secrets automatically updated, you must register at least one Secrets Manager instance to your cluster. For more information, see [Registering your Secrets Manager instance to your cluster](https://cloud.ibm.com/docs/openshift?topic=openshift-secrets-mgrsecrets-mgr_setup_register).







 Secrets Manager FAQ 

Keep the following points in mind when using Secrets Manager.

What types of secrets are supported with Secrets Manager?
: Secrets Manager supports IAM credentials, key-value secrets, user credentials, arbitrary secrets, and Kubernetes secrets. For Kubernetes secrets, Secrets Manager supports both TLS and non-TLS (Opaque) secret types. With TLS secrets, you can specify one certificate CRN. With non-TLS secrets, you can specify multiple fields to pull non-certificate secrets. If you do not specify a secret type when you create a secret, TLS is applied by default. For more information on supported secrets, see [Working with secrets of different types](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-what-is-secretsecret-types).
To view the configurations that are defined for your instance, you can go to Secrets engines > Private certificates.
11. Select a [certificate template](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-certificate-templates).

The template that you select determines the parameters to be applied to your generated certificate. To view the details of the certificate templates that are defined for your selected certificate authority, you can go to Secrets engines > Private certificates. From the list of certificate authorities, expand the row of the CA that you want to use as the issuing authority for your private certificate, and click Templates.
12. Optional: Enable automatic rotation for the certificate.

To enable automatic rotation, switch the rotation toggle to On. Select an interval and unit that specifies the number of days between scheduled rotations.

Depending on the certificate template that you choose in the following steps, some restrictions on the rotation interval for your private certificate might apply. For example, the rotation interval can't exceed the time-to-live (TTL) that is defined in the template. For more information, see [Certificate templates](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-certificate-templates).
13. Required: Specify a common name for your certificate.

Depending on the certificate template that you choose, some restrictions on the common name might apply. To view the details of your selected certificate template, you can go to Secrets engines > Private certificates. From the list of certificate authorities, expand the row of the CA that you want to use as the issuing authority for your private certificate, and click Templates.
14. Select the

secret groupthat you want to assign to the certificate.

If your selected certificate template allows certificates to be added to specific secret groups, only those allowed groups are listed. If the template has no restrictions, you can create a secret group if you don't already have one. Your certificate is added to the new group automatically.
For more information, see [Creating IAM credentials](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam-credentials).

Restore secrets to a previous version
: Need to roll back a secret to its previous version? If you need to revert a secret, you can now restore select secret types to a previous version.

Currently, you can restore 1 version back for IAM credentials and public certificate secrets only. For more information, see [Restoring secrets to a previous version](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-version-history&interface=uirestore-secrets).

Rotate IAM credentials on-demand
: You can now rotate IAM credentials manually by using the UI or APIs. For more information, see [Rotating secrets manually](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-manual-rotation).





 20 September 2021 

Order domain-validated TLS certificates from Let's Encrypt
: In addition to [importing your existing certificates](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-certificates), you can now use Secrets Manager to order domain-validated certificates!

In this release, the following certificate authorities (CA) and DNS providers are supported:



* Let's Encrypt
* IBM Cloud Internet Services (CIS)
* IBM Cloud classic infrastructure (SoftLayer)



For more information, see [Ordering domain-validated certificates from third-parties](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-public-certificatesorder-public-certificates) or check out the [announcement blog](https://www.ibm.com/cloud/blog/announcements/now-available-order-domain-validated-tls-certificates-with-single-tenant-ibm-cloud-secrets-manager).





 30 August 2021 

Migrate certificates from Certificate Manager to Secrets Manager
: Ready to try Secrets Manager for certificates management?
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.

To view your authorizations in IBM Cloud, complete the following steps:



1. From the IBM Cloud console, click Manage > Access (IAM).
2. Click Authorizations.

You can also access your authorizations on the [Manage authorizations](https://cloud.ibm.com/iam/authorizations) page.

You can create the authorization manually, if required. To successfully resolve the secret references, your toolchain instance must have both Viewer and SecretsReader access to the correct Secrets Manager service instance.

When Secrets Manager tool integrations that identify secrets by CRN are configured to access secrets in a different account, you must create the authorization in the account where the Secrets Manager service instance exists.







 Configuring Secrets Manager by using the API 

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.
Rotating master keys by using key part files 

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. To rotate the master key using master key part files on your local workstation, follow these steps.

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 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 do the following steps:



* 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. For more information, see
"s1.example.com",
".s2.example.com"
],
"ca": "lets-encrypt-config",
"dns": "manual",
"rotation": {
"auto_rotate": true,
"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"

Example response:

"metadata": {
"collection_type": "application/vnd.ibm.secrets-manager.secret+json",
"collection_total": 1
},
"resources": [
{
"alt_names":
"domain2",
"domain3"
],
"common_name": "domain1",
"created_by": "User",
"creation_date": "2022-09-13T06:21:33Z",
"crn": "secret crn",
"description": "Description for ordered certificate.",
"downloaded": false,
"id": "38747ae6-8c69-d745-5276-cdf3157b9021",
"issuance_info": {
"auto_rotated": false,
"bundle_certs": false,
"ca": "ca_config_name",
"challenges":
{
"domain": "domain1",
"expiration": "2022-09-20T06:21:36Z",
"status": "pending",
* UI
* API







 Rotating root keys based on the rotation policy 

You can set an automatic rotation policy for a root key by using IBM Cloud® Hyper Protect Crypto Services.

When you set an automatic rotation policy for a root key, you shorten the lifetime of the key at regular intervals, and you limit the amount of information that is protected by that key.

You can create a rotation policy only for root keys that are generated in Hyper Protect Crypto Services. If you imported the root key initially, you must provide new base64 encoded key material to rotate the key. For more information, see [Rotating root keys on demand](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-keysrotate-keys).

Want to learn more about your key rotation options in Hyper Protect Crypto Services? Check out [Comparing your key rotation options](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-root-key-rotation-introcompare-key-rotation-options) for more information.



 Managing rotation policies in the console 

If you prefer to manage policies for your root keys by using a graphical interface, you can use the IBM Cloud console.



1. [Log in to the IBM Cloud console](https://cloud.ibm.com/).
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 Hyper Protect Crypto Services.
4. On the KMS keys page, use the Keys table to browse the keys in your service.
5. Click the Actions icon ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/icons/action-menu-icon.svg) to open a list of options for a specific key.
6. From the options menu, click Edit key rotation policy to manage the rotation policy for the key.
7.
Currently, only [Secrets Manager](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-secretsmanager) tool integrations support referencing secrets by CRN. This format allows for greater flexibility because you can reference secrets from a Secrets Manager instance in a different account if the correct [authorization](https://cloud.ibm.com/iam/authorizations) is in place.

Make sure that you consider the following prerequisites for specifying a secrets reference within the scope of a toolchain:



* The secrets store must be added to the toolchain as a tool integration. For more information about secrets store tool integrations, see [Configuring Key Protect](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-keyprotect), [Configuring Secrets Manager](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-secretsmanager), and [Configuring HashiCorp Vault](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-hashicorpvault).
* An IAM service-to-service authorization policy must be configured to allow the source toolchain to retrieve secrets from the target secrets store. For more information about service-to-service authorizations, see [Using authorizations to grant access between services](https://cloud.ibm.com/docs/account?topic=account-serviceauth).



When you work outside of the console, such as with the API or Terraform, use the following format for secrets references by name:



* {vault::SECRET_STORE_INTEGRATION_NAME.SECRET_NAME} when you reference secrets that are contained within Key Protect.
* {vault::SECRET_STORE_INTEGRATION_NAME.SECRET_GROUP_NAME.SECRET_NAME} when you reference secrets that are contained within Secrets Manager.
* {vault::SECRET_STORE_INTEGRATION_NAME.SECRET_NAME.FIELD_NAME} when you reference secrets that are contained within HashiCorp Vault.



where:
* UI
* API







 Rotating managed keys manually 

You can rotate your managed keys on demand by using Hyper Protect Crypto Services with Unified Key Orchestrator.

To learn how managed key rotation works, see [Managed key rotation](https://cloud.ibm.com/docs/hs-crypto/concepts?topic=hs-crypto-managed-key-rotation-intro).



 Rotating managed keys with the console 

If you prefer to rotate your managed keys by using a graphical interface, you can use the IBM Cloud console.

Complete the following steps to rotate a 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 Hyper Protect Crypto Services with Unified Key Orchestrator.
4. Click Managed keys from the navigation to view all the available keys.
5. Select the key that you want to rotate and click the Actions icon ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/icons/action-menu-icon.svg) to open a list of options for the key.
6. Click Rotate from the options menu. Alternatively, you can click Show details from the options menu and then click Rotate on the key details page.
7. Click Rotate key to confirm.







 Rotating managed keys with the API 

To rotate a managed key through the API, follow these steps:



1. [Retrieve your service and authentication credentials to work with keys in the service](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-up-uko-api).
2. Rotate a managed key by making a POST call based on the following example:
* UI
* API







 Rotating root keys manually 

You can rotate your

root keyson demand by using IBM Cloud® Hyper Protect Crypto Services.

When you rotate your root key, you shorten the lifetime of the key, and you limit the amount of information that is protected by that key.

To learn how key rotation helps you meet industry standards and cryptographic best practices, see [Key rotation](https://cloud.ibm.com/docs/hs-crypto/concepts?topic=hs-crypto-root-key-rotation-intro).



 Rotating root keys in the console 

If you prefer to rotate your root keys by using a graphical interface, you can use the IBM Cloud console.

[After you create or import your existing root keys into the service](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-create-root-keys), complete the following steps to rotate a 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 Hyper Protect Crypto Services.
4. On the KMS keys page, use the Keys table to browse the keys in your service.
5. Select the key that you want to rotate and click the Actions icon ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/icons/action-menu-icon.svg) to open a list of options for the key.
6. From the options menu, click Rotate key.

If you initially provided the key material for the key, specify the new base64 encoded key material that you want to store and manage in the service. Ensure that the key material meets the following requirements:



* Must be 128, 192, or 256 bits.
$ 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

 show key details
$ ibmcloud kp key show $KEY_ID --output json

{
"id": "5b976173-7804-4f82-acfa-bb98098bc528",
"name": "my-root-key",
"type": "application/vnd.ibm.kms.key+json",
"algorithmType": "AES",
"createdBy": "user id ...<redacted>...",
"creationDate": "2020-06-10T18:09:27Z",
"lastUpdateDate": "2020-06-10T18:13:31Z",
"lastRotateDate": "2020-06-10T18:13:31Z",
"keyVersion": {
"id": "4330715a-918b-4718-b5ca-9475a214067e",
"creationDate": "2020-06-10T18:13:31Z"
},
"extractable": false,
"state": 1,
ibmcloud secrets-manager policy-update --secret-type=username_password --id=exampleString --metadata='{"collection_type": "application/vnd.ibm.secrets-manager.config+json", "collection_total": 1}' --resources='[{"type": "application/vnd.ibm.secrets-manager.secret.policy+json", "rotation": {"interval": 1, "unit": "day"}}]' --policy=rotation







 ibmcloud secrets-manager policy 

List the rotation policies that are associated with a specified secret.

ibmcloud secrets-manager policy --secret-type SECRET-TYPE --id ID [--policy POLICY]



 Command options 

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

Allowable values are: username_password, iam_credentials, public_cert, private_cert.

--id (string)
: The v4 UUID that uniquely identifies the secret. Required.

The value must match regular expression /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/.

--policy (string)
: The type of policy that is associated with the specified secret.

Allowable values are: rotation.





 Examples 

ibmcloud secrets-manager policy --secret-type=username_password --id=exampleString --policy=rotation









 Config 

Configure secrets engines for your instance so that you can work with specific types of secrets.



 ibmcloud secrets-manager config-update 

Set the configuration for the specified secret type.

Use this method to configure the IAM credentials (iam_credentials) engine for your service instance. Looking to order or generate certificates? To configure the public certificates (public_cert) or private certificates (private_cert) engines, use the Add a configuration method.