Package com.amazonaws.encryptionsdk.internal

Class DecryptionHandler<K extends MasterKey<K>>

java.lang.Object

com.amazonaws.encryptionsdk.internal.DecryptionHandler<K>

All Implemented Interfaces:

CryptoHandler, MessageCryptoHandler

public class DecryptionHandler<K extends MasterKey<K>>
extends Object
implements MessageCryptoHandler

This class implements the CryptoHandler interface by providing methods for the decryption of ciphertext produced by the methods in EncryptionHandler.

This class reads and parses the values in the ciphertext headers and delegates the decryption of the ciphertext to the BlockDecryptionHandler or FrameDecryptionHandler based on the content type parsed in the ciphertext headers.

Method Summary

Modifier and Type	Method	Description
static DecryptionHandler<?>	create(CryptoMaterialsManager materialsManager, CommitmentPolicy commitmentPolicy, SignaturePolicy signaturePolicy, int maxEncryptedDataKeys)	Create a decryption handler using the provided materials manager.
static DecryptionHandler<?>	create(CryptoMaterialsManager materialsManager, CiphertextHeaders headers, CommitmentPolicy commitmentPolicy, SignaturePolicy signaturePolicy, int maxEncryptedDataKeys)	Deprecated. This version may have to recalculate the number of bytes already parsed, which adds a performance penalty.
static DecryptionHandler<?>	create(CryptoMaterialsManager materialsManager, ParsedCiphertext headers, CommitmentPolicy commitmentPolicy, SignaturePolicy signaturePolicy, int maxEncryptedDataKeys)	Create a decryption handler using the provided materials manager and already parsed headers.
static <K extends MasterKey<K>> DecryptionHandler<K>	create(MasterKeyProvider<K> customerMasterKeyProvider, CommitmentPolicy commitmentPolicy, SignaturePolicy signaturePolicy, int maxEncryptedDataKeys)	Create a decryption handler using the provided master key.
static <K extends MasterKey<K>> DecryptionHandler<K>	create(MasterKeyProvider<K> customerMasterKeyProvider, CiphertextHeaders headers, CommitmentPolicy commitmentPolicy, SignaturePolicy signaturePolicy, int maxEncryptedDataKeys)	Deprecated. This version may have to recalculate the number of bytes already parsed, which adds a performance penalty.
static <K extends MasterKey<K>> DecryptionHandler<K>	create(MasterKeyProvider<K> customerMasterKeyProvider, ParsedCiphertext headers, CommitmentPolicy commitmentPolicy, SignaturePolicy signaturePolicy, int maxEncryptedDataKeys)	Create a decryption handler using the provided master key and already parsed headers.
static DecryptionHandler<?>	create(software.amazon.cryptography.materialproviders.ICryptographicMaterialsManager materialsManager, CommitmentPolicy commitmentPolicy, SignaturePolicy signaturePolicy, int maxEncryptedDataKeys)	Create a decryption handler using the provided materials manager.
static DecryptionHandler<?>	create(software.amazon.cryptography.materialproviders.ICryptographicMaterialsManager materialsManager, CommitmentPolicy commitmentPolicy, SignaturePolicy signaturePolicy, int maxEncryptedDataKeys, Map<String,String> reproducedEncryptionContext)	Create a decryption handler using the provided materials manager.
static DecryptionHandler<?>	create(software.amazon.cryptography.materialproviders.ICryptographicMaterialsManager materialsManager, ParsedCiphertext headers, CommitmentPolicy commitmentPolicy, SignaturePolicy signaturePolicy, int maxEncryptedDataKeys)	Create a decryption handler using the provided materials manager and already parsed headers.
static DecryptionHandler<?>	create(software.amazon.cryptography.materialproviders.ICryptographicMaterialsManager materialsManager, ParsedCiphertext headers, CommitmentPolicy commitmentPolicy, SignaturePolicy signaturePolicy, int maxEncryptedDataKeys, Map<String,String> reproducedEncryptionContext)	Create a decryption handler using the provided materials manager and already parsed headers.
int	doFinal(byte[] out, int outOff)	Finish processing of the bytes.
int	estimateFinalOutputSize()	Return the size of the output buffer required for a call to CryptoHandler.doFinal(byte[], int).
int	estimateOutputSize(int inLen)	Return the size of the output buffer required for a processBytes plus a doFinal with an input of inLen bytes.
int	estimatePartialOutputSize(int inLen)	Return the size of the output buffer required for a call to CryptoHandler.processBytes(byte[], int, int, byte[], int).
Map<String,String>	getEncryptionContext()	Return the encryption context.
CiphertextHeaders	getHeaders()
List<K>	getMasterKeys()	All used MasterKeys.
boolean	isComplete()	For decrypt and parsing flows returns true when this has handled as many bytes as it can.
ProcessingSummary	processBytes(byte[] in, int off, int len, byte[] out, int outOff)	Decrypt the ciphertext bytes provided in in and copy the plaintext bytes to out.
void	setMaxInputLength(long size)	Informs this handler of an upper bound on the input data size.

