com.ibm.cloud.objectstorage.services.s3

Interface AmazonS3EncryptionV2

All Superinterfaces:

AmazonS3, S3DirectSpi

public interface AmazonS3EncryptionV2
extends AmazonS3

Interface for an S3 client that performs encryption, V2. This interface provides some extra methods specific for encryption.

Field Summary

Fields inherited from interface com.ibm.cloud.objectstorage.services.s3.AmazonS3

ENDPOINT_PREFIX

Method Summary

Modifier and Type	Method and Description
PutObjectResult	putInstructionFile(PutInstructionFileRequest req) Creates a new crypto instruction file by re-encrypting the CEK of an existing encrypted S3 object with a new encryption material identifiable via a new set of material description.
CompleteMultipartUploadResult	uploadObject(UploadObjectRequest req) Used to encrypt data first to disk with pipelined concurrent multi-part uploads to S3.

Methods inherited from interface com.ibm.cloud.objectstorage.services.s3.AmazonS3

abortMultipartUpload, addLegalHold, addLegalHold, changeObjectStorageClass, completeMultipartUpload, copyObject, copyObject, copyPart, createBucket, createBucket, createBucket, createBucket, deleteBucket, deleteBucket, deleteBucketCrossOriginConfiguration, deleteBucketCrossOriginConfiguration, deleteBucketLifecycleConfiguration, deleteBucketLifecycleConfiguration, deleteBucketReplicationConfiguration, deleteBucketReplicationConfiguration, deleteBucketWebsiteConfiguration, deleteBucketWebsiteConfiguration, deleteLegalHold, deleteLegalHold, deleteObject, deleteObject, deleteObjects, deleteObjectTagging, deletePublicAccessBlock, deleteVersion, deleteVersion, doesBucketExist, doesBucketExistV2, doesObjectExist, download, download, extendObjectRetention, extendObjectRetention, generatePresignedUrl, generatePresignedUrl, generatePresignedUrl, getBucketAcl, getBucketAcl, getBucketCrossOriginConfiguration, getBucketCrossOriginConfiguration, getBucketFaspConnectionInfo, getBucketFaspConnectionInfo, getBucketLifecycleConfiguration, getBucketLifecycleConfiguration, getBucketProtection, getBucketProtectionConfiguration, getBucketReplicationConfiguration, getBucketReplicationConfiguration, getBucketVersioningConfiguration, getBucketVersioningConfiguration, getBucketWebsiteConfiguration, getBucketWebsiteConfiguration, getCachedResponseMetadata, getObject, getObject, getObject, getObjectAcl, getObjectAcl, getObjectAcl, getObjectAsString, getObjectLegalHold, getObjectLockConfiguration, getObjectMetadata, getObjectMetadata, getObjectRetention, getObjectTagging, getPublicAccessBlock, getRegion, getRegionName, getS3AccountOwner, getS3AccountOwner, getUrl, headBucket, initiateMultipartUpload, listBuckets, listBuckets, listBucketsExtended, listBucketsExtended, listLegalHolds, listLegalHolds, listMultipartUploads, listNextBatchOfObjects, listNextBatchOfObjects, listNextBatchOfVersions, listNextBatchOfVersions, listObjects, listObjects, listObjects, listObjectsV2, listObjectsV2, listObjectsV2, listParts, listVersions, listVersions, listVersions, putObject, putObject, putObject, putObject, restoreObject, restoreObject, setBucketAcl, setBucketAcl, setBucketAcl, setBucketCrossOriginConfiguration, setBucketCrossOriginConfiguration, setBucketLifecycleConfiguration, setBucketLifecycleConfiguration, setBucketProtection, setBucketProtectionConfiguration, setBucketReplicationConfiguration, setBucketReplicationConfiguration, setBucketVersioningConfiguration, setBucketWebsiteConfiguration, setBucketWebsiteConfiguration, setEndpoint, setObjectAcl, setObjectAcl, setObjectAcl, setObjectAcl, setObjectAcl, setObjectLegalHold, setObjectLockConfiguration, setObjectRedirectLocation, setObjectRetention, setObjectTagging, setPublicAccessBlock, setRegion, setS3ClientOptions, shutdown, upload, uploadPart, waiters

Method Detail

putInstructionFile

PutObjectResult putInstructionFile(PutInstructionFileRequest req)

Creates a new crypto instruction file by re-encrypting the CEK of an existing encrypted S3 object with a new encryption material identifiable via a new set of material description.

User of this method is responsible for explicitly deleting/updating the instruction file so created should the corresponding S3 object is deleted/created.

Returns:

the result of the put (instruction file) operation.

uploadObject

CompleteMultipartUploadResult uploadObject(UploadObjectRequest req)
                                    throws IOException,
                                           InterruptedException,
                                           ExecutionException

Used to encrypt data first to disk with pipelined concurrent multi-part uploads to S3. This method enables significant speed-up of encrypting and uploading large payloads to Amazon S3 via pipelining and parallel uploads by consuming temporary disk space.

There are many ways you can customize the behavior of this method, including

• the configuration of your own custom thread pool
• the part size of each multi-part upload request; By default, a temporary ciphertext file is generated per part and gets uploaded immediately to S3
• the maximum temporary disk space that must not be exceeded by execution of this request; By default, the encryption will block upon hitting the limit and will only resume when the in-flight uploads catch up by releasing the temporary disk space upon successful uploads of the completed parts
• the configuration of your own MultiFileOutputStream for custom pipeline behavior
• the configuration of your own UploadObjectObserver for custom multi-part upload behavior

A request is handled with the following life cycle, calling the necessary Service Provider Interface:

1. A thread pool is constructed (or retrieved from the request) for the execution of concurrent upload tasks to be submitted by the UploadObjectObserver
2. An UploadObjectObserver is constructed (or retrieved from the request) for execution of concurrent uploads to S3
3. Initialize the UploadObjectObserver
4. Initialize a multi-part upload request to S3 by calling UploadObjectObserver.onUploadInitiation(UploadObjectRequest)
5. A MultiFileOutputStream is constructed (or retrieved from the request) which serves as the pipeline for incremental (but serial) encryption to disk with concurrent multipart uploads to S3 whenever the parts on the disk are ready
6. Initialize the MultiFileOutputStream
7. Kicks off the pipeline for incremental encryption to disk with pipelined concurrent multi-part uploads to S3
8. For every part encrypted into a temporary file on disk, it is uploaded by calling UploadObjectObserver.onPartCreate(PartCreationEvent)
9. Finally, clean up and complete the multi-part upload by calling UploadObjectObserver.onCompletion(List).

Returns:

the result of the completed muti-part uploads

Throws:

IOException - if the encryption to disk failed

InterruptedException - if the current thread was interrupted while waiting

ExecutionException - if the concurrent uploads threw an exception