Securing your data in Secrets Manager

To ensure that you can securely manage your data when you use IBM Cloud® Secrets Manager, it is important to know exactly what data is stored and encrypted and how you can delete it. Data encryption by using customer-managed keys is supported by integrations with Key Protect or Hyper Protect Crypto Services.

How your data is stored and encrypted in Secrets Manager

When you work with Secrets Manager, the service communicates with HashiCorp Vault to process operations on secrets of different types. By design, Vault uses a security barrier for all requests that are made to its back end. Data that leaves Vault is automatically encrypted by using a 256-bit Advanced Encryption Standard (AES) cipher in the Galois Counter Mode (GCM) with 96-bit nonces.

Secrets Manager encrypts all secrets at rest with envelope encryptionThe process of encrypting data with a data encryption key and then encrypting the key with a root key that can be fully managed.. Your encrypted secrets are stored in a dedicated Cloud Object Storage bucket that is unique to your instance. To protect secrets at rest, Secrets Manager integrates with a key management service, such as Key Protect and Hyper Protect Crypto Services. Each version of every secret is encrypted by a data encryption key (DEK) that is protected by a root keyA symmetric wrapping key that is used for encrypting and decrypting other keys that are stored in a data service., which is used by Secrets Manager to seal and unseal access to Vault. This integration protects your secrets by using encryption keys that are rooted in FIPS-validated hardware security modulesA physical appliance that provides on-demand encryption, key management, and key storage as a managed service.. At no time are your credentials available in clear text while they are stored by the service.

Secrets Manager also uses the following security mechanisms to protect your data in transit.

TLS 1.2+ for end to end communications
mTLS for internal communications
Web App Firewall and DDoS protection
Ingress and Egress network rules to isolate your dedicated instance

Protecting your sensitive data in Secrets Manager

You can add a higher level of encryption control to your data at rest (when it is stored) by enabling integration with a key management service.

The data that you store in IBM Cloud is encrypted at rest by using envelope encryption. If you need to control the encryption keys, you can integrate a key management service. These processes are commonly referred to as Bring Your Own Keys (BYOK) or Keep Your Own Keys (KYOK). With a key management service, you can create, import, and manage encryption keys. You can assign access policies to the keys, assign users or service IDs to the keys, or give the key access only to a specific service.

The following table describes your options for managing the encryption of your Secrets Manager data.

Encryption options for Secrets Manager
Encryption	Description
Provider-managed encryption	The data that you store in Secrets Manager is encrypted at rest by using an IBM-managed key. The encryption key is stored in Key Protect. This setting is by default.
Customer-managed encryption	The data that is stored in Secrets Manager is encrypted at rest by using an encryption key that you own and manage. You can use a root key that you manage in Key Protect or Hyper Protect Crypto Services.

About customer-managed keys

Secrets Manager uses envelope encryption to implement customer-managed keys. Envelope encryption describes encrypting one encryption key with another encryption key. The key used to encrypt the actual data is known as a data encryption key (DEK)A cryptographic key used to encrypt data that is stored in an application.. The DEK itself is never stored but is wrapped by a second key that is known as the key encryption key (KEK) to create a wrapped DEK. To decrypt data, the wrapped DEK is unwrapped to get the DEK. This process is possible only by accessing the KEK, which in this case is your root key that is stored in your key management service.

You can encrypt the data that you store in Secrets Manager by using the Bring Your Own Key process (BYOK), which is supported by Key Protect. With this multi-tenant service, you can import your encryption keys from the on-premises hardware security modules (HSM), then manage the keys. If you would like exclusive control of the entire key hierarchy, which includes the master key, you can use the Keep Your Own Key (KYOK) process, which is supported by Hyper Protect Crypto Services. With KYOK, in addition to the BYOK capabilities, you have the technical assurance that even IBM cannot access your keys. Learn more.

Depending on your use case and security requirements, the key management service that is most suited for your organization's needs can vary. To learn more about which key management solution is best for you, see How is Hyper Protect Crypto Services different from Key Protect?

Enabling customer-managed keys for Secrets Manager

If you choose to work with a key that you manage, you must ensure that valid IAM authorization is assigned to the instance of Secrets Manager that you're working with. To create that authorization, you can use the following steps.

Create an instance of Key Protect or Hyper Protect Crypto Services.
Generate or import a root key to your key management service instance.

When you use Key Protect or Hyper Protect Crypto Services to create a root key, the service generates cryptographic key material that is rooted in cloud-based HSMs. Be sure that the name of your key does not contain any personal information such as your name or location.
Grant service access to Key Protect or Hyper Protect Crypto Services.

You must be the account owner or an administrator for the instance of the key management service that you're working with. You must also have at least Viewer access for the Secrets Manager service.
1. Go to Manage > Access IAM > Authorizations.
2. Select the Secrets Manager service as the source service.
3. Select the instance of the Key Protect or Hyper Protect Crypto Services as the target service.
4. Assign the Reader role.
5. Click Authorize to confirm the authorization.
If you choose to delete your Secrets Manager instance later, this authorization is also deleted by IAM.
Create an instance of the Secrets Manager service.
1. Select the region that corresponds to the region for the instance of the key management service that you created previously.
2. Select your Key Protect or Hyper Protect Crypto Services instance.
3. Select the Root key that you previously authorized.
4. Click Create.

Deleting your data in Secrets Manager

When you delete your instance of Secrets Manager, all the user data that is associated with it is also deleted. When the service instance is deleted, a 7-day reclamation period begins. During that time, you're able to restore the instance and all of its associated user data. However, if the instance and data are permanently deleted, it can no longer be restored. Secrets Manager does not store any data from permanently deleted instances.

If your instance was automatically deleted as part of the release of new pricing plans, you can use the reclamation process to restore it. After it is restored, you must upgrade your plan within 1 hour or it will be deleted again.

The Secrets Manager data retention policy describes how long your data is stored after you delete the service. The data retention policy is included in the Secrets Manager service description, which you can find in the IBM Cloud Terms and Notices.

Deleting a Secrets Manager instance

If you no longer need an instance of Secrets Manager, you can delete the service instance and any data that is stored. Your instance enters a disabled state, and after 7 days its data is permanently deleted. You can also choose to delete your service instance by using the console.

During the 7-day reclamation period, do not delete authorizations between Secrets Manager and other integrated services, such as Key Protect. Secrets Manager uses the authorization to unregister your instance from any associated resources in those services. After the instance is permanently deleted, the authorization is also deleted by IAM.

Delete the service and place it in a reclamation period of 7 days.
```
ibmcloud resource service-instance-delete "<instance_name>"
```
Replace <instance_name> with the name of the Secrets Manager instance that you want to delete.
Optional: To permanently delete your instance, get the reclamation ID.
```
ibmcloud resource reclamations --resource-instance-id <instance_ID>
```
Replace <instance_ID> with your Secrets Manager instance ID.

If you choose to permanently delete the instance by deleting its reclamation, you cannot restore your data.
Optional: Permanently delete the reclamation instance.
```
ibmcloud resource reclamation-delete <reclamation_ID>
```
Replace <reclamation_ID> with the value that you retrieved in the previous step.

Restoring a deleted service instance

If you haven't permanently deleted your instance, you can restore it during the 7-day reclamation period.

View which service instances are available for restoration.
```
ibmcloud resource reclamations
```
From the list of available instances, copy the reclamation ID of the Secrets Manager instance that you want to restore.
Restore the reclamation.
```
ibmcloud resource reclamation-restore <reclamation_ID>
```
Replace <reclamation_ID> with the value that you retrieved in the previous step.