Package com.amazonaws.encryptionsdk

Class AwsCrypto

java.lang.Object

com.amazonaws.encryptionsdk.AwsCrypto

public class AwsCrypto
extends Object

Provides the primary entry-point to the AWS Encryption SDK. All encryption and decryption operations should start here. Most people will want to use either encryptData(MasterKeyProvider, byte[], Map) and decryptData(MasterKeyProvider, byte[]) to encrypt/decrypt things.

The core concepts (and classes) in this SDK are:

• AwsCrypto
• DataKey
• MasterKey
• MasterKeyProvider

AwsCrypto provides the primary way to encrypt/decrypt data. It can operate on byte-arrays, streams, or Strings. This data is encrypted using the specifed CryptoAlgorithm and a DataKey which is unique to each encrypted message. This DataKey is then encrypted using one (or more) MasterKeys. The process is reversed on decryption with the code selecting a copy of the DataKey protected by a usable MasterKey, decrypting the DataKey, and then decrypted the message.

The main way to get a MasterKey is through the use of a MasterKeyProvider. This provides a common interface for the AwsEncryptionSdk to find and retrieve MasterKeys. (Some MasterKeys can also be constructed directly.)

AwsCrypto uses the MasterKeyProvider to determine which MasterKeys should be used to encrypt the DataKeys by calling MasterKeyProvider.getMasterKeysForEncryption(MasterKeyRequest) . When more than one MasterKey is returned, the first MasterKeys is used to create the DataKeys by calling MasterKey.generateDataKey(CryptoAlgorithm,java.util.Map) . All of the other MasterKeys are then used to re-encrypt that DataKey with MasterKey.encryptDataKey(CryptoAlgorithm,java.util.Map,DataKey) . This list of EncryptedDataKeys (the same DataKey possibly encrypted multiple times) is stored in the CiphertextHeaders.

AwsCrypto also uses the MasterKeyProvider to decrypt one of the EncryptedDataKeys from the header to retrieve the actual DataKey necessary to decrypt the message.

Any place a MasterKeyProvider is used, a MasterKey can be used instead. The MasterKey will behave as a MasterKeyProvider which is only capable of providing itself. This is often useful when only one MasterKey is being used.

Note regarding the use of generics: This library makes heavy use of generics to provide type safety to advanced developers. The great majority of users should be able to just use the provided type parameters or the ? wildcard.

Constructor Summary

Constructors

Constructor	Description
AwsCrypto()

Method Summary

