Using Your Own Keys for Server-Side Encryption

The Oracle Cloud Infrastructure Object Storage service encrypts and decrypts all objects using 256-bit AES encryption. By default, Object Storage service manages the master encryption key used to encrypt each object's encryption keys.

You can alternatively employ one of these encryption strategies:

  • You can assign a key that you created and control through the Oracle Cloud Infrastructure Vault service. See Overview of Vault for details.
  • You can encrypt objects using your own encryption key. The key you supply is known as a customer-provided encryption key.

This topic provides the details for implementing and using server-side encryption with customer-provided keys (SSE-C).

About SSE-C

Using optional API headers, you can provide your own 256-bit AES encryption key that is used to encrypt and decrypt objects uploaded to and downloaded from Object Storage:

  • When you upload an object, you supply the encryption key. Object Storage encrypts the object using that key and immediately deletes the key.
  • When you want to download an object, you supply the same key that was used to encrypt the object and Object Storage decrypts and returns the object to you.

You manage the encryption keys and Object Storage manages the encryption and decryption.

Important

Object Storage does not store your encryption keys. You are responsible for tracking the key that is associated with each object and rotating the key as necessary. If you lose your encryption key, you cannot retrieve your object.

Scope and Constraints

Understand the following scope and constraints regarding SSE-C:

  • An SSE-C key cannot be associated with a bucket and can only be used to encrypt individual objects.
  • You can encrypt objects using your own encryption key using pre-authenticated requests. To retrieve an SSE-C encrypted object using a pre-authenticated request, you need to specify your encryption key.
  • To delete or rename an SSE-C encrypted object, you do not need to specify your encryption key.
  • You can only specify either a kmsKeyId or an sseCustomerKey in the ReencryptObject request payload, not both. If the request payload is empty, the object is encrypted using the encryption key assigned to the bucket. The bucket encryption mechanism can either be a master encryption key managed by Oracle or the Vault service.
  • You can only use the Object Storage APIs and the CLI to provide SSE-C keys. You can't use the Console to upload or retrieve objects using a customer-provided key.
  • The Amazon S3 Compatibility API also supports SSE-C.

Using SSE-C

If you want to use your own keys for server-side encryption, specify the following three request headers with the encryption key information:

Headers Description APIs Supported
opc-sse-customer-algorithm Specifies "AES256" as the encryption algorithm. CopyObject

GetObject

HeadObject

PutObject

CreateMultipartUpload

UploadPart

opc-sse-customer-key Specifies the base64-encoded 256-bit encryption key to use to encrypt or decrypt the data.
opc-sse-customer-key-sha256 Specifies the base64-encoded SHA256 hash of the encryption key.

For CopyObject:

If the source object is encrypted with an SSE-C key, you must also specify the following three headers so that Object Storage can decrypt the object.

Headers Description APIs Supported
opc-source-sse-customer-algorithm Specifies "AES256" as the encryption algorithm to use to decrypt the source object. CopyObject
opc-source-sse-customer-key Specifies the base64-encoded 256-bit encryption key to use to decrypt the source object.
opc-source-sse-customer-key-sha256 Specifies the base64-encoded SHA256 hash of the encryption key used to decrypt the source object.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be granted security access in a policy  by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, verify with your administrator what type of access you have and which compartment  you should work in.

If you are new to policies, see Getting Started with Policies and Common Policies. For more information about Object Storage-specific policies, see Details for Object Storage, Archive Storage, and Data Transfer.

Using the CLI

You can also use your own encryption keys to encrypt objects using the CLI.

You can supply the optional parameter --encryption-key-file <filename> for the following commands:

  • oci os object put
  • oci os object get
  • oci os object head
  • oci os object resume-put
  • oci os object bulk-upload
  • oci os object bulk-download
  • oci os object copy
  • oci os object reencrypt

<filename> points to a file containing the base64-encoded string of the AES-256 encryption key. No other parameters are required. Object Storage decodes the key to compute the SHA256 hash of the encryption key.

If the source object is encrypted with an SSE-C key, you must also specify the optional parameter --source-encryption-key-file <filename> for the following commands:

  • oci os object copy
  • oci os object reencrypt

<filename> points to a file containing the base64-encoded string of the AES-256 source encryption key. No other parameters are required. Object Storage decodes the key to compute the SHA256 hash of the source encryption key.

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.