Skip to content

Commit d44f65c

Browse files
soo-awssoo-aws
committed
adding s3 encryption examples
1 parent 32f0573 commit d44f65c

File tree

5 files changed

+335
-1
lines changed

5 files changed

+335
-1
lines changed

‎doc_source/document-history.rst‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,10 @@ This topic describes important changes to the |sdk-java-dg| over the course of i
1616

1717
**This documentation was built on:** |today|
1818

19+
Nov 2, 2017
20+
Added cryptography examples for |S3| encryption client, including new topics:
21+
:doc:`examples-crypto` and :doc:`examples-crypto-kms` and :doc:`examples-crypto-masterkey`.
22+
1923
Apr 14, 2017
2024
Made a number of updates to the :doc:`examples-s3` section, including new topics:
2125
:doc:`examples-s3-access-permissions` and :doc:`examples-s3-website-configuration`.
@@ -139,4 +143,3 @@ May 9, 2014
139143
Sep 9, 2013
140144
This topic, *Document History*, tracks changes to the |sdk-java-dg|. It is intended as a
141145
companion to the release notes history.
142-

‎doc_source/examples-crypto-kms.rst‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
2+
3+
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0
4+
International License (the "License"). You may not use this file except in compliance with the
5+
License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/.
6+
7+
This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
8+
either express or implied. See the License for the specific language governing permissions and
9+
limitations under the License.
10+
11+
###################################################
12+
|S3| Client-Side Encryption with |KMS| Managed Keys
13+
###################################################
14+
15+
.. meta::
16+
:description: How to use the cryptography configuration settings for the AWS SDK for Java
17+
:keywords: cryptography, encryption, example code
18+
19+
The following examples use the
20+
:aws-java-class:`AmazonS3EncryptionClientBuilder <services/s3/AmazonS3EncryptionClientBuilder>`
21+
to create an |S3| client with client-side encryption enabled. Once configured,
22+
any object you upload to |S3| using this client
23+
will be encrypted. Any objects you get from |S3| using this client will automatically
24+
be decrypted.
25+
26+
.. note::
27+
The examples here demonstrate using the |S3| client-side
28+
encryption with |KMS| managed keys. To learn how to use encryption with your own keys,
29+
see the :doc:`examples-crypto-masterkey` topic.
30+
31+
You can choose from three encryption modes when enabling client-side |S3| encryption.
32+
The sections below show how to enable each type. To learn which algorithms each mode uses,
33+
see :aws-java-class:`CryptoMode <services/s3/model/CryptoMode>` definition.
34+
35+
36+
Required Imports
37+
================
38+
39+
Import the following libraries for the examples on this page.
40+
41+
**Imports**
42+
43+
.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java
44+
:lines: 16-31
45+
:language: java
46+
47+
.. _encryption-only:
48+
49+
Encryption only Mode
50+
====================
51+
52+
This is the default mode, if no :classname:`CryptoMode` is not specified. To use |KMS|
53+
managed key for encryption, pass the |KMS| key ID or alias to the
54+
:aws-java-class:`KMSEncryptionMaterialsProvider` constructor.
55+
56+
**Code**
57+
58+
.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java
59+
:lines: 237-243
60+
:dedent: 8
61+
:language: java
62+
63+
You can retrieve the object with the same client.
64+
65+
**Code**
66+
67+
.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java
68+
:lines: 249
69+
:dedent: 8
70+
:language: java
71+
72+
See the :sdk-examples-java-s3:`complete example <S3Encrypt.java>`.
73+
74+
.. _authenticated-encryption:
75+
76+
Authenticated Encryption Mode
77+
=============================
78+
79+
When :classname:`AuthenticatedEncryption` mode is used, an improved key wrapping algorithm is applied
80+
applied during encryption. When decrypting in this mode, the algorithm is able to verify the integrity
81+
of the decrypted object and throw an exception if the check fails.
82+
To get more details about how authenticated encryption works, see the
83+
:blog:`Amazon S3 Client-Side Authenticated Encryption <developer/amazon-s3-client-side-authenticated-encryption>`
84+
blog post.
85+
86+
To use client-side authenticated encryption, two steps are required:
87+
88+
#. Include the latest `Bouncy Castle jar <https://www.bouncycastle.org/latest_releases.html>`_
89+
in the classpath.
90+
#. Explicitly specify the cryptographic mode of authenticated encryption when
91+
instantiating an S3 encryption client.
92+
93+
Use the :aws-java-class:`CryptoMode <service/s3/model/CryptoMode>` to specify
94+
:classname:`AuthenticatedEncryption`.
95+
96+
**Code**
97+
98+
.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java
99+
:lines: 257-263
100+
:dedent: 8
101+
:language: java
102+
103+
The :classname:`AuthenticatedEncryption` mode can retrieve unencrypted objects as well as
104+
objects encrypted with :classname:`EncryptionOnly` mode. This example shows the
105+
|S3| encryption client retrieving an unencrypted object.
106+
107+
**Code**
108+
109+
.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java
110+
:lines: 257-270
111+
:dedent: 8
112+
:language: java
113+
114+
See the :sdk-examples-java-s3:`complete example <S3Encrypt.java>`.
115+
116+
.. _strict-authenticated-encryption:
117+
118+
Strict Authenticated Encryption
119+
===============================
120+
121+
Use the :aws-java-class:`CryptoMode <service/s3/model/CryptoMode>` to specify
122+
:classname:`StrictAuthenticatedEncryption`.
123+
124+
**Code**
125+
126+
.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java
127+
:lines: 278-284
128+
:dedent: 8
129+
:language: java
130+
131+
In :classname:`StrictAuthenticatedEncryption` mode, the |S3| client will throw an
132+
exception when retrieving an object that was not encrypted using an
133+
authenticated mode.
134+
135+
**Code**
136+
137+
.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java
138+
:lines: 278-295
139+
:dedent: 8
140+
:language: java
141+
142+
See the :sdk-examples-java-s3:`complete example <S3Encrypt.java>`.

