public class

X500Name

extends Object
implements Principal GeneralNameInterface
java.lang.Object
   ↳ sun.security.x509.X500Name

Class Overview

Note: As of 1.4, the public class, javax.security.auth.x500.X500Principal, should be used when parsing, generating, and comparing X.500 DNs. This class contains other useful methods for checking name constraints and retrieving DNs by keyword.

X.500 names are used to identify entities, such as those which are identified by X.509 certificates. They are world-wide, hierarchical, and descriptive. Entities can be identified by attributes, and in some systems can be searched for according to those attributes.

The ASN.1 for this is: 

 GeneralName ::= CHOICE {
 ....
     directoryName                   [4]     Name,
 ....
 Name ::= CHOICE {
   RDNSequence }

 RDNSequence ::= SEQUENCE OF RelativeDistinguishedName

 RelativeDistinguishedName ::=
   SET OF AttributeTypeAndValue

 AttributeTypeAndValue ::= SEQUENCE {
   type     AttributeType,
   value    AttributeValue }

 AttributeType ::= OBJECT IDENTIFIER

 AttributeValue ::= ANY DEFINED BY AttributeType
 ....
 DirectoryString ::= CHOICE {
       teletexString           TeletexString (SIZE (1..MAX)),
       printableString         PrintableString (SIZE (1..MAX)),
       universalString         UniversalString (SIZE (1..MAX)),
       utf8String              UTF8String (SIZE (1.. MAX)),
       bmpString               BMPString (SIZE (1..MAX)) }

This specification requires only a subset of the name comparison functionality specified in the X.500 series of specifications. The requirements for conforming implementations are as follows:

  1. attribute values encoded in different types (e.g., PrintableString and BMPString) may be assumed to represent different strings;

  2. attribute values in types other than PrintableString are case sensitive (this permits matching of attribute values as binary objects);

  3. attribute values in PrintableString are not case sensitive (e.g., "Marianne Swanson" is the same as "MARIANNE SWANSON"); and

  4. attribute values in PrintableString are compared after removing leading and trailing white space and converting internal substrings of one or more consecutive white space characters to a single space.

These name comparison rules permit a certificate user to validate certificates issued using languages or encodings unfamiliar to the certificate user.

In addition, implementations of this specification MAY use these comparison rules to process unfamiliar attribute types for name chaining. This allows implementations to process certificates with unfamiliar attributes in the issuer name.

Note that the comparison rules defined in the X.500 series of specifications indicate that the character sets used to encode data in distinguished names are irrelevant. The characters themselves are compared without regard to encoding. Implementations of the profile are permitted to use the comparison algorithm defined in the X.500 series. Such an implementation will recognize a superset of name matches recognized by the algorithm specified above.

Note that instances of this class are immutable.

See Also

Summary

[Expand]
Inherited Constants
From interface sun.security.x509.GeneralNameInterface
Fields
public static final ObjectIdentifier DNQUALIFIER_OID
public static final ObjectIdentifier DOMAIN_COMPONENT_OID
public static final ObjectIdentifier GENERATIONQUALIFIER_OID
public static final ObjectIdentifier GIVENNAME_OID
public static final ObjectIdentifier INITIALS_OID
public static final ObjectIdentifier SERIALNUMBER_OID
public static final ObjectIdentifier SURNAME_OID
public static final ObjectIdentifier commonName_oid
public static final ObjectIdentifier countryName_oid
public static final ObjectIdentifier ipAddress_oid
public static final ObjectIdentifier localityName_oid
public static final ObjectIdentifier orgName_oid
public static final ObjectIdentifier orgUnitName_oid
public static final ObjectIdentifier stateName_oid
public static final ObjectIdentifier streetAddress_oid
public static final ObjectIdentifier title_oid
public static final ObjectIdentifier userid_oid
Public Constructors
X500Name(String dname)
Constructs a name from a conventionally formatted string, such as "CN=Dave, OU=JavaSoft, O=Sun Microsystems, C=US".
X500Name(String dname, Map<String, String> keywordMap)
Constructs a name from a conventionally formatted string, such as "CN=Dave, OU=JavaSoft, O=Sun Microsystems, C=US".
X500Name(String dname, String format)
Constructs a name from a string formatted according to format.
X500Name(String commonName, String organizationUnit, String organizationName, String country)
Constructs a name from fields common in enterprise application environments.
X500Name(String commonName, String organizationUnit, String organizationName, String localityName, String stateName, String country)
Constructs a name from fields common in Internet application environments.
X500Name(RDN[] rdnArray)
Constructs a name from an array of relative distinguished names
X500Name(DerValue value)
Constructs a name from an ASN.1 encoded value.
X500Name(DerInputStream in)
Constructs a name from an ASN.1 encoded input stream.
X500Name(byte[] name)
Constructs a name from an ASN.1 encoded byte array.
Public Methods
List<AVA> allAvas()
Return an immutable List of the the AVAs contained in all the RDNs of this X500Name.
static X500Name asX500Name(X500Principal p)
Get the X500Name contained in the given X500Principal.
X500Principal asX500Principal()
Get an X500Principal backed by this X500Name.
int avaSize()
Return the total number of AVAs contained in all the RDNs of this X500Name.
X500Name commonAncestor(X500Name other)
Return lowest common ancestor of this name and other name
int constrains(GeneralNameInterface inputName)
Return constraint type:
  • NAME_DIFF_TYPE = -1: input name is different type from this name (i.e.
void emit(DerOutputStream out)
This method is deprecated. Use encode() instead
void encode(DerOutputStream out)
Encodes the name in DER-encoded form.
boolean equals(Object obj)
Compares this name with another, for equality.
DerValue findMostSpecificAttribute(ObjectIdentifier attribute)
Find the most specific ("last") attribute of the given type.
String getCommonName()
Returns a "Common Name" component.
String getCountry()
Returns a "Country" name component.
String getDNQualifier()
Returns a "DN Qualifier" name component.
String getDomain()
Returns a "Domain" name component.
byte[] getEncoded()
Gets the name in DER-encoded form.
byte[] getEncodedInternal()
Returned the encoding as an uncloned byte array.
String getGeneration()
Returns a "Generation Qualifier" name component.
String getGivenName()
Returns a "Given Name" name component.
String getIP()
Returns an "IP address" name component.
String getInitials()
Returns an "Initials" name component.
String getLocality()
Returns a "Locality" name component.
String getName()
Returns the value of toString().
String getOrganization()
Returns an "Organization" name component.
String getOrganizationalUnit()
Returns an "Organizational Unit" name component.
String getRFC1779Name(Map<String, String> oidMap)
Returns a string form of the X.500 distinguished name using the algorithm defined in RFC 1779.
String getRFC1779Name()
Returns a string form of the X.500 distinguished name using the algorithm defined in RFC 1779.
String getRFC2253CanonicalName()
String getRFC2253Name()
Returns a string form of the X.500 distinguished name using the algorithm defined in RFC 2253.
String getRFC2253Name(Map<String, String> oidMap)
Returns a string form of the X.500 distinguished name using the algorithm defined in RFC 2253.
String getState()
Returns a "State" name component.
String getSurname()
Returns a "Surname" name component.
int getType()
Return type of GeneralName.
int hashCode()
Calculates a hash code value for the object.
boolean isEmpty()
Return whether this X500Name is empty.
List<RDN> rdns()
Return an immutable List of all RDNs in this X500Name.
int size()
Return the number of RDNs in this X500Name.
int subtreeDepth()
Return subtree depth of this name for purposes of determining NameConstraints minimum and maximum bounds and for calculating path lengths in name subtrees.
String toString()
Returns a string form of the X.500 distinguished name.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.security.Principal
From interface sun.security.x509.GeneralNameInterface

Fields

public static final ObjectIdentifier DNQUALIFIER_OID

public static final ObjectIdentifier DOMAIN_COMPONENT_OID

public static final ObjectIdentifier GENERATIONQUALIFIER_OID

public static final ObjectIdentifier GIVENNAME_OID

public static final ObjectIdentifier INITIALS_OID

public static final ObjectIdentifier SERIALNUMBER_OID

public static final ObjectIdentifier SURNAME_OID

public static final ObjectIdentifier commonName_oid

public static final ObjectIdentifier countryName_oid

public static final ObjectIdentifier ipAddress_oid

public static final ObjectIdentifier localityName_oid

public static final ObjectIdentifier orgName_oid

public static final ObjectIdentifier orgUnitName_oid

public static final ObjectIdentifier stateName_oid

public static final ObjectIdentifier streetAddress_oid

public static final ObjectIdentifier title_oid

public static final ObjectIdentifier userid_oid

Public Constructors

public X500Name (String dname)

Constructs a name from a conventionally formatted string, such as "CN=Dave, OU=JavaSoft, O=Sun Microsystems, C=US". (RFC 1779 or RFC 2253 style).

Throws
IOException

public X500Name (String dname, Map<String, String> keywordMap)

Constructs a name from a conventionally formatted string, such as "CN=Dave, OU=JavaSoft, O=Sun Microsystems, C=US". (RFC 1779 or RFC 2253 style).

Parameters
keywordMap an additional keyword/OID map
Throws
IOException

public X500Name (String dname, String format)

Constructs a name from a string formatted according to format. Currently, the formats DEFAULT and RFC2253 are supported. DEFAULT is the default format used by the X500Name(String) constructor. RFC2253 is format strictly according to RFC2253 without extensions.

Throws
IOException

public X500Name (String commonName, String organizationUnit, String organizationName, String country)

Constructs a name from fields common in enterprise application environments.

NOTE: The behaviour when any of these strings contain characters outside the ASCII range is unspecified in currently relevant standards.

Parameters
commonName common name of a person, e.g. "Vivette Davis"
organizationUnit small organization name, e.g. "Purchasing"
organizationName large organization name, e.g. "Onizuka, Inc."
country two letter country code, e.g. "CH"
Throws
IOException

public X500Name (String commonName, String organizationUnit, String organizationName, String localityName, String stateName, String country)

Constructs a name from fields common in Internet application environments.

NOTE: The behaviour when any of these strings contain characters outside the ASCII range is unspecified in currently relevant standards.

Parameters
commonName common name of a person, e.g. "Vivette Davis"
organizationUnit small organization name, e.g. "Purchasing"
organizationName large organization name, e.g. "Onizuka, Inc."
localityName locality (city) name, e.g. "Palo Alto"
stateName state name, e.g. "California"
country two letter country code, e.g. "CH"
Throws
IOException

public X500Name (RDN[] rdnArray)

Constructs a name from an array of relative distinguished names

Parameters
rdnArray array of relative distinguished names
Throws
IOException on error

public X500Name (DerValue value)

Constructs a name from an ASN.1 encoded value. The encoding of the name in the stream uses DER (a BER/1 subset).

Parameters
value a DER-encoded value holding an X.500 name.
Throws
IOException

public X500Name (DerInputStream in)

Constructs a name from an ASN.1 encoded input stream. The encoding of the name in the stream uses DER (a BER/1 subset).

Parameters
in DER-encoded data holding an X.500 name.
Throws
IOException

public X500Name (byte[] name)

Constructs a name from an ASN.1 encoded byte array.

Parameters
name DER-encoded byte array holding an X.500 name.
Throws
IOException

Public Methods

public List<AVA> allAvas ()

Return an immutable List of the the AVAs contained in all the RDNs of this X500Name.

public static X500Name asX500Name (X500Principal p)

Get the X500Name contained in the given X500Principal. Note that the X500Name is retrieved using reflection.

public X500Principal asX500Principal ()

Get an X500Principal backed by this X500Name. Note that we are using privileged reflection to access the hidden package private constructor in X500Principal.

public int avaSize ()

Return the total number of AVAs contained in all the RDNs of this X500Name.

public X500Name commonAncestor (X500Name other)

Return lowest common ancestor of this name and other name

Parameters
other another X500Name
Returns
  • X500Name of lowest common ancestor; null if none

public int constrains (GeneralNameInterface inputName)

Return constraint type:

  • NAME_DIFF_TYPE = -1: input name is different type from this name (i.e. does not constrain)
  • NAME_MATCH = 0: input name matches this name
  • NAME_NARROWS = 1: input name narrows this name
  • NAME_WIDENS = 2: input name widens this name
  • NAME_SAME_TYPE = 3: input name does not match or narrow this name, & but is same type
. These results are used in checking NameConstraints during certification path verification.

Parameters
inputName to be checked for being constrained
Throws
UnsupportedOperationException if name is not exact match, but narrowing and widening are not supported for this name type.

public void emit (DerOutputStream out)

This method is deprecated.
Use encode() instead

Encodes the name in DER-encoded form.

Parameters
out where to put the DER-encoded X.500 name
Throws
IOException

public void encode (DerOutputStream out)

Encodes the name in DER-encoded form.

Parameters
out where to put the DER-encoded X.500 name
Throws
IOException

public boolean equals (Object obj)

Compares this name with another, for equality.

Parameters
obj the reference object with which to compare.
Returns
  • true iff the names are identical.

public DerValue findMostSpecificAttribute (ObjectIdentifier attribute)

Find the most specific ("last") attribute of the given type.

public String getCommonName ()

Returns a "Common Name" component. If more than one such attribute exists, the topmost one is returned.

Returns
  • "CN=" component of the name, if any.
Throws
IOException

public String getCountry ()

Returns a "Country" name component. If more than one such attribute exists, the topmost one is returned.

Returns
  • "C=" component of the name, if any.
Throws
IOException

public String getDNQualifier ()

Returns a "DN Qualifier" name component. If more than one such component exists, the topmost one is returned.

Returns
  • "DNQ=" component of the name, if any.
Throws
IOException

public String getDomain ()

Returns a "Domain" name component. If more than one such component exists, the topmost one is returned.

Returns
  • "DC=" component of the name, if any.
Throws
IOException

public byte[] getEncoded ()

Gets the name in DER-encoded form.

Returns
  • the DER encoded byte array of this name.
Throws
IOException

public byte[] getEncodedInternal ()

Returned the encoding as an uncloned byte array. Callers must guarantee that they neither modify it not expose it to untrusted code.

Throws
IOException

public String getGeneration ()

Returns a "Generation Qualifier" name component. If more than one such component exists, the topmost one is returned.

Returns
  • "GENERATION=" component of the name, if any.
Throws
IOException

public String getGivenName ()

Returns a "Given Name" name component. If more than one such component exists, the topmost one is returned.

Returns
  • "GIVENNAME=" component of the name, if any.
Throws
IOException

public String getIP ()

Returns an "IP address" name component. If more than one such component exists, the topmost one is returned.

Returns
  • "IP=" component of the name, if any.
Throws
IOException

public String getInitials ()

Returns an "Initials" name component. If more than one such component exists, the topmost one is returned.

Returns
  • "INITIALS=" component of the name, if any.
Throws
IOException

public String getLocality ()

Returns a "Locality" name component. If more than one such component exists, the topmost one is returned.

Returns
  • "L=" component of the name, if any.
Throws
IOException

public String getName ()

Returns the value of toString(). This call is needed to implement the java.security.Principal interface.

Returns
  • the name of this principal.

public String getOrganization ()

Returns an "Organization" name component. If more than one such attribute exists, the topmost one is returned.

Returns
  • "O=" component of the name, if any.
Throws
IOException

public String getOrganizationalUnit ()

Returns an "Organizational Unit" name component. If more than one such attribute exists, the topmost one is returned.

Returns
  • "OU=" component of the name, if any.
Throws
IOException

public String getRFC1779Name (Map<String, String> oidMap)

Returns a string form of the X.500 distinguished name using the algorithm defined in RFC 1779. Attribute type keywords defined in RFC 1779 are emitted, as well as additional keywords contained in the OID/keyword map.

Throws
IllegalArgumentException

public String getRFC1779Name ()

Returns a string form of the X.500 distinguished name using the algorithm defined in RFC 1779. Only standard attribute type keywords defined in RFC 1779 are emitted.

public String getRFC2253CanonicalName ()

public String getRFC2253Name ()

Returns a string form of the X.500 distinguished name using the algorithm defined in RFC 2253. Only standard attribute type keywords defined in RFC 2253 are emitted.

public String getRFC2253Name (Map<String, String> oidMap)

Returns a string form of the X.500 distinguished name using the algorithm defined in RFC 2253. Attribute type keywords defined in RFC 2253 are emitted, as well as additional keywords contained in the OID/keyword map.

public String getState ()

Returns a "State" name component. If more than one such component exists, the topmost one is returned.

Returns
  • "S=" component of the name, if any.
Throws
IOException

public String getSurname ()

Returns a "Surname" name component. If more than one such component exists, the topmost one is returned.

Returns
  • "SURNAME=" component of the name, if any.
Throws
IOException

public int getType ()

Return type of GeneralName.

public int hashCode ()

Calculates a hash code value for the object. Objects which are equal will also have the same hashcode.

Returns
  • a hash code value for this object.

public boolean isEmpty ()

Return whether this X500Name is empty. An X500Name is not empty if it has at least one RDN containing at least one AVA.

public List<RDN> rdns ()

Return an immutable List of all RDNs in this X500Name.

public int size ()

Return the number of RDNs in this X500Name.

public int subtreeDepth ()

Return subtree depth of this name for purposes of determining NameConstraints minimum and maximum bounds and for calculating path lengths in name subtrees.

Throws
UnsupportedOperationException if not supported for this name type

public String toString ()

Returns a string form of the X.500 distinguished name. The format of the string is from RFC 1779. The returned string may contain non-standardised keywords for more readability (keywords from RFCs 1779, 2253, and 3280).

Returns
  • a string representation of the object.