Module: Aws::S3::EncryptionV2

Defined in:
lib/aws-sdk-s3/encryptionV2/client.rb,
lib/aws-sdk-s3/encryption_v2.rb,
lib/aws-sdk-s3/encryptionV2/utils.rb,
lib/aws-sdk-s3/encryptionV2/errors.rb,
lib/aws-sdk-s3/encryptionV2/materials.rb,
lib/aws-sdk-s3/encryptionV2/io_decrypter.rb,
lib/aws-sdk-s3/encryptionV2/io_encrypter.rb,
lib/aws-sdk-s3/encryptionV2/key_provider.rb,
lib/aws-sdk-s3/encryptionV2/decrypt_handler.rb,
lib/aws-sdk-s3/encryptionV2/encrypt_handler.rb,
lib/aws-sdk-s3/encryptionV2/io_auth_decrypter.rb,
lib/aws-sdk-s3/encryptionV2/kms_cipher_provider.rb,
lib/aws-sdk-s3/encryptionV2/default_key_provider.rb,
lib/aws-sdk-s3/encryptionV2/default_cipher_provider.rb

Overview

Provides an encryption client that encrypts and decrypts data client-side, storing the encrypted data in Amazon S3. The ‘EncryptionV2::Client` (V2 Client) provides improved security over the `Encryption::Client` (V1 Client) by using more modern and secure algorithms. You can use the V2 Client to continue decrypting objects encrypted using deprecated algorithms by setting security_profile: :v2_and_legacy. The latest V1 Client also supports reading and decrypting objects encrypted by the V2 Client.

This client uses a process called “envelope encryption”. Your private encryption keys and your data’s plain-text are never sent to Amazon S3. **If you lose you encryption keys, you will not be able to decrypt your data.**

## Envelope Encryption Overview

The goal of envelope encryption is to combine the performance of fast symmetric encryption while maintaining the secure key management that asymmetric keys provide.

A one-time-use symmetric key (envelope key) is generated client-side. This is used to encrypt the data client-side. This key is then encrypted by your master key and stored alongside your data in Amazon S3.

When accessing your encrypted data with the encryption client, the encrypted envelope key is retrieved and decrypted client-side with your master key. The envelope key is then used to decrypt the data client-side.

One of the benefits of envelope encryption is that if your master key is compromised, you have the option of just re-encrypting the stored envelope symmetric keys, instead of re-encrypting all of the data in your account.

## Basic Usage

The encryption client requires an Client. If you do not provide a ‘:client`, then a client will be constructed for you.

require 'openssl'
key = OpenSSL::PKey::RSA.new(1024)

# encryption client
s3 = Aws::S3::EncryptionV2::Client.new(
  encryption_key: key,
  key_wrap_schema: :rsa_oaep_sha1, # the key_wrap_schema must be rsa_oaep_sha1 for asymmetric keys
  content_encryption_schema: :aes_gcm_no_padding,
  security_profile: :v2 # use :v2_and_legacy to allow reading/decrypting objects encrypted by the V1 encryption client
)

# round-trip an object, encrypted/decrypted locally
s3.put_object(bucket:'aws-sdk', key:'secret', body:'handshake')
s3.get_object(bucket:'aws-sdk', key:'secret').body.read
#=> 'handshake'

# reading encrypted object without the encryption client
# results in the getting the cipher text
Aws::S3::Client.new.get_object(bucket:'aws-sdk', key:'secret').body.read
#=> "... cipher text ..."

## Required Configuration