‎doc_source/examples-crypto-masterkey.rst‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
2+
3+
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0
4+
International License (the "License"). You may not use this file except in compliance with the
5+
License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/.
6+
7+
This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
8+
either express or implied. See the License for the specific language governing permissions and
9+
limitations under the License.
10+
11+
##########################################################
12+
|S3| Client-Side Encryption with Client Master Keys
13+
##########################################################
14+
15+
.. meta::
16+
:description: How to use the cryptography configuration settings for the AWS SDK for Java
17+
:keywords: cryptography, encryption, example code
18+
19+
The following examples use the
20+
:aws-java-class:`AmazonS3EncryptionClientBuilder <services/s3/AmazonS3EncryptionClientBuilder>`
21+
to create an |S3| client with client-side encryption enabled. Once configured,
22+
any object you upload to |S3| using this client
23+
will be encrypted. Any objects you get from |S3| using this client will automatically
24+
be decrypted.
25+
26+
.. note::
27+
The examples here demonstrate using the |S3| client-side
28+
encryption with customer managed client master keys. To learn how to use encryption
29+
with |KMS| managed keys, see the :doc:`examples-crypto-kms` topic.
30+
31+
You can choose from three encryption modes when enabling client-side |S3| encryption.
32+
The sections below show how to enable each type. To learn which algorithms each mode uses,
33+
see :aws-java-class:`CryptoMode <services/s3/model/CryptoMode>` definition.
34+
35+
Required Imports
36+
================
37+
38+
Import the following libraries for the examples on this page.
39+
40+
**Imports**
41+
42+
.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java
43+
:lines: 16-24,26-31
44+
:language: java
45+
46+
.. _encryption-only:
47+
48+
Encryption only Mode
49+
====================
50+
51+
This is the default mode, if no :classname:`CryptoMode` is not specified. To use a
52+
symmetric key for encryption, pass the symmetric key to the
53+
:aws-java-class:`EncryptionMaterials` constructor. The example below uses
54+
the Java class :class:`KeyGenerator` to generate a symmetric private key.
55+
56+
**Code**
57+
58+
.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java
59+
:lines: 198-204
60+
:dedent: 8
61+
:language: java
62+
63+
To use an asymmetric key, simply pass the key pair to the same class
64+
:aws-java-class:`EncryptionMaterials`. The example below uses the
65+
:class:`KeyPairGenerator` class to generate a key pair.
66+
67+
**Code**
68+
69+
.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java
70+
:lines: 217-223
71+
:dedent: 8
72+
:language: java
73+
74+
You can retrieve the object with the same client.
75+
76+
**Code**
77+
78+
.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java
79+
:lines: 229
80+
:dedent: 8
81+
:language: java
82+
83+
See the :sdk-examples-java-s3:`complete example <S3Encrypt.java>`.
84+
85+
.. _authenticated-encryption:
86+
87+
Authenticated Encryption Mode
88+
=============================
89+
90+
When :classname:`AuthenticatedEncryption` mode is used, an improved key wrapping algorithm is applied
91+
applied during encryption. When decrypting in this mode, the algorithm is able to verify the integrity
92+
of the decrypted object and throw an exception if the check fails.
93+
To get more details about how authenticated encryption works, see the
94+
:blog:`Amazon S3 Client-Side Authenticated Encryption <developer/amazon-s3-client-side-authenticated-encryption>`
95+
blog post.
96+
97+
To use client-side authenticated encryption, two steps are required:
98+
99+
#. Include the latest `Bouncy Castle jar <https://www.bouncycastle.org/latest_releases.html>`_
100+
in the classpath.
101+
#. Explicitly specify the cryptographic mode of authenticated encryption when
102+
instantiating an S3 encryption client.
103+
104+
Use the :aws-java-class:`CryptoMode <service/s3/model/CryptoMode>` to specify
105+
:classname:`AuthenticatedEncryption`.
106+
107+
**Code**
108+
109+
.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java
110+
:lines: 67-72
111+
:dedent: 8
112+
:language: java
113+
114+
The :classname:`AuthenticatedEncryption` mode can retrieve unencrypted objects as well as
115+
objects encrypted with :classname:`EncryptionOnly` mode. This example shows the
116+
|S3| encryption client retrieving an unencrypted object.
117+
118+
**Code**
119+
120+
.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java
121+
:lines: 66-79
122+
:dedent: 8
123+
:language: java
124+
125+
See the :sdk-examples-java-s3:`complete example <S3Encrypt.java>`.
126+
127+
.. _strict-authenticated-encryption:
128+
129+
Strict Authenticated Encryption
130+
===============================
131+
132+
Use the :aws-java-class:`CryptoMode <service/s3/model/CryptoMode>` to specify
133+
:classname:`StrictAuthenticatedEncryption`.
134+
135+
**Code**
136+
137+
.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java
138+
:lines: 132-137
139+
:dedent: 8
140+
:language: java
141+
142+
In :classname:`StrictAuthenticatedEncryption`, the |S3| client will throw an
143+
exception when retrieving an object that was not encrypted using an
144+
authenticated mode.
145+
146+
**Code**
147+
148+
.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java
149+
:lines: 131-149
150+
:dedent: 8
151+
:language: java
152+
153+
See the :sdk-examples-java-s3:`complete example <S3Encrypt.java>`.

