How to Encrypt Amazon S3 Objects with the AWS SDK for Ruby

August 31, 2021: AWS KMS is replacing the term customer master key (CMK) with AWS KMS key and KMS key. The concept has not changed. To prevent breaking changes, AWS KMS is keeping some variations of this term. More info.

Recently, Amazon announced some new Amazon S3 encryption and security features. The AWS Blog post showed how to use the Amazon S3 console to take advantage of these new features. However, if you have a large number of Amazon S3 buckets, using the console to implement these features could take hours, if not days. As an alternative, I created documentation topics in the AWS SDK for Ruby Developer Guide that include code examples showing you how to use the new Amazon S3 encryption features using the AWS SDK for Ruby.

What are my encryption options?

You can encrypt Amazon S3 bucket objects on a server or on a client:

• When you encrypt objects on a server, you request that Amazon S3 encrypt the objects before saving them to disk in data centers and decrypt the objects when you download them. The main advantage of this approach is that Amazon S3 manages the entire encryption process.
• When you encrypt objects on a client, you encrypt the objects before you upload them to Amazon S3. In this case, you manage the encryption process, the encryption keys, and related tools. Use this option when:
  • Company policy and standards require it.
  • You already have a development process in place that meets your needs.

  Encrypting on the client has always been available, but you should know the following points:

  • You must be diligent about protecting your encryption keys, which is analogous to having a burglar-proof lock on your front door. If you leave a key under the mat, your security is compromised.
  • If you lose your encryption keys, you won’t be able to decrypt your data.

  If you encrypt objects on the client, we strongly recommend that you use an AWS Key Management Service (AWS KMS) key.

How to use encryption on a server

You can specify that Amazon S3 automatically encrypts objects as you upload them to a bucket or require that objects uploaded to an Amazon S3 bucket include encryption on a server before they are uploaded to an Amazon S3 bucket.

The advantage of these settings is that when you specify them, you ensure that objects uploaded to Amazon S3 are encrypted. Alternatively, you can have Amazon S3 encrypt individual objects on the server as you upload them to a bucket or encrypt them on the server with your own key as you upload them to a bucket.

The AWS SDK for Ruby Developer Guide now contains the following topics that explain your encryption options on a server:

• Setting Default Server-Side Encryption for an Amazon S3 Bucket – Describes how to specify that objects uploaded to a bucket are automatically encrypted by Amazon S3.
• Encrypting an Amazon S3 Bucket Object on the Server – Describes how to have Amazon S3 encrypt an object when it’s uploaded to a bucket.
• Requiring Encryption on the Server to Upload Amazon S3 Bucket Objects – Describes how to require objects uploaded to a bucket be encrypted by Amazon S3 using a bucket policy.
• Encrypting an Amazon S3 Bucket Object with an AWS KMS Key – Describes how to have Amazon S3 encrypt an object with a key that you provide when you upload the object to a bucket.

How to use encryption on a client

You can encrypt objects on a client before you upload them to a bucket and decrypt them after you download them from a bucket by using the Amazon S3 encryption client.

The AWS SDK for Ruby Developer Guide now contains the following topics that explain your encryption options on the client:

• Encrypting an Amazon S3 Bucket Object with an AWS KMS Key and Decrypting an Amazon S3 Bucket Object with an AWS KMS Key – Describe how to encrypt and decrypt an object with an AWS KMS managed key. KMS keys are either customer managed or AWS managed. For more information, see AWS Key Management Service Concepts.
• Encrypting an Amazon S3 Bucket Object with a Public Key and Decrypting an Amazon S3 Bucket Object with a Private Key – Describe how to encrypt and decrypt an object with a public/private RSA key. Public keys can be distributed to others so that they can encrypt data; however, only those in possession of a private key can decrypt that data. For more information, see OpenSSL::PKey.

Note: The Amazon S3 encryption client in the AWS SDK for Ruby is compatible with other Amazon S3 encryption clients, but it is not compatible with other AWS client-side encryption libraries, including the AWS Encryption SDK and the Amazon DynamoDB encryption client for Java. Each library returns a different ciphertext (“encrypted message”) format, so you can’t use one library to encrypt objects and a different library to decrypt them. For more information, see Protecting Data Using Client-Side Encryption.

If you have comments about this blog post, submit them in the “Comments” section below. If you have questions about encrypting objects on servers and clients, start a new thread on the Amazon S3 forum or contact AWS Support.

– Doug