com.amazonaws.services.s3.internal.crypto

Class EncryptionUtils

java.lang.Object

com.amazonaws.services.s3.internal.crypto.EncryptionUtils

public class EncryptionUtils
extends Object

The EncryptionUtils class encrypts and decrypts data stored in S3. It can be used to prepare requests for encryption before they are stored in S3 and to decrypt objects that are retrieved from S3.

Constructor Summary

Constructors

Constructor and Description
EncryptionUtils()

Method Summary

Modifier and Type	Method and Description
static S3Object	adjustOutputToDesiredRange(S3Object object, long[] range) Adjusts the retrieved S3Object so that the object contents contain only the range of bytes desired by the user.
static EncryptionInstruction	buildInstructionFromInstructionFile(S3Object instructionFile, EncryptionMaterials materials, Provider cryptoProvider) Deprecated.
static EncryptionInstruction	buildInstructionFromInstructionFile(S3Object instructionFile, EncryptionMaterialsProvider materialsProvider, Provider cryptoProvider) Builds an instruction object from the contents of an instruction file.
static EncryptionInstruction	buildInstructionFromObjectMetadata(S3Object object, EncryptionMaterials materials, Provider cryptoProvider) Deprecated.
static EncryptionInstruction	buildInstructionFromObjectMetadata(S3Object object, EncryptionMaterialsProvider materialsProvider, Provider cryptoProvider) Builds an instruction object from the object metadata.
static long	calculateCryptoContentLength(Cipher symmetricCipher, UploadPartRequest request)
static DeleteObjectRequest	createInstructionDeleteObjectRequest(DeleteObjectRequest request) Creates a delete request to delete an instruction file in S3.
static GetObjectRequest	createInstructionGetRequest(GetObjectRequest request) Creates a get request to retrieve an instruction file from S3.
static PutObjectRequest	createInstructionPutRequest(PutObjectRequest request, EncryptionInstruction instruction) Creates a put request to store the specified instruction object in S3.
static PutObjectRequest	createInstructionPutRequest(String bucketName, String key, EncryptionInstruction instruction)
static Cipher	createSymmetricCipher(SecretKey symmetricCryptoKey, int encryptMode, Provider cryptoProvider, byte[] initVector) Creates a symmetric cipher in the specified mode from the given symmetric key and IV.
static S3Object	decryptObjectUsingInstruction(S3Object object, EncryptionInstruction instruction) Returns an updated object where the object content input stream contains the decrypted contents.
static S3Object	decryptObjectUsingMetadata(S3Object object, EncryptionMaterials materials, Provider cryptoProvider) Deprecated. use buildInstructionFromObjectMetadata and decryptObjectUsingInstruction instead.
static PutObjectRequest	encryptRequestUsingInstruction(PutObjectRequest request, EncryptionInstruction instruction) Returns an updated request where the input stream contains the encrypted object contents.
static PutObjectRequest	encryptRequestUsingMetadata(PutObjectRequest request, EncryptionMaterials materials, Provider cryptoProvider) Deprecated. use generateInstruction, encryptRequestUsingInstruction, and updateMetadataWithEncryptionInfo instead
static EncryptionInstruction	generateInstruction(EncryptionMaterials materials, Provider cryptoProvider) Deprecated.
static EncryptionInstruction	generateInstruction(EncryptionMaterialsProvider materialsProvider, Provider cryptoProvider)
static SecretKey	generateOneTimeUseSymmetricKey() Generates a one-time use Symmetric Key on-the-fly for use in envelope encryption.
static long[]	getAdjustedCryptoRange(long[] range) Adjusts a user specified range to retrieve all of the cipher blocks (each of size 16 bytes) that contain the specified range.
static ByteRangeCapturingInputStream	getEncryptedInputStream(UploadPartRequest request, CipherFactory cipherFactory)
static byte[]	getEncryptedSymmetricKey(SecretKey toBeEncrypted, EncryptionMaterials materials, Provider cryptoProvider) Encrypts a symmetric key using the provided encryption materials and returns it in raw byte array form.
static boolean	isEncryptionInfoInInstructionFile(S3Object instructionFile) Returns true if the specified S3Object is an instruction file containing encryption info, false otherwise.
static boolean	isEncryptionInfoInMetadata(S3Object retrievedObject) Returns true if the specified S3Object contains encryption info in its metadata, false otherwise.
static ObjectMetadata	updateMetadataWithEncryptionInfo(InitiateMultipartUploadRequest request, byte[] keyBytesToStoreInMetadata, Cipher symmetricCipher, Map<String,String> materialsDescription)
static void	updateMetadataWithEncryptionInstruction(PutObjectRequest request, EncryptionInstruction instruction) Update the request's ObjectMetadata with the necessary information for decrypting the object

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EncryptionUtils

