javax.security.auth.x500.X500Principal Maven / Gradle / Ivy
/*
This is not an official specification document, and usage is restricted.
NOTICE
(c) 2005-2007 Sun Microsystems, Inc. All Rights Reserved.
Neither this file nor any files generated from it describe a complete
specification, and they may only be used as described below. For
example, no permission is given for you to incorporate this file, in
whole or in part, in an implementation of a Java specification.
Sun Microsystems Inc. owns the copyright in this file and it is provided
to you for informative, as opposed to normative, use. The file and any
files generated from it may be used to generate other informative
documentation, such as a unified set of documents of API signatures for
a platform that includes technologies expressed as Java APIs. The file
may also be used to produce "compilation stubs," which allow
applications to be compiled and validated for such platforms.
Any work generated from this file, such as unified javadocs or compiled
stub files, must be accompanied by this notice in its entirety.
This work corresponds to the API signatures of JSR 219: Foundation
Profile 1.1. In the event of a discrepency between this work and the
JSR 219 specification, which is available at
http://www.jcp.org/en/jsr/detail?id=219, the latter takes precedence.
*/
package javax.security.auth.x500;
import java.io.*;
import java.security.Principal;
/**
*
This class represents an X.500 Principal.
* X500Principals are represented by distinguished names such as
* "CN=Duke, OU=JavaSoft, O=Sun Microsystems, C=US".
*
*
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
* RFC 2253.
* This class, however, accepts string formats from both RFC 2253 and
* RFC 1779,
* and also recognizes attribute type keywords whose OIDs
* (Object Identifiers) are defined in
* RFC 2459.
*
*
The string representation for this X500Principal
* can be obtained by calling the getName methods.
*
*
Note that the getSubjectX500Principal and
* getIssuerX500Principal methods of
* X509Certificate return X500Principals representing the
* issuer and subject fields of the certificate.
*
* @version 1.20, 03/12/05
* @see java.security.cert.X509Certificate
* @since 1.4
*/
public final class X500Principal implements Principal, 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";
/**
* Creates an X500Principal 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).
*
*
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 name
* is null
* @exception IllegalArgumentException if the name
* is improperly specified
*/
public X500Principal(String name) { }
/**
* Creates an X500Principal from a distinguished name in
* ASN.1 DER encoded form. The ASN.1 notation for this structure is as
* follows.
*
* 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)) }
*
*
* @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) { }
/**
* Creates an X500Principal from an InputStream
* 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)}.
*
* The read position of the input stream is positioned
* to the next available byte after the encoded distinguished name.
*
* @param is an InputStream containing the distinguished
* name in ASN.1 DER encoded form
*
* @exception NullPointerException if the InputStream
* is null
* @exception IllegalArgumentException if an encoding error occurs
* (incorrect form for DN)
*/
public X500Principal(InputStream is) { }
/**
* Returns a string representation of the X.500 distinguished name using
* the format defined in RFC 2253.
*
*
This method is equivalent to calling
* getName(X500Principal.RFC2253).
*
* @return the distinguished name of this X500Principal
*/
public String getName() {
return null;
}
/**
* 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).
*
*
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.
*
*
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.
*
*
If "CANONICAL" is specified as the format,
* this method returns an RFC 2253 conformant string representation
* with the following additional canonicalizations:
*
*
* - Leading zeros are removed from attribute types
* that are encoded as dotted decimal OIDs
*
- DirectoryString attribute values of type
* PrintableString and UTF8String are not
* output in hexadecimal format
*
- DirectoryString attribute values of types
* other than PrintableString and UTF8String
* are output in hexadecimal format
*
- Leading and trailing white space characters
* are removed from non-hexadecimal attribute values
* (unless the value consists entirely of white space characters)
*
- Internal substrings of one or more white space characters are
* converted to a single space in non-hexadecimal
* attribute values
*
- 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.
*
- 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)
*
- The entire name is converted to upper case
* using
String.toUpperCase(Locale.US)
* - The entire name is converted to lower case
* using
String.toLowerCase(Locale.US)
* - The name is finally normalized using normalization form KD,
* as described in the Unicode Standard and UAX #15
*
*
* Additional standard formats may be introduced in the future.
*
* @param format the format to use
*
* @return a string representation of this X500Principal
* using the specified format
* @throws IllegalArgumentException if the specified format is invalid
*/
public String getName(String format) {
return null;
}
/**
* 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)}.
*
*
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() {
return null;
}
/**
* Return a user-friendly string representation of this
* X500Principal.
*
* @return a string representation of this X500Principal
*/
public String toString() {
return null;
}
/**
* Compares the specified Object with this
* X500Principal for equality.
*
*
Specifically, this method returns true if
* the Object o is an X500Principal
* and if the respective canonical string representations
* (obtained via the getName(X500Principal.CANONICAL) method)
* of this object and o are equal.
*
*
This implementation is compliant with the requirements of RFC 2459.
*
* @param o Object to be compared for equality with this
* X500Principal
*
* @return true if the specified Object is equal
* to this X500Principal, false otherwise
*/
public boolean equals(Object o) {
return false;
}
/**
* Return a hash code for this X500Principal.
*
*
The hash code is calculated via:
* getName(X500Principal.CANONICAL).hashCode()
*
* @return a hash code for this X500Principal
*/
public int hashCode() {
return 0;
}
/**
* Reads this object from a stream (i.e., deserializes it).
*/
private void readObject(ObjectInputStream s)
throws IOException, NotActiveException, ClassNotFoundException
{ }
/**
* Save the X500Principal object to a stream.
*
* @serialData this X500Principal is serialized
* by writing out its DER-encoded form
* (the value of getEncoded is serialized).
*/
private void writeObject(ObjectOutputStream s) throws IOException { }
}