Assigning 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 how to assign keys to supported resources and how to remove those key assignments when no longer needed.

You can assign master encryption keys to block or boot volumes, file systems, buckets, and stream pools. Block Volume, File Storage, Object Storage, and Streaming use the keys to decrypt the data encryption keys that protect the data that is stored by each respective service. By default, these services rely on Oracle-managed master encryption keys for cryptographic operations. When you remove a Vault master encryption key assignment from a resource, the service returns to using an Oracle-managed key for encryption, decryption, and generating data encryption keys.

You can also assign master encryption keys to clusters that you create using Container Engine for Kubernetes to encrypt Kubernetes secrets at rest in the etcd key-value store.

For information about managing the creation and usage of master encryption keys and key versions, see Managing Keys. For information specifically about creating keys with your own key material, see Importing Keys and Key Versions. For information about how you can use keys in cryptographic operations, see Using Keys. For information about what you can do with vaults where you store keys, see Managing Vaults.

Required IAM Policy

Warning

Keys associated with volumes, buckets, file systems, clusters, and stream pools will not work unless you authorize Block Volume, Object Storage, File Storage, Container Engine for Kubernetes, and Streaming to use keys on your behalf. Additionally, you must also authorize users to delegate key usage to these services in the first place. For more information, see Let a user group delegate key usage in a compartment and Let Block Volume, Object Storage, File Storage, Container Engine for Kubernetes, and Streaming services encrypt and decrypt volumes, volume backups, buckets, file systems, Kubernetes secrets, and stream pools in Common Policies.

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.

Using the Console

To assign a key to a new Object Storage bucket
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Under List Scope, in the Compartment list, choose the compartment where you want to create a bucket that's encrypted with a Vault service master encryption key.
  3. Click Create Bucket, and then follow the instructions in To create a bucket in Managing Buckets.

To assign a key to an existing Object Storage bucket
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Under List Scope, in the Compartment list, choose the compartment that contains the bucket that you want to encrypt with a Vault service master encryption key.
  3. From the list of buckets, click the bucket name.

  4. Do one of the following:

    • If the bucket already has a key assigned to it, next to Encryption Key, click Edit to assign a different key.
    • If the bucket does not already have a key assigned to it, next to Encryption Key, click Assign.
  5. Choose the vault compartment, vault, key compartment, and key.

  6. When you are finished, click Assign or Update, as appropriate.

To assign a key to a new Block Volume
  1. Open the navigation menu. Under Core Infrastructure, go to Block Storage and click Block Volumes.
  2. Under List Scope, in the Compartment list, choose the compartment where you want to create a block volume that's encrypted with a Vault service master encryption key.
  3. Click Create Block Volume, and then follow the instructions in Creating a Volume.

To assign a key to an existing Block Volume
  1. Open the navigation menu. Under Core Infrastructure, go to Block Storage and click Block Volumes.
  2. Under List Scope, in the Compartment list, choose the compartment that contains the block volume that you want to encrypt with a Vault service master encryption key.
  3. From the list of volumes, click the volume name.
  4. If the volume is currently attached to an instance, click Detach from Instance. Follow the instructions in the Detach Block Volume dialog box as appropriate, click Continue Detachment, and then click OK.
  5. Then, do one of the following:

    • If the volume already has a key assigned to it, next to Encryption Key, click Edit to assign a different key.
    • If the volume does not already have a key assigned to it, next to Encryption Key, click Assign.
  6. Choose the vault compartment, vault, key compartment, and key.

  7. When you are finished, click Assign or Update, as appropriate.

To assign a key to a new file system
  1. Open the navigation menu. Under Core Infrastructure, click File Storage and then click File Systems.
  2. Under List Scope, in the Compartment list, choose the compartment where you want to create a file system that's encrypted with a Vault service master encryption key.
  3. Click Create File System, and then follow the instructions in Creating File Systems.

To create a Compute instance with an encrypted boot volume
  1. Open the navigation menu. Under Core Infrastructure, go to Compute and click Instances.
  2. Under List Scope, in the Compartment list, choose the compartment where you want to create an instance with a boot volume that's encrypted with a Vault service master encryption key.
  3. Click Create Instance, and then follow the instructions in Launching an Instance.

To assign a key to an existing boot volume
Note

