1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
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 this.
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 * <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 }