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.util.Arrays;
21
22 import org.apache.commons.codec.CodecPolicy;
23
24 /**
25 * Provides Base32 encoding and decoding as defined by <a href="https://www.ietf.org/rfc/rfc4648.txt">RFC 4648</a>.
26 *
27 * <p>
28 * The class can be parameterized in the following manner with various constructors:
29 * </p>
30 * <ul>
31 * <li>Whether to use the "base32hex" variant instead of the default "base32"</li>
32 * <li>Line length: Default 76. Line length that aren't multiples of 8 will still essentially end up being multiples of 8 in the encoded data.
33 * <li>Line separator: Default is CRLF ("\r\n")</li>
34 * </ul>
35 * <p>
36 * This class operates directly on byte streams, and not character streams.
37 * </p>
38 * <p>
39 * This class is thread-safe.
40 * </p>
41 * <p>
42 * To configure a new instance, use a {@link Builder}. For example:
43 * </p>
44 * <pre>
45 * Base32 base32 = Base32.builder()
46 * .setDecodingPolicy(DecodingPolicy.LENIENT) // default is lenient
47 * .setLineLength(0) // default is none
48 * .setLineSeparator('\r', '\n') // default is CR LF
49 * .setPadding('=') // default is '='
50 * .setEncodeTable(customEncodeTable) // default is RFC 4648 Section 6, Table 3: The Base 32 Alphabet
51 * .get()
52 * </pre>
53 *
54 * @see Base32InputStream
55 * @see Base32OutputStream
56 * @see <a href="https://www.ietf.org/rfc/rfc4648.txt">RFC 4648</a>
57 * @since 1.5
58 */
59 public class Base32 extends BaseNCodec {
60
61 /**
62 * Builds {@link Base32} instances.
63 *
64 * <p>
65 * To configure a new instance, use a {@link Builder}. For example:
66 * </p>
67 *
68 * <pre>
69 * Base32 base32 = Base32.builder()
70 * .setDecodingPolicy(DecodingPolicy.LENIENT) // default is lenient
71 * .setLineLength(0) // default is none
72 * .setLineSeparator('\r', '\n') // default is CR LF
73 * .setPadding('=') // default is '='
74 * .setEncodeTable(customEncodeTable) // default is RFC 4648 Section 6, Table 3: The Base 32 Alphabet
75 * .get()
76 * </pre>
77 *
78 * @since 1.17.0
79 */
80 public static class Builder extends AbstractBuilder<Base32, Builder> {
81
82 /**
83 * Constructs a new instance using <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">RFC 4648 Section 6, Table 3: The Base 32
84 * Alphabet</a>.
85 */
86 public Builder() {
87 super(ENCODE_TABLE);
88 setDecodeTableRaw(DECODE_TABLE);
89 setEncodeTableRaw(ENCODE_TABLE);
90 setEncodedBlockSize(BYTES_PER_ENCODED_BLOCK);
91 setUnencodedBlockSize(BYTES_PER_UNENCODED_BLOCK);
92 }
93
94 @Override
95 public Base32 get() {
96 return new Base32(this);
97 }
98
99 /**
100 * Sets the encode table and derives the matching decode table.
101 * <p>
102 * The RFC 4648 Base32 and Base32 Hex tables keep their case-insensitive decoders.
103 * </p>
104 *
105 * @param encodeTable The encode table with exactly 32 unique entries, null resets to the default.
106 * @return {@code this} instance.
107 * @throws IllegalArgumentException if the encode table does not contain exactly 32 unique entries.
108 */
109 @Override
110 public Builder setEncodeTable(final byte... encodeTable) {
111 super.setDecodeTableRaw(toDecodeTable(encodeTable));
112 return super.setEncodeTable(encodeTable);
113 }
114
115 /**
116 * Sets the encode and decode tables to use Base32 hexadecimal if {@code true}, otherwise use the Base32 alphabet.
117 * <p>
118 * This overrides a value previously set with {@link #setEncodeTable(byte...)}.
119 * </p>
120 *
121 * @param useHex use Base32 hexadecimal if {@code true}, otherwise use the Base32 alphabet.
122 * @return {@code this} instance.
123 * @since 1.18.0
124 */
125 public Builder setHexDecodeTable(final boolean useHex) {
126 return setEncodeTable(encodeTable(useHex));
127 }
128
129 /**
130 * Sets the encode table to use Base32 hexadecimal if {@code true}, otherwise use the Base32 alphabet.
131 * <p>
132 * This overrides a value previously set with {@link #setEncodeTable(byte...)}.
133 * </p>
134 *
135 * @param useHex
136 * <ul>
137 * <li>If true, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-7">RFC 4648 Section 7, Table 4: Base 32 Encoding
138 * with Extended Hex Alphabet</a></li>
139 * <li>If false, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">RFC 4648 Section 6, Table 3: The Base 32
140 * Alphabet</a></li>
141 * </ul>
142 * @return {@code this} instance.
143 * @since 1.18.0
144 */
145 public Builder setHexEncodeTable(final boolean useHex) {
146 return setEncodeTable(encodeTable(useHex));
147 }
148 }
149
150 /**
151 * BASE32 characters are 5 bits in length. They are formed by taking a block of five octets to form a 40-bit string, which is converted into eight BASE32
152 * characters.
153 */
154 private static final int BITS_PER_ENCODED_BYTE = 5;
155
156 private static final int BYTES_PER_ENCODED_BLOCK = 8;
157 private static final int BYTES_PER_UNENCODED_BLOCK = 5;
158 private static final int DECODING_TABLE_LENGTH = 256;
159 private static final int ENCODING_TABLE_LENGTH = 1 << BITS_PER_ENCODED_BYTE;
160
161 /**
162 * This array is a lookup table that translates Unicode characters drawn from the "Base32 Alphabet" (as specified in Table 3 of RFC 4648) into their 5-bit
163 * positive integer equivalents. Characters that are not in the Base32 alphabet but fall within the bounds of the array are translated to -1.
164 */
165 // @formatter:off
166 private static final byte[] DECODE_TABLE = {
167 // 0 1 2 3 4 5 6 7 8 9 A B C D E F
168 -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, // 00-0f
169 -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, // 10-1f
170 -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, // 20-2f
171 -1, -1, 26, 27, 28, 29, 30, 31, -1, -1, -1, -1, -1, -1, -1, -1, // 30-3f 2-7
172 -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, // 40-4f A-O
173 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, // 50-5a P-Z
174 -1, -1, -1, -1, -1, // 5b-5f
175 -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, // 60-6f a-o
176 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, // 70-7a p-z
177 };
178 // @formatter:on
179
180 /**
181 * This array is a lookup table that translates 5-bit positive integer index values into their "Base32 Alphabet" equivalents as specified in
182 * <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">RFC 4648 Section 6, Table 3: The Base 32 Alphabet</a>.
183 *
184 * @see <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">RFC 4648 Section 6, Table 3: The Base 32 Alphabet</a>
185 */
186 // @formatter:off
187 private static final byte[] ENCODE_TABLE = {
188 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M',
189 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z',
190 '2', '3', '4', '5', '6', '7',
191 };
192 // @formatter:on
193
194 /**
195 * This array is a lookup table that translates Unicode characters drawn from the "Base32 Hex Alphabet" (as specified in Table 4 of RFC 4648) into their
196 * 5-bit positive integer equivalents. Characters that are not in the Base32 Hex alphabet but fall within the bounds of the array are translated to -1.
197 */
198 // @formatter:off
199 private static final byte[] HEX_DECODE_TABLE = {
200 // 0 1 2 3 4 5 6 7 8 9 A B C D E F
201 -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, // 00-0f
202 -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, // 10-1f
203 -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, // 20-2f
204 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, -1, -1, -1, -1, -1, -1, // 30-3f 0-9
205 -1, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, // 40-4f A-O
206 25, 26, 27, 28, 29, 30, 31, // 50-56 P-V
207 -1, -1, -1, -1, -1, -1, -1, -1, -1, // 57-5f
208 -1, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, // 60-6f a-o
209 25, 26, 27, 28, 29, 30, 31 // 70-76 p-v
210 };
211 // @formatter:on
212
213 /**
214 * This array is a lookup table that translates 5-bit positive integer index values into their "Base 32 Encoding with Extended Hex Alphabet" equivalents as
215 * specified in <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-7">RFC 4648 Section 7, Table 4: Base 32 Encoding with Extended Hex
216 * Alphabet</a>.
217 *
218 * @see <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-7">RFC 4648 Section 7, Table 4: Base 32 Encoding with Extended Hex Alphabet</a>
219 */
220 // @formatter:off
221 private static final byte[] HEX_ENCODE_TABLE = {
222 '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
223 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M',
224 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V',
225 };
226 // @formatter:on
227
228 /** Mask used to extract 5 bits, used when encoding Base32 bytes */
229 private static final int MASK_5_BITS = 0x1f;
230
231 /** Mask used to extract 4 bits, used when decoding final trailing character. */
232 private static final long MASK_4_BITS = 0x0fL;
233
234 /** Mask used to extract 3 bits, used when decoding final trailing character. */
235 private static final long MASK_3_BITS = 0x07L;
236
237 /** Mask used to extract 2 bits, used when decoding final trailing character. */
238 private static final long MASK_2_BITS = 0x03L;
239
240 /** Mask used to extract 1 bits, used when decoding final trailing character. */
241 private static final long MASK_1_BITS = 0x01L;
242
243 // The static final fields above are used for the original static byte[] methods on Base32.
244 // The private member fields below are used with the new streaming approach, which requires
245 // some state be preserved between calls of encode() and decode().
246
247 /**
248 * Creates a new Builder.
249 *
250 * <p>
251 * To configure a new instance, use a {@link Builder}. For example:
252 * </p>
253 *
254 * <pre>
255 * Base32 base32 = Base32.builder()
256 * .setDecodingPolicy(DecodingPolicy.LENIENT) // default is lenient
257 * .setLineLength(0) // default is none
258 * .setLineSeparator('\r', '\n') // default is CR LF
259 * .setPadding('=') // default is '='
260 * .setEncodeTable(customEncodeTable) // default is RFC 4648 Section 6, Table 3: The Base 32 Alphabet
261 * .get()
262 * </pre>
263 *
264 * @return A new Builder.
265 * @since 1.17.0
266 */
267 public static Builder builder() {
268 return new Builder();
269 }
270
271 /**
272 * Calculates a decode table for a given encode table.
273 *
274 * @param encodeTable that is used to determine decode lookup table.
275 * @return A new decode table.
276 * @throws IllegalArgumentException if the encode table does not contain exactly 32 unique entries.
277 */
278 private static byte[] calculateDecodeTable(final byte[] encodeTable) {
279 if (encodeTable.length != ENCODING_TABLE_LENGTH) {
280 throw new IllegalArgumentException("encodeTable must have exactly 32 entries.");
281 }
282 final byte[] decodeTable = new byte[DECODING_TABLE_LENGTH];
283 Arrays.fill(decodeTable, (byte) -1);
284 for (int i = 0; i < encodeTable.length; i++) {
285 final int encodedByte = encodeTable[i] & 0xff;
286 if (decodeTable[encodedByte] != -1) {
287 throw new IllegalArgumentException("encodeTable must not contain duplicate entries.");
288 }
289 decodeTable[encodedByte] = (byte) i;
290 }
291 return decodeTable;
292 }
293
294 private static byte[] decodeTable(final boolean useHex) {
295 return useHex ? HEX_DECODE_TABLE : DECODE_TABLE;
296 }
297
298 /**
299 * Gets the encoding table that matches {@code useHex}.
300 *
301 * @param useHex
302 * <ul>
303 * <li>If true, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-7">RFC 4648 Section 7, Table 4: Base 32 Encoding with
304 * Extended Hex Alphabet</a></li>
305 * <li>If false, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">RFC 4648 Section 6, Table 3: The Base 32
306 * Alphabet</a></li>
307 * </ul>
308 * @return The encoding table that matches {@code useHex}.
309 */
310 private static byte[] encodeTable(final boolean useHex) {
311 return useHex ? HEX_ENCODE_TABLE : ENCODE_TABLE;
312 }
313
314 /**
315 * Gets the decode table that matches the given encode table.
316 *
317 * @param encodeTable that is used to determine decode lookup table.
318 * @return The matching decode table.
319 */
320 private static byte[] toDecodeTable(final byte[] encodeTable) {
321 final byte[] table = encodeTable != null ? encodeTable : ENCODE_TABLE;
322 if (Arrays.equals(table, ENCODE_TABLE)) {
323 return DECODE_TABLE;
324 }
325 if (Arrays.equals(table, HEX_ENCODE_TABLE)) {
326 return HEX_DECODE_TABLE;
327 }
328 return calculateDecodeTable(table);
329 }
330
331 /**
332 * Convenience variable to help us determine when our buffer is going to run out of room and needs resizing. {@code encodeSize = {@link
333 * #BYTES_PER_ENCODED_BLOCK} + lineSeparator.length;}
334 */
335 private final int encodeSize;
336
337 /**
338 * Line separator for encoding. Not used when decoding. Only used if lineLength > 0.
339 */
340 private final byte[] lineSeparator;
341
342 /**
343 * Constructs a Base32 codec used for decoding and encoding.
344 * <p>
345 * When encoding the line length is 0 (no chunking).
346 * </p>
347 */
348 public Base32() {
349 this(false);
350 }
351
352 /**
353 * Constructs a Base32 codec used for decoding and encoding.
354 * <p>
355 * When encoding the line length is 0 (no chunking).
356 * </p>
357 *
358 * @param useHex
359 * <ul>
360 * <li>If true, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-7">RFC 4648 Section 7, Table 4: Base 32 Encoding with
361 * Extended Hex Alphabet</a></li>
362 * <li>If false, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">RFC 4648 Section 6, Table 3: The Base 32
363 * Alphabet</a></li>
364 * </ul>
365 * @deprecated Use {@link #builder()} and {@link Builder}.
366 */
367 @Deprecated
368 public Base32(final boolean useHex) {
369 this(0, null, useHex, PAD_DEFAULT);
370 }
371
372 /**
373 * Constructs a Base32 codec used for decoding and encoding.
374 * <p>
375 * When encoding the line length is 0 (no chunking).
376 * </p>
377 *
378 * @param useHex
379 * <ul>
380 * <li>If true, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-7">RFC 4648 Section 7, Table 4: Base 32 Encoding with
381 * Extended Hex Alphabet</a></li>
382 * <li>If false, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">RFC 4648 Section 6, Table 3: The Base 32
383 * Alphabet</a></li>
384 * </ul>
385 * @param padding byte used as padding byte.
386 * @deprecated Use {@link #builder()} and {@link Builder}.
387 */
388 @Deprecated
389 public Base32(final boolean useHex, final byte padding) {
390 this(0, null, useHex, padding);
391 }
392
393 private Base32(final Builder builder) {
394 super(builder);
395 if (builder.getLineLength() > 0) {
396 final byte[] lineSeparator = builder.getLineSeparator();
397 // Must be done after initializing the tables
398 if (containsAlphabetOrPad(lineSeparator)) {
399 final String sep = StringUtils.newStringUtf8(lineSeparator);
400 throw new IllegalArgumentException("lineSeparator must not contain Base32 characters: [" + sep + "]");
401 }
402 this.encodeSize = BYTES_PER_ENCODED_BLOCK + lineSeparator.length;
403 this.lineSeparator = lineSeparator;
404 } else {
405 this.encodeSize = BYTES_PER_ENCODED_BLOCK;
406 this.lineSeparator = null;
407 }
408 if (isInAlphabet(builder.getPadding()) || Character.isWhitespace(builder.getPadding())) {
409 throw new IllegalArgumentException("pad must not be in alphabet or whitespace");
410 }
411 }
412
413 /**
414 * Constructs a Base32 codec used for decoding and encoding.
415 * <p>
416 * When encoding the line length is 0 (no chunking).
417 * </p>
418 *
419 * @param pad byte used as padding byte.
420 * @deprecated Use {@link #builder()} and {@link Builder}.
421 */
422 @Deprecated
423 public Base32(final byte pad) {
424 this(false, pad);
425 }
426
427 /**
428 * Constructs a Base32 codec used for decoding and encoding.
429 * <p>
430 * When encoding the line length is given in the constructor, the line separator is CRLF.
431 * </p>
432 *
433 * @param lineLength Each line of encoded data will be at most of the given length (rounded down to the nearest multiple of 8). If lineLength <= 0, then
434 * the output will not be divided into lines (chunks). Ignored when decoding.
435 * @deprecated Use {@link #builder()} and {@link Builder}.
436 */
437 @Deprecated
438 public Base32(final int lineLength) {
439 this(lineLength, CHUNK_SEPARATOR);
440 }
441
442 /**
443 * Constructs a Base32 codec used for decoding and encoding.
444 * <p>
445 * When encoding the line length and line separator are given in the constructor.
446 * </p>
447 * <p>
448 * Line lengths that aren't multiples of 8 will still essentially end up being multiples of 8 in the encoded data.
449 * </p>
450 *
451 * @param lineLength Each line of encoded data will be at most of the given length (rounded down to the nearest multiple of 8). If lineLength <= 0,
452 * then the output will not be divided into lines (chunks). Ignored when decoding.
453 * @param lineSeparator Each line of encoded data will end with this sequence of bytes.
454 * @throws IllegalArgumentException Thrown when the {@code lineSeparator} contains Base32 characters.
455 * @deprecated Use {@link #builder()} and {@link Builder}.
456 */
457 @Deprecated
458 public Base32(final int lineLength, final byte[] lineSeparator) {
459 this(lineLength, lineSeparator, false, PAD_DEFAULT);
460 }
461
462 /**
463 * Constructs a Base32 / Base32 Hex codec used for decoding and encoding.
464 * <p>
465 * When encoding the line length and line separator are given in the constructor.
466 * </p>
467 * <p>
468 * Line lengths that aren't multiples of 8 will still essentially end up being multiples of 8 in the encoded data.
469 * </p>
470 *
471 * @param lineLength Each line of encoded data will be at most of the given length (rounded down to the nearest multiple of 8). If lineLength <= 0,
472 * then the output will not be divided into lines (chunks). Ignored when decoding.
473 * @param lineSeparator Each line of encoded data will end with this sequence of bytes.
474 * @param useHex
475 * <ul>
476 * <li>If true, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-7">RFC 4648 Section 7, Table 4: Base 32 Encoding with
477 * Extended Hex Alphabet</a></li>
478 * <li>If false, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">RFC 4648 Section 6, Table 3: The Base 32
479 * Alphabet</a></li>
480 * </ul>
481 * @throws IllegalArgumentException Thrown when the {@code lineSeparator} contains Base32 characters. Or the lineLength > 0 and lineSeparator is null.
482 * @deprecated Use {@link #builder()} and {@link Builder}.
483 */
484 @Deprecated
485 public Base32(final int lineLength, final byte[] lineSeparator, final boolean useHex) {
486 this(lineLength, lineSeparator, useHex, PAD_DEFAULT);
487 }
488
489 /**
490 * Constructs a Base32 / Base32 Hex codec used for decoding and encoding.
491 * <p>
492 * When encoding the line length and line separator are given in the constructor.
493 * </p>
494 * <p>
495 * Line lengths that aren't multiples of 8 will still essentially end up being multiples of 8 in the encoded data.
496 * </p>
497 *
498 * @param lineLength Each line of encoded data will be at most of the given length (rounded down to the nearest multiple of 8). If lineLength <= 0,
499 * then the output will not be divided into lines (chunks). Ignored when decoding.
500 * @param lineSeparator Each line of encoded data will end with this sequence of bytes.
501 * @param useHex
502 * <ul>
503 * <li>If true, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-7">RFC 4648 Section 7, Table 4: Base 32 Encoding with
504 * Extended Hex Alphabet</a></li>
505 * <li>If false, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">RFC 4648 Section 6, Table 3: The Base 32
506 * Alphabet</a></li>
507 * </ul>
508 * @param padding padding byte.
509 * @throws IllegalArgumentException Thrown when the {@code lineSeparator} contains Base32 characters. Or the lineLength > 0 and lineSeparator is null.
510 * @deprecated Use {@link #builder()} and {@link Builder}.
511 */
512 @Deprecated
513 public Base32(final int lineLength, final byte[] lineSeparator, final boolean useHex, final byte padding) {
514 this(lineLength, lineSeparator, useHex, padding, DECODING_POLICY_DEFAULT);
515 }
516
517 /**
518 * Constructs a Base32 / Base32 Hex codec used for decoding and encoding.
519 * <p>
520 * When encoding the line length and line separator are given in the constructor.
521 * </p>
522 * <p>
523 * Line lengths that aren't multiples of 8 will still essentially end up being multiples of 8 in the encoded data.
524 * </p>
525 *
526 * @param lineLength Each line of encoded data will be at most of the given length (rounded down to the nearest multiple of 8). If lineLength <= 0,
527 * then the output will not be divided into lines (chunks). Ignored when decoding.
528 * @param lineSeparator Each line of encoded data will end with this sequence of bytes.
529 * @param useHex
530 * <ul>
531 * <li>If true, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-7">RFC 4648 Section 7, Table 4: Base 32 Encoding with
532 * Extended Hex Alphabet</a></li>
533 * <li>If false, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">RFC 4648 Section 6, Table 3: The Base 32
534 * Alphabet</a></li>
535 * </ul>
536 * @param padding padding byte.
537 * @param decodingPolicy The decoding policy.
538 * @throws IllegalArgumentException Thrown when the {@code lineSeparator} contains Base32 characters. Or the lineLength > 0 and lineSeparator is null.
539 * @since 1.15
540 * @deprecated Use {@link #builder()} and {@link Builder}.
541 */
542 @Deprecated
543 public Base32(final int lineLength, final byte[] lineSeparator, final boolean useHex, final byte padding, final CodecPolicy decodingPolicy) {
544 // @formatter:off
545 this(builder()
546 .setLineLength(lineLength)
547 .setLineSeparator(lineSeparator != null ? lineSeparator : EMPTY_BYTE_ARRAY)
548 .setDecodeTable(decodeTable(useHex))
549 .setEncodeTableRaw(encodeTable(useHex))
550 .setPadding(padding)
551 .setDecodingPolicy(decodingPolicy));
552 // @formatter:on
553 }
554
555 /**
556 * <p>
557 * Decodes all of the provided data, starting at inPos, for inAvail bytes. Should be called at least twice: once with the data to decode, and once with
558 * inAvail set to "-1" to alert decoder that EOF has been reached. The "-1" call is not necessary when decoding, but it doesn't hurt, either.
559 * </p>
560 * <p>
561 * Ignores all non-Base32 characters. This is how chunked (for example 76 character) data is handled, since CR and LF are silently ignored, but has implications
562 * for other bytes, too. This method subscribes to the garbage-in, garbage-out philosophy: it will not check the provided data for validity.
563 * </p>
564 * <p>
565 * Output is written to {@link org.apache.commons.codec.binary.BaseNCodec.Context#buffer Context#buffer} as 8-bit octets, using
566 * {@link org.apache.commons.codec.binary.BaseNCodec.Context#pos Context#pos} as the buffer position
567 * </p>
568 *
569 * @param input byte[] array of ASCII data to Base32 decode.
570 * @param inPos Position to start reading data from.
571 * @param inAvail Amount of bytes available from input for decoding.
572 * @param context The context to be used.
573 */
574 @Override
575 void decode(final byte[] input, int inPos, final int inAvail, final Context context) {
576 // package protected for access from I/O streams
577 if (context.eof) {
578 return;
579 }
580 if (inAvail < 0) {
581 context.eof = true;
582 }
583 final int decodeSize = this.encodeSize - 1;
584 for (int i = 0; i < inAvail; i++) {
585 final int b = input[inPos++] & 0xff;
586 if (b == (pad & 0xff)) {
587 // We're done.
588 context.eof = true;
589 break;
590 }
591 final byte[] buffer = ensureBufferSize(decodeSize, context);
592 if (b < this.decodeTable.length) {
593 final int result = this.decodeTable[b];
594 if (result >= 0) {
595 context.modulus = (context.modulus + 1) % BYTES_PER_ENCODED_BLOCK;
596 // collect decoded bytes
597 context.lbitWorkArea = (context.lbitWorkArea << BITS_PER_ENCODED_BYTE) + result;
598 if (context.modulus == 0) { // we can output the 5 bytes
599 buffer[context.pos++] = (byte) (context.lbitWorkArea >> 32 & MASK_8BITS);
600 buffer[context.pos++] = (byte) (context.lbitWorkArea >> 24 & MASK_8BITS);
601 buffer[context.pos++] = (byte) (context.lbitWorkArea >> 16 & MASK_8BITS);
602 buffer[context.pos++] = (byte) (context.lbitWorkArea >> 8 & MASK_8BITS);
603 buffer[context.pos++] = (byte) (context.lbitWorkArea & MASK_8BITS);
604 }
605 }
606 }
607 }
608 // Two forms of EOF as far as Base32 decoder is concerned: actual
609 // EOF (-1) and first time '=' character is encountered in stream.
610 // This approach makes the '=' padding characters completely optional.
611 if (context.eof && context.modulus > 0) { // if modulus == 0, nothing to do
612 final byte[] buffer = ensureBufferSize(decodeSize, context);
613 // We ignore partial bytes, i.e. only multiples of 8 count.
614 // Any combination not part of a valid encoding is either partially decoded
615 // or will raise an exception. Possible trailing characters are 2, 4, 5, 7.
616 // It is not possible to encode with 1, 3, 6 trailing characters.
617 // For backwards compatibility 3 & 6 chars are decoded anyway rather than discarded.
618 // See the encode(byte[]) method EOF section.
619 switch (context.modulus) {
620 // case 0 : // impossible, as excluded above
621 case 1: // 5 bits - either ignore entirely, or raise an exception
622 validateTrailingCharacters();
623 // falls-through
624 case 2: // 10 bits, drop 2 and output one byte
625 validateCharacter(MASK_2_BITS, context);
626 buffer[context.pos++] = (byte) (context.lbitWorkArea >> 2 & MASK_8BITS);
627 break;
628 case 3: // 15 bits, drop 7 and output 1 byte, or raise an exception
629 validateTrailingCharacters();
630 // Not possible from a valid encoding but decode anyway
631 buffer[context.pos++] = (byte) (context.lbitWorkArea >> 7 & MASK_8BITS);
632 break;
633 case 4: // 20 bits = 2*8 + 4
634 validateCharacter(MASK_4_BITS, context);
635 context.lbitWorkArea = context.lbitWorkArea >> 4; // drop 4 bits
636 buffer[context.pos++] = (byte) (context.lbitWorkArea >> 8 & MASK_8BITS);
637 buffer[context.pos++] = (byte) (context.lbitWorkArea & MASK_8BITS);
638 break;
639 case 5: // 25 bits = 3*8 + 1
640 validateCharacter(MASK_1_BITS, context);
641 context.lbitWorkArea = context.lbitWorkArea >> 1;
642 buffer[context.pos++] = (byte) (context.lbitWorkArea >> 16 & MASK_8BITS);
643 buffer[context.pos++] = (byte) (context.lbitWorkArea >> 8 & MASK_8BITS);
644 buffer[context.pos++] = (byte) (context.lbitWorkArea & MASK_8BITS);
645 break;
646 case 6: // 30 bits = 3*8 + 6, or raise an exception
647 validateTrailingCharacters();
648 // Not possible from a valid encoding but decode anyway
649 context.lbitWorkArea = context.lbitWorkArea >> 6;
650 buffer[context.pos++] = (byte) (context.lbitWorkArea >> 16 & MASK_8BITS);
651 buffer[context.pos++] = (byte) (context.lbitWorkArea >> 8 & MASK_8BITS);
652 buffer[context.pos++] = (byte) (context.lbitWorkArea & MASK_8BITS);
653 break;
654 case 7: // 35 bits = 4*8 +3
655 validateCharacter(MASK_3_BITS, context);
656 context.lbitWorkArea = context.lbitWorkArea >> 3;
657 buffer[context.pos++] = (byte) (context.lbitWorkArea >> 24 & MASK_8BITS);
658 buffer[context.pos++] = (byte) (context.lbitWorkArea >> 16 & MASK_8BITS);
659 buffer[context.pos++] = (byte) (context.lbitWorkArea >> 8 & MASK_8BITS);
660 buffer[context.pos++] = (byte) (context.lbitWorkArea & MASK_8BITS);
661 break;
662 default:
663 // modulus can be 0-7, and we excluded 0,1 already
664 throw new IllegalStateException("Impossible modulus " + context.modulus);
665 }
666 }
667 }
668
669 /**
670 * <p>
671 * Encodes all of the provided data, starting at inPos, for inAvail bytes. Must be called at least twice: once with the data to encode, and once with
672 * inAvail set to "-1" to alert encoder that EOF has been reached, so flush last remaining bytes (if not multiple of 5).
673 * </p>
674 *
675 * @param input byte[] array of binary data to Base32 encode.
676 * @param inPos Position to start reading data from.
677 * @param inAvail Amount of bytes available from input for encoding.
678 * @param context The context to be used.
679 */
680 @Override
681 void encode(final byte[] input, int inPos, final int inAvail, final Context context) {
682 // package protected for access from I/O streams
683 if (context.eof) {
684 return;
685 }
686 // inAvail < 0 is how we're informed of EOF in the underlying data we're
687 // encoding.
688 if (inAvail < 0) {
689 context.eof = true;
690 if (0 == context.modulus && lineLength == 0) {
691 return; // no leftovers to process and not using chunking
692 }
693 final byte[] buffer = ensureBufferSize(encodeSize, context);
694 final int savedPos = context.pos;
695 switch (context.modulus) { // % 5
696 case 0:
697 break;
698 case 1: // Only 1 octet; take top 5 bits then remainder
699 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 3) & MASK_5_BITS]; // 8-1*5 = 3
700 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea << 2) & MASK_5_BITS]; // 5-3=2
701 buffer[context.pos++] = pad;
702 buffer[context.pos++] = pad;
703 buffer[context.pos++] = pad;
704 buffer[context.pos++] = pad;
705 buffer[context.pos++] = pad;
706 buffer[context.pos++] = pad;
707 break;
708 case 2: // 2 octets = 16 bits to use
709 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 11) & MASK_5_BITS]; // 16-1*5 = 11
710 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 6) & MASK_5_BITS]; // 16-2*5 = 6
711 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 1) & MASK_5_BITS]; // 16-3*5 = 1
712 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea << 4) & MASK_5_BITS]; // 5-1 = 4
713 buffer[context.pos++] = pad;
714 buffer[context.pos++] = pad;
715 buffer[context.pos++] = pad;
716 buffer[context.pos++] = pad;
717 break;
718 case 3: // 3 octets = 24 bits to use
719 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 19) & MASK_5_BITS]; // 24-1*5 = 19
720 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 14) & MASK_5_BITS]; // 24-2*5 = 14
721 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 9) & MASK_5_BITS]; // 24-3*5 = 9
722 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 4) & MASK_5_BITS]; // 24-4*5 = 4
723 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea << 1) & MASK_5_BITS]; // 5-4 = 1
724 buffer[context.pos++] = pad;
725 buffer[context.pos++] = pad;
726 buffer[context.pos++] = pad;
727 break;
728 case 4: // 4 octets = 32 bits to use
729 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 27) & MASK_5_BITS]; // 32-1*5 = 27
730 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 22) & MASK_5_BITS]; // 32-2*5 = 22
731 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 17) & MASK_5_BITS]; // 32-3*5 = 17
732 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 12) & MASK_5_BITS]; // 32-4*5 = 12
733 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 7) & MASK_5_BITS]; // 32-5*5 = 7
734 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 2) & MASK_5_BITS]; // 32-6*5 = 2
735 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea << 3) & MASK_5_BITS]; // 5-2 = 3
736 buffer[context.pos++] = pad;
737 break;
738 default:
739 throw new IllegalStateException("Impossible modulus " + context.modulus);
740 }
741 context.currentLinePos += context.pos - savedPos; // keep track of current line position
742 // if currentPos == 0 we are at the start of a line, so don't add CRLF
743 if (lineLength > 0 && context.currentLinePos > 0) { // add chunk separator if required
744 System.arraycopy(lineSeparator, 0, buffer, context.pos, lineSeparator.length);
745 context.pos += lineSeparator.length;
746 }
747 } else {
748 for (int i = 0; i < inAvail; i++) {
749 final byte[] buffer = ensureBufferSize(encodeSize, context);
750 context.modulus = (context.modulus + 1) % BYTES_PER_UNENCODED_BLOCK;
751 int b = input[inPos++];
752 if (b < 0) {
753 b += 256;
754 }
755 context.lbitWorkArea = (context.lbitWorkArea << 8) + b; // BITS_PER_BYTE
756 if (0 == context.modulus) { // we have enough bytes to create our output
757 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 35) & MASK_5_BITS];
758 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 30) & MASK_5_BITS];
759 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 25) & MASK_5_BITS];
760 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 20) & MASK_5_BITS];
761 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 15) & MASK_5_BITS];
762 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 10) & MASK_5_BITS];
763 buffer[context.pos++] = encodeTable[(int) (context.lbitWorkArea >> 5) & MASK_5_BITS];
764 buffer[context.pos++] = encodeTable[(int) context.lbitWorkArea & MASK_5_BITS];
765 context.currentLinePos += BYTES_PER_ENCODED_BLOCK;
766 if (lineLength > 0 && lineLength <= context.currentLinePos) {
767 System.arraycopy(lineSeparator, 0, buffer, context.pos, lineSeparator.length);
768 context.pos += lineSeparator.length;
769 context.currentLinePos = 0;
770 }
771 }
772 }
773 }
774 }
775
776 /**
777 * Gets the line separator (for testing only).
778 *
779 * @return The line separator.
780 */
781 byte[] getLineSeparator() {
782 return lineSeparator;
783 }
784
785 /**
786 * Returns whether or not the {@code octet} is in the Base32 alphabet.
787 *
788 * @param octet The value to test.
789 * @return {@code true} if the value is defined in the Base32 alphabet {@code false} otherwise.
790 */
791 @Override
792 public boolean isInAlphabet(final byte octet) {
793 final int value = octet & 0xff;
794 return value < decodeTable.length && decodeTable[value] != -1;
795 }
796
797 /**
798 * Validates whether decoding the final trailing character is possible in the context of the set of possible Base32 values.
799 * <p>
800 * The character is valid if the lower bits within the provided mask are zero. This is used to test the final trailing base-32 digit is zero in the bits
801 * that will be discarded.
802 * </p>
803 *
804 * @param emptyBitsMask The mask of the lower bits that should be empty.
805 * @param context The context to be used.
806 * @throws IllegalArgumentException if the bits being checked contain any non-zero value.
807 */
808 private void validateCharacter(final long emptyBitsMask, final Context context) {
809 // Use the long bit work area
810 if (isStrictDecoding() && (context.lbitWorkArea & emptyBitsMask) != 0) {
811 throw new IllegalArgumentException("Strict decoding: Last encoded character (before the paddings if any) is a valid " +
812 "Base32 alphabet but not a possible encoding. Expected the discarded bits from the character to be zero.");
813 }
814 }
815
816 /**
817 * Validates whether decoding allows final trailing characters that cannot be created during encoding.
818 *
819 * @throws IllegalArgumentException if strict decoding is enabled.
820 */
821 private void validateTrailingCharacters() {
822 if (isStrictDecoding()) {
823 throw new IllegalArgumentException("Strict decoding: Last encoded character(s) (before the paddings if any) are valid " +
824 "Base32 alphabet but not a possible encoding. Decoding requires either 2, 4, 5, or 7 trailing 5-bit characters to create bytes.");
825 }
826 }
827 }