You must configure all of the following:

  • a key or key provider - See the Keys section below. The key provided determines the key wrapping schema(s) supported for both encryption and decryption.

  • ‘key_wrap_schema` - The key wrapping schema. It must match the type of key configured.

  • ‘content_encryption_schema` - The only supported value currently is `:aes_gcm_no_padding`.

    More options will be added in future releases.

  • ‘security_profile` - Determines the support for reading objects written

    using older key wrap or content encryption schemas. If you need to read
legacy objects encrypted by an existing V1 Client, then set this to `:v2_and_legacy`.
Otherwise, set it to `:v2`

## Keys

For client-side encryption to work, you must provide one of the following:

  • An encryption key

  • A KeyProvider

  • A KMS encryption key id

Additionally, the key wrapping schema must agree with the type of the key:

  • :aes_gcm: An AES encryption key or a key provider.

  • :rsa_oaep_sha1: An RSA encryption key or key provider.

  • :kms_context: A KMS encryption key id

### An Encryption Key

You can pass a single encryption key. This is used as a master key encrypting and decrypting all object keys.

key = OpenSSL::Cipher.new("AES-256-ECB").random_key # symmetric key - used with `key_wrap_schema: :aes_gcm`
key = OpenSSL::PKey::RSA.new(1024) # asymmetric key pair - used with `key_wrap_schema: :rsa_oaep_sha1`

s3 = Aws::S3::EncryptionV2::Client.new(
  encryption_key: key,
  key_wrap_schema: :aes_gcm, # or :rsa_oaep_sha1 if using RSA
  content_encryption_schema: :aes_gcm_no_padding,
  security_profile: :v2
)

### Key Provider

Alternatively, you can use a KeyProvider. A key provider makes it easy to work with multiple keys and simplifies key rotation.

### KMS Encryption Key Id

If you pass the id of an AWS Key Management Service (KMS) key and use :kms_content for the key_wrap_schema, then KMS will be used to generate, encrypt and decrypt object keys.

# keep track of the kms key id
kms = Aws::KMS::Client.new
key_id = kms.create_key.key_metadata.key_id

Aws::S3::EncryptionV2::Client.new(
  kms_key_id: key_id,
  kms_client: kms,
  key_wrap_schema: :kms_context,
  content_encryption_schema: :aes_gcm_no_padding,
  security_profile: :v2
)

## Custom Key Providers

A KeyProvider is any object that responds to:

  • ‘#encryption_materials`

  • ‘#key_for(materials_description)`

Here is a trivial implementation of an in-memory key provider. This is provided as a demonstration of the key provider interface, and should not be used in production:

class KeyProvider

  def initialize(default_key_name, keys)
    @keys = keys
    @encryption_materials = Aws::S3::EncryptionV2::Materials.new(
      key: @keys[default_key_name],
      description: JSON.dump(key: default_key_name),
    )
  end

  attr_reader :encryption_materials

  def key_for(matdesc)
    key_name = JSON.parse(matdesc)['key']
    if key = @keys[key_name]
      key
    else
      raise "encryption key not found for: #{matdesc.inspect}"
    end
  end
end

Given the above key provider, you can create an encryption client that chooses the key to use based on the materials description stored with the encrypted object. This makes it possible to use multiple keys and simplifies key rotation.

# uses "new-key" for encrypting objects, uses either for decrypting
keys = KeyProvider.new('new-key', {
  "old-key" => Base64.decode64("kM5UVbhE/4rtMZJfsadYEdm2vaKFsmV2f5+URSeUCV4="),
  "new-key" => Base64.decode64("w1WLio3agRWRTSJK/Ouh8NHoqRQ6fn5WbSXDTHjXMSo="),
}),

# chooses the key based on the materials description stored
# with the encrypted object
s3 = Aws::S3::EncryptionV2::Client.new(
  key_provider: keys,
  key_wrap_schema: ...,
  content_encryption_schema: :aes_gcm_no_padding,
  security_profile: :v2
)

## Materials Description

A materials description is JSON document string that is stored in the metadata (or instruction file) of an encrypted object. The DefaultKeyProvider uses the empty JSON document ‘“{}”`.

When building a key provider, you are free to store whatever information you need to identify the master key that was used to encrypt the object.

## Envelope Location

By default, the encryption client store the encryption envelope with the object, as metadata. You can choose to have the envelope stored in a separate “instruction file”. An instruction file is an object, with the key of the encrypted object, suffixed with ‘“.instruction”`.

Specify the ‘:envelope_location` option as `:instruction_file` to use an instruction file for storing the envelope.

# default behavior
s3 = Aws::S3::EncryptionV2::Client.new(
  key_provider: ...,
  envelope_location: :metadata,
)

# store envelope in a separate object
s3 = Aws::S3::EncryptionV2::Client.new(
  key_provider: ...,
  envelope_location: :instruction_file,
  instruction_file_suffix: '.instruction' # default
  key_wrap_schema: ...,
  content_encryption_schema: :aes_gcm_no_padding,
  security_profile: :v2
)

When using an instruction file, multiple requests are made when putting and getting the object. **This may cause issues if you are issuing concurrent PUT and GET requests to an encrypted object.**

Defined Under Namespace

Modules: Errors, KeyProvider, Utils Classes: Client, DecryptHandler, DefaultCipherProvider, DefaultKeyProvider, EncryptHandler, IOAuthDecrypter, IODecrypter, IOEncrypter, KmsCipherProvider, Materials

Constant Summary collapse

AES_GCM_TAG_LEN_BYTES = 
16
EC_USER_AGENT = 
'S3CryptoV2'