iaik.asn1.structures
Class AVA

java.lang.Object
  |
  +--iaik.asn1.structures.AVA

All Implemented Interfaces:

ASN1Type

public class AVA

extends Object

implements ASN1Type

This class implements the ASN.1 type AttributeValueAssertion. An AttributeValueAssertion gives one component of a RelativeDistinguishedName structure:

 RelativeDistinguishedName ::= SET OF AttributeValueAssertion

 AttributeValueAssertion ::= SEQUENCE {
  AttributeType    OBJECT IDENTIFIER,
  AttributeValue   ANY
 }
 

When creating a new AVA object, the attribute type has to be specified as ObjectID, and the value has to be supplied as a Java object of matching type (i.e. compatible to the type expected by the setValue method of the corresponding ASN.1 type), e.g.:

 AVA ava = new AVA(ObjectID.commonName, "John Doe");
 

The example above will create an AVA for the X.500 attribute type commonName. Since, per default, the commonName value will be encoded as PrintableString, the value has to be specified as java.lang.String object since the setValue method of class PrintableString expects a String object. Alternatively immediately a PrintableString ASN1Object may be supplied (and will be encoded unchanged):

 AVA ava = new AVA(ObjectID.commonName, new PrintableString("John Doe"));
 

When DER encoding an AVA object where the value is not immediately given as ASN1Object, the inherent value per default will be encoded as ASN.1 character string of type PrintableString, except for the X.500 attribute type uniqueIdentifier and the PKCS#9 attribute type emailAddress which per default will be encoded as BIT_STRING, and IA5String, respectively.

An application wishing to use another encoding type than PrintableString for encoding some specific attribute value, may register the ASN.1 encoding type in mind by means of the static defineEncoding(ObjectID type, ASN encodingType) method, e.g.:

 AVA.defineEncoding(ObjectID.title, ASN.VisibleString);
 

will enforce that any AVA value of X.500 attribute type title will be encoded as VisibleString instead of PrintableString}.

If you want to use a different encoding type only for one specific AVA object you may specify the particular encoding type when creating a new AVA object; e.g.:

 AVA ava = new AVA(ObjectID.commonName, "John Doe", ASN.IA5String);
 

will enforce that the value of this specific AVA object will be encoded as IA5String.

Special care has to taken when using an attribute of type type uniqueIdentifier. Since the uniqueIdentifier value has to be encoded as BIT_STRING, per default the value has to be specified as byte array as expected by the setValue method of the BIT_STRING class:

 byte[] value = ...;
 AVA ava = new AVA(ObjectID.uniqueIdentifier, value);
 

However, since some certificates use a DER encoded PrintableString as value for the BIT_STRING uniqueIdentifier alternatively a string value may be supplied:

 String s = ...;
 AVA ava = new AVA(ObjectID.uniqueIdentifier, s);
 

In such cases, the AVA will encode the uniqueIdentifier value as BIT_STRING having a DER encoded PrintableString as its value.

Version:

File Revision 34

Constructor Summary

AVA(ASN1Object obj)
Creates an AttributeValueAssertion from an ASN1Object.

AVA(ObjectID type, Object value)
Creates a new AttributeValueAssertion from a type and a value.

AVA(ObjectID type, Object value, ASN encodingType)
Creates a new AttributeValueAssertion from a type and a value to be encoded using the given encoding type.

Method Summary

void	decode(ASN1Object obj) Decodes an AVA from the given ASN1Object.
static void	defineEncoding(ObjectID type, ASN encodingType) Defines the ASN.1 encoding for a specified Attribute type.
boolean	equals(Object obj) Compares two AttributeValueAssertions.
ASN1Object	getASN1Value() Returns an ASN.1 representation of the value of this AttributeValueAssertion.
static ASN	getDefaultEncoding() Gets the default encoding.
static ASN	getEncoding(ObjectID type) Gets the encoding type associated with the given attribute type.
static ASN	getNonPrintableDefaultEncoding() Gets the encoding that is used if a String attribute value has non printable chars.
String	getRFC2253String() Returns a string representation of this AVA according to RFC 2253.
ObjectID	getType() Returns the type of this AttributeValueAssertion.
Object	getValue() Returns the value of this AttributeValueAssertion.
int	hashCode() Returns the hashcode for this AttributeValueAssertion.
static void	setDefaultEncoding(ASN encodingType) Sets the default encoding to be used.
static void	setNonPrintableDefaultEncoding(ASN encodingType) Sets the encoding that shall be used if a String attribute value has non printable chars.
ASN1Object	toASN1Object() Returns this AttributeValueAssertion as an ASN1Object.
String	toString() Returns a string that represents the contents of this RDN.
String	toString(boolean detailed) Returns a string that represents the contents of this AVA.

