iaik.asn1

Class UTF8String

java.lang.Object

iaik.asn1.ASN1Object

iaik.asn1.ASN1String

iaik.asn1.UTF8String

All Implemented Interfaces:

java.lang.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 3629.

RFC 2279, RFC 3629 give an algorithm for transforming UCS multi octet characters into UTF-8 octet sequences. This class can be used for UTF-8 encoding 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 having two one (1) bits in its highest position 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 having three (1) bits in its highest position according to 1110xxxx 10xxxxxx 10xxxxxx, where x denote the bits of the given character to be inserted from the right.
• Characters sequences in the range of 0x0001 0x0000 to 0x0010 0xFFFF are encoded as four octets having four (1) bits in its highest position according to 11110xxx 10xxxxxx 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.
(*) Four octets will be required only for encoding supplementary Unicode characters represented as surrogate pairs (H,L) in the range of (U+D800, U+DC00) to (U+DBFF, U+DFFF). These means that the encoding of a supplementary character requires a two-character pair input to be encoded to four octets.

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 29

See Also:

ASN1Object, ASN

Field Summary

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

Constructors

Modifier	Constructor and Description
protected	UTF8String() Creates an empty UTF8String.
	UTF8String(java.lang.String value) Creates a new ASN.1 UTF8String object for the given String value.

Method Summary

Methods

Modifier and Type	Method and Description
static char[]	getCharsFromUTF8Encoding(byte[] enc) Decodes an UTF-8 encoded byte array and returns the result as char array.
static char[]	getCharsFromUTF8Encoding(byte[] enc, boolean skipInvalidCharacters) Decodes an UTF-8 encoded byte array and returns the result as char array.
static java.lang.String	getRFC2253String(char[] str) Returns a UTF-8 String representation according to RFC 2253.
static java.lang.String	getRFC2253String(char[] str, boolean strictEscaping) Returns a UTF-8 String representation according to RFC 2253.
static java.lang.String	getRFC2253String(java.lang.String str) Returns a UTF-8 String representation according to RFC 2253.
static java.lang.String	getRFC2253String(java.lang.String str, boolean strictEscaping) Returns a UTF-8 String representation according to RFC 2253.
static java.lang.String	getStringFromUTF8Encoding(byte[] enc) Decodes an UTF-8 encoded byte array and returns the result as string.
static java.lang.String	getStringFromUTF8Encoding(byte[] enc, boolean skipInvalidCharacters) Decodes an UTF-8 encoded byte array and returns the result as string.
static byte[]	getUTF8EncodingFromCharArray(char[] str) UTF-8 encodes the given char array.
static byte[]	getUTF8EncodingFromString(java.lang.String str) UTF-8 encodes the given string.
java.lang.Object	getValue() Returns the value of this UTF8String as a String object.
static void	setSkipInvalidEncodedUTF8Characters(boolean skip) Decides whether to skip invalid encoded characters when decoding an UTF-8 encoded byte array to a String (default: false; invalid UTF-8 encoded characters cause a CodingException).
void	setValue(java.lang.Object object) Sets the value of this UTF8String.

Methods inherited from class iaik.asn1.ASN1String

clone, decode, encode, equals, getByteValue, hashCode, setIgnoreConstructedEncodingForSimpleTypes, setIndefiniteLength, toString