Modifier and Type	Method	Description
CryptoInputStream<?>	createDecryptingStream(CryptoMaterialsManager materialsManager, InputStream is)	Returns a CryptoInputStream which decrypts the data after reading it from the underlying InputStream.
CryptoOutputStream<?>	createDecryptingStream(CryptoMaterialsManager materialsManager, OutputStream os)	Returns a CryptoOutputStream which decrypts the data prior to passing it onto the underlying OutputStream.
<K extends MasterKey<K>> CryptoInputStream<K>	createDecryptingStream(MasterKeyProvider<K> provider, InputStream is)	Returns a CryptoInputStream which decrypts the data after reading it from the underlying InputStream.
<K extends MasterKey<K>> CryptoOutputStream<K>	createDecryptingStream(MasterKeyProvider<K> provider, OutputStream os)	Returns a CryptoOutputStream which decrypts the data prior to passing it onto the underlying OutputStream.
CryptoInputStream<?>	createEncryptingStream(CryptoMaterialsManager materialsManager, InputStream is)	Returns the equivalent to calling createEncryptingStream(CryptoMaterialsManager, InputStream, Map) with an empty encryptionContext.
CryptoInputStream<?>	createEncryptingStream(CryptoMaterialsManager materialsManager, InputStream is, Map<String,String> encryptionContext)	Returns a CryptoInputStream which encrypts the data after reading it from the underlying InputStream.
CryptoOutputStream<?>	createEncryptingStream(CryptoMaterialsManager materialsManager, OutputStream os)	Returns the equivalent to calling createEncryptingStream(CryptoMaterialsManager, OutputStream, Map) with an empty encryptionContext.
CryptoOutputStream<?>	createEncryptingStream(CryptoMaterialsManager materialsManager, OutputStream os, Map<String,String> encryptionContext)	Returns a CryptoOutputStream which encrypts the data prior to passing it onto the underlying OutputStream.
<K extends MasterKey<K>> CryptoInputStream<K>	createEncryptingStream(MasterKeyProvider<K> provider, InputStream is)	Returns the equivalent to calling createEncryptingStream(MasterKeyProvider, InputStream, Map) with an empty encryptionContext.
<K extends MasterKey<K>> CryptoInputStream<K>	createEncryptingStream(MasterKeyProvider<K> provider, InputStream is, Map<String,String> encryptionContext)	Returns a CryptoInputStream which encrypts the data after reading it from the underlying InputStream.
<K extends MasterKey<K>> CryptoOutputStream<K>	createEncryptingStream(MasterKeyProvider<K> provider, OutputStream os)	Returns the equivalent to calling createEncryptingStream(MasterKeyProvider, OutputStream, Map) with an empty encryptionContext.
<K extends MasterKey<K>> CryptoOutputStream<K>	createEncryptingStream(MasterKeyProvider<K> provider, OutputStream os, Map<String,String> encryptionContext)	Returns a CryptoOutputStream which encrypts the data prior to passing it onto the underlying OutputStream.
CryptoResult<byte[],?>	decryptData(CryptoMaterialsManager materialsManager, byte[] ciphertext)	Decrypts the provided ciphertext by delegating to the provided materialsManager to obtain the decrypted DataKey.
CryptoResult<byte[],?>	decryptData(CryptoMaterialsManager materialsManager, ParsedCiphertext ciphertext)
<K extends MasterKey<K>> CryptoResult<byte[],K>	decryptData(MasterKeyProvider<K> provider, byte[] ciphertext)	Decrypts the provided ciphertext by requesting that the provider unwrap any usable DataKey in the ciphertext and then decrypts the ciphertext using that DataKey.
<K extends MasterKey<K>> CryptoResult<byte[],K>	decryptData(MasterKeyProvider<K> provider, ParsedCiphertext ciphertext)
CryptoResult<String,?>	decryptString(CryptoMaterialsManager provider, String ciphertext)	Base64 decodes the ciphertext prior to decryption and then treats the results as a UTF-8 encoded string.
<K extends MasterKey<K>> CryptoResult<String,K>	decryptString(MasterKeyProvider<K> provider, String ciphertext)	Base64 decodes the ciphertext prior to decryption and then treats the results as a UTF-8 encoded string.
CryptoResult<byte[],?>	encryptData(CryptoMaterialsManager materialsManager, byte[] plaintext)	Returns the equivalent to calling encryptData(CryptoMaterialsManager, byte[], Map) with an empty encryptionContext.
CryptoResult<byte[],?>	encryptData(CryptoMaterialsManager materialsManager, byte[] plaintext, Map<String,String> encryptionContext)	Returns an encrypted form of plaintext that has been protected with DataKeys that are in turn protected by the given CryptoMaterialsProvider.
<K extends MasterKey<K>> CryptoResult<byte[],K>	encryptData(MasterKeyProvider<K> provider, byte[] plaintext)	Returns the equivalent to calling encryptData(MasterKeyProvider, byte[], Map) with an empty encryptionContext.
<K extends MasterKey<K>> CryptoResult<byte[],K>	encryptData(MasterKeyProvider<K> provider, byte[] plaintext, Map<String,String> encryptionContext)	Returns an encrypted form of plaintext that has been protected with DataKeys that are in turn protected by MasterKeys provided by provider.
CryptoResult<String,?>	encryptString(CryptoMaterialsManager materialsManager, String plaintext)	Returns the equivalent to calling encryptString(CryptoMaterialsManager, String, Map) with an empty encryptionContext.
CryptoResult<String,?>	encryptString(CryptoMaterialsManager materialsManager, String plaintext, Map<String,String> encryptionContext)	Calls encryptData(CryptoMaterialsManager, byte[], Map) on the UTF-8 encoded bytes of plaintext and base64 encodes the result.
<K extends MasterKey<K>> CryptoResult<String,K>	encryptString(MasterKeyProvider<K> provider, String plaintext)	Returns the equivalent to calling encryptString(MasterKeyProvider, String, Map) with an empty encryptionContext.
<K extends MasterKey<K>> CryptoResult<String,K>	encryptString(MasterKeyProvider<K> provider, String plaintext, Map<String,String> encryptionContext)	Calls encryptData(MasterKeyProvider, byte[], Map) on the UTF-8 encoded bytes of plaintext and base64 encodes the result.
long	estimateCiphertextSize(CryptoMaterialsManager materialsManager, int plaintextSize)	Returns the equivalent to calling estimateCiphertextSize(CryptoMaterialsManager, int, Map) with an empty encryptionContext.
long	estimateCiphertextSize(CryptoMaterialsManager materialsManager, int plaintextSize, Map<String,String> encryptionContext)	Returns the best estimate for the output length of encrypting a plaintext with the provided plaintextSize and encryptionContext.
<K extends MasterKey<K>> long	estimateCiphertextSize(MasterKeyProvider<K> provider, int plaintextSize)	Returns the equivalent to calling estimateCiphertextSize(MasterKeyProvider, int, Map) with an empty encryptionContext.
<K extends MasterKey<K>> long	estimateCiphertextSize(MasterKeyProvider<K> provider, int plaintextSize, Map<String,String> encryptionContext)	Returns the best estimate for the output length of encrypting a plaintext with the provided plaintextSize and encryptionContext.
static CryptoAlgorithm	getDefaultCryptoAlgorithm()	Returns the CryptoAlgorithm to be used for encryption when none is explicitly selected.
static int	getDefaultFrameSize()	Returns the frame size to use for encryption when none is explicitly selected.
CryptoAlgorithm	getEncryptionAlgorithm()
int	getEncryptionFrameSize()
void	setEncryptionAlgorithm(CryptoAlgorithm alg)	Sets the CryptoAlgorithm to use when encrypting data.
void	setEncryptionFrameSize(int frameSize)	Sets the framing size to use when encrypting data.

