Managing Encryption Keys on External Devices

Learn how to store and manage database encryption keys.

There are two options to store and manage database encryption keys for your autonomous databases on Exadata Cloud@Customer:
  1. In the Guest VM on the Exadata Infrastructure.
  2. On an external key management device. Oracle Key Vault is the currently supported device.

About Oracle Key Vault

Oracle Key Vault is a full-stack, security-hardened software appliance built to centralize the management of keys and security objects within the enterprise.

Note

The Oracle Key Vault is a customer-provisioned and managed system and it is not part of Oracle Cloud Infrastructure managed services.

Overview of Key Store

Integrate your on-premises Oracle Key Vault (OKV) with customer-managed database cloud services to secure your critical data on-premises.

Oracle Key Vault integration enables you to take complete control of your encryption keys and store them securely on an external, centralized key management device.

OKV is optimized for Oracle wallets, Java keystores, and Oracle Advanced Security Transparent Data Encryption (TDE) master keys. Oracle Key Vault supports the OASIS KMIP standard. The full-stack, security-hardened software appliance uses Oracle Linux and Oracle Database technology for security, availability, and scalability, and can be deployed on your choice of compatible hardware.

OKV also provides a REST interface for clients to auto-enroll endpoints and setup wallets and keys. For Autonomous Databases on Exadata Cloud@Customer to connect to OKV REST interface, create a key store in your tenancy to store the IP address and administrator credentials of your OKV. Exadata Cloud@Customer temporarily stores the OKV REST user administrator password required to connect to the OKV appliance in a password-protected wallet file so that the software running in the customer VM can connect to the OKV server. Following the migration of the TDE keys to OKV, the cloud automation software will remove the password from the wallet file. Ensure that you create a secret with Oracle's Vault Service, which will store the password required for autonomous databases to connect to OKV for key management.

For more information, see "Oracle Key Vault".

Required IAM Policy for Managing OKV on Oracle Exadata Database Service on Cloud@Customer

Review the identity access management (IAM) policy for managing OKV on Oracle Exadata Database Service on Cloud@Customer Systems.

A policy is an IAM document that specifies who has what type of access to your resources. It is used in different ways: to mean an individual statement written in the policy language; to mean a collection of statements in a single, named "policy" document (which has an Oracle Cloud ID (OCID) assigned to it), and to mean the overall body of policies your organization uses to control access to resources.

A compartment is a collection of related resources that can be accessed only by certain groups that have been given permission by an administrator in your organization.

To use Oracle Cloud Infrastructure, you must be given the required type of access in a policy written by an administrator, whether you're using the Console, or the REST API with a software development kit (SDK), a command-line interface (CLI), or some other tool. If you try to perform an action, and receive a message that you don’t have permission, or are unauthorized, then confirm with your administrator the type of access you've been granted, and which compartment you should work in.

For administrators: The policy in "Let database admins manage DB systems" lets the specified group do everything with databases and related database resources.

If you're new to policies, then see "Getting Started with Policies" and "Common Policies". If you want to dig deeper into writing policies for databases, then see "Details for the Database Service".

Tagging Resources

You can apply tags to your resources to help you organize them according to your business needs.

You can apply tags at the time you create a resource, or you can update the resource later with the desired tags. For general information about applying tags, see "Resource Tags".

Moving Resources to a Different Compartment

You can move OKV Vault, Secret, and Keystore resources from one compartment to another.

After you move an OCI resource to a new compartment, inherent policies apply immediately and affect access to the resource. Moving an OKV Vault resource doesn't affect access to any OKV Vault Keys or OKV Vault Secrets that the OKV Vault contains. You can move an OKV Vault Keys or OKV Vault Secrets from one compartment to another independently of moving the OKV Vault it's associated with. For more information, see Managing Compartments.

Setting Up Your Oracle Exadata Database Service on Cloud@Customer to Work With Oracle Key Vault

Prerequisites
  1. Ensure that OKV is set up and the network is accessible from the Exadata client network. Open ports 443, 5695, and 5696 for egress on the client network for the OKV client software and Oracle database instance to access the OKV server.
  2. Ensure that the REST interface is enabled from the OKV user interface.
  3. Create "OKV REST Administrator" user.

    You can use any qualified username of your choice, for example, "okv_rest_user". For ADB-C@C and ExaDB-C@C, use the same or different REST users. Those databases can be key-managed in the same or different on-prem OKV clusters. ExaDB-C@C needs REST user with create endpoint privilege. ADB-C@C needs REST user with create endpoint and create endpoint group privileges.

  4. Gather OKV administrator credentials and IP address, which is required to connect to OKV.

