001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 018package org.apache.commons.codec.net; 019 020import java.io.ByteArrayOutputStream; 021import java.io.UnsupportedEncodingException; 022import java.nio.charset.Charset; 023import java.nio.charset.IllegalCharsetNameException; 024import java.nio.charset.StandardCharsets; 025import java.nio.charset.UnsupportedCharsetException; 026import java.util.BitSet; 027 028import org.apache.commons.codec.BinaryDecoder; 029import org.apache.commons.codec.BinaryEncoder; 030import org.apache.commons.codec.DecoderException; 031import org.apache.commons.codec.EncoderException; 032import org.apache.commons.codec.StringDecoder; 033import org.apache.commons.codec.StringEncoder; 034import org.apache.commons.codec.binary.StringUtils; 035 036/** 037 * Codec for the Quoted-Printable section of <a href="http://www.ietf.org/rfc/rfc1521.txt">RFC 1521</a>. 038 * <p> 039 * The Quoted-Printable encoding is intended to represent data that largely consists of octets that correspond to 040 * printable characters in the ASCII character set. It encodes the data in such a way that the resulting octets are 041 * unlikely to be modified by mail transport. If the data being encoded are mostly ASCII text, the encoded form of the 042 * data remains largely recognizable by humans. A body which is entirely ASCII may also be encoded in Quoted-Printable 043 * to ensure the integrity of the data should the message pass through a character- translating, and/or line-wrapping 044 * gateway. 045 * </p> 046 * <p> 047 * Note: 048 * </p> 049 * <p> 050 * Depending on the selected {@code strict} parameter, this class will implement a different set of rules of the 051 * quoted-printable spec: 052 * </p> 053 * <ul> 054 * <li>{@code strict=false}: only rules #1 and #2 are implemented</li> 055 * <li>{@code strict=true}: all rules #1 through #5 are implemented</li> 056 * </ul> 057 * <p> 058 * Originally, this class only supported the non-strict mode, but the codec in this partial form could already be used 059 * for certain applications that do not require quoted-printable line formatting (rules #3, #4, #5), for instance 060 * Q codec. The strict mode has been added in 1.10. 061 * </p> 062 * <p> 063 * This class is immutable and thread-safe. 064 * </p> 065 * 066 * @see <a href="http://www.ietf.org/rfc/rfc1521.txt">RFC 1521 MIME (Multipurpose Internet Mail Extensions) Part One: 067 * Mechanisms for Specifying and Describing the Format of Internet Message Bodies </a> 068 * 069 * @since 1.3 070 */ 071public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, StringEncoder, StringDecoder { 072 /** 073 * The default Charset used for string decoding and encoding. 074 */ 075 private final Charset charset; 076 077 /** 078 * Indicates whether soft line breaks shall be used during encoding (rule #3-5). 079 */ 080 private final boolean strict; 081 082 /** 083 * BitSet of printable characters as defined in RFC 1521. 084 */ 085 private static final BitSet PRINTABLE_CHARS = new BitSet(256); 086 087 private static final byte ESCAPE_CHAR = '='; 088 089 private static final byte TAB = 9; 090 091 private static final byte SPACE = 32; 092 093 private static final byte CR = 13; 094 095 private static final byte LF = 10; 096 097 /** 098 * Safe line length for quoted printable encoded text. 099 */ 100 private static final int SAFE_LENGTH = 73; 101 102 // Static initializer for printable chars collection 103 static { 104 // alpha characters 105 for (int i = 33; i <= 60; i++) { 106 PRINTABLE_CHARS.set(i); 107 } 108 for (int i = 62; i <= 126; i++) { 109 PRINTABLE_CHARS.set(i); 110 } 111 PRINTABLE_CHARS.set(TAB); 112 PRINTABLE_CHARS.set(SPACE); 113 } 114 115 /** 116 * Default constructor, assumes default Charset of {@link StandardCharsets#UTF_8} 117 */ 118 public QuotedPrintableCodec() { 119 this(StandardCharsets.UTF_8, false); 120 } 121 122 /** 123 * Constructor which allows for the selection of the strict mode. 124 * 125 * @param strict 126 * if {@code true}, soft line breaks will be used 127 * @since 1.10 128 */ 129 public QuotedPrintableCodec(final boolean strict) { 130 this(StandardCharsets.UTF_8, strict); 131 } 132 133 /** 134 * Constructor which allows for the selection of a default Charset. 135 * 136 * @param charset 137 * the default string Charset to use. 138 * @since 1.7 139 */ 140 public QuotedPrintableCodec(final Charset charset) { 141 this(charset, false); 142 } 143 144 /** 145 * Constructor which allows for the selection of a default Charset and strict mode. 146 * 147 * @param charset 148 * the default string Charset to use. 149 * @param strict 150 * if {@code true}, soft line breaks will be used 151 * @since 1.10 152 */ 153 public QuotedPrintableCodec(final Charset charset, final boolean strict) { 154 this.charset = charset; 155 this.strict = strict; 156 } 157 158 /** 159 * Constructor which allows for the selection of a default Charset. 160 * 161 * @param charsetName 162 * the default string Charset to use. 163 * @throws UnsupportedCharsetException 164 * If no support for the named Charset is available 165 * in this instance of the Java virtual machine 166 * @throws IllegalArgumentException 167 * If the given charsetName is null 168 * @throws IllegalCharsetNameException 169 * If the given Charset name is illegal 170 * 171 * @since 1.7 throws UnsupportedCharsetException if the named Charset is unavailable 172 */ 173 public QuotedPrintableCodec(final String charsetName) 174 throws IllegalCharsetNameException, IllegalArgumentException, UnsupportedCharsetException { 175 this(Charset.forName(charsetName), false); 176 } 177 178 /** 179 * Encodes byte into its quoted-printable representation. 180 * 181 * @param b 182 * byte to encode 183 * @param buffer 184 * the buffer to write to 185 * @return The number of bytes written to the {@code buffer} 186 */ 187 private static final int encodeQuotedPrintable(final int b, final ByteArrayOutputStream buffer) { 188 buffer.write(ESCAPE_CHAR); 189 final char hex1 = Utils.hexDigit(b >> 4); 190 final char hex2 = Utils.hexDigit(b); 191 buffer.write(hex1); 192 buffer.write(hex2); 193 return 3; 194 } 195 196 /** 197 * Return the byte at position {@code index} of the byte array and 198 * make sure it is unsigned. 199 * 200 * @param index 201 * position in the array 202 * @param bytes 203 * the byte array 204 * @return the unsigned octet at position {@code index} from the array 205 */ 206 private static int getUnsignedOctet(final int index, final byte[] bytes) { 207 int b = bytes[index]; 208 if (b < 0) { 209 b = 256 + b; 210 } 211 return b; 212 } 213 214 /** 215 * Write a byte to the buffer. 216 * 217 * @param b 218 * byte to write 219 * @param encode 220 * indicates whether the octet shall be encoded 221 * @param buffer 222 * the buffer to write to 223 * @return the number of bytes that have been written to the buffer 224 */ 225 private static int encodeByte(final int b, final boolean encode, 226 final ByteArrayOutputStream buffer) { 227 if (encode) { 228 return encodeQuotedPrintable(b, buffer); 229 } 230 buffer.write(b); 231 return 1; 232 } 233 234 /** 235 * Checks whether the given byte is whitespace. 236 * 237 * @param b 238 * byte to be checked 239 * @return {@code true} if the byte is either a space or tab character 240 */ 241 private static boolean isWhitespace(final int b) { 242 return b == SPACE || b == TAB; 243 } 244 245 /** 246 * Encodes an array of bytes into an array of quoted-printable 7-bit characters. Unsafe characters are escaped. 247 * <p> 248 * This function implements a subset of quoted-printable encoding specification (rule #1 and rule #2) as defined in 249 * RFC 1521 and is suitable for encoding binary data and unformatted text. 250 * 251 * @param printable 252 * bitset of characters deemed quoted-printable 253 * @param bytes 254 * array of bytes to be encoded 255 * @return array of bytes containing quoted-printable data 256 */ 257 public static final byte[] encodeQuotedPrintable(final BitSet printable, final byte[] bytes) { 258 return encodeQuotedPrintable(printable, bytes, false); 259 } 260 261 /** 262 * Encodes an array of bytes into an array of quoted-printable 7-bit characters. Unsafe characters are escaped. 263 * <p> 264 * Depending on the selection of the {@code strict} parameter, this function either implements the full ruleset 265 * or only a subset of quoted-printable encoding specification (rule #1 and rule #2) as defined in 266 * RFC 1521 and is suitable for encoding binary data and unformatted text. 267 * 268 * @param printable 269 * bitset of characters deemed quoted-printable 270 * @param bytes 271 * array of bytes to be encoded 272 * @param strict 273 * if {@code true} the full ruleset is used, otherwise only rule #1 and rule #2 274 * @return array of bytes containing quoted-printable data 275 * @since 1.10 276 */ 277 public static final byte[] encodeQuotedPrintable(BitSet printable, final byte[] bytes, final boolean strict) { 278 if (bytes == null) { 279 return null; 280 } 281 if (printable == null) { 282 printable = PRINTABLE_CHARS; 283 } 284 final ByteArrayOutputStream buffer = new ByteArrayOutputStream(); 285 286 if (strict) { 287 int pos = 1; 288 // encode up to buffer.length - 3, the last three octets will be treated 289 // separately for simplification of note #3 290 for (int i = 0; i < bytes.length - 3; i++) { 291 final int b = getUnsignedOctet(i, bytes); 292 if (pos < SAFE_LENGTH) { 293 // up to this length it is safe to add any byte, encoded or not 294 pos += encodeByte(b, !printable.get(b), buffer); 295 } else { 296 // rule #3: whitespace at the end of a line *must* be encoded 297 encodeByte(b, !printable.get(b) || isWhitespace(b), buffer); 298 299 // rule #5: soft line break 300 buffer.write(ESCAPE_CHAR); 301 buffer.write(CR); 302 buffer.write(LF); 303 pos = 1; 304 } 305 } 306 307 // rule #3: whitespace at the end of a line *must* be encoded 308 // if we would do a soft break line after this octet, encode whitespace 309 int b = getUnsignedOctet(bytes.length - 3, bytes); 310 boolean encode = !printable.get(b) || (isWhitespace(b) && pos > SAFE_LENGTH - 5); 311 pos += encodeByte(b, encode, buffer); 312 313 // note #3: '=' *must not* be the ultimate or penultimate character 314 // simplification: if < 6 bytes left, do a soft line break as we may need 315 // exactly 6 bytes space for the last 2 bytes 316 if (pos > SAFE_LENGTH - 2) { 317 buffer.write(ESCAPE_CHAR); 318 buffer.write(CR); 319 buffer.write(LF); 320 } 321 for (int i = bytes.length - 2; i < bytes.length; i++) { 322 b = getUnsignedOctet(i, bytes); 323 // rule #3: trailing whitespace shall be encoded 324 encode = !printable.get(b) || (i > bytes.length - 2 && isWhitespace(b)); 325 encodeByte(b, encode, buffer); 326 } 327 } else { 328 for (final byte c : bytes) { 329 int b = c; 330 if (b < 0) { 331 b = 256 + b; 332 } 333 if (printable.get(b)) { 334 buffer.write(b); 335 } else { 336 encodeQuotedPrintable(b, buffer); 337 } 338 } 339 } 340 return buffer.toByteArray(); 341 } 342 343 /** 344 * Decodes an array quoted-printable characters into an array of original bytes. Escaped characters are converted 345 * back to their original representation. 346 * <p> 347 * This function fully implements the quoted-printable encoding specification (rule #1 through rule #5) as 348 * defined in RFC 1521. 349 * 350 * @param bytes 351 * array of quoted-printable characters 352 * @return array of original bytes 353 * @throws DecoderException 354 * Thrown if quoted-printable decoding is unsuccessful 355 */ 356 public static final byte[] decodeQuotedPrintable(final byte[] bytes) throws DecoderException { 357 if (bytes == null) { 358 return null; 359 } 360 final ByteArrayOutputStream buffer = new ByteArrayOutputStream(); 361 for (int i = 0; i < bytes.length; i++) { 362 final int b = bytes[i]; 363 if (b == ESCAPE_CHAR) { 364 try { 365 // if the next octet is a CR we have found a soft line break 366 if (bytes[++i] == CR) { 367 continue; 368 } 369 final int u = Utils.digit16(bytes[i]); 370 final int l = Utils.digit16(bytes[++i]); 371 buffer.write((char) ((u << 4) + l)); 372 } catch (final ArrayIndexOutOfBoundsException e) { 373 throw new DecoderException("Invalid quoted-printable encoding", e); 374 } 375 } else if (b != CR && b != LF) { 376 // every other octet is appended except for CR & LF 377 buffer.write(b); 378 } 379 } 380 return buffer.toByteArray(); 381 } 382 383 /** 384 * Encodes an array of bytes into an array of quoted-printable 7-bit characters. Unsafe characters are escaped. 385 * <p> 386 * Depending on the selection of the {@code strict} parameter, this function either implements the full ruleset 387 * or only a subset of quoted-printable encoding specification (rule #1 and rule #2) as defined in 388 * RFC 1521 and is suitable for encoding binary data and unformatted text. 389 * 390 * @param bytes 391 * array of bytes to be encoded 392 * @return array of bytes containing quoted-printable data 393 */ 394 @Override 395 public byte[] encode(final byte[] bytes) { 396 return encodeQuotedPrintable(PRINTABLE_CHARS, bytes, strict); 397 } 398 399 /** 400 * Decodes an array of quoted-printable characters into an array of original bytes. Escaped characters are converted 401 * back to their original representation. 402 * <p> 403 * This function fully implements the quoted-printable encoding specification (rule #1 through rule #5) as 404 * defined in RFC 1521. 405 * 406 * @param bytes 407 * array of quoted-printable characters 408 * @return array of original bytes 409 * @throws DecoderException 410 * Thrown if quoted-printable decoding is unsuccessful 411 */ 412 @Override 413 public byte[] decode(final byte[] bytes) throws DecoderException { 414 return decodeQuotedPrintable(bytes); 415 } 416 417 /** 418 * Encodes a string into its quoted-printable form using the default string Charset. Unsafe characters are escaped. 419 * <p> 420 * Depending on the selection of the {@code strict} parameter, this function either implements the full ruleset 421 * or only a subset of quoted-printable encoding specification (rule #1 and rule #2) as defined in 422 * RFC 1521 and is suitable for encoding binary data and unformatted text. 423 * 424 * @param sourceStr 425 * string to convert to quoted-printable form 426 * @return quoted-printable string 427 * @throws EncoderException 428 * Thrown if quoted-printable encoding is unsuccessful 429 * 430 * @see #getCharset() 431 */ 432 @Override 433 public String encode(final String sourceStr) throws EncoderException { 434 return this.encode(sourceStr, getCharset()); 435 } 436 437 /** 438 * Decodes a quoted-printable string into its original form using the specified string Charset. Escaped characters 439 * are converted back to their original representation. 440 * 441 * @param sourceStr 442 * quoted-printable string to convert into its original form 443 * @param sourceCharset 444 * the original string Charset 445 * @return original string 446 * @throws DecoderException 447 * Thrown if quoted-printable decoding is unsuccessful 448 * @since 1.7 449 */ 450 public String decode(final String sourceStr, final Charset sourceCharset) throws DecoderException { 451 if (sourceStr == null) { 452 return null; 453 } 454 return new String(this.decode(StringUtils.getBytesUsAscii(sourceStr)), sourceCharset); 455 } 456 457 /** 458 * Decodes a quoted-printable string into its original form using the specified string Charset. Escaped characters 459 * are converted back to their original representation. 460 * 461 * @param sourceStr 462 * quoted-printable string to convert into its original form 463 * @param sourceCharset 464 * the original string Charset 465 * @return original string 466 * @throws DecoderException 467 * Thrown if quoted-printable decoding is unsuccessful 468 * @throws UnsupportedEncodingException 469 * Thrown if Charset is not supported 470 */ 471 public String decode(final String sourceStr, final String sourceCharset) 472 throws DecoderException, UnsupportedEncodingException { 473 if (sourceStr == null) { 474 return null; 475 } 476 return new String(decode(StringUtils.getBytesUsAscii(sourceStr)), sourceCharset); 477 } 478 479 /** 480 * Decodes a quoted-printable string into its original form using the default string Charset. Escaped characters are 481 * converted back to their original representation. 482 * 483 * @param sourceStr 484 * quoted-printable string to convert into its original form 485 * @return original string 486 * @throws DecoderException 487 * Thrown if quoted-printable decoding is unsuccessful. Thrown if Charset is not supported. 488 * @see #getCharset() 489 */ 490 @Override 491 public String decode(final String sourceStr) throws DecoderException { 492 return this.decode(sourceStr, this.getCharset()); 493 } 494 495 /** 496 * Encodes an object into its quoted-printable safe form. Unsafe characters are escaped. 497 * 498 * @param obj 499 * string to convert to a quoted-printable form 500 * @return quoted-printable object 501 * @throws EncoderException 502 * Thrown if quoted-printable encoding is not applicable to objects of this type or if encoding is 503 * unsuccessful 504 */ 505 @Override 506 public Object encode(final Object obj) throws EncoderException { 507 if (obj == null) { 508 return null; 509 } else if (obj instanceof byte[]) { 510 return encode((byte[]) obj); 511 } else if (obj instanceof String) { 512 return encode((String) obj); 513 } else { 514 throw new EncoderException("Objects of type " + 515 obj.getClass().getName() + 516 " cannot be quoted-printable encoded"); 517 } 518 } 519 520 /** 521 * Decodes a quoted-printable object into its original form. Escaped characters are converted back to their original 522 * representation. 523 * 524 * @param obj 525 * quoted-printable object to convert into its original form 526 * @return original object 527 * @throws DecoderException 528 * Thrown if the argument is not a {@code String} or {@code byte[]}. Thrown if a failure 529 * condition is encountered during the decode process. 530 */ 531 @Override 532 public Object decode(final Object obj) throws DecoderException { 533 if (obj == null) { 534 return null; 535 } else if (obj instanceof byte[]) { 536 return decode((byte[]) obj); 537 } else if (obj instanceof String) { 538 return decode((String) obj); 539 } else { 540 throw new DecoderException("Objects of type " + 541 obj.getClass().getName() + 542 " cannot be quoted-printable decoded"); 543 } 544 } 545 546 /** 547 * Gets the default Charset name used for string decoding and encoding. 548 * 549 * @return the default Charset name 550 * @since 1.7 551 */ 552 public Charset getCharset() { 553 return this.charset; 554 } 555 556 /** 557 * Gets the default Charset name used for string decoding and encoding. 558 * 559 * @return the default Charset name 560 */ 561 public String getDefaultCharset() { 562 return this.charset.name(); 563 } 564 565 /** 566 * Encodes a string into its quoted-printable form using the specified Charset. Unsafe characters are escaped. 567 * <p> 568 * Depending on the selection of the {@code strict} parameter, this function either implements the full ruleset 569 * or only a subset of quoted-printable encoding specification (rule #1 and rule #2) as defined in 570 * RFC 1521 and is suitable for encoding binary data and unformatted text. 571 * 572 * @param sourceStr 573 * string to convert to quoted-printable form 574 * @param sourceCharset 575 * the Charset for sourceStr 576 * @return quoted-printable string 577 * @since 1.7 578 */ 579 public String encode(final String sourceStr, final Charset sourceCharset) { 580 if (sourceStr == null) { 581 return null; 582 } 583 return StringUtils.newStringUsAscii(this.encode(sourceStr.getBytes(sourceCharset))); 584 } 585 586 /** 587 * Encodes a string into its quoted-printable form using the specified Charset. Unsafe characters are escaped. 588 * <p> 589 * Depending on the selection of the {@code strict} parameter, this function either implements the full ruleset 590 * or only a subset of quoted-printable encoding specification (rule #1 and rule #2) as defined in 591 * RFC 1521 and is suitable for encoding binary data and unformatted text. 592 * 593 * @param sourceStr 594 * string to convert to quoted-printable form 595 * @param sourceCharset 596 * the Charset for sourceStr 597 * @return quoted-printable string 598 * @throws UnsupportedEncodingException 599 * Thrown if the Charset is not supported 600 */ 601 public String encode(final String sourceStr, final String sourceCharset) throws UnsupportedEncodingException { 602 if (sourceStr == null) { 603 return null; 604 } 605 return StringUtils.newStringUsAscii(encode(sourceStr.getBytes(sourceCharset))); 606 } 607}