public EncryptionUtils()

Method Detail

encryptRequestUsingMetadata

@Deprecated
public static PutObjectRequest encryptRequestUsingMetadata(PutObjectRequest request,
                                                                       EncryptionMaterials materials,
                                                                       Provider cryptoProvider)

Deprecated. use generateInstruction, encryptRequestUsingInstruction, and updateMetadataWithEncryptionInfo instead

Returns an updated request where the metadata contains encryption information and the input stream contains the encrypted object contents. The specified encryption materials will be used to encrypt and decrypt data.

Parameters:

request - The request whose contents are to be encrypted.

materials - The encryption materials to be used to encrypt and decrypt data.

cryptoProvider - The crypto provider whose encryption implementation will be used to encrypt data

Returns:

The updated request where the metadata is set up for encryption and input stream contains the encrypted contents.

decryptObjectUsingMetadata

@Deprecated
public static S3Object decryptObjectUsingMetadata(S3Object object,
                                                              EncryptionMaterials materials,
                                                              Provider cryptoProvider)

Deprecated. use buildInstructionFromObjectMetadata and decryptObjectUsingInstruction instead.

Returns an updated object where the object content input stream contains the decrypted contents.

Parameters:

object - The object whose contents are to be decrypted.

materials - The encryption materials to be used to encrypt and decrypt data.

cryptoProvider - The crypto provider whose encryption implementation will be used to decrypt data

Returns:

The updated object where the object content input stream contains the decrypted contents.

generateInstruction

@Deprecated
public static EncryptionInstruction generateInstruction(EncryptionMaterials materials,
                                                                    Provider cryptoProvider)

Deprecated.

Generates an instruction that will be used to encrypt an object.

Parameters:

materials - The encryption materials to be used to encrypt and decrypt data.

cryptoProvider - The crypto provider whose encryption implementation will be used to encrypt and decrypt data.

Returns:

The instruction that will be used to encrypt an object.

generateInstruction

public static EncryptionInstruction generateInstruction(EncryptionMaterialsProvider materialsProvider,
                                                        Provider cryptoProvider)

buildInstructionFromInstructionFile

@Deprecated
public static EncryptionInstruction buildInstructionFromInstructionFile(S3Object instructionFile,
                                                                                    EncryptionMaterials materials,
                                                                                    Provider cryptoProvider)

Deprecated.

Builds an instruction object from the contents of an instruction file.

Parameters:

instructionFile - A non-null instruction file retrieved from S3 that contains encryption information

materials - The non-null encryption materials to be used to encrypt and decrypt data.

cryptoProvider - The crypto provider whose encryption implementation will be used to encrypt and decrypt data. Null is ok and uses the preferred provider from Security.getProviders().

Returns:

A non-null instruction object containing encryption information

buildInstructionFromInstructionFile

public static EncryptionInstruction buildInstructionFromInstructionFile(S3Object instructionFile,
                                                                        EncryptionMaterialsProvider materialsProvider,
                                                                        Provider cryptoProvider)

