/*
* @(#)X500Principal.java 1.25 05/11/17
*
* Copyright 2006 Sun Microsystems, Inc. All rights reserved.
* SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
*/
package javax.security.auth.x500;
import java.io.*;
import java.security.Principal;
import java.util.Collections;
import java.util.Map;
import sun.security.x509.X500Name;
import sun.security.util.*;
/**
* <p> This class represents an X.500 <code>Principal</code>.
* <code>X500Principal</code>s are represented by distinguished names such as
* "CN=Duke, OU=JavaSoft, O=Sun Microsystems, C=US".
*
* <p> This class can be instantiated by using a string representation
* of the distinguished name, or by using the ASN.1 DER encoded byte
* representation of the distinguished name. The current specification
* for the string representation of a distinguished name is defined in
* <a href="http://www.ietf.org/rfc/rfc2253.txt">RFC 2253</a>.
* This class, however, accepts string formats from both RFC 2253 and
* <a href="http://www.ietf.org/rfc/rfc1779.txt">RFC 1779</a>,
* and also recognizes attribute type keywords whose OIDs
* (Object Identifiers) are defined in
* <a href="http://www.ietf.org/rfc/rfc2459.txt">RFC 2459</a>.
*
* <p> The string representation for this <code>X500Principal</code>
* can be obtained by calling the <code>getName</code> methods.
*
* <p> Note that the <code>getSubjectX500Principal</code> and
* <code>getIssuerX500Principal</code> methods of
* <code>X509Certificate</code> return X500Principals representing the
* issuer and subject fields of the certificate.
*
* @version 1.25, 11/17/05
* @see java.security.cert.X509Certificate
* @since 1.4
*/
public final class X500Principal implements Principal, java.io.Serializable {
private static final long serialVersionUID = -500463348111345721L;
/**
* RFC 1779 String format of Distinguished Names.
*/
public static final String RFC1779 = "RFC1779";
/**
* RFC 2253 String format of Distinguished Names.
*/
public static final String RFC2253 = "RFC2253";
/**
* Canonical String format of Distinguished Names.
*/
public static final String CANONICAL = "CANONICAL";
/**
* The X500Name representing this principal.
*
* NOTE: this field is reflectively accessed from within X500Name.
*/
private transient X500Name thisX500Name;
/**
* Creates an X500Principal by wrapping an X500Name.
*
* NOTE: The constructor is package private. It is intended to be accessed
* using privileged reflection from classes in sun.security.*.
* Currently referenced from sun.security.x509.X500Name.asX500Principal().
*/
X500Principal(X500Name x500Name) {
thisX500Name = x500Name;
}
/**
* Creates an <code>X500Principal</code> from a string representation of
* an X.500 distinguished name (ex:
* "CN=Duke, OU=JavaSoft, O=Sun Microsystems, C=US").
* The distinguished name must be specified using the grammar defined in
* RFC 1779 or RFC 2253 (either format is acceptable).
*
* <p>This constructor recognizes the attribute type keywords
* defined in RFC 1779 and RFC 2253
* (and listed in {@link #getName(String format) getName(String format)}),
* as well as the T, DNQ or DNQUALIFIER, SURNAME, GIVENNAME, INITIALS,
* GENERATION, EMAILADDRESS, and SERIALNUMBER keywords whose OIDs are
* defined in RFC 2459 and its successor.
* Any other attribute type must be specified as an OID.
*
* @param name an X.500 distinguished name in RFC 1779 or RFC 2253 format
* @exception NullPointerException if the <code>name</code>
* is <code>null</code>
* @exception IllegalArgumentException if the <code>name</code>
* is improperly specified
*/
public X500Principal(String name) {
this(name, (Map<String, String>) Collections.EMPTY_MAP);
}
/**
* Creates an <code>X500Principal</code> from a string representation of
* an X.500 distinguished name (ex:
* "CN=Duke, OU=JavaSoft, O=Sun Microsystems, C=US").
* The distinguished name must be specified using the grammar defined in
* RFC 1779 or RFC 2253 (either format is acceptable).
*
* <p> This constructor recognizes the attribute type keywords specified
* in {@link #X500Principal(String)} and also recognizes additional
* keywords that have entries in the <code>keywordMap</code> parameter.
* Keyword entries in the keywordMap take precedence over the default
* keywords recognized by <code>X500Principal(String)</code>. Keywords
* MUST be specified in all upper-case, otherwise they will be ignored.
* Improperly specified keywords are ignored; however if a keyword in the
* name maps to an improperly specified OID, an
* <code>IllegalArgumentException</code> is thrown. It is permissible to
* have 2 different keywords that map to the same OID.
*
* @param name an X.500 distinguished name in RFC 1779 or RFC 2253 format
* @param keywordMap an attribute type keyword map, where each key is a
* keyword String that maps to a corresponding object identifier in String
* form (a sequence of nonnegative integers separated by periods). The map
* may be empty but never <code>null</code>.
* @exception NullPointerException if <code>name</code> or
* <code>keywordMap</code> is <code>null</code>
* @exception IllegalArgumentException if the <code>name</code> is
* improperly specified or a keyword in the <code>name</code> maps to an
* OID that is not in the correct form
* @since 1.6
*/
public X500Principal(String name, Map<String, String> keywordMap) {
if (name == null) {
throw new NullPointerException
(sun.security.util.ResourcesMgr.getString
("provided null name"));
}
if (keywordMap == null) {
throw new NullPointerException
(sun.security.util.ResourcesMgr.getString
("provided null keyword map"));
}
try {
thisX500Name = new X500Name(name, keywordMap);
} catch (Exception e) {
IllegalArgumentException iae = new IllegalArgumentException
("improperly specified input name: " + name);
iae.initCause(e);
throw iae;
}
}
/**
* Creates an <code>X500Principal</code> from a distinguished name in
* ASN.1 DER encoded form. The ASN.1 notation for this structure is as
* follows.
* <pre><code>
* Name ::= CHOICE {
* RDNSequence }
*
* RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
*
* RelativeDistinguishedName ::=
* SET SIZE (1 .. MAX) 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)) }
* </code></pre>
*
* @param name a byte array containing the distinguished name in ASN.1
* DER encoded form
* @throws IllegalArgumentException if an encoding error occurs
* (incorrect form for DN)
*/
public X500Principal(byte[] name) {
try {
thisX500Name = new X500Name(name);
} catch (Exception e) {
IllegalArgumentException iae = new IllegalArgumentException
("improperly specified input name");
iae.initCause(e);
throw iae;
}
}
/**
* Creates an <code>X500Principal</code> from an <code>InputStream</code>
* containing the distinguished name in ASN.1 DER encoded form.
* The ASN.1 notation for this structure is supplied in the
* documentation for
* {@link #X500Principal(byte[] name) X500Principal(byte[] name)}.
*
* <p> The read position of the input stream is positioned
* to the next available byte after the encoded distinguished name.
*
* @param is an <code>InputStream</code> containing the distinguished
* name in ASN.1 DER encoded form
*
* @exception NullPointerException if the <code>InputStream</code>
* is <code>null</code>
* @exception IllegalArgumentException if an encoding error occurs
* (incorrect form for DN)
*/
public X500Principal(InputStream is) {
if (is == null) {
throw new NullPointerException("provided null input stream");
}
try {
if (is.markSupported())
is.mark(is.available() + 1);
DerValue der = new DerValue(is);
thisX500Name = new X500Name(der.data);
} catch (Exception e) {
if (is.markSupported()) {
try {
is.reset();
} catch (IOException ioe) {
IllegalArgumentException iae = new IllegalArgumentException
("improperly specified input stream " +
("and unable to reset input stream"));
iae.initCause(e);
throw iae;
}
}
IllegalArgumentException iae = new IllegalArgumentException
("improperly specified input stream");
iae.initCause(e);
throw iae;
}
}
/**
* Returns a string representation of the X.500 distinguished name using
* the format defined in RFC 2253.
*
* <p>This method is equivalent to calling
* <code>getName(X500Principal.RFC2253)</code>.
*
* @return the distinguished name of this <code>X500Principal</code>
*/
public String getName() {
return getName(X500Principal.RFC2253);
}
/**
* Returns a string representation of the X.500 distinguished name
* using the specified format. Valid values for the format are
* "RFC1779", "RFC2253", and "CANONICAL" (case insensitive).
*
* <p> If "RFC1779" is specified as the format,
* this method emits the attribute type keywords defined in
* RFC 1779 (CN, L, ST, O, OU, C, STREET).
* Any other attribute type is emitted as an OID.
*
* <p> If "RFC2253" is specified as the format,
* this method emits the attribute type keywords defined in
* RFC 2253 (CN, L, ST, O, OU, C, STREET, DC, UID).
* Any other attribute type is emitted as an OID.
* Under a strict reading, RFC 2253 only specifies a UTF-8 string
* representation. The String returned by this method is the
* Unicode string achieved by decoding this UTF-8 representation.
*
* <p> If "CANONICAL" is specified as the format,
* this method returns an RFC 2253 conformant string representation
* with the following additional canonicalizations:
*
* <p><ol>
* <li> Leading zeros are removed from attribute types
* that are encoded as dotted decimal OIDs
* <li> DirectoryString attribute values of type
* PrintableString and UTF8String are not
* output in hexadecimal format
* <li> DirectoryString attribute values of types
* other than PrintableString and UTF8String
* are output in hexadecimal format
* <li> Leading and trailing white space characters
* are removed from non-hexadecimal attribute values
* (unless the value consists entirely of white space characters)
* <li> Internal substrings of one or more white space characters are
* converted to a single space in non-hexadecimal
* attribute values
* <li> Relative Distinguished Names containing more than one
* Attribute Value Assertion (AVA) are output in the
* following order: an alphabetical ordering of AVAs
* containing standard keywords, followed by a numeric
* ordering of AVAs containing OID keywords.
* <li> The only characters in attribute values that are escaped are
* those which section 2.4 of RFC 2253 states must be escaped
* (they are escaped using a preceding backslash character)
* <li> The entire name is converted to upper case
* using <code>String.toUpperCase(Locale.US)</code>
* <li> The entire name is converted to lower case
* using <code>String.toLowerCase(Locale.US)</code>
* <li> The name is finally normalized using normalization form KD,
* as described in the Unicode Standard and UAX #15
* </ol>
*
* <p> Additional standard formats may be introduced in the future.
*
* @param format the format to use
*
* @return a string representation of this <code>X500Principal</code>
* using the specified format
* @throws IllegalArgumentException if the specified format is invalid
* or null
*/
public String getName(String format) {
if (format != null) {
if (format.equalsIgnoreCase(RFC1779)) {
return thisX500Name.getRFC1779Name();
} else if (format.equalsIgnoreCase(RFC2253)) {
return thisX500Name.getRFC2253Name();
} else if (format.equalsIgnoreCase(CANONICAL)) {
return thisX500Name.getRFC2253CanonicalName();
}
}
throw new IllegalArgumentException("invalid format specified");
}
/**
* Returns a string representation of the X.500 distinguished name
* using the specified format. Valid values for the format are
* "RFC1779" and "RFC2253" (case insensitive). "CANONICAL" is not
* permitted and an <code>IllegalArgumentException</code> will be thrown.
*
* <p>This method returns Strings in the format as specified in
* {@link #getName(String)} and also emits additional attribute type
* keywords for OIDs that have entries in the <code>oidMap</code>
* parameter. OID entries in the oidMap take precedence over the default
* OIDs recognized by <code>getName(String)</code>.
* Improperly specified OIDs are ignored; however if an OID
* in the name maps to an improperly specified keyword, an
* <code>IllegalArgumentException</code> is thrown.
*
* <p> Additional standard formats may be introduced in the future.
*
* <p> Warning: additional attribute type keywords may not be recognized
* by other implementations; therefore do not use this method if
* you are unsure if these keywords will be recognized by other
* implementations.
*
* @param format the format to use
* @param oidMap an OID map, where each key is an object identifier in
* String form (a sequence of nonnegative integers separated by periods)
* that maps to a corresponding attribute type keyword String.
* The map may be empty but never <code>null</code>.
* @return a string representation of this <code>X500Principal</code>
* using the specified format
* @throws IllegalArgumentException if the specified format is invalid,
* null, or an OID in the name maps to an improperly specified keyword
* @throws NullPointerException if <code>oidMap</code> is <code>null</code>
* @since 1.6
*/
public String getName(String format, Map<String, String> oidMap) {
if (oidMap == null) {
throw new NullPointerException
(sun.security.util.ResourcesMgr.getString
("provided null OID map"));
}
if (format != null) {
if (format.equalsIgnoreCase(RFC1779)) {
return thisX500Name.getRFC1779Name(oidMap);
} else if (format.equalsIgnoreCase(RFC2253)) {
return thisX500Name.getRFC2253Name(oidMap);
}
}
throw new IllegalArgumentException("invalid format specified");
}
/**
* Returns the distinguished name in ASN.1 DER encoded form. The ASN.1
* notation for this structure is supplied in the documentation for
* {@link #X500Principal(byte[] name) X500Principal(byte[] name)}.
*
* <p>Note that the byte array returned is cloned to protect against
* subsequent modifications.
*
* @return a byte array containing the distinguished name in ASN.1 DER
* encoded form
*/
public byte[] getEncoded() {
try {
return thisX500Name.getEncoded();
} catch (IOException e) {
throw new RuntimeException("unable to get encoding", e);
}
}
/**
* Return a user-friendly string representation of this
* <code>X500Principal</code>.
*
* @return a string representation of this <code>X500Principal</code>
*/
public String toString() {
return thisX500Name.toString();
}
/**
* Compares the specified <code>Object</code> with this
* <code>X500Principal</code> for equality.
*
* <p> Specifically, this method returns <code>true</code> if
* the <code>Object</code> <i>o</i> is an <code>X500Principal</code>
* and if the respective canonical string representations
* (obtained via the <code>getName(X500Principal.CANONICAL)</code> method)
* of this object and <i>o</i> are equal.
*
* <p> This implementation is compliant with the requirements of RFC 2459.
*
* @param o Object to be compared for equality with this
* <code>X500Principal</code>
*
* @return <code>true</code> if the specified <code>Object</code> is equal
* to this <code>X500Principal</code>, <code>false</code> otherwise
*/
public boolean equals(Object o) {
if (this == o) {
return true;
}
if (o instanceof X500Principal == false) {
return false;
}
X500Principal other = (X500Principal)o;
return this.thisX500Name.equals(other.thisX500Name);
}
/**
* Return a hash code for this <code>X500Principal</code>.
*
* <p> The hash code is calculated via:
* <code>getName(X500Principal.CANONICAL).hashCode()</code>
*
* @return a hash code for this <code>X500Principal</code>
*/
public int hashCode() {
return thisX500Name.hashCode();
}
/**
* Save the X500Principal object to a stream.
*
* @serialData this <code>X500Principal</code> is serialized
* by writing out its DER-encoded form
* (the value of <code>getEncoded</code> is serialized).
*/
private void writeObject(java.io.ObjectOutputStream s)
throws IOException {
s.writeObject(thisX500Name.getEncodedInternal());
}
/**
* Reads this object from a stream (i.e., deserializes it).
*/
private void readObject(java.io.ObjectInputStream s)
throws java.io.IOException,
java.io.NotActiveException,
ClassNotFoundException {
// re-create thisX500Name
thisX500Name = new X500Name((byte[])s.readObject());
}
}