‎doc_source/examples-crypto.rst‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
2+
3+
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0
4+
International License (the "License"). You may not use this file except in compliance with the
5+
License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/.
6+
7+
This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
8+
either express or implied. See the License for the specific language governing permissions and
9+
limitations under the License.
10+
11+
#################################
12+
Using |S3| Client-Side Encryption
13+
#################################
14+
15+
.. meta::
16+
:description: How to use the cryptography configuration settings for the AWS SDK for Java
17+
:keywords: cryptography, encryption, example code
18+
19+
Encrypting data using the |S3| encryption client is one way you can provide an
20+
additional layer of protection for sensitive information you store in |S3|.
21+
If you are new to cryptography,
22+
see the :KMS-dg:`Cryptography Basics <crypto-intro>` in the |KMS-dg| for a basic overview of
23+
cryptography terms and algorithms.
24+
25+
.. include:: includes/examples-note.txt
26+
27+
.. toctree::
28+
:titlesonly:
29+
:maxdepth: 1
30+
31+
examples-crypto-masterkey
32+
examples-crypto-kms
33+
34+
For information about cryptography support across all AWS SDKs, see
35+
:AWS-gr:`AWS SDK Support for Amazon S3 Client-Side Encryption <aws_sdk_cryptography>` in the |AWS-gr|.

‎doc_source/examples-s3.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,3 +31,4 @@ This section provides examples of programming |S3|_ using the |sdk-java|_.
3131
examples-s3-bucket-policies
3232
examples-s3-transfermanager
3333
examples-s3-website-configuration
34+
examples-crypto

0 commit comments

Comments
 (0)