To assign a key to an existing boot volume, you must first detach the boot volume from any instance. However, you can only detach a boot volume from an instance when the instance is stopped. For more information, see Detaching a Boot Volume and Stopping and Starting an Instance.
  1. Open the navigation menu. Under Core Infrastructure, go to Compute and click Boot Volumes.
  2. Under List Scope, in the Compartment list, choose the compartment that contains the boot volume that you want to encrypt with a Vault service master encryption key.
  3. From the list of volumes, click the volume name.
  4. Do one of the following:

    • If the volume already has a key assigned to it, next to Encryption Key, click Edit to assign a different key.
    • If the volume does not already have a key assigned to it, next to Encryption Key, click Assign.
  5. Choose the vault compartment, vault, key compartment, and key.

  6. When you are finished, click Assign or Update, as appropriate.

To create a Kubernetes cluster with encrypted secrets in the etcd key-value store
Note

These instructions assume you have already followed the steps in Encrypting Kubernetes Secrets at Rest in Etcd and created:

  • a dynamic group including all clusters in the compartment
  • a suitable policy to give the dynamic group access to the master encryption key in Vault
  1. Open the navigation menu. Under Solutions and Platform, go to Developer Services and click Container Clusters.

  2. Under List Scope, in the Compartment list, choose the compartment where you want to create a Kubernetes cluster that has Kubernetes secrets encrypted with a Vault service master encryption key.
  3. Click Create Cluster, follow the instructions under Using the Console to create a 'Custom Cluster' with Explicitly Defined Settings in Creating a Kubernetes Cluster, and select the Encrypt Using Customer-Managed Keys option.

To assign a key to a new stream pool
  1. Open the navigation menu. Under Solutions and Platform, click Analytics, and then click Streaming.
  2. Under List Scope, in the Compartment list, choose the compartment where you want to create a stream pool that's encrypted with a Vault service master encryption key.
  3. Click Create Stream Pool, and then follow the instructions in To create a stream pool in Managing Stream Pools.

To change or remove the master encryption key assigned to an existing stream pool
  1. Open the navigation menu. Under Solutions and Platform, click Analytics, and then click Streaming.

  2. Click Stream Pools.
  3. Click a stream pool to display the stream details page.
  4. In Stream Pool Information, next to Encryption Key, do one of the following:
    • To stop using an Oracle-managed key in favor of a Vault master encryption key that you manage, click Assign, select a vault and encryption key you have access to, and then click Assign.
    • To select a different Vault master encryption key that you manage, click Edit, select a vault and encryption key you have access to, and then click Update.
    • Click Unassign to remove the assigned Vault master encryption key and let Oracle manage the encryption key, and then click Unassign again to confirm the removal of the existing key assignment.
To remove a key assignment from a bucket
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Under List Scope, in the Compartment list, choose the compartment that contains the bucket from which you want to remove a Vault service key assignment.
  3. From the list of buckets, click the bucket name.
  4. Next to Encryption Key, click Unassign.

  5. In the Confirm dialog box, click OK to remove the key assignment from the bucket.

To remove a key assignment from a Block Volume
  1. Open the navigation menu. Under Core Infrastructure, go to Block Storage and click Block Volumes.
  2. Under List Scope, in the Compartment list, choose the compartment that contains the block volume from which you want to remove a Vault service key assignment.
  3. From the list of volumes, click the volume name.
  4. Next to Encryption Key, click Unassign.

  5. In the Confirm dialog box, click OK to remove the key assignment from the volume.

To remove a key assignment from a boot volume
  1. Open the navigation menu. Under Core Infrastructure, go to Compute and click Boot Volumes.
  2. Under List Scope, in the Compartment list, choose the compartment that contains the boot volume from which you want to remove a Vault service key assignment.
  3. From the list of volumes, click the volume name.
  4. Next to Encryption Key, click Unassign.

  5. In the Confirm dialog box, click OK to remove the key assignment from the volume.

To change a key assignment for a file system
  1. Open the navigation menu. Under Core Infrastructure, click File Storage and then click File Systems.
  2. Under List Scope, in the Compartment list, choose the compartment that contains the file system from which you want to remove or change a Vault service key assignment.
  3. From the list of file systems, click the file system name.
  4. Next to Encryption Key, click Edit.

  5. If you want to use Oracle-managed keys:

    • In Encryption Type, select Encrypt using Oracle-managed keys.
  6. If you want to assign a different customer-managed key: 

    • In Encryption Type, select Encrypt using customer-manged keys.
    • Choose the vault compartment, vault, key compartment, and key.
  7. When you are finished, click Save Changes.

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 assign a key to an Object Storage bucket

