Oracle Cloud Infrastructure Documentation

Rotating a Key

Learn how to rotate a key by creating a new key version.

When you create a new key version of a master encryption key, the KMS service rotates the key version in use for the key. The service can generate the key material for the new key version, or you can import your own key material. When importing a key you must use a wrapping key to wrap the key material. However, you can't create, delete or rotate a wrapping key. For more information about key rotation, see Key Versions & Rotations in the the Key and Secret Management Concepts topic.

Automatic Key Rotation

For keys created in virtual private vaults, you can enable automatic key rotation. See the Automatic Key Rotation section of the Key and Secret Management Concepts topic for details. This option can be enabled during key creation, or enabled after a key is created. See Enabling and Updating Auto Key Rotation for instructions on updating auto-rotation settings, and Creating a Master Encryption Key for instructions on creating a new key with automatic rotation enabled.

Manual Key Rotation

Use the instructions in the following sections to manually rotate a key using the Console, CLI, or API.

    1. On the Master Encryption Keys list page, find the key that you want to work with. If you need help finding the list page, see Listing Keys.
    2. In the key list, select Actions menu Actions Menu and then select Rotate key.
    3. In the Confirm dialog box, enable Import External key version to import the key materials and key versions and allow Key Management Service to use a copy of it.
    4. Select Rotate Key.
      Note

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

  • use the oci kms management key-version create command and required parameters to rotate a key.

    oci kms management key-version create --key-id <target_key_id> --endpoint <kmsmanagement_endpoint> [OPTIONS]

    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.

    For a complete list of parameters and values for CLI commands, see the CLI Command Reference.

  • Use the CreateKeyVersion API with the Management Endpoint to rotate a master encryption key.

    Note

    The Management Endpoint is used for management operations including Create, Update, List, Get, and Delete. The Management Endpoint is also called the control plane URL or the KMSMANAGEMENT endpoint.

    The Cryptographic Endpoint is used for cryptographic operations including Encrypt, Decrypt, Generate Data Encryption Key, Sign, and Verify. The Cryptographic Endpoint is also called the data plane URL or the KMSCRYPTO endpoint.

    You can find the management and cryptographic endpoints in a vault's details metadata. See Getting a Vault's Details for instructions.

    For regional endpoints for the Key Management, Secret Management, and Secret Retrieval APIs, see API Reference and Endpoints.

    For information about using the API and signing requests, see REST API documentation and Security Credentials. For information about SDKs, see SDKs and the CLI.