Skip to content

Commit 9d4523e

Browse files
imabhichowimabhichow
authored
feat!: Updates to the S3 Encryption Client (#491)
BREAKING CHANGES: The S3 Encryption Client now requires key committing algorithm suites by default. See migration guide from 3.x to 4.x: [link](https://docs.aws.amazon.com/amazon-s3-encryption-client/latest/developerguide/java-v4-migration.html) * `builder()` method has been removed; use `builderV4()` instead * `builderV4()` now defaults to `commitmentPolicy` (REQUIRE_ENCRYPT_REQUIRE_DECRYPT) and `encryptionAlgorithm` (ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY) * Updated expectations for custom implementations of the `CryptographicMaterialsManager` interface. * Custom implementations of the interface's `getEncryptionMaterials` method MUST set the `AlgorithmSuite` field on the returned `EncryptionMaterials`. * The provided `DefaultCryptoMaterialsManager`'s `getEncryptionMaterials` method sets this field from the `AlgorithmSuite` provided in the `EncryptionMaterialsRequest`. * If the custom implementation wraps the provided `DefaultCryptoMaterialsManager.getEncryptionMaterials` method, it's likely that no code updates are required. The provided logic has been updated with this change. * Custom implementations of the interface's `decryptMaterials` method MUST set the `KeyCommitment` field on the returned `DecryptionMaterials`. * The provided `DefaultCryptoMaterialsManager`'s `decryptMaterials` method sets this field from the `KeyCommitment` provided in the `DecryptMaterialsRequest`. * If the custom implementation wraps the provided `DefaultCryptoMaterialsManager.decryptMaterials` method, it's likely that no code updates are required. The provided logic has been updated with this change. * Updated expectations for custom implementations of the `Keyring` interface. * Custom implementations of the interface's `onDecrypt` method MUST preserve the `KeyCommitment` field on the returned `DecryptionMaterials`. * The provided `S3Keyring`'s `onDecrypt` method (base class for all keyrings including `KmsKeyring`) preserves this field through the builder pattern when returning updated materials. * If the custom implementation wraps the provided `S3Keyring.onDecrypt` method or uses the builder pattern to return materials, it's likely that no code updates are required. The provided logic has been updated with this change.
1 parent d829a23 commit 9d4523e

File tree

63 files changed

+5073
-866
lines changed

Some content is hidden

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

63 files changed

+5073
-866
lines changed

‎.github/workflows/build.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,4 +59,4 @@ jobs:
5959
- name: Package JAR
6060
run: |
6161
mvn -B -ntp install -DskipTests
62-
shell: bash
62+
shell: bash

‎.github/workflows/ci-workflow.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,3 +22,10 @@ jobs:
2222
with:
2323
version: ${{ matrix.version }}
2424
distribution: ${{ matrix.distribution }}
25+
26+
Examples:
27+
uses: ./.github/workflows/examples.yml
28+
secrets: inherit
29+
with:
30+
version: 17
31+
distribution: corretto

‎.github/workflows/examples.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Migration Examples
2+
3+
on:
4+
workflow_call:
5+
inputs:
6+
version:
7+
required: true
8+
type: string
9+
distribution:
10+
required: true
11+
type: string
12+
13+
jobs:
14+
MigrationExamples:
15+
runs-on: ubuntu-latest
16+
permissions:
17+
id-token: write
18+
contents: read
19+
20+
steps:
21+
- name: Configure AWS Credentials
22+
uses: aws-actions/configure-aws-credentials@v2
23+
with:
24+
role-to-assume: arn:aws:iam::${{ secrets.CI_AWS_ACCOUNT_ID }}:role/service-role/${{ vars.CI_AWS_ROLE }}
25+
role-session-name: S3EC-Github-CI-Tests
26+
aws-region: ${{ vars.CI_AWS_REGION }}
27+
28+
- name: Checkout Code
29+
uses: actions/checkout@v3
30+
31+
- name: Setup JDK
32+
uses: actions/setup-java@v3
33+
with:
34+
distribution: ${{ inputs.distribution }}
35+
java-version: ${{ inputs.version}}
36+
cache: 'maven'
37+
38+
- name: Install S3EC
39+
run: |
40+
mvn -B -ntp install -DskipTests
41+
shell: bash
42+
43+
# TODO: Add step to run v3 examples once we have transitional version
44+
# cd migration_examples/v3-to-v4/v3
45+
# mvn -B -ntp test -DskipCompile
46+
- name: Run Migration Examples
47+
run: |
48+
export AWS_S3EC_TEST_BUCKET=${{ vars.CI_S3_BUCKET }}
49+
export AWS_S3EC_TEST_KMS_KEY_ID=arn:aws:kms:${{ vars.CI_AWS_REGION }}:${{ secrets.CI_AWS_ACCOUNT_ID }}:key/${{ vars.CI_KMS_KEY_ID }}
50+
export AWS_REGION=${{ vars.CI_AWS_REGION }}
51+
cd migration_examples/v3-to-v4/v4
52+
mvn -B -ntp test -DskipCompile
53+
shell: bash

‎.releaserc‎

Lines changed: 79 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,84 @@
11
## Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
22
## SPDX-License-Identifier: Apache-2.0
33
{
4-
"branches": ["main"],
5-
"plugins": [
6-
["@semantic-release/commit-analyzer", {
7-
"preset": "conventionalcommits",
8-
"parserOpts": {
9-
"noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES"]
10-
},
11-
"presetConfig": {
12-
"types": [
13-
{"type": "feat", "section": "Features"},
14-
{"type": "fix", "section": "Fixes"},
15-
{"type": "chore", "section": "Maintenance"},
16-
{"type": "docs", "section": "Maintenance"},
17-
{"type": "revert", "section": "Fixes"},
18-
{"type": "style", "hidden": true},
19-
{"type": "refactor", "hidden": true},
20-
{"type": "perf", "hidden": true},
21-
{"type": "test", "hidden": true}
22-
]
23-
},
24-
"releaseRules": [
25-
{"type": "docs", "release": "patch"},
26-
{"type": "revert", "release": "patch"},
27-
{"type": "chore", "release": "patch"}
28-
]
29-
}],
30-
["@semantic-release/release-notes-generator", {
31-
"preset": "conventionalcommits",
32-
"parserOpts": {
33-
"noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES"]
34-
},
35-
"presetConfig": {
36-
"types": [
37-
{"type": "feat", "section": "Features"},
38-
{"type": "fix", "section": "Fixes"},
39-
{"type": "chore", "section": "Maintenance"},
40-
{"type": "docs", "section": "Maintenance"},
41-
{"type": "revert", "section": "Fixes"},
42-
{"type": "style", "hidden": true},
43-
{"type": "refactor", "hidden": true},
44-
{"type": "perf", "hidden": true},
45-
{"type": "test", "hidden": true}
46-
]
47-
}
48-
}],
49-
["@semantic-release/changelog", {
50-
"changelogFile": "./CHANGELOG.md",
51-
"changelogTitle": "# Changelog"
52-
}],
53-
["@semantic-release/exec", {
54-
"prepareCmd": "mvn versions:set -DnewVersion=${nextRelease.version} \
55-
-DautoVersionSubmodules=true && find README.md -type f \
56-
-exec sed -i 's/<version>.*<\\/version>/<version>${nextRelease.version}<\\/version>/g' {} \\;"
57-
}],
58-
["@semantic-release/git", {
59-
"assets": ["./CHANGELOG.md", "./pom.xml", "./README.md"],
60-
"message": "Amazon S3 Encryption Client ${nextRelease.version} Release -- ${new Date().toISOString().slice(0, 10)} \n\n${nextRelease.notes}"
61-
}],
4+
"branches": ["main"],
5+
"plugins": [
6+
[
7+
"@semantic-release/commit-analyzer",
8+
{
9+
"preset": "conventionalcommits",
10+
"parserOpts": {
11+
"noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES"]
12+
},
13+
"presetConfig": {
14+
"types": [
15+
{"type": "feat", "section": "Features"},
16+
{"type": "fix", "section": "Fixes"},
17+
{"type": "chore", "section": "Maintenance"},
18+
{"type": "docs", "section": "Maintenance"},
19+
{"type": "revert", "section": "Fixes"},
20+
{"type": "style", "hidden": true},
21+
{"type": "refactor", "hidden": true},
22+
{"type": "perf", "hidden": true},
23+
{"type": "test", "hidden": true}
24+
]
25+
},
26+
"releaseRules": [
27+
{"type": "docs", "release": "patch"},
28+
{"type": "revert", "release": "patch"},
29+
{"type": "chore", "release": "patch"}
30+
]
31+
}
6232
],
63-
"repositoryUrl": "https://github.com/aws/amazon-s3-encryption-client-java",
33+
[
34+
"@semantic-release/release-notes-generator",
35+
{
36+
"preset": "conventionalcommits",
37+
"parserOpts": {
38+
"noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES"]
39+
},
40+
"presetConfig": {
41+
"types": [
42+
{"type": "feat", "section": "Features"},
43+
{"type": "fix", "section": "Fixes"},
44+
{"type": "chore", "section": "Maintenance"},
45+
{"type": "docs", "section": "Maintenance"},
46+
{"type": "revert", "section": "Fixes"},
47+
{"type": "style", "hidden": true},
48+
{"type": "refactor", "hidden": true},
49+
{"type": "perf", "hidden": true},
50+
{"type": "test", "hidden": true}
51+
]
52+
}
53+
}
54+
],
55+
[
56+
"@semantic-release/changelog",
57+
{
58+
"changelogFile": "./CHANGELOG.md",
59+
"changelogTitle": "# Changelog"
60+
}
61+
],
62+
[
63+
"@semantic-release/exec",
64+
{
65+
"prepareCmd": "bash ./release-prepare.sh ${nextRelease.version}"
66+
}
67+
],
68+
[
69+
"@semantic-release/git",
70+
{
71+
"assets": [
72+
"./CHANGELOG.md",
73+
"./pom.xml",
74+
"./README.md",
75+
"./migration_examples/v3-to-v4/v4/pom.xml",
76+
"./src/main/java/software/amazon/encryption/s3/internal/ApiNameVersion.java",
77+
"./src/test/java/software/amazon/encryption/s3/internal/ApiNameVersionTest.java"
78+
],
79+
"message": "Amazon S3 Encryption Client ${nextRelease.version} Release -- ${new Date().toISOString().slice(0, 10)} \n\n${nextRelease.notes}"
80+
}
81+
]
82+
],
83+
"repositoryUrl": "https://github.com/aws/aws-s3-encryption-client-java"
6484
}

