    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      https://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017
    018package org.apache.commons.codec.binary;
    019
    020import java.math.BigInteger;
    021import java.util.Arrays;
    022import java.util.Objects;
    023
    024import org.apache.commons.codec.CodecPolicy;
    025
    026/**
    027 * Provides Base64 encoding and decoding as defined by <a href="https://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>.
    028 *
    029 * <p>
    030 * This class implements section <cite>6.8. Base64 Content-Transfer-Encoding</cite> from RFC 2045 <cite>Multipurpose
    031 * Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies</cite> by Freed and Borenstein.
    032 * </p>
    033 * <p>
    034 * The class can be parameterized in the following manner with various constructors:
    035 * </p>
    036 * <ul>
    037 * <li>URL-safe mode: Default off.</li>
    038 * <li>Line length: Default 76. Line length that aren't multiples of 4 will still essentially end up being multiples of
    039 * 4 in the encoded data.
    040 * <li>Line separator: Default is CRLF ("\r\n")</li>
    041 * </ul>
    042 * <p>
    043 * The URL-safe parameter is only applied to encode operations. Decoding seamlessly handles both modes.
    044 * </p>
    045 * <p>
    046 * Since this class operates directly on byte streams, and not character streams, it is hard-coded to only
    047 * encode/decode character encodings which are compatible with the lower 127 ASCII chart (ISO-8859-1, Windows-1252,
    048 * UTF-8, etc).
    049 * </p>
    050 * <p>
    051 * This class is thread-safe.
    052 * </p>
    053 * <p>
    054 * To configure a new instance, use a {@link Builder}. For example:
    055 * </p>
    056 * <pre>
    057 * Base64 base64 = Base64.builder()
    058 *   .setDecodingPolicy(DecodingPolicy.LENIENT) // default is lenient, null resets to default
    059 *   .setEncodeTable(customEncodeTable)         // default is built in, null resets to default
    060 *   .setLineLength(0)                          // default is none
    061 *   .setLineSeparator('\r', '\n')              // default is CR LF, null resets to default
    062 *   .setPadding('=')                           // default is '='
    063 *   .setUrlSafe(false)                         // default is false
    064 *   .get()
    065 * </pre>
    066 *
    067 * @see Base64InputStream
    068 * @see Base64OutputStream
    069 * @see <a href="https://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>
    070 * @since 1.0
    071 */
    072public class Base64 extends BaseNCodec {
    073
    074    /**
    075     * Builds {@link Base64} instances.
    076     *
    077     * <p>
    078     * To configure a new instance, use a {@link Builder}. For example:
    079     * </p>
    080     *
    081     * <pre>
    082     * Base64 base64 = Base64.builder()
    083     *   .setDecodingPolicy(DecodingPolicy.LENIENT) // default is lenient, null resets to default
    084     *   .setEncodeTable(customEncodeTable)         // default is built in, null resets to default
    085     *   .setLineLength(0)                          // default is none
    086     *   .setLineSeparator('\r', '\n')              // default is CR LF, null resets to default
    087     *   .setPadding('=')                           // default is '='
    088     *   .setUrlSafe(false)                         // default is false
    089     *   .get()
    090     * </pre>
    091     *
    092     * @since 1.17.0
    093     */
    094    public static class Builder extends AbstractBuilder<Base64, Builder> {
    095
    096        /**
    097         * Constructs a new instance.
    098         */
    099        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 &gt; 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 &lt;= 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 &lt;= 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 &lt;= 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 &lt;= 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}