For more information, see Network Port Requirements, Managing Oracle Key Vault Users, and Managing Administrative Roles and User Privileges

Step 1: Create a Vault in OKV Vault Service and Add a Secret to the Vault to Store OKV REST Administrator Password

Your Exadata Cloud@Customer infrastructure communicates with OKV over REST each time an Oracle Database is provisioned to register the Oracle Database and request a wallet on OKV. Therefore, Exadata infrastructure needs access to the REST admin credentials to register with the OKV server.

These credentials are stored securely in the Oracle Vault Service in OCI as a Secret and accessed by your Exadata Cloud@Customer infrastructure only when needed. When needed, the credentials are stored in a password-protected wallet file.

To store the OKV administrator password in the OKV Vault service, create a vault by following the instructions outlined in Managing Vaults and create a Secret in that vault by following the instructions outlined in Managing Secrets.

Step 2: Create a Dynamic Group and a Policy Statement for Key Store to Access Secret in OKV Vault

To grant your Key Store resources permission to access Secret in OKV Vault, you create an IAM dynamic group that identifies these resources and then create an IAM policy that grants this dynamic group access to the Secret you created in the OKV Vaults and Secrets.

When defining the dynamic group, you identify your Key Store resources by specifying the OCID of the compartment containing your Key Store.

  1. Copy the OCID of the compartment containing your Key Store resource.

    You can find this OCID on the Compartment Details page of the compartment.

  2. Create a dynamic group by following the instructions in "To create a dynamic group" in Oracle Cloud Infrastructure Documentation. When following these instructions, enter a matching rule of this format:
    ALL {resource.compartment.id ='<compartment-ocid>'}

    where <compartment-ocid> is the OCID of the compartment containing your Key Store resource.

  3. After creating the dynamic group, navigate to (or create) an IAM policy in a compartment higher up in your compartment hierarchy than the compartment containing your vaults and secrets. Then, add a policy statement of this format:
    allow dynamic-group <dynamic-group> to use secret-family in compartment <vaults-and-secrets-compartment>

    where <dynamic-group> is the name of the dynamic group you created and <vaults-and-secrets-compartment> is the name of the compartment in which you created your vaults and secrets.

Step 3: Create a Dynamic Group and a Policy Statement for Exadata Infrastructure to Key Store

To grant your Exadata infrastructure resources permission to access Key Store, you create an IAM dynamic group that identifies these resources and then create an IAM policy that grants this dynamic group access to the Key Store you created.

When defining the dynamic group, you identify your Exadata infrastructure resources by specifying the OCID of the compartment containing your Exadata infrastructure.

  1. Copy the OCID of the compartment containing your Exadata infrastructure resource.
    You can find this OCID on the Compartment Details page of the compartment.
  2. Create a dynamic group by following the instructions in "To create a dynamic group" in Oracle Cloud Infrastructure Documentation. When following these instructions, enter a matching rule of this format:
    ALL {resource.compartment.id ='<compartment-ocid>'}

    where <compartment-ocid> is the OCID of the compartment containing your Exadata infrastructure resource.

  3. After creating the dynamic group, navigate to (or create) an IAM policy in a compartment higher up in your compartment hierarchy than the compartment containing your Key Store. Then, add a policy statement of this format:
    Allow dynamic-group <dynamic-group> to use keystores in compartment <key-store-compartment>

    where <dynamic-group> is the name of the dynamic group you created and <key-store-compartment> is the name of the compartment in which you created your Key Store.

Step 4: Create a Policy Statement for Database Service to Use Secret from OKV Vault Service

To grant the Exadata Database service permission to use the secret in OKV Vault to log in to the OKV REST interface, navigate to (or create) an IAM policy in a compartment higher up in your compartment hierarchy than the compartment containing your OKV Vaults and Secrets. Then, add a policy statement of this format:
allow service database to read secret-family in compartment <vaults-and-secrets-compartment>

where <vaults-and-secrets-compartment> is the name of the compartment in which you created your OKV Vaults and Secrets.

Once the OKV Vault is set up and the IAM configuration is in place, you are now ready to deploy your Oracle Key Vault 'Key Store' in OCI and associate it with your Exadata Cloud@Customer VM Cluster.

Step 5: Create Key Store

