edu.emory.mathcs.util.security
Class CharStrings

java.lang.Object
  extended byedu.emory.mathcs.util.security.CharStrings

public class CharStrings
extends java.lang.Object

Utility methods to securely manipulate on character arrays. The methods allow to treat the character arrays similarly to strings, yet they ensure that all temporary arrays are zeroed-out before discarding.

Application of this class stems from the fact that String class is not appropriate for holding passwords and other sensitive information. Strings cannot be zeroed-out before unreferencing, thus the content may be dangling in memory for quite a while before it is garbage-collected, and it can stay in the process data block even longer, until it is overwritten. It has been demonstrated that attacker can obtain the data in clear text by forcing the operating system to swap out the application in question, and then by reading the swap file. To minimize the risk, sensitive data should be cleared explicitly as soon as possible. It suggests using mutable character arrays in favor of strings. This class allows to operate on such arrays much like on strings, in particular, it provides methods to securely concatenate them, as well as write them to, and read them from streams in the UTF format.

Version:
1.0
Author:
Dawid Kurzyniec

Method Summary
static void clear(char[] s)
          Zeroes-out the specified character array.
static char[] concat(char[] s1, char[] s2)
          Returns a concatenation of two character arrays.
static boolean equals(char[] s1, char[] s2)
          Compares two character arrays.
static char[] fromUTF(byte[] utfString)
          Recovers a character array out of its UTF-8 encoding.
static char[] fromUTF(byte[] utfString, int off, int len)
          Recovers a character array out of its UTF-8 encoding.
static int getUTFLen(char[] s, int off, int len)
          Returns the number of bytes of an UTF-8 encoding of a portion of the specified character array.
static char[] readUTF(java.io.DataInput in)
          Reads UTF-8 encoded character array from a data input.
static char[] readUTF(java.io.InputStream in)
          Reads UTF-8 encoded character array from an input stream.
static byte[] toUTF(char[] s)
          Converts the specified character array into its UTF-8 encoding.
static byte[] toUTF(char[] s, int off, int len)
          Converts a portion of the specified character array into its UTF-8 encoding.
static int writeUTF(java.io.OutputStream out, char[] s)
          Writes the specified character array to the output stream using UTF-8 encoding.
static int writeUTF(java.io.OutputStream out, char[] s, int off, int len)
          Writes a portion of the specified character array to the output stream using UTF-8 encoding.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

concat

public static char[] concat(char[] s1,
                            char[] s2)
Returns a concatenation of two character arrays.

Parameters:
s1 - first array
s2 - second array
Returns:
new array containing s1 concatenated with s2

equals

public static boolean equals(char[] s1,
                             char[] s2)
Compares two character arrays.

Parameters:
s1 - first array
s2 - second array
Returns:
true if arrays have identical content; false otherwise

clear

public static void clear(char[] s)
Zeroes-out the specified character array.

Parameters:
s - the array to zero-out

writeUTF

public static int writeUTF(java.io.OutputStream out,
                           char[] s)
                    throws java.io.IOException
Writes the specified character array to the output stream using UTF-8 encoding.

Parameters:
out - the output to write to
s - array to write to
Returns:
the number of bytes written
Throws:
java.io.IOException - if I/O error occurs

writeUTF

public static int writeUTF(java.io.OutputStream out,
                           char[] s,
                           int off,
                           int len)
                    throws java.io.IOException
Writes a portion of the specified character array to the output stream using UTF-8 encoding.

Parameters:
out - the output to write to
s - array to write to
off - start offset within s
len - number of characters to write
Returns:
the number of bytes written
Throws:
java.io.IOException - if I/O error occurs

toUTF

public static byte[] toUTF(char[] s)
Converts the specified character array into its UTF-8 encoding.

Parameters:
s - the array to encode
Returns:
UTF-8 encoded array

toUTF

public static byte[] toUTF(char[] s,
                           int off,
                           int len)
Converts a portion of the specified character array into its UTF-8 encoding.

Parameters:
s - the array to encode
off - the start offset within s
len - the number of characters to encode
Returns:
UTF-8 encoded array

getUTFLen

public static int getUTFLen(char[] s,
                            int off,
                            int len)
Returns the number of bytes of an UTF-8 encoding of a portion of the specified character array.

Parameters:
s - the character array
off - the start offset within s
len - the number of characters to include
Returns:
the number of bytes of an UTF-8 encoding

readUTF

public static final char[] readUTF(java.io.InputStream in)
                            throws java.io.IOException
Reads UTF-8 encoded character array from an input stream.

Parameters:
in - the input stream to read from
Returns:
decoded character array
Throws:
java.io.IOException - if I/O error occurs

readUTF

public static final char[] readUTF(java.io.DataInput in)
                            throws java.io.IOException
Reads UTF-8 encoded character array from a data input.

Parameters:
in - the data input to read from
Returns:
decoded character array
Throws:
java.io.IOException - if I/O error occurs

fromUTF

public static final char[] fromUTF(byte[] utfString)
                            throws java.io.IOException
Recovers a character array out of its UTF-8 encoding.

Parameters:
utfString - containing UTF-8-encoded character array
Returns:
the decoded character array
Throws:
java.io.IOException - if I/O error occurs

fromUTF

public static final char[] fromUTF(byte[] utfString,
                                   int off,
                                   int len)
                            throws java.io.IOException
Recovers a character array out of its UTF-8 encoding.

Parameters:
utfString - array containing UTF-8-encoded character array
off - start offset within utfString
len - number of bytes to include
Returns:
the decoded character array
Throws:
java.io.IOException - if I/O error occurs