AVA (6.0 API Documentation)

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

All Implemented Interfaces:

ASN1Type
```
public class AVA
extends java.lang.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
 }
 
```
Note that some (newer) standards (e.g. RFC 5280) use the term AttributeTypeAndValue instead of AttributeValueAssertion; the ASN.1 syntax is the same:
```
 RelativeDistinguishedName ::= SET OF AttributeTypeAndValue
 
 AttributeTypeAndValue ::= SEQUENCE {
  AttributeType    AttributeType,
  AttributeValue   AttributeValue
 }
 
 AttributeType ::= OBJECT IDENTIFIER
 
 AttributeValue ::= ANY -- DEFINED BY AttributeType
 
```
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 42

Constructor Summary

Constructors
Constructor and Description
`AVA(ASN1Object obj)` Creates an AttributeValueAssertion from an ASN1Object.
`AVA(ObjectID type, java.lang.Object value)` Creates a new AttributeValueAssertion from a type and a value.
`AVA(ObjectID type, java.lang.Object value, ASN encodingType)` Creates a new AttributeValueAssertion from a type and a value to be encoded using the given encoding type.

Method Summary

Methods
Modifier and Type	Method and Description
`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(java.lang.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.
`java.lang.String`	`getRFC2253String()` Returns a string representation of this AVA according to RFC 2253.
`java.lang.String`	`getRFC2253String(boolean strictEscaping)` Returns a string representation of this AVA according to RFC 2253.
`ObjectID`	`getType()` Returns the type of this AttributeValueAssertion.
`java.lang.Object`	`getValue()` Returns the value of this AttributeValueAssertion.
`java.lang.String`	`getValueAsString()` Returns the value of this AttributeValueAssertion as String.
`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.
`java.lang.String`	`toString()` Returns a string that represents the contents of this RDN.
`java.lang.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,
   java.lang.Object value)
    throws java.lang.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
    
    Throws:
    
    java.lang.IllegalArgumentException
  - AVA
```
public AVA(ObjectID type,
   java.lang.Object value,
   ASN encodingType)
    throws java.lang.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
    
    Throws:
    
    java.lang.IllegalArgumentException
  - 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 RFC3280. 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 RFC3280. This method 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.
    
    Returns:
    the type of this AttributeValueAssertion, as ObjectID
  - getValue
```
public java.lang.Object getValue()
```
    Returns the value of this AttributeValueAssertion.
    
    Returns:
    the value of this AttributeValueAssertion
  - getValueAsString
```
public java.lang.String getValueAsString()
```
    Returns the value of this AttributeValueAssertion as String. If the value of this AVA is not a String object this method tries to return an escaped hexadecimal representation of the DER encoded value.
    
    Returns:
    the value of this AttributeValueAssertion as String
  - 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 java.lang.Object
    
    Returns:
    a hashcode for this AttributeValueAssertion
  - equals
```
public boolean equals(java.lang.Object obj)
```
    Compares two AttributeValueAssertions.
    
    Overrides:
    
    equals in class java.lang.Object
    
    Parameters:
    obj - the other AttributeValueAssertion
    
    Returns:
    true, if the two AttributeValueAssertions are equal, false otherwise
  - toString
```
public java.lang.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 java.lang.Object
    
    Returns:
    the string representation
  - toString
```
public java.lang.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 java.lang.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. This implementation is also compliant with the updated standard RFC 4514, which obsoleted RFC 2253.
    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 representation 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
  - getRFC2253String
```
public java.lang.String getRFC2253String(boolean strictEscaping)
                                  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. This implementation is also compliant with the updated standard RFC 4514, which obsoleted RFC 2253.
    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 representation 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.
    - The space character (0x21) only is escaped when appearing at the beginning or the end of the string.
    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 if strictEscaping is set to true
    Parameters:
    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:
    
    RFC2253NameParserException - if the AVA cannot be represented according to the rules above

Class AVA

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

AVA

AVA

AVA

Method Detail

defineEncoding

getEncoding

setDefaultEncoding

setNonPrintableDefaultEncoding

getDefaultEncoding

getNonPrintableDefaultEncoding

decode

toASN1Object

getType

getValue

getValueAsString

getASN1Value

hashCode

equals

toString

toString

getRFC2253String

getRFC2253String