Methods inherited from class java.lang.Object

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

Constructor Detail

AVA

public AVA(ObjectID type,
           Object value)
    throws IllegalArgumentException

Creates a new AttributeValueAssertion from a type and a value. The value has to be supplied as a Java object of matching type (i.e. compatible to the type expected by the setValue method of the corresponding ASN.1 type), e.g.:

 AVA ava = new AVA(ObjectID.commonName, "John Doe");
 

The example above will create an AVA for the X.500 attribute type commonName. Since, per default, the commonName value will be encoded as PrintableString, the value has to be specified as java.lang.String object since the setValue method of class PrintableString expects a String object. Alternatively immediately a PrintableString ASN1Object may be supplied when creating the AVA:

 AVA ava = new AVA(ObjectID.commonName, new PrintableString("John Doe"));
 

If the supplied value constitutes a String and the default encoding type is set to ASN.1 PrintableString this constructor checks if the supplied string really consists only of printable characters. If not the encoding type for this string is set to ASN.1 UTF8String.

Parameters:

type - the attribute type as an ObjectID

value - the attribute value

AVA

public AVA(ObjectID type,
           Object value,
           ASN encodingType)
    throws IllegalArgumentException

Creates a new AttributeValueAssertion from a type and a value to be encoded using the given encoding type.

The value has to be supplied as a Java object of matching type (i.e. compatible to the type expected by the setValue method of the corresponding ASN.1 type), e.g.:

 AVA ava = new AVA(ObjectID.commonName, "John Doe", ASN.IA5String);
 

The example above will create an AVA for the X.500 attribute type commonName. Since IA5String shall be used to encode the AVA, the value has to be supplied as Java String object.

Alternatively immediately a IA5String ASN1Object may be supplied when creating the AVA:

 AVA ava = new AVA(ObjectID.commonName, new IA5String("John Doe"));
 

If the supplied value constitutes a String and the default encoding type is set to ASN.1 PrintableString this constructor checks if the supplied string really consists only of printable characters. If not the encoding type for this string is set to ASN.1 UTF8String.

Parameters:

type - the attribute type as an ObjectID

value - the attribute value

AVA

public AVA(ASN1Object obj)
    throws CodingException

Creates an AttributeValueAssertion from an ASN1Object.

The supplied ASN1Object represents an already existing AVA that may have been created by means of the toASN1Object method.

Parameters:

obj - the AttributeValueAssertion as ASN1Object

Throws:

CodingException - if the AttributeValueAssertion can not be decoded

Method Detail

defineEncoding

public static void defineEncoding(ObjectID type,
                                  ASN encodingType)

Defines the ASN.1 encoding for a specified Attribute type. The default encoding is a PrintableString meaning that per default the inherent attribute value will be encoded as ASN.1 character string of type PrintableString, except for the X.500 attribute type uniqueIdentifier and the PKCS#9 attribute type emailAddress which per default will be encoded as BIT_STRING, and IA5String, respectively.

This method may be used to enforce another encoding scheme for some specific attribute type, e.g.:

 AVA.defineEncoding(ObjectID.title, ASN.VisibleString);
 

will enforce that any AVA value of X.500 attribute type title will be encoded as VisibleString instead of PrintableString}.

Parameters:

type - the attribute type for which a new encoding scheme shall be defined

encodingType - the ASN.1 type for encoding it

getEncoding

public static ASN getEncoding(ObjectID type)

Gets the encoding type associated with the given attribute type.

This method asks if there has been registered a special encoding scheme for the given attribute type.

Parameters:

type - the attribute type to be searched for an encoding scheme

Returns:

the encoding scheme associated with the attribute type, or null if no encoding scheme has been registered for this attribute type

setDefaultEncoding

public static void setDefaultEncoding(ASN encodingType)

Sets the default encoding to be used. This method may be used to set another default encoding than PrintableString.

Parameters:

encodingType - the ASN.1 type to be used as default encoding

setNonPrintableDefaultEncoding

public static void setNonPrintableDefaultEncoding(ASN encodingType)

Sets the encoding that shall be used if a String attribute value has non printable chars.

