com.ibm.cloud.objectstorage.services.s3.model

Class EncryptedGetObjectRequest

java.lang.Object

com.ibm.cloud.objectstorage.AmazonWebServiceRequest

com.ibm.cloud.objectstorage.services.s3.model.GetObjectRequest

com.ibm.cloud.objectstorage.services.s3.model.EncryptedGetObjectRequest

All Implemented Interfaces:

HandlerContextAware, ReadLimitInfo, SSECustomerKeyProvider, WormMirrorDestinationProvider, Serializable, Cloneable

public class EncryptedGetObjectRequest
extends GetObjectRequest
implements Serializable

An extension of GetObjectRequest to allow additional encryption material description to be specified on a per-request basis. In particular, EncryptedGetObjectRequest is only recognized by AmazonS3EncryptionClient.

If EncryptedGetObjectRequest is used against the non-encrypting AmazonS3Client, the additional attributes will be ignored.

The additional material description must not conflict with the existing one saved in S3 or else will cause the get request to fail fast later on.

See Also:

Serialized Form

Field Summary

Fields inherited from class com.ibm.cloud.objectstorage.AmazonWebServiceRequest

NOOP

Constructor Summary

Constructors

Constructor and Description
EncryptedGetObjectRequest(S3ObjectId s3ObjectId)
EncryptedGetObjectRequest(String bucketName, String key)
EncryptedGetObjectRequest(String bucketName, String key, boolean isRequesterPays)
EncryptedGetObjectRequest(String bucketName, String key, String versionId)

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object o)
ExtraMaterialsDescription	getExtraMaterialDescription() Returns the supplemental material description to be used for retrieving the encryption materials.
String	getInstructionFileSuffix()
Integer	getPartNumber() Deprecated.
long[]	getRange() Deprecated.
int	hashCode()
boolean	isKeyWrapExpected() Returns true if key wrapping is expected; false otherwise.
void	setExtraMaterialDescription(ExtraMaterialsDescription supplemental) Sets the supplemental materials description for the encryption materials to be used with the current request.
void	setInstructionFileSuffix(String instructionFileSuffix) Explicitly sets the suffix of an instruction file to be used to retrieve the S3 encrypted object.
void	setKeyWrapExpected(boolean keyWrapExpected)
void	setPartNumber(Integer partNumber) Deprecated.
void	setRange(long start) Deprecated.
void	setRange(long start, long end) Deprecated.
EncryptedGetObjectRequest	withExtraMaterialsDescription(ExtraMaterialsDescription supplemental) Sets the supplemental materials description for the encryption materials to be used with the current request.
EncryptedGetObjectRequest	withExtraMaterialsDescription(Map<String,String> supplemental) Fluent API to set the supplemental materials description for the encryption materials to be used with the current request.
EncryptedGetObjectRequest	withInstructionFileSuffix(String instructionFileSuffix) Fluent API to explicitly sets the suffix of an instruction file to be used to retrieve the S3 encrypted object.
EncryptedGetObjectRequest	withKeyWrapExpected(boolean keyWrapExpected) Fluent API for EncryptedGetObjectRequest.setKeyWrapExpected(boolean).
EncryptedGetObjectRequest	withPartNumber(Integer partNumber) Deprecated.
EncryptedGetObjectRequest	withRange(long start) Deprecated.
EncryptedGetObjectRequest	withRange(long start, long end) Deprecated.

Methods inherited from class com.ibm.cloud.objectstorage.services.s3.model.GetObjectRequest

getBucketName, getKey, getMatchingETagConstraints, getModifiedSinceConstraint, getNonmatchingETagConstraints, getProgressListener, getResponseHeaders, getS3ObjectId, getSSECustomerKey, getUnmodifiedSinceConstraint, getVersionId, getWormMirrorDestination, isRequesterPays, setBucketName, setKey, setMatchingETagConstraints, setModifiedSinceConstraint, setNonmatchingETagConstraints, setProgressListener, setRequesterPays, setResponseHeaders, setS3ObjectId, setSSECustomerKey, setUnmodifiedSinceConstraint, setVersionId, setWormMirrorDestination, withBucketName, withKey, withMatchingETagConstraint, withModifiedSinceConstraint, withNonmatchingETagConstraint, withProgressListener, withRequesterPays, withResponseHeaders, withS3ObjectId, withSSECustomerKey, withUnmodifiedSinceConstraint, withVersionId, withWormMirrorDestination

Methods inherited from class com.ibm.cloud.objectstorage.AmazonWebServiceRequest

addHandlerContext, clone, copyBaseTo, getCloneRoot, getCloneSource, getCustomQueryParameters, getCustomRequestHeaders, getGeneralProgressListener, getHandlerContext, getReadLimit, getRequestClientOptions, getRequestCredentials, getRequestCredentialsProvider, getRequestMetricCollector, getSdkClientExecutionTimeout, getSdkRequestTimeout, putCustomQueryParameter, putCustomRequestHeader, setGeneralProgressListener, setRequestCredentials, setRequestCredentialsProvider, setRequestMetricCollector, setSdkClientExecutionTimeout, setSdkRequestTimeout, withGeneralProgressListener, withRequestCredentialsProvider, withRequestMetricCollector, withSdkClientExecutionTimeout, withSdkRequestTimeout

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EncryptedGetObjectRequest

