public final class CipherText extends Object implements Serializable
Serializable
interface representing the result of encrypting
plaintext and some additional information about the encryption algorithm,
the IV (if pertinent), and an optional Message Authentication Code (MAC).
Note that while this class is Serializable
in the usual Java sense,
ESAPI uses asPortableSerializedByteArray()
for serialization. Not
only is this serialization somewhat more compact, it is also portable
across other ESAPI programming language implementations. However, Java
serialization is supported in the event that one wishes to store
CipherText
in an HttpSession
object.
Copyright © 2009 - The OWASP Foundation
PlainText
,
Encryptor
,
Serialized FormModifier and Type | Field and Description |
---|---|
static int |
cipherTextVersion |
Constructor and Description |
---|
CipherText()
Default CTOR.
|
CipherText(CipherSpec cipherSpec)
Construct from a
CipherSpec object. |
CipherText(CipherSpec cipherSpec,
byte[] cipherText)
Construct from a
CipherSpec object and the raw ciphertext. |
Modifier and Type | Method and Description |
---|---|
byte[] |
asPortableSerializedByteArray()
Return this
CipherText object as a portable (i.e., network byte
ordered) serialized byte array. |
protected boolean |
canEqual(Object other)
Needed for correct definition of equals for general classes.
|
void |
computeAndStoreMAC(SecretKey authKey)
Compute and store the Message Authentication Code (MAC) if the ESAPI property
Encryptor.CipherText.useMAC is set to true . |
boolean |
equals(Object other) |
static CipherText |
fromPortableSerializedBytes(byte[] bytes)
Create a
CipherText object from what is supposed to be a
portable serialized byte array, given in network byte order, that
represents a valid, previously serialized CipherText object
using asPortableSerializedByteArray() . |
String |
getBase64EncodedRawCipherText()
Return a base64-encoded representation of the raw ciphertext alone.
|
int |
getBlockSize()
Retrieve the block size (in bytes!) of the cipher used for encryption.
|
String |
getCipherAlgorithm()
Obtain the name of the cipher algorithm used for encrypting the
plaintext.
|
String |
getCipherMode()
Get the name of the cipher mode used to encrypt some plaintext.
|
String |
getCipherTransformation()
Obtain the String representing the cipher transformation used to encrypt
the plaintext.
|
String |
getEncodedIVCipherText()
Return the ciphertext as a base64-encoded
String . |
long |
getEncryptionTimestamp()
Get stored time stamp representing when data was encrypted.
|
byte[] |
getIV()
Return the initialization vector (IV) used to encrypt the plaintext
if applicable.
|
KeyDerivationFunction.PRF_ALGORITHMS |
getKDF_PRF() |
int |
getKDFInfo()
Based on the KDF version and the selected MAC algorithm for the KDF PRF,
calculate the 32-bit quantity representing these.
|
int |
getKDFVersion() |
int |
getKeySize()
Retrieve the key size used with the cipher algorithm that was used to
encrypt data to produce this ciphertext.
|
String |
getPaddingScheme()
Get the name of the padding scheme used to encrypt some plaintext.
|
byte[] |
getRawCipherText()
Get the raw ciphertext byte array resulting from encrypting some
plaintext.
|
int |
getRawCipherTextByteLength()
Get number of bytes in raw ciphertext.
|
byte[] |
getSeparateMAC()
Return the separately calculated Message Authentication Code (MAC) that
is computed via the
computeAndStoreMAC(SecretKey authKey) method. |
int |
hashCode() |
boolean |
requiresIV()
Return true if the cipher mode used requires an IV.
|
void |
setCiphertext(byte[] ciphertext)
Set the raw ciphertext.
|
void |
setIVandCiphertext(byte[] iv,
byte[] ciphertext)
Set the IV and raw ciphertext.
|
void |
setKDF_PRF(int prfSelection) |
void |
setKDFVersion(int vers) |
String |
toString()
More useful
toString() method. |
boolean |
validateMAC(SecretKey authKey)
Validate the message authentication code (MAC) associated with the ciphertext.
|
public static final int cipherTextVersion
public CipherText()
public CipherText(CipherSpec cipherSpec)
CipherSpec
object. Still needs to have
setCiphertext(byte[])
or setIVandCiphertext(byte[], byte[])
called to be usable.cipherSpec
- The cipher specification to use.public CipherText(CipherSpec cipherSpec, byte[] cipherText) throws EncryptionException
CipherSpec
object and the raw ciphertext.cipherSpec
- The cipher specification to use.cipherText
- The raw ciphertext bytes to use.EncryptionException
- Thrown if cipherText
is null or
empty array.public static CipherText fromPortableSerializedBytes(byte[] bytes) throws EncryptionException
CipherText
object from what is supposed to be a
portable serialized byte array, given in network byte order, that
represents a valid, previously serialized CipherText
object
using asPortableSerializedByteArray()
.bytes
- A byte array created via
CipherText.asPortableSerializedByteArray()
CipherText
object reconstructed from the byte array.EncryptionException
asPortableSerializedByteArray()
public String getCipherTransformation()
The cipher transformation name is usually sufficient to be passed to
Cipher.getInstance(String)
to create a
Cipher
object to decrypt the ciphertext.
public String getCipherAlgorithm()
public int getKeySize()
public int getBlockSize()
public String getCipherMode()
public String getPaddingScheme()
public byte[] getIV()
null
is returned.public boolean requiresIV()
public byte[] getRawCipherText()
public int getRawCipherTextByteLength()
public String getBase64EncodedRawCipherText()
If there is a need to store an encrypted value, say in a database, this
is not the method you should use unless you are using are storing the
IV separately (i.e., in a separate DB column), which doesn't make a lot of sense.
Normally, you should prefer the method getEncodedIVCipherText()
instead as
it will return the IV prepended to the ciphertext.
getEncodedIVCipherText()
public String getEncodedIVCipherText()
String
. If an
IV was used, the IV if first prepended to the raw ciphertext before
base64-encoding. If an IV is not used, then this method returns the same
value as getBase64EncodedRawCipherText()
.
getBase64EncodedRawCipherText()
public void computeAndStoreMAC(SecretKey authKey)
Encryptor.CipherText.useMAC
is set to true
. If it
is, the MAC is conceptually calculated as:
authKey = DerivedKey(secret_key, "authenticate") HMAC-SHA1(authKey, IV + secret_key)where derived key is an HMacSHA1, possibly repeated multiple times. (See
CryptoHelper.computeDerivedKey(SecretKey, int, String)
for details.)
Perceived Benefits: There are certain cases where if an attacker is able to change the IV. When one uses a authenticity key that is derived from the "master" key, it also makes it possible to know when the incorrect key was attempted to be used to decrypt the ciphertext.
NOTE: The purpose of this MAC (which is always computed by the
ESAPI reference model implementing Encryptor
) is to ensure the
authenticity of the IV and ciphertext. Among other things, this prevents
an adversary from substituting the IV with one of their own choosing.
Because we don't know whether or not the recipient of this CipherText
object will want to validate the authenticity or not, the reference
implementation of Encryptor
always computes it and includes it.
The recipient of the ciphertext can then choose whether or not to validate
it.
authKey
- The secret key that is used for proving authenticity of
the IV and ciphertext. This key should be derived from
the SecretKey
passed to the
Encryptor.encrypt(javax.crypto.SecretKey, PlainText)
and
Encryptor.decrypt(javax.crypto.SecretKey, CipherText)
methods or the "master" key when those corresponding
encrypt / decrypt methods are used. This authenticity key
should be the same length and for the same cipher algorithm
as this SecretKey
. The method
CryptoHelper.computeDerivedKey(SecretKey, int, String)
is a secure way to produce this derived key.public boolean validateMAC(SecretKey authKey)
authKey
- The secret key that is used for proving authenticity of
the IV and ciphertext. This key should be derived from
the SecretKey
passed to the
Encryptor.encrypt(javax.crypto.SecretKey, PlainText)
and
Encryptor.decrypt(javax.crypto.SecretKey, CipherText)
methods or the "master" key when those corresponding
encrypt / decrypt methods are used. This authenticity key
should be the same length and for the same cipher algorithm
as this SecretKey
. The method
CryptoHelper.computeDerivedKey(SecretKey, int, String)
is a secure way to produce this derived key.public byte[] asPortableSerializedByteArray() throws EncryptionException
CipherText
object as a portable (i.e., network byte
ordered) serialized byte array. Note this is not the same as
returning a serialized object using Java serialization. Instead this
is a representation that all ESAPI implementations will use to pass
ciphertext between different programming language implementations.EncryptionException
public void setCiphertext(byte[] ciphertext) throws EncryptionException
ciphertext
- The raw ciphertext.EncryptionException
- Thrown if the MAC has already been computed
via computeAndStoreMAC(SecretKey)
.public void setIVandCiphertext(byte[] iv, byte[] ciphertext) throws EncryptionException
iv
- The initialization vector.ciphertext
- The raw ciphertext.EncryptionException
public int getKDFVersion()
public void setKDFVersion(int vers)
public KeyDerivationFunction.PRF_ALGORITHMS getKDF_PRF()
public void setKDF_PRF(int prfSelection)
public long getEncryptionTimestamp()
public byte[] getSeparateMAC()
computeAndStoreMAC(SecretKey authKey)
method.null
if one is not used.public String toString()
toString()
method.protected boolean canEqual(Object other)
See
public int getKDFInfo()
Copyright © 2022 The Open Web Application Security Project (OWASP). All rights reserved.