‎README.md‎

Lines changed: 49 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,36 @@ You can configure each client independently, or apply a "top-level" configuratio
5353
Refer to the Client Configuration Example in the [Examples directory](https://github.com/aws/amazon-s3-encryption-client-java/tree/main/src/examples/java/software/amazon/encryption/s3/examples) for examples of each configuration method.
5454

5555
### Examples
56-
#### V2 KMS Materials Provider to V3
56+
#### V3 to V4 Migration
57+
58+
V4 introduces enhanced security with commitment policies. To migrate from V3:
59+
60+
```java
61+
class Example {
62+
public static void main(String[] args) {
63+
KeyGenerator keyGen = KeyGenerator.getInstance("AES");
64+
keyGen.init(256);
65+
SecretKey aesKey = keyGen.generateKey();
66+
67+
// V3
68+
S3Client v3Client = S3EncryptionClient.builder()
69+
.aesKey(aesKey)
70+
.build();
71+
72+
// V4
73+
S3Client v4Client = S3EncryptionClient.builderV4()
74+
.commitmentPolicy(CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
75+
.encryptionAlgorithm(AlgorithmSuite.ALG_AES_256_GCM_IV12_TAG16_NO_KDF)
76+
.aesKey(aesKey)
77+
.build();
78+
}
79+
}
80+
```
81+
82+
For detailed migration guidance and step-by-step examples, refer to the [Migration Examples](migration_examples/v3-to-v4/README.md). For more information, refer to the <a href="https://docs.aws.amazon.com/amazon-s3-encryption-client/latest/developerguide/java-v4-migration.html">Developer Guide</a>.
83+
84+
85+
#### V2 KMS Materials Provider to V4
5786
```java
5887
class Example {
5988
public static void main(String[] args) {
@@ -63,15 +92,17 @@ class Example {
6392
.withEncryptionMaterialsProvider(materialsProvider)
6493
.build();
6594

66-
// V3
67-
S3Client v3Client = S3EncryptionClient.builder()
95+
// V4
96+
S3Client v4Client = S3EncryptionClient.builderV4()
97+
.commitmentPolicy(CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
98+
.encryptionAlgorithm(AlgorithmSuite.ALG_AES_256_GCM_IV12_TAG16_NO_KDF)
6899
.kmsKeyId(KMS_WRAPPING_KEY_ID)
69100
.build();
70101
}
71102
}
72103
```
73104

74-
#### V2 AES Key Materials Provider to V3
105+
#### V2 AES Key Materials Provider to V4
75106
```java
76107
class Example {
77108
public static void main(String[] args) {
@@ -85,15 +116,17 @@ class Example {
85116
.withEncryptionMaterialsProvider(materialsProvider)
86117
.build();
87118

88-
// V3
89-
S3Client v3Client = S3EncryptionClient.builder()
119+
// V4
120+
S3Client v4Client = S3EncryptionClient.builderV4()
121+
.commitmentPolicy(CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
122+
.encryptionAlgorithm(AlgorithmSuite.ALG_AES_256_GCM_IV12_TAG16_NO_KDF)
90123
.aesKey(aesKey)
91124
.build();
92125
}
93126
}
94127
```
95128

96-
#### V2 RSA Key Materials Provider to V3
129+
#### V2 RSA Key Materials Provider to V4
97130
```java
98131
class Example {
99132
public static void main(String[] args) {
@@ -107,15 +140,17 @@ class Example {
107140
.withEncryptionMaterialsProvider(materialsProvider)
108141
.build();
109142

110-
// V3
111-
S3Client v3Client = S3EncryptionClient.builder()
143+
// V4
144+
S3Client v4Client = S3EncryptionClient.builderV4()
145+
.commitmentPolicy(CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
146+
.encryptionAlgorithm(AlgorithmSuite.ALG_AES_256_GCM_IV12_TAG16_NO_KDF)
112147
.rsaKeyPair(rsaKey)
113148
.build();
114149
}
115150
}
116151
```
117152

118-
#### V1 Key Materials Provider to V3
153+
#### V1 Key Materials Provider to V4
119154
To allow legacy modes (for decryption only), you must explicitly allow them
120155
```java
121156
class Example {
@@ -130,8 +165,10 @@ class Example {
130165
.withEncryptionMaterials(materialsProvider)
131166
.build();
132167

133-
// V3
134-
S3Client v3Client = S3EncryptionClient.builder()
168+
// V4
169+
S3Client v4Client = S3EncryptionClient.builderV4()
170+
.commitmentPolicy(CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
171+
.encryptionAlgorithm(AlgorithmSuite.ALG_AES_256_GCM_IV12_TAG16_NO_KDF)
135172
.aesKey(aesKey)
136173
.enableLegacyUnauthenticatedModes(true) // for enabling legacy content decryption modes
137174
.enableLegacyWrappingAlgorithms(true) // for enabling legacy key wrapping modes
@@ -149,8 +186,6 @@ class Example {
149186
* RSA-OAEP w/MGF-1 and SHA-256
150187
* RSA
151188
* KMS (without context)
152-
#### Encryption Metadata Storage
153-
* Instruction File
154189

155190
## Security
156191

‎SUPPORT_POLICY.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,10 @@ This table describes the current support status of each major version of the Ama
3030
- End of Support
3131
- EOY 2025
3232
* - 3.x
33+
- Maintenance Mode
34+
-
35+
-
36+
* - 4.x
3337
- Generally Available
3438
-
3539
-

0 commit comments

Comments
 (0)