Managing Keys

Note

Before the introduction of secrets as a resource, Oracle Cloud Infrastructure Vault was known as Oracle Cloud Infrastructure Key Management.

This topic describes what you can do with keys and key versions to manage their creation and usage. For information specifically about creating keys with your own key material, see Importing Keys and Key Versions. For information about assigning keys to protect supported resources, see Assigning Keys. For information about how you can use keys in cryptographic operations, see Using Keys. For information about backing up and restoring keys, see Backing Up Vaults and Keys. For information about what you can do with vaults where you store keys, see Managing Vaults.

In the context of this topic, management of keys includes the ability to do the following:

  • Create keys
  • View key details
  • View a list of keys
  • View a list of key versions for a specific key
  • Update a key name
  • Manage a key's tags
  • Enable keys for use in cryptographic operations
  • Rotate keys to generate new cryptographic material
  • Disable keys to prevent their usage in cryptographic operations
  • Delete keys to permanently prevent their usage in cryptographic operations or assignment to resources
  • Move a key to a new compartment

Required IAM Policy

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 an SDK, CLI, or other tool. If you try to perform an action and get a message that you don’t have permission or are unauthorized, confirm with your administrator the type of access you've been granted and which compartment  you should work in.

For administrators: for typical policies that give access to vaults, keys, and secrets, see Let security admins manage vaults, keys, and secrets. For more information about permissions or if you need to write more restrictive policies, see Details for the Vault Service.

If you're new to policies, see Getting Started with Policies and Common Policies.

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.

Monitoring Resources

You can monitor the health, capacity, and performance of your Oracle Cloud Infrastructure resources by using metrics, alarms, and notifications. For more information, see Monitoring Overview and Notifications Overview.

For information about monitoring the traffic associated with your master encryption keys, see Vault Metrics.

Moving Resources to a Different Compartment

You can move keys from one compartment to another. After you move a key to a new compartment, inherent policies apply immediately and affect access to the key and key versions. Moving a key doesn't affect access to the vault that a key is associated with. Similarly, you can move a vault from one compartment to another independently of moving any of its keys. For more information, see Managing Compartments.

Using the Console

To create a new master encryption key
  1. Open the navigation menu. Under the Governance and Administration group, go to Security and click Vault.
  2. Under List Scope, in the Compartment list, click the name of the compartment where you want to create the key.
  3. From the list of vaults in the compartment, do one of the following:

    • Click the name of the vault where you want to create the key.

    • Create a new vault for the key by following the instructions in To create a new vault, and then click the name of the vault.

  4. Click Master Encryption Keys, and then click Create Key.
  5. In the Create Key dialog box, choose a compartment from the Create in Compartment list. (Keys can exist outside the compartment the vault is in.)
  6. Click Protection Mode, and then do one of the following:
    • To create a master encryption key that is stored and processed on a hardware security module (HSM), choose HSM.
    • To create a master encryption key that is stored and processed on a server, choose Software.

    You cannot change a key's protection mode after you create it. For more information about keys, including information about key protection modes, see Key and Secret Management Concepts.

  7. Click Name, and then enter a name to identify the key. Avoid entering any confidential information in this field.
  8. Specify the key length, in bits, by choosing a length from the Key Shape: Length list.
  9. Optionally, to apply tags, click Show Advanced Options.
    If you have permissions to create a resource, 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 are not sure if you should apply tags, skip this option (you can apply tags later) or ask your administrator.
  10. When you are finished, click Create Key.
To view key details
  1. Open the navigation menu. Under the Governance and Administration group, go to Security and click Vault.
  2. Under List Scope, in the Compartment list, click the name of the compartment that contains the vault with the key you're interested in.
  3. From the list of vaults in the compartment, click the vault name.

  4. Click Master Encryption Keys, and then click the name of the key for which you want to see configuration details. (If needed, first change the list scope to the compartment that contains the key, and then click the key name.)
  5. The console displays the following information:

    • OCID: The unique, Oracle-assigned ID of the key.
    • Created: The date and time when you initially created the key.
    • Compartment: The unique, Oracle-assigned ID of the compartment that contains the key.
    • Protection Mode: Where the key is stored and processed, whether on a hardware security module (HSM) or on a server (software).
    • Vault: The unique, Oracle-assigned ID of the vault that contains the key.
    • Key Version: The unique, Oracle-assigned ID of the key version.
    • Algorithm: The encryption algorithm used by the key.
    • Length: The number of bits in the key length.
To view a list of keys
  1. Open the navigation menu. Under the Governance and Administration group, go to Security and click Vault.
  2. Under List Scope, in the Compartment list, click the name of the compartment that contains the vault with the keys you're interested in.
  3. From the list of vaults in the compartment, click the vault name.

  4. To see a list of keys in this vault, click Master Encryption Keys. You can see keys in other compartments by changing the list scope.
