com.entrust.toolkit.util

Class SecureStringBuffer

java.lang.Object

com.entrust.toolkit.util.SecureStringBuffer

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:

AuthorizationCode

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

Used to represent sensitive data in an application — a user's password for example.

Application programmers do not usually have to consider how to destroy a SecureStringBuffer passed within the Toolkit — most methods automatically wipe, or destroy, the SecureStringBuffer object once it is no longer needed. However, this class includes a wipe method to destroy SecureStringBuffer 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 obfuscate the data
static int	HIGH High sensitivity - encrypt the data
static int	MEDIUM Medium sensitivity - xor the data

Constructor Summary

Constructors

Constructor and Description
SecureStringBuffer(char[] ca) Creates a new SecureStringBuffer from the given character array.
SecureStringBuffer(char[] ca, int sensitivity) Creates a new SecureStringBuffer from the given character array and using the specified sensitivity.
SecureStringBuffer(java.io.InputStream is) Deprecated. use SecureByteArray instead; since JTK 6.1
SecureStringBuffer(SecureStringBuffer ssb) Copy constructor — used to create a new instance of SecureStringBuffer that is identical to the specified SecureStringBuffer.
SecureStringBuffer(java.lang.String s) Deprecated. Pass sensitive data in as a StringBuffer or as a char []. Using a String creates a copy of the data in memory that cannot be destroyed. Since JTK 6.1.
SecureStringBuffer(java.lang.StringBuffer sb) Creates a SecureStringBuffer from the given StringBuffer.
SecureStringBuffer(java.lang.StringBuffer sb, int sensitivity) Creates a SecureStringBuffer from the given StringBuffer and specified sensitivity.
SecureStringBuffer(java.lang.StringBuilder sb) Creates a SecureStringBuffer from the given StringBuilder.
SecureStringBuffer(java.lang.StringBuilder sb, int sensitivity) Creates a SecureStringBuffer from the given StringBuilder and specified sensitivity.

Method Summary

Modifier and Type	Method and Description
java.lang.Object	clone() Returns a clone of the SecureStringBuffer.
boolean	equals(java.lang.Object obj) Indicates whether some other object is "equal to" this one.
int	getSensitivity() Returns the sensitivity for this SecureStringBuffer object.
java.lang.StringBuffer	getStringBuffer() Returns a copy of the sensitive data as a StringBuffer.
byte[]	toASCIIByteArray() Deprecated. use toUSASCIIByteArray() instead; since 7.0patch
byte[]	toByteArray() Returns a copy of the sensitive data as a byte array, using the default character encoding.
byte[]	toByteArray(java.lang.String enc) Returns a copy of the sensitive data as a byte array, using the specified character encoding.
char[]	toCharArray() Returns a copy of the sensitive data as a character array.
byte[]	toISO88591ByteArray() Returns a copy of the sensitive data as a byte array, using the ISO-8859-1 character encoding.
SecureByteArray	toSecureByteArray() Securley transforms the SecureStringBuffer to a SecreByteArray using the default character encoding.
SecureByteArray	toSecureByteArray(java.lang.String enc) Securley transforms the SecureStringBuffer to a SecreByteArray using the specified character encoding.
java.lang.String	toString() Returns a copy of the sensitive data as a String.
java.lang.StringBuffer	toStringBuffer() Returns a copy of the sensitive data as a StringBuffer.
byte[]	toUSASCIIByteArray() Returns a copy of the sensitive data as a byte array, using the US-ASCII character encoding.
byte[]	toUTF8ByteArray() Returns a copy of the sensitive data as a byte array, using the UTF-8 character encoding.
void	wipe() Clears the sensitive data held as a SecureStringBuffer.

Methods inherited from class java.lang.Object

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

Field Detail

BASE

public static final int BASE

Base sensitivity - do not obfuscate 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

SecureStringBuffer

public SecureStringBuffer(char[] ca)

Creates a new SecureStringBuffer from the given character array.

