com.rsa.certj.cert

Class X500Name

java.lang.Object
  |
  +--com.rsa.certj.cert.X500Name

All Implemented Interfaces:

Cloneable, Serializable

public class X500Name

extends Object

implements Cloneable, Serializable

This class builds and holds X.500 names.

The following are the Cert-J supported attribute types:

• Country Name
• Common Name
• Locality Name
• State or Province Name
• Organization Name
• Organizational Unit Name
• Telephone Number
• Title
• Business Category
• Email Address
• Street Address
• Postal Code
• Surname
• Given Name
• DomainComponent
• DN Qualifier
• Initials
• Generation Qualifier
• Name
• Serial Number
• Postal Address
• Pseudonym
• Date Of Birth
• Place Of Birth
• Gender
• Country Of Citizenship
• Country Of Residence

The ASN.1 definition is as follows:

 Name ::=	CHOICE {
   rdnSequence  RDNSequence } -- only one possibility for now
 RDNSequence ::=	SEQUENCE OF
 	RelativeDistinguishedName

 RelativeDistinguishedName  ::=  SET SIZE (1..MAX) OF AttributeTypeAndValue
 AttributeTypeAndValue ::=	SEQUENCE
 	type	ATTRIBUTE.&id ({SupportedAttributes}),
 	value	({ATTRIBUTE.&Type ({SupportedAttributes}{@type})}   

The following is an example of how Cert-J implements its encoding engine:

 Name ::= SEQUENCE OF {
   SET OF {                  -- This is an RDN
     SEQUENCE {              -- This is an AVA
       OBJECT IDENTIFIER,
       ANY Encoded
   }
 }    

Copyright © RSA Security Inc., 1998-2003. All rights reserved.

See Also

Serialized Form

Constructor Summary

X500Name()

Constructs an empty X500Name object.

X500Name(byte[] nameBER, int offset, int special)

Constructs an X500Name object and initializes it with the collection of attributes represented by nameBER.

X500Name(String nameString)

Constructs an X500Name object and initializes it with the collection of attributes represented by the String value.

Method Summary

void	addRDN(byte[] rdnBER, int offset) Adds an RDN to this object.
void	addRDN(RDN rdn) Adds an RDN to this object.
void	addRDN(RDN name, int index) Adds the new RDN at the specified index.
Object	clone() Overrides the default clone method to get a deeper clone.
boolean	contains(X500Name name) Takes the RDNs from name and checks whether this X500Name object contains every RDN from name and whether the data is the same.
boolean	equals(Object obj) Returns true if this object and obj contain the same X.500 name, returns false otherwise.
AttributeValueAssertion	getAttribute(int attributeType) Gets the attribute, of the type attributeType, from the name object.
int	getAttributeCount() Gets the number of attributes in this X.500 name.
int	getDEREncoding(byte[] encoding, int offset, int special) Places the DER encoding of the X.500 name in this object into encoding, beginning at offset.
int	getDERLen(int special) Returns the number of bytes of the DER encoding of this X.500 name.
static int	getNextBEROffset(byte[] nameBER, int offset) Given nameBER, the BER encoding of an X.500 name beginning at offset, finds the index to the next element in the encoding.
RDN	getRDN(int index) Gets the RDN at the specified index.
int	getRDNCount() Gets the number of RDNs in this X.500 name.
void	removeRDN(int index) Deletes the RDN object at the specified index.
String	toString() Returns a String that describes this X.500 name in RFC2253 format.
String	toString(boolean reverse) Returns a String that describes this X.500 name in RFC2253 format.

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

X500Name

public X500Name(byte[] nameBER,
                int offset,
                int special)
         throws NameException

Constructs an X500Name object and initializes it with the collection of attributes represented by nameBER.

The ASN.1 definition (previously defined in this class) means the tag will be 0x30. However, an X500Name object can be part of a certificate request (or some other construct), and it might have a different tag, caused by IMPLICIT or EXPLICIT. For example, suppose the definition is as follows:

   name   [1] IMPLICIT Name     

In this case, the tag will change from 0x30 to 0xa1. To indicate that the BER encoding of the X500Name object should follow any special circumstances, use the special argument. For example, to indicate the following:

   name   [1] IMPLICIT Name   

Pass in the following:

 special = (ASN1.CONTEXT_IMPLICIT | 1);   

If there are no special circumstances, pass in the following:

   special = 0  

The following ASN.1 constants are possible values for special: APP_IMPLICIT, APP_EXPLICIT, PRIVATE_IMPLICIT, PRIVATE_EXPLICIT, OPTIONAL, DEFAULT, CONTEXT_IMPLICIT, or CONTEXT_EXPLICIT.

Parameters

	nameBER		A byte array that contains the BER encoding of the X.500 name.
	offset		The offset into nameBER where the encoding begins.
	special		The special circumstances of the BER encoding, if there are any, such as OPTIONAL.

Throws

NameException - If the BER encoding is invalid.

X500Name

public X500Name()

Constructs an empty X500Name object. After calling this constructor, use the addRDN() method to set the X500Name object to the correct attributes.

X500Name

public X500Name(String nameString)
         throws NameException

Constructs an X500Name object and initializes it with the collection of attributes represented by the String value.

Parameters

nameString

A String object that holds the string value of an X500Name object, according to RFC 2253.

Throws

NameException - If an error occured while parsing and building the X500Name object.

Method Detail

clone

public Object clone()
             throws CloneNotSupportedException

Overrides the default clone method to get a deeper clone.

Returns

A new X500Name object, a copy of this object.

Throws

CloneNotSupportedException - If the cloning operation is not successful.

toString

public String toString(boolean reverse)

Returns a String that describes this X.500 name in RFC2253 format. RFC2253 format specifies certain formatting, including the presence of a backslash before a comma, and a comma without a preceding backslash to delineate fields.

Parameters

reverse

A boolean that if set to true, reverses the order of the RDNs within the returned String. This makes it easier to index in a database.

Returns

A String that describes this X.500 name.

toString

public String toString()

Returns a String that describes this X.500 name in RFC2253 format. RFC2253 format specifies certain formatting, including the presence of a backslash before a comma, and a comma without a preceding backslash to delineate fields.

Overrides

toString in class Object

Returns

A String that describes this X.500 name.

getRDNCount

public int getRDNCount()

Gets the number of RDNs in this X.500 name.

Returns

The number of RDNs in this X.500 name.

getAttributeCount

public int getAttributeCount()

Gets the number of attributes in this X.500 name.

Returns

The number of attributes in this X.500 name.

getRDN

public RDN getRDN(int index)
           throws NameException

Gets the RDN at the specified index.

Parameters

index

The index into the list of RDNs where the requested RDN is located.

Returns

The specified RDN.

Throws

NameException - If the provided index is invalid.

removeRDN

public void removeRDN(int index)
               throws NameException

Deletes the RDN object at the specified index.

Parameters

index

The index into the list of RDNs.

Throws

NameException - If the provided index is invalid.

addRDN

public void addRDN(RDN name,
                   int index)
            throws NameException

Adds the new RDN at the specified index.

Parameters

	name		The new RDN object.
	index		The index into the list of RDNs.

Throws

NameException - If index is invalid.

getAttribute

public AttributeValueAssertion getAttribute(int attributeType)

Gets the attribute, of the type attributeType, from the name object. The attributeType will be one of the fields specified in the AttributeValueAssertion class, such as COUNTRY_NAME or COMMON_NAME. If the X.500 name object does not possess an attribute of attributeType, this method returns null.

Parameters

attributeType

The flag indicating which attribute type is requested.

Returns

The attribute of the specified attribute type.

getNextBEROffset

public static int getNextBEROffset(byte[] nameBER,
                                   int offset)
                            throws NameException

Given nameBER, the BER encoding of an X.500 name beginning at offset, finds the index to the next element in the encoding. In other words, gets the next offset after the X.500 name.

For example, if the offset is 120 and the name's BER encoding is 1819 bytes, this method will return 1939, the index immediately following the name. That is, nameBER>[120] is the first byte in the encoding of the name, nameBER[1938] is the last byte in the encoding of the name, and the next element begins at index 1939.

Parameters

	nameBER		The BER encoding of an X.500 name.
	offset		The offset into nameBER where the encoding begins.

Returns

An int that contains the index to the next element in the BER encoding.

Throws

NameException - If the method cannot read the BER encoding.

getDERLen

public int getDERLen(int special)

Returns the number of bytes of the DER encoding of this X.500 name. If this object is not set with values, this method returns zero.

Parameters

special

The special circumstances of the DER encoding, if there are any. The following ASN.1 constants are possible values for special: APP_IMPLICIT, APP_EXPLICIT, PRIVATE_IMPLICIT, PRIVATE_EXPLICIT, OPTIONAL, DEFAULT, CONTEXT_IMPLICIT, or CONTEXT_EXPLICIT.

Returns

The number of bytes of the DER encoding of this attribute.

getDEREncoding

public int getDEREncoding(byte[] encoding,
                          int offset,
                          int special)
                   throws NameException

Places the DER encoding of the X.500 name in this object into encoding, beginning at offset. To determine the length, in bytes, of the encoding, call getNameDERLen. If this object is not yet set with an X.500 name, then this method places nothing into the array and returns zero.

The ASN.1 definition (previously defined in this class) means the tag will be 0x30. However, an X500Name object can be part of a certificate request (or some other construct) and it might have a different tag, caused by IMPLICIT or EXPLICIT. For example, suppose the definition is as follows:

   name   [1] IMPLICIT Name   

In this case, the tag will change from 0x30 to 0xa1. To indicate that the DER encoding of the X500Name should follow any special circumstances of this particular encoding, use the special argument. For example, to indicate the following:

   name   [1] IMPLICIT Name   

Pass in the following:

   special = (ASN1.CONTEXT_IMPLICIT | 1);   

If there are no special circumstances, pass in the following:

   special = 0  

The following ASN.1 constants are possible values for special: APP_IMPLICIT, APP_EXPLICIT, PRIVATE_IMPLICIT, PRIVATE_EXPLICIT, OPTIONAL, DEFAULT, CONTEXT_IMPLICIT, or CONTEXT_EXPLICIT.

Parameters

	encoding		A byte array that will hold the BER encoding of the X.500 name.
	offset		The offset into encoding where the encoding begins.
	special		The special circumstances of the DER encoding, if there are any, such as OPTIONAL.

Returns

The number of bytes placed into encoding.

Throws

NameException - If unable to encode the X.500 name.

addRDN

public void addRDN(RDN rdn)
            throws NameException

Adds an RDN to this object.

Parameters

rdn

The RDN object to be added.

Throws

NameException - If the provided RDN is invalid.

addRDN

public void addRDN(byte[] rdnBER,
                   int offset)
            throws NameException

Adds an RDN to this object.

Parameters

	rdnBER		A byte array where the BER-encoded value of this RDN is located.
	offset		The offset into rdnBER where the encoding begins.

Throws

NameException - If the provided RDN is invalid.

equals

public boolean equals(Object obj)

Returns true if this object and obj contain the same X.500 name, returns false otherwise.

Overrides

equals in class Object

Parameters

obj

An instance of the X500Name object.

Returns

A boolean indicating whether these objects are equal.

contains

public boolean contains(X500Name name)

Takes the RDNs from name and checks whether this X500Name object contains every RDN from name and whether the data is the same. For example, this method could be used to determine if the name contains everyone from the engineering department at RSA, by setting name to the following:

     O="RSA", OU="engineering"

The O represents "organization name" and the OU represents "organizational unit name."

Parameters

name

The partial X500Name to compare against.

Returns

Returns true if this name contains the RDNs from name, with the same data.