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