Methods inherited from class java.lang.Object

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

Method Detail

create

public static <K extends MasterKey<K>> DecryptionHandler<K> create(MasterKeyProvider<K> customerMasterKeyProvider,
                                                                   CommitmentPolicy commitmentPolicy,
                                                                   SignaturePolicy signaturePolicy,
                                                                   int maxEncryptedDataKeys)
                                                            throws AwsCryptoException

Create a decryption handler using the provided master key.

Note the methods in the provided master key are used in decrypting the encrypted data key parsed from the ciphertext headers.

Parameters:

customerMasterKeyProvider - the master key provider to use in picking a master key from the key blobs encoded in the provided ciphertext.

commitmentPolicy - The commitment policy to enforce during decryption

signaturePolicy - The signature policy to enforce during decryption

maxEncryptedDataKeys - The maximum number of encrypted data keys to unwrap during decryption; zero indicates no maximum

Throws:

AwsCryptoException - if the master key is null.

create

@Deprecated
public static <K extends MasterKey<K>> DecryptionHandler<K> create(MasterKeyProvider<K> customerMasterKeyProvider,
                                                                   CiphertextHeaders headers,
                                                                   CommitmentPolicy commitmentPolicy,
                                                                   SignaturePolicy signaturePolicy,
                                                                   int maxEncryptedDataKeys)
                                                            throws AwsCryptoException

Deprecated.

This version may have to recalculate the number of bytes already parsed, which adds a performance penalty. Use create(CryptoMaterialsManager, ParsedCiphertext, CommitmentPolicy, SignaturePolicy, int) instead, which makes the parsed byte count directly available instead.

Create a decryption handler using the provided master key and already parsed headers.

Note the methods in the provided master key are used in decrypting the encrypted data key parsed from the ciphertext headers.

Parameters:

customerMasterKeyProvider - the master key provider to use in picking a master key from the key blobs encoded in the provided ciphertext.

headers - already parsed headers which will not be passed into processBytes(byte[], int, int, byte[], int)

commitmentPolicy - The commitment policy to enforce during decryption

signaturePolicy - The signature policy to enforce during decryption

maxEncryptedDataKeys - The maximum number of encrypted data keys to unwrap during decryption; zero indicates no maximum

Throws:

AwsCryptoException - if the master key is null.

create

public static <K extends MasterKey<K>> DecryptionHandler<K> create(MasterKeyProvider<K> customerMasterKeyProvider,
                                                                   ParsedCiphertext headers,
                                                                   CommitmentPolicy commitmentPolicy,
                                                                   SignaturePolicy signaturePolicy,
                                                                   int maxEncryptedDataKeys)
                                                            throws AwsCryptoException

Create a decryption handler using the provided master key and already parsed headers.

Note the methods in the provided master key are used in decrypting the encrypted data key parsed from the ciphertext headers.

Parameters:

customerMasterKeyProvider - the master key provider to use in picking a master key from the key blobs encoded in the provided ciphertext.