public EncryptedGetObjectRequest(String bucketName,
                                 String key)

EncryptedGetObjectRequest

public EncryptedGetObjectRequest(String bucketName,
                                 String key,
                                 String versionId)

EncryptedGetObjectRequest

public EncryptedGetObjectRequest(S3ObjectId s3ObjectId)

EncryptedGetObjectRequest

public EncryptedGetObjectRequest(String bucketName,
                                 String key,
                                 boolean isRequesterPays)

Method Detail

withRange

@Deprecated
public EncryptedGetObjectRequest withRange(long start,
                                                       long end)

Deprecated.

Sets the optional inclusive byte range within the desired object that will be downloaded by this request. Returns this GetObjectRequest, enabling additional method calls to be chained together.

The first byte in an object has position 0; as an example, the first ten bytes of an object can be downloaded by specifying a range of 0 to 9.

If no byte range is specified, this request downloads the entire object from Amazon S3.

Range gets do not provide authenticated encryption properties even when used with an authenticated mode (AES-GCM).

Overrides:

withRange in class GetObjectRequest

Parameters:

start - The start of the inclusive byte range to download.

end - The end of the inclusive byte range to download.

Returns:

This GetObjectRequest, enabling additional method calls to be chained together.

See Also:

GetObjectRequest.getRange(), GetObjectRequest.setRange(long, long)

setRange

@Deprecated
public void setRange(long start,
                                 long end)

Deprecated.

Sets the optional inclusive byte range within the desired object that will be downloaded by this request.

The first byte in an object has position 0; as an example, the first ten bytes of an object can be downloaded by specifying a range of 0 to 9.

If no byte range is specified, this request downloads the entire object from Amazon S3.

Range gets do not provide authenticated encryption properties even when used with an authenticated mode (AES-GCM).

Overrides:

setRange in class GetObjectRequest

Parameters:

start - The start of the inclusive byte range to download.

end - The end of the inclusive byte range to download.

See Also:

GetObjectRequest.getRange(), GetObjectRequest.withRange(long, long)

withRange

@Deprecated
public EncryptedGetObjectRequest withRange(long start)

Deprecated.

Sets the optional inclusive start range within the desired object that the rest of which will be downloaded by this request.

Returns this GetObjectRequest, enabling additional method calls to be chained together.

The first byte in an object has position 0; as an example, the object is of 10 bytes in length, the last 4 bytes can be downloaded by specifying the start range as 6.

If no byte range is specified, this request downloads the entire object from Amazon S3.

Range gets do not provide authenticated encryption properties even when used with an authenticated mode (AES-GCM).

Overrides:

withRange in class GetObjectRequest

Parameters:

start - The start of the inclusive byte range to download.

Returns:

This GetObjectRequest, enabling additional method calls to be chained together.

See Also:

GetObjectRequest.withRange(long, long), GetObjectRequest.setRange(long)

setRange

@Deprecated
public void setRange(long start)

Deprecated.

Sets the optional inclusive start range within the desired object that the rest of which will be downloaded by this request.

The first byte in an object has position 0; as an example, the object is of 10 bytes in length, the last 4 bytes can be downloaded by specifying the start range as 6.

If no byte range is specified, this request downloads the entire object from Amazon S3.

Range gets do not provide authenticated encryption properties even when used with an authenticated mode (AES-GCM).

Overrides:

setRange in class GetObjectRequest

Parameters:

start - The start of the inclusive byte range to download.

See Also:

GetObjectRequest.setRange(long, long), GetObjectRequest.withRange(long)

getRange

@Deprecated
public long[] getRange()

Deprecated.

Gets the optional inclusive byte range within the desired object that will be downloaded by this request.

The range is returned as a two element array, containing the start and end index of the byte range. If no byte range has been specified, the entire object is downloaded and this method returns null.

Range gets do not provide authenticated encryption properties even when used with an authenticated mode (AES-GCM).

Overrides:

getRange in class GetObjectRequest

Returns:

A two element array indicating the inclusive start index and end index within the object being downloaded by this request. Returns null if no range has been specified, and the whole object is to be downloaded.

See Also:

GetObjectRequest.setRange(long, long), GetObjectRequest.withRange(long, long)

withPartNumber

@Deprecated
public EncryptedGetObjectRequest withPartNumber(Integer partNumber)

Deprecated.

Sets the optional part number that indicates the part to be downloaded in a multipart object.

The valid range for part number is 1 - 10000 inclusive. Part numbers are 1 based. If an object has 1 part, partNumber=1 would be the correct not 0. For partNumber < 1, an AmazonS3Exception is thrown with response code 400 bad request. For partNumber larger than actual part count, an AmazonS3Exception is thrown with response code 416 Request Range Not Satisfiable.

Range gets do not provide authenticated encryption properties even when used with an authenticated mode (AES-GCM).

Overrides:

withPartNumber in class GetObjectRequest

Parameters:

partNumber - The part number representing a part in a multipart object.

Returns:

This GetObjectRequest, enabling additional method calls to be chained together.

See Also:

GetObjectRequest.getPartNumber(), GetObjectRequest.setPartNumber(Integer)

setPartNumber

@Deprecated
public void setPartNumber(Integer partNumber)

Deprecated.

Sets the optional part number that indicates the part to be downloaded in a multipart object.

The valid range for part number is 1 - 10000 inclusive. Part numbers are 1 based. If an object has 1 part, partNumber=1 would be the correct not 0. For partNumber < 1, an AmazonS3Exception is thrown with response code 400 bad request. For partNumber larger than actual part count, an AmazonS3Exception is thrown with response code 416 Request Range Not Satisfiable.

Range gets do not provide authenticated encryption properties even when used with an authenticated mode (AES-GCM).

Overrides:

setPartNumber in class GetObjectRequest

Parameters:

partNumber - The part number representing a part in a multipart object.

See Also:

GetObjectRequest.getPartNumber(), GetObjectRequest.withPartNumber(Integer)

getPartNumber

@Deprecated
public Integer getPartNumber()

Deprecated.

Returns the optional part number that indicates the part to be downloaded in a multipart object.

Range gets do not provide authenticated encryption properties even when used with an authenticated mode (AES-GCM).

Overrides:

getPartNumber in class GetObjectRequest

Returns:

The part number representing a part in a multipart object.

See Also:

GetObjectRequest.setPartNumber(Integer), GetObjectRequest.withPartNumber(Integer)

getExtraMaterialDescription

public ExtraMaterialsDescription getExtraMaterialDescription()

Returns the supplemental material description to be used for retrieving the encryption materials.

Returns:

the supplemental material description; never null.

setExtraMaterialDescription

public void setExtraMaterialDescription(ExtraMaterialsDescription supplemental)

Sets the supplemental materials description for the encryption materials to be used with the current request.

Parameters:

supplemental - the materialsDescription to set; must not conflict with the existing one saved in S3 or else will cause the get request to fail fast later on

withExtraMaterialsDescription

public EncryptedGetObjectRequest withExtraMaterialsDescription(ExtraMaterialsDescription supplemental)

Sets the supplemental materials description for the encryption materials to be used with the current request.

Parameters:

supplemental - the materialsDescription to set; must not conflict with the existing one saved in S3 or else will cause the get request to fail fast later on

withExtraMaterialsDescription

public EncryptedGetObjectRequest withExtraMaterialsDescription(Map<String,String> supplemental)

Fluent API to set the supplemental materials description for the encryption materials to be used with the current request.

Parameters:

supplemental - the materialsDescription to set; must not conflict with the existing one saved in S3 or else will cause the get request to fail fast later on

getInstructionFileSuffix

public String getInstructionFileSuffix()

setInstructionFileSuffix

public void setInstructionFileSuffix(String instructionFileSuffix)

Explicitly sets the suffix of an instruction file to be used to retrieve the S3 encrypted object. Typically this is for more advanced use cases where multiple crypto instruction files have been created for the same S3 object. Each instruction file contains the same CEK encrypted under a different KEK, the IV, and other meta information (aka material description).

Parameters:

instructionFileSuffix - suffix of the instruction file to be used.

See Also:

AmazonS3EncryptionClient.putInstructionFile(PutInstructionFileRequest)

withInstructionFileSuffix

public EncryptedGetObjectRequest withInstructionFileSuffix(String instructionFileSuffix)

Fluent API to explicitly sets the suffix of an instruction file to be used to retrieve the S3 encrypted object. Typically this is for more advanced use cases where multiple crypto instruction files have been created for the same S3 object. Each instruction file contains the same CEK encrypted under a different KEK, the IV, and other meta information (aka material description).

Parameters:

instructionFileSuffix - suffix of the instruction file to be used.

See Also:

AmazonS3EncryptionClient.putInstructionFile(PutInstructionFileRequest)

isKeyWrapExpected

public boolean isKeyWrapExpected()

Returns true if key wrapping is expected; false otherwise. Note, however, that if CryptoMode.StrictAuthenticatedEncryption or KMS is in use, key wrapping is always expected for the CEK regardless.

setKeyWrapExpected

public void setKeyWrapExpected(boolean keyWrapExpected)

Parameters:

keyWrapExpected - true if key wrapping is expected for the CEK; false otherwse. Note, however, that if CryptoMode.StrictAuthenticatedEncryption or KMS is in use, key wrapping is always expected for the CEK regardless.

If keyWrapExpected is set to true but the CEK is found to be not key-wrapped, it would cause a KeyWrapException to be thrown.

withKeyWrapExpected

public EncryptedGetObjectRequest withKeyWrapExpected(boolean keyWrapExpected)

Fluent API for EncryptedGetObjectRequest.setKeyWrapExpected(boolean).

equals

public boolean equals(Object o)

Overrides:

equals in class GetObjectRequest

hashCode

public int hashCode()

Overrides:

hashCode in class GetObjectRequest