Methods inherited from class java.lang.Object

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

Constructor Detail

AwsCrypto

public AwsCrypto()

Method Detail

getDefaultCryptoAlgorithm

public static CryptoAlgorithm getDefaultCryptoAlgorithm()

Returns the CryptoAlgorithm to be used for encryption when none is explicitly selected. Currently it is CryptoAlgorithm.ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384.

getDefaultFrameSize

public static int getDefaultFrameSize()

Returns the frame size to use for encryption when none is explicitly selected. Currently it is 4096.

setEncryptionAlgorithm

public void setEncryptionAlgorithm(CryptoAlgorithm alg)

Sets the CryptoAlgorithm to use when encrypting data. This has no impact on decryption.

getEncryptionAlgorithm

public CryptoAlgorithm getEncryptionAlgorithm()

setEncryptionFrameSize

public void setEncryptionFrameSize(int frameSize)

Sets the framing size to use when encrypting data. This has no impact on decryption. If frameSize is 0, then framing is disabled and the entire plaintext will be encrypted in a single block. Note that during encryption arrays of this size will be allocated. Using extremely large frame sizes may pose compatibility issues when the decryptor is running on 32-bit systems. Additionally, Java VM limits may set a platform-specific upper bound to frame sizes.

getEncryptionFrameSize

public int getEncryptionFrameSize()

estimateCiphertextSize

public <K extends MasterKey<K>> long estimateCiphertextSize(MasterKeyProvider<K> provider,
                                                            int plaintextSize,
                                                            Map<String,String> encryptionContext)

Returns the best estimate for the output length of encrypting a plaintext with the provided plaintextSize and encryptionContext. The actual ciphertext may be shorter. This method is equivalent to calling estimateCiphertextSize(CryptoMaterialsManager, int, Map) with a DefaultCryptoMaterialsManager based on the given provider.

estimateCiphertextSize

public long estimateCiphertextSize(CryptoMaterialsManager materialsManager,
                                   int plaintextSize,
                                   Map<String,String> encryptionContext)

Returns the best estimate for the output length of encrypting a plaintext with the provided plaintextSize and encryptionContext. The actual ciphertext may be shorter.

estimateCiphertextSize

public <K extends MasterKey<K>> long estimateCiphertextSize(MasterKeyProvider<K> provider,
                                                            int plaintextSize)

Returns the equivalent to calling estimateCiphertextSize(MasterKeyProvider, int, Map) with an empty encryptionContext.

estimateCiphertextSize