Open a command prompt and run oci os bucket create to create a bucket that is encrypted with a Vault service master encryption key:

oci os bucket create --name <bucket_name> --compartment-id <target_compartment_id> --kms-key-id <target_key_id>

For example:


oci os bucket create --name Bucket-1 --compartment-id ocid1.compartment.oc1..example1example25qrlpo4agcmothkbgqgmuz2zzum45ibplooqtabwk3zz --kms-key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --namespace-name example_namespace
Warning

Avoid entering confidential information in the bucket name.
To update the key assigned to an Object Storage bucket

Open a command prompt and run oci os bucket update to update the Vault service master encryption key assigned to a bucket:

oci os bucket update --name <bucket_name> --namespace-name <your_namespace> --kms-key-id <target_key_id>

For example:


oci os bucket update --name Bucket-1 --namespace-name example_namespace --kms-key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq
To create a block volume that's encrypted with a Vault key

Open a command prompt and run oci bv volume create to create a block volume that is encrypted with a Vault service master encryption key:

oci bv volume create --display-name <volume_name> --compartment-id <target_compartment_id> --size-in-gbs <volume_size> --availability-domain <target_availability_domain> --kms-key-id <target_key_id>

For example:


oci bv volume create --display-name EncryptedBlockVolume --compartment-id ocid1.compartment.oc1..example1example25qrlpo4agcmothkbgqgmuz2zzum45ibplooqtabwk3zz --size-in-gbs 50 --availability-domain AAbC:US-ASHBURN-AD-1 --kms-key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq
Warning

Avoid entering confidential information in the volume name.
To update a key assigned to an existing Block Volume
Tip

If the volume is currently attached to an instance, you must first detach it. To do so, open a command prompt and run oci compute volume-attachment detach --volume-attachment-id <target_blockvolume-attachment_id>. For more information, see Oracle Cloud Infrastructure CLI Command Reference.

Open a command prompt and run oci bv volume-kms-key update to assign a new Vault service master encryption key to an existing block volume:

oci bv volume-kms-key update --volume-id <target_blockvolume_id> --kms-key-id <new_key_id>

For example:


oci bv volume-kms-key update --volume-id ocid1.volume.oc1.sea.examplerwzq7bnohn5vf6b7k4zkp54miqfcvg6xsuvkllgzzw63mfuu6z5fa --kms-key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq
To create a boot volume that's encrypted with a Vault key

Open a command prompt and run oci bv boot-volume create to create a boot volume that is encrypted with a Vault service master encryption key:

oci bv boot-volume create --display-name <volume_name> --compartment-id <target_compartment_id> --size-in-gbs <volume_size> --availability-domain <target_availability_domain> --kms-key-id <target_key_id>

For example:


oci bv boot-volume create --display-name EncryptedBlockVolume --compartment-id ocid1.compartment.oc1..example1example25qrlpo4agcmothkbgqgmuz2zzum45ibplooqtabwk3zz --size-in-gbs 50 --availability-domain AAbC:US-ASHBURN-AD-1 --kms-key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq
Warning

Avoid entering confidential information in the volume name.
To create a Compute instance with a boot volume that's encrypted with a Vault key
  1. First, create the JSON input for configuring the instance and boot volume: Open a command prompt and run oci compute instance launch --generate-full-command-json-input.
  2. Copy, and then paste the output from the command into a text file for editing. Edit the JSON to provide values appropriate for your tenancy and desired image operating system and instance shape. The following example shows the minimum settings required to create an instance and encrypted boot volume.

    {
    "availabilityDomain": "ABcD:US-ASHBURN-AD-1",
    "compartmentId": "ocid1.tenancy.oc1..examplea54hlbsiugecvb4g67tnth7ouk4iivkpysfauxcetd55uiunrykhq",
    "displayName": "InstanceWithEncryptedBootVolume",
    "metadata": {
    },
    "shape": "VM.Standard1.1",
    "subnetId": "ocid1.subnet.oc1.iad.exampleaurihk3x3yl2vcvb53uz22zgauoujtcwvtbxvfauxdvsjmdfv4dza",
    "sourceDetails": {
       "sourceType": "image",
       "imageId": "ocid1.image.oc1.iad.exampleaeookczfwutjxzcvb2gcdgdx4yk6xls7d5fhtlfauxzpaxdedny4a",
       "kmsKeyId": "ocid1.key.oc1.iad.exampleoaaeug.examplera4soq2vescvbjmwredhewtto7rlfauxhvme73y7jayxx6rpaenlq"
       }
    }
    Warning

    Avoid entering confidential information in the instance name.
  3. Save the file with a ".json" file extension.
  4. In the command prompt, run oci compute instance launch --from-json file://<file_path>, providing the location of the file you saved in the previous step. For example:

    oci compute instance launch --from-json file://c:\temp\compute-boot-volume.json
