Skip to content

Commit c03e32c

Browse files
Carey-AWSCarey-AWS
committed
Updates for the Amazon S3 Encryption Client
This change includes fixes for issues that were reported by Sophie Schmieg from the Google ISE team, and for issues that were discovered by AWS Cryptography
1 parent d10c8fd commit c03e32c

File tree

5 files changed

+394
-175
lines changed

5 files changed

+394
-175
lines changed

‎doc_source/examples-crypto-kms.rst‎

Lines changed: 54 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
1+
.. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
22
33
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0
44
International License (the "License"). You may not use this file except in compliance with the
@@ -9,15 +9,15 @@
99
limitations under the License.
1010
1111
###################################################
12-
|S3| Client-Side Encryption with |KMS| Managed Keys
12+
|S3| client-side encryption with |KMS| managed keys
1313
###################################################
1414

1515
.. meta::
1616
:description: How to use the cryptography configuration settings for the AWS SDK for Java
1717
:keywords: AWS SDK for Java code examples, cryptography, encryption
1818

1919
The following examples use the
20-
:aws-java-class:`AmazonS3EncryptionClientBuilder <services/s3/AmazonS3EncryptionClientBuilder>` class
20+
:aws-java-class:`AmazonS3EncryptionClientV2Builder <services/s3/AmazonS3EncryptionClientV2Builder>` class
2121
to create an |S3| client with client-side encryption enabled. Once configured,
2222
any objects you upload to |S3| using this client
2323
will be encrypted. Any objects you get from |S3| using this client are automatically
@@ -28,61 +28,82 @@ decrypted.
2828
encryption with |KMS| managed keys. To learn how to use encryption with your own keys,
2929
see :doc:`examples-crypto-masterkey`.
3030

31-
You can choose from three encryption modes when enabling client-side |S3| encryption: encryption-only,
32-
authenticated, and strict authenticated.
31+
You can choose from two encryption modes when enabling client-side |S3| encryption: strict
32+
authenticated or authenticated.
3333
The following sections show how to enable each type. To learn which algorithms each mode uses,
3434
see the :aws-java-class:`CryptoMode <services/s3/model/CryptoMode>` definition.
3535

3636

37-
Required Imports
37+
Required imports
3838
================
3939

4040
Import the following classes for these examples.
4141

4242
**Imports**
4343

44-
.. literalinclude:: s3.java1.s3_encrypt.import.txt
45-
:language: java
44+
.. code-block:: java
45+
46+
import com.amazonaws.ClientConfiguration;
47+
import com.amazonaws.regions.Regions;
48+
import com.amazonaws.services.kms.AWSKMS;
49+
import com.amazonaws.services.kms.AWSKMSClientBuilder;
50+
import com.amazonaws.services.kms.model.GenerateDataKeyRequest;
51+
import com.amazonaws.services.kms.model.GenerateDataKeyResult;
52+
import com.amazonaws.services.s3.AmazonS3EncryptionClientV2Builder;
53+
import com.amazonaws.services.s3.AmazonS3EncryptionV2;
54+
import com.amazonaws.services.s3.model.CryptoConfigurationV2;
55+
import com.amazonaws.services.s3.model.CryptoMode;
56+
import com.amazonaws.services.s3.model.EncryptionMaterials;
57+
import com.amazonaws.services.s3.model.KMSEncryptionMaterialsProvider;
4658
47-
.. _encryption-only-kms:
59+
.. _strict-authenticated-encryption-kms:
4860

49-
Encryption-Only Mode
50-
====================
61+
Strict authenticated encryption
62+
===============================
5163

52-
Encryption-only is the default mode, if no :classname:`CryptoMode` is specified.
53-
To use an |KMS|
54-
managed key for encryption, pass the |KMS| key ID or alias to the
55-
:aws-java-class:`KMSEncryptionMaterialsProvider` constructor.
64+
Strict authenticated encryption is the default mode if no :classname:`CryptoMode` is specified.
65+
66+
To explicitly enable this mode, specify the :classname:`StrictAuthenticatedEncryption` value in the
67+
:methodName:`withCryptoConfiguration` method.
68+
69+
.. note:: To use client-side authenticated encryption, you must include the latest
70+
`Bouncy Castle jar <https://www.bouncycastle.org/latest_releases.html>`_ file
71+
in the classpath of your application.
5672

