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 {@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 * <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 /**
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 * <b>Note: no padding is added when encoding using the URL-safe alphabet.</b>
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 * <b>Note: no padding is added when encoding using the URL-safe alphabet.</b>
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 * <b>Note: no padding is added.</b>
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 * <b>Note: no padding is added.</b>
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 /**
535 * Constructs a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode.
536 * <p>
537 * When encoding the line length is given in the constructor, the line separator is CRLF, and the encoding table is
538 * STANDARD_ENCODE_TABLE.
539 * </p>
540 * <p>
541 * Line lengths that aren't multiples of 4 will still essentially end up being multiples of 4 in the encoded data.
542 * </p>
543 * <p>
544 * When decoding all variants are supported.
545 * </p>
546 *
547 * @param lineLength
548 * Each line of encoded data will be at most of the given length (rounded down to the nearest multiple of
549 * 4). If lineLength <= 0, then the output will not be divided into lines (chunks). Ignored when
550 * decoding.
551 * @since 1.4
552 */
553 public Base64(final int lineLength) {
554 this(lineLength, CHUNK_SEPARATOR);
555 }
556
557 /**
558 * Constructs a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode.
559 * <p>
560 * When encoding the line length and line separator are given in the constructor, and the encoding table is
561 * STANDARD_ENCODE_TABLE.
562 * </p>
563 * <p>
564 * Line lengths that aren't multiples of 4 will still essentially end up being multiples of 4 in the encoded data.
565 * </p>
566 * <p>
567 * When decoding all variants are supported.
568 * </p>
569 *
570 * @param lineLength
571 * Each line of encoded data will be at most of the given length (rounded down to the nearest multiple of
572 * 4). If lineLength <= 0, then the output will not be divided into lines (chunks). Ignored when
573 * decoding.
574 * @param lineSeparator
575 * Each line of encoded data will end with this sequence of bytes.
576 * @throws IllegalArgumentException
577 * Thrown when the provided lineSeparator included some base64 characters.
578 * @since 1.4
579 */
580 public Base64(final int lineLength, final byte[] lineSeparator) {
581 this(lineLength, lineSeparator, false);
582 }
583
584 /**
585 * Constructs a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode.
586 * <p>
587 * When encoding the line length and line separator are given in the constructor, and the encoding table is
588 * STANDARD_ENCODE_TABLE.
589 * </p>
590 * <p>
591 * Line lengths that aren't multiples of 4 will still essentially end up being multiples of 4 in the encoded data.
592 * </p>
593 * <p>
594 * When decoding all variants are supported.
595 * </p>
596 *
597 * @param lineLength
598 * Each line of encoded data will be at most of the given length (rounded down to the nearest multiple of
599 * 4). If lineLength <= 0, then the output will not be divided into lines (chunks). Ignored when
600 * decoding.
601 * @param lineSeparator
602 * Each line of encoded data will end with this sequence of bytes.
603 * @param urlSafe
604 * Instead of emitting '+' and '/' we emit '-' and '_' respectively. urlSafe is only applied to encode
605 * operations. Decoding seamlessly handles both modes.
606 * <b>Note: no padding is added when using the URL-safe alphabet.</b>
607 * @throws IllegalArgumentException
608 * Thrown when the {@code lineSeparator} contains Base64 characters.
609 * @since 1.4
610 */
611 public Base64(final int lineLength, final byte[] lineSeparator, final boolean urlSafe) {
612 this(lineLength, lineSeparator, PAD_DEFAULT, toUrlSafeEncodeTable(urlSafe), DECODING_POLICY_DEFAULT);
613 }
614
615 /**
616 * Constructs a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode.
617 * <p>
618 * When encoding the line length and line separator are given in the constructor, and the encoding table is
619 * STANDARD_ENCODE_TABLE.
620 * </p>
621 * <p>
622 * Line lengths that aren't multiples of 4 will still essentially end up being multiples of 4 in the encoded data.
623 * </p>
624 * <p>
625 * When decoding all variants are supported.
626 * </p>
627 *
628 * @param lineLength
629 * Each line of encoded data will be at most of the given length (rounded down to the nearest multiple of
630 * 4). If lineLength <= 0, then the output will not be divided into lines (chunks). Ignored when
631 * decoding.
632 * @param lineSeparator
633 * Each line of encoded data will end with this sequence of bytes.
634 * @param urlSafe
635 * Instead of emitting '+' and '/' we emit '-' and '_' respectively. urlSafe is only applied to encode
636 * operations. Decoding seamlessly handles both modes.
637 * <b>Note: no padding is added when using the URL-safe alphabet.</b>
638 * @param decodingPolicy The decoding policy.
639 * @throws IllegalArgumentException
640 * Thrown when the {@code lineSeparator} contains Base64 characters.
641 * @since 1.15
642 */
643 public Base64(final int lineLength, final byte[] lineSeparator, final boolean urlSafe, final CodecPolicy decodingPolicy) {
644 this(lineLength, lineSeparator, PAD_DEFAULT, toUrlSafeEncodeTable(urlSafe), decodingPolicy);
645 }
646
647 /**
648 * Constructs a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode.
649 * <p>
650 * When encoding the line length and line separator are given in the constructor, and the encoding table is STANDARD_ENCODE_TABLE.
651 * </p>
652 * <p>
653 * Line lengths that aren't multiples of 4 will still essentially end up being multiples of 4 in the encoded data.
654 * </p>
655 * <p>
656 * When decoding all variants are supported.
657 * </p>
658 *
659 * @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,
660 * then the output will not be divided into lines (chunks). Ignored when decoding.
661 * @param lineSeparator Each line of encoded data will end with this sequence of bytes; the constructor makes a defensive copy. May be null.
662 * @param padding padding byte.
663 * @param encodeTable The manual encodeTable - a byte array of 64 chars.
664 * @param decodingPolicy The decoding policy.
665 * @throws IllegalArgumentException Thrown when the {@code lineSeparator} contains Base64 characters.
666 */
667 private Base64(final int lineLength, final byte[] lineSeparator, final byte padding, final byte[] encodeTable, final CodecPolicy decodingPolicy) {
668 super(BYTES_PER_UNENCODED_BLOCK, BYTES_PER_ENCODED_BLOCK, lineLength, toLength(lineSeparator), padding, decodingPolicy);
669 Objects.requireNonNull(encodeTable, "encodeTable");
670 if (encodeTable.length != ALPHABET_LENGTH) {
671 throw new IllegalArgumentException("encodeTable must have exactly 64 entries.");
672 }
673 this.isUrlSafe = encodeTable == URL_SAFE_ENCODE_TABLE;
674 if (encodeTable == STANDARD_ENCODE_TABLE || this.isUrlSafe) {
675 decodeTable = DECODE_TABLE;
676 // No need of a defensive copy of an internal table.
677 this.encodeTable = encodeTable;
678 } else {
679 this.encodeTable = encodeTable.clone();
680 this.decodeTable = calculateDecodeTable(this.encodeTable);
681 }
682 // TODO could be simplified if there is no requirement to reject invalid line sep when length <=0
683 // @see test case Base64Test.testConstructors()
684 if (lineSeparator != null) {
685 final byte[] lineSeparatorCopy = lineSeparator.clone();
686 if (containsAlphabetOrPad(lineSeparatorCopy)) {
687 final String sep = StringUtils.newStringUtf8(lineSeparatorCopy);
688 throw new IllegalArgumentException("lineSeparator must not contain base64 characters: [" + sep + "]");
689 }
690 if (lineLength > 0) { // null line-sep forces no chunking rather than throwing IAE
691 this.encodeSize = BYTES_PER_ENCODED_BLOCK + lineSeparatorCopy.length;
692 this.lineSeparator = lineSeparatorCopy;
693 } else {
694 this.encodeSize = BYTES_PER_ENCODED_BLOCK;
695 this.lineSeparator = null;
696 }
697 } else {
698 this.encodeSize = BYTES_PER_ENCODED_BLOCK;
699 this.lineSeparator = null;
700 }
701 }
702
703 /**
704 * Calculates a decode table for a given encode table.
705 *
706 * @param encodeTable that is used to determine decode lookup table
707 * @return decodeTable
708 */
709 private byte[] calculateDecodeTable(final byte[] encodeTable) {
710 final byte[] decodeTable = new byte[DECODING_TABLE_LENGTH];
711 Arrays.fill(decodeTable, (byte) -1);
712 for (int i = 0; i < encodeTable.length; i++) {
713 decodeTable[encodeTable[i]] = (byte) i;
714 }
715 return decodeTable;
716 }
717
718 /**
719 * <p>
720 * Decodes all of the provided data, starting at inPos, for inAvail bytes. Should be called at least twice: once
721 * with the data to decode, and once with inAvail set to "-1" to alert decoder that EOF has been reached. The "-1"
722 * call is not necessary when decoding, but it doesn't hurt, either.
723 * </p>
724 * <p>
725 * Ignores all non-base64 characters. This is how chunked (e.g. 76 character) data is handled, since CR and LF are
726 * silently ignored, but has implications for other bytes, too. This method subscribes to the garbage-in,
727 * garbage-out philosophy: it will not check the provided data for validity.
728 * </p>
729 * <p>
730 * Thanks to "commons" project in ws.apache.org for the bitwise operations, and general approach.
731 * https://svn.apache.org/repos/asf/webservices/commons/trunk/modules/util/
732 * </p>
733 *
734 * @param input
735 * byte[] array of ASCII data to base64 decode.
736 * @param inPos
737 * Position to start reading data from.
738 * @param inAvail
739 * Amount of bytes available from input for decoding.
740 * @param context
741 * the context to be used
742 */
743 @Override
744 void decode(final byte[] input, int inPos, final int inAvail, final Context context) {
745 if (context.eof) {
746 return;
747 }
748 if (inAvail < 0) {
749 context.eof = true;
750 }
751 final int decodeSize = this.encodeSize - 1;
752 for (int i = 0; i < inAvail; i++) {
753 final byte[] buffer = ensureBufferSize(decodeSize, context);
754 final byte b = input[inPos++];
755 if (b == pad) {
756 // We're done.
757 context.eof = true;
758 break;
759 }
760 if (b >= 0 && b < decodeTable.length) {
761 final int result = decodeTable[b];
762 if (result >= 0) {
763 context.modulus = (context.modulus + 1) % BYTES_PER_ENCODED_BLOCK;
764 context.ibitWorkArea = (context.ibitWorkArea << BITS_PER_ENCODED_BYTE) + result;
765 if (context.modulus == 0) {
766 buffer[context.pos++] = (byte) (context.ibitWorkArea >> 16 & MASK_8BITS);
767 buffer[context.pos++] = (byte) (context.ibitWorkArea >> 8 & MASK_8BITS);
768 buffer[context.pos++] = (byte) (context.ibitWorkArea & MASK_8BITS);
769 }
770 }
771 }
772 }
773
774 // Two forms of EOF as far as base64 decoder is concerned: actual
775 // EOF (-1) and first time '=' character is encountered in stream.
776 // This approach makes the '=' padding characters completely optional.
777 if (context.eof && context.modulus != 0) {
778 final byte[] buffer = ensureBufferSize(decodeSize, context);
779
780 // We have some spare bits remaining
781 // Output all whole multiples of 8 bits and ignore the rest
782 switch (context.modulus) {
783 // case 0 : // impossible, as excluded above
784 case 1 : // 6 bits - either ignore entirely, or raise an exception
785 validateTrailingCharacter();
786 break;
787 case 2 : // 12 bits = 8 + 4
788 validateCharacter(MASK_4BITS, context);
789 context.ibitWorkArea = context.ibitWorkArea >> 4; // dump the extra 4 bits
790 buffer[context.pos++] = (byte) (context.ibitWorkArea & MASK_8BITS);
791 break;
792 case 3 : // 18 bits = 8 + 8 + 2
793 validateCharacter(MASK_2BITS, context);
794 context.ibitWorkArea = context.ibitWorkArea >> 2; // dump 2 bits
795 buffer[context.pos++] = (byte) (context.ibitWorkArea >> 8 & MASK_8BITS);
796 buffer[context.pos++] = (byte) (context.ibitWorkArea & MASK_8BITS);
797 break;
798 default:
799 throw new IllegalStateException("Impossible modulus " + context.modulus);
800 }
801 }
802 }
803
804 /**
805 * <p>
806 * Encodes all of the provided data, starting at inPos, for inAvail bytes. Must be called at least twice: once with
807 * the data to encode, and once with inAvail set to "-1" to alert encoder that EOF has been reached, to flush last
808 * remaining bytes (if not multiple of 3).
809 * </p>
810 * <p><b>Note: no padding is added when encoding using the URL-safe alphabet.</b></p>
811 * <p>
812 * Thanks to "commons" project in ws.apache.org for the bitwise operations, and general approach.
813 * https://svn.apache.org/repos/asf/webservices/commons/trunk/modules/util/
814 * </p>
815 *
816 * @param in
817 * byte[] array of binary data to base64 encode.
818 * @param inPos
819 * Position to start reading data from.
820 * @param inAvail
821 * Amount of bytes available from input for encoding.
822 * @param context
823 * the context to be used
824 */
825 @Override
826 void encode(final byte[] in, int inPos, final int inAvail, final Context context) {
827 if (context.eof) {
828 return;
829 }
830 // inAvail < 0 is how we're informed of EOF in the underlying data we're
831 // encoding.
832 if (inAvail < 0) {
833 context.eof = true;
834 if (0 == context.modulus && lineLength == 0) {
835 return; // no leftovers to process and not using chunking
836 }
837 final byte[] buffer = ensureBufferSize(encodeSize, context);
838 final int savedPos = context.pos;
839 switch (context.modulus) { // 0-2
840 case 0 : // nothing to do here
841 break;
842 case 1 : // 8 bits = 6 + 2
843 // top 6 bits:
844 buffer[context.pos++] = encodeTable[context.ibitWorkArea >> 2 & MASK_6BITS];
845 // remaining 2:
846 buffer[context.pos++] = encodeTable[context.ibitWorkArea << 4 & MASK_6BITS];
847 // URL-SAFE skips the padding to further reduce size.
848 if (encodeTable == STANDARD_ENCODE_TABLE) {
849 buffer[context.pos++] = pad;
850 buffer[context.pos++] = pad;
851 }
852 break;
853
854 case 2 : // 16 bits = 6 + 6 + 4
855 buffer[context.pos++] = encodeTable[context.ibitWorkArea >> 10 & MASK_6BITS];
856 buffer[context.pos++] = encodeTable[context.ibitWorkArea >> 4 & MASK_6BITS];
857 buffer[context.pos++] = encodeTable[context.ibitWorkArea << 2 & MASK_6BITS];
858 // URL-SAFE skips the padding to further reduce size.
859 if (encodeTable == STANDARD_ENCODE_TABLE) {
860 buffer[context.pos++] = pad;
861 }
862 break;
863 default:
864 throw new IllegalStateException("Impossible modulus " + context.modulus);
865 }
866 context.currentLinePos += context.pos - savedPos; // keep track of current line position
867 // if currentPos == 0 we are at the start of a line, so don't add CRLF
868 if (lineLength > 0 && context.currentLinePos > 0) {
869 System.arraycopy(lineSeparator, 0, buffer, context.pos, lineSeparator.length);
870 context.pos += lineSeparator.length;
871 }
872 } else {
873 for (int i = 0; i < inAvail; i++) {
874 final byte[] buffer = ensureBufferSize(encodeSize, context);
875 context.modulus = (context.modulus + 1) % BYTES_PER_UNENCODED_BLOCK;
876 int b = in[inPos++];
877 if (b < 0) {
878 b += 256;
879 }
880 context.ibitWorkArea = (context.ibitWorkArea << 8) + b; // BITS_PER_BYTE
881 if (0 == context.modulus) { // 3 bytes = 24 bits = 4 * 6 bits to extract
882 buffer[context.pos++] = encodeTable[context.ibitWorkArea >> 18 & MASK_6BITS];
883 buffer[context.pos++] = encodeTable[context.ibitWorkArea >> 12 & MASK_6BITS];
884 buffer[context.pos++] = encodeTable[context.ibitWorkArea >> 6 & MASK_6BITS];
885 buffer[context.pos++] = encodeTable[context.ibitWorkArea & MASK_6BITS];
886 context.currentLinePos += BYTES_PER_ENCODED_BLOCK;
887 if (lineLength > 0 && lineLength <= context.currentLinePos) {
888 System.arraycopy(lineSeparator, 0, buffer, context.pos, lineSeparator.length);
889 context.pos += lineSeparator.length;
890 context.currentLinePos = 0;
891 }
892 }
893 }
894 }
895 }
896
897 /**
898 * Gets the line separator (for testing only).
899 *
900 * @return the line separator.
901 */
902 byte[] getLineSeparator() {
903 return lineSeparator;
904 }
905
906 /**
907 * Returns whether or not the {@code octet} is in the Base64 alphabet.
908 *
909 * @param octet
910 * The value to test
911 * @return {@code true} if the value is defined in the Base64 alphabet {@code false} otherwise.
912 */
913 @Override
914 protected boolean isInAlphabet(final byte octet) {
915 return octet >= 0 && octet < decodeTable.length && decodeTable[octet] != -1;
916 }
917
918 /**
919 * Returns our current encode mode. True if we're URL-safe, false otherwise.
920 *
921 * @return true if we're in URL-safe mode, false otherwise.
922 * @since 1.4
923 */
924 public boolean isUrlSafe() {
925 return isUrlSafe;
926 }
927
928 /**
929 * Validates whether decoding the final trailing character is possible in the context
930 * of the set of possible base 64 values.
931 * <p>
932 * The character is valid if the lower bits within the provided mask are zero. This
933 * is used to test the final trailing base-64 digit is zero in the bits that will be discarded.
934 * </p>
935 *
936 * @param emptyBitsMask The mask of the lower bits that should be empty
937 * @param context the context to be used
938 *
939 * @throws IllegalArgumentException if the bits being checked contain any non-zero value
940 */
941 private void validateCharacter(final int emptyBitsMask, final Context context) {
942 if (isStrictDecoding() && (context.ibitWorkArea & emptyBitsMask) != 0) {
943 throw new IllegalArgumentException(
944 "Strict decoding: Last encoded character (before the paddings if any) is a valid " +
945 "base 64 alphabet but not a possible encoding. " +
946 "Expected the discarded bits from the character to be zero.");
947 }
948 }
949
950 /**
951 * Validates whether decoding allows an entire final trailing character that cannot be
952 * used for a complete byte.
953 *
954 * @throws IllegalArgumentException if strict decoding is enabled
955 */
956 private void validateTrailingCharacter() {
957 if (isStrictDecoding()) {
958 throw new IllegalArgumentException(
959 "Strict decoding: Last encoded character (before the paddings if any) is a valid " +
960 "base 64 alphabet but not a possible encoding. " +
961 "Decoding requires at least two trailing 6-bit characters to create bytes.");
962 }
963 }
964
965 }