View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.fileupload.util.mime;
18  
19  import java.io.ByteArrayOutputStream;
20  import java.io.IOException;
21  import java.io.UnsupportedEncodingException;
22  import java.util.HashMap;
23  import java.util.Locale;
24  import java.util.Map;
25  
26  /**
27   * Utility class to decode MIME texts.
28   *
29   * @since 1.3
30   */
31  public final class MimeUtility {
32  
33      /**
34       * The {@code US-ASCII} charset identifier constant.
35       */
36      private static final String US_ASCII_CHARSET = "US-ASCII";
37  
38      /**
39       * The marker to indicate text is encoded with BASE64 algorithm.
40       */
41      private static final String BASE64_ENCODING_MARKER = "B";
42  
43      /**
44       * The marker to indicate text is encoded with QuotedPrintable algorithm.
45       */
46      private static final String QUOTEDPRINTABLE_ENCODING_MARKER = "Q";
47  
48      /**
49       * If the text contains any encoded tokens, those tokens will be marked with "=?".
50       */
51      private static final String ENCODED_TOKEN_MARKER = "=?";
52  
53      /**
54       * If the text contains any encoded tokens, those tokens will terminate with "=?".
55       */
56      private static final String ENCODED_TOKEN_FINISHER = "?=";
57  
58      /**
59       * The linear whitespace chars sequence.
60       */
61      private static final String LINEAR_WHITESPACE = " \t\r\n";
62  
63      /**
64       * Mappings between MIME and Java charset.
65       */
66      private static final Map<String, String> MIME2JAVA = new HashMap<String, String>();
67  
68      static {
69          MIME2JAVA.put("iso-2022-cn", "ISO2022CN");
70          MIME2JAVA.put("iso-2022-kr", "ISO2022KR");
71          MIME2JAVA.put("utf-8", "UTF8");
72          MIME2JAVA.put("utf8", "UTF8");
73          MIME2JAVA.put("ja_jp.iso2022-7", "ISO2022JP");
74          MIME2JAVA.put("ja_jp.eucjp", "EUCJIS");
75          MIME2JAVA.put("euc-kr", "KSC5601");
76          MIME2JAVA.put("euckr", "KSC5601");
77          MIME2JAVA.put("us-ascii", "ISO-8859-1");
78          MIME2JAVA.put("x-us-ascii", "ISO-8859-1");
79      }
80  
81      /**
82       * Hidden constructor, this class must not be instantiated.
83       */
84      private MimeUtility() {
85          // do nothing
86      }
87  
88      /**
89       * Decode a string of text obtained from a mail header into
90       * its proper form.  The text generally will consist of a
91       * string of tokens, some of which may be encoded using
92       * base64 encoding.
93       *
94       * @param text   The text to decode.
95       *
96       * @return The decoded text string.
97       * @throws UnsupportedEncodingException if the detected encoding in the input text is not supported.
98       */
99      public static String decodeText(String text) throws UnsupportedEncodingException {
100         // if the text contains any encoded tokens, those tokens will be marked with "=?".  If the
101         // source string doesn't contain that sequent, no decoding is required.
102         if (text.indexOf(ENCODED_TOKEN_MARKER) < 0) {
103             return text;
104         }
105 
106         int offset = 0;
107         int endOffset = text.length();
108 
109         int startWhiteSpace = -1;
110         int endWhiteSpace = -1;
111 
112         StringBuilder decodedText = new StringBuilder(text.length());
113 
114         boolean previousTokenEncoded = false;
115 
116         while (offset < endOffset) {
117             char ch = text.charAt(offset);
118 
119             // is this a whitespace character?
120             if (LINEAR_WHITESPACE.indexOf(ch) != -1) { // whitespace found
121                 startWhiteSpace = offset;
122                 while (offset < endOffset) {
123                     // step over the white space characters.
124                     ch = text.charAt(offset);
125                     if (LINEAR_WHITESPACE.indexOf(ch) != -1) { // whitespace found
126                         offset++;
127                     } else {
128                         // record the location of the first non lwsp and drop down to process the
129                         // token characters.
130                         endWhiteSpace = offset;
131                         break;
132                     }
133                 }
134             } else {
135                 // we have a word token.  We need to scan over the word and then try to parse it.
136                 int wordStart = offset;
137 
138                 while (offset < endOffset) {
139                     // step over the non white space characters.
140                     ch = text.charAt(offset);
141                     if (LINEAR_WHITESPACE.indexOf(ch) == -1) { // not white space
142                         offset++;
143                     } else {
144                         break;
145                     }
146 
147                     //NB:  Trailing whitespace on these header strings will just be discarded.
148                 }
149                 // pull out the word token.
150                 String word = text.substring(wordStart, offset);
151                 // is the token encoded?  decode the word
152                 if (word.startsWith(ENCODED_TOKEN_MARKER)) {
153                     try {
154                         // if this gives a parsing failure, treat it like a non-encoded word.
155                         String decodedWord = decodeWord(word);
156 
157                         // are any whitespace characters significant?  Append 'em if we've got 'em.
158                         if (!previousTokenEncoded && startWhiteSpace != -1) {
159                             decodedText.append(text.substring(startWhiteSpace, endWhiteSpace));
160                             startWhiteSpace = -1;
161                         }
162                         // this is definitely a decoded token.
163                         previousTokenEncoded = true;
164                         // and add this to the text.
165                         decodedText.append(decodedWord);
166                         // we continue parsing from here...we allow parsing errors to fall through
167                         // and get handled as normal text.
168                         continue;
169 
170                     } catch (ParseException e) {
171                         // just ignore it, skip to next word
172                     }
173                 }
174                 // this is a normal token, so it doesn't matter what the previous token was.  Add the white space
175                 // if we have it.
176                 if (startWhiteSpace != -1) {
177                     decodedText.append(text.substring(startWhiteSpace, endWhiteSpace));
178                     startWhiteSpace = -1;
179                 }
180                 // this is not a decoded token.
181                 previousTokenEncoded = false;
182                 decodedText.append(word);
183             }
184         }
185 
186         return decodedText.toString();
187     }
188 
189     /**
190      * Parse a string using the RFC 2047 rules for an "encoded-word"
191      * type.  This encoding has the syntax:
192      *
193      * encoded-word = "=?" charset "?" encoding "?" encoded-text "?="
194      *
195      * @param word   The possibly encoded word value.
196      *
197      * @return The decoded word.
198      * @throws ParseException
199      * @throws UnsupportedEncodingException
200      */
201     private static String decodeWord(String word) throws ParseException, UnsupportedEncodingException {
202         // encoded words start with the characters "=?".  If this not an encoded word, we throw a
203         // ParseException for the caller.
204 
205         if (!word.startsWith(ENCODED_TOKEN_MARKER)) {
206             throw new ParseException("Invalid RFC 2047 encoded-word: " + word);
207         }
208 
209         int charsetPos = word.indexOf('?', 2);
210         if (charsetPos == -1) {
211             throw new ParseException("Missing charset in RFC 2047 encoded-word: " + word);
212         }
213 
214         // pull out the character set information (this is the MIME name at this point).
215         String charset = word.substring(2, charsetPos).toLowerCase();
216 
217         // now pull out the encoding token the same way.
218         int encodingPos = word.indexOf('?', charsetPos + 1);
219         if (encodingPos == -1) {
220             throw new ParseException("Missing encoding in RFC 2047 encoded-word: " + word);
221         }
222 
223         String encoding = word.substring(charsetPos + 1, encodingPos);
224 
225         // and finally the encoded text.
226         int encodedTextPos = word.indexOf(ENCODED_TOKEN_FINISHER, encodingPos + 1);
227         if (encodedTextPos == -1) {
228             throw new ParseException("Missing encoded text in RFC 2047 encoded-word: " + word);
229         }
230 
231         String encodedText = word.substring(encodingPos + 1, encodedTextPos);
232 
233         // seems a bit silly to encode a null string, but easy to deal with.
234         if (encodedText.length() == 0) {
235             return "";
236         }
237 
238         try {
239             // the decoder writes directly to an output stream.
240             ByteArrayOutputStream out = new ByteArrayOutputStream(encodedText.length());
241 
242             byte[] encodedData = encodedText.getBytes(US_ASCII_CHARSET);
243 
244             // Base64 encoded?
245             if (encoding.equals(BASE64_ENCODING_MARKER)) {
246                 Base64Decoder.decode(encodedData, out);
247             } else if (encoding.equals(QUOTEDPRINTABLE_ENCODING_MARKER)) { // maybe quoted printable.
248                 QuotedPrintableDecoder.decode(encodedData, out);
249             } else {
250                 throw new UnsupportedEncodingException("Unknown RFC 2047 encoding: " + encoding);
251             }
252             // get the decoded byte data and convert into a string.
253             byte[] decodedData = out.toByteArray();
254             return new String(decodedData, javaCharset(charset));
255         } catch (IOException e) {
256             throw new UnsupportedEncodingException("Invalid RFC 2047 encoding");
257         }
258     }
259 
260     /**
261      * Translate a MIME standard character set name into the Java
262      * equivalent.
263      *
264      * @param charset The MIME standard name.
265      *
266      * @return The Java equivalent for this name.
267      */
268     private static String javaCharset(String charset) {
269         // nothing in, nothing out.
270         if (charset == null) {
271             return null;
272         }
273 
274         String mappedCharset = MIME2JAVA.get(charset.toLowerCase(Locale.ENGLISH));
275         // if there is no mapping, then the original name is used.  Many of the MIME character set
276         // names map directly back into Java.  The reverse isn't necessarily true.
277         if (mappedCharset == null) {
278             return charset;
279         }
280         return mappedCharset;
281     }
282 
283 }