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