public long estimateCiphertextSize(CryptoMaterialsManager materialsManager,
                                   int plaintextSize)

Returns the equivalent to calling estimateCiphertextSize(CryptoMaterialsManager, int, Map) with an empty encryptionContext.

encryptData

public <K extends MasterKey<K>> CryptoResult<byte[],K> encryptData(MasterKeyProvider<K> provider,
                                                                         byte[] plaintext,
                                                                         Map<String,String> encryptionContext)

Returns an encrypted form of plaintext that has been protected with DataKeys that are in turn protected by MasterKeys provided by provider. This method is equivalent to calling encryptData(CryptoMaterialsManager, byte[], Map) using a DefaultCryptoMaterialsManager based on the given provider.

encryptData

public CryptoResult<byte[],?> encryptData(CryptoMaterialsManager materialsManager,
                                                byte[] plaintext,
                                                Map<String,String> encryptionContext)

Returns an encrypted form of plaintext that has been protected with DataKeys that are in turn protected by the given CryptoMaterialsProvider.

encryptData

public <K extends MasterKey<K>> CryptoResult<byte[],K> encryptData(MasterKeyProvider<K> provider,
                                                                         byte[] plaintext)

Returns the equivalent to calling encryptData(MasterKeyProvider, byte[], Map) with an empty encryptionContext.

encryptData

public CryptoResult<byte[],?> encryptData(CryptoMaterialsManager materialsManager,
                                                byte[] plaintext)

Returns the equivalent to calling encryptData(CryptoMaterialsManager, byte[], Map) with an empty encryptionContext.

encryptString

public <K extends MasterKey<K>> CryptoResult<String,K> encryptString(MasterKeyProvider<K> provider,
                                                                           String plaintext,
                                                                           Map<String,String> encryptionContext)

Calls encryptData(MasterKeyProvider, byte[], Map) on the UTF-8 encoded bytes of plaintext and base64 encodes the result.

encryptString

public CryptoResult<String,?> encryptString(CryptoMaterialsManager materialsManager,
                                                  String plaintext,
                                                  Map<String,String> encryptionContext)

Calls encryptData(CryptoMaterialsManager, byte[], Map) on the UTF-8 encoded bytes of plaintext and base64 encodes the result.

encryptString

public <K extends MasterKey<K>> CryptoResult<String,K> encryptString(MasterKeyProvider<K> provider,
                                                                           String plaintext)

Returns the equivalent to calling encryptString(MasterKeyProvider, String, Map) with an empty encryptionContext.

encryptString

public CryptoResult<String,?> encryptString(CryptoMaterialsManager materialsManager,
                                                  String plaintext)

Returns the equivalent to calling encryptString(CryptoMaterialsManager, String, Map) with an empty encryptionContext.

decryptData

public <K extends MasterKey<K>> CryptoResult<byte[],K> decryptData(MasterKeyProvider<K> provider,
                                                                         byte[] ciphertext)

Decrypts the provided ciphertext by requesting that the provider unwrap any usable DataKey in the ciphertext and then decrypts the ciphertext using that DataKey.

decryptData

public CryptoResult<byte[],?> decryptData(CryptoMaterialsManager materialsManager,
                                                byte[] ciphertext)

Decrypts the provided ciphertext by delegating to the provided materialsManager to obtain the decrypted DataKey.

Parameters:

materialsManager -

ciphertext -

Returns:

decryptData

public <K extends MasterKey<K>> CryptoResult<byte[],K> decryptData(MasterKeyProvider<K> provider,
                                                                         ParsedCiphertext ciphertext)

See Also:

decryptData(MasterKeyProvider, byte[])

decryptData

public CryptoResult<byte[],?> decryptData(CryptoMaterialsManager materialsManager,
                                                ParsedCiphertext ciphertext)

See Also:

decryptData(CryptoMaterialsManager, byte[])

decryptString

public <K extends MasterKey<K>> CryptoResult<String,K> decryptString(MasterKeyProvider<K> provider,
                                                                           String ciphertext)

Base64 decodes the ciphertext prior to decryption and then treats the results as a UTF-8 encoded string.

See Also:

decryptData(MasterKeyProvider, byte[])

decryptString

public CryptoResult<String,?> decryptString(CryptoMaterialsManager provider,
                                                  String ciphertext)

