module Aws::S3::EncryptionV2
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 {Aws::S3::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.**
Constants
- AES_GCM_TAG_LEN_BYTES
- EC_USER_AGENT