Builds an instruction object from the contents of an instruction file.

Parameters:

instructionFile - A non-null instruction file retrieved from S3 that contains encryption information

materialsProvider - The non-null encryption materials provider to be used to encrypt and decrypt data.

cryptoProvider - The crypto provider whose encryption implementation will be used to encrypt and decrypt data. Null is ok and uses the preferred provider from Security.getProviders().

Returns:

A non-null instruction object containing encryption information

buildInstructionFromObjectMetadata

@Deprecated
public static EncryptionInstruction buildInstructionFromObjectMetadata(S3Object object,
                                                                                   EncryptionMaterials materials,
                                                                                   Provider cryptoProvider)

Deprecated.

Builds an instruction object from the object metadata.

Parameters:

object - A non-null object that contains encryption information in its headers

materials - The non-null encryption materials to be used to encrypt and decrypt data.

cryptoProvider - The crypto provider whose encryption implementation will be used to encrypt and decrypt data. Null is ok and uses the preferred provider from Security.getProviders().

Returns:

A non-null instruction object containing encryption information

Throws:

AmazonClientException - if encryption information is missing in the metadata, or the encryption materials used to encrypt the object are not available via the materials Accessor

buildInstructionFromObjectMetadata

public static EncryptionInstruction buildInstructionFromObjectMetadata(S3Object object,
                                                                       EncryptionMaterialsProvider materialsProvider,
                                                                       Provider cryptoProvider)

Builds an instruction object from the object metadata.

Parameters:

object - A non-null object that contains encryption information in its headers

materialsProvider - The non-null encryption materials provider to be used to encrypt and decrypt data.

cryptoProvider - The crypto provider whose encryption implementation will be used to encrypt and decrypt data. Null is ok and uses the preferred provider from Security.getProviders().

Returns:

A non-null instruction object containing encryption information

Throws:

AmazonClientException - if encryption information is missing in the metadata, or the encryption materials used to encrypt the object are not available via the materials Accessor

encryptRequestUsingInstruction

public static PutObjectRequest encryptRequestUsingInstruction(PutObjectRequest request,
                                                              EncryptionInstruction instruction)

Returns an updated request where the input stream contains the encrypted object contents. The specified instruction will be used to encrypt data.

Parameters:

request - The request whose contents are to be encrypted.

instruction - The instruction that will be used to encrypt the object data.

Returns:

The updated request where the input stream contains the encrypted contents.

decryptObjectUsingInstruction

public static S3Object decryptObjectUsingInstruction(S3Object object,
                                                     EncryptionInstruction instruction)

Returns an updated object where the object content input stream contains the decrypted contents.

Parameters:

object - The object whose contents are to be decrypted.

instruction - The instruction that will be used to decrypt the object data.

Returns:

The updated object where the object content input stream contains the decrypted contents.

createInstructionPutRequest

public static PutObjectRequest createInstructionPutRequest(PutObjectRequest request,
                                                           EncryptionInstruction instruction)

Creates a put request to store the specified instruction object in S3.

Parameters:

request - The put request for the original object to be stored in S3.

instruction - The instruction object to be stored in S3.

Returns:

A put request to store the specified instruction object in S3.

createInstructionPutRequest

public static PutObjectRequest createInstructionPutRequest(String bucketName,
                                                           String key,
                                                           EncryptionInstruction instruction)

createInstructionGetRequest

public static GetObjectRequest createInstructionGetRequest(GetObjectRequest request)

Creates a get request to retrieve an instruction file from S3.

Parameters:

request - The get request for the original object to be retrieved from S3.

Returns:

A get request to retrieve an instruction file from S3.

createInstructionDeleteObjectRequest

public static DeleteObjectRequest createInstructionDeleteObjectRequest(DeleteObjectRequest request)

Creates a delete request to delete an instruction file in S3.

Parameters:

request - The delete request for the original object to be deleted from S3.

Returns:

A delete request to delete an instruction file in S3.