headers - already parsed headers which will not be passed into processBytes(byte[], int, int, byte[], int)

commitmentPolicy - The commitment policy to enforce during decryption

signaturePolicy - The signature policy to enforce during decryption

maxEncryptedDataKeys - The maximum number of encrypted data keys to unwrap during decryption; zero indicates no maximum

Throws:

AwsCryptoException - if the master key is null.

create

public static DecryptionHandler<?> create(CryptoMaterialsManager materialsManager,
                                          CommitmentPolicy commitmentPolicy,
                                          SignaturePolicy signaturePolicy,
                                          int maxEncryptedDataKeys)
                                   throws AwsCryptoException

Create a decryption handler using the provided materials manager.

Note the methods in the provided materials manager are used in decrypting the encrypted data key parsed from the ciphertext headers.

Parameters:

materialsManager - the materials manager to use in decrypting the data key from the key blobs encoded in the provided ciphertext.

commitmentPolicy - The commitment policy to enforce during decryption

signaturePolicy - The signature policy to enforce during decryption

maxEncryptedDataKeys - The maximum number of encrypted data keys to unwrap during decryption; zero indicates no maximum

Throws:

AwsCryptoException - if the master key is null.

create

public static DecryptionHandler<?> create(software.amazon.cryptography.materialproviders.ICryptographicMaterialsManager materialsManager,
                                          CommitmentPolicy commitmentPolicy,
                                          SignaturePolicy signaturePolicy,
                                          int maxEncryptedDataKeys)
                                   throws AwsCryptoException

Create a decryption handler using the provided materials manager.

Note the methods in the provided materials manager are used in decrypting the encrypted data key parsed from the ciphertext headers.

Parameters:

materialsManager - the materials manager to use in decrypting the data key from the key blobs encoded in the provided ciphertext.

commitmentPolicy - The commitment policy to enforce during decryption

signaturePolicy - The signature policy to enforce during decryption

maxEncryptedDataKeys - The maximum number of encrypted data keys to unwrap during decryption; zero indicates no maximum

Throws:

AwsCryptoException - if the master key is null.

create

public static DecryptionHandler<?> create(software.amazon.cryptography.materialproviders.ICryptographicMaterialsManager materialsManager,
                                          CommitmentPolicy commitmentPolicy,
                                          SignaturePolicy signaturePolicy,
                                          int maxEncryptedDataKeys,
                                          Map<String,String> reproducedEncryptionContext)
                                   throws AwsCryptoException

Create a decryption handler using the provided materials manager.

Note the methods in the provided materials manager are used in decrypting the encrypted data key parsed from the ciphertext headers.

Parameters:

materialsManager - the materials manager to use in decrypting the data key from the key blobs encoded in the provided ciphertext.

commitmentPolicy - The commitment policy to enforce during decryption

signaturePolicy - The signature policy to enforce during decryption

maxEncryptedDataKeys - The maximum number of encrypted data keys to unwrap during decryption; zero indicates no maximum

reproducedEncryptionContext - The reproduced encryption context MUST contain a value for every key in the configured required encryption context keys during encryption with Required Encryption Context CMM.

Throws:

AwsCryptoException - if the master key is null.

create

@Deprecated
public static DecryptionHandler<?> create(CryptoMaterialsManager materialsManager,
                                          CiphertextHeaders headers,
                                          CommitmentPolicy commitmentPolicy,
                                          SignaturePolicy signaturePolicy,
                                          int maxEncryptedDataKeys)
                                   throws AwsCryptoException

Deprecated.

This version may have to recalculate the number of bytes already parsed, which adds a performance penalty. Use create(CryptoMaterialsManager, ParsedCiphertext, CommitmentPolicy, SignaturePolicy, int) instead, which makes the parsed byte count directly available instead.

Create a decryption handler using the provided materials manager and already parsed headers.

Note the methods in the provided materials manager are used in decrypting the encrypted data key parsed from the ciphertext headers.

Parameters:

