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.binary; 019 020import java.math.BigInteger; 021import java.util.Arrays; 022import java.util.Objects; 023 024import org.apache.commons.codec.CodecPolicy; 025 026/** 027 * Provides Base64 encoding and decoding as defined by <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>. 028 * 029 * <p> 030 * This class implements section <cite>6.8. Base64 Content-Transfer-Encoding</cite> from RFC 2045 <cite>Multipurpose 031 * Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies</cite> by Freed and Borenstein. 032 * </p> 033 * <p> 034 * The class can be parameterized in the following manner with various constructors: 035 * </p> 036 * <ul> 037 * <li>URL-safe mode: Default off.</li> 038 * <li>Line length: Default 76. Line length that aren't multiples of 4 will still essentially end up being multiples of 039 * 4 in the encoded data. 040 * <li>Line separator: Default is CRLF ("\r\n")</li> 041 * </ul> 042 * <p> 043 * The URL-safe parameter is only applied to encode operations. Decoding seamlessly handles both modes. 044 * </p> 045 * <p> 046 * Since this class operates directly on byte streams, and not character streams, it is hard-coded to only 047 * encode/decode character encodings which are compatible with the lower 127 ASCII chart (ISO-8859-1, Windows-1252, 048 * UTF-8, etc). 049 * </p> 050 * <p> 051 * This class is thread-safe. 052 * </p> 053 * <p> 054 * You can configure instances with the {@link Builder}. 055 * </p> 056 * <pre> 057 * Base64 base64 = Base64.builder() 058 * .setDecodingPolicy(DecodingPolicy.LENIENT) // default is lenient, null resets to default 059 * .setEncodeTable(customEncodeTable) // default is built in, null resets to default 060 * .setLineLength(0) // default is none 061 * .setLineSeparator('\r', '\n') // default is CR LF, null resets to default 062 * .setPadding('=') // default is = 063 * .setUrlSafe(false) // default is false 064 * .get() 065 * </pre> 066 * 067 * @see <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a> 068 * @since 1.0 069 */ 070public class Base64 extends BaseNCodec { 071 072 /** 073 * Builds {@link Base64} instances. 074 * 075 * @since 1.17.0 076 */ 077 public static class Builder extends AbstractBuilder<Base64, Builder> { 078 079 /** 080 * Constructs a new instance. 081 */ 082 public Builder() { 083 super(STANDARD_ENCODE_TABLE); 084 } 085 086 @Override 087 public Base64 get() { 088 return new Base64(getLineLength(), getLineSeparator(), getPadding(), getEncodeTable(), getDecodingPolicy()); 089 } 090 091 /** 092 * Sets the URL-safe encoding policy. 093 * 094 * @param urlSafe URL-safe encoding policy, null resets to the default. 095 * @return this. 096 */ 097 public Builder setUrlSafe(final boolean urlSafe) { 098 return setEncodeTable(toUrlSafeEncodeTable(urlSafe)); 099 } 100 101 } 102 103 /** 104 * BASE64 characters are 6 bits in length. 105 * They are formed by taking a block of 3 octets to form a 24-bit string, 106 * which is converted into 4 BASE64 characters. 107 */ 108 private static final int BITS_PER_ENCODED_BYTE = 6; 109 private static final int BYTES_PER_UNENCODED_BLOCK = 3; 110 private static final int BYTES_PER_ENCODED_BLOCK = 4; 111 private static final int ALPHABET_LENGTH = 64; 112 private static final int DECODING_TABLE_LENGTH = 256; 113 114 /** 115 * This array is a lookup table that translates 6-bit positive integer index values into their "Base64 Alphabet" 116 * equivalents as specified in Table 1 of RFC 2045. 117 * <p> 118 * Thanks to "commons" project in ws.apache.org for this code. 119 * https://svn.apache.org/repos/asf/webservices/commons/trunk/modules/util/ 120 * </p> 121 */ 122 private static final byte[] STANDARD_ENCODE_TABLE = { 123 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 124 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', 125 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 126 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', 127 '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '+', '/' 128 }; 129 130 /** 131 * This is a copy of the STANDARD_ENCODE_TABLE above, but with + and / 132 * changed to - and _ to make the encoded Base64 results more URL-SAFE. 133 * This table is only used when the Base64's mode is set to URL-SAFE. 134 */ 135 private static final byte[] URL_SAFE_ENCODE_TABLE = { 136 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 137 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', 138 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 139 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', 140 '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '-', '_' 141 }; 142 143 /** 144 * This array is a lookup table that translates Unicode characters drawn from the "Base64 Alphabet" (as specified 145 * in Table 1 of RFC 2045) into their 6-bit positive integer equivalents. Characters that are not in the Base64 146 * alphabet but fall within the bounds of the array are translated to -1. 147 * <p> 148 * Note: '+' and '-' both decode to 62. '/' and '_' both decode to 63. This means decoder seamlessly handles both 149 * URL_SAFE and STANDARD base64. (The encoder, on the other hand, needs to know ahead of time what to emit). 150 * </p> 151 * <p> 152 * Thanks to "commons" project in ws.apache.org for this code. 153 * https://svn.apache.org/repos/asf/webservices/commons/trunk/modules/util/ 154 * </p> 155 */ 156 private static final byte[] DECODE_TABLE = { 157 // 0 1 2 3 4 5 6 7 8 9 A B C D E F 158 -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, // 00-0f 159 -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, // 10-1f 160 -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 62, -1, 62, -1, 63, // 20-2f + - / 161 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, -1, -1, -1, -1, -1, -1, // 30-3f 0-9 162 -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, // 40-4f A-O 163 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, -1, -1, -1, -1, 63, // 50-5f P-Z _ 164 -1, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, // 60-6f a-o 165 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51 // 70-7a p-z 166 }; 167 168 /** 169 * Base64 uses 6-bit fields. 170 */ 171 /** Mask used to extract 6 bits, used when encoding */ 172 private static final int MASK_6BITS = 0x3f; 173 174 // The static final fields above are used for the original static byte[] methods on Base64. 175 // The private member fields below are used with the new streaming approach, which requires 176 // some state be preserved between calls of encode() and decode(). 177 178 /** Mask used to extract 4 bits, used when decoding final trailing character. */ 179 private static final int MASK_4BITS = 0xf; 180 /** Mask used to extract 2 bits, used when decoding final trailing character. */ 181 private static final int MASK_2BITS = 0x3; 182 183 /** 184 * Creates a new Builder. 185 * 186 * @return a new Builder. 187 * @since 1.17.0 188 */ 189 public static Builder builder() { 190 return new Builder(); 191 } 192 193 /** 194 * Decodes Base64 data into octets. 195 * <p> 196 * <b>Note:</b> this method seamlessly handles data encoded in URL-safe or normal mode. 197 * </p> 198 * 199 * @param base64Data 200 * Byte array containing Base64 data 201 * @return Array containing decoded data. 202 */ 203 public static byte[] decodeBase64(final byte[] base64Data) { 204 return new Base64().decode(base64Data); 205 } 206 207 /** 208 * Decodes a Base64 String into octets. 209 * <p> 210 * <b>Note:</b> this method seamlessly handles data encoded in URL-safe or normal mode. 211 * </p> 212 * 213 * @param base64String 214 * String containing Base64 data 215 * @return Array containing decoded data. 216 * @since 1.4 217 */ 218 public static byte[] decodeBase64(final String base64String) { 219 return new Base64().decode(base64String); 220 } 221 222 // Implementation of integer encoding used for crypto 223 /** 224 * Decodes a byte64-encoded integer according to crypto standards such as W3C's XML-Signature. 225 * 226 * @param pArray 227 * a byte array containing base64 character data 228 * @return A BigInteger 229 * @since 1.4 230 */ 231 public static BigInteger decodeInteger(final byte[] pArray) { 232 return new BigInteger(1, decodeBase64(pArray)); 233 } 234 235 /** 236 * Encodes binary data using the base64 algorithm but does not chunk the output. 237 * 238 * @param binaryData 239 * binary data to encode 240 * @return byte[] containing Base64 characters in their UTF-8 representation. 241 */ 242 public static byte[] encodeBase64(final byte[] binaryData) { 243 return encodeBase64(binaryData, false); 244 } 245 246 /** 247 * Encodes binary data using the base64 algorithm, optionally chunking the output into 76 character blocks. 248 * 249 * @param binaryData 250 * Array containing binary data to encode. 251 * @param isChunked 252 * if {@code true} this encoder will chunk the base64 output into 76 character blocks 253 * @return Base64-encoded data. 254 * @throws IllegalArgumentException 255 * Thrown when the input array needs an output array bigger than {@link Integer#MAX_VALUE} 256 */ 257 public static byte[] encodeBase64(final byte[] binaryData, final boolean isChunked) { 258 return encodeBase64(binaryData, isChunked, false); 259 } 260 261 /** 262 * Encodes binary data using the base64 algorithm, optionally chunking the output into 76 character blocks. 263 * 264 * @param binaryData 265 * Array containing binary data to encode. 266 * @param isChunked 267 * if {@code true} this encoder will chunk the base64 output into 76 character blocks 268 * @param urlSafe 269 * if {@code true} this encoder will emit - and _ instead of the usual + and / characters. 270 * <b>Note: no padding is added when encoding using the URL-safe alphabet.</b> 271 * @return Base64-encoded data. 272 * @throws IllegalArgumentException 273 * Thrown when the input array needs an output array bigger than {@link Integer#MAX_VALUE} 274 * @since 1.4 275 */ 276 public static byte[] encodeBase64(final byte[] binaryData, final boolean isChunked, final boolean urlSafe) { 277 return encodeBase64(binaryData, isChunked, urlSafe, Integer.MAX_VALUE); 278 } 279 280 /** 281 * Encodes binary data using the base64 algorithm, optionally chunking the output into 76 character blocks. 282 * 283 * @param binaryData 284 * Array containing binary data to encode. 285 * @param isChunked 286 * if {@code true} this encoder will chunk the base64 output into 76 character blocks 287 * @param urlSafe 288 * if {@code true} this encoder will emit - and _ instead of the usual + and / characters. 289 * <b>Note: no padding is added when encoding using the URL-safe alphabet.</b> 290 * @param maxResultSize 291 * The maximum result size to accept. 292 * @return Base64-encoded data. 293 * @throws IllegalArgumentException 294 * Thrown when the input array needs an output array bigger than maxResultSize 295 * @since 1.4 296 */ 297 public static byte[] encodeBase64(final byte[] binaryData, final boolean isChunked, 298 final boolean urlSafe, final int maxResultSize) { 299 if (BinaryCodec.isEmpty(binaryData)) { 300 return binaryData; 301 } 302 // Create this so can use the super-class method 303 // Also ensures that the same roundings are performed by the ctor and the code 304 final Base64 b64 = isChunked ? new Base64(urlSafe) : new Base64(0, CHUNK_SEPARATOR, urlSafe); 305 final long len = b64.getEncodedLength(binaryData); 306 if (len > maxResultSize) { 307 throw new IllegalArgumentException("Input array too big, the output array would be bigger (" + 308 len + 309 ") than the specified maximum size of " + 310 maxResultSize); 311 } 312 return b64.encode(binaryData); 313 } 314 315 /** 316 * Encodes binary data using the base64 algorithm and chunks the encoded output into 76 character blocks 317 * 318 * @param binaryData 319 * binary data to encode 320 * @return Base64 characters chunked in 76 character blocks 321 */ 322 public static byte[] encodeBase64Chunked(final byte[] binaryData) { 323 return encodeBase64(binaryData, true); 324 } 325 326 /** 327 * Encodes binary data using the base64 algorithm but does not chunk the output. 328 * 329 * NOTE: We changed the behavior of this method from multi-line chunking (commons-codec-1.4) to 330 * single-line non-chunking (commons-codec-1.5). 331 * 332 * @param binaryData 333 * binary data to encode 334 * @return String containing Base64 characters. 335 * @since 1.4 (NOTE: 1.4 chunked the output, whereas 1.5 does not). 336 */ 337 public static String encodeBase64String(final byte[] binaryData) { 338 return StringUtils.newStringUsAscii(encodeBase64(binaryData, false)); 339 } 340 341 /** 342 * Encodes binary data using a URL-safe variation of the base64 algorithm but does not chunk the output. The 343 * url-safe variation emits - and _ instead of + and / characters. 344 * <b>Note: no padding is added.</b> 345 * @param binaryData 346 * binary data to encode 347 * @return byte[] containing Base64 characters in their UTF-8 representation. 348 * @since 1.4 349 */ 350 public static byte[] encodeBase64URLSafe(final byte[] binaryData) { 351 return encodeBase64(binaryData, false, true); 352 } 353 354 /** 355 * Encodes binary data using a URL-safe variation of the base64 algorithm but does not chunk the output. The 356 * url-safe variation emits - and _ instead of + and / characters. 357 * <b>Note: no padding is added.</b> 358 * @param binaryData 359 * binary data to encode 360 * @return String containing Base64 characters 361 * @since 1.4 362 */ 363 public static String encodeBase64URLSafeString(final byte[] binaryData) { 364 return StringUtils.newStringUsAscii(encodeBase64(binaryData, false, true)); 365 } 366 367 /** 368 * Encodes to a byte64-encoded integer according to crypto standards such as W3C's XML-Signature. 369 * 370 * @param bigInteger 371 * a BigInteger 372 * @return A byte array containing base64 character data 373 * @throws NullPointerException 374 * if null is passed in 375 * @since 1.4 376 */ 377 public static byte[] encodeInteger(final BigInteger bigInteger) { 378 Objects.requireNonNull(bigInteger, "bigInteger"); 379 return encodeBase64(toIntegerBytes(bigInteger), false); 380 } 381 382 /** 383 * Tests a given byte array to see if it contains only valid characters within the Base64 alphabet. Currently the 384 * method treats whitespace as valid. 385 * 386 * @param arrayOctet 387 * byte array to test 388 * @return {@code true} if all bytes are valid characters in the Base64 alphabet or if the byte array is empty; 389 * {@code false}, otherwise 390 * @deprecated 1.5 Use {@link #isBase64(byte[])}, will be removed in 2.0. 391 */ 392 @Deprecated 393 public static boolean isArrayByteBase64(final byte[] arrayOctet) { 394 return isBase64(arrayOctet); 395 } 396 397 /** 398 * Returns whether or not the {@code octet} is in the base 64 alphabet. 399 * 400 * @param octet 401 * The value to test 402 * @return {@code true} if the value is defined in the base 64 alphabet, {@code false} otherwise. 403 * @since 1.4 404 */ 405 public static boolean isBase64(final byte octet) { 406 return octet == PAD_DEFAULT || octet >= 0 && octet < DECODE_TABLE.length && DECODE_TABLE[octet] != -1; 407 } 408 409 /** 410 * Tests a given byte array to see if it contains only valid characters within the Base64 alphabet. Currently the 411 * method treats whitespace as valid. 412 * 413 * @param arrayOctet 414 * byte array to test 415 * @return {@code true} if all bytes are valid characters in the Base64 alphabet or if the byte array is empty; 416 * {@code false}, otherwise 417 * @since 1.5 418 */ 419 public static boolean isBase64(final byte[] arrayOctet) { 420 for (final byte element : arrayOctet) { 421 if (!isBase64(element) && !Character.isWhitespace(element)) { 422 return false; 423 } 424 } 425 return true; 426 } 427 428 /** 429 * Tests a given String to see if it contains only valid characters within the Base64 alphabet. Currently the 430 * method treats whitespace as valid. 431 * 432 * @param base64 433 * String to test 434 * @return {@code true} if all characters in the String are valid characters in the Base64 alphabet or if 435 * the String is empty; {@code false}, otherwise 436 * @since 1.5 437 */ 438 public static boolean isBase64(final String base64) { 439 return isBase64(StringUtils.getBytesUtf8(base64)); 440 } 441 442 /** 443 * Returns a byte-array representation of a {@code BigInteger} without sign bit. 444 * 445 * @param bigInt 446 * {@code BigInteger} to be converted 447 * @return a byte array representation of the BigInteger parameter 448 */ 449 static byte[] toIntegerBytes(final BigInteger bigInt) { 450 int bitlen = bigInt.bitLength(); 451 // round bitlen 452 bitlen = bitlen + 7 >> 3 << 3; 453 final byte[] bigBytes = bigInt.toByteArray(); 454 455 if (bigInt.bitLength() % 8 != 0 && bigInt.bitLength() / 8 + 1 == bitlen / 8) { 456 return bigBytes; 457 } 458 // set up params for copying everything but sign bit 459 int startSrc = 0; 460 int len = bigBytes.length; 461 462 // if bigInt is exactly byte-aligned, just skip signbit in copy 463 if (bigInt.bitLength() % 8 == 0) { 464 startSrc = 1; 465 len--; 466 } 467 final int startDst = bitlen / 8 - len; // to pad w/ nulls as per spec 468 final byte[] resizedBytes = new byte[bitlen / 8]; 469 System.arraycopy(bigBytes, startSrc, resizedBytes, startDst, len); 470 return resizedBytes; 471 } 472 473 private static byte[] toUrlSafeEncodeTable(final boolean urlSafe) { 474 return urlSafe ? URL_SAFE_ENCODE_TABLE : STANDARD_ENCODE_TABLE; 475 } 476 477 /** 478 * Encode table to use: either STANDARD or URL_SAFE or custom. 479 * Note: the DECODE_TABLE above remains static because it is able 480 * to decode both STANDARD and URL_SAFE streams, but the encodeTable must be a member variable so we can switch 481 * between the two modes. 482 */ 483 private final byte[] encodeTable; 484 485 /** 486 * Decode table to use. 487 */ 488 private final byte[] decodeTable; 489 490 /** 491 * Line separator for encoding. Not used when decoding. Only used if lineLength > 0. 492 */ 493 private final byte[] lineSeparator; 494 495 /** 496 * Convenience variable to help us determine when our buffer is going to run out of room and needs resizing. 497 * {@code encodeSize = 4 + lineSeparator.length;} 498 */ 499 private final int encodeSize; 500 501 private final boolean isUrlSafe; 502 503 /** 504 * Constructs a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode. 505 * <p> 506 * When encoding the line length is 0 (no chunking), and the encoding table is STANDARD_ENCODE_TABLE. 507 * </p> 508 * <p> 509 * When decoding all variants are supported. 510 * </p> 511 */ 512 public Base64() { 513 this(0); 514 } 515 516 /** 517 * Constructs a Base64 codec used for decoding (all modes) and encoding in the given URL-safe mode. 518 * <p> 519 * When encoding the line length is 76, the line separator is CRLF, and the encoding table is STANDARD_ENCODE_TABLE. 520 * </p> 521 * <p> 522 * When decoding all variants are supported. 523 * </p> 524 * 525 * @param urlSafe 526 * if {@code true}, URL-safe encoding is used. In most cases this should be set to 527 * {@code false}. 528 * @since 1.4 529 */ 530 public Base64(final boolean urlSafe) { 531 this(MIME_CHUNK_SIZE, CHUNK_SEPARATOR, urlSafe); 532 } 533 534 535 /** 536 * Constructs a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode. 537 * <p> 538 * When encoding the line length is given in the constructor, the line separator is CRLF, and the encoding table is 539 * STANDARD_ENCODE_TABLE. 540 * </p> 541 * <p> 542 * Line lengths that aren't multiples of 4 will still essentially end up being multiples of 4 in the encoded data. 543 * </p> 544 * <p> 545 * When decoding all variants are supported. 546 * </p> 547 * 548 * @param lineLength 549 * Each line of encoded data will be at most of the given length (rounded down to the nearest multiple of 550 * 4). If lineLength <= 0, then the output will not be divided into lines (chunks). Ignored when 551 * decoding. 552 * @since 1.4 553 */ 554 public Base64(final int lineLength) { 555 this(lineLength, CHUNK_SEPARATOR); 556 } 557 558 /** 559 * Constructs a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode. 560 * <p> 561 * When encoding the line length and line separator are given in the constructor, and the encoding table is 562 * STANDARD_ENCODE_TABLE. 563 * </p> 564 * <p> 565 * Line lengths that aren't multiples of 4 will still essentially end up being multiples of 4 in the encoded data. 566 * </p> 567 * <p> 568 * When decoding all variants are supported. 569 * </p> 570 * 571 * @param lineLength 572 * Each line of encoded data will be at most of the given length (rounded down to the nearest multiple of 573 * 4). If lineLength <= 0, then the output will not be divided into lines (chunks). Ignored when 574 * decoding. 575 * @param lineSeparator 576 * Each line of encoded data will end with this sequence of bytes. 577 * @throws IllegalArgumentException 578 * Thrown when the provided lineSeparator included some base64 characters. 579 * @since 1.4 580 */ 581 public Base64(final int lineLength, final byte[] lineSeparator) { 582 this(lineLength, lineSeparator, false); 583 } 584 585 /** 586 * Constructs a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode. 587 * <p> 588 * When encoding the line length and line separator are given in the constructor, and the encoding table is 589 * STANDARD_ENCODE_TABLE. 590 * </p> 591 * <p> 592 * Line lengths that aren't multiples of 4 will still essentially end up being multiples of 4 in the encoded data. 593 * </p> 594 * <p> 595 * When decoding all variants are supported. 596 * </p> 597 * 598 * @param lineLength 599 * Each line of encoded data will be at most of the given length (rounded down to the nearest multiple of 600 * 4). If lineLength <= 0, then the output will not be divided into lines (chunks). Ignored when 601 * decoding. 602 * @param lineSeparator 603 * Each line of encoded data will end with this sequence of bytes. 604 * @param urlSafe 605 * Instead of emitting '+' and '/' we emit '-' and '_' respectively. urlSafe is only applied to encode 606 * operations. Decoding seamlessly handles both modes. 607 * <b>Note: no padding is added when using the URL-safe alphabet.</b> 608 * @throws IllegalArgumentException 609 * Thrown when the {@code lineSeparator} contains Base64 characters. 610 * @since 1.4 611 */ 612 public Base64(final int lineLength, final byte[] lineSeparator, final boolean urlSafe) { 613 this(lineLength, lineSeparator, PAD_DEFAULT, toUrlSafeEncodeTable(urlSafe), DECODING_POLICY_DEFAULT); 614 } 615 616 /** 617 * Constructs a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode. 618 * <p> 619 * When encoding the line length and line separator are given in the constructor, and the encoding table is 620 * STANDARD_ENCODE_TABLE. 621 * </p> 622 * <p> 623 * Line lengths that aren't multiples of 4 will still essentially end up being multiples of 4 in the encoded data. 624 * </p> 625 * <p> 626 * When decoding all variants are supported. 627 * </p> 628 * 629 * @param lineLength 630 * Each line of encoded data will be at most of the given length (rounded down to the nearest multiple of 631 * 4). If lineLength <= 0, then the output will not be divided into lines (chunks). Ignored when 632 * decoding. 633 * @param lineSeparator 634 * Each line of encoded data will end with this sequence of bytes. 635 * @param urlSafe 636 * Instead of emitting '+' and '/' we emit '-' and '_' respectively. urlSafe is only applied to encode 637 * operations. Decoding seamlessly handles both modes. 638 * <b>Note: no padding is added when using the URL-safe alphabet.</b> 639 * @param decodingPolicy The decoding policy. 640 * @throws IllegalArgumentException 641 * Thrown when the {@code lineSeparator} contains Base64 characters. 642 * @since 1.15 643 */ 644 public Base64(final int lineLength, final byte[] lineSeparator, final boolean urlSafe, final CodecPolicy decodingPolicy) { 645 this(lineLength, lineSeparator, PAD_DEFAULT, toUrlSafeEncodeTable(urlSafe), decodingPolicy); 646 } 647 648 /** 649 * Constructs a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode. 650 * <p> 651 * When encoding the line length and line separator are given in the constructor, and the encoding table is STANDARD_ENCODE_TABLE. 652 * </p> 653 * <p> 654 * Line lengths that aren't multiples of 4 will still essentially end up being multiples of 4 in the encoded data. 655 * </p> 656 * <p> 657 * When decoding all variants are supported. 658 * </p> 659 * 660 * @param lineLength Each line of encoded data will be at most of the given length (rounded down to the nearest multiple of 4). If lineLength <= 0, 661 * then the output will not be divided into lines (chunks). Ignored when decoding. 662 * @param lineSeparator Each line of encoded data will end with this sequence of bytes; the constructor makes a defensive copy. May be null. 663 * @param padding padding byte. 664 * @param encodeTable The manual encodeTable - a byte array of 64 chars. 665 * @param decodingPolicy The decoding policy. 666 * @throws IllegalArgumentException Thrown when the {@code lineSeparator} contains Base64 characters. 667 */ 668 private Base64(final int lineLength, final byte[] lineSeparator, final byte padding, final byte[] encodeTable, final CodecPolicy decodingPolicy) { 669 super(BYTES_PER_UNENCODED_BLOCK, BYTES_PER_ENCODED_BLOCK, lineLength, toLength(lineSeparator), padding, decodingPolicy); 670 Objects.requireNonNull(encodeTable, "encodeTable"); 671 if (encodeTable.length != ALPHABET_LENGTH) { 672 throw new IllegalArgumentException("encodeTable must have exactly 64 entries."); 673 } 674 this.isUrlSafe = encodeTable == URL_SAFE_ENCODE_TABLE; 675 if (encodeTable == STANDARD_ENCODE_TABLE || this.isUrlSafe) { 676 decodeTable = DECODE_TABLE; 677 // No need of a defensive copy of an internal table. 678 this.encodeTable = encodeTable; 679 } else { 680 this.encodeTable = encodeTable.clone(); 681 this.decodeTable = calculateDecodeTable(this.encodeTable); 682 } 683 // TODO could be simplified if there is no requirement to reject invalid line sep when length <=0 684 // @see test case Base64Test.testConstructors() 685 if (lineSeparator != null) { 686 final byte[] lineSeparatorCopy = lineSeparator.clone(); 687 if (containsAlphabetOrPad(lineSeparatorCopy)) { 688 final String sep = StringUtils.newStringUtf8(lineSeparatorCopy); 689 throw new IllegalArgumentException("lineSeparator must not contain base64 characters: [" + sep + "]"); 690 } 691 if (lineLength > 0) { // null line-sep forces no chunking rather than throwing IAE 692 this.encodeSize = BYTES_PER_ENCODED_BLOCK + lineSeparatorCopy.length; 693 this.lineSeparator = lineSeparatorCopy; 694 } else { 695 this.encodeSize = BYTES_PER_ENCODED_BLOCK; 696 this.lineSeparator = null; 697 } 698 } else { 699 this.encodeSize = BYTES_PER_ENCODED_BLOCK; 700 this.lineSeparator = null; 701 } 702 } 703 704 /** 705 * Calculates a decode table for a given encode table. 706 * 707 * @param encodeTable that is used to determine decode lookup table 708 * @return decodeTable 709 */ 710 private byte[] calculateDecodeTable(final byte[] encodeTable) { 711 final byte[] decodeTable = new byte[DECODING_TABLE_LENGTH]; 712 Arrays.fill(decodeTable, (byte) -1); 713 for (int i = 0; i < encodeTable.length; i++) { 714 decodeTable[encodeTable[i]] = (byte) i; 715 } 716 return decodeTable; 717 } 718 719 /** 720 * <p> 721 * Decodes all of the provided data, starting at inPos, for inAvail bytes. Should be called at least twice: once 722 * with the data to decode, and once with inAvail set to "-1" to alert decoder that EOF has been reached. The "-1" 723 * call is not necessary when decoding, but it doesn't hurt, either. 724 * </p> 725 * <p> 726 * Ignores all non-base64 characters. This is how chunked (e.g. 76 character) data is handled, since CR and LF are 727 * silently ignored, but has implications for other bytes, too. This method subscribes to the garbage-in, 728 * garbage-out philosophy: it will not check the provided data for validity. 729 * </p> 730 * <p> 731 * Thanks to "commons" project in ws.apache.org for the bitwise operations, and general approach. 732 * https://svn.apache.org/repos/asf/webservices/commons/trunk/modules/util/ 733 * </p> 734 * 735 * @param input 736 * byte[] array of ASCII data to base64 decode. 737 * @param inPos 738 * Position to start reading data from. 739 * @param inAvail 740 * Amount of bytes available from input for decoding. 741 * @param context 742 * the context to be used 743 */ 744 @Override 745 void decode(final byte[] input, int inPos, final int inAvail, final Context context) { 746 if (context.eof) { 747 return; 748 } 749 if (inAvail < 0) { 750 context.eof = true; 751 } 752 final int decodeSize = this.encodeSize - 1; 753 for (int i = 0; i < inAvail; i++) { 754 final byte[] buffer = ensureBufferSize(decodeSize, context); 755 final byte b = input[inPos++]; 756 if (b == pad) { 757 // We're done. 758 context.eof = true; 759 break; 760 } 761 if (b >= 0 && b < decodeTable.length) { 762 final int result = decodeTable[b]; 763 if (result >= 0) { 764 context.modulus = (context.modulus + 1) % BYTES_PER_ENCODED_BLOCK; 765 context.ibitWorkArea = (context.ibitWorkArea << BITS_PER_ENCODED_BYTE) + result; 766 if (context.modulus == 0) { 767 buffer[context.pos++] = (byte) (context.ibitWorkArea >> 16 & MASK_8BITS); 768 buffer[context.pos++] = (byte) (context.ibitWorkArea >> 8 & MASK_8BITS); 769 buffer[context.pos++] = (byte) (context.ibitWorkArea & MASK_8BITS); 770 } 771 } 772 } 773 } 774 775 // Two forms of EOF as far as base64 decoder is concerned: actual 776 // EOF (-1) and first time '=' character is encountered in stream. 777 // This approach makes the '=' padding characters completely optional. 778 if (context.eof && context.modulus != 0) { 779 final byte[] buffer = ensureBufferSize(decodeSize, context); 780 781 // We have some spare bits remaining 782 // Output all whole multiples of 8 bits and ignore the rest 783 switch (context.modulus) { 784// case 0 : // impossible, as excluded above 785 case 1 : // 6 bits - either ignore entirely, or raise an exception 786 validateTrailingCharacter(); 787 break; 788 case 2 : // 12 bits = 8 + 4 789 validateCharacter(MASK_4BITS, context); 790 context.ibitWorkArea = context.ibitWorkArea >> 4; // dump the extra 4 bits 791 buffer[context.pos++] = (byte) (context.ibitWorkArea & MASK_8BITS); 792 break; 793 case 3 : // 18 bits = 8 + 8 + 2 794 validateCharacter(MASK_2BITS, context); 795 context.ibitWorkArea = context.ibitWorkArea >> 2; // dump 2 bits 796 buffer[context.pos++] = (byte) (context.ibitWorkArea >> 8 & MASK_8BITS); 797 buffer[context.pos++] = (byte) (context.ibitWorkArea & MASK_8BITS); 798 break; 799 default: 800 throw new IllegalStateException("Impossible modulus " + context.modulus); 801 } 802 } 803 } 804 805 /** 806 * <p> 807 * Encodes all of the provided data, starting at inPos, for inAvail bytes. Must be called at least twice: once with 808 * the data to encode, and once with inAvail set to "-1" to alert encoder that EOF has been reached, to flush last 809 * remaining bytes (if not multiple of 3). 810 * </p> 811 * <p><b>Note: no padding is added when encoding using the URL-safe alphabet.</b></p> 812 * <p> 813 * Thanks to "commons" project in ws.apache.org for the bitwise operations, and general approach. 814 * https://svn.apache.org/repos/asf/webservices/commons/trunk/modules/util/ 815 * </p> 816 * 817 * @param in 818 * byte[] array of binary data to base64 encode. 819 * @param inPos 820 * Position to start reading data from. 821 * @param inAvail 822 * Amount of bytes available from input for encoding. 823 * @param context 824 * the context to be used 825 */ 826 @Override 827 void encode(final byte[] in, int inPos, final int inAvail, final Context context) { 828 if (context.eof) { 829 return; 830 } 831 // inAvail < 0 is how we're informed of EOF in the underlying data we're 832 // encoding. 833 if (inAvail < 0) { 834 context.eof = true; 835 if (0 == context.modulus && lineLength == 0) { 836 return; // no leftovers to process and not using chunking 837 } 838 final byte[] buffer = ensureBufferSize(encodeSize, context); 839 final int savedPos = context.pos; 840 switch (context.modulus) { // 0-2 841 case 0 : // nothing to do here 842 break; 843 case 1 : // 8 bits = 6 + 2 844 // top 6 bits: 845 buffer[context.pos++] = encodeTable[context.ibitWorkArea >> 2 & MASK_6BITS]; 846 // remaining 2: 847 buffer[context.pos++] = encodeTable[context.ibitWorkArea << 4 & MASK_6BITS]; 848 // URL-SAFE skips the padding to further reduce size. 849 if (encodeTable == STANDARD_ENCODE_TABLE) { 850 buffer[context.pos++] = pad; 851 buffer[context.pos++] = pad; 852 } 853 break; 854 855 case 2 : // 16 bits = 6 + 6 + 4 856 buffer[context.pos++] = encodeTable[context.ibitWorkArea >> 10 & MASK_6BITS]; 857 buffer[context.pos++] = encodeTable[context.ibitWorkArea >> 4 & MASK_6BITS]; 858 buffer[context.pos++] = encodeTable[context.ibitWorkArea << 2 & MASK_6BITS]; 859 // URL-SAFE skips the padding to further reduce size. 860 if (encodeTable == STANDARD_ENCODE_TABLE) { 861 buffer[context.pos++] = pad; 862 } 863 break; 864 default: 865 throw new IllegalStateException("Impossible modulus " + context.modulus); 866 } 867 context.currentLinePos += context.pos - savedPos; // keep track of current line position 868 // if currentPos == 0 we are at the start of a line, so don't add CRLF 869 if (lineLength > 0 && context.currentLinePos > 0) { 870 System.arraycopy(lineSeparator, 0, buffer, context.pos, lineSeparator.length); 871 context.pos += lineSeparator.length; 872 } 873 } else { 874 for (int i = 0; i < inAvail; i++) { 875 final byte[] buffer = ensureBufferSize(encodeSize, context); 876 context.modulus = (context.modulus + 1) % BYTES_PER_UNENCODED_BLOCK; 877 int b = in[inPos++]; 878 if (b < 0) { 879 b += 256; 880 } 881 context.ibitWorkArea = (context.ibitWorkArea << 8) + b; // BITS_PER_BYTE 882 if (0 == context.modulus) { // 3 bytes = 24 bits = 4 * 6 bits to extract 883 buffer[context.pos++] = encodeTable[context.ibitWorkArea >> 18 & MASK_6BITS]; 884 buffer[context.pos++] = encodeTable[context.ibitWorkArea >> 12 & MASK_6BITS]; 885 buffer[context.pos++] = encodeTable[context.ibitWorkArea >> 6 & MASK_6BITS]; 886 buffer[context.pos++] = encodeTable[context.ibitWorkArea & MASK_6BITS]; 887 context.currentLinePos += BYTES_PER_ENCODED_BLOCK; 888 if (lineLength > 0 && lineLength <= context.currentLinePos) { 889 System.arraycopy(lineSeparator, 0, buffer, context.pos, lineSeparator.length); 890 context.pos += lineSeparator.length; 891 context.currentLinePos = 0; 892 } 893 } 894 } 895 } 896 } 897 898 /** 899 * Gets the line separator (for testing only). 900 * 901 * @return the line separator. 902 */ 903 byte[] getLineSeparator() { 904 return lineSeparator; 905 } 906 907 /** 908 * Returns whether or not the {@code octet} is in the Base64 alphabet. 909 * 910 * @param octet 911 * The value to test 912 * @return {@code true} if the value is defined in the Base64 alphabet {@code false} otherwise. 913 */ 914 @Override 915 protected boolean isInAlphabet(final byte octet) { 916 return octet >= 0 && octet < decodeTable.length && decodeTable[octet] != -1; 917 } 918 919 /** 920 * Returns our current encode mode. True if we're URL-safe, false otherwise. 921 * 922 * @return true if we're in URL-safe mode, false otherwise. 923 * @since 1.4 924 */ 925 public boolean isUrlSafe() { 926 return isUrlSafe; 927 } 928 929 /** 930 * Validates whether decoding the final trailing character is possible in the context 931 * of the set of possible base 64 values. 932 * <p> 933 * The character is valid if the lower bits within the provided mask are zero. This 934 * is used to test the final trailing base-64 digit is zero in the bits that will be discarded. 935 * </p> 936 * 937 * @param emptyBitsMask The mask of the lower bits that should be empty 938 * @param context the context to be used 939 * 940 * @throws IllegalArgumentException if the bits being checked contain any non-zero value 941 */ 942 private void validateCharacter(final int emptyBitsMask, final Context context) { 943 if (isStrictDecoding() && (context.ibitWorkArea & emptyBitsMask) != 0) { 944 throw new IllegalArgumentException( 945 "Strict decoding: Last encoded character (before the paddings if any) is a valid " + 946 "base 64 alphabet but not a possible encoding. " + 947 "Expected the discarded bits from the character to be zero."); 948 } 949 } 950 951 /** 952 * Validates whether decoding allows an entire final trailing character that cannot be 953 * used for a complete byte. 954 * 955 * @throws IllegalArgumentException if strict decoding is enabled 956 */ 957 private void validateTrailingCharacter() { 958 if (isStrictDecoding()) { 959 throw new IllegalArgumentException( 960 "Strict decoding: Last encoded character (before the paddings if any) is a valid " + 961 "base 64 alphabet but not a possible encoding. " + 962 "Decoding requires at least two trailing 6-bit characters to create bytes."); 963 } 964 } 965 966}