From b5a353d2aa8d4ffe54629ed0a033615e93d3c916 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Thu, 21 Nov 2019 12:29:55 -0500 Subject: [PATCH 01/83] fixed indent in example --- doc_source/examples-crypto-masterkey.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-crypto-masterkey.rst b/doc_source/examples-crypto-masterkey.rst index bebc77e..77b015c 100644 --- a/doc_source/examples-crypto-masterkey.rst +++ b/doc_source/examples-crypto-masterkey.rst @@ -56,7 +56,7 @@ the :class:`KeyGenerator` Java class generate a symmetric private key. **Code** .. literalinclude:: s3.java1.s3_encrypt.encryption_only.txt - :dedent: 8 + :dedent: 4 :language: java To use an asymmetric key or a key pair, simply pass the key pair to the same From 4ff91d9ba6ad337bed11bab9d8a82fd9aea85db6 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Thu, 21 Nov 2019 14:46:04 -0500 Subject: [PATCH 02/83] fixed indent in example --- doc_source/examples-crypto-masterkey.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/examples-crypto-masterkey.rst b/doc_source/examples-crypto-masterkey.rst index 77b015c..5ae4458 100644 --- a/doc_source/examples-crypto-masterkey.rst +++ b/doc_source/examples-crypto-masterkey.rst @@ -120,7 +120,7 @@ objects encrypted with :classname:`EncryptionOnly` mode. The following example s **Code** .. literalinclude:: s3.java1.s3_encrypt.authenticated_encryption.txt - :dedent: 8 + :dedent: 4 :language: java See the :sdk-examples-java-s3:`complete example ` on GitHub. @@ -150,7 +150,7 @@ authenticated mode. **Code** .. literalinclude:: s3.java1.s3_encrypt.strict_authenticated_encryption.txt - :dedent: 8 + :dedent: 4 :language: java See the :sdk-examples-java-s3:`complete example ` on GitHub. From 97c509908693a1584f0e11c08d80c46bb7c12342 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Fri, 22 Nov 2019 10:17:38 -0500 Subject: [PATCH 03/83] added POM depend tip --- doc_source/setup-project-maven.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc_source/setup-project-maven.rst b/doc_source/setup-project-maven.rst index d71d415..e976f37 100644 --- a/doc_source/setup-project-maven.rst +++ b/doc_source/setup-project-maven.rst @@ -130,6 +130,8 @@ declare it in your :file:`pom.xml` like this: +.. tip:: You can refer to the AWS Code Catalog to learn what dependencies to use for a given AWS service. Refer to the POM file under a specific service example. +For example, if you are interested in the dependencies for the AWS S3 service, see the :sdk-examples-java-s3:`complete example ` on GitHub. (Look at the pom under /java/example_code/s3). Build your project ================== From 8b315f06d0735ea0cf23c553d6690a29f4618834 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Fri, 22 Nov 2019 10:29:44 -0500 Subject: [PATCH 04/83] added POM depend tip --- doc_source/setup-project-maven.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/setup-project-maven.rst b/doc_source/setup-project-maven.rst index e976f37..fe8d041 100644 --- a/doc_source/setup-project-maven.rst +++ b/doc_source/setup-project-maven.rst @@ -111,6 +111,8 @@ component. +.. tip:: You can also refer to the AWS Code Catalog to learn what dependencies to use for a given AWS service. Refer to the POM file under a specific service example. +For example, if you are interested in the dependencies for the AWS S3 service, see the :sdk-examples-java-s3:`complete example ` on GitHub. (Look at the pom under /java/example_code/s3). .. _configuring-maven-entire-sdk: @@ -130,8 +132,6 @@ declare it in your :file:`pom.xml` like this: -.. tip:: You can refer to the AWS Code Catalog to learn what dependencies to use for a given AWS service. Refer to the POM file under a specific service example. -For example, if you are interested in the dependencies for the AWS S3 service, see the :sdk-examples-java-s3:`complete example ` on GitHub. (Look at the pom under /java/example_code/s3). Build your project ================== From 385258d9243fb4807bf78a8623df23abdf8d722c Mon Sep 17 00:00:00 2001 From: scmacdon Date: Fri, 22 Nov 2019 10:56:35 -0500 Subject: [PATCH 05/83] added POM depend tip --- doc_source/setup-project-maven.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/setup-project-maven.rst b/doc_source/setup-project-maven.rst index fe8d041..8fadd1d 100644 --- a/doc_source/setup-project-maven.rst +++ b/doc_source/setup-project-maven.rst @@ -111,7 +111,7 @@ component. -.. tip:: You can also refer to the AWS Code Catalog to learn what dependencies to use for a given AWS service. Refer to the POM file under a specific service example. +You can also refer to the *AWS Code Catalog* to learn what dependencies to use for a given AWS service. Refer to the POM file under a specific service example. For example, if you are interested in the dependencies for the AWS S3 service, see the :sdk-examples-java-s3:`complete example ` on GitHub. (Look at the pom under /java/example_code/s3). .. _configuring-maven-entire-sdk: From 92faee23d3cfe6b5c51b0b77cb67610891af5f3b Mon Sep 17 00:00:00 2001 From: scmacdon Date: Fri, 22 Nov 2019 11:52:58 -0500 Subject: [PATCH 06/83] updated cred info --- doc_source/credentials.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/credentials.rst b/doc_source/credentials.rst index 291a869..50fbede 100644 --- a/doc_source/credentials.rst +++ b/doc_source/credentials.rst @@ -59,10 +59,10 @@ class. The default credential provider chain looks for credentials in this order #. **Amazon ECS container credentials** |ndash| loaded from the |ECS| if the environment variable :envvar:`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` is set. The |sdk-java| uses the :aws-java-class:`ContainerCredentialsProvider ` to load these - credentials. + credentials. You can specify the IP address for this value. #. **Instance profile credentials** |ndash| used on EC2 instances, and delivered through the |EC2| metadata service. The |sdk-java| uses the :aws-java-class:`InstanceProfileCredentialsProvider - ` to load these credentials. + ` to load these credentials. You can specify the IP address for this value. .. note:: Instance profile credentials are used only if :envvar:`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` is not set. See From 685bc98e30a4f713f3205ef986fddebbd4edc9d7 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Fri, 22 Nov 2019 12:18:57 -0500 Subject: [PATCH 07/83] updated depen info --- doc_source/setup-project-gradle.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc_source/setup-project-gradle.rst b/doc_source/setup-project-gradle.rst index a4a6912..9a68542 100644 --- a/doc_source/setup-project-gradle.rst +++ b/doc_source/setup-project-gradle.rst @@ -43,6 +43,9 @@ use Gradle's improved POM support feature for importing bill of materials (BOM) Gradle will automatically resolve the correct version of your SDK dependencies using the information from the BOM. +You can also refer to the *AWS Code Catalog* to learn what dependencies to use for a given AWS service. Refer to the POM file under a specific service example. +For example, if you are interested in the dependencies for the AWS S3 service, see the :sdk-examples-java-s3:`complete example ` on GitHub. (Look at the pom under /java/example_code/s3). + Here's the complete :file:`build.gradle` file: .. code-block:: groovy From aa6ff9d75d7b4261cda423c902569927735af37a Mon Sep 17 00:00:00 2001 From: scmacdon Date: Fri, 22 Nov 2019 12:43:15 -0500 Subject: [PATCH 08/83] updated depen info --- doc_source/setup-project-gradle.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/setup-project-gradle.rst b/doc_source/setup-project-gradle.rst index 9a68542..1f36d79 100644 --- a/doc_source/setup-project-gradle.rst +++ b/doc_source/setup-project-gradle.rst @@ -44,7 +44,7 @@ Gradle will automatically resolve the correct version of your SDK dependencies u from the BOM. You can also refer to the *AWS Code Catalog* to learn what dependencies to use for a given AWS service. Refer to the POM file under a specific service example. -For example, if you are interested in the dependencies for the AWS S3 service, see the :sdk-examples-java-s3:`complete example ` on GitHub. (Look at the pom under /java/example_code/s3). +For example, if you are interested in the dependencies for the AWS S3 service (as shown in the previous dependencies example), see the :sdk-examples-java-s3:`complete example ` on GitHub. (Look at the pom under /java/example_code/s3). Here's the complete :file:`build.gradle` file: From 563a6604c37f6eac2e9b912647d8492abdecc365 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Thu, 28 Nov 2019 14:29:04 -0500 Subject: [PATCH 09/83] new file --- doc_source/examples-s3-objects.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-s3-objects.rst b/doc_source/examples-s3-objects.rst index e2dcc22..b37ed54 100644 --- a/doc_source/examples-s3-objects.rst +++ b/doc_source/examples-s3-objects.rst @@ -132,7 +132,7 @@ and the destination bucket and name. **Code** .. literalinclude:: example_code/s3/src/main/java/aws/example/s3/CopyObject.java - :lines: 46-52 + :lines: 50-63 :dedent: 8 :language: java From 66269f4c054f6e6c77afb3d7507e10e97b621385 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Thu, 28 Nov 2019 14:41:39 -0500 Subject: [PATCH 10/83] new file --- doc_source/examples-s3-objects.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/examples-s3-objects.rst b/doc_source/examples-s3-objects.rst index b37ed54..2cff970 100644 --- a/doc_source/examples-s3-objects.rst +++ b/doc_source/examples-s3-objects.rst @@ -121,7 +121,7 @@ Copy, Move, or Rename Objects You can copy an object from one bucket to another by using the |s3client| client's :methodname:`copyObject` method. It takes the name of the bucket to copy from, the object to copy, -and the destination bucket and name. +and the destination bucket name. **Imports** @@ -132,7 +132,7 @@ and the destination bucket and name. **Code** .. literalinclude:: example_code/s3/src/main/java/aws/example/s3/CopyObject.java - :lines: 50-63 + :lines: 48-64 :dedent: 8 :language: java From 8b735c1d65c7f6f91d416406cf05c876495d7d08 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Fri, 29 Nov 2019 10:03:47 -0500 Subject: [PATCH 11/83] modified code lines --- doc_source/examples-s3-bucket-policies.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-s3-bucket-policies.rst b/doc_source/examples-s3-bucket-policies.rst index d6335a1..f8b8e0c 100644 --- a/doc_source/examples-s3-bucket-policies.rst +++ b/doc_source/examples-s3-bucket-policies.rst @@ -41,7 +41,7 @@ You can set the bucket policy for a particular S3 bucket by: .. literalinclude:: example_code/s3/src/main/java/aws/example/s3/SetBucketPolicy.java :dedent: 8 - :lines: 81-88 + :lines: 81-86 :language: java From b809ecbe519a4e3670fd1a3af8a29ce4977e1993 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Tue, 3 Dec 2019 08:46:07 -0500 Subject: [PATCH 12/83] added new section --- doc_source/prog-services.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc_source/prog-services.rst b/doc_source/prog-services.rst index e623982..722f3c5 100644 --- a/doc_source/prog-services.rst +++ b/doc_source/prog-services.rst @@ -40,6 +40,7 @@ In 2018, AWS released |sdk-java| v2. For more AWS examples, see the `AWS SDK for Amazon DynamoDB Examples Amazon EC2 Examples AWS Identity and Access Management (IAM) Examples + Amazon Lambda Examples Amazon Pinpoint Examples Amazon S3 Examples Amazon SQS Examples From 8079902e9d43f863c4143e9e5cc98a02e37ea1cb Mon Sep 17 00:00:00 2001 From: scmacdon <57190223+scmacdon@users.noreply.github.com> Date: Tue, 3 Dec 2019 08:48:22 -0500 Subject: [PATCH 13/83] Create examples-lambda.rst --- doc_source/examples-lambda.rst | 106 +++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 doc_source/examples-lambda.rst diff --git a/doc_source/examples-lambda.rst b/doc_source/examples-lambda.rst new file mode 100644 index 0000000..d909c94 --- /dev/null +++ b/doc_source/examples-lambda.rst @@ -0,0 +1,106 @@ +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +################################################# +Invoking, Listing, and Deleting Lambda Functions +################################################# + +.. meta:: + :description: How to invoke, list, and delete a Lambda function by using the AWS SDK for Java 2.x. + :keywords: Amazon Lambda, AWS SDK for Java 2.x, Lambda code examples, + deleteFunction, invoke, listFunctions + + +This section provides examples of programming with the Lambda service client by using the AWS SDK for Java. + +.. contents:: + :local: + :depth: 1 + +.. _invoke-function: +Invoke a Lambda function +======================== + +You can invoke a Lambda function by creating a :aws-java-class:`LambdaClient ` +object and invoking its :methodname:`invoke` method. Create an :aws-java-class:`InvokeRequest ` +object to specify additional information such as the function name and the payload to pass to the Lambda function. Function names +appear as *arn:aws:lambda:us-west-2:555556330391:function:HelloFunction*. You can retrieve the value by looking at the function in the AWS Console. + +To pass payload data to a function, create a :aws-java-class:`SdkBytes ` +object that contains information. For example, in the following code example, notice the JSON data passed to the Lambda function. + +**Imports** + +.. literalinclude:: s3.java2.s3_object_operations.import.txt + :language: java + +**Code** + +The following code example demonstrates how to invoke a Lambda function. + +.. literalinclude:: s3.java2.s3_object_operations.upload.txt + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +.. _list-function: + +List Lambda functions +========================= + +Build a :aws-java-class:`LambdaClient ` +object and invoke its :methodname:`listFunctions` method. +This method returns a :aws-java-class:`ListFunctionsResponse ` object. +You can invoke this object's :methodname:`functions` method to return a list of :aws-java-class:`FunctionConfiguration ` objects. +You can iterate through the list to retrieve information about the functions. For example, the following Java code example shows how to get each function name. + + +**Imports** + +.. literalinclude:: s3.java2.s3_object_operations.import.txt + :language: java + +**Code** + +The following Java code example demonstrates how to retrieve a list of function names. + +.. literalinclude:: s3.java2.s3_object_operations.upload.txt + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +.. _delete-function: + +Delete a Lambda function +======================== + +Build a :aws-java-class:`LambdaClient ` +object and invoke its :methodname:`deleteFunction` method. +Create a :aws-java-class:`DeleteFunctionRequest ` +object and pass it to the :methodname:`deleteFunction` method. This object contains information such as the name of the function to delete. +Function names appear as *arn:aws:lambda:us-west-2:555556330391:function:HelloFunction*. You can retrieve the value by looking at the function in the AWS Console. + +**Imports** + +.. literalinclude:: s3.java2.s3_object_operations.import.txt + :language: java + +**Code** + +The following Java code demonstrates how to delete a Lambda function. + +.. literalinclude:: s3.java2.s3_object_operations.upload.txt + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + From 636965f51373aab4664d019518bf759a5013937b Mon Sep 17 00:00:00 2001 From: scmacdon <57190223+scmacdon@users.noreply.github.com> Date: Tue, 3 Dec 2019 08:49:17 -0500 Subject: [PATCH 14/83] Create lambda-examples.rst --- doc_source/lambda-examples.rst | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 doc_source/lambda-examples.rst diff --git a/doc_source/lambda-examples.rst b/doc_source/lambda-examples.rst new file mode 100644 index 0000000..d0cdacf --- /dev/null +++ b/doc_source/lambda-examples.rst @@ -0,0 +1,28 @@ +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +########################################## +Lambda Examples Using the |sdk-java| +########################################## + +.. meta:: + :description: Programming Amazon Lambda using the AWS SDK for Java 2.x + :keywords: AWS SDK for Java code examples + +This section provides examples of programming Lambda using the |sdk-java-v2|. + +.. include:: includes/complete-examples-note.txt + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Service Operations + From c5078e8f1f1124d41cd307a49a6d525949ea6503 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Tue, 3 Dec 2019 10:43:04 -0500 Subject: [PATCH 15/83] added new section --- doc_source/examples-lambda.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc_source/examples-lambda.rst b/doc_source/examples-lambda.rst index d909c94..516273d 100644 --- a/doc_source/examples-lambda.rst +++ b/doc_source/examples-lambda.rst @@ -26,15 +26,15 @@ This section provides examples of programming with the Lambda service client by .. _invoke-function: Invoke a Lambda function -======================== +======================== -You can invoke a Lambda function by creating a :aws-java-class:`LambdaClient ` +You can invoke a Lambda function by creating a :aws-java-class:`AWSLambda ` object and invoking its :methodname:`invoke` method. Create an :aws-java-class:`InvokeRequest ` object to specify additional information such as the function name and the payload to pass to the Lambda function. Function names appear as *arn:aws:lambda:us-west-2:555556330391:function:HelloFunction*. You can retrieve the value by looking at the function in the AWS Console. -To pass payload data to a function, create a :aws-java-class:`SdkBytes ` -object that contains information. For example, in the following code example, notice the JSON data passed to the Lambda function. +To pass payload data to a function, invoke the :aws-java-class:`InvokeRequest ` +object's :methodname:`withPayload` method and specify a String in JSON format, as shown in the following code example. **Imports** From 474d32e6bdeb8fb4cca6ec6071d470988a5e28ef Mon Sep 17 00:00:00 2001 From: scmacdon Date: Tue, 3 Dec 2019 10:56:55 -0500 Subject: [PATCH 16/83] added new section --- doc_source/examples-lambda.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc_source/examples-lambda.rst b/doc_source/examples-lambda.rst index 516273d..2549dee 100644 --- a/doc_source/examples-lambda.rst +++ b/doc_source/examples-lambda.rst @@ -26,9 +26,9 @@ This section provides examples of programming with the Lambda service client by .. _invoke-function: Invoke a Lambda function -======================== +======================== -You can invoke a Lambda function by creating a :aws-java-class:`AWSLambda ` +You can invoke a Lambda function by creating an :aws-java-class:`AWSLambda ` object and invoking its :methodname:`invoke` method. Create an :aws-java-class:`InvokeRequest ` object to specify additional information such as the function name and the payload to pass to the Lambda function. Function names appear as *arn:aws:lambda:us-west-2:555556330391:function:HelloFunction*. You can retrieve the value by looking at the function in the AWS Console. @@ -54,12 +54,12 @@ See the :sdk-examples-java-s3:`complete example ` on GitHub. .. _list-function: List Lambda functions -========================= +===================== -Build a :aws-java-class:`LambdaClient ` +Build an :aws-java-class:`AWSLambda ` object and invoke its :methodname:`listFunctions` method. -This method returns a :aws-java-class:`ListFunctionsResponse ` object. -You can invoke this object's :methodname:`functions` method to return a list of :aws-java-class:`FunctionConfiguration ` objects. +This method returns a :aws-java-class:`ListFunctionsResult ` object. +You can invoke this object's :methodname:`getFunctions` method to return a list of :aws-java-class:`FunctionConfiguration ` objects. You can iterate through the list to retrieve information about the functions. For example, the following Java code example shows how to get each function name. From 7f40b668cbfda7d161c7a719b9d7396e187af652 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Tue, 3 Dec 2019 11:13:07 -0500 Subject: [PATCH 17/83] added new section --- doc_source/examples-lambda.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-lambda.rst b/doc_source/examples-lambda.rst index 2549dee..90c3cd2 100644 --- a/doc_source/examples-lambda.rst +++ b/doc_source/examples-lambda.rst @@ -83,7 +83,7 @@ See the :sdk-examples-java-s3:`complete example ` on GitHub. Delete a Lambda function ======================== -Build a :aws-java-class:`LambdaClient ` +Build an :aws-java-class:`AWSLambda ` object and invoke its :methodname:`deleteFunction` method. Create a :aws-java-class:`DeleteFunctionRequest ` object and pass it to the :methodname:`deleteFunction` method. This object contains information such as the name of the function to delete. From 4e6efef2513b1053fcf6f4515c4f29f70210feac Mon Sep 17 00:00:00 2001 From: scmacdon Date: Tue, 3 Dec 2019 16:35:15 -0500 Subject: [PATCH 18/83] added an example --- doc_source/examples-ec2-regions-zones.rst | 29 +++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/doc_source/examples-ec2-regions-zones.rst b/doc_source/examples-ec2-regions-zones.rst index 4d93ba1..ea9de5c 100644 --- a/doc_source/examples-ec2-regions-zones.rst +++ b/doc_source/examples-ec2-regions-zones.rst @@ -68,6 +68,35 @@ objects that represent each Availability Zone. See the :sdk-examples-java-ec2:`complete example `. +Describing Accounts +================== + +To describe your account, call the |ec2client|'s :methodname:`describeAccountAttributes` +method. This method returns a :aws-java-class:`DescribeAccountAttributesResult ` object. +Invoke this objects :methodname:`getAccountAttributes` method to get a list of :aws-java-class:`AccountAttribute +` objects. You can iterate through the list to retrieve an +:aws-java-class:`AccountAttribute ` object. + +You can +get your account's attribute values by invoking the :aws-java-class:`AccountAttribute ` object's +:methodname:`getAttributeValues` method. This method returns a list of :aws-java-class:`AccountAttributeValue +` objects. You can iterate through this second list to display the value of attributes (see the following code example). + +**Imports** + +.. literalinclude:: ec2.java2.describe_region_and_zones.import.txt + :language: java + +**Code** + +.. literalinclude:: ec2.java2.describe_region_and_zones.region.txt + :dedent: 8 + :language: java + +See the :sdk-examples-java-ec2:`complete example ` on GitHub. + + + More Information ================ From 72772b25c207f35cee812211b28ed659ed3504a1 Mon Sep 17 00:00:00 2001 From: Paul Cornell Date: Wed, 4 Dec 2019 16:11:15 +0000 Subject: [PATCH 19/83] Periodic update 2019-12-04 08:11 PT. --- doc_source/conf.py | 2 +- doc_source/data-protection.rst | 46 ++++++++++++++++++++++++++++++++++ doc_source/index.rst | 1 + doc_source/security.rst | 31 +++++++++++++++++++++++ 4 files changed, 79 insertions(+), 1 deletion(-) create mode 100644 doc_source/data-protection.rst create mode 100644 doc_source/security.rst diff --git a/doc_source/conf.py b/doc_source/conf.py index 0737153..c8adbe8 100644 --- a/doc_source/conf.py +++ b/doc_source/conf.py @@ -121,7 +121,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'bizstyle' +html_theme = 'default' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/doc_source/data-protection.rst b/doc_source/data-protection.rst new file mode 100644 index 0000000..c315926 --- /dev/null +++ b/doc_source/data-protection.rst @@ -0,0 +1,46 @@ +.. Copyright 2010-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +##################################### +Data Protection in |SERVICENAMETITLE| +##################################### + +.. meta:: + :description: Learn how the AWS shared responsibility model applies to data protection in this AWS product or service. + :keywords: + +.. include:: common/_security-includes.txt + +|SERVICENAMESENTENCECASE| conforms to the `shared responsibility model `_, +which includes regulations and guidelines for data protection. |AWSlong| (|AWS|) is responsible for protecting the global infrastructure +that runs all the |AWS| services. |AWS| maintains control over data hosted on this infrastructure, including the security configuration +controls for handling customer content and personal data. |AWS| customers and APN partners, acting either as data controllers or data +processors, are responsible for any personal data that they put in the |AWS| Cloud. + +For data protection purposes, we recommend that you protect |AWS| account credentials and set up individual user accounts with +|IAMlong| (|IAM|), so that each user is given only the permissions necessary to fulfill their job duties. We also recommend that +you secure your data in the following ways: + +* Use multi-factor authentication (MFA) with each account. +* Use SSL/TLS to communicate with |AWS| resources. +* Set up API and user activity logging with |CTlong|. +* Use |AWS| encryption solutions, along with all default security controls within |AWS| services. +* Use advanced managed security services such as |MCElong|, which assists in discovering and securing personal data that + is stored in |S3|. + +We strongly recommend that you never put sensitive identifying information, such as your customers' account numbers, into +free-form fields such as a **Name** field. This includes when you work with |SERVICENAME| or other |AWS| services +using the console, API, |CLI|, or |AWS| SDKs. Any data that you enter into |SERVICENAME| or other services might get picked up +for inclusion in diagnostic logs. When you provide a URL to an external server, don't include credentials information in the URL +to validate your request to that server. + +For more information about data protection, see the +`AWS Shared Responsibility Model and GDPR `_ +blog post on the *AWS Security Blog*. \ No newline at end of file diff --git a/doc_source/index.rst b/doc_source/index.rst index 4c68e99..59814c8 100644 --- a/doc_source/index.rst +++ b/doc_source/index.rst @@ -24,6 +24,7 @@ getting-started basics Code Examples + Security document-history .. include:: about-aws.txt diff --git a/doc_source/security.rst b/doc_source/security.rst new file mode 100644 index 0000000..827ac76 --- /dev/null +++ b/doc_source/security.rst @@ -0,0 +1,31 @@ +.. Copyright 2010-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +############################### +Security for |SERVICENAMETITLE| +############################### + +.. meta:: + :description: Provides security-related information for this AWS product or service. + :keywords: + +.. include:: common/_security-includes.txt + +.. include:: common/_security.txt + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + Data Protection + Identity and Access Management + Compliance Validation + Resilience + Infrastructure Security From feecc24cdcc61b4fdc5af0ea5cbe8241eac4ff2c Mon Sep 17 00:00:00 2001 From: scmacdon Date: Wed, 11 Dec 2019 12:08:51 -0500 Subject: [PATCH 20/83] updated content --- doc_source/examples-lambda.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-lambda.rst b/doc_source/examples-lambda.rst index 90c3cd2..90b6c73 100644 --- a/doc_source/examples-lambda.rst +++ b/doc_source/examples-lambda.rst @@ -38,7 +38,7 @@ object's :methodname:`withPayload` method and specify a String in JSON format, a **Imports** -.. literalinclude:: s3.java2.s3_object_operations.import.txt +.. literalinclude:: lambda.java1.invoke.import.txt :language: java **Code** From ed85c0635c7e009b87e3af8e8a8b761cf2ab3cce Mon Sep 17 00:00:00 2001 From: scmacdon Date: Wed, 11 Dec 2019 12:35:49 -0500 Subject: [PATCH 21/83] updated content --- doc_source/examples-lambda.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-lambda.rst b/doc_source/examples-lambda.rst index 90b6c73..90c3cd2 100644 --- a/doc_source/examples-lambda.rst +++ b/doc_source/examples-lambda.rst @@ -38,7 +38,7 @@ object's :methodname:`withPayload` method and specify a String in JSON format, a **Imports** -.. literalinclude:: lambda.java1.invoke.import.txt +.. literalinclude:: s3.java2.s3_object_operations.import.txt :language: java **Code** From b7748a026c899e0903883d5c84307ebd8eca5db0 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Wed, 11 Dec 2019 12:46:41 -0500 Subject: [PATCH 22/83] updated content --- doc_source/examples-lambda.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-lambda.rst b/doc_source/examples-lambda.rst index 90c3cd2..90b6c73 100644 --- a/doc_source/examples-lambda.rst +++ b/doc_source/examples-lambda.rst @@ -38,7 +38,7 @@ object's :methodname:`withPayload` method and specify a String in JSON format, a **Imports** -.. literalinclude:: s3.java2.s3_object_operations.import.txt +.. literalinclude:: lambda.java1.invoke.import.txt :language: java **Code** From 354a91332ddbd975547e366ba737cf9267c82d62 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Wed, 11 Dec 2019 13:24:38 -0500 Subject: [PATCH 23/83] updated content --- doc_source/examples-lambda.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc_source/examples-lambda.rst b/doc_source/examples-lambda.rst index 90b6c73..4044ba5 100644 --- a/doc_source/examples-lambda.rst +++ b/doc_source/examples-lambda.rst @@ -45,7 +45,7 @@ object's :methodname:`withPayload` method and specify a String in JSON format, a The following code example demonstrates how to invoke a Lambda function. -.. literalinclude:: s3.java2.s3_object_operations.upload.txt +.. literalinclude:: lambda.java1.invoke.main.txt :language: java See the :sdk-examples-java-s3:`complete example ` on GitHub. @@ -65,14 +65,14 @@ You can iterate through the list to retrieve information about the functions. Fo **Imports** -.. literalinclude:: s3.java2.s3_object_operations.import.txt +.. literalinclude:: lambda.java1.list.import.txt :language: java **Code** The following Java code example demonstrates how to retrieve a list of function names. -.. literalinclude:: s3.java2.s3_object_operations.upload.txt +.. literalinclude:: lambda.java1.list.main.txt :language: java See the :sdk-examples-java-s3:`complete example ` on GitHub. @@ -91,14 +91,14 @@ Function names appear as *arn:aws:lambda:us-west-2:555556330391:function:HelloFu **Imports** -.. literalinclude:: s3.java2.s3_object_operations.import.txt +.. literalinclude:: lambda.java1.delete.import.txt :language: java **Code** The following Java code demonstrates how to delete a Lambda function. -.. literalinclude:: s3.java2.s3_object_operations.upload.txt +.. literalinclude:: lambda.java1.delete.main.txt :language: java See the :sdk-examples-java-s3:`complete example ` on GitHub. From 72b59b77783bdec08fd176bee9f0ab678e459df3 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Wed, 11 Dec 2019 13:56:47 -0500 Subject: [PATCH 24/83] updated content --- doc_source/examples-lambda.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/doc_source/examples-lambda.rst b/doc_source/examples-lambda.rst index 4044ba5..a228b81 100644 --- a/doc_source/examples-lambda.rst +++ b/doc_source/examples-lambda.rst @@ -48,7 +48,8 @@ The following code example demonstrates how to invoke a Lambda function. .. literalinclude:: lambda.java1.invoke.main.txt :language: java -See the :sdk-examples-java-s3:`complete example ` on GitHub. +See the complete example on `Github +`_. .. _list-function: @@ -75,7 +76,8 @@ The following Java code example demonstrates how to retrieve a list of function .. literalinclude:: lambda.java1.list.main.txt :language: java -See the :sdk-examples-java-s3:`complete example ` on GitHub. +See the complete example on `Github +`_. .. _delete-function: @@ -101,6 +103,7 @@ The following Java code demonstrates how to delete a Lambda function. .. literalinclude:: lambda.java1.delete.main.txt :language: java -See the :sdk-examples-java-s3:`complete example ` on GitHub. +See the complete example on `Github +`_. From cb21064230be42eb80b9b72206dfed85275de4e2 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Thu, 12 Dec 2019 17:26:36 -0500 Subject: [PATCH 25/83] updated content --- doc_source/examples-lambda.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-lambda.rst b/doc_source/examples-lambda.rst index a228b81..bb4b7d0 100644 --- a/doc_source/examples-lambda.rst +++ b/doc_source/examples-lambda.rst @@ -71,7 +71,7 @@ You can iterate through the list to retrieve information about the functions. Fo **Code** -The following Java code example demonstrates how to retrieve a list of function names. +The following Java code example demonstrates how to retrieve a list of Lambda function names. .. literalinclude:: lambda.java1.list.main.txt :language: java From c91ae76ed2631ac5974d140cafbc13a9899867be Mon Sep 17 00:00:00 2001 From: scmacdon Date: Fri, 13 Dec 2019 11:14:30 -0500 Subject: [PATCH 26/83] updated content --- doc_source/setup-credentials.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/doc_source/setup-credentials.rst b/doc_source/setup-credentials.rst index c9caf99..858a1eb 100644 --- a/doc_source/setup-credentials.rst +++ b/doc_source/setup-credentials.rst @@ -48,6 +48,31 @@ Once you have set your AWS credentials using one of these methods, they will be by the |sdk-java| by using the default credential provider chain. For further information about working with AWS credentials in your Java applications, see :doc:`credentials`. + +.. _refresh-credentials: +Refreshing IMDS credentials +=========================== + +The|sdk-java| supports opt-in refreshing IMDS credentials in the background every 1 minute, regardless of the credential expiration time. +That’s frequent enough that a relatively short outage should not impact the perceived AWS availability. + +.. code:: java + + // Refresh credentials using a background thread, automatically every minute. This will log an error if IMDS is down during +// a refresh, but customer's service calls will continue using the cached credentials until the credentials are refreshed +// again one minute later. + +InstanceProfileCredentialsProvider credentials = + InstanceProfileCredentialsProvider.createAsyncRefreshingProvider(true); + +AmazonS3Client.builder() + .withCredentials(credentials) + .build(); + +// This is new: When the customer is done with the credentials provider, they must close it to release the background thread. +credentials.close(); + + .. _setup-credentials-setting-region: Setting the AWS Region From 8aeffd909c780cd30603615152a9a78c5777394c Mon Sep 17 00:00:00 2001 From: scmacdon Date: Fri, 13 Dec 2019 11:26:07 -0500 Subject: [PATCH 27/83] updated content --- doc_source/setup-credentials.rst | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/doc_source/setup-credentials.rst b/doc_source/setup-credentials.rst index 858a1eb..16d22e4 100644 --- a/doc_source/setup-credentials.rst +++ b/doc_source/setup-credentials.rst @@ -56,21 +56,22 @@ Refreshing IMDS credentials The|sdk-java| supports opt-in refreshing IMDS credentials in the background every 1 minute, regardless of the credential expiration time. That’s frequent enough that a relatively short outage should not impact the perceived AWS availability. -.. code:: java - - // Refresh credentials using a background thread, automatically every minute. This will log an error if IMDS is down during -// a refresh, but customer's service calls will continue using the cached credentials until the credentials are refreshed -// again one minute later. - -InstanceProfileCredentialsProvider credentials = - InstanceProfileCredentialsProvider.createAsyncRefreshingProvider(true); - -AmazonS3Client.builder() - .withCredentials(credentials) - .build(); - -// This is new: When the customer is done with the credentials provider, they must close it to release the background thread. -credentials.close(); +.. code-block:: java + :linenos: + +1. // Refresh credentials using a background thread, automatically every minute. This will log an error if IMDS is down during +2. // a refresh, but customer's service calls will continue using the cached credentials until the credentials are refreshed +3. // again one minute later. +4. +5. InstanceProfileCredentialsProvider credentials = +6. InstanceProfileCredentialsProvider.createAsyncRefreshingProvider(true); +7. +8. AmazonS3Client.builder() +9. .withCredentials(credentials) +10. .build(); +11. +12. // This is new: When the customer is done with the credentials provider, they must close it to release the background thread. +23. credentials.close(); .. _setup-credentials-setting-region: From 022a8b82fa124a0f244cc993ab1f7a2e430eb213 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Fri, 13 Dec 2019 11:29:05 -0500 Subject: [PATCH 28/83] updated content --- doc_source/setup-credentials.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/doc_source/setup-credentials.rst b/doc_source/setup-credentials.rst index 16d22e4..cc4043b 100644 --- a/doc_source/setup-credentials.rst +++ b/doc_source/setup-credentials.rst @@ -59,19 +59,19 @@ That’s frequent enough that a relatively short outage should not impact the pe .. code-block:: java :linenos: -1. // Refresh credentials using a background thread, automatically every minute. This will log an error if IMDS is down during -2. // a refresh, but customer's service calls will continue using the cached credentials until the credentials are refreshed -3. // again one minute later. -4. -5. InstanceProfileCredentialsProvider credentials = -6. InstanceProfileCredentialsProvider.createAsyncRefreshingProvider(true); -7. -8. AmazonS3Client.builder() -9. .withCredentials(credentials) -10. .build(); -11. -12. // This is new: When the customer is done with the credentials provider, they must close it to release the background thread. -23. credentials.close(); + 1. // Refresh credentials using a background thread, automatically every minute. This will log an error if IMDS is down during + 2. // a refresh, but your service calls will continue using the cached credentials until the credentials are refreshed + 3. // again one minute later. + 4. + 5. InstanceProfileCredentialsProvider credentials = + 6. InstanceProfileCredentialsProvider.createAsyncRefreshingProvider(true); + 7. + 8. AmazonS3Client.builder() + 9. .withCredentials(credentials) + 10. .build(); + 11. + 12. // This is new: When you are done with the credentials provider, you must close it to release the background thread. + 23. credentials.close(); .. _setup-credentials-setting-region: From 126940353293d290df492178e5ef3d36f3acac57 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Fri, 13 Dec 2019 11:39:21 -0500 Subject: [PATCH 29/83] updated content --- doc_source/setup-credentials.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/setup-credentials.rst b/doc_source/setup-credentials.rst index cc4043b..12b1e95 100644 --- a/doc_source/setup-credentials.rst +++ b/doc_source/setup-credentials.rst @@ -53,7 +53,7 @@ working with AWS credentials in your Java applications, see :doc:`credentials`. Refreshing IMDS credentials =========================== -The|sdk-java| supports opt-in refreshing IMDS credentials in the background every 1 minute, regardless of the credential expiration time. +The |sdk-java| supports opt-in refreshing IMDS credentials in the background every 1 minute, regardless of the credential expiration time. That’s frequent enough that a relatively short outage should not impact the perceived AWS availability. .. code-block:: java From 1044384cbcda0308b818757a8fada56833c14187 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Fri, 13 Dec 2019 12:11:31 -0500 Subject: [PATCH 30/83] updated content --- doc_source/setup-credentials.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc_source/setup-credentials.rst b/doc_source/setup-credentials.rst index 12b1e95..c58b718 100644 --- a/doc_source/setup-credentials.rst +++ b/doc_source/setup-credentials.rst @@ -54,7 +54,8 @@ Refreshing IMDS credentials =========================== The |sdk-java| supports opt-in refreshing IMDS credentials in the background every 1 minute, regardless of the credential expiration time. -That’s frequent enough that a relatively short outage should not impact the perceived AWS availability. +This allows you to refresh credentials more frequently and reduces the chance that not reaching IMDS impacts +the perceived AWS availability. .. code-block:: java :linenos: From 5aae0ca2d3de386614a1045b09734c797cba6c70 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Fri, 13 Dec 2019 12:12:39 -0500 Subject: [PATCH 31/83] updated content --- doc_source/setup-credentials.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/setup-credentials.rst b/doc_source/setup-credentials.rst index c58b718..127b3b3 100644 --- a/doc_source/setup-credentials.rst +++ b/doc_source/setup-credentials.rst @@ -72,7 +72,7 @@ the perceived AWS availability. 10. .build(); 11. 12. // This is new: When you are done with the credentials provider, you must close it to release the background thread. - 23. credentials.close(); + 13. credentials.close(); .. _setup-credentials-setting-region: From 50ace1ffa1597957ce8efe6ba6de2fa3c09f3a10 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Thu, 2 Jan 2020 13:56:48 -0500 Subject: [PATCH 32/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 5caefc1..1d2e909 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -110,6 +110,30 @@ update. See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. +Use the DynamoDBMapper class +================================== + +The |sdk-java|_ provides a :aws-java-class:`DynamoDBMapper ` class, +allowing you to map your client-side classes to Amazon DynamoDB tables. To use the :aws-java-class:`DynamoDBMapper ` class, +you define the relationship between items in a DynamoDB table and their corresponding object instances in your code. +The :aws-java-class:`DynamoDBMapper ` class enables you to access your tables; perform various create, read, update, and delete (CRUD) operations; and execute queries. + +.. note:: The :aws-java-class:`DynamoDBMapper ` class does not allow you to create, update, or delete tables. + +**Imports** + +.. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/UpdateItem.java + :lines: 15-22 + :language: java + +**Code** + +.. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/UpdateItem.java + :lines: 82-105 + :dedent: 8 + :language: java + +See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. More Info ========= From cf85c3b39ebecbc9da17ed3868af8861e3801c0b Mon Sep 17 00:00:00 2001 From: scmacdon Date: Thu, 2 Jan 2020 14:37:36 -0500 Subject: [PATCH 33/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 1d2e909..521bba9 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -128,6 +128,11 @@ The :aws-java-class:`DynamoDBMapper ` in the |ddb-dg|. + +After the content is added to the table, notice that an item is loaded by using the +Partition Key and Sort Key. Then the *Awards* item is updated. .. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/UpdateItem.java :lines: 82-105 :dedent: 8 From cecc97f3a3275f1599f66b610f9f722d50bcfd95 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Thu, 2 Jan 2020 14:49:30 -0500 Subject: [PATCH 34/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 521bba9..77ca384 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -132,7 +132,8 @@ The following Java code example shows you how to add content to the Music table. :ddb-dg:`Create a Table ` in the |ddb-dg|. After the content is added to the table, notice that an item is loaded by using the -Partition Key and Sort Key. Then the *Awards* item is updated. +*Partition* and *Sort* keys. Then the *Awards* item is updated. + .. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/UpdateItem.java :lines: 82-105 :dedent: 8 From 196e090bbec1a1831b3de6cd409f5dbc74a1d449 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Thu, 2 Jan 2020 15:00:32 -0500 Subject: [PATCH 35/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 77ca384..75d24e1 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -129,9 +129,7 @@ The :aws-java-class:`DynamoDBMapper ` in the |ddb-dg|. - -After the content is added to the table, notice that an item is loaded by using the +:ddb-dg:`Create a Table ` in the |ddb-dg|. After the content is added to the table, notice that an item is loaded by using the *Partition* and *Sort* keys. Then the *Awards* item is updated. .. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/UpdateItem.java From ddd0b6babdf0b0dd6067b63fb2f26009b3e035bc Mon Sep 17 00:00:00 2001 From: scmacdon Date: Thu, 2 Jan 2020 15:04:36 -0500 Subject: [PATCH 36/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 75d24e1..7cc66dd 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -128,7 +128,7 @@ The :aws-java-class:`DynamoDBMapper ` in the |ddb-dg|. After the content is added to the table, notice that an item is loaded by using the *Partition* and *Sort* keys. Then the *Awards* item is updated. From fffff9b87b31cbb52c858a5e42601c2b13242551 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Thu, 2 Jan 2020 15:26:23 -0500 Subject: [PATCH 37/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 7cc66dd..98c336d 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -128,8 +128,9 @@ The :aws-java-class:`DynamoDBMapper ` in the |ddb-dg|. After the content is added to the table, notice that an item is loaded by using the +The following Java code example shows you how to add content to the *Music* table by using the :aws-java-class:`DynamoDBMapper ` class. +For information on creating the *Music* table, see :ddb-dg:`Create a Table ` in the |ddb-dg|. +After the content is added to the table, notice that an item is loaded by using the *Partition* and *Sort* keys. Then the *Awards* item is updated. .. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/UpdateItem.java From 50d89750ca61acbbe8e88f818204ccad411644ac Mon Sep 17 00:00:00 2001 From: scmacdon Date: Thu, 2 Jan 2020 15:46:01 -0500 Subject: [PATCH 38/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 98c336d..953cce1 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -115,7 +115,7 @@ Use the DynamoDBMapper class The |sdk-java|_ provides a :aws-java-class:`DynamoDBMapper ` class, allowing you to map your client-side classes to Amazon DynamoDB tables. To use the :aws-java-class:`DynamoDBMapper ` class, -you define the relationship between items in a DynamoDB table and their corresponding object instances in your code. +you define the relationship between items in a DynamoDB table and their corresponding object instances in your code by using annotations (as shown in the following code example). The :aws-java-class:`DynamoDBMapper ` class enables you to access your tables; perform various create, read, update, and delete (CRUD) operations; and execute queries. .. note:: The :aws-java-class:`DynamoDBMapper ` class does not allow you to create, update, or delete tables. From cef3adc13f4c1669bc950036e0fe729e2b1a18c6 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Thu, 2 Jan 2020 15:52:58 -0500 Subject: [PATCH 39/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 953cce1..1649586 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -138,7 +138,7 @@ After the content is added to the table, notice that an item is loaded by using :dedent: 8 :language: java -See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. +See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. More Info ========= From d956354229e9a7c28f67e52b784782c7628ec669 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Fri, 3 Jan 2020 10:49:50 -0500 Subject: [PATCH 40/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 1649586..4affebb 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -122,8 +122,8 @@ The :aws-java-class:`DynamoDBMapper Date: Fri, 3 Jan 2020 11:05:15 -0500 Subject: [PATCH 41/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 4affebb..1649586 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -122,8 +122,8 @@ The :aws-java-class:`DynamoDBMapper Date: Fri, 3 Jan 2020 12:45:24 -0500 Subject: [PATCH 42/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 1649586..458bcea 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -133,7 +133,7 @@ For information on creating the *Music* table, see :ddb-dg:`Create a Table Date: Fri, 3 Jan 2020 13:10:59 -0500 Subject: [PATCH 43/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 458bcea..1649586 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -133,7 +133,7 @@ For information on creating the *Music* table, see :ddb-dg:`Create a Table Date: Mon, 6 Jan 2020 09:48:50 -0500 Subject: [PATCH 44/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 1649586..458bcea 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -133,7 +133,7 @@ For information on creating the *Music* table, see :ddb-dg:`Create a Table Date: Mon, 6 Jan 2020 11:15:04 -0500 Subject: [PATCH 45/83] added setup info --- doc_source/setup-install.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc_source/setup-install.rst b/doc_source/setup-install.rst index d304e8d..2541b0c 100644 --- a/doc_source/setup-install.rst +++ b/doc_source/setup-install.rst @@ -47,7 +47,8 @@ system or IDE: which will automatically download, install and update the Java SDK for you. For more information and setup instructions, see the |tke-ug|_. -If you intend to build your projects using a different IDE, with Apache Ant or by any other means, +If you are using one the above methods (for example, +you are using Maven), then you do not need to download and install the AWS JAR files (you can skip the following section). If you intend to build your projects using a different IDE, with Apache Ant or by any other means, then download and extract the SDK as shown in the next section. .. _download-and-extract-sdk: From d6c5d055159bb79aef8c5b1241e8b6571d78225e Mon Sep 17 00:00:00 2001 From: scmacdon Date: Mon, 6 Jan 2020 11:41:02 -0500 Subject: [PATCH 46/83] added additional info --- doc_source/examples-lambda.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc_source/examples-lambda.rst b/doc_source/examples-lambda.rst index bb4b7d0..ef50ba7 100644 --- a/doc_source/examples-lambda.rst +++ b/doc_source/examples-lambda.rst @@ -18,7 +18,8 @@ Invoking, Listing, and Deleting Lambda Functions deleteFunction, invoke, listFunctions -This section provides examples of programming with the Lambda service client by using the AWS SDK for Java. +This section provides examples of programming with the Lambda service client by using the AWS SDK for Java. To learn how to +create a Lambda function, see see :AWS Toolkit for Eclipse:`Tutorial: How to Create, Upload, and Invoke an AWS Lambda Function ` in the AWS Toolkit for Eclipse. .. contents:: :local: From ce1fc145c182c0680a514f7ee7e5523e85ab59f2 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Mon, 6 Jan 2020 11:48:12 -0500 Subject: [PATCH 47/83] added additional info --- doc_source/lambda-examples.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/lambda-examples.rst b/doc_source/lambda-examples.rst index d0cdacf..2687321 100644 --- a/doc_source/lambda-examples.rst +++ b/doc_source/lambda-examples.rst @@ -13,10 +13,10 @@ Lambda Examples Using the |sdk-java| ########################################## .. meta:: - :description: Programming Amazon Lambda using the AWS SDK for Java 2.x + :description: Programming Amazon Lambda using the AWS SDK for Java. :keywords: AWS SDK for Java code examples -This section provides examples of programming Lambda using the |sdk-java-v2|. +This section provides examples of programming Lambda using the |sdk-java|. .. include:: includes/complete-examples-note.txt From abe2736f62369c52b8165060b76b7242bfded271 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Mon, 6 Jan 2020 11:50:41 -0500 Subject: [PATCH 48/83] added additional info --- doc_source/examples-lambda.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-lambda.rst b/doc_source/examples-lambda.rst index ef50ba7..b45966a 100644 --- a/doc_source/examples-lambda.rst +++ b/doc_source/examples-lambda.rst @@ -19,7 +19,7 @@ Invoking, Listing, and Deleting Lambda Functions This section provides examples of programming with the Lambda service client by using the AWS SDK for Java. To learn how to -create a Lambda function, see see :AWS Toolkit for Eclipse:`Tutorial: How to Create, Upload, and Invoke an AWS Lambda Function ` in the AWS Toolkit for Eclipse. +create a Lambda function, see see :tke:`Tutorial: How to Create, Upload, and Invoke an AWS Lambda Function ` in the |tke|. .. contents:: :local: From 2b78cab356dc14ec155b08cdfdb0f0586d2e691c Mon Sep 17 00:00:00 2001 From: scmacdon Date: Mon, 6 Jan 2020 12:00:16 -0500 Subject: [PATCH 49/83] added additional info --- doc_source/examples-lambda.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-lambda.rst b/doc_source/examples-lambda.rst index b45966a..e524d4d 100644 --- a/doc_source/examples-lambda.rst +++ b/doc_source/examples-lambda.rst @@ -19,7 +19,7 @@ Invoking, Listing, and Deleting Lambda Functions This section provides examples of programming with the Lambda service client by using the AWS SDK for Java. To learn how to -create a Lambda function, see see :tke:`Tutorial: How to Create, Upload, and Invoke an AWS Lambda Function ` in the |tke|. +create a Lambda function, see `How to Create AWS Lambda functions `_. .. contents:: :local: From d7a0cde84ceb2dac95a6387bdf3c1b3021b81ff2 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Mon, 6 Jan 2020 12:09:28 -0500 Subject: [PATCH 50/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 458bcea..3b57198 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -134,8 +134,8 @@ After the content is added to the table, notice that an item is loaded by using *Partition* and *Sort* keys. Then the *Awards* item is updated. .. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/UseDynamoMapping.java - :lines: 82-105 - :dedent: 8 + :lines: 51-90 + :dedent: 2 :language: java See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. From 65afe0017d1888144b27d2d67a621011f3fc00e9 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Mon, 6 Jan 2020 12:15:50 -0500 Subject: [PATCH 51/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 3b57198..1014cbf 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -122,8 +122,8 @@ The :aws-java-class:`DynamoDBMapper Date: Mon, 6 Jan 2020 12:23:40 -0500 Subject: [PATCH 52/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 1014cbf..71c844b 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -122,8 +122,7 @@ The :aws-java-class:`DynamoDBMapper ` on GitHub. From 1e3bd5484687903ac54e944d985cbed200e7a0ce Mon Sep 17 00:00:00 2001 From: scmacdon Date: Mon, 6 Jan 2020 12:28:43 -0500 Subject: [PATCH 53/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 71c844b..cbda484 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -133,7 +133,7 @@ After the content is added to the table, notice that an item is loaded by using *Partition* and *Sort* keys. Then the *Awards* item is updated. .. literalinclude:: dynamodb.java.dynamoDB_mapping.main.txt - :dedent: 8 + :dedent: 4 :language: java See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. From fba796400777f926611db1f8ce5baddc8946f3c1 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Mon, 6 Jan 2020 12:34:21 -0500 Subject: [PATCH 54/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index cbda484..c1de871 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -133,7 +133,7 @@ After the content is added to the table, notice that an item is loaded by using *Partition* and *Sort* keys. Then the *Awards* item is updated. .. literalinclude:: dynamodb.java.dynamoDB_mapping.main.txt - :dedent: 4 + :dedent: 2 :language: java See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. From 0466379b2753c280de2dd959a3f2e9fe5d134c31 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Mon, 6 Jan 2020 12:35:38 -0500 Subject: [PATCH 55/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index c1de871..343d474 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -128,9 +128,8 @@ The :aws-java-class:`DynamoDBMapper ` class. -For information on creating the *Music* table, see :ddb-dg:`Create a Table ` in the |ddb-dg|. After the content is added to the table, notice that an item is loaded by using the -*Partition* and *Sort* keys. Then the *Awards* item is updated. +*Partition* and *Sort* keys. Then the *Awards* item is updated. For information on creating the *Music* table, see :ddb-dg:`Create a Table ` in the |ddb-dg|. .. literalinclude:: dynamodb.java.dynamoDB_mapping.main.txt :dedent: 2 From 271ce62a54155519e2df5ebd4a322953ec4ad01d Mon Sep 17 00:00:00 2001 From: scmacdon Date: Mon, 6 Jan 2020 12:42:14 -0500 Subject: [PATCH 56/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 343d474..88046ff 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -132,7 +132,7 @@ After the content is added to the table, notice that an item is loaded by using *Partition* and *Sort* keys. Then the *Awards* item is updated. For information on creating the *Music* table, see :ddb-dg:`Create a Table ` in the |ddb-dg|. .. literalinclude:: dynamodb.java.dynamoDB_mapping.main.txt - :dedent: 2 + :dedent: 0 :language: java See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. From 18b477c44aae38b7d1836b4e5c00a7079aee3c5c Mon Sep 17 00:00:00 2001 From: scmacdon Date: Mon, 6 Jan 2020 12:51:24 -0500 Subject: [PATCH 57/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 88046ff..a0d0ad2 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -132,7 +132,7 @@ After the content is added to the table, notice that an item is loaded by using *Partition* and *Sort* keys. Then the *Awards* item is updated. For information on creating the *Music* table, see :ddb-dg:`Create a Table ` in the |ddb-dg|. .. literalinclude:: dynamodb.java.dynamoDB_mapping.main.txt - :dedent: 0 + :dedent: 8 :language: java See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. From cff3ab7f99709230dd1a2cb2a6cb167a4269f8ea Mon Sep 17 00:00:00 2001 From: scmacdon Date: Mon, 6 Jan 2020 12:56:47 -0500 Subject: [PATCH 58/83] added the code tags --- doc_source/examples-dynamodb-items.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index a0d0ad2..b360d0a 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -132,7 +132,7 @@ After the content is added to the table, notice that an item is loaded by using *Partition* and *Sort* keys. Then the *Awards* item is updated. For information on creating the *Music* table, see :ddb-dg:`Create a Table ` in the |ddb-dg|. .. literalinclude:: dynamodb.java.dynamoDB_mapping.main.txt - :dedent: 8 + :dedent: 1 :language: java See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. From f3c126f75ec4bb790d7296d09cdec75ab861d72e Mon Sep 17 00:00:00 2001 From: scmacdon Date: Thu, 9 Jan 2020 11:56:01 -0500 Subject: [PATCH 59/83] fixed order of service provider --- doc_source/java-dg-roles.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/doc_source/java-dg-roles.rst b/doc_source/java-dg-roles.rst index bf90958..ffafc22 100644 --- a/doc_source/java-dg-roles.rst +++ b/doc_source/java-dg-roles.rst @@ -29,13 +29,15 @@ The default provider chain and EC2 instance profiles If your application creates an AWS client using the default constructor, then the client will search for credentials using the :emphasis:`default credentials provider chain`, in the following order: -1. In system environment variables: :code:`AWS_ACCESS_KEY_ID` and :code:`AWS_SECRET_ACCESS_KEY`. +1. In the Java system properties: :code:`aws.accessKeyId` and :code:`aws.secretKey`. -2. In the Java system properties: :code:`aws.accessKeyId` and :code:`aws.secretKey`. +2. In system environment variables: :code:`AWS_ACCESS_KEY_ID` and :code:`AWS_SECRET_ACCESS_KEY`. 3. In the default credentials file (the location of this file varies by platform). -4. In the :emphasis:`instance profile credentials`, which exist within the instance metadata +4. Credentials delivered through the Amazon EC2 container service if the :code:`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` environment variable is set and security manager has permission to access the variable. + +5. In the :emphasis:`instance profile credentials`, which exist within the instance metadata associated with the IAM role for the EC2 instance. The final step in the default provider chain is available only when running your application on an From 335d2e00457472276c83fb9ab0954f94edd28a27 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Thu, 9 Jan 2020 21:21:07 -0500 Subject: [PATCH 60/83] added additional info --- doc_source/credentials.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc_source/credentials.rst b/doc_source/credentials.rst index 50fbede..758ad44 100644 --- a/doc_source/credentials.rst +++ b/doc_source/credentials.rst @@ -60,6 +60,7 @@ class. The default credential provider chain looks for credentials in this order variable :envvar:`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` is set. The |sdk-java| uses the :aws-java-class:`ContainerCredentialsProvider ` to load these credentials. You can specify the IP address for this value. + #. **Instance profile credentials** |ndash| used on EC2 instances, and delivered through the |EC2| metadata service. The |sdk-java| uses the :aws-java-class:`InstanceProfileCredentialsProvider ` to load these credentials. You can specify the IP address for this value. @@ -69,6 +70,7 @@ class. The default credential provider chain looks for credentials in this order :aws-java-class:`EC2ContainerCredentialsProviderWrapper ` for more information. +#. **Web Identity Token credentials** from the environment or container. Setting Credentials ------------------- From 4afd628e34689018c1d9909ad213de7bda0ab446 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Thu, 9 Jan 2020 21:21:53 -0500 Subject: [PATCH 61/83] added additional info --- doc_source/java-dg-roles.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc_source/java-dg-roles.rst b/doc_source/java-dg-roles.rst index ffafc22..82f1fec 100644 --- a/doc_source/java-dg-roles.rst +++ b/doc_source/java-dg-roles.rst @@ -40,7 +40,9 @@ for credentials using the :emphasis:`default credentials provider chain`, in the 5. In the :emphasis:`instance profile credentials`, which exist within the instance metadata associated with the IAM role for the EC2 instance. -The final step in the default provider chain is available only when running your application on an +6. Web Identity Token credentials from the environment or container. + +The :emphasis:`instance profile credentials` step in the default provider chain is available only when running your application on an |EC2| instance, but provides the greatest ease of use and best security when working with |EC2| instances. You can also pass an :aws-java-class:`InstanceProfileCredentialsProvider ` instance directly to the client constructor to get From be848e56db1d0e629ac2714f9e1d8e1e07e479c0 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Thu, 23 Jan 2020 11:20:46 -0500 Subject: [PATCH 62/83] updated file --- doc_source/examples-sqs-messages.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc_source/examples-sqs-messages.rst b/doc_source/examples-sqs-messages.rst index 67aa64e..d4427c9 100644 --- a/doc_source/examples-sqs-messages.rst +++ b/doc_source/examples-sqs-messages.rst @@ -45,6 +45,7 @@ Add a single message to an |SQS| queue by calling the |sqsclient| client's :dedent: 8 :language: java +See the :sdk-examples-java-sqs:`complete example ` on GitHub. .. _sqs-messages-send-multiple: From 32caab7fb5b1257ab6fa63c7e4ee1b7e9c75a75e Mon Sep 17 00:00:00 2001 From: scmacdon Date: Mon, 9 Mar 2020 16:37:58 -0400 Subject: [PATCH 63/83] minor change --- doc_source/examples-iam.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-iam.rst b/doc_source/examples-iam.rst index 92005a0..46500e3 100644 --- a/doc_source/examples-iam.rst +++ b/doc_source/examples-iam.rst @@ -16,7 +16,7 @@ :description: Programming AWS Identity and Access Management using the AWS SDK for Java :keywords: AWS SDK for Java code examples, IAM -This section provides examples of programming |iam|_ using the |sdk-java|_. +This section provides examples of programming |iam|_ by using the |sdk-java|_. .. include:: common/desc-iam.txt From 9f0bdd5854d47a071b31fffdb4eb2b0a5591d411 Mon Sep 17 00:00:00 2001 From: Scott Macdonald <57190223+scmacdon@users.noreply.github.com> Date: Fri, 13 Mar 2020 13:29:23 -0400 Subject: [PATCH 64/83] Create java-tls.rst add new file --- doc_source/java-tls.rst | 64 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 doc_source/java-tls.rst diff --git a/doc_source/java-tls.rst b/doc_source/java-tls.rst new file mode 100644 index 0000000..f680ee8 --- /dev/null +++ b/doc_source/java-tls.rst @@ -0,0 +1,64 @@ +.. Copyright 2010-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +##################################### +Java SDK TLS 1.2 +##################################### + +.. meta:: + :description: Applies to Java SSL implementation (default SSL implementation in the SDK)Learn how the AWS shared responsibility model applies to data protection in this AWS product or service. + :keywords: + +The following information only applies to Java SSL implementation (default SSL implementation in the SDK). If you are using a different SSL implementations, you need to +look at your specific ssl implementation for how to enforce tls versions. + +TLS support in Java +=================== +TLS 1.2 is supported starting from Java 7. + +How to check TLS version +======================== +To check what TLS version is supported in your JVM, you can use the following code. + +.. code-block:: java + + System*.out.println(*Arrays*.toString(*SSLContext*.getDefault().getSupportedSSLParameters().getProtocols())); + +To see the SSL handshake in action and what version of TLS is used, you can use the system property **javax.net.debug**. + +.. code-block:: java + + java app.jar -Djavax.net.debug=ssl + +How to set TLS version +====================== + +**AWS Java SDK 1.x** + +* Apache http client: the SDK always prefers TLS 1.2 if it's supported in the platform. + +**AWS Java SDK 2.x** + +* ApacheHttpClient: the SDK always prefers TLS 1.2 if it's supported in the platform. + +* UrlHttpConnectionClient: + * To enforce only tls 1.2, using the system property + +.. code-block:: java + + java app.jar -Djdk.tls.client.protocols=TLSv1.2 + +or in code + +.. code-block:: java + + System.setProperty("jdk.tls.client.protocols", "TLSv1.2"); + +* NettyNioHttpClient: The SDK dependency Netty by default always prefers TLS 1.2 if it's supported in the platform. From 4cc6d7af8bf0db46199fb79e09f61f0b8cd85988 Mon Sep 17 00:00:00 2001 From: scmacdon Date: Fri, 13 Mar 2020 13:36:19 -0400 Subject: [PATCH 65/83] update file --- doc_source/security.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc_source/security.rst b/doc_source/security.rst index 827ac76..07691e7 100644 --- a/doc_source/security.rst +++ b/doc_source/security.rst @@ -25,6 +25,7 @@ Security for |SERVICENAMETITLE| :titlesonly: Data Protection + Java SDK TLS 1.2 Identity and Access Management Compliance Validation Resilience From 352d6f4b8b8725ab011135ae2b0155f28c25f57b Mon Sep 17 00:00:00 2001 From: Carey Burgess Date: Thu, 19 Mar 2020 12:32:17 -0700 Subject: [PATCH 66/83] update to security section --- doc_source/java-tls.rst | 37 ++++++++++++++++++------------------- doc_source/security.rst | 2 +- 2 files changed, 19 insertions(+), 20 deletions(-) diff --git a/doc_source/java-tls.rst b/doc_source/java-tls.rst index f680ee8..68d9899 100644 --- a/doc_source/java-tls.rst +++ b/doc_source/java-tls.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -9,23 +9,23 @@ limitations under the License. ##################################### -Java SDK TLS 1.2 +AWS SDK for Java support for TLS 1.2 ##################################### .. meta:: - :description: Applies to Java SSL implementation (default SSL implementation in the SDK)Learn how the AWS shared responsibility model applies to data protection in this AWS product or service. + :description: Applies to Java SSL implementation (default SSL implementation in the SDK). Learn how the AWS shared responsibility model applies to data protection in this AWS product or service. :keywords: -The following information only applies to Java SSL implementation (default SSL implementation in the SDK). If you are using a different SSL implementations, you need to -look at your specific ssl implementation for how to enforce tls versions. +The following information applies only to Java SSL implementation (the default SSL implementation in the AWS SDK for Java). If you're using a different SSL implementation, +see your specific SSL implementation to learn how to enforce TLS versions. TLS support in Java =================== -TLS 1.2 is supported starting from Java 7. +TLS 1.2 is supported starting in Java 7. -How to check TLS version -======================== -To check what TLS version is supported in your JVM, you can use the following code. +How to check the TLS version +============================ +To check what TLS version is supported in your Java virtual machine (JVM), you can use the following code. .. code-block:: java @@ -37,28 +37,27 @@ To see the SSL handshake in action and what version of TLS is used, you can use java app.jar -Djavax.net.debug=ssl -How to set TLS version -====================== +How to set the TLS version +========================== -**AWS Java SDK 1.x** +**AWS SDK for Java 1.x** -* Apache http client: the SDK always prefers TLS 1.2 if it's supported in the platform. +* Apache HTTP client: The SDK always prefers TLS 1.2 (if it's supported in the platform). -**AWS Java SDK 2.x** +**AWS SDK for Java 2.x** -* ApacheHttpClient: the SDK always prefers TLS 1.2 if it's supported in the platform. +* ApacheHttpClient: The SDK always prefers TLS 1.2 (if it's supported in the platform). -* UrlHttpConnectionClient: - * To enforce only tls 1.2, using the system property +* UrlHttpConnectionClient: To enforce only TLS 1.2, you can use this Java command. .. code-block:: java java app.jar -Djdk.tls.client.protocols=TLSv1.2 -or in code +Or use this code. .. code-block:: java System.setProperty("jdk.tls.client.protocols", "TLSv1.2"); -* NettyNioHttpClient: The SDK dependency Netty by default always prefers TLS 1.2 if it's supported in the platform. +* NettyNioHttpClient: The SDK dependency for Netty is TLS 1.2 (if it's supported in the platform). diff --git a/doc_source/security.rst b/doc_source/security.rst index 07691e7..3a2e39f 100644 --- a/doc_source/security.rst +++ b/doc_source/security.rst @@ -25,7 +25,7 @@ Security for |SERVICENAMETITLE| :titlesonly: Data Protection - Java SDK TLS 1.2 + Enforcing TLS 1.2 Identity and Access Management Compliance Validation Resilience From 0a7b4cce5d1ce5d05c16c01220088d362bb5e95c Mon Sep 17 00:00:00 2001 From: Carey Burgess Date: Thu, 19 Mar 2020 12:36:19 -0700 Subject: [PATCH 67/83] minor repo cleanup --- doc_source/{java-tls.rst => security-java-tls.rst} | 0 doc_source/security.rst | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename doc_source/{java-tls.rst => security-java-tls.rst} (100%) diff --git a/doc_source/java-tls.rst b/doc_source/security-java-tls.rst similarity index 100% rename from doc_source/java-tls.rst rename to doc_source/security-java-tls.rst diff --git a/doc_source/security.rst b/doc_source/security.rst index 3a2e39f..34d0c04 100644 --- a/doc_source/security.rst +++ b/doc_source/security.rst @@ -25,7 +25,7 @@ Security for |SERVICENAMETITLE| :titlesonly: Data Protection - Enforcing TLS 1.2 + Enforcing TLS 1.2 Identity and Access Management Compliance Validation Resilience From 878d8f2383cb7c29d34d27225c59e7ab51103bc8 Mon Sep 17 00:00:00 2001 From: Carey Burgess Date: Mon, 13 Apr 2020 18:33:14 -0700 Subject: [PATCH 68/83] updating Gradle setup instructions --- doc_source/setup-project-gradle.rst | 90 ++++++++++++++++++----------- 1 file changed, 55 insertions(+), 35 deletions(-) diff --git a/doc_source/setup-project-gradle.rst b/doc_source/setup-project-gradle.rst index 1f36d79..c946f23 100644 --- a/doc_source/setup-project-gradle.rst +++ b/doc_source/setup-project-gradle.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -12,41 +12,52 @@ Using the SDK with Gradle ######################### + +Project setup for Gradle 4.6 or higher +=============== + `Since Gradle 4.6 `_ it is possible to use Gradle's improved POM support feature for importing bill of materials (BOM) files by simply declaring a dependency on a BOM. -.. topic:: To configure the SDK for Gradle 4.6 and upper +To manage SDK dependencies for your Gradle_ project, import the |sdk-java|'s Maven Bill of Materials (BOM) into the :file:`build.gradle` file. + +.. note:: Replace *1.11.X* in the build file examples below with a valid version of the |sdk-java|. Find the latest version in the + `AWS SDK for Java 1.11.x Reference `_ + - #. Enable `IMPROVED_POM_SUPPORT` feature in :file:`settings.gradle` file (not needed in Gradle 5 and upper) +.. topic:: To configure the |sdk-java| for Gradle 4.6 or higher: + + #. If you are using Gradle 5.0 or higher, skip to Step 2. Otherwise, enable the `IMPROVED_POM_SUPPORT` feature in the :file:`settings.gradle` file .. code-block:: groovy enableFeaturePreview('IMPROVED_POM_SUPPORT') - #. Import BOM as a usual dependency in the *dependencies* section + #. Add the BOM to the *dependencies* section of the :file:`build.gradle` file. .. code-block:: groovy + ... dependencies { - implementation platform('com.amazonaws:aws-java-sdk-bom:1.11.228') + implementation platform('com.amazonaws:aws-java-sdk-bom:1.11.X') + + // Declare individual SDK dependencies without version + ... } - #. Specify the SDK modules that you'll be using in the *dependencies* section + #. Specify the SDK modules you want to use in the *dependencies* section. For example, the following includes a dependency for |S3long|. .. code-block:: groovy + ... dependencies { implementation 'com.amazonaws:aws-java-sdk-s3' - testCompile group: 'junit', name: 'junit', version: '4.11' + ... } -Gradle will automatically resolve the correct version of your SDK dependencies using the information -from the BOM. - -You can also refer to the *AWS Code Catalog* to learn what dependencies to use for a given AWS service. Refer to the POM file under a specific service example. -For example, if you are interested in the dependencies for the AWS S3 service (as shown in the previous dependencies example), see the :sdk-examples-java-s3:`complete example ` on GitHub. (Look at the pom under /java/example_code/s3). +Gradle automatically resolves the correct version of your SDK dependencies using the information from the BOM. -Here's the complete :file:`build.gradle` file: +The following is an example of a complete :file:`build.gradle` file that includes a dependency for |S3|: .. code-block:: groovy @@ -62,18 +73,27 @@ Here's the complete :file:`build.gradle` file: } dependencies { - implementation platform('com.amazonaws:aws-java-sdk-bom:1.11.228') - implementation 'com.amazonaws:aws-java-sdk-s3' - testCompile group: 'junit', name: 'junit', version: '4.11' + implementation platform('com.amazonaws:aws-java-sdk-bom:1.11.X') + implementation 'com.amazonaws:aws-java-sdk-s3' + testCompile group: 'junit', name: 'junit', version: '4.11' } -Gradle versions prior to 4.6 lack of native BOM support, so Spring's `dependency management plugin -`_ for Gradle can be used -to import the SDK's Maven Bill of Materials (BOM) to manage SDK dependencies for your project. +.. note:: Replace the dependency for |S3| above with the dependency or dependencies of the Amazon service(s) you will be using in your project. The modules (dependencies) that are managed by the |sdk-java| BOM are listed on Maven Central (https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-bom/latest). + + +Project setup for Gradle versions prior to 4.6 +=============== + +Gradle versions prior to 4.6 lack native BOM support. To manage |sdk-java| dependencies for your project, +use Spring's `dependency management plugin +`_ for Gradle to import the SDK's Maven Bill of Materials (BOM). -.. topic:: To configure the SDK for Gradle prior 4.6 +.. note:: Replace *1.11.X* in the build file examples below with a valid version of the |sdk-java|. Find the latest version in the + `AWS SDK for Java 1.11.x Reference `_ - #. Add the dependency management plugin to your :file:`build.gradle` file +.. topic:: To configure the SDK for Gradle versions prior to 4.6: + + #. Add the dependency management plugin to your :file:`build.gradle` file. .. code-block:: groovy @@ -82,40 +102,38 @@ to import the SDK's Maven Bill of Materials (BOM) to manage SDK dependencies for mavenCentral() } dependencies { - classpath "io.spring.gradle:dependency-management-plugin:1.0.3.RELEASE" + classpath "io.spring.gradle:dependency-management-plugin:1.0.9.RELEASE" } } apply plugin: "io.spring.dependency-management" - #. Add the BOM to the *dependencyManagement* section of the file + #. Add the BOM to the *dependencyManagement* section of the file. .. code-block:: groovy dependencyManagement { imports { - mavenBom 'com.amazonaws:aws-java-sdk-bom:1.11.228' + mavenBom 'com.amazonaws:aws-java-sdk-bom:1.11.X' } } - #. Specify the SDK modules that you'll be using in the *dependencies* section + #. Specify the SDK modules that you'll be using in the *dependencies* section. For example, the following includes a dependency for |S3long|. .. code-block:: groovy dependencies { compile 'com.amazonaws:aws-java-sdk-s3' - testCompile group: 'junit', name: 'junit', version: '4.11' } -Gradle will automatically resolve the correct version of your SDK dependencies using the information -from the BOM. +Gradle automatically resolves the correct version of your SDK dependencies using the information from the BOM. -Here's the complete :file:`build.gradle` file: +The following is an example of a complete :file:`build.gradle` file that includes a dependency for |S3|: .. code-block:: groovy group 'aws.test' - version '1.0-SNAPSHOT' + version '1.0' apply plugin: 'java' @@ -127,10 +145,10 @@ Here's the complete :file:`build.gradle` file: buildscript { repositories { - mavenCentral() + mavenCentral() } dependencies { - classpath "io.spring.gradle:dependency-management-plugin:1.0.3.RELEASE" + classpath "io.spring.gradle:dependency-management-plugin:1.0.9.RELEASE" } } @@ -138,7 +156,7 @@ Here's the complete :file:`build.gradle` file: dependencyManagement { imports { - mavenBom 'com.amazonaws:aws-java-sdk-bom:1.11.228' + mavenBom 'com.amazonaws:aws-java-sdk-bom:1.11.X' } } @@ -147,5 +165,7 @@ Here's the complete :file:`build.gradle` file: testCompile group: 'junit', name: 'junit', version: '4.11' } -.. note:: For more detail about specifying SDK dependencies using the BOM, see - :doc:`setup-project-maven`. +.. note:: Replace the dependency for |S3| above with the dependency or dependencies of the Amazon service(s) you will be using in your project. The modules (dependencies) that are managed by the |sdk-java| BOM are listed on Maven Central (https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-bom/latest). + +For more detail about specifying SDK dependencies using the BOM, see +:doc:`setup-project-maven`. From 6780b657638f8b560ba2208f61f07b007f66d324 Mon Sep 17 00:00:00 2001 From: Carey Burgess Date: Tue, 14 Apr 2020 13:22:06 -0700 Subject: [PATCH 69/83] minor reorganization --- doc_source/java-dg-samples.rst | 2 +- doc_source/prog-services-sts.rst | 19 +++---------------- doc_source/prog-services.rst | 5 ++--- doc_source/setup-credentials.rst | 6 ++++++ 4 files changed, 12 insertions(+), 20 deletions(-) diff --git a/doc_source/java-dg-samples.rst b/doc_source/java-dg-samples.rst index 73aacf2..343550d 100644 --- a/doc_source/java-dg-samples.rst +++ b/doc_source/java-dg-samples.rst @@ -9,7 +9,7 @@ limitations under the License. ####################### -|sdk-java| Code Samples +Code Samples included with the SDK ####################### The |sdk-java| comes packaged with code samples that demonstrate many of the features of diff --git a/doc_source/prog-services-sts.rst b/doc_source/prog-services-sts.rst index bbf4721..a7cd288 100644 --- a/doc_source/prog-services-sts.rst +++ b/doc_source/prog-services-sts.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -66,25 +66,12 @@ Retrieve temporary security credentials from |STS| .. code-block:: java - AWSSecurityTokenService sts_client = new AWSSecurityTokenServiceClientBuilder().standard().withEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration("sts-endpoint.amazonaws.com", "signing-region")).build() + AWSSecurityTokenServiceClientBuilder sts_client = new AWSSecurityTokenServiceClientBuilder().standard().withEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration("sts-endpoint.amazonaws.com", "signing-region")).build() - When creating the client with no arguments (:code:`AWSSecurityTokenServiceClient sts_client = new AWSSecurityTokenServiceClientBuilder().standard().build();`), the default credential provider chain is used to + When creating the client with no arguments (:code:`AWSSecurityTokenServiceClientBuilder sts_client = new AWSSecurityTokenServiceClientBuilder().standard().build();`), the default credential provider chain is used to retrieve credentials. You can provide a specific credential provider if you want. For more information, see Providing AWS Credentials in the AWS SDK for Java. - #. :emphasis:`Optional`; requires that you have activated the region) Set the endpoint for the - STS client: - - .. code-block:: java - - sts_client.setEndpoint("sts-endpoint.amazonaws.com"); - - where :emphasis:`sts-endpoint` represents the STS endpoint for your region. - - .. important:: Do not use the :methodname:`setRegion` method to set a regional endpoint - |mdash| for backwards compatibility, that method continues to use the single global - endpoint of sts.amazonaws.com. - #. Create a :aws-java-class:`GetSessionTokenRequest ` object, and optionally set the duration in seconds for which the temporary credentials are valid: diff --git a/doc_source/prog-services.rst b/doc_source/prog-services.rst index 722f3c5..995b1b3 100644 --- a/doc_source/prog-services.rst +++ b/doc_source/prog-services.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -35,7 +35,6 @@ In 2018, AWS released |sdk-java| v2. For more AWS examples, see the `AWS SDK for :maxdepth: 1 :titlesonly: - SDK Code Samples Amazon CloudWatch Examples Amazon DynamoDB Examples Amazon EC2 Examples @@ -44,5 +43,5 @@ In 2018, AWS released |sdk-java| v2. For more AWS examples, see the `AWS SDK for Amazon Pinpoint Examples Amazon S3 Examples Amazon SQS Examples - prog-services-sts Amazon SWF Examples + Code Samples included with the SDK diff --git a/doc_source/setup-credentials.rst b/doc_source/setup-credentials.rst index 127b3b3..7042377 100644 --- a/doc_source/setup-credentials.rst +++ b/doc_source/setup-credentials.rst @@ -92,3 +92,9 @@ You can use similar techniques to setting credentials to set your default AWS re .. The following file is in the shared content at https://github.com/awsdocs/aws-doc-shared-content .. include:: common/sdk-shared-region.txt + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + prog-services-sts \ No newline at end of file From 415f3349ea1e82843f1bd635ce6490a980398921 Mon Sep 17 00:00:00 2001 From: Carey Burgess Date: Tue, 14 Apr 2020 13:24:00 -0700 Subject: [PATCH 70/83] replaced deprecated method --- doc_source/java-dg-region-selection.rst | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/doc_source/java-dg-region-selection.rst b/doc_source/java-dg-region-selection.rst index de6e25c..e6a1ae0 100644 --- a/doc_source/java-dg-region-selection.rst +++ b/doc_source/java-dg-region-selection.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -79,14 +79,19 @@ Choosing a Specific Endpoint ============================ Each AWS client can be configured to use a *specific endpoint* within a region by calling the -:methodname:`setEndpoint` method. +:methodname:`withEndpointConfiguration` method when creating the client. -For example, to configure the |EC2| client to use the |euwest1-name|, use the following code. +For example, to configure the |S3| client to use the |euwest1-name|, use the following code. :: - AmazonEC2 ec2 = new AmazonEC2(myCredentials); - ec2.setEndpoint("https://ec2.eu-west-1.amazonaws.com"); + AmazonS3 s3 = AmazonS3ClientBuilder.standard() + .withEndpointConfiguration(new EndpointConfiguration( + "https://s3.eu-west-1.amazonaws.com", + "eu-west-1")) + .withCredentials(CREDENTIALS_PROVIDER) + .build(); + See |regions-and-endpoints|_ for the current list of regions and their corresponding endpoints for all AWS services. From 54abf885786b862cf2af7c5dadf7e32ac9a1b1c2 Mon Sep 17 00:00:00 2001 From: Carey Burgess Date: Sun, 19 Apr 2020 16:02:19 -0700 Subject: [PATCH 71/83] fixes based on customer feedback --- doc_source/sdk-metrics.rst | 36 +++++++++---------- doc_source/setup-project-gradle.rst | 55 +++++++++++++++-------------- 2 files changed, 47 insertions(+), 44 deletions(-) diff --git a/doc_source/sdk-metrics.rst b/doc_source/sdk-metrics.rst index 66df031..ef87fca 100755 --- a/doc_source/sdk-metrics.rst +++ b/doc_source/sdk-metrics.rst @@ -62,30 +62,14 @@ Enabling |SDKM| is independent of configuring your credentials to use an AWS ser You can enable |SDKM| using one of 4 options. -* :ref:`csm-enable-agent-code` * :ref:`csm-enable-agent-environ` +* :ref:`csm-enable-agent-code` * :ref:`csm-enable-agent-java-prop` * :ref:`csm-enable-agent-shared-config` -.. _csm-enable-agent-code: - -Option 1: Set |SDKM| in Code ----------------------------- - -The |language| implementation allows you to set |SDKM| configurations within code when building -a service client. -The values set in code override any configurations set in the other options described below. - -.. code-block:: java - - CsmConfiguration csmConfig = new CsmConfiguration(true, MY_PORT, MY_CLIENT_ID); - AmazonDynamoDB dynamodb = AmazonDynamoDBClientBuilder.standard() - .withClientSideMonitoringConfigurationProvider(new StaticCsmConfigurationProvider(csmConfig)) - .build(); - .. _csm-enable-agent-environ: -Option 2: Set Environment Variables +Option 1: Set Environment Variables ----------------------------------- If :code:`AWS_CSM_ENABLED` is not set, the SDK first checks the profile specified in @@ -102,6 +86,22 @@ To turn on |SDKM|, add the following to your environmental variables. Note: Enabling |SDKM| does not configure your credentials to use an AWS service. +.. _csm-enable-agent-code: + +Option 2: Set |SDKM| in Code +---------------------------- + +The |language| implementation allows you to set |SDKM| configurations within code when building +a service client. +The values set in code override any configurations set in the other options described below. + +.. code-block:: java + + CsmConfiguration csmConfig = new CsmConfiguration(true, MY_PORT, MY_CLIENT_ID); + AmazonDynamoDB dynamodb = AmazonDynamoDBClientBuilder.standard() + .withClientSideMonitoringConfigurationProvider(new StaticCsmConfigurationProvider(csmConfig)) + .build(); + .. _csm-enable-agent-java-prop: Option 3: Set Java System Property diff --git a/doc_source/setup-project-gradle.rst b/doc_source/setup-project-gradle.rst index c946f23..aa12322 100644 --- a/doc_source/setup-project-gradle.rst +++ b/doc_source/setup-project-gradle.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -13,21 +13,27 @@ Using the SDK with Gradle ######################### -Project setup for Gradle 4.6 or higher -=============== +.. meta:: + :description: How to use Gradle to set up your AWS SDK for Java project + :keywords: AWS SDK for Java, Gradle, BOM, install, download, setup + + +To manage SDK dependencies for your Gradle_ project, import the Maven BOM for the |sdk-java| into the :file:`build.gradle` file. -`Since Gradle 4.6 `_ it is possible to -use Gradle's improved POM support feature for importing bill of materials (BOM) files by simply declaring a dependency on a BOM. +.. note:: In the following examples, replace *1.11.X* in the build file with a valid version of the |sdk-java|. Find the latest version in the + `AWS SDK for Java 1.11.x Reference `_. -To manage SDK dependencies for your Gradle_ project, import the |sdk-java|'s Maven Bill of Materials (BOM) into the :file:`build.gradle` file. -.. note:: Replace *1.11.X* in the build file examples below with a valid version of the |sdk-java|. Find the latest version in the - `AWS SDK for Java 1.11.x Reference `_ +Project setup for Gradle 4.6 or higher +=============== +`Since Gradle 4.6 `_, you can +use Gradle's improved POM support feature for importing bill of materials (BOM) files by declaring a dependency on a BOM. -.. topic:: To configure the |sdk-java| for Gradle 4.6 or higher: - #. If you are using Gradle 5.0 or higher, skip to Step 2. Otherwise, enable the `IMPROVED_POM_SUPPORT` feature in the :file:`settings.gradle` file +.. topic:: To configure the |sdk-java| for Gradle 4.6 or later + + #. If you're using Gradle 5.0 or later, skip to step 2. Otherwise, enable the *IMPROVED_POM_SUPPORT* feature in the :file:`settings.gradle` file. .. code-block:: groovy @@ -45,7 +51,7 @@ To manage SDK dependencies for your Gradle_ project, import the |sdk-java|'s Mav ... } - #. Specify the SDK modules you want to use in the *dependencies* section. For example, the following includes a dependency for |S3long|. + #. Specify the SDK modules to use in the *dependencies* section. For example, the following includes a dependency for |S3long| (|S3|). .. code-block:: groovy @@ -55,9 +61,9 @@ To manage SDK dependencies for your Gradle_ project, import the |sdk-java|'s Mav ... } -Gradle automatically resolves the correct version of your SDK dependencies using the information from the BOM. +Gradle automatically resolves the correct version of your SDK dependencies by using the information from the BOM. -The following is an example of a complete :file:`build.gradle` file that includes a dependency for |S3|: +The following is an example of a complete :file:`build.gradle` file that includes a dependency for |S3|. .. code-block:: groovy @@ -78,20 +84,17 @@ The following is an example of a complete :file:`build.gradle` file that include testCompile group: 'junit', name: 'junit', version: '4.11' } -.. note:: Replace the dependency for |S3| above with the dependency or dependencies of the Amazon service(s) you will be using in your project. The modules (dependencies) that are managed by the |sdk-java| BOM are listed on Maven Central (https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-bom/latest). +.. note:: In the previous example, replace the dependency for |S3| with the dependencies of the AWS services you will use in your project. The modules (dependencies) that are managed by the |sdk-java| BOM are listed on Maven central repository (https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-bom/latest). -Project setup for Gradle versions prior to 4.6 +Project setup for Gradle versions earlier than 4.6 =============== -Gradle versions prior to 4.6 lack native BOM support. To manage |sdk-java| dependencies for your project, +Gradle versions earlier than 4.6 lack native BOM support. To manage |sdk-java| dependencies for your project, use Spring's `dependency management plugin -`_ for Gradle to import the SDK's Maven Bill of Materials (BOM). - -.. note:: Replace *1.11.X* in the build file examples below with a valid version of the |sdk-java|. Find the latest version in the - `AWS SDK for Java 1.11.x Reference `_ +`_ for Gradle to import the Maven BOM for the SDK. -.. topic:: To configure the SDK for Gradle versions prior to 4.6: +.. topic:: To configure the SDK for Gradle versions earlier than 4.6 #. Add the dependency management plugin to your :file:`build.gradle` file. @@ -118,7 +121,7 @@ use Spring's `dependency management plugin } } - #. Specify the SDK modules that you'll be using in the *dependencies* section. For example, the following includes a dependency for |S3long|. + #. Specify the SDK modules that you'll use in the *dependencies* section. For example, the following includes a dependency for |S3|. .. code-block:: groovy @@ -126,9 +129,9 @@ use Spring's `dependency management plugin compile 'com.amazonaws:aws-java-sdk-s3' } -Gradle automatically resolves the correct version of your SDK dependencies using the information from the BOM. +Gradle automatically resolves the correct version of your SDK dependencies by using the information from the BOM. -The following is an example of a complete :file:`build.gradle` file that includes a dependency for |S3|: +The following is an example of a complete :file:`build.gradle` file that includes a dependency for |S3|. .. code-block:: groovy @@ -165,7 +168,7 @@ The following is an example of a complete :file:`build.gradle` file that include testCompile group: 'junit', name: 'junit', version: '4.11' } -.. note:: Replace the dependency for |S3| above with the dependency or dependencies of the Amazon service(s) you will be using in your project. The modules (dependencies) that are managed by the |sdk-java| BOM are listed on Maven Central (https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-bom/latest). +.. note:: In the previous example, replace the dependency for |S3| with the dependencies of the AWS service you will use in your project. The modules (dependencies) that are managed by the |sdk-java| BOM are listed on Maven central repository (https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-bom/latest). -For more detail about specifying SDK dependencies using the BOM, see +For more information about specifying SDK dependencies by using the BOM, see :doc:`setup-project-maven`. From 908a6804830a488264152fc1ec6df5f6bff08495 Mon Sep 17 00:00:00 2001 From: Carey Burgess Date: Tue, 21 Apr 2020 12:55:34 -0700 Subject: [PATCH 72/83] typo --- doc_source/section-client-configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/section-client-configuration.rst b/doc_source/section-client-configuration.rst index a552071..70fc1e8 100644 --- a/doc_source/section-client-configuration.rst +++ b/doc_source/section-client-configuration.rst @@ -119,7 +119,7 @@ Large buffer sizes (e.g., 2 MB) allow the operating system to buffer more data i requiring the remote server to acknowledge receipt of that information, and so can be particularly useful when the network has high latency. -This is only a *hint*, and the operating system might not to honor it. When using this option, users +This is only a *hint*, and the operating system might not honor it. When using this option, users should always check the operating system's configured limits and defaults. Most operating systems have a maximum TCP buffer size limit configured, and won't let you go beyond that limit unless you explicitly raise the maximum TCP buffer size limit. From 3c4707a05f1d174bd0d8dce785d52926ef4ac307 Mon Sep 17 00:00:00 2001 From: Carey Burgess Date: Sat, 25 Apr 2020 17:49:43 -0700 Subject: [PATCH 73/83] customer feedback; fixing code error --- doc_source/prog-services-sts.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/prog-services-sts.rst b/doc_source/prog-services-sts.rst index a7cd288..f82ecb5 100644 --- a/doc_source/prog-services-sts.rst +++ b/doc_source/prog-services-sts.rst @@ -66,9 +66,9 @@ Retrieve temporary security credentials from |STS| .. code-block:: java - AWSSecurityTokenServiceClientBuilder sts_client = new AWSSecurityTokenServiceClientBuilder().standard().withEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration("sts-endpoint.amazonaws.com", "signing-region")).build() + AWSSecurityTokenService sts_client = new AWSSecurityTokenServiceClientBuilder().standard().withEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration("sts-endpoint.amazonaws.com", "signing-region")).build() - When creating the client with no arguments (:code:`AWSSecurityTokenServiceClientBuilder sts_client = new AWSSecurityTokenServiceClientBuilder().standard().build();`), the default credential provider chain is used to + When creating the client with no arguments (:code:`AWSSecurityTokenService sts_client = new AWSSecurityTokenServiceClientBuilder().standard().build();`), the default credential provider chain is used to retrieve credentials. You can provide a specific credential provider if you want. For more information, see Providing AWS Credentials in the AWS SDK for Java. From 7de170fd15e6ea82b699a45ad3116f2fbbab3f59 Mon Sep 17 00:00:00 2001 From: Carey Burgess Date: Wed, 6 May 2020 10:38:10 -0700 Subject: [PATCH 74/83] fix broken links --- doc_source/data-protection.rst | 2 +- doc_source/security.rst | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/doc_source/data-protection.rst b/doc_source/data-protection.rst index c315926..185e987 100644 --- a/doc_source/data-protection.rst +++ b/doc_source/data-protection.rst @@ -29,7 +29,7 @@ For data protection purposes, we recommend that you protect |AWS| account creden you secure your data in the following ways: * Use multi-factor authentication (MFA) with each account. -* Use SSL/TLS to communicate with |AWS| resources. +* Use SSL/TLS to communicate with |AWS| resources. To use a minimum TLS version of 1.2, see `Enforcing TLS 1.2 `_. * Set up API and user activity logging with |CTlong|. * Use |AWS| encryption solutions, along with all default security controls within |AWS| services. * Use advanced managed security services such as |MCElong|, which assists in discovering and securing personal data that diff --git a/doc_source/security.rst b/doc_source/security.rst index 34d0c04..ac8c981 100644 --- a/doc_source/security.rst +++ b/doc_source/security.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -26,7 +26,7 @@ Security for |SERVICENAMETITLE| Data Protection Enforcing TLS 1.2 - Identity and Access Management - Compliance Validation - Resilience - Infrastructure Security + Identity and Access Management security-iam> + Compliance Validation + Resilience + Infrastructure Security From 5ffc174fbd7c0b20f2e7a7e48937c1290b990d8a Mon Sep 17 00:00:00 2001 From: Carey Burgess Date: Wed, 6 May 2020 10:39:33 -0700 Subject: [PATCH 75/83] fix broken links --- doc_source/compliance-validation.rst | 58 +++++++++++++++++++++ doc_source/disaster-recovery-resiliency.rst | 29 +++++++++++ doc_source/infrastructure-security.rst | 12 +++++ doc_source/security-iam.rst | 33 ++++++++++++ 4 files changed, 132 insertions(+) create mode 100644 doc_source/compliance-validation.rst create mode 100644 doc_source/disaster-recovery-resiliency.rst create mode 100644 doc_source/infrastructure-security.rst create mode 100644 doc_source/security-iam.rst diff --git a/doc_source/compliance-validation.rst b/doc_source/compliance-validation.rst new file mode 100644 index 0000000..f3ea15b --- /dev/null +++ b/doc_source/compliance-validation.rst @@ -0,0 +1,58 @@ +Compliance Validation for this AWS Product or Service +===================================================== + +This AWS product or service follows the `shared responsibility +model `__ +through the specific Amazon Web Services (AWS) services it supports. For +AWS service security information, see the `AWS service security +documentation +page `__ +and `AWS services that are in scope of AWS compliance efforts by +compliance +program `__. + +The security and compliance of AWS services is assessed by third-party +auditors as part of multiple AWS compliance programs. These include SOC, +PCI, FedRAMP, HIPAA, and others. AWS provides a frequently updated list +of AWS services in scope of specific compliance programs at `AWS +Services in Scope by Compliance +Program `__. + +Third-party audit reports are available for you to download using AWS +Artifact. For more information, see `Downloading Reports in AWS +Artifact `__. + +For more information about AWS compliance programs, see `AWS Compliance +Programs `__. + +Your compliance responsibility when using this AWS product or service to +access an AWS service is determined by the sensitivity of your data, +your organization’s compliance objectives, and applicable laws and +regulations. If your use of an AWS service is subject to compliance with +standards such as HIPAA, PCI, or FedRAMP, AWS provides resources to +help: + + + `Security and Compliance Quick Start Guides + `__ + – Deployment guides that discuss architectural considerations and provide steps for + deploying security-focused and compliance-focused baseline environments on AWS. + + + + `Architecting for HIPAA Security and Compliance Whitepaper + `__ + – A whitepaper that describes how companies can use AWS to create + HIPAA-compliant applications. + + + + `AWS Compliance Resources `__ + – A collection of workbooks and guides that might apply to your industry and + location. + + + + `AWS Config `__ – A service that assesses how well your + resource configurations comply with internal practices, industry guidelines, and regulations. + + + + `AWS Security Hub `__ – A comprehensive view of + your security state within AWS that helps you check your compliance with + security industry standards and best practices. diff --git a/doc_source/disaster-recovery-resiliency.rst b/doc_source/disaster-recovery-resiliency.rst new file mode 100644 index 0000000..e4abd93 --- /dev/null +++ b/doc_source/disaster-recovery-resiliency.rst @@ -0,0 +1,29 @@ +Resilience for this AWS Product or Service +========================================== + +The Amazon Web Services (AWS) global infrastructure is built around AWS +Regions and Availability Zones. + +AWS Regions provide multiple physically separated and isolated +Availability Zones, which are connected with low-latency, +high-throughput, and highly redundant networking. + +With Availability Zones, you can design and operate applications and +databases that automatically fail over between Availability Zones +without interruption. Availability Zones are more highly available, +fault tolerant, and scalable than traditional single or multiple data +center infrastructures. + +For more information about AWS Regions and Availability Zones, see `AWS +Global +Infrastructure `__. + +This AWS product or service follows the `shared responsibility +model `__ +through the specific Amazon Web Services (AWS) services it supports. For +AWS service security information, see the `AWS service security +documentation +page `__ +and `AWS services that are in scope of AWS compliance efforts by +compliance +program `__. diff --git a/doc_source/infrastructure-security.rst b/doc_source/infrastructure-security.rst new file mode 100644 index 0000000..10e994e --- /dev/null +++ b/doc_source/infrastructure-security.rst @@ -0,0 +1,12 @@ +Infrastructure Security for this AWS Product or Service +======================================================= + +This AWS product or service follows the `shared responsibility +model `__ +through the specific Amazon Web Services (AWS) services it supports. For +AWS service security information, see the `AWS service security +documentation +page `__ +and `AWS services that are in scope of AWS compliance efforts by +compliance +program `__. diff --git a/doc_source/security-iam.rst b/doc_source/security-iam.rst new file mode 100644 index 0000000..65b77e6 --- /dev/null +++ b/doc_source/security-iam.rst @@ -0,0 +1,33 @@ +Identity and Access Management for this AWS Product or Service +============================================================== + +AWS Identity and Access Management (IAM) is an Amazon Web Services (AWS) +service that helps an administrator securely control access to AWS +resources. IAM administrators control who can be *authenticated* (signed +in) and *authorized* (have permissions) to use resources in AWS +services. IAM is an AWS service that you can use with no additional +charge. + +To use this AWS product or service to access AWS, you need an AWS +account and AWS credentials. To increase the security of your AWS +account, we recommend that you use an *IAM user* to provide access +credentials instead of using your AWS account credentials. + +For details about working with IAM, see `AWS Identity and Access +Management `__. + +For an overview of IAM users and why they are important for the security +of your account, see `AWS Security +Credentials `__ +in the `Amazon Web Services General +Reference `__. + +This AWS product or service follows the `shared responsibility +model `__ +through the specific Amazon Web Services (AWS) services it supports. For +AWS service security information, see the `AWS service security +documentation +page `__ +and `AWS services that are in scope of AWS compliance efforts by +compliance +program `__. From c158b32ac47684c6b4ad99801682d93e99cf8b94 Mon Sep 17 00:00:00 2001 From: Carey Burgess Date: Wed, 6 May 2020 10:49:08 -0700 Subject: [PATCH 76/83] minor change --- doc_source/security.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/security.rst b/doc_source/security.rst index ac8c981..978ff0d 100644 --- a/doc_source/security.rst +++ b/doc_source/security.rst @@ -26,7 +26,7 @@ Security for |SERVICENAMETITLE| Data Protection Enforcing TLS 1.2 - Identity and Access Management security-iam> + Identity and Access Management Compliance Validation Resilience Infrastructure Security From 95675ca9002e5eebf4a40b618f3f01350a8ca264 Mon Sep 17 00:00:00 2001 From: Carey Burgess Date: Tue, 12 May 2020 09:40:02 -0700 Subject: [PATCH 77/83] fix typo --- doc_source/examples-s3-transfermanager.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/examples-s3-transfermanager.rst b/doc_source/examples-s3-transfermanager.rst index 5828351..a3e62e7 100644 --- a/doc_source/examples-s3-transfermanager.rst +++ b/doc_source/examples-s3-transfermanager.rst @@ -45,7 +45,7 @@ Upload Files and Directories Upload a Single File -------------------- -Call the |xfermgr| :methodname:`upload` method, providing an |S3| +Call |xfermgr|'s :methodname:`upload` method, providing an |S3| bucket name, a key (object) name, and a standard Java :javase-ref:`File ` object that represents the file to upload. From acefbcb5ef67dd4ab39f7bf0f16e3fcc365fe27f Mon Sep 17 00:00:00 2001 From: Carey Burgess Date: Tue, 19 May 2020 22:39:49 -0700 Subject: [PATCH 78/83] fix code example; rst edits --- doc_source/examples-ec2-regions-zones.rst | 59 ++++++++++++----------- doc_source/setup-project-gradle.rst | 4 +- 2 files changed, 32 insertions(+), 31 deletions(-) diff --git a/doc_source/examples-ec2-regions-zones.rst b/doc_source/examples-ec2-regions-zones.rst index ea9de5c..ecde885 100644 --- a/doc_source/examples-ec2-regions-zones.rst +++ b/doc_source/examples-ec2-regions-zones.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -8,9 +8,9 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. -#################################### -Using Regions and Availability Zones -#################################### +################################## +Use regions and availability zones +################################## .. meta:: :description: How to list EC2 regions and availability zones using the AWS SDK for Java. @@ -18,8 +18,8 @@ Using Regions and Availability Zones zones, describe availability zones -Describing Regions -================== +Describe regions +================ To list the Regions available to your account, call the |ec2client|'s :methodname:`describeRegions` method. It returns a :aws-java-class:`DescribeRegionsResult @@ -29,22 +29,20 @@ each Region. **Imports** -.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/DescribeRegionsAndZones.java - :lines: 16-19 +.. literalinclude:: ec2.java.describe_region_and_zones.import.txt :language: java **Code** -.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/DescribeRegionsAndZones.java - :lines: 30-40 +.. literalinclude:: ec2.java1.describe_region_and_zones.regions.txt :dedent: 8 :language: java See the :sdk-examples-java-ec2:`complete example `. -Describing Availability Zones -============================= +Describe availability zones +=========================== To list each Availability Zone available to your account, call the |ec2client|'s :methodname:`describeAvailabilityZones` method. It returns a @@ -55,50 +53,53 @@ objects that represent each Availability Zone. **Imports** -.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/DescribeRegionsAndZones.java - :lines: 16-19 +.. literalinclude:: ec2.java.describe_region_and_zones.import.txt :language: java **Code** -.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/DescribeRegionsAndZones.java - :lines: 42-53 +.. literalinclude:: ec2.java1.describe_region_and_zones.zones.txt :dedent: 8 :language: java See the :sdk-examples-java-ec2:`complete example `. -Describing Accounts -================== +Describe accounts +================= To describe your account, call the |ec2client|'s :methodname:`describeAccountAttributes` -method. This method returns a :aws-java-class:`DescribeAccountAttributesResult ` object. -Invoke this objects :methodname:`getAccountAttributes` method to get a list of :aws-java-class:`AccountAttribute -` objects. You can iterate through the list to retrieve an +method. This method returns a +:aws-java-class:`DescribeAccountAttributesResult ` +object. +Invoke this objects :methodname:`getAccountAttributes` method to get a list of +:aws-java-class:`AccountAttribute ` objects. You can iterate +through the list to retrieve an :aws-java-class:`AccountAttribute ` object. -You can -get your account's attribute values by invoking the :aws-java-class:`AccountAttribute ` object's -:methodname:`getAttributeValues` method. This method returns a list of :aws-java-class:`AccountAttributeValue -` objects. You can iterate through this second list to display the value of attributes (see the following code example). +You can get your account's attribute values by invoking the +:aws-java-class:`AccountAttribute ` object's +:methodname:`getAttributeValues` method. This method returns a list of +:aws-java-class:`AccountAttributeValue ` objects. You can +iterate through this second list to display the value of attributes (see the following code +example). **Imports** -.. literalinclude:: ec2.java2.describe_region_and_zones.import.txt +.. literalinclude:: ec2.java1.describe_account.import.txt :language: java **Code** -.. literalinclude:: ec2.java2.describe_region_and_zones.region.txt +.. literalinclude:: ec2.java1.describe_account.main.txt :dedent: 8 :language: java -See the :sdk-examples-java-ec2:`complete example ` on GitHub. +See the :sdk-examples-java-ec2:`complete example ` on GitHub. -More Information +More information ================ * :ec2-ug:`Regions and Availability Zones ` in the |ec2-ug| diff --git a/doc_source/setup-project-gradle.rst b/doc_source/setup-project-gradle.rst index aa12322..a6d4dd6 100644 --- a/doc_source/setup-project-gradle.rst +++ b/doc_source/setup-project-gradle.rst @@ -25,7 +25,7 @@ To manage SDK dependencies for your Gradle_ project, import the Maven BOM for th Project setup for Gradle 4.6 or higher -=============== +====================================== `Since Gradle 4.6 `_, you can use Gradle's improved POM support feature for importing bill of materials (BOM) files by declaring a dependency on a BOM. @@ -88,7 +88,7 @@ The following is an example of a complete :file:`build.gradle` file that include Project setup for Gradle versions earlier than 4.6 -=============== +================================================== Gradle versions earlier than 4.6 lack native BOM support. To manage |sdk-java| dependencies for your project, use Spring's `dependency management plugin From f3f38e48cee8fefe6cb066ecafd7e253d8ded031 Mon Sep 17 00:00:00 2001 From: Carey Burgess Date: Wed, 20 May 2020 06:52:40 -0700 Subject: [PATCH 79/83] update import snippet tag --- doc_source/examples-ec2-regions-zones.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/examples-ec2-regions-zones.rst b/doc_source/examples-ec2-regions-zones.rst index ecde885..568ae5e 100644 --- a/doc_source/examples-ec2-regions-zones.rst +++ b/doc_source/examples-ec2-regions-zones.rst @@ -29,7 +29,7 @@ each Region. **Imports** -.. literalinclude:: ec2.java.describe_region_and_zones.import.txt +.. literalinclude:: ec2.java1.describe_region_and_zones.import.txt :language: java **Code** @@ -53,7 +53,7 @@ objects that represent each Availability Zone. **Imports** -.. literalinclude:: ec2.java.describe_region_and_zones.import.txt +.. literalinclude:: ec2.java1.describe_region_and_zones.import.txt :language: java **Code** From 145c82df43f9eeed5f9d9498301e873ce4eb1c66 Mon Sep 17 00:00:00 2001 From: Carey Burgess Date: Wed, 8 Jul 2020 11:11:57 -0700 Subject: [PATCH 80/83] Update credentials chain order --- doc_source/credentials.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/credentials.rst b/doc_source/credentials.rst index 758ad44..2d017ea 100644 --- a/doc_source/credentials.rst +++ b/doc_source/credentials.rst @@ -48,6 +48,8 @@ class. The default credential provider chain looks for credentials in this order The |sdk-java| uses the :aws-java-class:`SystemPropertiesCredentialsProvider ` to load these credentials. +#. **Web Identity Token credentials** from the environment or container. + #. **The default credential profiles file** |ndash| typically located at :file:`~/.aws/credentials` (location can vary per platform), and shared by many of the AWS SDKs and by the AWS CLI. The |sdk-java| uses the :aws-java-class:`ProfileCredentialsProvider ` to load these credentials. @@ -70,8 +72,6 @@ class. The default credential provider chain looks for credentials in this order :aws-java-class:`EC2ContainerCredentialsProviderWrapper ` for more information. -#. **Web Identity Token credentials** from the environment or container. - Setting Credentials ------------------- From d10c8fdbdd9710b3eec98cee7e50fa6550392a90 Mon Sep 17 00:00:00 2001 From: Carey Burgess Date: Mon, 10 Aug 2020 13:30:08 -0700 Subject: [PATCH 81/83] update gitignore --- doc_source/.gitignore | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc_source/.gitignore b/doc_source/.gitignore index 5193fae..4423b35 100644 --- a/doc_source/.gitignore +++ b/doc_source/.gitignore @@ -1 +1,3 @@ example_code +.vscode +_build \ No newline at end of file From c03e32c1b936ff06afc44b82a340fa7dada0fb33 Mon Sep 17 00:00:00 2001 From: Carey Burgess Date: Mon, 10 Aug 2020 13:40:52 -0700 Subject: [PATCH 82/83] 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 --- doc_source/examples-crypto-kms.rst | 132 +++++------ doc_source/examples-crypto-masterkey.rst | 126 ++++------- doc_source/examples-crypto.rst | 30 ++- doc_source/s3-encryption-migration.rst | 276 +++++++++++++++++++++++ doc_source/security.rst | 5 +- 5 files changed, 394 insertions(+), 175 deletions(-) create mode 100644 doc_source/s3-encryption-migration.rst diff --git a/doc_source/examples-crypto-kms.rst b/doc_source/examples-crypto-kms.rst index 68bc328..b0dc34d 100644 --- a/doc_source/examples-crypto-kms.rst +++ b/doc_source/examples-crypto-kms.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -9,7 +9,7 @@ limitations under the License. ################################################### -|S3| Client-Side Encryption with |KMS| Managed Keys +|S3| client-side encryption with |KMS| managed keys ################################################### .. meta:: @@ -17,7 +17,7 @@ :keywords: AWS SDK for Java code examples, cryptography, encryption The following examples use the -:aws-java-class:`AmazonS3EncryptionClientBuilder ` class +:aws-java-class:`AmazonS3EncryptionClientV2Builder ` class to create an |S3| client with client-side encryption enabled. Once configured, any objects you upload to |S3| using this client will be encrypted. Any objects you get from |S3| using this client are automatically @@ -28,61 +28,82 @@ decrypted. encryption with |KMS| managed keys. To learn how to use encryption with your own keys, see :doc:`examples-crypto-masterkey`. -You can choose from three encryption modes when enabling client-side |S3| encryption: encryption-only, -authenticated, and strict authenticated. +You can choose from two encryption modes when enabling client-side |S3| encryption: strict +authenticated or authenticated. The following sections show how to enable each type. To learn which algorithms each mode uses, see the :aws-java-class:`CryptoMode ` definition. -Required Imports +Required imports ================ Import the following classes for these examples. **Imports** -.. literalinclude:: s3.java1.s3_encrypt.import.txt - :language: java +.. code-block:: java + + import com.amazonaws.ClientConfiguration; + import com.amazonaws.regions.Regions; + import com.amazonaws.services.kms.AWSKMS; + import com.amazonaws.services.kms.AWSKMSClientBuilder; + import com.amazonaws.services.kms.model.GenerateDataKeyRequest; + import com.amazonaws.services.kms.model.GenerateDataKeyResult; + import com.amazonaws.services.s3.AmazonS3EncryptionClientV2Builder; + import com.amazonaws.services.s3.AmazonS3EncryptionV2; + import com.amazonaws.services.s3.model.CryptoConfigurationV2; + import com.amazonaws.services.s3.model.CryptoMode; + import com.amazonaws.services.s3.model.EncryptionMaterials; + import com.amazonaws.services.s3.model.KMSEncryptionMaterialsProvider; -.. _encryption-only-kms: +.. _strict-authenticated-encryption-kms: -Encryption-Only Mode -==================== +Strict authenticated encryption +=============================== -Encryption-only is the default mode, if no :classname:`CryptoMode` is specified. -To use an |KMS| -managed key for encryption, pass the |KMS| key ID or alias to the -:aws-java-class:`KMSEncryptionMaterialsProvider` constructor. +Strict authenticated encryption is the default mode if no :classname:`CryptoMode` is specified. + +To explicitly enable this mode, specify the :classname:`StrictAuthenticatedEncryption` value in the +:methodName:`withCryptoConfiguration` method. + +.. note:: To use client-side authenticated encryption, you must include the latest + `Bouncy Castle jar `_ file + in the classpath of your application. **Code** -.. literalinclude:: s3.java1.s3_encrypt.kms_encryption_only_build.txt - :dedent: 8 - :language: java +.. code-block:: java + + AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard() + .withRegion(Regions.US_WEST_2) + .withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.StrictAuthenticatedEncryption))) + .withEncryptionMaterialsProvider(new KMSEncryptionMaterialsProvider(keyId)) + .build(); + + s3Encryption.putObject(bucket_name, ENCRYPTED_KEY3, "This is the 3rd content to encrypt with a key created in the AWS Console"); + System.out.println(s3Encryption.getObjectAsString(bucket_name, ENCRYPTED_KEY3)); Call the :methodname:`putObject` method on the |S3| encryption client to upload objects. **Code** -.. literalinclude:: s3.java1.s3_encrypt.kms_encryption_only_put_object.txt - :dedent: 8 - :language: java +.. code-block:: java + + s3Encryption.putObject(bucket_name, ENCRYPTED_KEY3, "This is the 3rd content to encrypt with a key created in the AWS Console"); You can retrieve the object using the same client. This example calls the :methodname:`getObjectAsString` method to retrieve the string that was stored. **Code** -.. literalinclude:: s3.java1.s3_encrypt.kms_encryption_only_retrieve.txt - :dedent: 8 - :language: java +.. code-block:: java -See the :sdk-examples-java-s3:`complete example ` on GitHub. + System.out.println(s3Encryption.getObjectAsString(bucket_name, ENCRYPTED_KEY3)); .. _authenticated-encryption-kms: -Authenticated Encryption Mode +Authenticated encryption mode ============================= 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 **Code** -.. literalinclude:: s3.java1.s3_encrypt.kms_authenticated_encryption_builder.txt - :dedent: 8 - :language: java - -The :classname:`AuthenticatedEncryption` mode can retrieve unencrypted objects and -objects encrypted with :classname:`EncryptionOnly` mode. The following example shows the -|S3| encryption client retrieving an unencrypted object. - -**Code** - -.. literalinclude:: s3.java1.s3_encrypt.kms_authenticated_encryption_put_object.txt - :dedent: 8 - :language: java - -See the :sdk-examples-java-s3:`complete example ` on GitHub. - -.. _strict-authenticated-encryption-kms: - -Strict Authenticated Encryption -=============================== - -To enable this mode, specify the :classname:`StrictAuthenticatedEncryption` value in the -:methodName:`withCryptoConfiguration` method. - -.. note:: To use client-side authenticated encryption, you must include the latest - `Bouncy Castle jar `_ file - in the classpath of your application. - -**Code** - -.. literalinclude:: s3.java1.s3_encrypt.kms_authenticated_encryption_strict_builder.txt - :dedent: 8 - :language: java - -Call the :methodname:`putObject` method on the |S3| encryption client to upload objects. - -**Code** - -.. literalinclude:: s3.java1.s3_encrypt.kms_authenticated_encryption_strict_put_object.txt - :dedent: 8 - :language: java - -In :classname:`StrictAuthenticatedEncryption` mode, the |S3| client throws an -exception when retrieving an object that was not encrypted using an -authenticated mode. - -**Code** - -.. literalinclude:: s3.java1.s3_encrypt.kms_authenticated_encryption_strict_exception.txt - :dedent: 8 - :language: java +.. code-block:: java -See the :sdk-examples-java-s3:`complete example ` on GitHub. + AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard() + .withRegion(Regions.US_WEST_2) + .withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.AuthenticatedEncryption))) + .withEncryptionMaterialsProvider(new KMSEncryptionMaterialsProvider(keyId)) + .build(); + \ No newline at end of file diff --git a/doc_source/examples-crypto-masterkey.rst b/doc_source/examples-crypto-masterkey.rst index 5ae4458..5afbd50 100644 --- a/doc_source/examples-crypto-masterkey.rst +++ b/doc_source/examples-crypto-masterkey.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -9,7 +9,7 @@ limitations under the License. ################################################### -|S3| Client-Side Encryption with Client Master Keys +|S3| client-side encryption with client master keys ################################################### .. meta:: @@ -17,7 +17,7 @@ :keywords: AWS SDK for Java code examples The following examples use the -:aws-java-class:`AmazonS3EncryptionClientBuilder ` class +:aws-java-class:`AmazonS3EncryptionClientV2Builder ` class to create an |S3| client with client-side encryption enabled. Once enabled, any objects you upload to |S3| using this client will be encrypted. Any objects you get from |S3| using this client will automatically @@ -28,69 +28,57 @@ be decrypted. encryption with customer-managed client master keys. To learn how to use encryption with |KMS| managed keys, see :doc:`examples-crypto-kms`. -You can choose from three encryption modes when enabling client-side |S3| encryption: encryption-only, -authenticated, and strict authenticated. +You can choose from two encryption modes when enabling client-side |S3| encryption: strict +authenticated or authenticated. The following sections show how to enable each type. To learn which algorithms each mode uses, see the :aws-java-class:`CryptoMode ` definition. -Required Imports +Required imports ================ Import the following classes for these examples. **Imports** -.. literalinclude:: s3.java1.s3_encrypt.import.txt - :language: java +.. code-block:: java -.. _encryption-only: + import com.amazonaws.ClientConfiguration; + import com.amazonaws.regions.Regions; + import com.amazonaws.services.s3.AmazonS3EncryptionClientV2Builder; + import com.amazonaws.services.s3.AmazonS3EncryptionV2; + import com.amazonaws.services.s3.model.CryptoConfigurationV2; + import com.amazonaws.services.s3.model.CryptoMode; + import com.amazonaws.services.s3.model.EncryptionMaterials; + import com.amazonaws.services.s3.model.StaticEncryptionMaterialsProvider; -Encryption-Only Mode -==================== - -Encryption-only is the default mode, if no :classname:`CryptoMode` is specified. To enable -encryption, you must pass a key to the :aws-java-class:`EncryptionMaterials` -constructor. The example below uses -the :class:`KeyGenerator` Java class generate a symmetric private key. - -**Code** - -.. literalinclude:: s3.java1.s3_encrypt.encryption_only.txt - :dedent: 4 - :language: java +.. _strict-authenticated-encryption: -To use an asymmetric key or a key pair, simply pass the key pair to the same -:aws-java-class:`EncryptionMaterials` class. The example below uses the -:class:`KeyPairGenerator` class to generate a key pair. +Strict authenticated encryption +=============================== -**Code** +Strict authenticated encryption is the default mode if no :classname:`CryptoMode` is specified. -.. literalinclude:: s3.java1.s3_encrypt.encryption_only_asymetric_key_build.txt - :dedent: 8 - :language: java +To explicitly enable this mode, specify the :classname:`StrictAuthenticatedEncryption` value in the +:methodName:`withCryptoConfiguration` method. -Call the :methodname:`putObject` method on the |S3| encryption client to upload objects. +.. note:: To use client-side authenticated encryption, you must include the latest + `Bouncy Castle jar `_ file + in the classpath of your application. **Code** -.. literalinclude:: s3.java1.s3_encrypt.encryption_only_asymetric_key_put_object.txt - :dedent: 8 - :language: java - -You can retrieve the object using the same client. This example calls the -:methodname:`getObjectAsString` method to retrieve the string that was stored. - -**Code** +.. code-block:: java -.. literalinclude:: s3.java1.s3_encrypt.encryption_only_asymetric_key_retrieve.txt - :dedent: 8 - :language: java + AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard() + .withRegion(Regions.US_WEST_2) + .withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.StrictAuthenticatedEncryption))) + .withEncryptionMaterialsProvider(new StaticEncryptionMaterialsProvider(new EncryptionMaterials(secretKey))) + .build(); -See the :sdk-examples-java-s3:`complete example ` on GitHub. + s3Encryption.putObject(bucket_name, ENCRYPTED_KEY2, "This is the 2nd content to encrypt"); -.. _authenticated-encryption: -Authenticated Encryption Mode +Authenticated encryption mode ============================= 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 **Code** -.. literalinclude:: s3.java1.s3_encrypt.authenticated_encryption_build.txt - :dedent: 8 - :language: java - -The :classname:`AuthenticatedEncryption` mode can retrieve unencrypted objects and -objects encrypted with :classname:`EncryptionOnly` mode. The following example shows the -|S3| encryption client retrieving an unencrypted object. - -**Code** - -.. literalinclude:: s3.java1.s3_encrypt.authenticated_encryption.txt - :dedent: 4 - :language: java - -See the :sdk-examples-java-s3:`complete example ` on GitHub. - -.. _strict-authenticated-encryption: - -Strict Authenticated Encryption -=============================== - -To enable this mode, specify the :classname:`StrictAuthenticatedEncryption` value in the -:methodName:`withCryptoConfiguration` method. - -.. note:: To use client-side authenticated encryption, you must include the latest - `Bouncy Castle jar `_ file - in the classpath of your application. - -**Code** - -.. literalinclude:: s3.java1.s3_encrypt.strict_authenticated_encryption_build.txt - :dedent: 8 - :language: java +.. code-block:: java -In :classname:`StrictAuthenticatedEncryption` mode, the |S3| client throws an -exception when retrieving an object that was not encrypted using an -authenticated mode. - -**Code** + AmazonS3EncryptionV2 s3EncryptionClientV2 = AmazonS3EncryptionClientV2Builder.standard() + .withRegion(Regions.DEFAULT_REGION) + .withClientConfiguration(new ClientConfiguration()) + .withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode(CryptoMode.AuthenticatedEncryption)) + .withEncryptionMaterialsProvider(new StaticEncryptionMaterialsProvider(new EncryptionMaterials(secretKey))) + .build(); -.. literalinclude:: s3.java1.s3_encrypt.strict_authenticated_encryption.txt - :dedent: 4 - :language: java + s3EncryptionClientV2.putObject(bucket_name, ENCRYPTED_KEY1, "This is the 1st content to encrypt"); -See the :sdk-examples-java-s3:`complete example ` on GitHub. diff --git a/doc_source/examples-crypto.rst b/doc_source/examples-crypto.rst index db71298..c37c681 100644 --- a/doc_source/examples-crypto.rst +++ b/doc_source/examples-crypto.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -8,9 +8,9 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. -################################# -Using |S3| Client-Side Encryption -################################# +############################### +Use |S3| client-side encryption +############################### .. meta:: :description: How to use the cryptography configuration settings for the AWS SDK for Java @@ -20,12 +20,25 @@ Encrypting data using the |S3| encryption client is one way you can provide an additional layer of protection for sensitive information you store in |S3|. The examples in this section demonstrate how to create and configure the |S3| encryption client for your application. -If you are new to cryptography, -see the :KMS-dg:`Cryptography Basics ` in the |KMS-dg| for a basic overview of -cryptography terms and algorithms. + +If you are new to cryptography, see the :KMS-dg:`Cryptography Basics ` in the |KMS-dg| +for a basic overview of cryptography terms and algorithms. For information about cryptography +support across all AWS SDKs, see +:AWS-gr:`AWS SDK Support for Amazon S3 Client-Side Encryption ` in the +|AWS-gr|. .. include:: includes/examples-note.txt +If you are using version 1.11.836 or earlier of the AWS SDK for Java, see +:doc:`s3-encryption-migration` for information on migrating your applications to later versions. +If you cannot migrate, see +`this complete example `_ +on GitHub. + +Otherwise, if you are using version 1.11.837 or later of the AWS SDK for Java, explore the example +topics listed below to use |S3| client-side encryption. + + .. toctree:: :titlesonly: :maxdepth: 1 @@ -33,5 +46,4 @@ cryptography terms and algorithms. examples-crypto-masterkey examples-crypto-kms -For information about cryptography support across all AWS SDKs, see -:AWS-gr:`AWS SDK Support for Amazon S3 Client-Side Encryption ` in the |AWS-gr|. + diff --git a/doc_source/s3-encryption-migration.rst b/doc_source/s3-encryption-migration.rst new file mode 100644 index 0000000..f6c93c0 --- /dev/null +++ b/doc_source/s3-encryption-migration.rst @@ -0,0 +1,276 @@ +.. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +################################ +|S3| Encryption Client Migration +################################ + +.. meta:: + :description: How to migrate your applications from v1 to v2 of the AWS S3 client-side encryption + service client + :keywords: AWS for Java SDK, migrate, migration, CSE, encryption, key, KMS, S3, + AmazonS3EncryptionClientV2, AmazonS3EncryptionClient + + +This topic shows you how to migrate your applications from Version 1 (V1) of the |S3long| (|S3|) +encryption client to Version 2 (V2) and ensure application availability throughout the migration +process. + +.. _s3-cse-prereq: + +Prerequisites +============= + +* |S3| client-side encryption requires Java 8 or later to be installed in your application + environment. + The |sdk-java| works with the + `Oracle Java SE Development Kit `_ + and with distributions of Open Java Development Kit (OpenJDK) such as + `Amazon Corretto `_, + `Red Hat OpenJDK `_, + and `AdoptOpenJDK `_. + +* You need to take a dependency on BouncyCastle. If you don't already have this, + go to https://bouncycastle.org/latest_releases.html and download the provider file that corresponds to your JDK. + Alternatively, you can pick it up from Maven (groupId: org.bouncycastle, artifactId: bcprov-ext-jdk15on)." + +.. _s3-cse-overview: + +Migration Overview +================== + +This migration happens in two phases: + +1. **Update existing clients to read new formats.** Update your application to use version 1.11.837 + or later of the AWS SDK for Java and redeploy the application. This enables the |S3| client-side + encryption service clients in your application to decrypt objects created by V2 service clients. + If your application uses multiple AWS SDKs, you must update each SDK separately. + +2. **Migrate encryption and decryption clients to V2.** Once all of your V1 encryption clients can + read V2 encryption formats, update the |S3| client-side encryption and decryption clients in your + application code to use their V2 equivalents. + +.. _s3-cse-update-project: + +Update Existing Clients to Read New Formats +=========================================== + +The V2 encryption client uses encryption algorithms that older versions of the AWS SDK for Java do +not support. + +The first step in the migration is to update your V1 encryption clients to use version 1.11.837 or +later of the |sdk-java|. (We recommend that you update to the latest release version, which you can +find in the +`Java API Reference version 1.x `_.) To do +so, update the dependency in your project configuration. After your project configuration is +updated, rebuild your project and redeploy it. + +Once you have completed these steps, your application’s V1 encryption clients will be able to read +objects written by V2 encryption clients. + +Update the Dependency in Your Project Configuration +--------------------------------------------------- + +Modify your project configuration file (for example, pom.xml or build.gradle) to use version +1.11.837 or later of the AWS SDK for Java. Then, rebuild your project and redeploy it. + +Completing this step before deploying new application code helps to ensure that encryption +and decryption operations remain consistent across your fleet during the migration process. + +Example Using Maven +~~~~~~~~~~~~~~~~~~~ + +Snippet from a pom.xml file: + +.. code-block:: xml + + + + + com.amazonaws + aws-java-sdk-bom + 1.11.837 + pom + import + + + + +Example Using Gradle +~~~~~~~~~~~~~~~~~~~~ + +Snippet from a build.gradle file: + +.. code-block:: json + + dependencies { + implementation platform('com.amazonaws:aws-java-sdk-bom:1.11.837') + implementation 'com.amazonaws:aws-java-sdk-s3' + } + +.. _s3-cse-update-code: + +Migrate Encryption and Decryption Clients to V2 +=============================================== + +Once your project has been updated with the latest SDK version, you can modify your application code +to use the V2 client. To do so, first update your code to use the new service client builder. Then +provide encryption materials using a method on the builder that has been renamed, and configure your +service client further as needed. + +These code snippets demonstrate how to use client-side encryption with the AWS SDK for Java, and +provide comparisons between the V1 and V2 encryption clients. + +**V1** + +.. code-block:: java + + // minimal configuration in V1; default CryptoMode.EncryptionOnly. + EncryptionMaterialsProvider encryptionMaterialsProvider = ... + AmazonS3Encryption encryptionClient = AmazonS3EncryptionClient.encryptionBuilder() + .withEncryptionMaterials(encryptionMaterialsProvider) + .build(); + +**V2** + +.. code-block:: java + + // minimal configuration in V2; default CryptoMode.StrictAuthenticatedEncryption. + EncryptionMaterialsProvider encryptionMaterialsProvider = ... + AmazonS3EncryptionV2 encryptionClient = AmazonS3EncryptionClientV2.encryptionBuilder() + .withEncryptionMaterialsProvider(encryptionMaterialsProvider) + .withCryptoConfiguration(new CryptoConfigurationV2() + // The following setting allows the client to read V1 encrypted objects + .withCryptoMode(CryptoMode.AuthenticatedEncryption) + ) + .build(); + +The above example sets the :code:`cryptoMode` to :code:`AuthenticatedEncryption`. This is a setting +that allows a V2 encryption client to read objects that have been written by a V1 encryption +client. If your client does not need the capability to read objects written by a V1 client, then we +recommend using the default setting of :code:`StrictAuthenticatedEncryption` instead. + +Construct a V2 Encryption Client +-------------------------------- + +The V2 encryption client can be constructed by calling +*AmazonS3EncryptionClientV2.encryptionBuilder().* + +You can replace all of your existing V1 encryption clients with V2 encryption clients. A V2 +encryption client will always be able to read any object that has been written by a V1 encryption +client as long as you permit it to do so by configuring the V2 encryption client to use the +:code:`AuthenticatedEncryption` :code:`cryptoMode`. + +Creating a new V2 encryption client is very similar to how you create a V1 encryption client. +However, there are a few differences: + +* You will use a :code:`CryptoConfigurationV2` object to configure the client instead of a + :code:`CryptoConfiguration` object. This parameter is required. +* The default :code:`cryptoMode` setting for the V2 encryption client is + :code:`StrictAuthenticatedEncryption`. For the V1 encryption client it is :code:`EncryptionOnly`. +* The method *withEncryptionMaterials()* on the encryption client builder has been renamed to + *withEncryptionMaterialsProvider()*. This is merely a cosmetic change that more accurately + reflects the argument type. You must use the new method when you configure your service client. + +.. note:: When decrypting with AES-GCM, read the entire object to the end before you start using the + decrypted data. This is to verify that the object has not been modified since it was encrypted. + + +Use Encryption Materials Providers +---------------------------------- + +You can continue to use the same encryption materials providers and encryption materials objects +you are already using with the V1 encryption client. These classes are responsible for providing the +keys the encryption client uses to secure your data. They can be used interchangeably with both the +V2 and the V1 encryption client. + +Configure the V2 Encryption Client +---------------------------------- + +The V2 encryption client is configured with a :code:`CryptoConfigurationV2` object. This object can be +constructed by calling its default constructor and then modifying its properties as required from +the defaults. + +The default values for :code:`CryptoConfigurationV2` are: + +* :code:`cryptoMode` = :code:`CryptoMode.StrictAuthenticatedEncryption` +* :code:`storageMode` = :code:`CryptoStorageMode.ObjectMetadata` +* :code:`secureRandom` = instance of :code:`SecureRandom` +* :code:`rangeGetMode` = :code:`CryptoRangeGetMode.DISABLED` +* :code:`unsafeUndecryptableObjectPassthrough` = :code:`false` + +Note that `EncryptionOnly` is not a supported :code:`cryptoMode` in the V2 encryption client. The V2 +encryption client will always encrypt content using authenticated encryption, and protects content +encrypting keys (CEKs) using V2 :code:`KeyWrap` objects. + +The following example demonstrates how to specify the crypto configuration in V1, and how to +instantiate a *CryptoConfigurationV2* object to pass to the V2 encryption client builder. + +**V1** + +.. code-block:: java + + CryptoConfiguration cryptoConfiguration = new CryptoConfiguration() + .withCryptoMode(CryptoMode.StrictAuthenticatedEncryption); + +**V2** + +.. code-block:: java + + CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2() + .withCryptoMode(CryptoMode.StrictAuthenticatedEncryption); + +.. _additional-examples: + +Additional Examples +=================== + +The following examples demonstrate how to address specific use cases related to a migration from V1 +to V2. + +Configure a Service Client to Read Objects Created by the V1 Encryption Client +------------------------------------------------------------------------------ + +To read objects that were previously written using a V1 encryption client, set the +:code:`cryptoMode` to :code:`AuthenticatedEncryption`. The following code snippet demonstrates how +to construct a configuration object with this setting. + +.. code-block:: java + + CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2() + .withCryptoMode(CryptoMode.AuthenticatedEncryption); + +Configure a Service Client to Get Byte Ranges of Objects +-------------------------------------------------------- + +To be able to :code:`get` a range of bytes from an encrypted S3 object, enable the new configuration +setting :code:`rangeGetMode`. This setting is disabled on the V2 encryption client by default. Note +that even when enabled, a ranged :code:`get` only works on objects that have been encrypted using +algorithms supported by the :code:`cryptoMode` setting of the client. For more information, see +:aws-java-class:`CryptoRangeGetMode ` in the AWS SDK for Java +API Reference. + +If you plan to use the |S3| TransferManager to perform multipart downloads of encrypted |S3| objects +using the V2 encryption client, then you must first enable the :code:`rangeGetMode` setting on the +V2 encryption client. + +The following code snippet demonstrates how to configure the V2 client for performing a ranged +:code:`get`. + +.. code-block:: java + + // Allows range gets using AES/CTR, for V2 encrypted objects only + CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2() + .withRangeGetMode(CryptoRangeGetMode.ALL); + + // Allows range gets using AES/CTR and AES/CBC, for V1 and V2 objects + CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2() + .withCryptoMode(CryptoMode.AuthenticatedEncryption) + .withRangeGetMode(CryptoRangeGetMode.ALL); diff --git a/doc_source/security.rst b/doc_source/security.rst index 978ff0d..bdb10ca 100644 --- a/doc_source/security.rst +++ b/doc_source/security.rst @@ -24,9 +24,10 @@ Security for |SERVICENAMETITLE| :maxdepth: 1 :titlesonly: + Compliance Validation Data Protection Enforcing TLS 1.2 Identity and Access Management - Compliance Validation - Resilience Infrastructure Security + Resilience + S3 Encryption Client Migration From b91e8e9db8b90f085af22f2f242428b495a5fc73 Mon Sep 17 00:00:00 2001 From: Carey Burgess Date: Thu, 15 Oct 2020 12:51:07 -0700 Subject: [PATCH 83/83] minor edit --- doc_source/s3-encryption-migration.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/doc_source/s3-encryption-migration.rst b/doc_source/s3-encryption-migration.rst index f6c93c0..0b09cac 100644 --- a/doc_source/s3-encryption-migration.rst +++ b/doc_source/s3-encryption-migration.rst @@ -28,18 +28,19 @@ process. Prerequisites ============= -* |S3| client-side encryption requires Java 8 or later to be installed in your application - environment. - The |sdk-java| works with the +|S3| client-side encryption requires the following: + +* Java 8 or later installed in your application environment. The |sdk-java| works with the `Oracle Java SE Development Kit `_ and with distributions of Open Java Development Kit (OpenJDK) such as `Amazon Corretto `_, `Red Hat OpenJDK `_, and `AdoptOpenJDK `_. -* You need to take a dependency on BouncyCastle. If you don't already have this, - go to https://bouncycastle.org/latest_releases.html and download the provider file that corresponds to your JDK. - Alternatively, you can pick it up from Maven (groupId: org.bouncycastle, artifactId: bcprov-ext-jdk15on)." +* The `Bouncy Castle Crypto package `_. You can + place the Bouncy Castle .jar file on the classpath of your application environment, or add a + dependency on the artifactId :code:`bcprov-ext-jdk15on` (with the groupId of + :code:`org.bouncycastle`) to your Maven :file:`pom.xml` file. .. _s3-cse-overview: