/*
* Copyright 2014-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License").
* You may not use this file except in compliance with the License.
* A copy of the License is located at
*
* http://aws.amazon.com/apache2.0
*
* or in the "license" file accompanying this file. 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.
*/
package com.amazonaws.services.s3.model;
import java.io.Serializable;
import static com.amazonaws.services.s3.model.ExtraMaterialsDescription.NONE;
import java.util.Map;
import com.amazonaws.services.s3.AmazonS3Client;
import com.amazonaws.services.s3.AmazonS3EncryptionClient;
import com.amazonaws.services.s3.KeyWrapException;
/**
* <p>
* An extension of {@link GetObjectRequest} to allow additional encryption
* material description to be specified on a per-request basis. In particular,
* {@link EncryptedGetObjectRequest} is only recognized by
* {@link AmazonS3EncryptionClient}.
* </p>
* <p>
* If {@link EncryptedGetObjectRequest} is used against the non-encrypting
* {@link AmazonS3Client}, the additional attributes will be ignored.
* </p>
* <p>
* 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.
*/
public class EncryptedGetObjectRequest extends GetObjectRequest implements Serializable {
/**
* Request specific additional material description; never null.
*/
private ExtraMaterialsDescription supplemental = NONE;
/**
* Used to retrieve the S3 encrypted object via instruction file with
* an explicit suffix. Applicable only if specified (which means non-null
* and non-blank.)
*/
private String instructionFileSuffix;
/**
* True if the retrieval of the encrypted object expects the CEK to have
* been key-wrapped; Default is false.
* <p>
* Note, however, that if {@link CryptoMode#StrictAuthenticatedEncryption}
* is in use, key wrapping is always expected for the CEK regardless.
*/
private boolean keyWrapExpected;
public EncryptedGetObjectRequest(String bucketName, String key) {
this(bucketName, key, null);
}
public EncryptedGetObjectRequest(String bucketName, String key,
String versionId) {
super(bucketName, key, versionId);
setKey(key);
setVersionId(versionId);
}
public EncryptedGetObjectRequest(S3ObjectId s3ObjectId) {
super(s3ObjectId);
}
public EncryptedGetObjectRequest(String bucketName, String key,
boolean isRequesterPays) {
super(bucketName, key, isRequesterPays);
}
/**
* Returns the supplemental material description to be used for retrieving
* the encryption materials.
*
* @return the supplemental material description; never null.
*/
public ExtraMaterialsDescription getExtraMaterialDescription() {
return supplemental;
}
/**
* Sets the supplemental materials description for the encryption materials
* to be used with the current request.
*
* @param 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
*/
public void setExtraMaterialDescription(
ExtraMaterialsDescription supplemental) {
this.supplemental = supplemental == null
? NONE : supplemental;
}
/**
* Sets the supplemental materials description for the encryption materials
* to be used with the current request.
*
* @param 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
*/
public EncryptedGetObjectRequest withExtraMaterialsDescription(
ExtraMaterialsDescription supplemental) {
setExtraMaterialDescription(supplemental);
return this;
}
/**
* Fluent API to set the supplemental materials description for the
* encryption materials to be used with the current request.
*
* @param 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
*/
public EncryptedGetObjectRequest withExtraMaterialsDescription(
Map<String, String> supplemental) {
setExtraMaterialDescription(supplemental == null ? null
: new ExtraMaterialsDescription(supplemental));
return this;
}
public String getInstructionFileSuffix() {
return 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).
*
* @param instructionFileSuffix
* suffix of the instruction file to be used.
*
* @see AmazonS3EncryptionClient#putInstructionFile(PutInstructionFileRequest)
*/
public void setInstructionFileSuffix(String instructionFileSuffix) {
this.instructionFileSuffix = 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).
*
* @param instructionFileSuffix
* suffix of the instruction file to be used.
*
* @see AmazonS3EncryptionClient#putInstructionFile(PutInstructionFileRequest)
*/
public EncryptedGetObjectRequest withInstructionFileSuffix(
String instructionFileSuffix) {
this.instructionFileSuffix = instructionFileSuffix;
return this;
}
/**
* Returns true if key wrapping is expected; false otherwise. Note, however,
* that if {@link CryptoMode#StrictAuthenticatedEncryption} or KMS is in
* use, key wrapping is always expected for the CEK regardless.
*/
public boolean isKeyWrapExpected() {
return keyWrapExpected;
}
/**
* @param keyWrapExpected
* true if key wrapping is expected for the CEK; false otherwse.
* Note, however, that if
* {@link CryptoMode#StrictAuthenticatedEncryption} or KMS is in
* use, key wrapping is always expected for the CEK regardless.
* <p>
* If keyWrapExpected is set to true but the CEK is found to be
* not key-wrapped, it would cause a {@link KeyWrapException} to
* be thrown.
*/
public void setKeyWrapExpected(boolean keyWrapExpected) {
this.keyWrapExpected = keyWrapExpected;
}
/**
* Fluent API for {@link #setKeyWrapExpected(boolean)}.
*/
public EncryptedGetObjectRequest withKeyWrapExpected(boolean keyWrapExpected) {
this.keyWrapExpected = keyWrapExpected;
return this;
}
}