After the SecureStringBuffer has been initialized, the character array passed in as an argument is wiped from memory. Because this constructor accepts a character array and not a* String, it is possible to clear the memory. The sensitivity is set to the default value — BASE.

Parameters:

ca - the character array that contains the sensitive data

Throws:

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

SecureStringBuffer

public SecureStringBuffer(char[] ca,
                          int sensitivity)

Creates a new SecureStringBuffer from the given character array and using the specified sensitivity.

After the SecureStringBuffer has been initialized, the character array passed in as an argument is wiped from memory. Because this constructor accepts a character array and not a String, it is possible to clear the memory.

Parameters:

ca - the character array that contains the sensitive data

sensitivity - sensitivity of the data

Throws:

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

SecureStringBuffer

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

Deprecated. use SecureByteArray instead; since JTK 6.1

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

The sensitivity is set to the default value — BASE.

Warning

Data passed as an InputStream to this constructor will be converted to characters using the String constructor. This creates a copy of the data in memory that cannot be destryed.

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

SecureStringBuffer

public SecureStringBuffer(SecureStringBuffer ssb)

Copy constructor — used to create a new instance of SecureStringBuffer that is identical to the specified SecureStringBuffer.

Note

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

Parameters:

ssb - the secure string buffer to be copied

Throws:

java.lang.IllegalArgumentException - thrown if the secure string buffer is null

SecureStringBuffer

public SecureStringBuffer(java.lang.StringBuffer sb)

Creates a SecureStringBuffer from the given StringBuffer.

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

Parameters:

sb - the string buffer that contains the sensitive data

Throws:

java.lang.IllegalArgumentException - thrown if the string buffer is null

SecureStringBuffer

public SecureStringBuffer(java.lang.StringBuilder sb)

Creates a SecureStringBuffer from the given StringBuilder.

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

Parameters:

sb - the string builder that contains the sensitive data

Throws:

java.lang.IllegalArgumentException - thrown if the string builder is null

SecureStringBuffer

public SecureStringBuffer(java.lang.StringBuffer sb,
                          int sensitivity)

Creates a SecureStringBuffer from the given StringBuffer and specified sensitivity.

After the SecureStringBuffer has been initialized, the StringBuffer passed in as an argument is wiped from memory.

Parameters:

sb - the string buffer that contains the sensitive data

sensitivity - sensitivity of the data

Throws:

java.lang.IllegalArgumentException - thrown if the string buffer is null

SecureStringBuffer

public SecureStringBuffer(java.lang.StringBuilder sb,
                          int sensitivity)

Creates a SecureStringBuffer from the given StringBuilder and specified sensitivity.

After the SecureStringBuffer has been initialized, the StringBuilder passed in as an argument is wiped from memory.

Parameters:

sb - the string builder that contains the sensitive data

sensitivity - sensitivity of the data

Throws:

java.lang.IllegalArgumentException - thrown if the string buffer is null

SecureStringBuffer

public SecureStringBuffer(java.lang.String s)

Deprecated. Pass sensitive data in as a StringBuffer or as a char []. Using a String creates a copy of the data in memory that cannot be destroyed. Since JTK 6.1.

Creates a SecureStringBuffer instance taking a String as an argument.

Warning

Data passed as a String to this constructor cannot be destroyed using the wipe() method. The original String continues to represent sensitive data after calling this constructor.

Parameters:

s - the string that contains the sensitive data

Method Detail

clone

public java.lang.Object clone()

Returns a clone of the SecureStringBuffer.

Overrides:

clone in class java.lang.Object

Returns:

a clone of this instance

getSensitivity

public int getSensitivity()

Returns the sensitivity for this SecureStringBuffer object.

Returns:

the sensitivity

getStringBuffer

public java.lang.StringBuffer getStringBuffer()

Returns a copy of the sensitive data as a StringBuffer.

Note

Ensure that the memory held by the StringBuffer is cleared after use.

Returns:

a copy of the sensitive data

toStringBuffer

public java.lang.StringBuffer toStringBuffer()

