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 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/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/credentials.rst b/doc_source/credentials.rst index 291a869..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. @@ -59,17 +61,17 @@ 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 :aws-java-class:`EC2ContainerCredentialsProviderWrapper ` for more information. - Setting Credentials ------------------- diff --git a/doc_source/data-protection.rst b/doc_source/data-protection.rst new file mode 100644 index 0000000..185e987 --- /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. 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 + 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/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/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 bebc77e..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: 8 - :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: 8 - :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: 8 - :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/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 5caefc1..b360d0a 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -110,6 +110,32 @@ 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 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. + +**Imports** + +.. literalinclude:: dynamodb.java.dynamoDB_mapping.import.txt + :language: java + +**Code** + +The following Java code example shows you how to add content to the *Music* table by using the :aws-java-class:`DynamoDBMapper ` class. +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. 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: 1 + :language: java + +See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. More Info ========= diff --git a/doc_source/examples-ec2-regions-zones.rst b/doc_source/examples-ec2-regions-zones.rst index 4d93ba1..568ae5e 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.java1.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,21 +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.java1.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 `. +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 +: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.java1.describe_account.import.txt + :language: java + +**Code** + +.. literalinclude:: ec2.java1.describe_account.main.txt + :dedent: 8 + :language: java + +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/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 diff --git a/doc_source/examples-lambda.rst b/doc_source/examples-lambda.rst new file mode 100644 index 0000000..e524d4d --- /dev/null +++ b/doc_source/examples-lambda.rst @@ -0,0 +1,110 @@ +.. 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. To learn how to +create a Lambda function, see `How to Create AWS Lambda functions `_. + +.. contents:: + :local: + :depth: 1 + +.. _invoke-function: +Invoke a Lambda function +======================== + +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. + +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** + +.. literalinclude:: lambda.java1.invoke.import.txt + :language: java + +**Code** + +The following code example demonstrates how to invoke a Lambda function. + +.. literalinclude:: lambda.java1.invoke.main.txt + :language: java + +See the complete example on `Github +`_. + + +.. _list-function: + +List Lambda functions +===================== + +Build an :aws-java-class:`AWSLambda ` +object and invoke its :methodname:`listFunctions` method. +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. + + +**Imports** + +.. literalinclude:: lambda.java1.list.import.txt + :language: java + +**Code** + +The following Java code example demonstrates how to retrieve a list of Lambda function names. + +.. literalinclude:: lambda.java1.list.main.txt + :language: java + +See the complete example on `Github +`_. + + +.. _delete-function: + +Delete a Lambda function +======================== + +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. +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:: lambda.java1.delete.import.txt + :language: java + +**Code** + +The following Java code demonstrates how to delete a Lambda function. + +.. literalinclude:: lambda.java1.delete.main.txt + :language: java + +See the complete example on `Github +`_. + + 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 diff --git a/doc_source/examples-s3-objects.rst b/doc_source/examples-s3-objects.rst index e2dcc22..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: 46-52 + :lines: 48-64 :dedent: 8 :language: java 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. 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: 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/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/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. diff --git a/doc_source/java-dg-roles.rst b/doc_source/java-dg-roles.rst index bf90958..82f1fec 100644 --- a/doc_source/java-dg-roles.rst +++ b/doc_source/java-dg-roles.rst @@ -29,16 +29,20 @@ 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 +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 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/lambda-examples.rst b/doc_source/lambda-examples.rst new file mode 100644 index 0000000..2687321 --- /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. + :keywords: AWS SDK for Java code examples + +This section provides examples of programming Lambda using the |sdk-java|. + +.. include:: includes/complete-examples-note.txt + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Service Operations + diff --git a/doc_source/prog-services-sts.rst b/doc_source/prog-services-sts.rst index bbf4721..f82ecb5 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 @@ -68,23 +68,10 @@ Retrieve temporary security credentials from |STS| 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:`AWSSecurityTokenServiceClient 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. - #. :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 e623982..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,13 +35,13 @@ 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 AWS Identity and Access Management (IAM) Examples + Amazon Lambda Examples 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/s3-encryption-migration.rst b/doc_source/s3-encryption-migration.rst new file mode 100644 index 0000000..0b09cac --- /dev/null +++ b/doc_source/s3-encryption-migration.rst @@ -0,0 +1,277 @@ +.. 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 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 `_. + +* 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: + +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/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/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. 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 `__. diff --git a/doc_source/security-java-tls.rst b/doc_source/security-java-tls.rst new file mode 100644 index 0000000..68d9899 --- /dev/null +++ b/doc_source/security-java-tls.rst @@ -0,0 +1,63 @@ +.. 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. + +##################################### +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. + :keywords: + +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 in Java 7. + +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 + + 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 the TLS version +========================== + +**AWS SDK for Java 1.x** + +* Apache HTTP client: The SDK always prefers TLS 1.2 (if it's supported in the platform). + +**AWS SDK for Java 2.x** + +* ApacheHttpClient: The SDK always prefers TLS 1.2 (if it's supported in the platform). + +* 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 use this code. + +.. code-block:: java + + System.setProperty("jdk.tls.client.protocols", "TLSv1.2"); + +* 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 new file mode 100644 index 0000000..bdb10ca --- /dev/null +++ b/doc_source/security.rst @@ -0,0 +1,33 @@ +.. 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. + +############################### +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: + + Compliance Validation + Data Protection + Enforcing TLS 1.2 + Identity and Access Management + Infrastructure Security + Resilience + S3 Encryption Client Migration diff --git a/doc_source/setup-credentials.rst b/doc_source/setup-credentials.rst index c9caf99..7042377 100644 --- a/doc_source/setup-credentials.rst +++ b/doc_source/setup-credentials.rst @@ -48,6 +48,33 @@ 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. +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: + + 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. + 13. credentials.close(); + + .. _setup-credentials-setting-region: Setting the AWS Region @@ -65,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 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: diff --git a/doc_source/setup-project-gradle.rst b/doc_source/setup-project-gradle.rst index a4a6912..a6d4dd6 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 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,38 +12,58 @@ Using the SDK with Gradle ######################### -`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 +.. 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 - #. Enable `IMPROVED_POM_SUPPORT` feature in :file:`settings.gradle` file (not needed in Gradle 5 and upper) + +To manage SDK dependencies for your Gradle_ project, import the Maven BOM for the |sdk-java| into the :file:`build.gradle` file. + +.. 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 `_. + + +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 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 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 to use in the *dependencies* section. For example, the following includes a dependency for |S3long| (|S3|). .. 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. +Gradle automatically resolves the correct version of your SDK dependencies by 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 @@ -59,18 +79,24 @@ 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:: 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 earlier than 4.6 +================================================== -.. topic:: To configure the SDK for Gradle prior 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 +`_ for Gradle to import the Maven BOM for the SDK. - #. Add the dependency management plugin to your :file:`build.gradle` file +.. topic:: To configure the SDK for Gradle versions earlier than 4.6 + + #. Add the dependency management plugin to your :file:`build.gradle` file. .. code-block:: groovy @@ -79,40 +105,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 use in the *dependencies* section. For example, the following includes a dependency for |S3|. .. 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 by 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' @@ -124,10 +148,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" } } @@ -135,7 +159,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' } } @@ -144,5 +168,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:: 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 information about specifying SDK dependencies by using the BOM, see +:doc:`setup-project-maven`. diff --git a/doc_source/setup-project-maven.rst b/doc_source/setup-project-maven.rst index d71d415..8fadd1d 100644 --- a/doc_source/setup-project-maven.rst +++ b/doc_source/setup-project-maven.rst @@ -111,6 +111,8 @@ component. +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: