Package software.amazon.encryption.s3

Class S3EncryptionClient

  • All Implemented Interfaces:
    AutoCloseable, software.amazon.awssdk.awscore.AwsClient, software.amazon.awssdk.core.SdkClient, software.amazon.awssdk.services.s3.S3Client, software.amazon.awssdk.utils.SdkAutoCloseable
    public class S3EncryptionClient
extends software.amazon.awssdk.services.s3.DelegatingS3Client
    This client is a drop-in replacement for the S3 client. It will automatically encrypt objects on putObject and decrypt objects on getObject using the provided encryption key(s).

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      software.amazon.awssdk.services.s3.model.AbortMultipartUploadResponse abortMultipartUpload​(software.amazon.awssdk.services.s3.model.AbortMultipartUploadRequest request)
      See S3Client.abortMultipartUpload(AbortMultipartUploadRequest)
      static S3EncryptionClient.Builder builder()
      Creates a builder that can be used to configure and create a S3EncryptionClient.
      void close()
      Closes the wrapped clients.
      software.amazon.awssdk.services.s3.model.CompleteMultipartUploadResponse completeMultipartUpload​(software.amazon.awssdk.services.s3.model.CompleteMultipartUploadRequest request)
      See S3Client.completeMultipartUpload(CompleteMultipartUploadRequest)
      software.amazon.awssdk.services.s3.model.CreateMultipartUploadResponse createMultipartUpload​(software.amazon.awssdk.services.s3.model.CreateMultipartUploadRequest request)
      See S3Client.createMultipartUpload(CreateMultipartUploadRequest)
      software.amazon.awssdk.services.s3.model.DeleteObjectResponse deleteObject​(software.amazon.awssdk.services.s3.model.DeleteObjectRequest deleteObjectRequest)
      See S3Client.deleteObject(DeleteObjectRequest).
      software.amazon.awssdk.services.s3.model.DeleteObjectsResponse deleteObjects​(software.amazon.awssdk.services.s3.model.DeleteObjectsRequest deleteObjectsRequest)
      See S3Client.deleteObjects(DeleteObjectsRequest).
      <T> T getObject​(software.amazon.awssdk.services.s3.model.GetObjectRequest getObjectRequest, software.amazon.awssdk.core.sync.ResponseTransformer<software.amazon.awssdk.services.s3.model.GetObjectResponse,​T> responseTransformer)
      See getObject(GetObjectRequest, ResponseTransformer)
      software.amazon.awssdk.services.s3.model.PutObjectResponse putObject​(software.amazon.awssdk.services.s3.model.PutObjectRequest putObjectRequest, software.amazon.awssdk.core.sync.RequestBody requestBody)
      See putObject(PutObjectRequest, RequestBody).
      ReEncryptInstructionFileResponse reEncryptInstructionFile​(ReEncryptInstructionFileRequest reEncryptInstructionFileRequest)
      Re-encrypts an instruction file with a new keyring while preserving the original encrypted object in S3.
      software.amazon.awssdk.services.s3.model.UploadPartResponse uploadPart​(software.amazon.awssdk.services.s3.model.UploadPartRequest request, software.amazon.awssdk.core.sync.RequestBody requestBody)
      See S3Client.uploadPart(UploadPartRequest, RequestBody) NOTE: Because the encryption process requires context from block N-1 in order to encrypt block N, parts uploaded with the S3EncryptionClient (as opposed to the normal S3Client) must be uploaded serially, and in order.
      static Consumer<software.amazon.awssdk.awscore.AwsRequestOverrideConfiguration.Builder> withAdditionalConfiguration​(Map<String,​String> encryptionContext)
      Attaches encryption context to a request.
      static Consumer<software.amazon.awssdk.awscore.AwsRequestOverrideConfiguration.Builder> withAdditionalConfiguration​(Map<String,​String> encryptionContext, MultipartConfiguration multipartConfiguration)
      Attaches encryption context and multipart configuration to a request
      static Consumer<software.amazon.awssdk.awscore.AwsRequestOverrideConfiguration.Builder> withAdditionalConfiguration​(MultipartConfiguration multipartConfiguration)
      Attaches multipart configuration to a request.
      static Consumer<software.amazon.awssdk.awscore.AwsRequestOverrideConfiguration.Builder> withCustomInstructionFileSuffix​(String customInstructionFileSuffix)
      Attaches a custom instruction file suffix to a request.

      • Methods inherited from class software.amazon.awssdk.services.s3.DelegatingS3Client

        copyObject, createBucket, createBucketMetadataTableConfiguration, createSession, delegate, deleteBucket, deleteBucketAnalyticsConfiguration, deleteBucketCors, deleteBucketEncryption, deleteBucketIntelligentTieringConfiguration, deleteBucketInventoryConfiguration, deleteBucketLifecycle, deleteBucketMetadataTableConfiguration, deleteBucketMetricsConfiguration, deleteBucketOwnershipControls, deleteBucketPolicy, deleteBucketReplication, deleteBucketTagging, deleteBucketWebsite, deleteObjectTagging, deletePublicAccessBlock, getBucketAccelerateConfiguration, getBucketAcl, getBucketAnalyticsConfiguration, getBucketCors, getBucketEncryption, getBucketIntelligentTieringConfiguration, getBucketInventoryConfiguration, getBucketLifecycleConfiguration, getBucketLocation, getBucketLogging, getBucketMetadataTableConfiguration, getBucketMetricsConfiguration, getBucketNotificationConfiguration, getBucketOwnershipControls, getBucketPolicy, getBucketPolicyStatus, getBucketReplication, getBucketRequestPayment, getBucketTagging, getBucketVersioning, getBucketWebsite, getObjectAcl, getObjectAttributes, getObjectLegalHold, getObjectLockConfiguration, getObjectRetention, getObjectTagging, getObjectTorrent, getPublicAccessBlock, headBucket, headObject, invokeOperation, listBucketAnalyticsConfigurations, listBucketIntelligentTieringConfigurations, listBucketInventoryConfigurations, listBucketMetricsConfigurations, listBuckets, listDirectoryBuckets, listMultipartUploads, listObjects, listObjectsV2, listObjectVersions, listParts, putBucketAccelerateConfiguration, putBucketAcl, putBucketAnalyticsConfiguration, putBucketCors, putBucketEncryption, putBucketIntelligentTieringConfiguration, putBucketInventoryConfiguration, putBucketLifecycleConfiguration, putBucketLogging, putBucketMetricsConfiguration, putBucketNotificationConfiguration, putBucketOwnershipControls, putBucketPolicy, putBucketReplication, putBucketRequestPayment, putBucketTagging, putBucketVersioning, putBucketWebsite, putObjectAcl, putObjectLegalHold, putObjectLockConfiguration, putObjectRetention, putObjectTagging, putPublicAccessBlock, restoreObject, serviceClientConfiguration, serviceName, uploadPartCopy, utilities, waiter, writeGetObjectResponse

      • Methods inherited from interface software.amazon.awssdk.services.s3.S3Client

        abortMultipartUpload, completeMultipartUpload, copyObject, createBucket, createBucketMetadataTableConfiguration, createMultipartUpload, createSession, deleteBucket, deleteBucketAnalyticsConfiguration, deleteBucketCors, deleteBucketEncryption, deleteBucketIntelligentTieringConfiguration, deleteBucketInventoryConfiguration, deleteBucketLifecycle, deleteBucketMetadataTableConfiguration, deleteBucketMetricsConfiguration, deleteBucketOwnershipControls, deleteBucketPolicy, deleteBucketReplication, deleteBucketTagging, deleteBucketWebsite, deleteObject, deleteObjects, deleteObjectTagging, deletePublicAccessBlock, getBucketAccelerateConfiguration, getBucketAcl, getBucketAnalyticsConfiguration, getBucketCors, getBucketEncryption, getBucketIntelligentTieringConfiguration, getBucketInventoryConfiguration, getBucketLifecycleConfiguration, getBucketLocation, getBucketLogging, getBucketMetadataTableConfiguration, getBucketMetricsConfiguration, getBucketNotificationConfiguration, getBucketOwnershipControls, getBucketPolicy, getBucketPolicyStatus, getBucketReplication, getBucketRequestPayment, getBucketTagging, getBucketVersioning, getBucketWebsite, getObject, getObject, getObject, getObject, getObject, getObjectAcl, getObjectAsBytes, getObjectAsBytes, getObjectAttributes, getObjectLegalHold, getObjectLockConfiguration, getObjectRetention, getObjectTagging, getObjectTorrent, getObjectTorrent, getObjectTorrent, getObjectTorrent, getObjectTorrent, getObjectTorrentAsBytes, getObjectTorrentAsBytes, getPublicAccessBlock, headBucket, headObject, listBucketAnalyticsConfigurations, listBucketIntelligentTieringConfigurations, listBucketInventoryConfigurations, listBucketMetricsConfigurations, listBuckets, listBuckets, listBucketsPaginator, listBucketsPaginator, listBucketsPaginator, listDirectoryBuckets, listDirectoryBucketsPaginator, listDirectoryBucketsPaginator, listMultipartUploads, listMultipartUploadsPaginator, listMultipartUploadsPaginator, listObjects, listObjectsV2, listObjectsV2Paginator, listObjectsV2Paginator, listObjectVersions, listObjectVersionsPaginator, listObjectVersionsPaginator, listParts, listPartsPaginator, listPartsPaginator, putBucketAccelerateConfiguration, putBucketAcl, putBucketAnalyticsConfiguration, putBucketCors, putBucketEncryption, putBucketIntelligentTieringConfiguration, putBucketInventoryConfiguration, putBucketLifecycleConfiguration, putBucketLogging, putBucketMetricsConfiguration, putBucketNotificationConfiguration, putBucketOwnershipControls, putBucketPolicy, putBucketReplication, putBucketRequestPayment, putBucketTagging, putBucketVersioning, putBucketWebsite, putObject, putObject, putObject, putObjectAcl, putObjectLegalHold, putObjectLockConfiguration, putObjectRetention, putObjectTagging, putPublicAccessBlock, restoreObject, uploadPart, uploadPart, uploadPart, uploadPartCopy, writeGetObjectResponse, writeGetObjectResponse, writeGetObjectResponse

    • Field Detail

      • ENCRYPTION_CONTEXT

        public static final software.amazon.awssdk.core.interceptor.ExecutionAttribute<Map<String,​String>> ENCRYPTION_CONTEXT

      • CONFIGURATION

        public static final software.amazon.awssdk.core.interceptor.ExecutionAttribute<MultipartConfiguration> CONFIGURATION

      • CUSTOM_INSTRUCTION_FILE_SUFFIX

        public static final software.amazon.awssdk.core.interceptor.ExecutionAttribute<String> CUSTOM_INSTRUCTION_FILE_SUFFIX

    • Method Detail

      • withAdditionalConfiguration

        public static Consumer<software.amazon.awssdk.awscore.AwsRequestOverrideConfiguration.Builder> withAdditionalConfiguration​(Map<String,​String> encryptionContext)
        Attaches encryption context to a request. Must be used as a parameter to AwsRequest.overrideConfiguration() in the request. Encryption context can be used to enforce authentication of ciphertext. The same encryption context used to encrypt MUST be provided on decrypt. Encryption context is only supported with KMS keys.
        Parameters:
        encryptionContext - the encryption context to use for the request.
        Returns:
        Consumer for use in overrideConfiguration()

      • withCustomInstructionFileSuffix

        public static Consumer<software.amazon.awssdk.awscore.AwsRequestOverrideConfiguration.Builder> withCustomInstructionFileSuffix​(String customInstructionFileSuffix)
        Attaches a custom instruction file suffix to a request. Must be used as a parameter to AwsRequest.overrideConfiguration() in the request. This allows specifying a custom suffix for the instruction file on a per-request basis.
        Parameters:
        customInstructionFileSuffix - the custom suffix to use for the instruction file.
        Returns:
        Consumer for use in overrideConfiguration()

      • withAdditionalConfiguration

        public static Consumer<software.amazon.awssdk.awscore.AwsRequestOverrideConfiguration.Builder> withAdditionalConfiguration​(MultipartConfiguration multipartConfiguration)
        Attaches multipart configuration to a request. Must be used as a parameter to AwsRequest.overrideConfiguration() in the request.
        Parameters:
        multipartConfiguration - the MultipartConfiguration instance to use
        Returns:
        Consumer for use in overrideConfiguration()

      • withAdditionalConfiguration

        public static Consumer<software.amazon.awssdk.awscore.AwsRequestOverrideConfiguration.Builder> withAdditionalConfiguration​(Map<String,​String> encryptionContext,
                                                                                                                           MultipartConfiguration multipartConfiguration)
        Attaches encryption context and multipart configuration to a request. * Must be used as a parameter to AwsRequest.overrideConfiguration() in the request. Encryption context can be used to enforce authentication of ciphertext. The same encryption context used to encrypt MUST be provided on decrypt. Encryption context is only supported with KMS keys.
        Parameters:
        encryptionContext - the encryption context to use for the request.
        multipartConfiguration - the MultipartConfiguration instance to use
        Returns:
        Consumer for use in overrideConfiguration()

      • reEncryptInstructionFile

        public ReEncryptInstructionFileResponse reEncryptInstructionFile​(ReEncryptInstructionFileRequest reEncryptInstructionFileRequest)
        Re-encrypts an instruction file with a new keyring while preserving the original encrypted object in S3. This enables: 1. Key rotation by updating instruction file metadata without re-encrypting object content 2. Sharing encrypted objects with partners by creating new instruction files with a custom suffix using their public keys

        Key rotation scenarios: - Legacy to V3: Can rotate same wrapping key from legacy wrapping algorithms to fully supported wrapping algorithms - Within V3: When rotating the wrapping key, the new keyring must be different from the current keyring - Enforce Rotation: When enabled, ensures old keyring cannot decrypt data encrypted by new keyring

        Parameters:
        reEncryptInstructionFileRequest - the request containing bucket, object key, new keyring, and optional instruction file suffix
        Returns:
        ReEncryptInstructionFileResponse containing the bucket, object key, and instruction file suffix used
        Throws:
        S3EncryptionClientException - if the new keyring has the same materials description as the current one

      • putObject

        public software.amazon.awssdk.services.s3.model.PutObjectResponse putObject​(software.amazon.awssdk.services.s3.model.PutObjectRequest putObjectRequest,
                                                                            software.amazon.awssdk.core.sync.RequestBody requestBody)
                                                                     throws software.amazon.awssdk.awscore.exception.AwsServiceException,
                                                                            software.amazon.awssdk.core.exception.SdkClientException
        See putObject(PutObjectRequest, RequestBody).

        In the S3EncryptionClient, putObject encrypts the data in the requestBody as it is written to S3.

        Specified by:
        putObject in interface software.amazon.awssdk.services.s3.S3Client
        Overrides:
        putObject in class software.amazon.awssdk.services.s3.DelegatingS3Client
        Parameters:
        putObjectRequest - the request instance
        requestBody - The content to send to the service. A RequestBody can be created using one of several factory methods for various sources of data. For example, to create a request body from a file you can do the following.
        Returns:
        Result of the PutObject operation returned by the service.
        Throws:
        software.amazon.awssdk.core.exception.SdkClientException - If any client side error occurs such as an IO related failure, failure to get credentials, etc.
        S3EncryptionClientException - Base class for all encryption client exceptions.
        software.amazon.awssdk.awscore.exception.AwsServiceException

      • getObject

        public <T> T getObject​(software.amazon.awssdk.services.s3.model.GetObjectRequest getObjectRequest,
                       software.amazon.awssdk.core.sync.ResponseTransformer<software.amazon.awssdk.services.s3.model.GetObjectResponse,​T> responseTransformer)
                throws software.amazon.awssdk.awscore.exception.AwsServiceException,
                       software.amazon.awssdk.core.exception.SdkClientException
        See getObject(GetObjectRequest, ResponseTransformer)

        In the S3EncryptionClient, getObject decrypts the data as it is read from S3.

        Specified by:
        getObject in interface software.amazon.awssdk.services.s3.S3Client
        Overrides:
        getObject in class software.amazon.awssdk.services.s3.DelegatingS3Client
        Parameters:
        getObjectRequest - the request instance
        responseTransformer - Functional interface for processing the streamed response content. The unmarshalled GetObjectResponse and an InputStream to the response content are provided as parameters to the callback. The callback may return a transformed type which will be the return value of this method. See ResponseTransformer for details on implementing this interface and for links to pre-canned implementations for common scenarios like downloading to a file.
        Returns:
        The transformed result of the ResponseTransformer.
        Throws:
        software.amazon.awssdk.core.exception.SdkClientException - If any client side error occurs such as an IO related failure, failure to get credentials, etc.
        S3EncryptionClientException - Base class for all encryption client exceptions.
        software.amazon.awssdk.awscore.exception.AwsServiceException

      • deleteObject

        public software.amazon.awssdk.services.s3.model.DeleteObjectResponse deleteObject​(software.amazon.awssdk.services.s3.model.DeleteObjectRequest deleteObjectRequest)
                                                                           throws software.amazon.awssdk.awscore.exception.AwsServiceException,
                                                                                  software.amazon.awssdk.core.exception.SdkClientException
        See S3Client.deleteObject(DeleteObjectRequest).

        In the S3 Encryption Client, deleteObject also deletes the instruction file, if present.

        Specified by:
        deleteObject in interface software.amazon.awssdk.services.s3.S3Client
        Overrides:
        deleteObject in class software.amazon.awssdk.services.s3.DelegatingS3Client
        Parameters:
        deleteObjectRequest - the request instance
        Returns:
        Result of the DeleteObject operation returned by the service.
        Throws:
        software.amazon.awssdk.awscore.exception.AwsServiceException
        software.amazon.awssdk.core.exception.SdkClientException

      • deleteObjects

        public software.amazon.awssdk.services.s3.model.DeleteObjectsResponse deleteObjects​(software.amazon.awssdk.services.s3.model.DeleteObjectsRequest deleteObjectsRequest)
                                                                             throws software.amazon.awssdk.awscore.exception.AwsServiceException,
                                                                                    software.amazon.awssdk.core.exception.SdkClientException
        See S3Client.deleteObjects(DeleteObjectsRequest).

        In the S3 Encryption Client, deleteObjects also deletes the instruction file(s), if present.

        Specified by:
        deleteObjects in interface software.amazon.awssdk.services.s3.S3Client
        Overrides:
        deleteObjects in class software.amazon.awssdk.services.s3.DelegatingS3Client
        Parameters:
        deleteObjectsRequest - the request instance
        Returns:
        Result of the DeleteObjects operation returned by the service.
        Throws:
        software.amazon.awssdk.awscore.exception.AwsServiceException
        software.amazon.awssdk.core.exception.SdkClientException

      • createMultipartUpload

        public software.amazon.awssdk.services.s3.model.CreateMultipartUploadResponse createMultipartUpload​(software.amazon.awssdk.services.s3.model.CreateMultipartUploadRequest request)
        See S3Client.createMultipartUpload(CreateMultipartUploadRequest)

        In the S3EncryptionClient, createMultipartUpload creates an encrypted multipart upload. Parts MUST be uploaded sequentially. See uploadPart(UploadPartRequest, RequestBody) for details.

        Specified by:
        createMultipartUpload in interface software.amazon.awssdk.services.s3.S3Client
        Overrides:
        createMultipartUpload in class software.amazon.awssdk.services.s3.DelegatingS3Client
        Parameters:
        request - the request instance
        Returns:
        Result of the CreateMultipartUpload operation returned by the service.

      • uploadPart

        public software.amazon.awssdk.services.s3.model.UploadPartResponse uploadPart​(software.amazon.awssdk.services.s3.model.UploadPartRequest request,
                                                                              software.amazon.awssdk.core.sync.RequestBody requestBody)
                                                                       throws software.amazon.awssdk.awscore.exception.AwsServiceException,
                                                                              software.amazon.awssdk.core.exception.SdkClientException
        See S3Client.uploadPart(UploadPartRequest, RequestBody) NOTE: Because the encryption process requires context from block N-1 in order to encrypt block N, parts uploaded with the S3EncryptionClient (as opposed to the normal S3Client) must be uploaded serially, and in order. Otherwise, the previous encryption context isn't available to use when encrypting the current part.
        Specified by:
        uploadPart in interface software.amazon.awssdk.services.s3.S3Client
        Overrides:
        uploadPart in class software.amazon.awssdk.services.s3.DelegatingS3Client
        Parameters:
        request - the request instance
        Returns:
        Result of the UploadPart operation returned by the service.
        Throws:
        software.amazon.awssdk.awscore.exception.AwsServiceException
        software.amazon.awssdk.core.exception.SdkClientException

      • completeMultipartUpload

        public software.amazon.awssdk.services.s3.model.CompleteMultipartUploadResponse completeMultipartUpload​(software.amazon.awssdk.services.s3.model.CompleteMultipartUploadRequest request)
                                                                                                 throws software.amazon.awssdk.awscore.exception.AwsServiceException,
                                                                                                        software.amazon.awssdk.core.exception.SdkClientException
        See S3Client.completeMultipartUpload(CompleteMultipartUploadRequest)
        Specified by:
        completeMultipartUpload in interface software.amazon.awssdk.services.s3.S3Client
        Overrides:
        completeMultipartUpload in class software.amazon.awssdk.services.s3.DelegatingS3Client
        Parameters:
        request - the request instance
        Returns:
        Result of the CompleteMultipartUpload operation returned by the service.
        Throws:
        software.amazon.awssdk.awscore.exception.AwsServiceException
        software.amazon.awssdk.core.exception.SdkClientException

      • abortMultipartUpload

        public software.amazon.awssdk.services.s3.model.AbortMultipartUploadResponse abortMultipartUpload​(software.amazon.awssdk.services.s3.model.AbortMultipartUploadRequest request)
                                                                                           throws software.amazon.awssdk.awscore.exception.AwsServiceException,
                                                                                                  software.amazon.awssdk.core.exception.SdkClientException
        See S3Client.abortMultipartUpload(AbortMultipartUploadRequest)
        Specified by:
        abortMultipartUpload in interface software.amazon.awssdk.services.s3.S3Client
        Overrides:
        abortMultipartUpload in class software.amazon.awssdk.services.s3.DelegatingS3Client
        Parameters:
        request - the request instance
        Returns:
        Result of the AbortMultipartUpload operation returned by the service.
        Throws:
        software.amazon.awssdk.awscore.exception.AwsServiceException
        software.amazon.awssdk.core.exception.SdkClientException

      • close

        public void close()
        Closes the wrapped clients.
        Specified by:
        close in interface AutoCloseable
        Specified by:
        close in interface software.amazon.awssdk.utils.SdkAutoCloseable
        Overrides:
        close in class software.amazon.awssdk.services.s3.DelegatingS3Client