To view a list of key versions
  1. Open the navigation menu. Under the Governance and Administration group, go to Security and click Vault.
  2. Under List Scope, in the Compartment list, click the name of the compartment that contains the vault with the key you're interested in.
  3. From the list of vaults in the compartment, click the vault name.

  4. Click Master Encryption Keys, click the name of the key for which you want to see a list of key versions, and then click Versions. (If needed, first change the list scope to the compartment that contains the key, and then click the key name.)
To change the name of a key
  1. Open the navigation menu. Under the Governance and Administration group, go to Security and click Vault.
  2. Under List Scope, in the Compartment list, click the name of the compartment that contains the vault with the key you want to rename.
  3. From the list of vaults in the compartment, click the vault name.

  4. Click Master Encryption Keys, locate the key you want to rename, and then click the Actions icon (three dots) for that key. (If needed, first change the list scope to the compartment that contains the key.)
  5. In the Actions menu, click Edit Name.
  6. In the Edit Key Name dialog box, click Name, and then enter a new name. Avoid entering any confidential information in this field.
  7. When you are finished, click Update.
To manage a key's tags
  1. Open the navigation menu. Under the Governance and Administration group, go to Security and click Vault.
  2. Under List Scope, in the Compartment list, click the name of the compartment that contains the vault with the key for which you want to manage tags.
  3. From the list of vaults in the compartment, click the vault name.

  4. Click Master Encryption Keys, locate the key you want to manage, and then click the key name. (If needed, first change the list scope to the compartment that contains the key, and then click the key name.)
  5. On the Key Details page, click the Tags tab to view or edit existing tags. Or, click Add Tags to add new ones.
To enable a key
  1. Open the navigation menu. Under the Governance and Administration group, go to Security and click Vault.
  2. Under List Scope, in the Compartment list, click the name of the compartment that contains the vault with the key you want to enable.
  3. From the list of vaults in the compartment, click the vault name.

  4. Click Master Encryption Keys, locate the key you want to enable, and then select the check box next to the key name. (If needed, first change the list scope to the compartment that contains the key.)
  5. In the Actions menu, click Enable.
To rotate a master encryption key
  1. Open the navigation menu. Under the Governance and Administration group, go to Security and click Vault.
  2. Under List Scope, in the Compartment list, click the name of the compartment that contains the vault with the key you want to rotate.
  3. From the list of vaults in the compartment, click the vault name.

  4. Click Master Encryption Keys, locate the key you want to rotate, and then select the check box next to the key name. (If needed, first change the list scope to the compartment that contains the key.)
  5. In the Actions menu, click Rotate Key. (You can only rotate keys in an enabled state.)
  6. In the Confirm dialog box, click Rotate Key.

Cryptographic operations involving objects that were encrypted with the previous version of this key will continue to use the older key version. You can re-encrypt those objects with the current key version if you prefer.

To disable a key
  1. Open the navigation menu. Under the Governance and Administration group, go to Security and click Vault.
  2. Under List Scope, in the Compartment list, click the name of the compartment that contains the vault with the key you want to disable.
  3. From the list of vaults in the compartment, click the vault name.

  4. Click Master Encryption Keys, locate the key you want to disable, and then click the Actions icon (three dots) for that key. (If needed, first change the list scope to the compartment that contains the key.)
  5. In the Actions menu, click Disable.
To delete a key
Warning

When you set a key to the Pending Deletion state, anything encrypted by that key immediately becomes inaccessible. This includes secrets. The key also cannot be assigned or unassigned to any resources or otherwise updated. When the key is deleted, all key material and metadata is irreversibly destroyed. Before you delete a key, either assign a new key to resources currently encrypted by the key or preserve your data another way. If you want to restore use of a key before it is permanently deleted, you can cancel its deletion.
  1. Open the navigation menu. Under the Governance and Administration group, go to Security and click Vault.
  2. Under List Scope, in the Compartment list, click the name of the compartment that contains the vault that has the key you want to delete.
  3. From the list of vaults in the compartment, click the vault name.

  4. Click Master Encryption Keys, locate the key you want to delete, and then click the Actions icon (three dots) for that key. (If needed, first change the list scope to the compartment that contains the key.)
  5. In the Actions menu, click Delete Key.
  6. Confirm that you want to delete the key by clicking the box and then typing the key name.
  7. Schedule when you want the Vault service to delete the key. By default, the service schedules keys for deletion 30 days from the current date and time. You can set a range between 7 days and 30 days.
  8. When you're ready, click Delete Key. If needed, you can restore use of the key and access to encrypted resources and data by canceling the scheduled deletion.
To cancel the deletion of a key
Tip

You can only cancel the deletion of a key that's in a Pending Deletion state.
  1. Open the navigation menu. Under the Governance and Administration group, go to Security and click Vault.
  2. Under List Scope, in the Compartment list, click the name of the compartment that contains the vault that has the key you want to delete.
  3. From the list of vaults in the compartment, click the vault name.

  4. Click Master Encryption Keys, locate the key you want to delete, and then click the Actions icon (three dots) for that key. (If needed, first change the list scope to the compartment that contains the key.)
  5. In the Actions menu, click Cancel Deletion.
  6. Confirm that you want to cancel the key's deletion by clicking Cancel Deletion. Access to the key and any resources or data encrypted by the key are restored when key returns to an enabled state.
To move a key to a different compartment
  1. Open the navigation menu. Under the Governance and Administration group, go to Security and click Vault.
  2. Under Scope, in the Compartment list, choose the compartment that contains the vault that has the master encryption key that you want to move.
  3. From the list of vaults in the compartment, click the vault name.

  4. Click Master Encryption Keys. Find the key in the list, click the the Actions icon (three dots), and then click Move Resource. (If needed, first change the list scope to the compartment that contains the key.)
  5. Choose the destination compartment from the list.
  6. Click Move Resource.
  7. If there are alarms monitoring the key, update the alarms to reference the new compartment. See To update an alarm after moving a resource for more information.

Using the Command Line Interface (CLI)

For information about using the CLI, see Command Line Interface (CLI). For a complete list of flags and options available for CLI commands, see the Command Line Reference.

Tip

Each vault has a unique endpoint for create, update, and list operations for keys. This endpoint is referred to as the control plane URL or management endpoint. Each vault also has a unique endpoint for cryptographic operations. This endpoint is known as the data plane URL or the cryptographic endpoint. When using the CLI for key operations, you must provide the appropriate endpoint for the type of operation. To retrieve a vault's endpoints, see instructions in To view vault configuration details.
To create a new key

Open a command prompt and run oci kms management key create to create a new key:

Warning

Avoid entering confidential information in the key name.
oci kms management key create --compartment-id <target_compartment_id> --display-name <key_name> --key-shape <key_encryption_information> --endpoint <control_plane_url>

For example, on a MacOS or Linux machine:


oci kms management key create --compartment-id ocid1.compartment.oc1..example1example25qrlpo4agcmothkbgqgmuz2zzum45ibplooqtabwk3zz --display-name key-1 --key-shape '{"algorithm":"AES","length":"16"}' --endpoint https://exampleaaacu2-management.kms.us-ashburn-1.oraclecloud.com

Or, for example, on a Windows machine:


oci kms management key create --compartment-id ocid1.compartment.oc1..example1example25qrlpo4agcmothkbgqgmuz2zzum45ibplooqtabwk3zz --display-name key-1 --key-shape '{\"algorithm\":\"AES\",\"length\":\"16\"}' --endpoint https://exampleaaacu2-management.kms.us-ashburn-1.oraclecloud.com

By default, the service creates a master encryption key protected by an HSM. If you prefer to create a master encryption key protected by software, specify the protection mode with --protection-mode. For example, on a Windows machine:


oci kms management key create --compartment-id ocid1.compartment.oc1..example1example25qrlpo4agcmothkbgqgmuz2zzum45ibplooqtabwk3zz --display-name key-1 --key-shape '{\"algorithm\":\"AES\",\"length\":\"16\"}' --protection-mode SOFTWARE --endpoint https://exampleaaacu2-management.kms.us-ashburn-1.oraclecloud.com
To create a new key with resource tags

Open a command prompt and run oci kms management key create with one or both of the --defined-tags and --freeform-tags options to create a new key with resource tags:

oci kms management key create --compartment-id <target_compartment_id> --display-name <key_name> --key-shape <JSON_formatted_key_encryption_information> --defined-tags <JSON_formatted_defined_tag> --freeform-tags <JSON_formatted_freeform_tag> --endpoint <control_plane_url>

For example, on a MacOS or Linux machine:


oci kms management key create --compartment-id ocid1.compartment.oc1..example1example25qrlpo4agcmothkbgqgmuz2zzum45ibplooqtabwk3zz --display-name key-1 --key-shape '{"algorithm":"AES","length":"16"}' --defined-tags '{"Operations": {"CostCenter":"42"}}' --freeform-tags '{"Department":"Finance"}' --endpoint https://exampleaaacu2-management.kms.us-ashburn-1.oraclecloud.com

Or, for example, on a Windows machine:


oci kms management key create --compartment-id ocid1.compartment.oc1..example1example25qrlpo4agcmothkbgqgmuz2zzum45ibplooqtabwk3zz --display-name key-1 --key-shape '{\"algorithm\":\"AES\",\"length\":\"16\"}' --defined-tags '{\"Operations\": {\"CostCenter\":\"42\"}}' --freeform-tags '{\"Department\":\"Finance\"}' --endpoint https://exampleaaacu2-management.kms.us-ashburn-1.oraclecloud.com
Warning

Avoid entering confidential information in the key name.
To view a key's details

Open a command prompt and run oci kms management key get to view a specific key's details:

oci kms management key get --key-id <key_OCID> --endpoint <control_plane_url>

For example:


oci kms management key get --key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --endpoint https://exampleaaacu2-management.kms.us-ashburn-1.oraclecloud.com
To view a list of keys

Open a command prompt and run oci kms management key list to list keys in a vault:

oci kms management key list --compartment-id <target_compartment_id> --endpoint <control_plane_url>

For example:


oci kms management key list --compartment-id ocid1.compartment.oc1..example1example25qrlpo4agcmothkbgqgmuz2zzum45ibplooqtabwk3zz --endpoint https://exampleaaacu2-management.kms.us-ashburn-1.oraclecloud.com
To view a list of key versions

Open a command prompt and run oci kms management key-version list to view a list of key versions for a specific key:

oci kms management key-version list --key-id <key_OCID> --endpoint <control_plane_url>

For example:


oci kms management key-version list --key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --endpoint https://exampleaaacu2-management.kms.us-ashburn-1.oraclecloud.com
To change the name of a key

Open a command prompt and run oci kms management key update to edit a key's name.

Warning

Avoid entering confidential information in the key name.
oci kms management key update --key-id <key_OCID> --display-name <new_key_name> --endpoint <control_plane_url>

For example:


oci kms management key update --key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --display-name key-A --endpoint https://exampleaaacu2-management.kms.us-ashburn-1.oraclecloud.com
To enable a key

Open a command prompt and run oci kms management key enable to enable a key:

oci kms management key enable --key-id <target_key_id> --endpoint <control_plane_url>

For example:


oci kms management key enable --key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --endpoint https://exampleaaacu2-management.kms.us-ashburn-1.oraclecloud.com
To rotate a key

Open a command prompt and run oci kms management key rotate to rotate a key:

oci kms management key rotate --key-id <target_key_id> --endpoint <control_plane_url>

For example:


oci kms management key rotate --key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --endpoint https://exampleaaacu2-management.kms.us-ashburn-1.oraclecloud.com	

Cryptographic operations involving objects that were encrypted with the previous version of this key will continue to use the older key version. You can re-encrypt those objects with the current key version if you prefer.

To disable a key

Open a command prompt and run oci kms management key disable to disable a key:

oci kms management key disable --key-id <target_key_id> --endpoint <control_plane_url>

For example:


oci kms management key disable --key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --endpoint https://exampleaaacu2-management.kms.us-ashburn-1.oraclecloud.com
To delete a key
Warning

When you set a key to the Pending Deletion state, anything encrypted by that key immediately becomes inaccessible. This includes secrets. The key also cannot be assigned or unassigned to any resources or otherwise updated. When the key is deleted, all key material and metadata is irreversibly destroyed. Before you delete a key, either assign a new key to resources currently encrypted by the key or preserve your data another way. If you want to restore use of a key before it is permanently deleted, you can cancel its deletion.

Open a command prompt and run oci kms management key schedule-deletion to schedule a key's deletion:

oci kms management key schedule-deletion --key-id <target_key_id> --endpoint <control_plane_url>

For example:


oci kms management key schedule-deletion --key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --endpoint https://exampleaaacu2-management.kms.us-ashburn-1.oraclecloud.com

By default, the service schedules keys for deletion 30 days from the current date and time. You can set a range between 7 days and 30 days. For example:


oci kms management key schedule-deletion --key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --time-of-deletion 2019-06-30T10:00:00Z --endpoint https://exampleaaacu2-management.kms.us-ashburn-1.oraclecloud.com
To cancel the deletion of a key
Tip

You can only cancel the deletion of a key that's in a Pending Deletion state.

Open a command prompt and run oci kms management key cancel-deletion to cancel a key's scheduled deletion:

oci kms management key cancel-deletion --key-id <target_key_id> --endpoint <control_plane_url>

For example:


oci kms management key cancel-deletion --key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --endpoint https://exampleaaacu2-management.kms.us-ashburn-1.oraclecloud.com
To move a key to a different compartment

Open a command prompt and run oci kms management key change-compartment to move a master encryption key from one compartment to another within the same tenancy:

oci kms management key change-compartment --key-id <target_key_id> --compartment-id <new_compartment_id>

For example:


oci kms management key change-compartment --key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --compartment-id ocid1.compartment.oc1..example1example25qrlpo4agcmothkbgqgmuz2zzum45ibplooqtabwk3zz