isEncryptionInfoInMetadata

public static boolean isEncryptionInfoInMetadata(S3Object retrievedObject)

Returns true if the specified S3Object contains encryption info in its metadata, false otherwise.

Parameters:

retrievedObject - An S3Object

Returns:

True if the specified S3Object contains encryption info in its metadata, false otherwise.

isEncryptionInfoInInstructionFile

public static boolean isEncryptionInfoInInstructionFile(S3Object instructionFile)

Returns true if the specified S3Object is an instruction file containing encryption info, false otherwise.

Parameters:

instructionFile - An S3Object that may potentially be an instruction file

Returns:

True if the specified S3Object is an instruction file containing encryption info, false otherwise.

getAdjustedCryptoRange

public static long[] getAdjustedCryptoRange(long[] range)

Adjusts a user specified range to retrieve all of the cipher blocks (each of size 16 bytes) that contain the specified range. For Chained Block Cipher decryption to function properly, we need to retrieve the cipher block that precedes the range, all of the cipher blocks that contain the range, and the cipher block that follows the range.

Parameters:

range - A two-element array of longs corresponding to the start and finish (inclusive) of a desired range of bytes.

Returns:

A two-element array of longs corresponding to the start and finish of the cipher blocks to be retrieved. If the range is invalid, then return null.

adjustOutputToDesiredRange

public static S3Object adjustOutputToDesiredRange(S3Object object,
                                                  long[] range)

Adjusts the retrieved S3Object so that the object contents contain only the range of bytes desired by the user. Since encrypted contents can only be retrieved in CIPHER_BLOCK_SIZE (16 bytes) chunks, the S3Object potentially contains more bytes than desired, so this method adjusts the contents range.

Parameters:

object - The S3Object retrieved from S3 that could possibly contain more bytes than desired by the user.

range - A two-element array of longs corresponding to the start and finish (inclusive) of a desired range of bytes.

Returns:

The S3Object with adjusted object contents containing only the range desired by the user. If the range specified is invalid, then the S3Object is returned without any modifications.

generateOneTimeUseSymmetricKey

public static SecretKey generateOneTimeUseSymmetricKey()

Generates a one-time use Symmetric Key on-the-fly for use in envelope encryption.

createSymmetricCipher

public static Cipher createSymmetricCipher(SecretKey symmetricCryptoKey,
                                           int encryptMode,
                                           Provider cryptoProvider,
                                           byte[] initVector)

Creates a symmetric cipher in the specified mode from the given symmetric key and IV. The given crypto provider will provide the encryption implementation. If the crypto provider is null, then the default JCE crypto provider will be used.

getEncryptedSymmetricKey

public static byte[] getEncryptedSymmetricKey(SecretKey toBeEncrypted,
                                              EncryptionMaterials materials,
                                              Provider cryptoProvider)

Encrypts a symmetric key using the provided encryption materials and returns it in raw byte array form.

getEncryptedInputStream

public static ByteRangeCapturingInputStream getEncryptedInputStream(UploadPartRequest request,
                                                                    CipherFactory cipherFactory)

updateMetadataWithEncryptionInstruction

public static void updateMetadataWithEncryptionInstruction(PutObjectRequest request,
                                                           EncryptionInstruction instruction)

Update the request's ObjectMetadata with the necessary information for decrypting the object

Parameters:

request - Non-null PUT request encrypted using the given instruction

instruction - Non-null instruction used to encrypt the data in this PUT request.

updateMetadataWithEncryptionInfo

public static ObjectMetadata updateMetadataWithEncryptionInfo(InitiateMultipartUploadRequest request,
                                                              byte[] keyBytesToStoreInMetadata,
                                                              Cipher symmetricCipher,
                                                              Map<String,String> materialsDescription)

calculateCryptoContentLength

public static long calculateCryptoContentLength(Cipher symmetricCipher,
                                                UploadPartRequest request)