Methods inherited from class iaik.asn1.ASN1Object

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

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(java.lang.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

setSkipInvalidEncodedUTF8Characters

public static void setSkipInvalidEncodedUTF8Characters(boolean skip)

Decides whether to skip invalid encoded characters when decoding an UTF-8 encoded byte array to a String (default: false; invalid UTF-8 encoded characters cause a CodingException).
Use this method very carefully. Skipping invalid encoded characters may be useful to be able to get a String representation of a decoded distinguished name (for instance the subjectDN of a certificate) that contains RDNs/AVAs with UTF-8 encoded values. However, generally invalid encoded UTF-8 characters should cause an CodingException (default behavior).

Parameters:

skip - whether to skip invalid encoded characters when decoding an UTF-8 encoded String (default: false; invalid UTF-8 encoded characters cause a CodingException).

getValue

public java.lang.Object getValue()

Returns the value of this UTF8String as a String object.

Specified by:

getValue in class ASN1Object

Returns:

the value of this UTF8String as a String object

setValue

public void setValue(java.lang.Object object)

Sets the value of this UTF8String.

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

Specified by:

setValue in class ASN1Object

Parameters:

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

getUTF8EncodingFromString

public static byte[] getUTF8EncodingFromString(java.lang.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

getCharsFromUTF8Encoding

public static char[] getCharsFromUTF8Encoding(byte[] enc)
                                       throws CodingException

Decodes an UTF-8 encoded byte array and returns the result as char array.

Parameters:

enc - the UTF-8 encoding as byte array

Returns:

the decoded char array

Throws:

CodingException - if an error occurs during the decoding process

getCharsFromUTF8Encoding

public static char[] getCharsFromUTF8Encoding(byte[] enc,
                              boolean skipInvalidCharacters)
                                       throws CodingException

Decodes an UTF-8 encoded byte array and returns the result as char array.

Parameters:

enc - the UTF-8 encoding as byte array

skipInvalidCharacters - whether to skip invalid encoded characters (default: false; invalid characters cause a CodingException)

Returns:

the decoded char array

Throws:

CodingException - if an error occurs during the decoding process

getStringFromUTF8Encoding

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

Decodes an UTF-8 encoded byte array and returns the result as string.

Parameters:

enc - the UTF-8 encoding as byte array

Returns:

the decoded string

Throws:

CodingException - if an error occurs during the decoding process

getStringFromUTF8Encoding

public static java.lang.String getStringFromUTF8Encoding(byte[] enc,
                                         boolean skipInvalidCharacters)
                                                  throws CodingException

Decodes an UTF-8 encoded byte array and returns the result as string.

Parameters:

enc - the UTF-8 encoding as byte array

skipInvalidCharacters - whether to skip invalid encoded characters (default: false; invalid characters cause a CodingException)

Returns:

the decoded string

Throws:

CodingException - if an error occurs during the decoding process

getRFC2253String

public static java.lang.String getRFC2253String(java.lang.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. This implementation is also compliant with the updated standard RFC 4514, which obsoleted RFC 2253.

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 java.lang.String getRFC2253String(java.lang.String str,
                                boolean strictEscaping)
                                         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. This implementation is also compliant with the updated standard RFC 4514, which obsoleted RFC 2253.

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.
• The space character (0x21) only is escaped when appearing at the beginning or the end of the string.
• Any non printable ASCII (< 0x21 or > 0x7e) and any non-ASCII character is escaped by an hexadecimal representation of its UTF-8 encoding if strictEscaping is set to true

Parameters:

str - the string to be represented

strictEscaping - whether to escape non printable ASCII (< 0x21 or > 0x7e) and non-ASCII characters by an hexadecimal representation of their UTF-8 encoding

Returns:

the string representation according to RFC 2253.

Throws:

CodingException - if an coding error occurs

getRFC2253String

public static java.lang.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. This implementation is also compliant with the updated standard RFC 4514, which obsoleted RFC 2253.

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

getRFC2253String

public static java.lang.String getRFC2253String(char[] str,
                                boolean strictEscaping)
                                         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. This implementation is also compliant with the updated standard RFC 4514, which obsoleted RFC 2253.

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.
• The space character (0x21) only is escaped when appearing at the beginning or the end of the string.
• Any non printable ASCII (< 0x21 or > 0x7e) and any non-ASCII character is escaped by an hexadecimal representation of its UTF-8 encoding if strictEscaping is set to true

Parameters:

str - the char array to be represented

strictEscaping - whether to escape non printable ASCII (< 0x21 or > 0x7e) and non-ASCII characters by an hexadecimal representation of their UTF-8 encoding

Returns:

the string representation according to RFC 2253.

Throws:

CodingException - if an coding error occurs