Name (6.0 API Documentation)

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

All Implemented Interfaces:

ASN1Type, java.security.Principal
```
public class Name
extends java.lang.Object
implements java.security.Principal, ASN1Type
```
This class represents a X.500 Name structure (Distinguished Name). A distinguished name is defined as a sequence of Relative Distinguished Names:
Name ::= SEQUENCE OF RelativeDistinguishedName
A Name object may be used for specifying, e.g. issuer and subject within a X.509 certificate. For creating a Name structure, use a proper constructor. You later may supply the relative distinguished names constituting your actual Name object by repeatedly calling the addRDN method, e.g.:
```
  Name subject = new Name();
  subject.addRDN(ObjectID.country, "AT");
  subject.addRDN(ObjectID.locality, "Graz");
  subject.addRDN(ObjectID.organization ,"TU Graz");
  subject.addRDN(ObjectID.organizationalUnit ,"IAIK");
  subject.addRDN(ObjectID.commonName ,"TestUser");
 
```
This class also allows to add more than one RDN of the same attribute type.
Version:

File Revision 37

Constructor Summary

Constructors
Constructor and Description
`Name()` The default constructor.
`Name(ASN1Object obj)` Constructs a Name from an ASN1Object.
`Name(byte[] name)` Creates a name from a DER encoded byte array.
`Name(java.lang.String dn)` Constructs a Name from its RFC 2253/4514 String representation.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addRDN(ObjectID oid, java.lang.Object value)` Adds a RelativeDistinguishedName with given attribute type and value to this Name.
`void`	`addRDN(RDN rdn)` Adds a RelativeDistinguishedName to this Name.
`void`	`decode(ASN1Object obj)` Decodes a Name from the given ASN1Object.
`RDN`	`element(ObjectID oid)` Returns an RDN that contains an AVA with the given attribute type.
`java.util.Enumeration`	`elements()` Returns an enumeration of all RDNs included in this Name.
`java.util.Enumeration`	`elements(ObjectID oid)` Returns an enumeration of all RDNs that contain an AVA with the given attribute type.
`boolean`	`equals(java.lang.Object obj)` Compares this Name to the specified object.
`byte[]`	`getEncoded()` Returns this Name as DER encoded byte array.
`java.lang.String`	`getName()` Returns a string that represents this Name.
`java.lang.String`	`getRDN(ObjectID oid)` Returns the RDN value assigned to a given ObjectID.
`java.lang.String`	`getRDN(ObjectID oid, boolean rfc2253)` Returns the RDN value assigned to a given ObjectID.
`RDN[]`	`getRDNs()` Returns an array containing all RDNs included this Name.
`java.lang.String[]`	`getRDNs(ObjectID oid)` Returns the values of all RDNs assigned to a given ObjectID.
`java.lang.String[]`	`getRDNs(ObjectID oid, boolean rfc2253)` Returns the values of all RDNs assigned to a given ObjectID.
`java.lang.Object`	`getRDNValue(ObjectID oid)` Returns the RDN value assigned to a given ObjectID.
`java.lang.Object[]`	`getRDNValues(ObjectID oid)` Returns the values of all RDNs assigned to a given ObjectID.
`java.lang.String`	`getRFC2253String()` Returns a string representation of this Name according to RFC 2253.
`java.lang.String`	`getRFC2253String(boolean strictEscaping)` Returns a string representation of this Name according to RFC 2253.
`int`	`hashCode()` Returns a hashcode for this Name.
`void`	`insertRDNAt(ObjectID oid, java.lang.Object value, int position)` Inserts a RelativeDistinguishedName with given attribute type and value to this Name at the given position.
`void`	`insertRDNAt(RDN rdn, int position)` Inserts a RelativeDistinguishedName to this Name at the given position.
`boolean`	`isEmpty()` Checks if there are any RDNs included in this Name.
`boolean`	`removeRDN(ObjectID oid)` Removes all RelativeDistinguishedNames with the given attribute type (oid) from this Name.
`ASN1Object`	`toASN1Object()` Returns this Name as ASN1Object.
`java.lang.String`	`toString()` Returns a string that represents this Name.
`java.lang.String`	`toString(boolean detailed)` Returns a string that represents this Name.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - Name
```
public Name()
```
    The default constructor.
  - Name
```
public Name(byte[] name)
     throws CodingException
```
    Creates a name from a DER encoded byte array. The supplied byte array represents the DER encoding of an already existing Name object.
    
    Parameters:
    name - a DER encoded Name
    
    Throws:
    
    CodingException
  - Name
```
public Name(ASN1Object obj)
     throws CodingException