5773
**Code**
5874

59-
.. literalinclude:: s3.java1.s3_encrypt.kms_encryption_only_build.txt
60-
:dedent: 8
61-
:language: java
75+
.. code-block:: java
76+
77+
AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard()
78+
.withRegion(Regions.US_WEST_2)
79+
.withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.StrictAuthenticatedEncryption)))
80+
.withEncryptionMaterialsProvider(new KMSEncryptionMaterialsProvider(keyId))
81+
.build();
82+
83+
s3Encryption.putObject(bucket_name, ENCRYPTED_KEY3, "This is the 3rd content to encrypt with a key created in the AWS Console");
84+
System.out.println(s3Encryption.getObjectAsString(bucket_name, ENCRYPTED_KEY3));
6285
6386
6487
Call the :methodname:`putObject` method on the |S3| encryption client to upload objects.
6588

6689
**Code**
6790

68-
.. literalinclude:: s3.java1.s3_encrypt.kms_encryption_only_put_object.txt
69-
:dedent: 8
70-
:language: java
91+
.. code-block:: java
92+
93+
s3Encryption.putObject(bucket_name, ENCRYPTED_KEY3, "This is the 3rd content to encrypt with a key created in the AWS Console");
7194
7295
You can retrieve the object using the same client. This example calls the
7396
:methodname:`getObjectAsString` method to retrieve the string that was stored.
7497

7598
**Code**
7699

77-
.. literalinclude:: s3.java1.s3_encrypt.kms_encryption_only_retrieve.txt
78-
:dedent: 8
79-
:language: java
100+
.. code-block:: java
80101
81-
See the :sdk-examples-java-s3:`complete example <S3Encrypt.java>` on GitHub.
102+
System.out.println(s3Encryption.getObjectAsString(bucket_name, ENCRYPTED_KEY3));
82103
83104
.. _authenticated-encryption-kms:
84105

85-
Authenticated Encryption Mode
106+
Authenticated encryption mode
86107
=============================
87108

88109
When you use :classname:`AuthenticatedEncryption` mode, an improved key wrapping algorithm is
@@ -102,56 +123,11 @@ To enable this mode, specify the :classname:`AuthenticatedEncryption` value in t
102123

103124
**Code**
104125

105-
.. literalinclude:: s3.java1.s3_encrypt.kms_authenticated_encryption_builder.txt
106-
:dedent: 8
107-
:language: java
108-
109-
The :classname:`AuthenticatedEncryption` mode can retrieve unencrypted objects and
110-
objects encrypted with :classname:`EncryptionOnly` mode. The following example shows the
111-
|S3| encryption client retrieving an unencrypted object.
112-
113-
**Code**
114-
115-
.. literalinclude:: s3.java1.s3_encrypt.kms_authenticated_encryption_put_object.txt
116-
:dedent: 8
117-
:language: java
118-
119-
See the :sdk-examples-java-s3:`complete example <S3Encrypt.java>` on GitHub.
120-
121-
.. _strict-authenticated-encryption-kms:
122-
123-
Strict Authenticated Encryption
124-
===============================
125-
126-
To enable this mode, specify the :classname:`StrictAuthenticatedEncryption` value in the
127-
:methodName:`withCryptoConfiguration` method.
128-
129-
.. note:: To use client-side authenticated encryption, you must include the latest
130-
`Bouncy Castle jar <https://www.bouncycastle.org/latest_releases.html>`_ file
131-
in the classpath of your application.
132-
133-
**Code**
134-
135-
.. literalinclude:: s3.java1.s3_encrypt.kms_authenticated_encryption_strict_builder.txt
136-
:dedent: 8
137-
:language: java
138-
139-
Call the :methodname:`putObject` method on the |S3| encryption client to upload objects.
140-
141-
**Code**
142-
143-
.. literalinclude:: s3.java1.s3_encrypt.kms_authenticated_encryption_strict_put_object.txt
144-
:dedent: 8
145-
:language: java
146-
147-
In :classname:`StrictAuthenticatedEncryption` mode, the |S3| client throws an
148-
exception when retrieving an object that was not encrypted using an
149-
authenticated mode.
150-
151-
**Code**
152-
153-
.. literalinclude:: s3.java1.s3_encrypt.kms_authenticated_encryption_strict_exception.txt
154-
:dedent: 8
155-
:language: java
126+
.. code-block:: java
156127
157-
See the :sdk-examples-java-s3:`complete example <S3Encrypt.java>` on GitHub.
128+
AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard()
129+
.withRegion(Regions.US_WEST_2)
130+
.withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.AuthenticatedEncryption)))
131+
.withEncryptionMaterialsProvider(new KMSEncryptionMaterialsProvider(keyId))
132+
.build();
133+

