Skip to content

Commit b633ba1

Browse files
richardwang1124seebeesjterapin
authored
Updates to the S3 Encryption Client (#3328)
Co-authored-by: Ryan Emery <[email protected]> Co-authored-by: Juli Tera <[email protected]>
1 parent 4cb81c3 commit b633ba1

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+7580
-188
lines changed

‎gems/aws-sdk-s3/CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
Unreleased Changes
22
------------------
33

4+
* Feature - Updates to the S3 Encryption Client. The V3 S3 Encryption Client now requires key committing algorithm suites by default. See migration guide: [link to docs]
5+
46
1.207.0 (2025-12-15)
57
------------------
68

‎gems/aws-sdk-s3/README.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Amazon S3 Encryption Client for Ruby V3
2+
3+
This library provides an S3 client that supports client-side encryption.
4+
`Aws::S3::EncryptionV3::Client` is the v3 of the Amazon S3 Encryption Client for the Ruby programming language.
5+
6+
The v3 encryption client requires a minimum version of **Ruby >= 2.5**.
7+
8+
Jump To:
9+
10+
* [Getting Started](#getting-started)
11+
* [Migration](#migration)
12+
13+
## Maintenance and support for SDK major versions
14+
15+
For information about maintenance and support for SDK major versions and their underlying dependencies, see the
16+
following in the AWS SDKs and Tools Shared Configuration and Credentials Reference Guide:
17+
18+
* [AWS SDKs and Tools Maintenance Policy](https://docs.aws.amazon.com/credref/latest/refdocs/maint-policy.html)
19+
* [AWS SDKs and Tools Version Support Matrix](https://docs.aws.amazon.com/credref/latest/refdocs/version-support-matrix.html)
20+
21+
### Ruby version support policy
22+
23+
The v3 Encryption Client follows the upstream Ruby [maintenance policy](https://www.ruby-lang.org/en/downloads/branches/)
24+
with an additional six months of support for the most recently deprecated
25+
language version.
26+
27+
**AWS reserves the right to drop support for unsupported Ruby versions earlier to
28+
address critical security issues.**
29+
30+
## Getting Started
31+
32+
1. **Sign up for AWS** – Before you begin, you need to
33+
sign up for an AWS account and retrieve your [AWS credentials][docs-signup].
34+
2. **Minimum requirements** – To run the SDK, your system will need to meet the
35+
[minimum requirements][docs-requirements], including having **Ruby >= 2.5**.
36+
3. **Install the SDK** – Using [Bundler][bundler] is the recommended way to install the
37+
AWS SDK for Ruby. The SDK is available via [RubyGems][rubygems] under the
38+
[`aws-sdk-s3`][install-rubygems] gem. If Bundler is installed on your system, you can add the following to your Gemfile:
39+
40+
```bash
41+
gem 'aws-sdk-s3'
42+
```
43+
44+
Or install the gem directly:
45+
46+
```bash
47+
gem install aws-sdk-s3
48+
```
49+
50+
Please see the
51+
[Installation section of the Developer Guide][docs-installation] for more
52+
detailed information about installing the SDK.
53+
4. **Using the SDK** – The best way to become familiar with how to use the SDK
54+
is to read the [Developer Guide][docs-guide]. The
55+
[Getting Started Guide][docs-quickstart] will help you become familiar with
56+
the basic concepts.
57+
58+
## Quick Examples
59+
60+
### Create an Amazon S3 Encryption Client
61+
62+
```ruby
63+
require 'aws-sdk-s3'
64+
65+
# Instantiate an Amazon S3 client.
66+
s3_client = Aws::S3::Client.new(
67+
region: 'us-west-2'
68+
)
69+
70+
# Instantiate an Amazon S3 Encryption Client V3.
71+
client = Aws::S3::EncryptionV3::Client.new(
72+
client: s3_client,
73+
encryption_key: encryption_key,
74+
key_wrap_schema: :aes_gcm
75+
)
76+
```
77+
78+
### Upload a file to Amazon S3 using client side encryption
79+
80+
```ruby
81+
require 'aws-sdk-s3'
82+
require 'aws-sdk-kms'
83+
84+
# Create a KMS client
85+
kms_client = Aws::KMS::Client.new(
86+
region: 'us-east-1'
87+
)
88+
89+
# Specify your KMS key ID
90+
kms_key_id = 'your-kms-key-id'
91+
92+
# Create the encryption client
93+
client = Aws::S3::EncryptionV3::Client.new(
94+
kms_key_id: kms_key_id,
95+
kms_client: kms_client,
96+
key_wrap_schema: :kms_context
97+
)
98+
99+
# Upload an encrypted object
100+
bucket = 'the-bucket-name'
101+
key = 'the-file-name'
102+
103+
result = client.put_object(
104+
bucket: bucket,
105+
key: key,
106+
body: File.open('file-to-encrypt.txt', 'r'),
107+
kms_encryption_context: { 'context-key' => 'context-value' }
108+
)
109+
```
110+
111+
## Migration
112+
113+
This version of the library supports reading encrypted objects from previous versions with extra configuration.
114+
It also supports writing objects with non-legacy algorithms.
115+
The list of legacy modes and operations will be provided below.
116+
117+
* [2.x to 3.x Migration Guide](https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/s3-encryption-migration-v2-v3.html)
118+
* [1.x to 2.x Migration Guide](https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/s3-encryption-migration-v1-v2.html)
119+
120+
## Security
121+
122+
See [CONTRIBUTING](../../../CONTRIBUTING.md#security-issue-notifications) for more information.
123+
124+
## License
125+
126+
This project is licensed under the Apache-2.0 License.
127+
128+
[docs-signup]: https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/setup-config.html
129+
[docs-requirements]: https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/setup-install.html
130+
[docs-installation]: https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/setup-install.html
131+
[docs-guide]: https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/welcome.html
132+
[docs-quickstart]: https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/getting-started.html
133+
[bundler]: https://bundler.io/
134+
[rubygems]: https://rubygems.org/
135+
[install-rubygems]: https://rubygems.org/gems/aws-sdk-s3

‎gems/aws-sdk-s3/S3_EC_SUPPORT_POLICY.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Amazon S3 Encryption Client for Ruby - Support Policy
2+
3+
## Overview
4+
5+
This page describes the support policy for the Amazon S3 Encryption Client for Ruby. We regularly provide the Amazon S3 Encryption Client for Ruby with updates that may contain support for new or updated APIs, new features, enhancements, bug fixes, security patches, or documentation updates. Updates may also address changes with dependencies, language runtimes, and operating systems.
6+
7+
We recommend users to stay up-to-date with Amazon S3 Encryption Client for Ruby releases to keep up with the latest features, security updates, and underlying dependencies. Continued use of an unsupported SDK version is not recommended and is done at the user's discretion.
8+
9+
## Major Version Lifecycle
10+
11+
The Amazon S3 Encryption Client for Ruby follows the same major version lifecycle as the AWS SDK. For details on this lifecycle, see [AWS SDKs and Tools Maintenance Policy](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle).
12+
13+
## Version Support Matrix
14+
15+
This table describes the current support status of each major version of the Amazon S3 Encryption Client for Ruby. It also shows the next status each major version will transition to, and the date at which that transition will happen.
16+
17+
| Major version | Current status | Next status | Next status date |
18+
|---------------|-----------------------|---------------|------------------|
19+
| 3.x | General Availability | | |
20+
| 2.x | General Availability | Maintenance | 2026-06-15 |
21+
| 1.x | End of Support | | |

‎gems/aws-sdk-s3/lib/aws-sdk-s3/customizations.rb‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ module S3
66
autoload :BucketRegionCache, 'aws-sdk-s3/bucket_region_cache'
77
autoload :Encryption, 'aws-sdk-s3/encryption'
88
autoload :EncryptionV2, 'aws-sdk-s3/encryption_v2'
9+
autoload :EncryptionV3, 'aws-sdk-s3/encryption_v3'
910
autoload :FilePart, 'aws-sdk-s3/file_part'
1011
autoload :DefaultExecutor, 'aws-sdk-s3/default_executor'
1112
autoload :FileUploader, 'aws-sdk-s3/file_uploader'

‎gems/aws-sdk-s3/lib/aws-sdk-s3/encryption/client.rb‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@ module Aws
66
module S3
77

88
# [MAINTENANCE MODE] There is a new version of the Encryption Client.
9-
# AWS strongly recommends upgrading to the {Aws::S3::EncryptionV2::Client},
9+
# AWS strongly recommends upgrading to the {Aws::S3::EncryptionV3::Client},
1010
# which provides updated data security best practices.
11-
# See documentation for {Aws::S3::EncryptionV2::Client}.
11+
# See documentation for {Aws::S3::EncryptionV3::Client}.
1212
# Provides an encryption client that encrypts and decrypts data client-side,
1313
# storing the encrypted data in Amazon S3.
1414
#

‎gems/aws-sdk-s3/lib/aws-sdk-s3/encryption/default_cipher_provider.rb‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ def initialize(options = {})
1616
# envelope and encryption cipher.
1717
def encryption_cipher
1818
cipher = Utils.aes_encryption_cipher(:CBC)
19+
##= ../specification/s3-encryption/data-format/content-metadata.md#algorithm-suite-and-message-format-version-compatibility
20+
##% Objects encrypted with ALG_AES_256_CBC_IV16_NO_KDF MAY use either the V1 or V2 message format version.
1921
envelope = {
2022
'x-amz-key' => encode64(encrypt(envelope_key(cipher))),
2123
'x-amz-iv' => encode64(envelope_iv(cipher)),

‎gems/aws-sdk-s3/lib/aws-sdk-s3/encryption/encrypt_handler.rb‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,8 @@ def apply_encryption_cipher(context, cipher)
3838
io = StringIO.new(io) if String === io
3939
context.params[:body] = IOEncrypter.new(cipher, io)
4040
context.params[:metadata] ||= {}
41+
##= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
42+
##% - The mapkey "x-amz-unencrypted-content-length" SHOULD be present for V1 format objects.
4143
context.params[:metadata]['x-amz-unencrypted-content-length'] = io.size
4244
if context.params.delete(:content_md5)
4345
warn('Setting content_md5 on client side encrypted objects is deprecated')

‎gems/aws-sdk-s3/lib/aws-sdk-s3/encryption/kms_cipher_provider.rb‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ def encryption_cipher
2626
end
2727
cipher = Utils.aes_encryption_cipher(:CBC)
2828
cipher.key = key_data.plaintext
29+
##= ../specification/s3-encryption/data-format/content-metadata.md#algorithm-suite-and-message-format-version-compatibility
30+
##% Objects encrypted with ALG_AES_256_CBC_IV16_NO_KDF MAY use either the V1 or V2 message format version.
2931
envelope = {
3032
'x-amz-key-v2' => encode64(key_data.ciphertext_blob),
3133
'x-amz-iv' => encode64(cipher.iv = cipher.random_iv),

0 commit comments

Comments
 (0)