org.owasp.esapi.crypto

Class CipherTextSerializer

java.lang.Object

org.owasp.esapi.crypto.CipherTextSerializer

public class CipherTextSerializer
extends java.lang.Object

Helper class to assist with programming language and platform independent serialization of CipherText objects. The serialization is done in network-byte order which is the same as big-endian byte order.

This serialization scheme is documented in Format of Portable Serialization of org.owasp.esapi.crypto.CipherText Objects. Other serialization schemes may be desirable and could be supported (notably, RFC 5083 - Cryptographic Message Syntax (CMS) Authenticated-Enveloped-Data Content Type, or CMS' predecessor, PKCS#7 (RFC 2315)), but these serialization schemes are by comparison very complicated, and do not have extensive support for the various implementation languages which ESAPI supports. (Perhaps wishful thinking that other ESAPI implementations such as ESAPI for .NET, ESAPI for C, ESAPI for C++, etc. will all support a single, common serialization technique so they could exchange encrypted data.)

Field Summary

Fields

Modifier and Type	Field and Description
private CipherText	cipherText_
static int	cipherTextSerializerVersion
private static Logger	logger
private static long	serialVersionUID

Constructor Summary

Constructors

Constructor and Description
CipherTextSerializer(byte[] cipherTextSerializedBytes) Given byte array in network byte order (i.e., big-endian order), convert it so that a CipherText can be constructed from it.
CipherTextSerializer(CipherText cipherTextObj)

Method Summary

Modifier and Type	Method and Description
CipherText	asCipherText() Return the actual CipherText object.
byte[]	asSerializedByteArray() Return this CipherText object as a specialized, portable serialized byte array.
private byte[]	computeSerialization(int kdfInfo, long timestamp, java.lang.String cipherXform, short keySize, short blockSize, short ivLen, byte[] iv, int ciphertextLen, byte[] rawCiphertext, short macLen, byte[] mac) Take all the individual elements that make of the serialized ciphertext format and put them in order and return them as a byte array.
private CipherText	convertToCipherText(byte[] cipherTextSerializedBytes) Convert the serialized ciphertext byte array to a CipherText object.
private void	debug(java.lang.String msg)
private int	readInt(java.io.ByteArrayInputStream bais)
private long	readLong(java.io.ByteArrayInputStream bais)
private short	readShort(java.io.ByteArrayInputStream bais)
private java.lang.String	readString(java.io.ByteArrayInputStream bais, short sz)
private static boolean	versionIsCompatible(int readKdfVers) Check to see if we can support the KSF version that was extracted from the serialized ciphertext.
private void	writeInt(java.io.ByteArrayOutputStream baos, int i)
private void	writeLong(java.io.ByteArrayOutputStream baos, long l)
private void	writeShort(java.io.ByteArrayOutputStream baos, short s)
private void	writeString(java.io.ByteArrayOutputStream baos, java.lang.String str)

Methods inherited from class java.lang.Object

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

Field Detail

cipherTextSerializerVersion

public static final int cipherTextSerializerVersion

See Also:

Constant Field Values

serialVersionUID

private static final long serialVersionUID

See Also:

Constant Field Values

logger

private static final Logger logger

cipherText_

private CipherText cipherText_

Constructor Detail

CipherTextSerializer

public CipherTextSerializer(CipherText cipherTextObj)

CipherTextSerializer

public CipherTextSerializer(byte[] cipherTextSerializedBytes)
                     throws EncryptionException

Given byte array in network byte order (i.e., big-endian order), convert it so that a CipherText can be constructed from it.

Parameters:

cipherTextSerializedBytes - A serialized CipherText object with the bytes in network byte order.

Throws:

EncryptionException - Thrown if a valid CipherText object cannot be reconstructed from the byte array.

Method Detail

asSerializedByteArray

public byte[] asSerializedByteArray()

Return this CipherText object as a specialized, portable serialized byte array.

Returns:

A serialization of this object. Note that this is not the Java serialization.

asCipherText

public CipherText asCipherText()

Return the actual CipherText object.

Returns:

The CipherText object that we are serializing.

computeSerialization

private byte[] computeSerialization(int kdfInfo,
                                    long timestamp,
                                    java.lang.String cipherXform,
                                    short keySize,
                                    short blockSize,
                                    short ivLen,
                                    byte[] iv,
                                    int ciphertextLen,
                                    byte[] rawCiphertext,
                                    short macLen,
                                    byte[] mac)

Take all the individual elements that make of the serialized ciphertext format and put them in order and return them as a byte array.

Parameters:

kdfInfo - Info about the KDF... which PRF and the KDF version asCipherText().

timestamp - Timestamp when the data was encrypted. Intended to help facilitate key change operations and nothing more. If it is meaningless, then the expectations are just that the recipient should ignore it. Mostly intended when encrypted data is kept long term over a period of many key change operations.

cipherXform - Details of how the ciphertext was encrypted. The format used is the same as used by javax.crypto.Cipher, namely, "cipherAlg/cipherMode/paddingScheme".

keySize - The key size used for encrypting. Intended for cipher algorithms supporting multiple key sizes such as triple DES (DESede) or Blowfish.

blockSize - The cipher block size. Intended to support cipher algorithms that support variable block sizes, such as Rijndael.

ivLen - The length of the IV.

iv - The actual IV (initialization vector) bytes.

ciphertextLen - The length of the raw ciphertext.

rawCiphertext - The actual raw ciphertext itself

macLen - The length of the MAC (message authentication code).

mac - The MAC itself.

Returns:

A byte array representing the serialized ciphertext.

writeString

private void writeString(java.io.ByteArrayOutputStream baos,
                         java.lang.String str)

readString

private java.lang.String readString(java.io.ByteArrayInputStream bais,
                                    short sz)
                             throws java.lang.NullPointerException,
                                    java.io.IOException

Throws:

java.lang.NullPointerException

java.io.IOException

writeShort

private void writeShort(java.io.ByteArrayOutputStream baos,
                        short s)

readShort

private short readShort(java.io.ByteArrayInputStream bais)
                 throws java.lang.NullPointerException,
                        java.lang.IndexOutOfBoundsException

Throws:

java.lang.NullPointerException

java.lang.IndexOutOfBoundsException

writeInt

private void writeInt(java.io.ByteArrayOutputStream baos,
                      int i)

readInt

private int readInt(java.io.ByteArrayInputStream bais)
             throws java.lang.NullPointerException,
                    java.lang.IndexOutOfBoundsException

Throws:

java.lang.NullPointerException

java.lang.IndexOutOfBoundsException

writeLong

private void writeLong(java.io.ByteArrayOutputStream baos,
                       long l)

readLong

private long readLong(java.io.ByteArrayInputStream bais)
               throws java.lang.NullPointerException,
                      java.lang.IndexOutOfBoundsException

Throws:

java.lang.NullPointerException

java.lang.IndexOutOfBoundsException

convertToCipherText

private CipherText convertToCipherText(byte[] cipherTextSerializedBytes)
                                throws EncryptionException

Convert the serialized ciphertext byte array to a CipherText object.

Parameters:

cipherTextSerializedBytes - The serialized ciphertext as a byte array.

Returns:

The corresponding CipherText object.

Throws:

EncryptionException - Thrown if the byte array data is corrupt or there are version mismatches, etc.

versionIsCompatible

private static boolean versionIsCompatible(int readKdfVers)

Check to see if we can support the KSF version that was extracted from the serialized ciphertext. In particular, we assume that if we have a newer version of KDF than we can support it as we assume that we have built in backward compatibility. At this point (ESAPI 2.1.0, KDF version 20130830), all we need to check if the version is either the current version or the previous version as both versions work the same. This checking may get more complicated in the future.

Parameters:

readKdfVers - The version information extracted from the serialized ciphertext.

debug

private void debug(java.lang.String msg)