materialsManager - the materials manager to use in decrypting the data key from the key blobs encoded in the provided ciphertext.

headers - already parsed headers which will not be passed into processBytes(byte[], int, int, byte[], int)

commitmentPolicy - The commitment policy to enforce during decryption

signaturePolicy - The signature policy to enforce during decryption

maxEncryptedDataKeys - The maximum number of encrypted data keys to unwrap during decryption; zero indicates no maximum

Throws:

AwsCryptoException - if the master key is null.

create

public static DecryptionHandler<?> create(CryptoMaterialsManager materialsManager,
                                          ParsedCiphertext headers,
                                          CommitmentPolicy commitmentPolicy,
                                          SignaturePolicy signaturePolicy,
                                          int maxEncryptedDataKeys)
                                   throws AwsCryptoException

Create a decryption handler using the provided materials manager and already parsed headers.

Note the methods in the provided materials manager are used in decrypting the encrypted data key parsed from the ciphertext headers.

Parameters:

materialsManager - the materials manager to use in decrypting the data key from the key blobs encoded in the provided ciphertext.

headers - already parsed headers which will not be passed into processBytes(byte[], int, int, byte[], int)

commitmentPolicy - The commitment policy to enforce during decryption

signaturePolicy - The signature policy to enforce during decryption

maxEncryptedDataKeys - The maximum number of encrypted data keys to unwrap during decryption; zero indicates no maximum

Throws:

AwsCryptoException - if the master key is null.

create

public static DecryptionHandler<?> create(software.amazon.cryptography.materialproviders.ICryptographicMaterialsManager materialsManager,
                                          ParsedCiphertext headers,
                                          CommitmentPolicy commitmentPolicy,
                                          SignaturePolicy signaturePolicy,
                                          int maxEncryptedDataKeys)
                                   throws AwsCryptoException

Create a decryption handler using the provided materials manager and already parsed headers.

Note the methods in the provided materials manager are used in decrypting the encrypted data key parsed from the ciphertext headers.

Parameters:

materialsManager - the materials manager to use in decrypting the data key from the key blobs encoded in the provided ciphertext.

headers - already parsed headers which will not be passed into processBytes(byte[], int, int, byte[], int)

commitmentPolicy - The commitment policy to enforce during decryption

signaturePolicy - The signature policy to enforce during decryption

maxEncryptedDataKeys - The maximum number of encrypted data keys to unwrap during decryption; zero indicates no maximum

Throws:

AwsCryptoException - if the master key is null.

create

public static DecryptionHandler<?> create(software.amazon.cryptography.materialproviders.ICryptographicMaterialsManager materialsManager,
                                          ParsedCiphertext headers,
                                          CommitmentPolicy commitmentPolicy,
                                          SignaturePolicy signaturePolicy,
                                          int maxEncryptedDataKeys,
                                          Map<String,String> reproducedEncryptionContext)
                                   throws AwsCryptoException

Create a decryption handler using the provided materials manager and already parsed headers.

Note the methods in the provided materials manager are used in decrypting the encrypted data key parsed from the ciphertext headers.

Parameters:

materialsManager - the materials manager to use in decrypting the data key from the key blobs encoded in the provided ciphertext.

headers - already parsed headers which will not be passed into processBytes(byte[], int, int, byte[], int)

commitmentPolicy - The commitment policy to enforce during decryption

signaturePolicy - The signature policy to enforce during decryption

maxEncryptedDataKeys - The maximum number of encrypted data keys to unwrap during decryption; zero indicates no maximum

reproducedEncryptionContext - The reproduced encryption context MUST contain a value for every key in the configured required encryption context keys during encryption with Required Encryption Context CMM.

Throws:

AwsCryptoException - if the master key is null.

processBytes

public ProcessingSummary processBytes(byte[] in,
                                      int off,
                                      int len,
                                      byte[] out,
                                      int outOff)
                               throws BadCiphertextException,
                                      AwsCryptoException

Decrypt the ciphertext bytes provided in in and copy the plaintext bytes to out.

