iaik.asn1
Class UTF8String

java.lang.Object
  |
  +--iaik.asn1.ASN1Object
        |
        +--iaik.asn1.ASN1String
              |
              +--iaik.asn1.UTF8String

All Implemented Interfaces:

Cloneable

public class UTF8String

extends ASN1String

This class implements the ASN.1 character string type "UTF8String". UTF8String is a simple ASN.1 string type identified by the UNIVERSAL TAG number 12.

UTF-8 (UCS transformation format 8) is an encoding format that has been developed for handling UCS-2/UCS-4 multi-octet character sets by applications that operate on 7, 8 bit characters. UTF-8 is specified by ISO 10646 in RFC 2279.

RFC 2279 gives an algorithm for transforming UCS-4/UCS-2 multi octet characters into UTF-8 octet sequences. This class can be used for UTF-8 encoding UCS-2/Unicode character strings according to the following rules:

• Characters in the range of 0x0000 to 0x007F (US-ASCII) are encoded as a single octet having a zero (0) bit in its highest position: 0xxxxxxx.
• Characters in the range of 0x0080 to 0x07EF are encoded as two octets according to 110xxxxx 10xxxxxx, where x denote the bits of the given character to be inserted from the right
• Characters in the range of 0x0800 to 0xFFFF are encoded as three octets according to 1110xxxx 10xxxxxx 10xxxxxx, where x denote the bits of the given character to be inserted from the right

Characters out of range will raise a CodingException.

When creating a new UTF8String object the value to be represented has to be supplied as Java String type:

 String s = ...;
 UTF8String UTF8String = new UTF8String(s);
 

When calling the getValue method for getting the inherent string value from an ASN.1 UTF8String instance, a Java object of type String is returned:

 String s = (String)UTF8String.getValue();
 

DER en/decoding generally is done by means of the several methods of the DerCoder class; decoding alternatively may be performed by using the DerInputStream utility.

Version:

File Revision 23

See Also:

ASN1Object, ASN

Fields inherited from class iaik.asn1.ASN1String

value

Fields inherited from class iaik.asn1.ASN1Object

asnType, constructed, encode_listener, indefinite_length, isStringType, stream_mode

Constructor Summary

protected	UTF8String() Creates an empty UTF8String.
	UTF8String(String value) Creates a new ASN.1 UTF8String object for the given String value.

Method Summary

static String	getRFC2253String(char[] str) Returns a UTF-8 String representation according to RFC 2253.
static String	getRFC2253String(String str) Returns a UTF-8 String representation according to RFC 2253.
static String	getStringFromUTF8Encoding(byte[] enc) Decodes the string from an UTF-8 encoded byte array.
static byte[]	getUTF8EncodingFromCharArray(char[] str) UTF-8 encodes the given char array.
static byte[]	getUTF8EncodingFromString(String str) UTF-8 encodes the given string.
Object	getValue() Returns the value of this UTF8String as a String object.
void	setValue(Object object) Sets the value of this UTF8String.

Methods inherited from class iaik.asn1.ASN1String

clone, decode, encode, equals, hashCode, toString

Methods inherited from class iaik.asn1.ASN1Object

addComponent, addEncodeListener, countComponents, encodeObject, getAsnType, getComponentAt, indefiniteLength, isA, isConstructed, isStringType, setIndefiniteLength

Methods inherited from class java.lang.Object

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

Constructor Detail

UTF8String

protected UTF8String()

Creates an empty UTF8String.

UTF8String

public UTF8String(String value)

Creates a new ASN.1 UTF8String object for the given String value.

Parameters:

value - the String value this UTF8String object should be initialized with

Method Detail

getValue

public Object getValue()

Returns the value of this UTF8String as a String object.

Overrides:

getValue in class ASN1Object

Returns:

the value of this UTF8String as a String object

setValue

public void setValue(Object object)

Sets the value of this UTF8String.

The supplied value has to be a Java object of type String.

Overrides:

setValue in class ASN1Object

Parameters:

object - the Java String value to be set for this UTF8String

getUTF8EncodingFromString

public static byte[] getUTF8EncodingFromString(String str)
                                        throws CodingException

UTF-8 encodes the given string.

Parameters:

str - the string to be encoded

Returns:

the UTF-8 encoding as byte array

Throws:

CodingException - if an coding error occurs

getUTF8EncodingFromCharArray

public static byte[] getUTF8EncodingFromCharArray(char[] str)
                                           throws CodingException

UTF-8 encodes the given char array.

Parameters:

str - the char array to be encoded

Returns:

the UTF-8 encoding as byte array

Throws:

CodingException - if an coding error occurs

getStringFromUTF8Encoding

public static String getStringFromUTF8Encoding(byte[] enc)
                                        throws CodingException

Decodes the string from an UTF-8 encoded byte array. This method is static not private to provide access for the DerInputStream class.

Parameters:

enc - the UTF-8 encoding as byte array

Returns:

the decoded string

Throws:

CodingException - if an error occurs during the decoding process

getRFC2253String

public static String getRFC2253String(String str)
                               throws CodingException

Returns a UTF-8 String representation according to RFC 2253.

RFC 2253 specifies a string representation of Distinguished Names as used for LDAP lookups.

The string representation returned by this method is based on the algorithm given in section 2.4 of RFC 2253 thereby applying the following escaping mechanisms:

• A space or "#" character at the beginning of the string is escaped.
• A space at the end of the string is escaped.
• Any of the characters ",", "+", """, "\", "<", ">" or ";" is escaped.
• Any non printable ASCII (< 0x21 or > 0x7e) and any non-ASCII character is escaped by an hexadecimal representation of its UTF-8 encoding. The space character (0x21) only is escaped when appearing at the beginning or the end of the string.

Parameters:

str - the string to be represented

Returns:

the string representation according to RFC 2253.

Throws:

CodingException - if an coding error occurs

getRFC2253String

public static String getRFC2253String(char[] str)
                               throws CodingException

Returns a UTF-8 String representation according to RFC 2253.

RFC 2253 specifies a string representation of Distinguished Names as used for LDAP lookups.

The string representation returned by this method is based on the algorithm given in section 2.4 of RFC 2253 thereby applying the following escaping mechanisms:

• A space or "#" character at the beginning of the string is escaped.
• A space at the end of the string is escaped.
• Any of the characters ",", "+", """, "\", "<", ">" or ";" is escaped.
• Any non printable ASCII (< 0x21 or > 0x7e) and any non-ASCII character is escaped by an hexadecimal representation of its UTF-8 encoding. The space character (0x21) only is escaped when appearing at the beginning or the end of the string.

Parameters:

str - the char array to be represented

Returns:

the string representation according to RFC 2253.

Throws:

CodingException - if an coding error occurs