Oracle Cloud Infrastructure Documentation

Customer-Managed Keys for Oracle Break Glass

Secure your Applications environments with Oracle Break Glass and customer-managed keys.

By default, your applications environments are protected by Oracle-managed encryption keys. By purchasing a subscription that includes Oracle Break Glass service, you are offered the customer-managed keys feature that allows you to provide and manage the encryption keys that protect your environments. You can also purchase this option as an add-on subscription.

You use the OCI Vault service to create and manage encryption keys to secure the data stored at rest in your production and non-production environments. You can set up keys on your environment either during environment creation or you can add the key to an existing environment.

Best Practices for Setting Up and Managing Vaults and Keys

It is a best practice to create separate vaults for production and non-production environments. Within the non-production vault, create separate keys for your test and development environments. For example, you might create the following:

Environment Vault Master encryption key
Production my-production-vault my-production-key
Test my-nonproduction-vault my-test-environment-key
Development my-development-environment-key

Benefits of separate vaults for production and non-production:

  • Maintaining separate vaults allows for independent rotation of keys for production and non-production environments.
  • There is limit to the number of keys per vault. Having separate vaults provides a separate count for production and non-production.

You can verify your key limits and usage by viewing the Limits, Quotas and Usage page where your resource limits, quotas, and usage for the specific region are displayed, broken out by service:

  1. In the Console, open the navigation menu and click Governance & Administration. Under Tenancy Management, click Limits, Quotas and Usage.
  2. From the Service list, select Key Management.

    Verify the key limits for: Key Version Count for Virtual Vaults or Software Key Version Count for Virtual Vaults, as appropriate for the key type you chose to use.

Perform Setup Tasks

Perform these tasks to set up your vaults and keys and prepare your tenancy to use customer-managed keys.

The tenancy administrator has the permissions required to perform all the required setup tasks. If you designate the setup tasks to another role, ensure that they have the appropriate permissions to work with vaults and keys. See Permissions Reference.

The table summarizes the setup tasks that are detailed below.

Task Required/Optional Additional Information
1. Create compartments for your vaults and keys. Optional It is a security best-practice to create separate compartments for you vaults and keys to refine access.
2. Add the system policy to enable customer-managed keys to be used by the application. Required This policy must be added before you add the vault and key to your environment. If this policy is not added, your environment will not complete provisioning (if added during environment creation) or will not complete the work request (if added to an existing environment).
3. Create the vaults for production and non-production environments. Required Follow the Vault service procedure.
4. Create the keys for production and non-production environments. Required Follow the Vault service procedure.

1. Create Compartment for Your Vaults and Keys (Optional)

Although not required, setting up a dedicated compartment for your vaults and keys allows you greater control over who has access to these resources. To enable customer-managed keys for your tenancy, you must create a system policy (Task 2) to allow access to the vaults and keys by Oracle-managed systems. By placing these resources in compartments rather than creating them in the tenancy, you can restrict your policy to the essential compartments. For more information about the benefits of compartments, see Understanding Compartments.

Following are abbreviated instructions for creating a compartment. For the full details on managing compartments, see Managing Compartments.

To create a compartment for your vaults and keys:

  1. Open the navigation menu and click Identity & Security. Under Identity, click Compartments. A list of the compartments you have access to is displayed.

  2. Click Create Compartment.

  3. Enter the following:
    • Name: A unique name for the compartment (maximum 100 characters, including letters, numbers, periods, hyphens, and underscores). The name must be unique across all the compartments in your tenancy. Avoid entering confidential information. For example, my-managed-keys.
    • Description: A friendly description. You can change this later if you want to.
    • Parent Compartment: The compartment you are in is displayed. If you have created other compartments, you can choose another compartment to create this compartment in.
    • Tags: If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you're not sure whether to apply tags, skip this option or ask an administrator. You can apply tags later.
  4. Click Create Compartment.

2. Add the System Policy to Enable Customer-Managed Keys in Your Tenancy

Important

This policy must be added before you add the customer-managed key to your environment. If this policy is not added, your environment will not complete provisioning (if added during environment creation) or will not complete the update (if added to an existing environment). See your application-specific documentation for the policy required for your application.

To create the system policy:

  1. Open the navigation menu, under Infrastructure, click Identity & Security to expand the menu, and then under Identity, click Policies.
  2. Click Create Policy.
  3. Enter the following:
    • Name: A unique name for the policy. The name must be unique across all policies in your tenancy. You cannot change this later.
    • Description: A friendly description. You can change this later if you want to.
    • Compartment: Ensure that the tenancy (root compartment) is selected.
  4. On the Policy Builder, toggle on Show manual editor to display the text box for free-form text entry.
  5. Enter the policy statements from your application-specific documentation.
  6. Click Create.

3. Create Vaults for the Environments

Follow the procedure Creating a Vault in the Vault documentation. If you created compartments, ensure that you create the vaults in the compartment that you specified in the system policy.

It is recommended that you create 2 vaults: one for your production environment keys and one for your non-production environment keys.

4. Create Keys

Follow the procedure Creating a Master Encryption Key in the Vault documentation. Ensure that you create the keys in the compartment that you specified in the system policy.