‎doc_source/examples-crypto-masterkey.rst‎

Lines changed: 40 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
1+
.. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
22
33
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0
44
International License (the "License"). You may not use this file except in compliance with the
@@ -9,15 +9,15 @@
99
limitations under the License.
1010
1111
###################################################
12-
|S3| Client-Side Encryption with Client Master Keys
12+
|S3| client-side encryption with client master keys
1313
###################################################
1414

1515
.. meta::
1616
:description: How to use the cryptography configuration settings for the AWS SDK for Java
1717
:keywords: AWS SDK for Java code examples
1818

1919
The following examples use the
20-
:aws-java-class:`AmazonS3EncryptionClientBuilder <services/s3/AmazonS3EncryptionClientBuilder>` class
20+
:aws-java-class:`AmazonS3EncryptionClientV2Builder <services/s3/AmazonS3EncryptionClientV2Builder>` class
2121
to create an |S3| client with client-side encryption enabled. Once enabled,
2222
any objects you upload to |S3| using this client
2323
will be encrypted. Any objects you get from |S3| using this client will automatically
@@ -28,69 +28,57 @@ be decrypted.
2828
encryption with customer-managed client master keys. To learn how to use encryption
2929
with |KMS| managed keys, see :doc:`examples-crypto-kms`.
3030

31-
You can choose from three encryption modes when enabling client-side |S3| encryption: encryption-only,
32-
authenticated, and strict authenticated.
31+
You can choose from two encryption modes when enabling client-side |S3| encryption: strict
32+
authenticated or authenticated.
3333
The following sections show how to enable each type. To learn which algorithms each mode uses,
3434
see the :aws-java-class:`CryptoMode <services/s3/model/CryptoMode>` definition.
3535

36-
Required Imports
36+
Required imports
3737
================
3838

3939
Import the following classes for these examples.
4040

4141
**Imports**
4242

43-
.. literalinclude:: s3.java1.s3_encrypt.import.txt
44-
:language: java
43+
.. code-block:: java
4544
46-
.. _encryption-only:
45+
import com.amazonaws.ClientConfiguration;
46+
import com.amazonaws.regions.Regions;
47+
import com.amazonaws.services.s3.AmazonS3EncryptionClientV2Builder;
48+
import com.amazonaws.services.s3.AmazonS3EncryptionV2;
49+
import com.amazonaws.services.s3.model.CryptoConfigurationV2;
50+
import com.amazonaws.services.s3.model.CryptoMode;
51+
import com.amazonaws.services.s3.model.EncryptionMaterials;
52+
import com.amazonaws.services.s3.model.StaticEncryptionMaterialsProvider;
4753
48-
Encryption-Only Mode
49-
====================
50-
51-
Encryption-only is the default mode, if no :classname:`CryptoMode` is specified. To enable
52-
encryption, you must pass a key to the :aws-java-class:`EncryptionMaterials`
53-
constructor. The example below uses
54-
the :class:`KeyGenerator` Java class generate a symmetric private key.
55-
56-
**Code**
57-
58-
.. literalinclude:: s3.java1.s3_encrypt.encryption_only.txt
59-
:dedent: 4
60-
:language: java
54+
.. _strict-authenticated-encryption:
6155

62-
To use an asymmetric key or a key pair, simply pass the key pair to the same
63-
:aws-java-class:`EncryptionMaterials` class. The example below uses the
64-
:class:`KeyPairGenerator` class to generate a key pair.
56+
Strict authenticated encryption
57+
===============================
6558

66-
**Code**
59+
Strict authenticated encryption is the default mode if no :classname:`CryptoMode` is specified.
6760

68-
.. literalinclude:: s3.java1.s3_encrypt.encryption_only_asymetric_key_build.txt
69-
:dedent: 8
70-
:language: java
61+
To explicitly enable this mode, specify the :classname:`StrictAuthenticatedEncryption` value in the
62+
:methodName:`withCryptoConfiguration` method.
7163