Base64 decodes the ciphertext prior to decryption and then treats the results as a UTF-8 encoded string.

See Also:

decryptData(CryptoMaterialsManager, byte[])

createEncryptingStream

public <K extends MasterKey<K>> CryptoOutputStream<K> createEncryptingStream(MasterKeyProvider<K> provider,
                                                                             OutputStream os,
                                                                             Map<String,String> encryptionContext)

Returns a CryptoOutputStream which encrypts the data prior to passing it onto the underlying OutputStream.

See Also:

encryptData(MasterKeyProvider, byte[], Map), CipherOutputStream

createEncryptingStream

public CryptoOutputStream<?> createEncryptingStream(CryptoMaterialsManager materialsManager,
                                                    OutputStream os,
                                                    Map<String,String> encryptionContext)

Returns a CryptoOutputStream which encrypts the data prior to passing it onto the underlying OutputStream.

See Also:

encryptData(MasterKeyProvider, byte[], Map), CipherOutputStream

createEncryptingStream

public <K extends MasterKey<K>> CryptoOutputStream<K> createEncryptingStream(MasterKeyProvider<K> provider,
                                                                             OutputStream os)

Returns the equivalent to calling createEncryptingStream(MasterKeyProvider, OutputStream, Map) with an empty encryptionContext.

createEncryptingStream

public CryptoOutputStream<?> createEncryptingStream(CryptoMaterialsManager materialsManager,
                                                    OutputStream os)

Returns the equivalent to calling createEncryptingStream(CryptoMaterialsManager, OutputStream, Map) with an empty encryptionContext.

createEncryptingStream

public <K extends MasterKey<K>> CryptoInputStream<K> createEncryptingStream(MasterKeyProvider<K> provider,
                                                                            InputStream is,
                                                                            Map<String,String> encryptionContext)

Returns a CryptoInputStream which encrypts the data after reading it from the underlying InputStream.

See Also:

encryptData(MasterKeyProvider, byte[], Map), CipherInputStream

createEncryptingStream

public CryptoInputStream<?> createEncryptingStream(CryptoMaterialsManager materialsManager,
                                                   InputStream is,
                                                   Map<String,String> encryptionContext)

Returns a CryptoInputStream which encrypts the data after reading it from the underlying InputStream.

See Also:

encryptData(MasterKeyProvider, byte[], Map), CipherInputStream

createEncryptingStream

public <K extends MasterKey<K>> CryptoInputStream<K> createEncryptingStream(MasterKeyProvider<K> provider,
                                                                            InputStream is)

Returns the equivalent to calling createEncryptingStream(MasterKeyProvider, InputStream, Map) with an empty encryptionContext.

createEncryptingStream

public CryptoInputStream<?> createEncryptingStream(CryptoMaterialsManager materialsManager,
                                                   InputStream is)

Returns the equivalent to calling createEncryptingStream(CryptoMaterialsManager, InputStream, Map) with an empty encryptionContext.

createDecryptingStream

public <K extends MasterKey<K>> CryptoOutputStream<K> createDecryptingStream(MasterKeyProvider<K> provider,
                                                                             OutputStream os)

Returns a CryptoOutputStream which decrypts the data prior to passing it onto the underlying OutputStream.

See Also:

decryptData(MasterKeyProvider, byte[]), CipherOutputStream

createDecryptingStream

public <K extends MasterKey<K>> CryptoInputStream<K> createDecryptingStream(MasterKeyProvider<K> provider,
                                                                            InputStream is)

Returns a CryptoInputStream which decrypts the data after reading it from the underlying InputStream.

See Also:

decryptData(MasterKeyProvider, byte[]), CipherInputStream

createDecryptingStream

public CryptoOutputStream<?> createDecryptingStream(CryptoMaterialsManager materialsManager,
                                                    OutputStream os)

Returns a CryptoOutputStream which decrypts the data prior to passing it onto the underlying OutputStream.

See Also:

decryptData(CryptoMaterialsManager, byte[]), CipherOutputStream

createDecryptingStream

public CryptoInputStream<?> createDecryptingStream(CryptoMaterialsManager materialsManager,
                                                   InputStream is)

Returns a CryptoInputStream which decrypts the data after reading it from the underlying InputStream.

See Also:

encryptData(CryptoMaterialsManager, byte[], Map), CipherInputStream