You must make the following selections when creating keys for applications:

  • For Key Shape: Algorithm, select AES (Symmetric key used for Encrypt and Decrypt (you must select this option for Applications customer-managed keys).
  • For Key Shape: Length, select 256 bits.

It is recommended you create one key in the production vault for your production environment and one key for each non-production environment in your non-production vault.

Adding a Customer-Managed Key to Your Environments

You can add the customer-managed key either during environment creation or after the environment has already been created.

Adding Customer-Managed Key During Environment Creation

This procedure includes only the steps for enabling the customer-managed key. See To create an environment for the full procedure for creating an environment.

On the environment creation page:

  1. Click Show advanced options.
  2. Click the Encryption tab.

  3. Select Encrypt using customer-managed keys.

    If you don't see this option, verify that the subscription has been added to the tenancy.

  4. Select the Vault. If your vault is not in the same compartment that you are creating your environment in, you need to click Change Compartment and choose the appropriate compartment.
  5. Select the Key. If your key is not in the same compartment that you are creating your environment in, you need to click Change Compartment and choose the appropriate compartment. Only AES-256-bit keys are displayed.

After you complete all the steps to set up the environment, the provisioning process begins. Adding the customer-managed key adds time to the provisioning process.

Adding Customer-Managed Key for an Existing Environment

To enable a customer-managed key for an existing environment:

  1. Navigate to the environment: On the Applications tab of the Console, click your application name. On the Overview page, click the environment name.
  2. On the Environment details page, click the Encryption tab.
  3. By default, the Type is Oracle-managed. Click Manage to add your vault and key.

    If you don't see the Manage option, either you have not purchased the option, or the subscription for customer-managed keys has not been added to the tenancy.

  4. Select Encrypt using customer-managed keys.

  5. Select the Vault. If your vault is not in the same compartment that you are creating your environment in, you need to click Change Compartment and choose the appropriate compartment.
  6. Select the Key. If your key is not in the same compartment that you are creating your environment in, you need to click Change Compartment and choose the appropriate compartment. Only AES-256-bit keys are displayed.
  7. Click Save changes.

The scheduling of the encryption of your environment depends on the application. For some applications, a work request is submitted immediately. You can monitor the work request to track the progress of the encryption. Your environment will be unavailable while the update is being made. For other applications, the encryption is performed in the next maintenance cycle or patch update. Until the maintenance occurs, the environment remains encrypted by the Oracle-managed key.

Viewing Key Status and Details

To view key status and details:

  1. Navigate to the environment: On the Applications tab of the Console, click your application name. On the Overview page, click the environment name.
  2. On the Environment details page, click the Encryption tab.

  3. The details of the key are displayed.

You can click the Vault and Key names to navigate to these resources. in the Vault service.

Rotating Keys

You rotate keys based on your organization's security practice. You can set up a CLI job to automatically rotate the keys, or your designated security administrator can rotate them manually through the Vault service Console UI. See Key and Secret Management Concepts for more details on key versions.

To Rotate a Key

Follow the procedure Rotating a Vault Key in the Vault documentation.

Note

Depending on your application, there may be more required steps. Verify the next steps for the rotation procedure in your application-specific documentation.

Disabling and Enabling Keys

If you encounter a situation in which you want to shut down your application service and access to the application database, you can disable the key to immediately force all users out of the system.

Warning

Disabling a key may result in loss of data. If the key is disabled, Oracle will proactively try to shut down the environment to minimize the chance of failures while the environment is being used. Once the key is disabled, however, the environment cannot be restarted until it is enabled again. While the key remains in a disabled state, no applications cloud service will be able to access any previously saved customer data.
Note

When you initiate the disabling of a key, a series of processes takes place to shut down the components of the environment (e.g., the database services, the middle tier, the load balancers), which can take up to an hour to complete. Do not attempt to re-enable a key until these processes have completed.

Similarly, when you initiate the enabling of a key, the completion of the set of processes to bring the system back up can take up to an hour.

Deleting Keys

The deletion of keys and vaults is a highly destructive operation and should be performed only by the tenancy administrator in rare circumstances.

When a tenancy administrator deletes a key, any data or any OCI resource (including your Applications database) that is encrypted by this key will be unusable or irretrievable immediately.

We strongly recommend that you back up a key before you schedule the key for deletion. With a backup, you can restore the key and the vault if you want to continue using the key again later.

For more information, see Deleting a Vault Key.

Permissions Reference

The application administrator needs read permissions for vaults and keys. The read permission enables the administrator to:
  • Choose the vault and key during configuration.
  • View the vault and keys in the OCI Vault service for troubleshooting.

To add the permissions for the Application Administrator:

  1. See the procedure Applications Services Policy Reference , which describes creating the Applications administrator role.
  2. Add the following statements to the role, if not already present: 
    
Allow group <your-group-name> to read vaults in tenancy
Allow group <your-group-name> to read keys in tenancy

If you want the application administrator to also be able to create the vaults and keys, or if you designate another individual, such as a security administrator to manage vaults and keys, they must be members of a group with the following permissions:

allow group <group-name> to manage keys in <location> where request.permission not in ('KEY_DELETE')
allow group <group-name> to manage vaults in <location> where request.permission not in ('VAULT_DELETE')

Note that the delete permissions are removed from the policy statements. That is to ensure that only the tenancy administrator can perform delete operations. See Add a User with Limited Access for the procedures to create groups and policies to define roles.