Package org.apache.tomcat.util.codec.binary

# Class Base64

java.lang.Object
org.apache.tomcat.util.codec.binary.BaseNCodec
org.apache.tomcat.util.codec.binary.Base64

All Implemented Interfaces:
  `BinaryDecoder`, `BinaryEncoder`, `Decoder`, `Encoder`

public class Base64 extends BaseNCodec
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")

The URL-safe parameter is only applied to encode operations. Decoding seamlessly handles both modes.

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).

This class is thread-safe.

Since:
  1.0
See Also:
  - RFC 2045

## Field Summary

### Fields inherited from class org.apache.tomcat.util.codec.binary.BaseNCodec

`lineLength, MASK_8BITS, MIME_CHUNK_SIZE, pad, PAD_DEFAULT, PEM_CHUNK_SIZE, sm`

## Constructor Summary

Constructors
Constructor
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

Modifier and Type
Method
Description
`static byte[]`
`decodeBase64(byte[] base64Data)`
Decodes Base64 data into octets.
`static byte[]`
`decodeBase64(byte[] base64Data, int off, int len)`
`static byte[]`
`decodeBase64(String base64String)`
Decodes a Base64 String into octets.
`static byte[]`
`decodeBase64URLSafe(String base64String)`
`static BigInteger`
`decodeInteger(byte[] pArray)`
Decodes a byte64-encoded integer according to crypto standards such as W3C's XML-Signature.
`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 but does not chunk the output.
`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 bigInteger)`
Encodes to a byte64-encoded integer according to crypto standards such as W3C's XML-Signature.
`static boolean`
`isBase64(byte octet)`
Returns whether or not the `octet` is in the base 64 alphabet.
`static boolean`
`isBase64(byte[] arrayOctet)`
Tests a given byte array to see if it contains only valid characters within the Base64 alphabet.
`static boolean`
`isBase64(String base64)`
Tests a given String to see if it contains only valid characters within the Base64 alphabet.
`protected boolean`
`isInAlphabet(byte octet)`
Returns whether or not the `octet` is in the Base64 alphabet.
`static boolean`
`isInAlphabet(char c)`
`boolean`
`isUrlSafe()`
Returns our current encode mode.

### Methods inherited from class org.apache.tomcat.util.codec.binary.BaseNCodec

`containsAlphabetOrPad, decode, decode, decode, decode, encode, encode, encode, encodeAsString, encodeToString, ensureBufferSize, getChunkSeparator, getDefaultBufferSize, getEncodedLength, isInAlphabet, isInAlphabet, isWhiteSpace`

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

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

## Constructor Details

### Base64

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

When encoding the line length is 0 (no chunking), 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 the 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 the 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 the 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. Note: no padding is added when using the URL-safe alphabet.
Throws:
  `IllegalArgumentException` - Thrown when the `lineSeparator` contains Base64 characters.
Since:
  1.4

## Method Details

### decodeBase64

public static byte[] decodeBase64(byte[] base64Data)
Decodes Base64 data into octets.

Note: this method seamlessly handles data encoded in URL-safe or normal mode.

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

### decodeBase64

public static byte[] decodeBase64(byte[] base64Data, int off, int len)

### decodeBase64

public static byte[] decodeBase64(String base64String)
Decodes a Base64 String into octets.

Note: this method seamlessly handles data encoded in URL-safe or normal mode.

Parameters:
  `base64String` - String containing Base64 data
Returns:
  Array containing decoded data.
Since:
  1.4

### decodeBase64URLSafe

public static byte[] decodeBase64URLSafe(String base64String)

### 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

### 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.

### 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. Note: no padding is added when encoding using the URL-safe alphabet.
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. Note: no padding is added when encoding using the URL-safe alphabet.
  `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

### 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

### encodeBase64String

public static String encodeBase64String(byte[] binaryData)
Encodes binary data using the base64 algorithm but does not chunk the output. NOTE: We changed the behavior of this method from multi-line chunking (commons-codec-1.4) to single-line non-chunking (commons-codec-1.5).

Parameters:
  `binaryData` - binary data to encode
Returns:
  String containing Base64 characters.
Since:
  1.4 (NOTE: 1.4 chunked the output, whereas 1.5 does not).

### 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. Note: no padding is added.

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. Note: no padding is added.

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

### encodeInteger

public static byte[] encodeInteger(BigInteger bigInteger)
Encodes to a byte64-encoded integer according to crypto standards such as W3C's XML-Signature.

Parameters:
  `bigInteger` - a BigInteger
Returns:
  A byte array containing base64 character data
Throws:
  `NullPointerException` - if null is passed in
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

### isBase64

public static boolean isBase64(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
Since:
  1.5

### isBase64

public static boolean isBase64(String base64)
Tests a given String to see if it contains only valid characters within the Base64 alphabet. Currently the method treats whitespace as valid.

Parameters:
  `base64` - String to test
Returns:
  `true` if all characters in the String are valid characters in the Base64 alphabet or if the String is empty; `false`, otherwise
Since:
  1.5

### isInAlphabet

public static boolean isInAlphabet(char c)

### isInAlphabet

protected boolean isInAlphabet(byte octet)
Returns whether or not the `octet` is in the Base64 alphabet.

Specified by:
  `isInAlphabet` in class `BaseNCodec`
Parameters:
  `octet` - The value to test
Returns:
  `true` if the value is defined in the Base64 alphabet `false` otherwise.

### 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