Returns a copy of the sensitive data as a StringBuffer.

Note

Ensure that the memory held by the StringBuffer is cleared after use.

Returns:

a copy of the sensitive data

Since:

7.1sp1

toByteArray

public byte[] toByteArray()

Returns a copy of the sensitive data as a byte array, using the default character encoding.

Note

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

Returns:

a default character encoded byte representation of the sensitive data

toASCIIByteArray

public byte[] toASCIIByteArray()

Deprecated. use toUSASCIIByteArray() instead; since 7.0patch

Returns a copy of the sensitive data as a byte array, using the an ASCII compatible character encoding.

Note

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

Returns:

an ASCII compatible character encoded byte representation of the sensitive data

Since:

7.0

toUTF8ByteArray

public byte[] toUTF8ByteArray()

Returns a copy of the sensitive data as a byte array, using the UTF-8 character encoding.

Note

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

Returns:

a UTF-8 character encoded byte representation of the sensitive data

Since:

7.0patch

toUSASCIIByteArray

public byte[] toUSASCIIByteArray()

Returns a copy of the sensitive data as a byte array, using the US-ASCII character encoding.

Sun states that any implementation of the Java 2 platform, Standard Edition, v. 1.3 or higher is required to support this encoding.

Note

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

Returns:

a US-ASCI character encoded byte representation of the sensitive data

Since:

7.0patch

toISO88591ByteArray

public byte[] toISO88591ByteArray()

Returns a copy of the sensitive data as a byte array, using the ISO-8859-1 character encoding.

Sun states that any implementation of the Java 2 platform, Standard Edition, v. 1.3 or higher is required to support this encoding.

Note

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

Returns:

an ISO-8859-1 character encoded byte representation of the sensitive data

Since:

7.0patch

toByteArray

public byte[] toByteArray(java.lang.String enc)
                   throws java.io.UnsupportedEncodingException

Returns a copy of the sensitive data as a byte array, using the specified character encoding.

Note

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

Parameters:

enc - the name of the character encoding

Returns:

a character encoded byte representation of the sensitive data

Throws:

java.io.UnsupportedEncodingException - thrown if the character encoding is not supported

toCharArray

public char[] toCharArray()

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

Note

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

Returns:

a copy of the sensitive data

toSecureByteArray

public SecureByteArray toSecureByteArray()

Securley transforms the SecureStringBuffer to a SecreByteArray using the default character encoding.

The method performs the transformation from SecureStringBuffer to SecreByteArray by creating a copy of the data.

Note

The original SecureStringBuffer is not wiped following this call, leaving two secure copies of the data in memory. Use the wipe() method if you want to clear the original SecureStringBuffer from memory.

Returns:

a default character encoded secure byte representation of the sensitive data

toSecureByteArray

public SecureByteArray toSecureByteArray(java.lang.String enc)
                                  throws java.io.UnsupportedEncodingException

Securley transforms the SecureStringBuffer to a SecreByteArray using the specified character encoding.

The method performs the transformation from SecureStringBuffer to SecreByteArray by creating a copy of the data.

Note

The original SecureStringBuffer is not wiped following this call, leaving two secure copies of the data in memory. Use the wipe() method if you want to clear the original SecureStringBuffer from memory.

Parameters:

enc - the name of the character encoding

Returns:

a character encoded secure byte representation of the sensitive data

Throws:

java.io.UnsupportedEncodingException - thrown if the character encoding is not supported

toString

public java.lang.String toString()

Returns a copy of the sensitive data as a String.

Warning

By retrieving the sensitive data as a String, a copy of the data, which cannot be destroyed, is placed in memory. The String continues to represent the sensitive data until it is garbage-collected and overwritten by other data.

Overrides:

toString in class java.lang.Object

Returns:

a copy of the sensitive data

equals

public boolean equals(java.lang.Object obj)

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

Two SecureStringBuffer objects are equal only if the sensitive data (textbyte arrays) 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 SecureStringBuffer.

Use this method rather than the finalize method to clear the memory.