View Javadoc
1   /*
2    * Copyright (c) 1996, 2011, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package sun.security.x509;
27  
28  import java.io.ByteArrayOutputStream;
29  import java.io.IOException;
30  import java.io.OutputStream;
31  import java.io.Reader;
32  import java.security.AccessController;
33  import java.text.Normalizer;
34  import java.util.*;
35  
36  import sun.security.action.GetBooleanAction;
37  import sun.security.util.*;
38  import sun.security.pkcs.PKCS9Attribute;
39  
40  
41  /**
42   * X.500 Attribute-Value-Assertion (AVA):  an attribute, as identified by
43   * some attribute ID, has some particular value.  Values are as a rule ASN.1
44   * printable strings.  A conventional set of type IDs is recognized when
45   * parsing (and generating) RFC 1779, 2253 or 4514 syntax strings.
46   *
47   * <P>AVAs are components of X.500 relative names.  Think of them as being
48   * individual fields of a database record.  The attribute ID is how you
49   * identify the field, and the value is part of a particular record.
50   * <p>
51   * Note that instances of this class are immutable.
52   *
53   * @see X500Name
54   * @see RDN
55   *
56   *
57   * @author David Brownell
58   * @author Amit Kapoor
59   * @author Hemma Prafullchandra
60   */
61  public class AVA implements DerEncoder {
62  
63      private static final Debug debug = Debug.getInstance("x509", "\t[AVA]");
64      // See CR 6391482: if enabled this flag preserves the old but incorrect
65      // PrintableString encoding for DomainComponent. It may need to be set to
66      // avoid breaking preexisting certificates generated with sun.security APIs.
67      private static final boolean PRESERVE_OLD_DC_ENCODING =
68          AccessController.doPrivileged(new GetBooleanAction
69              ("com.sun.security.preserveOldDCEncoding"));
70  
71      /**
72       * DEFAULT format allows both RFC1779 and RFC2253 syntax and
73       * additional keywords.
74       */
75      final static int DEFAULT = 1;
76      /**
77       * RFC1779 specifies format according to RFC1779.
78       */
79      final static int RFC1779 = 2;
80      /**
81       * RFC2253 specifies format according to RFC2253.
82       */
83      final static int RFC2253 = 3;
84  
85      // currently not private, accessed directly from RDN
86      final ObjectIdentifier oid;
87      final DerValue value;
88  
89      /*
90       * If the value has any of these characters in it, it must be quoted.
91       * Backslash and quote characters must also be individually escaped.
92       * Leading and trailing spaces, also multiple internal spaces, also
93       * call for quoting the whole string.
94       */
95      private static final String specialChars1779 = ",=\n+<>#;\\\"";
96  
97      /*
98       * In RFC2253, if the value has any of these characters in it, it
99       * must be quoted by a preceding \.
100      */
101     private static final String specialChars2253 = ",=+<>#;\\\"";
102 
103     /*
104      * includes special chars from RFC1779 and RFC2253, as well as ' ' from
105      * RFC 4514.
106      */
107     private static final String specialCharsDefault = ",=\n+<>#;\\\" ";
108     private static final String escapedDefault = ",+<>;\"";
109 
110     /*
111      * Values that aren't printable strings are emitted as BER-encoded
112      * hex data.
113      */
114     private static final String hexDigits = "0123456789ABCDEF";
115 
116     public AVA(ObjectIdentifier type, DerValue val) {
117         if ((type == null) || (val == null)) {
118             throw new NullPointerException();
119         }
120         oid = type;
121         value = val;
122     }
123 
124     /**
125      * Parse an RFC 1779, 2253 or 4514 style AVA string:  CN=fee fie foe fum
126      * or perhaps with quotes.  Not all defined AVA tags are supported;
127      * of current note are X.400 related ones (PRMD, ADMD, etc).
128      *
129      * This terminates at unescaped AVA separators ("+") or RDN
130      * separators (",", ";"), and removes cosmetic whitespace at the end of
131      * values.
132      */
133     AVA(Reader in) throws IOException {
134         this(in, DEFAULT);
135     }
136 
137     /**
138      * Parse an RFC 1779, 2253 or 4514 style AVA string:  CN=fee fie foe fum
139      * or perhaps with quotes. Additional keywords can be specified in the
140      * keyword/OID map.
141      *
142      * This terminates at unescaped AVA separators ("+") or RDN
143      * separators (",", ";"), and removes cosmetic whitespace at the end of
144      * values.
145      */
146     AVA(Reader in, Map<String, String> keywordMap) throws IOException {
147         this(in, DEFAULT, keywordMap);
148     }
149 
150     /**
151      * Parse an AVA string formatted according to format.
152      */
153     AVA(Reader in, int format) throws IOException {
154         this(in, format, Collections.<String, String>emptyMap());
155     }
156 
157     /**
158      * Parse an AVA string formatted according to format.
159      *
160      * @param in Reader containing AVA String
161      * @param format parsing format
162      * @param keywordMap a Map where a keyword String maps to a corresponding
163      *   OID String. Each AVA keyword will be mapped to the corresponding OID.
164      *   If an entry does not exist, it will fallback to the builtin
165      *   keyword/OID mapping.
166      * @throws IOException if the AVA String is not valid in the specified
167      *   format or an OID String from the keywordMap is improperly formatted
168      */
169     AVA(Reader in, int format, Map<String, String> keywordMap)
170         throws IOException {
171         // assume format is one of DEFAULT or RFC2253
172 
173         StringBuilder   temp = new StringBuilder();
174         int             c;
175 
176         /*
177          * First get the keyword indicating the attribute's type,
178          * and map it to the appropriate OID.
179          */
180         while (true) {
181             c = readChar(in, "Incorrect AVA format");
182             if (c == '=') {
183                 break;
184             }
185             temp.append((char)c);
186         }
187 
188         oid = AVAKeyword.getOID(temp.toString(), format, keywordMap);
189 
190         /*
191          * Now parse the value.  "#hex", a quoted string, or a string
192          * terminated by "+", ",", ";".  Whitespace before or after
193          * the value is stripped away unless format is RFC2253.
194          */
195         temp.setLength(0);
196         if (format == RFC2253) {
197             // read next character
198             c = in.read();
199             if (c == ' ') {
200                 throw new IOException("Incorrect AVA RFC2253 format - " +
201                                       "leading space must be escaped");
202             }
203         } else {
204             // read next character skipping whitespace
205             do {
206                 c = in.read();
207             } while ((c == ' ') || (c == '\n'));
208         }
209         if (c == -1) {
210             // empty value
211             value = new DerValue("");
212             return;
213         }
214 
215         if (c == '#') {
216             value = parseHexString(in, format);
217         } else if ((c == '"') && (format != RFC2253)) {
218             value = parseQuotedString(in, temp);
219         } else {
220             value = parseString(in, c, format, temp);
221         }
222     }
223 
224     /**
225      * Get the ObjectIdentifier of this AVA.
226      */
227     public ObjectIdentifier getObjectIdentifier() {
228         return oid;
229     }
230 
231     /**
232      * Get the value of this AVA as a DerValue.
233      */
234     public DerValue getDerValue() {
235         return value;
236     }
237 
238     /**
239      * Get the value of this AVA as a String.
240      *
241      * @exception RuntimeException if we could not obtain the string form
242      *    (should not occur)
243      */
244     public String getValueString() {
245         try {
246             String s = value.getAsString();
247             if (s == null) {
248                 throw new RuntimeException("AVA string is null");
249             }
250             return s;
251         } catch (IOException e) {
252             // should not occur
253             throw new RuntimeException("AVA error: " + e, e);
254         }
255     }
256 
257     private static DerValue parseHexString
258         (Reader in, int format) throws IOException {
259 
260         int c;
261         ByteArrayOutputStream baos = new ByteArrayOutputStream();
262         byte b = 0;
263         int cNdx = 0;
264         while (true) {
265             c = in.read();
266 
267             if (isTerminator(c, format)) {
268                 break;
269             }
270 
271             int cVal = hexDigits.indexOf(Character.toUpperCase((char)c));
272 
273             if (cVal == -1) {
274                 throw new IOException("AVA parse, invalid hex " +
275                                               "digit: "+ (char)c);
276             }
277 
278             if ((cNdx % 2) == 1) {
279                 b = (byte)((b * 16) + (byte)(cVal));
280                 baos.write(b);
281             } else {
282                 b = (byte)(cVal);
283             }
284             cNdx++;
285         }
286 
287         // throw exception if no hex digits
288         if (cNdx == 0) {
289             throw new IOException("AVA parse, zero hex digits");
290         }
291 
292         // throw exception if odd number of hex digits
293         if (cNdx % 2 == 1) {
294             throw new IOException("AVA parse, odd number of hex digits");
295         }
296 
297         return new DerValue(baos.toByteArray());
298     }
299 
300     private DerValue parseQuotedString
301         (Reader in, StringBuilder temp) throws IOException {
302 
303         // RFC1779 specifies that an entire RDN may be enclosed in double
304         // quotes. In this case the syntax is any sequence of
305         // backslash-specialChar, backslash-backslash,
306         // backslash-doublequote, or character other than backslash or
307         // doublequote.
308         int c = readChar(in, "Quoted string did not end in quote");
309 
310         List<Byte> embeddedHex = new ArrayList<Byte>();
311         boolean isPrintableString = true;
312         while (c != '"') {
313             if (c == '\\') {
314                 c = readChar(in, "Quoted string did not end in quote");
315 
316                 // check for embedded hex pairs
317                 Byte hexByte = null;
318                 if ((hexByte = getEmbeddedHexPair(c, in)) != null) {
319 
320                     // always encode AVAs with embedded hex as UTF8
321                     isPrintableString = false;
322 
323                     // append consecutive embedded hex
324                     // as single string later
325                     embeddedHex.add(hexByte);
326                     c = in.read();
327                     continue;
328                 }
329 
330                 if (specialChars1779.indexOf((char)c) < 0) {
331                     throw new IOException
332                         ("Invalid escaped character in AVA: " +
333                         (char)c);
334                 }
335             }
336 
337             // add embedded hex bytes before next char
338             if (embeddedHex.size() > 0) {
339                 String hexString = getEmbeddedHexString(embeddedHex);
340                 temp.append(hexString);
341                 embeddedHex.clear();
342             }
343 
344             // check for non-PrintableString chars
345             isPrintableString &= DerValue.isPrintableStringChar((char)c);
346             temp.append((char)c);
347             c = readChar(in, "Quoted string did not end in quote");
348         }
349 
350         // add trailing embedded hex bytes
351         if (embeddedHex.size() > 0) {
352             String hexString = getEmbeddedHexString(embeddedHex);
353             temp.append(hexString);
354             embeddedHex.clear();
355         }
356 
357         do {
358             c = in.read();
359         } while ((c == '\n') || (c == ' '));
360         if (c != -1) {
361             throw new IOException("AVA had characters other than "
362                     + "whitespace after terminating quote");
363         }
364 
365         // encode as PrintableString unless value contains
366         // non-PrintableString chars
367         if (this.oid.equals((Object)PKCS9Attribute.EMAIL_ADDRESS_OID) ||
368             (this.oid.equals((Object)X500Name.DOMAIN_COMPONENT_OID) &&
369                 PRESERVE_OLD_DC_ENCODING == false)) {
370             // EmailAddress and DomainComponent must be IA5String
371             return new DerValue(DerValue.tag_IA5String,
372                                         temp.toString().trim());
373         } else if (isPrintableString) {
374             return new DerValue(temp.toString().trim());
375         } else {
376             return new DerValue(DerValue.tag_UTF8String,
377                                         temp.toString().trim());
378         }
379     }
380 
381     private DerValue parseString
382         (Reader in, int c, int format, StringBuilder temp) throws IOException {
383 
384         List<Byte> embeddedHex = new ArrayList<>();
385         boolean isPrintableString = true;
386         boolean escape = false;
387         boolean leadingChar = true;
388         int spaceCount = 0;
389         do {
390             escape = false;
391             if (c == '\\') {
392                 escape = true;
393                 c = readChar(in, "Invalid trailing backslash");
394 
395                 // check for embedded hex pairs
396                 Byte hexByte = null;
397                 if ((hexByte = getEmbeddedHexPair(c, in)) != null) {
398 
399                     // always encode AVAs with embedded hex as UTF8
400                     isPrintableString = false;
401 
402                     // append consecutive embedded hex
403                     // as single string later
404                     embeddedHex.add(hexByte);
405                     c = in.read();
406                     leadingChar = false;
407                     continue;
408                 }
409 
410                 // check if character was improperly escaped
411                 if (format == DEFAULT &&
412                        specialCharsDefault.indexOf((char)c) == -1) {
413                     throw new IOException
414                         ("Invalid escaped character in AVA: '" +
415                         (char)c + "'");
416                 } else if (format == RFC2253) {
417                     if (c == ' ') {
418                         // only leading/trailing space can be escaped
419                         if (!leadingChar && !trailingSpace(in)) {
420                             throw new IOException
421                                     ("Invalid escaped space character " +
422                                     "in AVA.  Only a leading or trailing " +
423                                     "space character can be escaped.");
424                         }
425                     } else if (c == '#') {
426                         // only leading '#' can be escaped
427                         if (!leadingChar) {
428                             throw new IOException
429                                 ("Invalid escaped '#' character in AVA.  " +
430                                 "Only a leading '#' can be escaped.");
431                         }
432                     } else if (specialChars2253.indexOf((char)c) == -1) {
433                         throw new IOException
434                                 ("Invalid escaped character in AVA: '" +
435                                 (char)c + "'");
436                     }
437                 }
438             } else {
439                 // check if character should have been escaped
440                 if (format == RFC2253) {
441                     if (specialChars2253.indexOf((char)c) != -1) {
442                         throw new IOException
443                                 ("Character '" + (char)c +
444                                  "' in AVA appears without escape");
445                     }
446                 } else if (escapedDefault.indexOf((char)c) != -1) {
447                     throw new IOException
448                             ("Character '" + (char)c +
449                             "' in AVA appears without escape");
450                 }
451             }
452 
453             // add embedded hex bytes before next char
454             if (embeddedHex.size() > 0) {
455                 // add space(s) before embedded hex bytes
456                 for (int i = 0; i < spaceCount; i++) {
457                     temp.append(" ");
458                 }
459                 spaceCount = 0;
460 
461                 String hexString = getEmbeddedHexString(embeddedHex);
462                 temp.append(hexString);
463                 embeddedHex.clear();
464             }
465 
466             // check for non-PrintableString chars
467             isPrintableString &= DerValue.isPrintableStringChar((char)c);
468             if (c == ' ' && escape == false) {
469                 // do not add non-escaped spaces yet
470                 // (non-escaped trailing spaces are ignored)
471                 spaceCount++;
472             } else {
473                 // add space(s)
474                 for (int i = 0; i < spaceCount; i++) {
475                     temp.append(" ");
476                 }
477                 spaceCount = 0;
478                 temp.append((char)c);
479             }
480             c = in.read();
481             leadingChar = false;
482         } while (isTerminator(c, format) == false);
483 
484         if (format == RFC2253 && spaceCount > 0) {
485             throw new IOException("Incorrect AVA RFC2253 format - " +
486                                         "trailing space must be escaped");
487         }
488 
489         // add trailing embedded hex bytes
490         if (embeddedHex.size() > 0) {
491             String hexString = getEmbeddedHexString(embeddedHex);
492             temp.append(hexString);
493             embeddedHex.clear();
494         }
495 
496         // encode as PrintableString unless value contains
497         // non-PrintableString chars
498         if (this.oid.equals((Object)PKCS9Attribute.EMAIL_ADDRESS_OID) ||
499             (this.oid.equals((Object)X500Name.DOMAIN_COMPONENT_OID) &&
500                 PRESERVE_OLD_DC_ENCODING == false)) {
501             // EmailAddress and DomainComponent must be IA5String
502             return new DerValue(DerValue.tag_IA5String, temp.toString());
503         } else if (isPrintableString) {
504             return new DerValue(temp.toString());
505         } else {
506             return new DerValue(DerValue.tag_UTF8String, temp.toString());
507         }
508     }
509 
510     private static Byte getEmbeddedHexPair(int c1, Reader in)
511         throws IOException {
512 
513         if (hexDigits.indexOf(Character.toUpperCase((char)c1)) >= 0) {
514             int c2 = readChar(in, "unexpected EOF - " +
515                         "escaped hex value must include two valid digits");
516 
517             if (hexDigits.indexOf(Character.toUpperCase((char)c2)) >= 0) {
518                 int hi = Character.digit((char)c1, 16);
519                 int lo = Character.digit((char)c2, 16);
520                 return new Byte((byte)((hi<<4) + lo));
521             } else {
522                 throw new IOException
523                         ("escaped hex value must include two valid digits");
524             }
525         }
526         return null;
527     }
528 
529     private static String getEmbeddedHexString(List<Byte> hexList)
530                                                 throws IOException {
531         int n = hexList.size();
532         byte[] hexBytes = new byte[n];
533         for (int i = 0; i < n; i++) {
534                 hexBytes[i] = hexList.get(i).byteValue();
535         }
536         return new String(hexBytes, "UTF8");
537     }
538 
539     private static boolean isTerminator(int ch, int format) {
540         switch (ch) {
541         case -1:
542         case '+':
543         case ',':
544             return true;
545         case ';':
546             return format != RFC2253;
547         default:
548             return false;
549         }
550     }
551 
552     private static int readChar(Reader in, String errMsg) throws IOException {
553         int c = in.read();
554         if (c == -1) {
555             throw new IOException(errMsg);
556         }
557         return c;
558     }
559 
560     private static boolean trailingSpace(Reader in) throws IOException {
561 
562         boolean trailing = false;
563 
564         if (!in.markSupported()) {
565             // oh well
566             return true;
567         } else {
568             // make readAheadLimit huge -
569             // in practice, AVA was passed a StringReader from X500Name,
570             // and StringReader ignores readAheadLimit anyways
571             in.mark(9999);
572             while (true) {
573                 int nextChar = in.read();
574                 if (nextChar == -1) {
575                     trailing = true;
576                     break;
577                 } else if (nextChar == ' ') {
578                     continue;
579                 } else if (nextChar == '\\') {
580                     int followingChar = in.read();
581                     if (followingChar != ' ') {
582                         trailing = false;
583                         break;
584                     }
585                 } else {
586                     trailing = false;
587                     break;
588                 }
589             }
590 
591             in.reset();
592             return trailing;
593         }
594     }
595 
596     AVA(DerValue derval) throws IOException {
597         // Individual attribute value assertions are SEQUENCE of two values.
598         // That'd be a "struct" outside of ASN.1.
599         if (derval.tag != DerValue.tag_Sequence) {
600             throw new IOException("AVA not a sequence");
601         }
602         oid = X500Name.intern(derval.data.getOID());
603         value = derval.data.getDerValue();
604 
605         if (derval.data.available() != 0) {
606             throw new IOException("AVA, extra bytes = "
607                 + derval.data.available());
608         }
609     }
610 
611     AVA(DerInputStream in) throws IOException {
612         this(in.getDerValue());
613     }
614 
615     public boolean equals(Object obj) {
616         if (this == obj) {
617             return true;
618         }
619         if (obj instanceof AVA == false) {
620             return false;
621         }
622         AVA other = (AVA)obj;
623         return this.toRFC2253CanonicalString().equals
624                                 (other.toRFC2253CanonicalString());
625     }
626 
627     /**
628      * Returns a hashcode for this AVA.
629      *
630      * @return a hashcode for this AVA.
631      */
632     public int hashCode() {
633         return toRFC2253CanonicalString().hashCode();
634     }
635 
636     /*
637      * AVAs are encoded as a SEQUENCE of two elements.
638      */
639     public void encode(DerOutputStream out) throws IOException {
640         derEncode(out);
641     }
642 
643     /**
644      * DER encode this object onto an output stream.
645      * Implements the <code>DerEncoder</code> interface.
646      *
647      * @param out
648      * the output stream on which to write the DER encoding.
649      *
650      * @exception IOException on encoding error.
651      */
652     public void derEncode(OutputStream out) throws IOException {
653         DerOutputStream         tmp = new DerOutputStream();
654         DerOutputStream         tmp2 = new DerOutputStream();
655 
656         tmp.putOID(oid);
657         value.encode(tmp);
658         tmp2.write(DerValue.tag_Sequence, tmp);
659         out.write(tmp2.toByteArray());
660     }
661 
662     private String toKeyword(int format, Map<String, String> oidMap) {
663         return AVAKeyword.getKeyword(oid, format, oidMap);
664     }
665 
666     /**
667      * Returns a printable form of this attribute, using RFC 1779
668      * syntax for individual attribute/value assertions.
669      */
670     public String toString() {
671         return toKeywordValueString
672             (toKeyword(DEFAULT, Collections.<String, String>emptyMap()));
673     }
674 
675     /**
676      * Returns a printable form of this attribute, using RFC 1779
677      * syntax for individual attribute/value assertions. It only
678      * emits standardised keywords.
679      */
680     public String toRFC1779String() {
681         return toRFC1779String(Collections.<String, String>emptyMap());
682     }
683 
684     /**
685      * Returns a printable form of this attribute, using RFC 1779
686      * syntax for individual attribute/value assertions. It
687      * emits standardised keywords, as well as keywords contained in the
688      * OID/keyword map.
689      */
690     public String toRFC1779String(Map<String, String> oidMap) {
691         return toKeywordValueString(toKeyword(RFC1779, oidMap));
692     }
693 
694     /**
695      * Returns a printable form of this attribute, using RFC 2253
696      * syntax for individual attribute/value assertions. It only
697      * emits standardised keywords.
698      */
699     public String toRFC2253String() {
700         return toRFC2253String(Collections.<String, String>emptyMap());
701     }
702 
703     /**
704      * Returns a printable form of this attribute, using RFC 2253
705      * syntax for individual attribute/value assertions. It
706      * emits standardised keywords, as well as keywords contained in the
707      * OID/keyword map.
708      */
709     public String toRFC2253String(Map<String, String> oidMap) {
710         /*
711          * Section 2.3: The AttributeTypeAndValue is encoded as the string
712          * representation of the AttributeType, followed by an equals character
713          * ('=' ASCII 61), followed by the string representation of the
714          * AttributeValue. The encoding of the AttributeValue is given in
715          * section 2.4.
716          */
717         StringBuilder typeAndValue = new StringBuilder(100);
718         typeAndValue.append(toKeyword(RFC2253, oidMap));
719         typeAndValue.append('=');
720 
721         /*
722          * Section 2.4: Converting an AttributeValue from ASN.1 to a String.
723          * If the AttributeValue is of a type which does not have a string
724          * representation defined for it, then it is simply encoded as an
725          * octothorpe character ('#' ASCII 35) followed by the hexadecimal
726          * representation of each of the bytes of the BER encoding of the X.500
727          * AttributeValue.  This form SHOULD be used if the AttributeType is of
728          * the dotted-decimal form.
729          */
730         if ((typeAndValue.charAt(0) >= '0' && typeAndValue.charAt(0) <= '9') ||
731             !isDerString(value, false))
732         {
733             byte[] data = null;
734             try {
735                 data = value.toByteArray();
736             } catch (IOException ie) {
737                 throw new IllegalArgumentException("DER Value conversion");
738             }
739             typeAndValue.append('#');
740             for (int j = 0; j < data.length; j++) {
741                 byte b = data[j];
742                 typeAndValue.append(Character.forDigit(0xF & (b >>> 4), 16));
743                 typeAndValue.append(Character.forDigit(0xF & b, 16));
744             }
745         } else {
746             /*
747              * 2.4 (cont): Otherwise, if the AttributeValue is of a type which
748              * has a string representation, the value is converted first to a
749              * UTF-8 string according to its syntax specification.
750              *
751              * NOTE: this implementation only emits DirectoryStrings of the
752              * types returned by isDerString().
753              */
754             String valStr = null;
755             try {
756                 valStr = new String(value.getDataBytes(), "UTF8");
757             } catch (IOException ie) {
758                 throw new IllegalArgumentException("DER Value conversion");
759             }
760 
761             /*
762              * 2.4 (cont): If the UTF-8 string does not have any of the
763              * following characters which need escaping, then that string can be
764              * used as the string representation of the value.
765              *
766              *   o   a space or "#" character occurring at the beginning of the
767              *       string
768              *   o   a space character occurring at the end of the string
769              *   o   one of the characters ",", "+", """, "\", "<", ">" or ";"
770              *
771              * Implementations MAY escape other characters.
772              *
773              * NOTE: this implementation also recognizes "=" and "#" as
774              * characters which need escaping, and null which is escaped as
775              * '\00' (see RFC 4514).
776              *
777              * If a character to be escaped is one of the list shown above, then
778              * it is prefixed by a backslash ('\' ASCII 92).
779              *
780              * Otherwise the character to be escaped is replaced by a backslash
781              * and two hex digits, which form a single byte in the code of the
782              * character.
783              */
784             final String escapees = ",=+<>#;\"\\";
785             StringBuilder sbuffer = new StringBuilder();
786 
787             for (int i = 0; i < valStr.length(); i++) {
788                 char c = valStr.charAt(i);
789                 if (DerValue.isPrintableStringChar(c) ||
790                     escapees.indexOf(c) >= 0) {
791 
792                     // escape escapees
793                     if (escapees.indexOf(c) >= 0) {
794                         sbuffer.append('\\');
795                     }
796 
797                     // append printable/escaped char
798                     sbuffer.append(c);
799 
800                 } else if (c == '\u0000') {
801                     // escape null character
802                     sbuffer.append("\\00");
803 
804                 } else if (debug != null && Debug.isOn("ava")) {
805 
806                     // embed non-printable/non-escaped char
807                     // as escaped hex pairs for debugging
808                     byte[] valueBytes = null;
809                     try {
810                         valueBytes = Character.toString(c).getBytes("UTF8");
811                     } catch (IOException ie) {
812                         throw new IllegalArgumentException
813                                         ("DER Value conversion");
814                     }
815                     for (int j = 0; j < valueBytes.length; j++) {
816                         sbuffer.append('\\');
817                         char hexChar = Character.forDigit
818                                 (0xF & (valueBytes[j] >>> 4), 16);
819                         sbuffer.append(Character.toUpperCase(hexChar));
820                         hexChar = Character.forDigit
821                                 (0xF & (valueBytes[j]), 16);
822                         sbuffer.append(Character.toUpperCase(hexChar));
823                     }
824                 } else {
825 
826                     // append non-printable/non-escaped char
827                     sbuffer.append(c);
828                 }
829             }
830 
831             char[] chars = sbuffer.toString().toCharArray();
832             sbuffer = new StringBuilder();
833 
834             // Find leading and trailing whitespace.
835             int lead;   // index of first char that is not leading whitespace
836             for (lead = 0; lead < chars.length; lead++) {
837                 if (chars[lead] != ' ' && chars[lead] != '\r') {
838                     break;
839                 }
840             }
841             int trail;  // index of last char that is not trailing whitespace
842             for (trail = chars.length - 1; trail >= 0; trail--) {
843                 if (chars[trail] != ' ' && chars[trail] != '\r') {
844                     break;
845                 }
846             }
847 
848             // escape leading and trailing whitespace
849             for (int i = 0; i < chars.length; i++) {
850                 char c = chars[i];
851                 if (i < lead || i > trail) {
852                     sbuffer.append('\\');
853                 }
854                 sbuffer.append(c);
855             }
856             typeAndValue.append(sbuffer.toString());
857         }
858         return typeAndValue.toString();
859     }
860 
861     public String toRFC2253CanonicalString() {
862         /*
863          * Section 2.3: The AttributeTypeAndValue is encoded as the string
864          * representation of the AttributeType, followed by an equals character
865          * ('=' ASCII 61), followed by the string representation of the
866          * AttributeValue. The encoding of the AttributeValue is given in
867          * section 2.4.
868          */
869         StringBuilder typeAndValue = new StringBuilder(40);
870         typeAndValue.append
871             (toKeyword(RFC2253, Collections.<String, String>emptyMap()));
872         typeAndValue.append('=');
873 
874         /*
875          * Section 2.4: Converting an AttributeValue from ASN.1 to a String.
876          * If the AttributeValue is of a type which does not have a string
877          * representation defined for it, then it is simply encoded as an
878          * octothorpe character ('#' ASCII 35) followed by the hexadecimal
879          * representation of each of the bytes of the BER encoding of the X.500
880          * AttributeValue.  This form SHOULD be used if the AttributeType is of
881          * the dotted-decimal form.
882          */
883         if ((typeAndValue.charAt(0) >= '0' && typeAndValue.charAt(0) <= '9') ||
884             !isDerString(value, true))
885         {
886             byte[] data = null;
887             try {
888                 data = value.toByteArray();
889             } catch (IOException ie) {
890                 throw new IllegalArgumentException("DER Value conversion");
891             }
892             typeAndValue.append('#');
893             for (int j = 0; j < data.length; j++) {
894                 byte b = data[j];
895                 typeAndValue.append(Character.forDigit(0xF & (b >>> 4), 16));
896                 typeAndValue.append(Character.forDigit(0xF & b, 16));
897             }
898         } else {
899             /*
900              * 2.4 (cont): Otherwise, if the AttributeValue is of a type which
901              * has a string representation, the value is converted first to a
902              * UTF-8 string according to its syntax specification.
903              *
904              * NOTE: this implementation only emits DirectoryStrings of the
905              * types returned by isDerString().
906              */
907             String valStr = null;
908             try {
909                 valStr = new String(value.getDataBytes(), "UTF8");
910             } catch (IOException ie) {
911                 throw new IllegalArgumentException("DER Value conversion");
912             }
913 
914             /*
915              * 2.4 (cont): If the UTF-8 string does not have any of the
916              * following characters which need escaping, then that string can be
917              * used as the string representation of the value.
918              *
919              *   o   a space or "#" character occurring at the beginning of the
920              *       string
921              *   o   a space character occurring at the end of the string
922              *
923              *   o   one of the characters ",", "+", """, "\", "<", ">" or ";"
924              *
925              * If a character to be escaped is one of the list shown above, then
926              * it is prefixed by a backslash ('\' ASCII 92).
927              *
928              * Otherwise the character to be escaped is replaced by a backslash
929              * and two hex digits, which form a single byte in the code of the
930              * character.
931              */
932             final String escapees = ",+<>;\"\\";
933             StringBuilder sbuffer = new StringBuilder();
934             boolean previousWhite = false;
935 
936             for (int i = 0; i < valStr.length(); i++) {
937                 char c = valStr.charAt(i);
938 
939                 if (DerValue.isPrintableStringChar(c) ||
940                     escapees.indexOf(c) >= 0 ||
941                     (i == 0 && c == '#')) {
942 
943                     // escape leading '#' and escapees
944                     if ((i == 0 && c == '#') || escapees.indexOf(c) >= 0) {
945                         sbuffer.append('\\');
946                     }
947 
948                     // convert multiple whitespace to single whitespace
949                     if (!Character.isWhitespace(c)) {
950                         previousWhite = false;
951                         sbuffer.append(c);
952                     } else {
953                         if (previousWhite == false) {
954                             // add single whitespace
955                             previousWhite = true;
956                             sbuffer.append(c);
957                         } else {
958                             // ignore subsequent consecutive whitespace
959                             continue;
960                         }
961                     }
962 
963                 } else if (debug != null && Debug.isOn("ava")) {
964 
965                     // embed non-printable/non-escaped char
966                     // as escaped hex pairs for debugging
967 
968                     previousWhite = false;
969 
970                     byte valueBytes[] = null;
971                     try {
972                         valueBytes = Character.toString(c).getBytes("UTF8");
973                     } catch (IOException ie) {
974                         throw new IllegalArgumentException
975                                         ("DER Value conversion");
976                     }
977                     for (int j = 0; j < valueBytes.length; j++) {
978                         sbuffer.append('\\');
979                         sbuffer.append(Character.forDigit
980                                         (0xF & (valueBytes[j] >>> 4), 16));
981                         sbuffer.append(Character.forDigit
982                                         (0xF & (valueBytes[j]), 16));
983                     }
984                 } else {
985 
986                     // append non-printable/non-escaped char
987 
988                     previousWhite = false;
989                     sbuffer.append(c);
990                 }
991             }
992 
993             // remove leading and trailing whitespace from value
994             typeAndValue.append(sbuffer.toString().trim());
995         }
996 
997         String canon = typeAndValue.toString();
998         canon = canon.toUpperCase(Locale.US).toLowerCase(Locale.US);
999         return Normalizer.normalize(canon, Normalizer.Form.NFKD);
1000     }
1001 
1002     /*
1003      * Return true if DerValue can be represented as a String.
1004      */
1005     private static boolean isDerString(DerValue value, boolean canonical) {
1006         if (canonical) {
1007             switch (value.tag) {
1008                 case DerValue.tag_PrintableString:
1009                 case DerValue.tag_UTF8String:
1010                     return true;
1011                 default:
1012                     return false;
1013             }
1014         } else {
1015             switch (value.tag) {
1016                 case DerValue.tag_PrintableString:
1017                 case DerValue.tag_T61String:
1018                 case DerValue.tag_IA5String:
1019                 case DerValue.tag_GeneralString:
1020                 case DerValue.tag_BMPString:
1021                 case DerValue.tag_UTF8String:
1022                     return true;
1023                 default:
1024                     return false;
1025             }
1026         }
1027     }
1028 
1029     boolean hasRFC2253Keyword() {
1030         return AVAKeyword.hasKeyword(oid, RFC2253);
1031     }
1032 
1033     private String toKeywordValueString(String keyword) {
1034         /*
1035          * Construct the value with as little copying and garbage
1036          * production as practical.  First the keyword (mandatory),
1037          * then the equals sign, finally the value.
1038          */
1039         StringBuilder   retval = new StringBuilder(40);
1040 
1041         retval.append(keyword);
1042         retval.append("=");
1043 
1044         try {
1045             String valStr = value.getAsString();
1046 
1047             if (valStr == null) {
1048 
1049                 // rfc1779 specifies that attribute values associated
1050                 // with non-standard keyword attributes may be represented
1051                 // using the hex format below.  This will be used only
1052                 // when the value is not a string type
1053 
1054                 byte    data [] = value.toByteArray();
1055 
1056                 retval.append('#');
1057                 for (int i = 0; i < data.length; i++) {
1058                     retval.append(hexDigits.charAt((data [i] >> 4) & 0x0f));
1059                     retval.append(hexDigits.charAt(data [i] & 0x0f));
1060                 }
1061 
1062             } else {
1063 
1064                 boolean quoteNeeded = false;
1065                 StringBuilder sbuffer = new StringBuilder();
1066                 boolean previousWhite = false;
1067                 final String escapees = ",+=\n<>#;\\\"";
1068 
1069                 /*
1070                  * Special characters (e.g. AVA list separators) cause strings
1071                  * to need quoting, or at least escaping.  So do leading or
1072                  * trailing spaces, and multiple internal spaces.
1073                  */
1074                 int length = valStr.length();
1075                 boolean alreadyQuoted =
1076                     (length > 1 && valStr.charAt(0) == '\"'
1077                      && valStr.charAt(length - 1) == '\"');
1078 
1079                 for (int i = 0; i < length; i++) {
1080                     char c = valStr.charAt(i);
1081                     if (alreadyQuoted && (i == 0 || i == length - 1)) {
1082                         sbuffer.append(c);
1083                         continue;
1084                     }
1085                     if (DerValue.isPrintableStringChar(c) ||
1086                         escapees.indexOf(c) >= 0) {
1087 
1088                         // quote if leading whitespace or special chars
1089                         if (!quoteNeeded &&
1090                             ((i == 0 && (c == ' ' || c == '\n')) ||
1091                                 escapees.indexOf(c) >= 0)) {
1092                             quoteNeeded = true;
1093                         }
1094 
1095                         // quote if multiple internal whitespace
1096                         if (!(c == ' ' || c == '\n')) {
1097                             // escape '"' and '\'
1098                             if (c == '"' || c == '\\') {
1099                                 sbuffer.append('\\');
1100                             }
1101                             previousWhite = false;
1102                         } else {
1103                             if (!quoteNeeded && previousWhite) {
1104                                 quoteNeeded = true;
1105                             }
1106                             previousWhite = true;
1107                         }
1108 
1109                         sbuffer.append(c);
1110 
1111                     } else if (debug != null && Debug.isOn("ava")) {
1112 
1113                         // embed non-printable/non-escaped char
1114                         // as escaped hex pairs for debugging
1115 
1116                         previousWhite = false;
1117 
1118                         // embed escaped hex pairs
1119                         byte[] valueBytes =
1120                                 Character.toString(c).getBytes("UTF8");
1121                         for (int j = 0; j < valueBytes.length; j++) {
1122                             sbuffer.append('\\');
1123                             char hexChar = Character.forDigit
1124                                         (0xF & (valueBytes[j] >>> 4), 16);
1125                             sbuffer.append(Character.toUpperCase(hexChar));
1126                             hexChar = Character.forDigit
1127                                         (0xF & (valueBytes[j]), 16);
1128                             sbuffer.append(Character.toUpperCase(hexChar));
1129                         }
1130                     } else {
1131 
1132                         // append non-printable/non-escaped char
1133 
1134                         previousWhite = false;
1135                         sbuffer.append(c);
1136                     }
1137                 }
1138 
1139                 // quote if trailing whitespace
1140                 if (sbuffer.length() > 0) {
1141                     char trailChar = sbuffer.charAt(sbuffer.length() - 1);
1142                     if (trailChar == ' ' || trailChar == '\n') {
1143                         quoteNeeded = true;
1144                     }
1145                 }
1146 
1147                 // Emit the string ... quote it if needed
1148                 // if string is already quoted, don't re-quote
1149                 if (!alreadyQuoted && quoteNeeded) {
1150                     retval.append("\"" + sbuffer.toString() + "\"");
1151                 } else {
1152                     retval.append(sbuffer.toString());
1153                 }
1154             }
1155         } catch (IOException e) {
1156             throw new IllegalArgumentException("DER Value conversion");
1157         }
1158 
1159         return retval.toString();
1160     }
1161 
1162 }
1163 
1164 /**
1165  * Helper class that allows conversion from String to ObjectIdentifier and
1166  * vice versa according to RFC1779, RFC2253, and an augmented version of
1167  * those standards.
1168  */
1169 class AVAKeyword {
1170 
1171     private static final Map<ObjectIdentifier,AVAKeyword> oidMap;
1172     private static final Map<String,AVAKeyword> keywordMap;
1173 
1174     private String keyword;
1175     private ObjectIdentifier oid;
1176     private boolean rfc1779Compliant, rfc2253Compliant;
1177 
1178     private AVAKeyword(String keyword, ObjectIdentifier oid,
1179                boolean rfc1779Compliant, boolean rfc2253Compliant) {
1180         this.keyword = keyword;
1181         this.oid = oid;
1182         this.rfc1779Compliant = rfc1779Compliant;
1183         this.rfc2253Compliant = rfc2253Compliant;
1184 
1185         // register it
1186         oidMap.put(oid, this);
1187         keywordMap.put(keyword, this);
1188     }
1189 
1190     private boolean isCompliant(int standard) {
1191         switch (standard) {
1192         case AVA.RFC1779:
1193             return rfc1779Compliant;
1194         case AVA.RFC2253:
1195             return rfc2253Compliant;
1196         case AVA.DEFAULT:
1197             return true;
1198         default:
1199             // should not occur, internal error
1200             throw new IllegalArgumentException("Invalid standard " + standard);
1201         }
1202     }
1203 
1204     /**
1205      * Get an object identifier representing the specified keyword (or
1206      * string encoded object identifier) in the given standard.
1207      *
1208      * @param keywordMap a Map where a keyword String maps to a corresponding
1209      *   OID String. Each AVA keyword will be mapped to the corresponding OID.
1210      *   If an entry does not exist, it will fallback to the builtin
1211      *   keyword/OID mapping.
1212      * @throws IOException If the keyword is not valid in the specified standard
1213      *   or the OID String to which a keyword maps to is improperly formatted.
1214      */
1215     static ObjectIdentifier getOID
1216         (String keyword, int standard, Map<String, String> extraKeywordMap)
1217             throws IOException {
1218 
1219         keyword = keyword.toUpperCase(Locale.ENGLISH);
1220         if (standard == AVA.RFC2253) {
1221             if (keyword.startsWith(" ") || keyword.endsWith(" ")) {
1222                 throw new IOException("Invalid leading or trailing space " +
1223                         "in keyword \"" + keyword + "\"");
1224             }
1225         } else {
1226             keyword = keyword.trim();
1227         }
1228 
1229         // check user-specified keyword map first, then fallback to built-in
1230         // map
1231         String oidString = extraKeywordMap.get(keyword);
1232         if (oidString == null) {
1233             AVAKeyword ak = keywordMap.get(keyword);
1234             if ((ak != null) && ak.isCompliant(standard)) {
1235                 return ak.oid;
1236             }
1237         } else {
1238             return new ObjectIdentifier(oidString);
1239         }
1240 
1241         // no keyword found, check if OID string
1242         if (standard == AVA.DEFAULT && keyword.startsWith("OID.")) {
1243             keyword = keyword.substring(4);
1244         }
1245 
1246         boolean number = false;
1247         if (keyword.length() != 0) {
1248             char ch = keyword.charAt(0);
1249             if ((ch >= '0') && (ch <= '9')) {
1250                 number = true;
1251             }
1252         }
1253         if (number == false) {
1254             throw new IOException("Invalid keyword \"" + keyword + "\"");
1255         }
1256         return new ObjectIdentifier(keyword);
1257     }
1258 
1259     /**
1260      * Get a keyword for the given ObjectIdentifier according to standard.
1261      * If no keyword is available, the ObjectIdentifier is encoded as a
1262      * String.
1263      */
1264     static String getKeyword(ObjectIdentifier oid, int standard) {
1265         return getKeyword
1266             (oid, standard, Collections.<String, String>emptyMap());
1267     }
1268 
1269     /**
1270      * Get a keyword for the given ObjectIdentifier according to standard.
1271      * Checks the extraOidMap for a keyword first, then falls back to the
1272      * builtin/default set. If no keyword is available, the ObjectIdentifier
1273      * is encoded as a String.
1274      */
1275     static String getKeyword
1276         (ObjectIdentifier oid, int standard, Map<String, String> extraOidMap) {
1277 
1278         // check extraOidMap first, then fallback to built-in map
1279         String oidString = oid.toString();
1280         String keywordString = extraOidMap.get(oidString);
1281         if (keywordString == null) {
1282             AVAKeyword ak = oidMap.get(oid);
1283             if ((ak != null) && ak.isCompliant(standard)) {
1284                 return ak.keyword;
1285             }
1286         } else {
1287             if (keywordString.length() == 0) {
1288                 throw new IllegalArgumentException("keyword cannot be empty");
1289             }
1290             keywordString = keywordString.trim();
1291             char c = keywordString.charAt(0);
1292             if (c < 65 || c > 122 || (c > 90 && c < 97)) {
1293                 throw new IllegalArgumentException
1294                     ("keyword does not start with letter");
1295             }
1296             for (int i=1; i<keywordString.length(); i++) {
1297                 c = keywordString.charAt(i);
1298                 if ((c < 65 || c > 122 || (c > 90 && c < 97)) &&
1299                     (c < 48 || c > 57) && c != '_') {
1300                     throw new IllegalArgumentException
1301                     ("keyword character is not a letter, digit, or underscore");
1302                 }
1303             }
1304             return keywordString;
1305         }
1306         // no compliant keyword, use OID
1307         if (standard == AVA.RFC2253) {
1308             return oidString;
1309         } else {
1310             return "OID." + oidString;
1311         }
1312     }
1313 
1314     /**
1315      * Test if oid has an associated keyword in standard.
1316      */
1317     static boolean hasKeyword(ObjectIdentifier oid, int standard) {
1318         AVAKeyword ak = oidMap.get(oid);
1319         if (ak == null) {
1320             return false;
1321         }
1322         return ak.isCompliant(standard);
1323     }
1324 
1325     static {
1326         oidMap = new HashMap<ObjectIdentifier,AVAKeyword>();
1327         keywordMap = new HashMap<String,AVAKeyword>();
1328 
1329         // NOTE if multiple keywords are available for one OID, order
1330         // is significant!! Preferred *LAST*.
1331         new AVAKeyword("CN",           X500Name.commonName_oid,   true,  true);
1332         new AVAKeyword("C",            X500Name.countryName_oid,  true,  true);
1333         new AVAKeyword("L",            X500Name.localityName_oid, true,  true);
1334         new AVAKeyword("S",            X500Name.stateName_oid,    false, false);
1335         new AVAKeyword("ST",           X500Name.stateName_oid,    true,  true);
1336         new AVAKeyword("O",            X500Name.orgName_oid,      true,  true);
1337         new AVAKeyword("OU",           X500Name.orgUnitName_oid,  true,  true);
1338         new AVAKeyword("T",            X500Name.title_oid,        false, false);
1339         new AVAKeyword("IP",           X500Name.ipAddress_oid,    false, false);
1340         new AVAKeyword("STREET",       X500Name.streetAddress_oid,true,  true);
1341         new AVAKeyword("DC",           X500Name.DOMAIN_COMPONENT_OID,
1342                                                                   false, true);
1343         new AVAKeyword("DNQUALIFIER",  X500Name.DNQUALIFIER_OID,  false, false);
1344         new AVAKeyword("DNQ",          X500Name.DNQUALIFIER_OID,  false, false);
1345         new AVAKeyword("SURNAME",      X500Name.SURNAME_OID,      false, false);
1346         new AVAKeyword("GIVENNAME",    X500Name.GIVENNAME_OID,    false, false);
1347         new AVAKeyword("INITIALS",     X500Name.INITIALS_OID,     false, false);
1348         new AVAKeyword("GENERATION",   X500Name.GENERATIONQUALIFIER_OID,
1349                                                                   false, false);
1350         new AVAKeyword("EMAIL", PKCS9Attribute.EMAIL_ADDRESS_OID, false, false);
1351         new AVAKeyword("EMAILADDRESS", PKCS9Attribute.EMAIL_ADDRESS_OID,
1352                                                                   false, false);
1353         new AVAKeyword("UID",          X500Name.userid_oid,       false, true);
1354         new AVAKeyword("SERIALNUMBER", X500Name.SERIALNUMBER_OID, false, false);
1355     }
1356 }