This method consumes and parses the ciphertext headers. The decryption of the actual content is delegated to BlockDecryptionHandler or FrameDecryptionHandler based on the content type parsed in the ciphertext header.

Specified by:

processBytes in interface CryptoHandler

Parameters:

in - the input byte array.

off - the offset into the in array where the data to be decrypted starts.

len - the number of bytes to be decrypted.

out - the output buffer the decrypted plaintext bytes go into.

outOff - the offset into the output byte array the decrypted data starts at.

Returns:

the number of bytes written to out and processed.

Throws:

BadCiphertextException - if the ciphertext header contains invalid entries or if the header integrity check fails.

AwsCryptoException - if any of the offset or length arguments are negative or if the total bytes to decrypt exceeds the maximum allowed value.

doFinal

public int doFinal(byte[] out,
                   int outOff)
            throws BadCiphertextException

Finish processing of the bytes.

Specified by:

doFinal in interface CryptoHandler

Parameters:

out - space for any resulting output data.

outOff - offset into out to start copying the data at.

Returns:

number of bytes written into out.

Throws:

BadCiphertextException - if the bytes do not decrypt correctly.

estimateOutputSize

public int estimateOutputSize(int inLen)

Return the size of the output buffer required for a processBytes plus a doFinal with an input of inLen bytes.

Specified by:

estimateOutputSize in interface CryptoHandler

Parameters:

inLen - the length of the input.

Returns:

the space required to accommodate a call to processBytes and doFinal with input of size inLen bytes.

estimatePartialOutputSize

public int estimatePartialOutputSize(int inLen)

Description copied from interface: CryptoHandler

Return the size of the output buffer required for a call to CryptoHandler.processBytes(byte[], int, int, byte[], int).

Note this method is allowed to return an estimation of the output size that is greater than the actual size of the output. Returning an estimate that is lesser than the actual size of the output will result in underflow exceptions.

Specified by:

estimatePartialOutputSize in interface CryptoHandler

Parameters:

inLen - the length of the input.

Returns:

the space required to accommodate a call to CryptoHandler.processBytes(byte[], int, int, byte[], int) with an input of size inLen bytes.

estimateFinalOutputSize

public int estimateFinalOutputSize()

Description copied from interface: CryptoHandler

Return the size of the output buffer required for a call to CryptoHandler.doFinal(byte[], int).

Note this method is allowed to return an estimation of the output size that is greater than the actual size of the output. Returning an estimate that is lesser than the actual size of the output will result in underflow exceptions.

Specified by:

estimateFinalOutputSize in interface CryptoHandler

Returns:

the space required to accomodate a call to CryptoHandler.doFinal(byte[], int)

getEncryptionContext

public Map<String,String> getEncryptionContext()

Return the encryption context. This value is parsed from the ciphertext.

Specified by:

getEncryptionContext in interface MessageCryptoHandler

Returns:

the key-value map containing the encryption client.

setMaxInputLength

public void setMaxInputLength(long size)

Description copied from interface: MessageCryptoHandler

Informs this handler of an upper bound on the input data size. The handler will throw an exception if this bound is exceeded, and may use it to perform performance optimizations as well.

If this method is called multiple times, the smallest bound will be used.

Specified by:

setMaxInputLength in interface MessageCryptoHandler

Parameters:

size - An upper bound on the input data size.

getHeaders

public CiphertextHeaders getHeaders()

Specified by:

getHeaders in interface MessageCryptoHandler

getMasterKeys

public List<K> getMasterKeys()

Description copied from interface: MessageCryptoHandler

All used MasterKeys. For encryption flows, these are all the MasterKeys used to protect the data. In the decryption flow, it is the single MasterKey actually used to decrypt the data.

Specified by:

getMasterKeys in interface MessageCryptoHandler

isComplete

public boolean isComplete()

Description copied from interface: CryptoHandler

For decrypt and parsing flows returns true when this has handled as many bytes as it can. This usually means that it has reached the end of an object, file, or other delimited stream.

Specified by:

isComplete in interface CryptoHandler