com.entrust.toolkit.util

Class SecureByteArray

java.lang.Object

com.entrust.toolkit.util.SecureByteArray

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

public class SecureByteArray
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable

Represents sensitive binary data in an application.

Application programmers do not usually have to consider how to destroy a SecureByteArray passed within the Toolkit — most methods automatically wipe, or destroy, the SecureByteArray object once it is no longer needed. This class includes a wipe() method to destroy SecureByteArray objects that are not dealt with automatically.

The data in an instance of this class can be protected by an exclusive OR operation, xor, or by encryption. In the case of xor, the data is combined, using the exclusive OR operation, with a randomly generated value before it is committed to memory. In the case of encryption, the data is encrypted using a symmetric cipher before it is committed to memory. Data can be protected depending on its sensitivity:

• BASE — no protection
• MEDIUM — perform the xor operation on the data
• HIGH — encrypt/decrypt the data

The default sensitivity is BASE.

Note

Use of this class with sensitivities of MEDIUM or HIGH requires that the Entrust cryptographic service provider (CSP) be installed. The Entrust CSP is automatically installed when a User logs into the Toolkit. Using these sensitivities without logging into the Toolkit requires that the Entrust CSP be installed manually prior to instantiation of this class, otherwise a SecurityException will result. The Initializer class can be used to manually install the Entrust CSP.

Instances of this class can only be serialized if the sensitivity is set to BASE or MEDIUM.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static int	BASE Base sensitivity - do not protect the data
static int	HIGH High sensitivity - encrypt the data
static int	MEDIUM Medium sensitivity - xor the data

Constructor Summary

Constructors

Constructor and Description
SecureByteArray(byte[] ba) Creates a new SecureByteArray from the given byte array.
SecureByteArray(byte[] ba, int sensitivity) Creates a new SecureByteArray from the given byte array and using the specified sensitivity.
SecureByteArray(java.io.InputStream is) Creates a new SecureByteArray by reading the sensitive data from an InputStream.
SecureByteArray(java.io.InputStream is, int sensitivity) Creates a new SecureByteArray by reading the sensitive data from an InputStream.
SecureByteArray(SecureByteArray sba) The copy constructor — used to create a new instance of SecureByteArray that is identical to the specified SecureByteArray.

Method Summary

Modifier and Type	Method and Description
java.lang.Object	clone() Returns a clone of the SecureByteArray.
boolean	equals(java.lang.Object obj) Indicates whether some other object is "equal to" this one.
byte[]	getByteArray() Returns a copy of the sensitive data as a byte array.
int	getSensitivity() Returns the sensitivity for this SecureByteArray object.
byte[]	toByteArray() Returns a copy of the sensitive data as a byte array.
void	wipe() Clears the sensitive data held as a SecureByteArray.

Methods inherited from class java.lang.Object

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

Field Detail

BASE

public static final int BASE

Base sensitivity - do not protect the data

See Also:

Constant Field Values

MEDIUM

public static final int MEDIUM

Medium sensitivity - xor the data

See Also:

Constant Field Values

HIGH

public static final int HIGH

High sensitivity - encrypt the data

See Also:

Constant Field Values

Constructor Detail

SecureByteArray

public SecureByteArray(byte[] ba)

Creates a new SecureByteArray from the given byte array.

After the SecureByteArray has been initialized, the byte array passed in as an argument is wiped from memory. The sensitivity is set to the default value — BASE.

Parameters:

ba - the byte array holding the sensitive data

Throws:

java.lang.IllegalArgumentException - thrown if the byte array is null

java.lang.SecurityException - thrown when MEDIUM> or HIGH sensitivity is used and the Entrust cryptographic service provider is not installed

SecureByteArray

public SecureByteArray(byte[] ba,
                       int sensitivity)

Creates a new SecureByteArray from the given byte array and using the specified sensitivity.

After the SecureByteArray has been initialized, the byte array passed in as an argument is wiped from memory.

Parameters:

ba - the byte array holding the sensitive data

sensitivity - sensitivity of the data

Throws:

java.lang.IllegalArgumentException - thrown if the byte array is null

java.lang.SecurityException - thrown when MEDIUM> or HIGH sensitivity is used and the Entrust cryptographic service provider is not installed

SecureByteArray

public SecureByteArray(java.io.InputStream is)
                throws java.io.IOException

Creates a new SecureByteArray by reading the sensitive data from an InputStream.

The sensitivity is set to the default value — BASE.

Warning

The InputStream might use buffers internally that might not be cleared following use. If this is the case, you have no means of destroying this data.

Parameters:

is - the input stream from which the sensitive data will be read

Throws:

java.io.IOException - thrown if a problem occurs while reading the InputStream

java.lang.IllegalArgumentException - thrown if the input stream is null

java.lang.SecurityException - thrown when MEDIUM> or HIGH sensitivity is used and the Entrust cryptographic service provider is not installed

SecureByteArray

public SecureByteArray(java.io.InputStream is,
                       int sensitivity)
                throws java.io.IOException

Creates a new SecureByteArray by reading the sensitive data from an InputStream.

Warning

The InputStream might use buffers internally that might not be cleared following use. If this is the case, you have no means of destroying this data.

Parameters:

is - the input stream from which the sensitive data will be read

sensitivity - sensitivity of the data

Throws:

java.io.IOException - thrown if a problem occurs while reading the InputStream

java.lang.IllegalArgumentException - thrown if the input stream is null

java.lang.SecurityException - thrown when MEDIUM> or HIGH sensitivity is used and the Entrust cryptographic service provider is not installed

SecureByteArray

public SecureByteArray(SecureByteArray sba)

The copy constructor — used to create a new instance of SecureByteArray that is identical to the specified SecureByteArray.

Note

This constructor does not destroy the contents of its SecureByteArray argument. If necessary, you can do this by calling the wipe method on the argument.

Parameters:

sba - the secure byte array to be copied

Throws:

java.lang.IllegalArgumentException - thrown if the secure byte array is null

java.lang.SecurityException - thrown when MEDIUM> or HIGH sensitivity is used and the Entrust cryptographic service provider is not installed

Method Detail

clone

public java.lang.Object clone()

Returns a clone of the SecureByteArray.

Overrides:

clone in class java.lang.Object

Returns:

a clone of this instance

getSensitivity

public int getSensitivity()

Returns the sensitivity for this SecureByteArray object.

Returns:

the sensitivity

getByteArray

public byte[] getByteArray()

Returns a copy of the sensitive data as a byte array.

Note

Ensure that the memory held by the byte array is cleared after use.

Returns:

a copy of the sensitive data

Throws:

java.lang.SecurityException - thrown when HIGH sensitivity is used and the Entrust cryptographic service provider is not installed

toByteArray

public byte[] toByteArray()

Returns a copy of the sensitive data as a byte array.

Note

Ensure that the memory held by the byte array is cleared after use.

Returns:

a copy of the sensitive data

Throws:

java.lang.SecurityException - thrown when HIGH sensitivity is used and the Entrust cryptographic service provider is not installed

Since:

7.1sp1

equals

public boolean equals(java.lang.Object obj)

Indicates whether some other object is "equal to" this one.

Two SecureByteArray objects are equal only if the sensitive data (byte data) they represent are equal.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the reference object with which to compare

Returns:

true if the objects are "equal"; false otherwise

Since:

7.0

wipe

public void wipe()

Clears the sensitive data held as a SecureByteArray.

This method overwrites memory held by the sensitive data with bytes 0x00 and then sets the sensitive data to equal a new byte array of length zero. It also sets the sensitivity to -1, so that there is no way to tell how the data was originally protected. Use this method rather than finalize() to clear memory.