org.apache.commons.net.util

## Class Base64

- java.lang.Object
- - org.apache.commons.net.util.Base64

-     public class Base64
      extends Object

  Provides Base64 encoding and decoding as defined by RFC 2045.

  This class implements section 6.8. Base64 Content-Transfer-Encoding from RFC 2045 Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies by Freed and Borenstein.

  The class can be parameterized in the following manner with various constructors:

  - URL-safe mode: Default off.
  - Line length: Default 76. Line length that aren't multiples of 4 will still essentially end up being multiples of 4 in the encoded data.
  - Line separator: Default is CRLF ("\r\n")

  Since this class operates directly on byte streams, and not character streams, it is hard-coded to only encode/decode character encodings which are compatible with the lower 127 ASCII chart (ISO-8859-1, Windows-1252, UTF-8, etc).

  Since:
    2.2
  See Also:
    RFC 2045

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Base64()` Creates a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode.
    `Base64(boolean urlSafe)` Creates a Base64 codec used for decoding (all modes) and encoding in the given URL-safe mode.
    `Base64(int lineLength)` Creates a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode.
    `Base64(int lineLength, byte[] lineSeparator)` Creates a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode.
    `Base64(int lineLength, byte[] lineSeparator, boolean urlSafe)` Creates a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `byte[]` | `decode(byte[] pArray)` Decodes a byte[] containing containing characters in the Base64 alphabet.
    `byte[]` | `decode(String pArray)` Decodes a String containing containing characters in the Base64 alphabet.
    `static byte[]` | `decodeBase64(byte[] base64Data)` Decodes Base64 data into octets.
    `static byte[]` | `decodeBase64(String base64String)` Decodes a Base64 String into octets.
    `static BigInteger` | `decodeInteger(byte[] pArray)` Decodes a byte64-encoded integer according to crypto standards such as W3C's XML-Signature
    `byte[]` | `encode(byte[] pArray)` Encodes a byte[] containing binary data, into a byte[] containing characters in the Base64 alphabet.
    `static byte[]` | `encodeBase64(byte[] binaryData)` Encodes binary data using the base64 algorithm but does not chunk the output.
    `static byte[]` | `encodeBase64(byte[] binaryData, boolean isChunked)` Encodes binary data using the base64 algorithm, optionally chunking the output into 76 character blocks.
    `static byte[]` | `encodeBase64(byte[] binaryData, boolean isChunked, boolean urlSafe)` Encodes binary data using the base64 algorithm, optionally chunking the output into 76 character blocks.
    `static byte[]` | `encodeBase64(byte[] binaryData, boolean isChunked, boolean urlSafe, int maxResultSize)` Encodes binary data using the base64 algorithm, optionally chunking the output into 76 character blocks.
    `static byte[]` | `encodeBase64Chunked(byte[] binaryData)` Encodes binary data using the base64 algorithm and chunks the encoded output into 76 character blocks
    `static String` | `encodeBase64String(byte[] binaryData)` Encodes binary data using the base64 algorithm into 76 character blocks separated by CRLF.
    `static String` | `encodeBase64String(byte[] binaryData, boolean useChunking)` Encodes binary data using the base64 algorithm.
    `static String` | `encodeBase64StringUnChunked(byte[] binaryData)` Encodes binary data using the base64 algorithm, without using chunking.
    `static byte[]` | `encodeBase64URLSafe(byte[] binaryData)` Encodes binary data using a URL-safe variation of the base64 algorithm but does not chunk the output.
    `static String` | `encodeBase64URLSafeString(byte[] binaryData)` Encodes binary data using a URL-safe variation of the base64 algorithm but does not chunk the output.
    `static byte[]` | `encodeInteger(BigInteger bigInt)` Encodes to a byte64-encoded integer according to crypto standards such as W3C's XML-Signature
    `String` | `encodeToString(byte[] pArray)` Encodes a byte[] containing binary data, into a String containing characters in the Base64 alphabet.
    `static boolean` | `isArrayByteBase64(byte[] arrayOctet)` Tests a given byte array to see if it contains only valid characters within the Base64 alphabet.
    `static boolean` | `isBase64(byte octet)` Returns whether or not the `octet` is in the base 64 alphabet.
    `boolean` | `isUrlSafe()` Returns our current encode mode.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Base64

          public Base64()

      Creates a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode.

      When encoding the line length is 76, the line separator is CRLF, and the encoding table is STANDARD_ENCODE_TABLE.

      When decoding all variants are supported.

    - #### Base64

          public Base64(boolean urlSafe)

      Creates a Base64 codec used for decoding (all modes) and encoding in the given URL-safe mode.

      When encoding the line length is 76, the line separator is CRLF, and the encoding table is STANDARD_ENCODE_TABLE.

      When decoding all variants are supported.

      Parameters:
        `urlSafe` - if `true`, URL-safe encoding is used. In most cases this should be set to `false`.
      Since:
        1.4

    - #### Base64

          public Base64(int lineLength)

      Creates a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode.

      When encoding the line length is given in the constructor, the line separator is CRLF, and the encoding table is STANDARD_ENCODE_TABLE.

      Line lengths that aren't multiples of 4 will still essentially end up being multiples of 4 in the encoded data.

      When decoding all variants are supported.

      Parameters:
        `lineLength` - Each line of encoded data will be at most of the given length (rounded down to nearest multiple of 4). If `lineLength <= 0`, then the output will not be divided into lines (chunks). Ignored when decoding.
      Since:
        1.4

    - #### Base64

          public Base64(int lineLength,
                        byte[] lineSeparator)

      Creates a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode.

      When encoding the line length and line separator are given in the constructor, and the encoding table is STANDARD_ENCODE_TABLE.

      Line lengths that aren't multiples of 4 will still essentially end up being multiples of 4 in the encoded data.

      When decoding all variants are supported.

      Parameters:
        `lineLength` - Each line of encoded data will be at most of the given length (rounded down to nearest multiple of 4). If `lineLength <= 0`, then the output will not be divided into lines (chunks). Ignored when decoding.
        `lineSeparator` - Each line of encoded data will end with this sequence of bytes.
      Throws:
        `IllegalArgumentException` - Thrown when the provided lineSeparator included some base64 characters.
      Since:
        1.4

    - #### Base64

          public Base64(int lineLength,
                        byte[] lineSeparator,
                        boolean urlSafe)

      Creates a Base64 codec used for decoding (all modes) and encoding in URL-unsafe mode.

      When encoding the line length and line separator are given in the constructor, and the encoding table is STANDARD_ENCODE_TABLE.

      Line lengths that aren't multiples of 4 will still essentially end up being multiples of 4 in the encoded data.

      When decoding all variants are supported.

      Parameters:
        `lineLength` - Each line of encoded data will be at most of the given length (rounded down to nearest multiple of 4). If `lineLength <= 0`, then the output will not be divided into lines (chunks). Ignored when decoding.
        `lineSeparator` - Each line of encoded data will end with this sequence of bytes.
        `urlSafe` - Instead of emitting '+' and '/' we emit '-' and '_' respectively. urlSafe is only applied to encode operations. Decoding seamlessly handles both modes.
      Throws:
        `IllegalArgumentException` - The provided lineSeparator included some base64 characters. That's not going to work!
      Since:
        1.4

  - ### Method Detail

    - #### isUrlSafe

          public boolean isUrlSafe()

      Returns our current encode mode. True if we're URL-SAFE, false otherwise.
      Returns:
        true if we're in URL-SAFE mode, false otherwise.
      Since:
        1.4

    - #### isBase64

          public static boolean isBase64(byte octet)

      Returns whether or not the `octet` is in the base 64 alphabet.
      Parameters:
        `octet` - The value to test
      Returns:
        `true` if the value is defined in the the base 64 alphabet, `false` otherwise.
      Since:
        1.4

    - #### isArrayByteBase64

          public static boolean isArrayByteBase64(byte[] arrayOctet)

      Tests a given byte array to see if it contains only valid characters within the Base64 alphabet. Currently the method treats whitespace as valid.
      Parameters:
        `arrayOctet` - byte array to test
      Returns:
        `true` if all bytes are valid characters in the Base64 alphabet or if the byte array is empty; false, otherwise

    - #### encodeBase64

          public static byte[] encodeBase64(byte[] binaryData)

      Encodes binary data using the base64 algorithm but does not chunk the output.
      Parameters:
        `binaryData` - binary data to encode
      Returns:
        byte[] containing Base64 characters in their UTF-8 representation.

    - #### encodeBase64String

          public static String encodeBase64String(byte[] binaryData)

      Encodes binary data using the base64 algorithm into 76 character blocks separated by CRLF.

      For a non-chunking version, see `encodeBase64StringUnChunked(byte[])`.

      Parameters:
        `binaryData` - binary data to encode
      Returns:
        String containing Base64 characters.
      Since:
        1.4

    - #### encodeBase64StringUnChunked

          public static String encodeBase64StringUnChunked(byte[] binaryData)

      Encodes binary data using the base64 algorithm, without using chunking.

      For a chunking version, see `encodeBase64String(byte[])`.

      Parameters:
        `binaryData` - binary data to encode
      Returns:
        String containing Base64 characters.
      Since:
        3.2

    - #### encodeBase64String

          public static String encodeBase64String(byte[] binaryData,
                                                  boolean useChunking)

      Encodes binary data using the base64 algorithm.
      Parameters:
        `binaryData` - binary data to encode
        `useChunking` - whether to split the output into chunks
      Returns:
        String containing Base64 characters.
      Since:
        3.2

    - #### encodeBase64URLSafe

          public static byte[] encodeBase64URLSafe(byte[] binaryData)

      Encodes binary data using a URL-safe variation of the base64 algorithm but does not chunk the output. The url-safe variation emits - and _ instead of + and / characters.
      Parameters:
        `binaryData` - binary data to encode
      Returns:
        byte[] containing Base64 characters in their UTF-8 representation.
      Since:
        1.4

    - #### encodeBase64URLSafeString

          public static String encodeBase64URLSafeString(byte[] binaryData)

      Encodes binary data using a URL-safe variation of the base64 algorithm but does not chunk the output. The url-safe variation emits - and _ instead of + and / characters.
      Parameters:
        `binaryData` - binary data to encode
      Returns:
        String containing Base64 characters
      Since:
        1.4

    - #### encodeBase64Chunked

          public static byte[] encodeBase64Chunked(byte[] binaryData)

      Encodes binary data using the base64 algorithm and chunks the encoded output into 76 character blocks
      Parameters:
        `binaryData` - binary data to encode
      Returns:
        Base64 characters chunked in 76 character blocks

    - #### decode

          public byte[] decode(String pArray)

      Decodes a String containing containing characters in the Base64 alphabet.
      Parameters:
        `pArray` - A String containing Base64 character data
      Returns:
        a byte array containing binary data
      Since:
        1.4

    - #### decode

          public byte[] decode(byte[] pArray)

      Decodes a byte[] containing containing characters in the Base64 alphabet.
      Parameters:
        `pArray` - A byte array containing Base64 character data
      Returns:
        a byte array containing binary data

    - #### encodeBase64

          public static byte[] encodeBase64(byte[] binaryData,
                                            boolean isChunked)

      Encodes binary data using the base64 algorithm, optionally chunking the output into 76 character blocks.
      Parameters:
        `binaryData` - Array containing binary data to encode.
        `isChunked` - if `true` this encoder will chunk the base64 output into 76 character blocks
      Returns:
        Base64-encoded data.
      Throws:
        `IllegalArgumentException` - Thrown when the input array needs an output array bigger than `Integer.MAX_VALUE`

    - #### encodeBase64

          public static byte[] encodeBase64(byte[] binaryData,
                                            boolean isChunked,
                                            boolean urlSafe)

      Encodes binary data using the base64 algorithm, optionally chunking the output into 76 character blocks.
      Parameters:
        `binaryData` - Array containing binary data to encode.
        `isChunked` - if `true` this encoder will chunk the base64 output into 76 character blocks
        `urlSafe` - if `true` this encoder will emit - and _ instead of the usual + and / characters.
      Returns:
        Base64-encoded data.
      Throws:
        `IllegalArgumentException` - Thrown when the input array needs an output array bigger than `Integer.MAX_VALUE`
      Since:
        1.4

    - #### encodeBase64

          public static byte[] encodeBase64(byte[] binaryData,
                                            boolean isChunked,
                                            boolean urlSafe,
                                            int maxResultSize)

      Encodes binary data using the base64 algorithm, optionally chunking the output into 76 character blocks.
      Parameters:
        `binaryData` - Array containing binary data to encode.
        `isChunked` - if `true` this encoder will chunk the base64 output into 76 character blocks
        `urlSafe` - if `true` this encoder will emit - and _ instead of the usual + and / characters.
        `maxResultSize` - The maximum result size to accept.
      Returns:
        Base64-encoded data.
      Throws:
        `IllegalArgumentException` - Thrown when the input array needs an output array bigger than maxResultSize
      Since:
        1.4

    - #### decodeBase64

          public static byte[] decodeBase64(String base64String)

      Decodes a Base64 String into octets.
      Parameters:
        `base64String` - String containing Base64 data
      Returns:
        Array containing decoded data.
      Since:
        1.4

    - #### decodeBase64

          public static byte[] decodeBase64(byte[] base64Data)

      Decodes Base64 data into octets.
      Parameters:
        `base64Data` - Byte array containing Base64 data
      Returns:
        Array containing decoded data.

    - #### encodeToString

          public String encodeToString(byte[] pArray)

      Encodes a byte[] containing binary data, into a String containing characters in the Base64 alphabet.
      Parameters:
        `pArray` - a byte array containing binary data
      Returns:
        A String containing only Base64 character data
      Since:
        1.4

    - #### encode

          public byte[] encode(byte[] pArray)

      Encodes a byte[] containing binary data, into a byte[] containing characters in the Base64 alphabet.
      Parameters:
        `pArray` - a byte array containing binary data
      Returns:
        A byte array containing only Base64 character data

    - #### decodeInteger

          public static BigInteger decodeInteger(byte[] pArray)

      Decodes a byte64-encoded integer according to crypto standards such as W3C's XML-Signature
      Parameters:
        `pArray` - a byte array containing base64 character data
      Returns:
        A BigInteger
      Since:
        1.4

    - #### encodeInteger

          public static byte[] encodeInteger(BigInteger bigInt)

      Encodes to a byte64-encoded integer according to crypto standards such as W3C's XML-Signature
      Parameters:
        `bigInt` - a BigInteger
      Returns:
        A byte array containing base64 character data
      Throws:
        `NullPointerException` - if null is passed in
      Since:
        1.4

Copyright © 2001–2021 The Apache Software Foundation. All rights reserved.