001 /*
002 * Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.security.auth.x500;
027
028 import java.io.*;
029 import java.security.Principal;
030 import java.util.Collections;
031 import java.util.Map;
032 import sun.security.x509.X500Name;
033 import sun.security.util.*;
034
035 /**
036 * <p> This class represents an X.500 <code>Principal</code>.
037 * <code>X500Principal</code>s are represented by distinguished names such as
038 * "CN=Duke, OU=JavaSoft, O=Sun Microsystems, C=US".
039 *
040 * <p> This class can be instantiated by using a string representation
041 * of the distinguished name, or by using the ASN.1 DER encoded byte
042 * representation of the distinguished name. The current specification
043 * for the string representation of a distinguished name is defined in
044 * <a href="http://www.ietf.org/rfc/rfc2253.txt">RFC 2253: Lightweight
045 * Directory Access Protocol (v3): UTF-8 String Representation of
046 * Distinguished Names</a>. This class, however, accepts string formats from
047 * both RFC 2253 and <a href="http://www.ietf.org/rfc/rfc1779.txt">RFC 1779:
048 * A String Representation of Distinguished Names</a>, and also recognizes
049 * attribute type keywords whose OIDs (Object Identifiers) are defined in
050 * <a href="http://www.ietf.org/rfc/rfc3280.txt">RFC 3280: Internet X.509
051 * Public Key Infrastructure Certificate and CRL Profile</a>.
052 *
053 * <p> The string representation for this <code>X500Principal</code>
054 * can be obtained by calling the <code>getName</code> methods.
055 *
056 * <p> Note that the <code>getSubjectX500Principal</code> and
057 * <code>getIssuerX500Principal</code> methods of
058 * <code>X509Certificate</code> return X500Principals representing the
059 * issuer and subject fields of the certificate.
060 *
061 * @version 1.32, 05/05/07
062 * @see java.security.cert.X509Certificate
063 * @since 1.4
064 */
065 public final class X500Principal implements Principal,
066 java.io.Serializable {
067
068 private static final long serialVersionUID = -500463348111345721L;
069
070 /**
071 * RFC 1779 String format of Distinguished Names.
072 */
073 public static final String RFC1779 = "RFC1779";
074 /**
075 * RFC 2253 String format of Distinguished Names.
076 */
077 public static final String RFC2253 = "RFC2253";
078 /**
079 * Canonical String format of Distinguished Names.
080 */
081 public static final String CANONICAL = "CANONICAL";
082
083 /**
084 * The X500Name representing this principal.
085 *
086 * NOTE: this field is reflectively accessed from within X500Name.
087 */
088 private transient X500Name this X500Name;
089
090 /**
091 * Creates an X500Principal by wrapping an X500Name.
092 *
093 * NOTE: The constructor is package private. It is intended to be accessed
094 * using privileged reflection from classes in sun.security.*.
095 * Currently referenced from sun.security.x509.X500Name.asX500Principal().
096 */
097 X500Principal(X500Name x500Name) {
098 this X500Name = x500Name;
099 }
100
101 /**
102 * Creates an <code>X500Principal</code> from a string representation of
103 * an X.500 distinguished name (ex:
104 * "CN=Duke, OU=JavaSoft, O=Sun Microsystems, C=US").
105 * The distinguished name must be specified using the grammar defined in
106 * RFC 1779 or RFC 2253 (either format is acceptable).
107 *
108 * <p>This constructor recognizes the attribute type keywords
109 * defined in RFC 1779 and RFC 2253
110 * (and listed in {@link #getName(String format) getName(String format)}),
111 * as well as the T, DNQ or DNQUALIFIER, SURNAME, GIVENNAME, INITIALS,
112 * GENERATION, EMAILADDRESS, and SERIALNUMBER keywords whose OIDs are
113 * defined in RFC 3280 and its successor.
114 * Any other attribute type must be specified as an OID.
115 *
116 * @param name an X.500 distinguished name in RFC 1779 or RFC 2253 format
117 * @exception NullPointerException if the <code>name</code>
118 * is <code>null</code>
119 * @exception IllegalArgumentException if the <code>name</code>
120 * is improperly specified
121 */
122 public X500Principal(String name) {
123 this (name, (Map<String, String>) Collections.EMPTY_MAP);
124 }
125
126 /**
127 * Creates an <code>X500Principal</code> from a string representation of
128 * an X.500 distinguished name (ex:
129 * "CN=Duke, OU=JavaSoft, O=Sun Microsystems, C=US").
130 * The distinguished name must be specified using the grammar defined in
131 * RFC 1779 or RFC 2253 (either format is acceptable).
132 *
133 * <p> This constructor recognizes the attribute type keywords specified
134 * in {@link #X500Principal(String)} and also recognizes additional
135 * keywords that have entries in the <code>keywordMap</code> parameter.
136 * Keyword entries in the keywordMap take precedence over the default
137 * keywords recognized by <code>X500Principal(String)</code>. Keywords
138 * MUST be specified in all upper-case, otherwise they will be ignored.
139 * Improperly specified keywords are ignored; however if a keyword in the
140 * name maps to an improperly specified OID, an
141 * <code>IllegalArgumentException</code> is thrown. It is permissible to
142 * have 2 different keywords that map to the same OID.
143 *
144 * @param name an X.500 distinguished name in RFC 1779 or RFC 2253 format
145 * @param keywordMap an attribute type keyword map, where each key is a
146 * keyword String that maps to a corresponding object identifier in String
147 * form (a sequence of nonnegative integers separated by periods). The map
148 * may be empty but never <code>null</code>.
149 * @exception NullPointerException if <code>name</code> or
150 * <code>keywordMap</code> is <code>null</code>
151 * @exception IllegalArgumentException if the <code>name</code> is
152 * improperly specified or a keyword in the <code>name</code> maps to an
153 * OID that is not in the correct form
154 * @since 1.6
155 */
156 public X500Principal(String name, Map<String, String> keywordMap) {
157 if (name == null) {
158 throw new NullPointerException(
159 sun.security.util.ResourcesMgr
160 .getString("provided null name"));
161 }
162 if (keywordMap == null) {
163 throw new NullPointerException(
164 sun.security.util.ResourcesMgr
165 .getString("provided null keyword map"));
166 }
167
168 try {
169 this X500Name = new X500Name(name, keywordMap);
170 } catch (Exception e) {
171 IllegalArgumentException iae = new IllegalArgumentException(
172 "improperly specified input name: " + name);
173 iae.initCause(e);
174 throw iae;
175 }
176 }
177
178 /**
179 * Creates an <code>X500Principal</code> from a distinguished name in
180 * ASN.1 DER encoded form. The ASN.1 notation for this structure is as
181 * follows.
182 * <pre><code>
183 * Name ::= CHOICE {
184 * RDNSequence }
185 *
186 * RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
187 *
188 * RelativeDistinguishedName ::=
189 * SET SIZE (1 .. MAX) OF AttributeTypeAndValue
190 *
191 * AttributeTypeAndValue ::= SEQUENCE {
192 * type AttributeType,
193 * value AttributeValue }
194 *
195 * AttributeType ::= OBJECT IDENTIFIER
196 *
197 * AttributeValue ::= ANY DEFINED BY AttributeType
198 * ....
199 * DirectoryString ::= CHOICE {
200 * teletexString TeletexString (SIZE (1..MAX)),
201 * printableString PrintableString (SIZE (1..MAX)),
202 * universalString UniversalString (SIZE (1..MAX)),
203 * utf8String UTF8String (SIZE (1.. MAX)),
204 * bmpString BMPString (SIZE (1..MAX)) }
205 * </code></pre>
206 *
207 * @param name a byte array containing the distinguished name in ASN.1
208 * DER encoded form
209 * @throws IllegalArgumentException if an encoding error occurs
210 * (incorrect form for DN)
211 */
212 public X500Principal(byte[] name) {
213 try {
214 this X500Name = new X500Name(name);
215 } catch (Exception e) {
216 IllegalArgumentException iae = new IllegalArgumentException(
217 "improperly specified input name");
218 iae.initCause(e);
219 throw iae;
220 }
221 }
222
223 /**
224 * Creates an <code>X500Principal</code> from an <code>InputStream</code>
225 * containing the distinguished name in ASN.1 DER encoded form.
226 * The ASN.1 notation for this structure is supplied in the
227 * documentation for
228 * {@link #X500Principal(byte[] name) X500Principal(byte[] name)}.
229 *
230 * <p> The read position of the input stream is positioned
231 * to the next available byte after the encoded distinguished name.
232 *
233 * @param is an <code>InputStream</code> containing the distinguished
234 * name in ASN.1 DER encoded form
235 *
236 * @exception NullPointerException if the <code>InputStream</code>
237 * is <code>null</code>
238 * @exception IllegalArgumentException if an encoding error occurs
239 * (incorrect form for DN)
240 */
241 public X500Principal(InputStream is) {
242 if (is == null) {
243 throw new NullPointerException("provided null input stream");
244 }
245
246 try {
247 if (is.markSupported())
248 is.mark(is.available() + 1);
249 DerValue der = new DerValue(is);
250 this X500Name = new X500Name(der.data);
251 } catch (Exception e) {
252 if (is.markSupported()) {
253 try {
254 is.reset();
255 } catch (IOException ioe) {
256 IllegalArgumentException iae = new IllegalArgumentException(
257 "improperly specified input stream "
258 + ("and unable to reset input stream"));
259 iae.initCause(e);
260 throw iae;
261 }
262 }
263 IllegalArgumentException iae = new IllegalArgumentException(
264 "improperly specified input stream");
265 iae.initCause(e);
266 throw iae;
267 }
268 }
269
270 /**
271 * Returns a string representation of the X.500 distinguished name using
272 * the format defined in RFC 2253.
273 *
274 * <p>This method is equivalent to calling
275 * <code>getName(X500Principal.RFC2253)</code>.
276 *
277 * @return the distinguished name of this <code>X500Principal</code>
278 */
279 public String getName() {
280 return getName(X500Principal.RFC2253);
281 }
282
283 /**
284 * Returns a string representation of the X.500 distinguished name
285 * using the specified format. Valid values for the format are
286 * "RFC1779", "RFC2253", and "CANONICAL" (case insensitive).
287 *
288 * <p> If "RFC1779" is specified as the format,
289 * this method emits the attribute type keywords defined in
290 * RFC 1779 (CN, L, ST, O, OU, C, STREET).
291 * Any other attribute type is emitted as an OID.
292 *
293 * <p> If "RFC2253" is specified as the format,
294 * this method emits the attribute type keywords defined in
295 * RFC 2253 (CN, L, ST, O, OU, C, STREET, DC, UID).
296 * Any other attribute type is emitted as an OID.
297 * Under a strict reading, RFC 2253 only specifies a UTF-8 string
298 * representation. The String returned by this method is the
299 * Unicode string achieved by decoding this UTF-8 representation.
300 *
301 * <p> If "CANONICAL" is specified as the format,
302 * this method returns an RFC 2253 conformant string representation
303 * with the following additional canonicalizations:
304 *
305 * <p><ol>
306 * <li> Leading zeros are removed from attribute types
307 * that are encoded as dotted decimal OIDs
308 * <li> DirectoryString attribute values of type
309 * PrintableString and UTF8String are not
310 * output in hexadecimal format
311 * <li> DirectoryString attribute values of types
312 * other than PrintableString and UTF8String
313 * are output in hexadecimal format
314 * <li> Leading and trailing white space characters
315 * are removed from non-hexadecimal attribute values
316 * (unless the value consists entirely of white space characters)
317 * <li> Internal substrings of one or more white space characters are
318 * converted to a single space in non-hexadecimal
319 * attribute values
320 * <li> Relative Distinguished Names containing more than one
321 * Attribute Value Assertion (AVA) are output in the
322 * following order: an alphabetical ordering of AVAs
323 * containing standard keywords, followed by a numeric
324 * ordering of AVAs containing OID keywords.
325 * <li> The only characters in attribute values that are escaped are
326 * those which section 2.4 of RFC 2253 states must be escaped
327 * (they are escaped using a preceding backslash character)
328 * <li> The entire name is converted to upper case
329 * using <code>String.toUpperCase(Locale.US)</code>
330 * <li> The entire name is converted to lower case
331 * using <code>String.toLowerCase(Locale.US)</code>
332 * <li> The name is finally normalized using normalization form KD,
333 * as described in the Unicode Standard and UAX #15
334 * </ol>
335 *
336 * <p> Additional standard formats may be introduced in the future.
337 *
338 * @param format the format to use
339 *
340 * @return a string representation of this <code>X500Principal</code>
341 * using the specified format
342 * @throws IllegalArgumentException if the specified format is invalid
343 * or null
344 */
345 public String getName(String format) {
346 if (format != null) {
347 if (format.equalsIgnoreCase(RFC1779)) {
348 return this X500Name.getRFC1779Name();
349 } else if (format.equalsIgnoreCase(RFC2253)) {
350 return this X500Name.getRFC2253Name();
351 } else if (format.equalsIgnoreCase(CANONICAL)) {
352 return this X500Name.getRFC2253CanonicalName();
353 }
354 }
355 throw new IllegalArgumentException("invalid format specified");
356 }
357
358 /**
359 * Returns a string representation of the X.500 distinguished name
360 * using the specified format. Valid values for the format are
361 * "RFC1779" and "RFC2253" (case insensitive). "CANONICAL" is not
362 * permitted and an <code>IllegalArgumentException</code> will be thrown.
363 *
364 * <p>This method returns Strings in the format as specified in
365 * {@link #getName(String)} and also emits additional attribute type
366 * keywords for OIDs that have entries in the <code>oidMap</code>
367 * parameter. OID entries in the oidMap take precedence over the default
368 * OIDs recognized by <code>getName(String)</code>.
369 * Improperly specified OIDs are ignored; however if an OID
370 * in the name maps to an improperly specified keyword, an
371 * <code>IllegalArgumentException</code> is thrown.
372 *
373 * <p> Additional standard formats may be introduced in the future.
374 *
375 * <p> Warning: additional attribute type keywords may not be recognized
376 * by other implementations; therefore do not use this method if
377 * you are unsure if these keywords will be recognized by other
378 * implementations.
379 *
380 * @param format the format to use
381 * @param oidMap an OID map, where each key is an object identifier in
382 * String form (a sequence of nonnegative integers separated by periods)
383 * that maps to a corresponding attribute type keyword String.
384 * The map may be empty but never <code>null</code>.
385 * @return a string representation of this <code>X500Principal</code>
386 * using the specified format
387 * @throws IllegalArgumentException if the specified format is invalid,
388 * null, or an OID in the name maps to an improperly specified keyword
389 * @throws NullPointerException if <code>oidMap</code> is <code>null</code>
390 * @since 1.6
391 */
392 public String getName(String format, Map<String, String> oidMap) {
393 if (oidMap == null) {
394 throw new NullPointerException(
395 sun.security.util.ResourcesMgr
396 .getString("provided null OID map"));
397 }
398 if (format != null) {
399 if (format.equalsIgnoreCase(RFC1779)) {
400 return this X500Name.getRFC1779Name(oidMap);
401 } else if (format.equalsIgnoreCase(RFC2253)) {
402 return this X500Name.getRFC2253Name(oidMap);
403 }
404 }
405 throw new IllegalArgumentException("invalid format specified");
406 }
407
408 /**
409 * Returns the distinguished name in ASN.1 DER encoded form. The ASN.1
410 * notation for this structure is supplied in the documentation for
411 * {@link #X500Principal(byte[] name) X500Principal(byte[] name)}.
412 *
413 * <p>Note that the byte array returned is cloned to protect against
414 * subsequent modifications.
415 *
416 * @return a byte array containing the distinguished name in ASN.1 DER
417 * encoded form
418 */
419 public byte[] getEncoded() {
420 try {
421 return this X500Name.getEncoded();
422 } catch (IOException e) {
423 throw new RuntimeException("unable to get encoding", e);
424 }
425 }
426
427 /**
428 * Return a user-friendly string representation of this
429 * <code>X500Principal</code>.
430 *
431 * @return a string representation of this <code>X500Principal</code>
432 */
433 public String toString() {
434 return this X500Name.toString();
435 }
436
437 /**
438 * Compares the specified <code>Object</code> with this
439 * <code>X500Principal</code> for equality.
440 *
441 * <p> Specifically, this method returns <code>true</code> if
442 * the <code>Object</code> <i>o</i> is an <code>X500Principal</code>
443 * and if the respective canonical string representations
444 * (obtained via the <code>getName(X500Principal.CANONICAL)</code> method)
445 * of this object and <i>o</i> are equal.
446 *
447 * <p> This implementation is compliant with the requirements of RFC 3280.
448 *
449 * @param o Object to be compared for equality with this
450 * <code>X500Principal</code>
451 *
452 * @return <code>true</code> if the specified <code>Object</code> is equal
453 * to this <code>X500Principal</code>, <code>false</code> otherwise
454 */
455 public boolean equals(Object o) {
456 if (this == o) {
457 return true;
458 }
459 if (o instanceof X500Principal == false) {
460 return false;
461 }
462 X500Principal other = (X500Principal) o;
463 return this .this X500Name.equals(other.this X500Name);
464 }
465
466 /**
467 * Return a hash code for this <code>X500Principal</code>.
468 *
469 * <p> The hash code is calculated via:
470 * <code>getName(X500Principal.CANONICAL).hashCode()</code>
471 *
472 * @return a hash code for this <code>X500Principal</code>
473 */
474 public int hashCode() {
475 return this X500Name.hashCode();
476 }
477
478 /**
479 * Save the X500Principal object to a stream.
480 *
481 * @serialData this <code>X500Principal</code> is serialized
482 * by writing out its DER-encoded form
483 * (the value of <code>getEncoded</code> is serialized).
484 */
485 private void writeObject(java.io.ObjectOutputStream s)
486 throws IOException {
487 s.writeObject(this X500Name.getEncodedInternal());
488 }
489
490 /**
491 * Reads this object from a stream (i.e., deserializes it).
492 */
493 private void readObject(java.io.ObjectInputStream s)
494 throws java.io.IOException, java.io.NotActiveException,
495 ClassNotFoundException {
496
497 // re-create thisX500Name
498 this X500Name = new X500Name((byte[]) s.readObject());
499 }
500 }
|