To update a key assigned to an existing boot volume
Tip

If the volume is currently attached to an instance, you must first detach the volume. To do so, you must first stop the instance. To stop an instance, open a command prompt and run oci compute instance action --instance-id <target_instance_id> --action STOP. Then, to detach the boot volume, run oci compute boot-volume-attachment detach --boot-volume-attachment-id <target_bootvolume-attachment_id>. For more information, see the Oracle Cloud Infrastructure CLI Command Reference.

Open a command prompt and run oci bv boot-volume-kms-key update to assign a new Vault service master encryption key to an existing boot volume:

oci bv boot-volume-kms-key update --boot-volume-id <target_bootvolume_id> --kms-key-id <new_key_id>

For example:


oci bv boot-volume-kms-key update --boot-volume-id ocid1.bootvolume.oc1.sea.exampless6hvjs6j6mqwcdv4gfzhtanon3fsqyviqeh522be6wv7x7abz7pq --kms-key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq
To create a Kubernetes cluster with encrypted secrets in the etcd key-value store
Note

These instructions assume you have already followed the steps in Encrypting Kubernetes Secrets at Rest in Etcd and created:

  • a dynamic group including all clusters in the compartment
  • a suitable policy to give the dynamic group access to the master encryption key in Vault

Open a command prompt and run oci ce cluster create to create a cluster where Kubernetes secrets at rest in the etcd data-store are encrypted with a Vault service master encryption key:

oci ce cluster create --name <cluster_name> --compartment-id <target_compartment_id> --vcn-id <target_vcn_id> --kubernetes-version <kubernetes_version> --kms-key-id <target_key_id>

For example:


oci ce cluster create --name EncryptedCluster --compartment-id ocid1.compartment.oc1..example1example25qrlpo4agcmothkbgqgmuz2zzum45ibplooqtabwk3zz --vcn-id ocid1.vcn.oc1.iad.exampleexamplesgwertshsdgfy2muagjhrcmzhtp6c5fplejt3miqvyja --kubernetes-version v1.14.8 --kms-key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq
Warning

Avoid entering confidential information in the cluster name.
To remove the key assigned to an Object Storage bucket

Open a command prompt and run oci os bucket update to remove the Vault service master encryption key assigned to a bucket:

oci os bucket update --name <bucket_name> --namespace-name <your_namespace> --kms-key-id ""

For example:


oci os bucket update --name Bucket-1 --kms-key-id "" --namespace-name example_namespace
To remove a key assigned to a Block Volume

Open a command prompt and run oci bv volume-kms-key delete to remove the Vault service master encryption key assigned to an existing block volume:

oci bv volume-kms-key delete --volume-id <target_blockvolume_id>

For example:


oci bv volume-kms-key delete --volume-id ocid1.volume.oc1.sea.examplerwzq7bnohn5vf6b7k4zkp54miqfcvg6xsuvkllgzzw63mfuu6z5fa
To remove a key assigned to a Block Volume boot volume

Open a command prompt and run oci bv boot-volume-kms-key delete to remove the Vault service master encryption key assigned to an existing boot volume:

oci bv boot-volume-kms-key delete --boot-volume-id <target_bootvolume_id>

For example:


oci bv boot-volume-kms-key delete --boot-volume-id ocid1.bootvolume.oc1.sea.exampless6hvjs6j6mqwcdv4gfzhtanon3fsqyviqeh522be6wv7x7abz7pq

Using the API

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.

Use the following operations to assign keys:

Container Engine for Kubernetes

Core Services

File Storage

Object Storage

Streaming