```
    Constructs a Name from an ASN1Object. The supplied ASN1Object could be the ASN.1 type "Sequence of RelativeDistinguishedName" or only a SET if there would be just one element in the Sequence.
    
    Parameters:
    obj - the Name as ASN1Object
    
    Throws:
    
    CodingException - if the ASN1Object has the wrong format
  - Name
```
public Name(java.lang.String dn)
     throws RFC2253NameParserException
```
    Constructs a Name from its RFC 2253/4514 String representation.
    For instance:
```
 
 String rcf2253Name = "CN=Joe TestUser,O=IAIK,C=AT";
 Name = new Name(rcf2253Name);
 
```
    Parameters:
    dn - the (RFC 2253 formatted) distinguished name
    
    Throws:
    
    CodingException - if the ASN1Object has the wrong format
    
    RFC2253NameParserException
- Method Detail
  - decode
```
public void decode(ASN1Object obj)
            throws CodingException
```
    Decodes a Name from the given ASN1Object.
    
    Specified by:
    
    decode in interface ASN1Type
    
    Parameters:
    obj - the Name as ASN1Object
    
    Throws:
    
    CodingException - if the ASN1Object has the wrong format
  - getRDN
```
public java.lang.String getRDN(ObjectID oid)
```
    Returns the RDN value assigned to a given ObjectID. The inherent RDN objects are searched for the given objectID (attribute type). The value of first RDN with the requested ObjectID is returned. If no RDN with such an ObjectID (attribute type) is included, null is returned.
    Attention! This method only may be used for querying for a String RDN value. If you expect a non-string value (e.g. when searching for a uniqueIdentifier), use method getRDNValue which returns the value as Java object.
    
    Parameters:
    oid - the ObjectID of the RDN (AVA attribute) type to be searched for
    
    Returns:
    the value (as Java String) of the first RDN having the requested ObjectID; or null if no RDN of the requested type (oid) is included
    
    Throws:
    
    java.lang.ClassCastException - if the RDN value does not represent a String; in this case use method getRDNValue to get the RDN value
  - getRDN
```
public java.lang.String getRDN(ObjectID oid,
                      boolean rfc2253)
                        throws RFC2253NameParserException
```
    Returns the RDN value assigned to a given ObjectID. The inherent RDN objects are searched for the given objectID (attribute type). The value of first RDN with the requested ObjectID is returned. If no RDN with such an ObjectID (attribute type) is included, null is returned.
    Attention! This method only may be used for querying for a String RDN value. If you expect a non-string value (e.g. when searching for a uniqueIdentifier), use method getRDNValue which returns the value as Java object.
    
    Parameters:
    oid - the ObjectID of the RDN (AVA attribute) type to be searched for
    rfc2253 - whether to get the String in RFC2253 representation
    
    Returns:
    the value (as Java String) of the first RDN having the requested ObjectID; or null if no RDN of the requested type (oid) is included
    
    Throws:
    
    java.lang.ClassCastException - if the RDN value does not represent a String; in this case use method getRDNValue to get the RDN value
    
    RFC2253NameParserException - if the AVA cannot be represented according to RFC2253
  - getRDNs
```
public java.lang.String[] getRDNs(ObjectID oid)
```
    Returns the values of all RDNs assigned to a given ObjectID.
    Some CAs support certificates where the subject name may have multiple RDNs of same attribute type (ObjectID), e.g. two organizationalUnit entries. More than one RDN of same attribute type may be added to a Name structure by repeatedly calling the addRDN method with the same objectID (attribute type), e.g.:
```
 name.addRDN(ObjectID.organizationalUnit,"...");
 name.addRDN(ObjectID.organizationalUnit,"...");
   ...
 
```
    When calling this getRDNs method, all the inherent RDN objects are searched for the given objectID (attribute type). Any detected value contributes to a String array returning the values of all included RDN objects with the requested attribute type (oid). If no RDN with such an ObjectID (attribute type) is included, null is returned. Attention! This method only may be used for querying for String RDN values. If you expect non-string values (e.g. when searching for a uniqueIdentifier), use method getRDNValues which returns the values as an array of Java objects.
    Parameters:
    oid - the ObjectID of the RDN (AVA attribute) type to be searched for
    
    Returns:
    the values (as array of Strings) of all included RDNs having the requested ObjectID; or null if no RDN of the requested type (oid) is included
  - getRDNs
```
public java.lang.String[] getRDNs(ObjectID oid,
                         boolean rfc2253)
                           throws RFC2253NameParserException