72-
Call the :methodname:`putObject` method on the |S3| encryption client to upload objects.
64+
.. note:: To use client-side authenticated encryption, you must include the latest
65+
`Bouncy Castle jar <https://www.bouncycastle.org/latest_releases.html>`_ file
66+
in the classpath of your application.
7367

7468
**Code**
7569

76-
.. literalinclude:: s3.java1.s3_encrypt.encryption_only_asymetric_key_put_object.txt
77-
:dedent: 8
78-
:language: java
79-
80-
You can retrieve the object using the same client. This example calls the
81-
:methodname:`getObjectAsString` method to retrieve the string that was stored.
82-
83-
**Code**
70+
.. code-block:: java
8471
85-
.. literalinclude:: s3.java1.s3_encrypt.encryption_only_asymetric_key_retrieve.txt
86-
:dedent: 8
87-
:language: java
72+
AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard()
73+
.withRegion(Regions.US_WEST_2)
74+
.withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.StrictAuthenticatedEncryption)))
75+
.withEncryptionMaterialsProvider(new StaticEncryptionMaterialsProvider(new EncryptionMaterials(secretKey)))
76+
.build();
8877
89-
See the :sdk-examples-java-s3:`complete example <S3Encrypt.java>` on GitHub.
78+
s3Encryption.putObject(bucket_name, ENCRYPTED_KEY2, "This is the 2nd content to encrypt");
9079
91-
.. _authenticated-encryption:
9280
93-
Authenticated Encryption Mode
81+
Authenticated encryption mode
9482
=============================
9583

9684
When you use :classname:`AuthenticatedEncryption` mode, an improved key wrapping algorithm is
@@ -109,48 +97,14 @@ To enable this mode, specify the :classname:`AuthenticatedEncryption` value in t
10997

11098
**Code**
11199

112-
.. literalinclude:: s3.java1.s3_encrypt.authenticated_encryption_build.txt
113-
:dedent: 8
114-
:language: java
115-
116-
The :classname:`AuthenticatedEncryption` mode can retrieve unencrypted objects and
117-
objects encrypted with :classname:`EncryptionOnly` mode. The following example shows the
118-
|S3| encryption client retrieving an unencrypted object.
119-
120-
**Code**
121-
122-
.. literalinclude:: s3.java1.s3_encrypt.authenticated_encryption.txt
123-
:dedent: 4
124-
:language: java
125-
126-
See the :sdk-examples-java-s3:`complete example <S3Encrypt.java#L66-L80>` on GitHub.
127-
128-
.. _strict-authenticated-encryption:
129-
130-
Strict Authenticated Encryption
131-
===============================
132-
133-
To enable this mode, specify the :classname:`StrictAuthenticatedEncryption` value in the
134-
:methodName:`withCryptoConfiguration` method.
135-
136-
.. note:: To use client-side authenticated encryption, you must include the latest
137-
`Bouncy Castle jar <https://www.bouncycastle.org/latest_releases.html>`_ file
138-
in the classpath of your application.
139-
140-
**Code**
141-
142-
.. literalinclude:: s3.java1.s3_encrypt.strict_authenticated_encryption_build.txt
143-
:dedent: 8
144-
:language: java
100+
.. code-block:: java
145101
146-
In :classname:`StrictAuthenticatedEncryption` mode, the |S3| client throws an
147-
exception when retrieving an object that was not encrypted using an
148-
authenticated mode.
149-
150-
**Code**
102+
AmazonS3EncryptionV2 s3EncryptionClientV2 = AmazonS3EncryptionClientV2Builder.standard()
103+
.withRegion(Regions.DEFAULT_REGION)
104+
.withClientConfiguration(new ClientConfiguration())
105+
.withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode(CryptoMode.AuthenticatedEncryption))
106+
.withEncryptionMaterialsProvider(new StaticEncryptionMaterialsProvider(new EncryptionMaterials(secretKey)))
107+
.build();
151108
152-
.. literalinclude:: s3.java1.s3_encrypt.strict_authenticated_encryption.txt
153-
:dedent: 4
154-
:language: java
109+
s3EncryptionClientV2.putObject(bucket_name, ENCRYPTED_KEY1, "This is the 1st content to encrypt");
155110
156-
See the :sdk-examples-java-s3:`complete example <S3Encrypt.java>` on GitHub.

0 commit comments

Comments
 (0)