Follow these steps to create a Key Store to connect to an on-premises encryption key appliance such as Oracle Key Vault (OKV).

  1. Open the navigation menu. Under Oracle Database, click Exadata Database Service on Cloud@Customer.
  2. Choose your Compartment.
  3. Click Key Stores.

    Key Stores page displays the list of name of key stores, the number of databases associated with each database, and the date on which each key store was created.

  4. Click Create Key Store.
  5. In the Create Key Store dialog, enter the following general information:
    • Name your key store: A user-friendly description or other information that helps you easily identify the Key Store resource. Avoid entering confidential information.
    • Oracle Key Vault connection settings
      • Connection IP addresses: Enter at least one OKV cluster node IP address; multiple comma-separated IP addresses (of the same OKV cluster) are possible, for example, 193.10.20.1, 193.10.20.2.
      • Administrator username: Enter the user name of the okv_rest_user.
      • Administrator Password Secret: The administrator password is stored with the secret management service within OCI. Select the OKV Vault in your tenancy that contains okv_rest_user password stored as Secret.
    • Tags: Optionally, you can apply tags. If you have permission to create a resource, you also have permission to apply free-form tags to that resource. To apply a defined tag, you must have permission to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure if you should apply tags, skip this option (you can apply tags later) or ask your administrator. Avoid entering confidential information.
  6. Click Create Key Store.
  7. Ensure that you use the same "okv_rest_user" user credentials, while provisioning Autonomous Database.

    For more information, see Managing Vaults, Managing Keys, and Managing Secrets.

Managing Your Key Store

View Key Store Details

Follow these steps to view Key Store details that include Oracle Key Vault (OKV) connection details and the list of associated databases.

  1. Open the navigation menu. Under Oracle Database, click Exadata Database Service on Cloud@Customer.
  2. Choose your Compartment.
  3. Click Key Stores.

    Key Stores page displays the list name of Key Stores, the number of databases associated with each database, and the date on which each Key Store was created.

  4. Click the name of the Key Store or click the Actions icon (three dots), and then click View Details.
  5. Click the link in the Administrator Password Secret field to view secret details.

    The Associated Databases section displays the list of CDBs associated with this Key Store.

Edit Key Store Details

You can edit a Key Store only if it is not associated with any CDBs.

  1. Open the navigation menu. Under Oracle Database, click Exadata Database Service on Cloud@Customer.
  2. Choose your Compartment.
  3. Click Key Stores.
  4. Click the name of the Key Store or click the Actions icon (three dots), and then click View Details.
  5. On the Key Store Details page, click Edit.
  6. On the Edit Key Store page, make changes as needed, and then click Save Changes.

Move a Key Store to Another Compartment

Follow these steps to move a Key Store on an Oracle Exadata Database Service on Cloud@Customer system from one compartment to another compartment.

  1. Open the navigation menu. Under Oracle Database, click Exadata Database Service on Cloud@Customer.
  2. Choose your Compartment.
  3. Click Key Stores.
  4. Click the name of the Key Store or click the Actions icon (three dots), and then click View Details.
  5. On the Key Store Details page, click Move Resource.
  6. On the Move Resource to a Different Compartment page, select the new compartment.
  7. Click Move Resource.

Delete a Key Store

You can delete a Key Store only if it is not associated with any CDBs.

  1. Open the navigation menu. Under Oracle Database, click Exadata Database Service on Cloud@Customer.
  2. Choose your Compartment.
  3. Click Key Stores.
  4. Click the name of the Key Store or click the Actions icon (three dots), and then click View Details.
  5. On the Key Store Details page, click Delete.
  6. On the Delete Key Store dialog, click Delete.

View Key Store Associated Container Database Details

Follow these steps to view details of the container database associated with a Key Store.

  1. Open the navigation menu. Under Oracle Database, click Exadata Database Service on Cloud@Customer.
  2. Choose your Compartment.
  3. Click Key Stores.
  4. In the resulting Key Stores page, click the name of the Key Store or click the Actions icon (three dots), and then click View Details.
  5. Click the name of the associated database or click the Actions icon (three dots), and then click View Details.

Using the API to Manage Key Store

Learn how to use the API to manage key store.

For information about using the API and signing requests, see "REST APIs" and "Security Credentials". For information about SDKs, see "Software Development Kits and Command Line Interface".

The following table lists the REST API endpoints to manage key store.

Operation REST API Endpoint

Create OKV Key Store

CreateKeyStore

View OKV Key Store

GetKeyStore

Update OKV Key Store

UpdateKeyStore

Delete OKV Key Store

DeleteKeyStore

Change Key store compartment

ChangeKeyStoreCompartment

Choose between customer-managed and Oracle-managed encryption

CreateDatabase

Get the Key Store (OKV or Oracle-managed) and OKV wallet name

GetDatabase

Change Key store type

changeKeyStoreType

Rotate OKV and Oracle-managed key

RotateVaultKey