    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;
    021
    022/**
    023 * Provides Base64 encoding and decoding as defined by <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>.
    024 *
    025 * <p>
    026 * This class implements section <cite>6.8. Base64 Content-Transfer-Encoding</cite> from RFC 2045 <cite>Multipurpose
    027 * Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies</cite> by Freed and Borenstein.
    028 * </p>
    029 * <p>
    030 * The class can be parameterized in the following manner with various constructors:
    031 * </p>
    032 * <ul>
    033 * <li>URL-safe mode: Default off.</li>
    034 * <li>Line length: Default 76. Line length that aren't multiples of 4 will still essentially end up being multiples of
    035 * 4 in the encoded data.
    036 * <li>Line separator: Default is CRLF ("\r\n")</li>
    037 * </ul>
    038 * <p>
    039 * The URL-safe parameter is only applied to encode operations. Decoding seamlessly handles both modes.
    040 * </p>
    041 * <p>
    042 * Since this class operates directly on byte streams, and not character streams, it is hard-coded to only
    043 * encode/decode character encodings which are compatible with the lower 127 ASCII chart (ISO-8859-1, Windows-1252,
    044 * UTF-8, etc).
    045 * </p>
    046 * <p>
    047 * This class is thread-safe.
    048 * </p>
    049 *
    050 * @see <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>
    051 * @since 1.0
    052 * @version $Id: Base64.java 1635986 2014-11-01 16:27:52Z tn $
    053 */
    054public class Base64 extends BaseNCodec {
    055
    056    /**
    057     * BASE32 characters are 6 bits in length.
    058     * They are formed by taking a block of 3 octets to form a 24-bit string,
    059     * which is converted into 4 BASE64 characters.
    060     */
    061    private static final int BITS_PER_ENCODED_BYTE = 6;
    062    private static final int BYTES_PER_UNENCODED_BLOCK = 3;
    063    private static final int BYTES_PER_ENCODED_BLOCK = 4;
    064
    065    /**
    066     * Chunk separator per RFC 2045 section 2.1.
    067     *
    068     * <p>
    069     * N.B. The next major release may break compatibility and make this field private.
    070     * </p>
    071     *
    072     * @see <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045 section 2.1</a>
    073     */
    074    static final byte[] CHUNK_SEPARATOR = {'\r', '\n'};
    075
    076    /**
    077     * This array is a lookup table that translates 6-bit positive integer index values into their "Base64 Alphabet"
    078     * equivalents as specified in Table 1 of RFC 2045.
    079     *
    080     * Thanks to "commons" project in ws.apache.org for this code.
    081     * http://svn.apache.org/repos/asf/webservices/commons/trunk/modules/util/
    082     */
    083    private static final byte[] STANDARD_ENCODE_TABLE = {
    084            'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M',
    085            'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z',
    086            'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm',
    087            'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z',
    088            '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '+', '/'
    089    };
    090
    091    /**
    092     * This is a copy of the STANDARD_ENCODE_TABLE above, but with + and /
    093     * changed to - and _ to make the encoded Base64 results more URL-SAFE.
    094     * This table is only used when the Base64's mode is set to URL-SAFE.
    095     */
    096    private static final byte[] URL_SAFE_ENCODE_TABLE = {
    097            'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M',
    098            'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z',
    099            'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm',
    100            'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z',
    101            '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '-', '_'
    102    };
    103
    104    /**
    105     * This array is a lookup table that translates Unicode characters drawn from the "Base64 Alphabet" (as specified
    106     * in Table 1 of RFC 2045) into their 6-bit positive integer equivalents. Characters that are not in the Base64
    107     * alphabet but fall within the bounds of the array are translated to -1.
    108     *
    109     * Note: '+' and '-' both decode to 62. '/' and '_' both decode to 63. This means decoder seamlessly handles both
    110     * URL_SAFE and STANDARD base64. (The encoder, on the other hand, needs to know ahead of time what to emit).
    111     *
    112     * Thanks to "commons" project in ws.apache.org for this code.
    113     * http://svn.apache.org/repos/asf/webservices/commons/trunk/modules/util/
    114     */
    115    private static final byte[] DECODE_TABLE = {
    116            -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
    117            -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
    118            -1, -1, -1, -1, -1, -1, -1, -1, -1, 62, -1, 62, -1, 63, 52, 53, 54,
    119            55, 56, 57, 58, 59, 60, 61, -1, -1, -1, -1, -1, -1, -1, 0, 1, 2, 3, 4,
    120            5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23,
    121            24, 25, -1, -1, -1, -1, 63, -1, 26, 27, 28, 29, 30, 31, 32, 33, 34,
    122            35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51
    123    };
    124
    125    /**
    126     * Base64 uses 6-bit fields.
    127     */
    128    /** Mask used to extract 6 bits, used when encoding */
    129    private static final int MASK_6BITS = 0x3f;
    130
    131    // The static final fields above are used for the original static byte[] methods on Base64.
    132    // The private member fields below are used with the new streaming approach, which requires
    133    // some state be preserved between calls of encode() and decode().
    134
    135    /**
    136     * Encode table to use: either STANDARD or URL_SAFE. Note: the DECODE_TABLE above remains static because it is able
    137     * to decode both STANDARD and URL_SAFE streams, but the encodeTable must be a member variable so we can switch
    138     * between the two modes.
    139     */
    140    private final byte[] encodeTable;
    141
    142    // Only one decode table currently; keep for consistency with Base32 code
    143    private final byte[] decodeTable = DECODE_TABLE;
    144
    145    /**
    146     * Line separator for encoding. Not used when decoding. Only used if lineLength &gt; 0.
    147     */
    148    private final byte[] lineSeparator;
    149
    150    /**
    151     * Convenience variable to help us determine when our buffer is going to run out of room and needs resizing.
    152     * <code>decodeSize = 3 + lineSeparator.length;</code>
    153     */
    154    private final int decodeSize;
    155
    156    /**
    157     * Convenience variable to help us determine when our buffer is going to run out of room and needs resizing.
    158     * <code>encodeSize = 4 + lineSeparator.length;</code>
    159     */
    160    private final int encodeSize;
    161
    162    /**
    163     * Creates a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode.
    164     * <p>
    165     * When encoding the line length is 0 (no chunking), and the encoding table is STANDARD_ENCODE_TABLE.
    166     * </p>
    167     *
    168     * <p>
    169     * When decoding all variants are supported.
    170     * </p>
    171     */
    172    public Base64() {
    173        this(0);
    174    }
    175
    176    /**
    177     * Creates a Base64 codec used for decoding (all modes) and encoding in the given URL-safe mode.
    178     * <p>
    179     * When encoding the line length is 76, the line separator is CRLF, and the encoding table is STANDARD_ENCODE_TABLE.
    180     * </p>
    181     *
    182     * <p>
    183     * When decoding all variants are supported.
    184     * </p>
    185     *
    186     * @param urlSafe
    187     *            if <code>true</code>, URL-safe encoding is used. In most cases this should be set to
    188     *            <code>false</code>.
    189     * @since 1.4
    190     */
    191    public Base64(final boolean urlSafe) {
    192        this(MIME_CHUNK_SIZE, CHUNK_SEPARATOR, urlSafe);
    193    }
    194
    195    /**
    196     * Creates a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode.
    197     * <p>
    198     * When encoding the line length is given in the constructor, the line separator is CRLF, and the encoding table is
    199     * STANDARD_ENCODE_TABLE.
    200     * </p>
    201     * <p>
    202     * Line lengths that aren't multiples of 4 will still essentially end up being multiples of 4 in the encoded data.
    203     * </p>
    204     * <p>
    205     * When decoding all variants are supported.
    206     * </p>
    207     *
    208     * @param lineLength
    209     *            Each line of encoded data will be at most of the given length (rounded down to nearest multiple of
    210     *            4). If lineLength &lt;= 0, then the output will not be divided into lines (chunks). Ignored when
    211     *            decoding.
    212     * @since 1.4
    213     */
    214    public Base64(final int lineLength) {
    215        this(lineLength, CHUNK_SEPARATOR);
    216    }
    217
    218    /**
    219     * Creates a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode.
    220     * <p>
    221     * When encoding the line length and line separator are given in the constructor, and the encoding table is
    222     * STANDARD_ENCODE_TABLE.
    223     * </p>
    224     * <p>
    225     * Line lengths that aren't multiples of 4 will still essentially end up being multiples of 4 in the encoded data.
    226     * </p>
    227     * <p>
    228     * When decoding all variants are supported.
    229     * </p>
    230     *
    231     * @param lineLength
    232     *            Each line of encoded data will be at most of the given length (rounded down to nearest multiple of
    233     *            4). If lineLength &lt;= 0, then the output will not be divided into lines (chunks). Ignored when
    234     *            decoding.
    235     * @param lineSeparator
    236     *            Each line of encoded data will end with this sequence of bytes.
    237     * @throws IllegalArgumentException
    238     *             Thrown when the provided lineSeparator included some base64 characters.
    239     * @since 1.4
    240     */
    241    public Base64(final int lineLength, final byte[] lineSeparator) {
    242        this(lineLength, lineSeparator, false);
    243    }
    244
    245    /**
    246     * Creates a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode.
    247     * <p>
    248     * When encoding the line length and line separator are given in the constructor, and the encoding table is
    249     * STANDARD_ENCODE_TABLE.
    250     * </p>
    251     * <p>
    252     * Line lengths that aren't multiples of 4 will still essentially end up being multiples of 4 in the encoded data.
    253     * </p>
    254     * <p>
    255     * When decoding all variants are supported.
    256     * </p>
    257     *
    258     * @param lineLength
    259     *            Each line of encoded data will be at most of the given length (rounded down to nearest multiple of
    260     *            4). If lineLength &lt;= 0, then the output will not be divided into lines (chunks). Ignored when
    261     *            decoding.
    262     * @param lineSeparator
    263     *            Each line of encoded data will end with this sequence of bytes.
    264     * @param urlSafe
    265     *            Instead of emitting '+' and '/' we emit '-' and '_' respectively. urlSafe is only applied to encode
    266     *            operations. Decoding seamlessly handles both modes.
    267     *            <b>Note: no padding is added when using the URL-safe alphabet.</b>
    268     * @throws IllegalArgumentException
    269     *             The provided lineSeparator included some base64 characters. That's not going to work!
    270     * @since 1.4
    271     */
    272    public Base64(final int lineLength, final byte[] lineSeparator, final boolean urlSafe) {
    273        super(BYTES_PER_UNENCODED_BLOCK, BYTES_PER_ENCODED_BLOCK,
    274                lineLength,
    275                lineSeparator == null ? 0 : lineSeparator.length);
    276        // TODO could be simplified if there is no requirement to reject invalid line sep when length <=0
    277        // @see test case Base64Test.testConstructors()
    278        if (lineSeparator != null) {
    279            if (containsAlphabetOrPad(lineSeparator)) {
    280                final String sep = StringUtils.newStringUtf8(lineSeparator);
    281                throw new IllegalArgumentException("lineSeparator must not contain base64 characters: [" + sep + "]");
    282            }
    283            if (lineLength > 0){ // null line-sep forces no chunking rather than throwing IAE
    284                this.encodeSize = BYTES_PER_ENCODED_BLOCK + lineSeparator.length;
    285                this.lineSeparator = new byte[lineSeparator.length];
    286                System.arraycopy(lineSeparator, 0, this.lineSeparator, 0, lineSeparator.length);
    287            } else {
    288                this.encodeSize = BYTES_PER_ENCODED_BLOCK;
    289                this.lineSeparator = null;
    290            }
    291        } else {
    292            this.encodeSize = BYTES_PER_ENCODED_BLOCK;
    293            this.lineSeparator = null;
    294        }
    295        this.decodeSize = this.encodeSize - 1;
    296        this.encodeTable = urlSafe ? URL_SAFE_ENCODE_TABLE : STANDARD_ENCODE_TABLE;
    297    }
    298
    299    /**
    300     * Returns our current encode mode. True if we're URL-SAFE, false otherwise.
    301     *
    302     * @return true if we're in URL-SAFE mode, false otherwise.
    303     * @since 1.4
    304     */
    305    public boolean isUrlSafe() {
    306        return this.encodeTable == URL_SAFE_ENCODE_TABLE;
    307    }
    308
    309    /**
    310     * <p>
    311     * Encodes all of the provided data, starting at inPos, for inAvail bytes. Must be called at least twice: once with
    312     * the data to encode, and once with inAvail set to "-1" to alert encoder that EOF has been reached, to flush last
    313     * remaining bytes (if not multiple of 3).
    314     * </p>
    315     * <p><b>Note: no padding is added when encoding using the URL-safe alphabet.</b></p>
    316     * <p>
    317     * Thanks to "commons" project in ws.apache.org for the bitwise operations, and general approach.
    318     * http://svn.apache.org/repos/asf/webservices/commons/trunk/modules/util/
    319     * </p>
    320     *
    321     * @param in
    322     *            byte[] array of binary data to base64 encode.
    323     * @param inPos
    324     *            Position to start reading data from.
    325     * @param inAvail
    326     *            Amount of bytes available from input for encoding.
    327     * @param context
    328     *            the context to be used
    329     */
    330    @Override
    331    void encode(final byte[] in, int inPos, final int inAvail, final Context context) {
    332        if (context.eof) {
    333            return;
    334        }
    335        // inAvail < 0 is how we're informed of EOF in the underlying data we're
    336        // encoding.
    337        if (inAvail < 0) {
    338            context.eof = true;
    339            if (0 == context.modulus && lineLength == 0) {
    340                return; // no leftovers to process and not using chunking
    341            }
    342            final byte[] buffer = ensureBufferSize(encodeSize, context);
    343            final int savedPos = context.pos;
    344            switch (context.modulus) { // 0-2
    345                case 0 : // nothing to do here
    346                    break;
    347                case 1 : // 8 bits = 6 + 2
    348                    // top 6 bits:
    349                    buffer[context.pos++] = encodeTable[(context.ibitWorkArea >> 2) & MASK_6BITS];
    350                    // remaining 2:
    351                    buffer[context.pos++] = encodeTable[(context.ibitWorkArea << 4) & MASK_6BITS];
    352                    // URL-SAFE skips the padding to further reduce size.
    353                    if (encodeTable == STANDARD_ENCODE_TABLE) {
    354                        buffer[context.pos++] = pad;
    355                        buffer[context.pos++] = pad;
    356                    }
    357                    break;
    358
    359                case 2 : // 16 bits = 6 + 6 + 4
    360                    buffer[context.pos++] = encodeTable[(context.ibitWorkArea >> 10) & MASK_6BITS];
    361                    buffer[context.pos++] = encodeTable[(context.ibitWorkArea >> 4) & MASK_6BITS];
    362                    buffer[context.pos++] = encodeTable[(context.ibitWorkArea << 2) & MASK_6BITS];
    363                    // URL-SAFE skips the padding to further reduce size.
    364                    if (encodeTable == STANDARD_ENCODE_TABLE) {
    365                        buffer[context.pos++] = pad;
    366                    }
    367                    break;
    368                default:
    369                    throw new IllegalStateException("Impossible modulus "+context.modulus);
    370            }
    371            context.currentLinePos += context.pos - savedPos; // keep track of current line position
    372            // if currentPos == 0 we are at the start of a line, so don't add CRLF
    373            if (lineLength > 0 && context.currentLinePos > 0) {
    374                System.arraycopy(lineSeparator, 0, buffer, context.pos, lineSeparator.length);
    375                context.pos += lineSeparator.length;
    376            }
    377        } else {
    378            for (int i = 0; i < inAvail; i++) {
    379                final byte[] buffer = ensureBufferSize(encodeSize, context);
    380                context.modulus = (context.modulus+1) % BYTES_PER_UNENCODED_BLOCK;
    381                int b = in[inPos++];
    382                if (b < 0) {
    383                    b += 256;
    384                }
    385                context.ibitWorkArea = (context.ibitWorkArea << 8) + b; //  BITS_PER_BYTE
    386                if (0 == context.modulus) { // 3 bytes = 24 bits = 4 * 6 bits to extract
    387                    buffer[context.pos++] = encodeTable[(context.ibitWorkArea >> 18) & MASK_6BITS];
    388                    buffer[context.pos++] = encodeTable[(context.ibitWorkArea >> 12) & MASK_6BITS];
    389                    buffer[context.pos++] = encodeTable[(context.ibitWorkArea >> 6) & MASK_6BITS];
    390                    buffer[context.pos++] = encodeTable[context.ibitWorkArea & MASK_6BITS];
    391                    context.currentLinePos += BYTES_PER_ENCODED_BLOCK;
    392                    if (lineLength > 0 && lineLength <= context.currentLinePos) {
    393                        System.arraycopy(lineSeparator, 0, buffer, context.pos, lineSeparator.length);
    394                        context.pos += lineSeparator.length;
    395                        context.currentLinePos = 0;
    396                    }
    397                }
    398            }
    399        }
    400    }
    401
    402    /**
    403     * <p>
    404     * Decodes all of the provided data, starting at inPos, for inAvail bytes. Should be called at least twice: once
    405     * with the data to decode, and once with inAvail set to "-1" to alert decoder that EOF has been reached. The "-1"
    406     * call is not necessary when decoding, but it doesn't hurt, either.
    407     * </p>
    408     * <p>
    409     * Ignores all non-base64 characters. This is how chunked (e.g. 76 character) data is handled, since CR and LF are
    410     * silently ignored, but has implications for other bytes, too. This method subscribes to the garbage-in,
    411     * garbage-out philosophy: it will not check the provided data for validity.
    412     * </p>
    413     * <p>
    414     * Thanks to "commons" project in ws.apache.org for the bitwise operations, and general approach.
    415     * http://svn.apache.org/repos/asf/webservices/commons/trunk/modules/util/
    416     * </p>
    417     *
    418     * @param in
    419     *            byte[] array of ascii data to base64 decode.
    420     * @param inPos
    421     *            Position to start reading data from.
    422     * @param inAvail
    423     *            Amount of bytes available from input for encoding.
    424     * @param context
    425     *            the context to be used
    426     */
    427    @Override
    428    void decode(final byte[] in, int inPos, final int inAvail, final Context context) {
    429        if (context.eof) {
    430            return;
    431        }
    432        if (inAvail < 0) {
    433            context.eof = true;
    434        }
    435        for (int i = 0; i < inAvail; i++) {
    436            final byte[] buffer = ensureBufferSize(decodeSize, context);
    437            final byte b = in[inPos++];
    438            if (b == pad) {
    439                // We're done.
    440                context.eof = true;
    441                break;
    442            } else {
    443                if (b >= 0 && b < DECODE_TABLE.length) {
    444                    final int result = DECODE_TABLE[b];
    445                    if (result >= 0) {
    446                        context.modulus = (context.modulus+1) % BYTES_PER_ENCODED_BLOCK;
    447                        context.ibitWorkArea = (context.ibitWorkArea << BITS_PER_ENCODED_BYTE) + result;
    448                        if (context.modulus == 0) {
    449                            buffer[context.pos++] = (byte) ((context.ibitWorkArea >> 16) & MASK_8BITS);
    450                            buffer[context.pos++] = (byte) ((context.ibitWorkArea >> 8) & MASK_8BITS);
    451                            buffer[context.pos++] = (byte) (context.ibitWorkArea & MASK_8BITS);
    452                        }
    453                    }
    454                }
    455            }
    456        }
    457
    458        // Two forms of EOF as far as base64 decoder is concerned: actual
    459        // EOF (-1) and first time '=' character is encountered in stream.
    460        // This approach makes the '=' padding characters completely optional.
    461        if (context.eof && context.modulus != 0) {
    462            final byte[] buffer = ensureBufferSize(decodeSize, context);
    463
    464            // We have some spare bits remaining
    465            // Output all whole multiples of 8 bits and ignore the rest
    466            switch (context.modulus) {
    467//              case 0 : // impossible, as excluded above
    468                case 1 : // 6 bits - ignore entirely
    469                    // TODO not currently tested; perhaps it is impossible?
    470                    break;
    471                case 2 : // 12 bits = 8 + 4
    472                    context.ibitWorkArea = context.ibitWorkArea >> 4; // dump the extra 4 bits
    473                    buffer[context.pos++] = (byte) ((context.ibitWorkArea) & MASK_8BITS);
    474                    break;
    475                case 3 : // 18 bits = 8 + 8 + 2
    476                    context.ibitWorkArea = context.ibitWorkArea >> 2; // dump 2 bits
    477                    buffer[context.pos++] = (byte) ((context.ibitWorkArea >> 8) & MASK_8BITS);
    478                    buffer[context.pos++] = (byte) ((context.ibitWorkArea) & MASK_8BITS);
    479                    break;
    480                default:
    481                    throw new IllegalStateException("Impossible modulus "+context.modulus);
    482            }
    483        }
    484    }
    485
    486    /**
    487     * Tests a given byte array to see if it contains only valid characters within the Base64 alphabet. Currently the
    488     * method treats whitespace as valid.
    489     *
    490     * @param arrayOctet
    491     *            byte array to test
    492     * @return <code>true</code> if all bytes are valid characters in the Base64 alphabet or if the byte array is empty;
    493     *         <code>false</code>, otherwise
    494     * @deprecated 1.5 Use {@link #isBase64(byte[])}, will be removed in 2.0.
    495     */
    496    @Deprecated
    497    public static boolean isArrayByteBase64(final byte[] arrayOctet) {
    498        return isBase64(arrayOctet);
    499    }
    500
    501    /**
    502     * Returns whether or not the <code>octet</code> is in the base 64 alphabet.
    503     *
    504     * @param octet
    505     *            The value to test
    506     * @return <code>true</code> if the value is defined in the the base 64 alphabet, <code>false</code> otherwise.
    507     * @since 1.4
    508     */
    509    public static boolean isBase64(final byte octet) {
    510        return octet == PAD_DEFAULT || (octet >= 0 && octet < DECODE_TABLE.length && DECODE_TABLE[octet] != -1);
    511    }
    512
    513    /**
    514     * Tests a given String to see if it contains only valid characters within the Base64 alphabet. Currently the
    515     * method treats whitespace as valid.
    516     *
    517     * @param base64
    518     *            String to test
    519     * @return <code>true</code> if all characters in the String are valid characters in the Base64 alphabet or if
    520     *         the String is empty; <code>false</code>, otherwise
    521     *  @since 1.5
    522     */
    523    public static boolean isBase64(final String base64) {
    524        return isBase64(StringUtils.getBytesUtf8(base64));
    525    }
    526
    527    /**
    528     * Tests a given byte array to see if it contains only valid characters within the Base64 alphabet. Currently the
    529     * method treats whitespace as valid.
    530     *
    531     * @param arrayOctet
    532     *            byte array to test
    533     * @return <code>true</code> if all bytes are valid characters in the Base64 alphabet or if the byte array is empty;
    534     *         <code>false</code>, otherwise
    535     * @since 1.5
    536     */
    537    public static boolean isBase64(final byte[] arrayOctet) {
    538        for (int i = 0; i < arrayOctet.length; i++) {
    539            if (!isBase64(arrayOctet[i]) && !isWhiteSpace(arrayOctet[i])) {
    540                return false;
    541            }
    542        }
    543        return true;
    544    }
    545
    546    /**
    547     * Encodes binary data using the base64 algorithm but does not chunk the output.
    548     *
    549     * @param binaryData
    550     *            binary data to encode
    551     * @return byte[] containing Base64 characters in their UTF-8 representation.
    552     */
    553    public static byte[] encodeBase64(final byte[] binaryData) {
    554        return encodeBase64(binaryData, false);
    555    }
    556
    557    /**
    558     * Encodes binary data using the base64 algorithm but does not chunk the output.
    559     *
    560     * NOTE:  We changed the behaviour of this method from multi-line chunking (commons-codec-1.4) to
    561     * single-line non-chunking (commons-codec-1.5).
    562     *
    563     * @param binaryData
    564     *            binary data to encode
    565     * @return String containing Base64 characters.
    566     * @since 1.4 (NOTE:  1.4 chunked the output, whereas 1.5 does not).
    567     */
    568    public static String encodeBase64String(final byte[] binaryData) {
    569        return StringUtils.newStringUtf8(encodeBase64(binaryData, false));
    570    }
    571
    572    /**
    573     * Encodes binary data using a URL-safe variation of the base64 algorithm but does not chunk the output. The
    574     * url-safe variation emits - and _ instead of + and / characters.
    575     * <b>Note: no padding is added.</b>
    576     * @param binaryData
    577     *            binary data to encode
    578     * @return byte[] containing Base64 characters in their UTF-8 representation.
    579     * @since 1.4
    580     */
    581    public static byte[] encodeBase64URLSafe(final byte[] binaryData) {
    582        return encodeBase64(binaryData, false, true);
    583    }
    584
    585    /**
    586     * Encodes binary data using a URL-safe variation of the base64 algorithm but does not chunk the output. The
    587     * url-safe variation emits - and _ instead of + and / characters.
    588     * <b>Note: no padding is added.</b>
    589     * @param binaryData
    590     *            binary data to encode
    591     * @return String containing Base64 characters
    592     * @since 1.4
    593     */
    594    public static String encodeBase64URLSafeString(final byte[] binaryData) {
    595        return StringUtils.newStringUtf8(encodeBase64(binaryData, false, true));
    596    }
    597
    598    /**
    599     * Encodes binary data using the base64 algorithm and chunks the encoded output into 76 character blocks
    600     *
    601     * @param binaryData
    602     *            binary data to encode
    603     * @return Base64 characters chunked in 76 character blocks
    604     */
    605    public static byte[] encodeBase64Chunked(final byte[] binaryData) {
    606        return encodeBase64(binaryData, true);
    607    }
    608
    609    /**
    610     * Encodes binary data using the base64 algorithm, optionally chunking the output into 76 character blocks.
    611     *
    612     * @param binaryData
    613     *            Array containing binary data to encode.
    614     * @param isChunked
    615     *            if <code>true</code> this encoder will chunk the base64 output into 76 character blocks
    616     * @return Base64-encoded data.
    617     * @throws IllegalArgumentException
    618     *             Thrown when the input array needs an output array bigger than {@link Integer#MAX_VALUE}
    619     */
    620    public static byte[] encodeBase64(final byte[] binaryData, final boolean isChunked) {
    621        return encodeBase64(binaryData, isChunked, false);
    622    }
    623
    624    /**
    625     * Encodes binary data using the base64 algorithm, optionally chunking the output into 76 character blocks.
    626     *
    627     * @param binaryData
    628     *            Array containing binary data to encode.
    629     * @param isChunked
    630     *            if <code>true</code> this encoder will chunk the base64 output into 76 character blocks
    631     * @param urlSafe
    632     *            if <code>true</code> this encoder will emit - and _ instead of the usual + and / characters.
    633     *            <b>Note: no padding is added when encoding using the URL-safe alphabet.</b>
    634     * @return Base64-encoded data.
    635     * @throws IllegalArgumentException
    636     *             Thrown when the input array needs an output array bigger than {@link Integer#MAX_VALUE}
    637     * @since 1.4
    638     */
    639    public static byte[] encodeBase64(final byte[] binaryData, final boolean isChunked, final boolean urlSafe) {
    640        return encodeBase64(binaryData, isChunked, urlSafe, Integer.MAX_VALUE);
    641    }
    642
    643    /**
    644     * Encodes binary data using the base64 algorithm, optionally chunking the output into 76 character blocks.
    645     *
    646     * @param binaryData
    647     *            Array containing binary data to encode.
    648     * @param isChunked
    649     *            if <code>true</code> this encoder will chunk the base64 output into 76 character blocks
    650     * @param urlSafe
    651     *            if <code>true</code> this encoder will emit - and _ instead of the usual + and / characters.
    652     *            <b>Note: no padding is added when encoding using the URL-safe alphabet.</b>
    653     * @param maxResultSize
    654     *            The maximum result size to accept.
    655     * @return Base64-encoded data.
    656     * @throws IllegalArgumentException
    657     *             Thrown when the input array needs an output array bigger than maxResultSize
    658     * @since 1.4
    659     */
    660    public static byte[] encodeBase64(final byte[] binaryData, final boolean isChunked,
    661                                      final boolean urlSafe, final int maxResultSize) {
    662        if (binaryData == null || binaryData.length == 0) {
    663            return binaryData;
    664        }
    665
    666        // Create this so can use the super-class method
    667        // Also ensures that the same roundings are performed by the ctor and the code
    668        final Base64 b64 = isChunked ? new Base64(urlSafe) : new Base64(0, CHUNK_SEPARATOR, urlSafe);
    669        final long len = b64.getEncodedLength(binaryData);
    670        if (len > maxResultSize) {
    671            throw new IllegalArgumentException("Input array too big, the output array would be bigger (" +
    672                len +
    673                ") than the specified maximum size of " +
    674                maxResultSize);
    675        }
    676
    677        return b64.encode(binaryData);
    678    }
    679
    680    /**
    681     * Decodes a Base64 String into octets.
    682     * <p>
    683     * <b>Note:</b> this method seamlessly handles data encoded in URL-safe or normal mode.
    684     * </p>
    685     *
    686     * @param base64String
    687     *            String containing Base64 data
    688     * @return Array containing decoded data.
    689     * @since 1.4
    690     */
    691    public static byte[] decodeBase64(final String base64String) {
    692        return new Base64().decode(base64String);
    693    }
    694
    695    /**
    696     * Decodes Base64 data into octets.
    697     * <p>
    698     * <b>Note:</b> this method seamlessly handles data encoded in URL-safe or normal mode.
    699     * </p>
    700     *
    701     * @param base64Data
    702     *            Byte array containing Base64 data
    703     * @return Array containing decoded data.
    704     */
    705    public static byte[] decodeBase64(final byte[] base64Data) {
    706        return new Base64().decode(base64Data);
    707    }
    708
    709    // Implementation of the Encoder Interface
    710
    711    // Implementation of integer encoding used for crypto
    712    /**
    713     * Decodes a byte64-encoded integer according to crypto standards such as W3C's XML-Signature.
    714     *
    715     * @param pArray
    716     *            a byte array containing base64 character data
    717     * @return A BigInteger
    718     * @since 1.4
    719     */
    720    public static BigInteger decodeInteger(final byte[] pArray) {
    721        return new BigInteger(1, decodeBase64(pArray));
    722    }
    723
    724    /**
    725     * Encodes to a byte64-encoded integer according to crypto standards such as W3C's XML-Signature.
    726     *
    727     * @param bigInt
    728     *            a BigInteger
    729     * @return A byte array containing base64 character data
    730     * @throws NullPointerException
    731     *             if null is passed in
    732     * @since 1.4
    733     */
    734    public static byte[] encodeInteger(final BigInteger bigInt) {
    735        if (bigInt == null) {
    736            throw new NullPointerException("encodeInteger called with null parameter");
    737        }
    738        return encodeBase64(toIntegerBytes(bigInt), false);
    739    }
    740
    741    /**
    742     * Returns a byte-array representation of a <code>BigInteger</code> without sign bit.
    743     *
    744     * @param bigInt
    745     *            <code>BigInteger</code> to be converted
    746     * @return a byte array representation of the BigInteger parameter
    747     */
    748    static byte[] toIntegerBytes(final BigInteger bigInt) {
    749        int bitlen = bigInt.bitLength();
    750        // round bitlen
    751        bitlen = ((bitlen + 7) >> 3) << 3;
    752        final byte[] bigBytes = bigInt.toByteArray();
    753
    754        if (((bigInt.bitLength() % 8) != 0) && (((bigInt.bitLength() / 8) + 1) == (bitlen / 8))) {
    755            return bigBytes;
    756        }
    757        // set up params for copying everything but sign bit
    758        int startSrc = 0;
    759        int len = bigBytes.length;
    760
    761        // if bigInt is exactly byte-aligned, just skip signbit in copy
    762        if ((bigInt.bitLength() % 8) == 0) {
    763            startSrc = 1;
    764            len--;
    765        }
    766        final int startDst = bitlen / 8 - len; // to pad w/ nulls as per spec
    767        final byte[] resizedBytes = new byte[bitlen / 8];
    768        System.arraycopy(bigBytes, startSrc, resizedBytes, startDst, len);
    769        return resizedBytes;
    770    }
    771
    772    /**
    773     * Returns whether or not the <code>octet</code> is in the Base64 alphabet.
    774     *
    775     * @param octet
    776     *            The value to test
    777     * @return <code>true</code> if the value is defined in the the Base64 alphabet <code>false</code> otherwise.
    778     */
    779    @Override
    780    protected boolean isInAlphabet(final byte octet) {
    781        return octet >= 0 && octet < decodeTable.length && decodeTable[octet] != -1;
    782    }
    783
    784}