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