```
    Returns the values of all RDNs assigned to a given ObjectID.
    Some CAs support certificates where the subject name may have multiple RDNs of same attribute type (ObjectID), e.g. two organizationalUnit entries. More than one RDN of same attribute type may be added to a Name structure by repeatedly calling the addRDN method with the same objectID (attribute type), e.g.:
```
 name.addRDN(ObjectID.organizationalUnit,"...");
 name.addRDN(ObjectID.organizationalUnit,"...");
   ...
 
```
    When calling this getRDNs method, all the inherent RDN objects are searched for the given objectID (attribute type). Any detected value contributes to a String array returning the values of all included RDN objects with the requested attribute type (oid). If no RDN with such an ObjectID (attribute type) is included, null is returned. Attention! This method only may be used for querying for String RDN values. If you expect non-string values (e.g. when searching for a uniqueIdentifier), use method getRDNValues which returns the values as an array of Java objects.
    Parameters:
    oid - the ObjectID of the RDN (AVA attribute) type to be searched for
    rfc2253 - whether to get the String in RFC2253 representation
    
    Returns:
    the values (as array of Strings) of all included RDNs having the requested ObjectID; or null if no RDN of the requested type (oid) is included
    
    Throws:
    
    RFC2253NameParserException - if the AVA cannot be represented according to RFC2253
  - getRDNValue
```
public java.lang.Object getRDNValue(ObjectID oid)
```
    Returns the RDN value assigned to a given ObjectID. The inherent RDN objects are searched for the given objectID (attribute type). The value of first RDN with the requested ObjectID is returned. If no RDN with such an ObjectID (attribute type) is included, null is returned.
    
    Parameters:
    oid - the ObjectID of the RDN (AVA attribute) type to be searched for
    
    Returns:
    the value (as Java Object) of the first RDN having the requested ObjectID; or null if no RDN of the requested type (oid) is included
  - getRDNValues
```
public java.lang.Object[] getRDNValues(ObjectID oid)
```
    Returns the values of all RDNs assigned to a given ObjectID.
    Some CAs support certificates where the subject name may have multiple RDNs of same attribute type (ObjectID), e.g. two organizationalUnit entries. More than one RDN of same attribute type may be added to a Name structure by repeatedly calling the addRDN method with the same objectID (attribute type), e.g.:
```
 name.addRDN(ObjectID.organizationalUnit,"...");
 name.addRDN(ObjectID.organizationalUnit,"...");
   ...
 
```
    When calling this getRDNs method, all the inherent RDN objects are searched for the given objectID (attribute type). Any detected value contributes to a String array returning the values of all included RDN objects with the requested attribute type (oid). If no RDN with such an ObjectID (attribute type) is included, null is returned.
    Parameters:
    oid - the ObjectID of the RDN (AVA attribute) type to be searched for
    
    Returns:
    the values (as array of Java objects) of all included RDNs having the requested ObjectID; or null if no RDN of the requested type (oid) is included
  - getRDNs
```
public RDN[] getRDNs()
```
    Returns an array containing all RDNs included this Name.
    
    Returns:
    an array of all included RDN objects
  - elements
```
public java.util.Enumeration elements()
```
    Returns an enumeration of all RDNs included in this Name.
    
    Returns:
    an enumeration of all included RDN elements
  - elements
```
public java.util.Enumeration elements(ObjectID oid)
```
    Returns an enumeration of all RDNs that contain an AVA with the given attribute type.
    
    Parameters:
    oid - the ObjectID of the RDN (AVA attribute) type to be searched for
    
    Returns:
    an enumeration of all RDN elements that contain an AVA with the given attribute type
  - element
```
public RDN element(ObjectID oid)
```
    Returns an RDN that contains an AVA with the given attribute type. If more than only one RDN contains an AVA with the given type, only the first RDN is returned.
    
    Parameters:
    oid - the ObjectID of the RDN (AVA attribute) type to be searched for
    
    Returns:
    the first RDN element that contain an AVA with the given attribute type; or null if none of the included RDNs contains an AVA with the given type
  - isEmpty
```
public boolean isEmpty()
```
    Checks if there are any RDNs included in this Name.
    
    Returns:
    true if there are no RDNs, false otherwise
  - addRDN
```
public void addRDN(ObjectID oid,
          java.lang.Object value)