The default encoding used by this class is ASN.1 PrintableString. If a String attribute value, however, has no printable characters, the encoding automatically is switched to UTF8String as recommended to RFC2459. This method may be used to set another "secondary" default encoding than UTF8String.

Parameters:

encodingType - the encoding type to be used if PrintableString is the default encoding but a String value contains non printable characters

getDefaultEncoding

public static ASN getDefaultEncoding()

Gets the default encoding.

Returns:

the ASN.1 type to be used as default encoding

getNonPrintableDefaultEncoding

public static ASN getNonPrintableDefaultEncoding()

Gets the encoding that is used if a String attribute value has non printable chars.

The default encoding used by this class is ASN.1 PrintableString. If a String attribute value, however, has no printable characters, the encoding automatically is switched to UTF8String as recommended to RFC2459. Method {@ink #This method setNonPrintableDefaultEncoding(ASN) setNonPrintableDefaultEncoding} may be used to set another "secondary" default encoding than UTF8String.

Returns:

the encoding type that is used if PrintableString is the default encoding but a String value contains non printable characters

decode

public void decode(ASN1Object obj)
            throws CodingException

Decodes an AVA from the given ASN1Object.

The supplied ASN1Object represents an already existing AVA object that may have been created by means of the toASN1Object() method.

Specified by:

decode in interface ASN1Type

Parameters:

obj - the AttributeValueAssertion as ASN1Object

Throws:

CodingException - if the AttributeValueAssertion can not be decoded

toASN1Object

public ASN1Object toASN1Object()

Returns this AttributeValueAssertion as an ASN1Object.

Specified by:

toASN1Object in interface ASN1Type

Returns:

this AttributeValueAssertion as an ASN1Object

getType

public ObjectID getType()

Returns the type of this AttributeValueAssertion.

getValue

public Object getValue()

Returns the value of this AttributeValueAssertion.

getASN1Value

public ASN1Object getASN1Value()
                        throws CodingException

Returns an ASN.1 representation of the value of this AttributeValueAssertion.

Returns:

an ASN.1 representation of the value of this AttributeValueAssertion

Throws:

CodingException - if an error occurs when getting the ASN.1 representation

hashCode

public int hashCode()

Returns the hashcode for this AttributeValueAssertion.

Overrides:

hashCode in class Object

Returns:

a hashcode for this AttributeValueAssertion

equals

public boolean equals(Object obj)

Compares two AttributeValueAssertions.

Overrides:

equals in class Object

Parameters:

obj - the other AttributeValueAssertion

Returns:

true, if the two AttributeValueAssertions are equal, false otherwise

toString

public String toString()

Returns a string that represents the contents of this RDN.

The string output is compatible to RFC 1779/2253 except for escaping. If desired, an application itself make take care for proper escaping.

Care has to be taken about attributes of type uniqueIdentifier. Since some certificates use a DER encoded PrintableString as value for the BIT_STRING uniqueIdentifier this method prints a string for such a uniqueIdentifier. Otherwise a binary string representation of the bit string value is printed, e.g.: "#'10010'B".

Overrides:

toString in class Object

Returns:

the string representation

toString

public String toString(boolean detailed)

Returns a string that represents the contents of this AVA.

The string output is compatible to RFC 1779/2253 except for escaping. If desired, an application itself make take care for proper escaping.

Care has to be taken about attributes of type uniqueIdentifier. Since some certificates use a DER encoded PrintableString as value for the BIT_STRING uniqueIdentifier this method prints a string for such a uniqueIdentifier. Otherwise a binary string representation of the bit string value is printed, e.g.: "#'10010'B".

Parameters:

detailed - whether the short name of the full name of the type shall be used

Returns:

the string representation

getRFC2253String

public String getRFC2253String()
                        throws RFC2253NameParserException

Returns a string representation of this AVA according to RFC 2253.

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

The attribute type is represented as described in section 2.3 of RFC 2253. If there is no known name string for the attribute type a dotted-decimal encoding of the attribute type´s identifier.

The string representation of the attribute value is either a hexadecimal represenation of its BER encoding (introduced by a "#" character) or based on the algorithm given in section 2.4 of RFC 2253 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.

Additionally this method escapes Any non printable ASCII (< 0x21 or > 0x7e) and any non-ASCII character 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.

Returns:

the string representation according to RFC 2253.

Throws:

RFC2253NameParserException - if the AVA cannot be represented according to the rules above