```
    Adds a RelativeDistinguishedName with given attribute type and value to this Name.
    
    Parameters:
    oid - the ObjectID (attribute type) of the RDN to be added
    value - the value of the RDN to be added
  - addRDN
```
public void addRDN(RDN rdn)
```
    Adds a RelativeDistinguishedName to this Name.
    
    Parameters:
    rdn - the RDN to be added
  - insertRDNAt
```
public void insertRDNAt(ObjectID oid,
               java.lang.Object value,
               int position)
```
    Inserts a RelativeDistinguishedName with given attribute type and value to this Name at the given position.
    
    Parameters:
    oid - the ObjectID (attribute type) of the RDN to be added
    value - the value of the RDN to be added
    position - the position at which the RDN shall be inserted
    
    Throws:
    
    java.lang.ArrayIndexOutOfBoundsException - if position is out of bounds
  - insertRDNAt
```
public void insertRDNAt(RDN rdn,
               int position)
```
    Inserts a RelativeDistinguishedName to this Name at the given position.
    
    Parameters:
    rdn - the RDN to be inserted
    position - the position at which the RDN shall be inserted
    
    Throws:
    
    java.lang.ArrayIndexOutOfBoundsException - if position is out of bounds
  - removeRDN
```
public boolean removeRDN(ObjectID oid)
```
    Removes all RelativeDistinguishedNames with the given attribute type (oid) from this Name.
    
    Parameters:
    oid - the ObjectID (attribute type) of the RDN which shall be removed
    
    Returns:
    true if some RDN(s) have been removed; false if no RDN has been removed, since no RDN of the requested type is included in this Name
  - toASN1Object
```
public ASN1Object toASN1Object()
```
    Returns this Name as ASN1Object.
    
    Specified by:
    
    toASN1Object in interface ASN1Type
    
    Returns:
    this Name as ASN1Object
  - getEncoded
```
public byte[] getEncoded()
```
    Returns this Name as DER encoded byte array.
    
    Returns:
    this Name as DER encoded byte array
  - hashCode
```
public int hashCode()
```
    Returns a hashcode for this Name.
    
    Specified by:
    
    hashCode in interface java.security.Principal
    
    Overrides:
    
    hashCode in class java.lang.Object
    
    Returns:
    a hashcode for this Name
  - equals
```
public boolean equals(java.lang.Object obj)
```
    Compares this Name to the specified object.
    
    Specified by:
    
    equals in interface java.security.Principal
    
    Overrides:
    
    equals in class java.lang.Object
    
    Parameters:
    obj - - the object to compare this Name against.
    
    Returns:
    true, if the object represents the same Name false otherwise
  - getName
```
public java.lang.String getName()
```
    Returns a string that represents this Name. This method tries to get an RFC 2253 representation of the name; if this failed, a user-friendly representation is returned by calling method toString.
    
    Specified by:
    
    getName in interface java.security.Principal
    
    Returns:
    the string representation of this Name
  - toString
```
public java.lang.String toString()
```
    Returns a string that represents this Name.
    
    Specified by:
    
    toString in interface java.security.Principal
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    the string representation
  - toString
```
public java.lang.String toString(boolean detailed)
```
    Returns a string that represents this Name.
    
    Parameters:
    detailed - true if no shortNames shall be used when printing the attribute types of the AVAs
    
    Returns:
    the string representation
  - getRFC2253String
```
public java.lang.String getRFC2253String()
                                  throws RFC2253NameParserException
```
    Returns a string representation of this Name 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 included RDNs are represented in reversed order starting with the last element and moving to the first. Adjoining RDNs are separated by a comma (",").
    The AttributeTypeAndValues of each included RDN are represented as specified in sections 2.3, 2.4 of RFC 2253 (adjoining AttributeTypeAndValues (or AVAs) are separated by a plus ("+") character):
    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 Name 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 included RDNs are represented in reversed order starting with the last element and moving to the first. Adjoining RDNs are separated by a comma (",").
    The AttributeTypeAndValues of each included RDN are represented as specified in sections 2.3, 2.4 of RFC 2253 (adjoining AttributeTypeAndValues (or AVAs) are separated by a plus ("+") character):
    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.
    - 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 Name

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Name

Name

Name

Name

Method Detail

decode

getRDN

getRDN

getRDNs

getRDNs

getRDNValue

getRDNValues

getRDNs

elements

elements

element

isEmpty

addRDN

addRDN

insertRDNAt

insertRDNAt

removeRDN

toASN1Object

getEncoded

hashCode

equals

getName

toString

toString

getRFC2253String

getRFC2253String