org.apache.commons.codec.binary.BaseNCodec

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

Direct Known Subclasses:: Base16, Base32, Base45, Base58, Base64

public abstract class BaseNCodec extends Object implements BinaryEncoder, BinaryDecoder

Abstract superclass for Base-N encoders and decoders.

This class is thread-safe.

The default decoding policy is lenient. Strict decoding rejects trailing bits that cannot be produced by an encoding, including nonzero unused bits and impossible counts of final characters.

For Base32 and Base64, strict decoding additionally requires the exact canonical form produced by this instance's encoder. Re-encoding successfully decoded input reproduces the input byte for byte. This includes the configured alphabet, padding, line length, and line separator, including the final line separator when chunking is enabled. Whitespace and alphabet aliases are rejected unless the encoder produces them in that position.

Lenient decoding can map different encoded values to the same bytes. If an application uses encoded values as identifiers for blocklists, replay caches, or deduplication, validate canonical input before comparing those identifiers, or compare a consistently normalized representation throughout the application. Decoding alone does not authenticate input; signature verification must use the representation required by the signing protocol.

For example, select canonical Base32 decoding with:

Base32 base32 = Base32.builder().setDecodingPolicy(CodecPolicy.STRICT).get();

This instance requires the uppercase Base32 alphabet, padding for partial blocks, and no line separators. See Base64 for standard and URL-safe Base64 examples.

Strict validation completes only at the end of the input. When decoding streams, consume the input stream to EOF or finish the output stream with BaseNCodecOutputStream.eof() or BaseNCodecOutputStream.close(). A stream can emit decoded bytes before a later validation error.

Nested Class Summary

Nested Classes

Modifier and Type

Class

Description

static class

BaseNCodec.AbstractBuilder<T, B extends BaseNCodec.AbstractBuilder<T,B>>

Builds Base64 instances.
Field Summary

Fields

Modifier and Type

Field

Description

protected static final CodecPolicy

DECODING_POLICY_DEFAULT

The default decoding policy.

protected final int

lineLength

Chunk size for encoding and strict decoding.

protected static final int

MASK_8BITS

Mask used to extract 8 bits, used in decoding bytes

static final int

MIME_CHUNK_SIZE

MIME chunk size per RFC 2045 section 6.8.

protected final byte

pad

Pad byte.

protected final byte

PAD

Deprecated.
Use pad.

protected static final byte

PAD_DEFAULT

Byte used to pad output.

static final int

PEM_CHUNK_SIZE

PEM chunk size per RFC 1421 section 4.3.2.4.
Constructor Summary

Constructors

Modifier

Constructor

Description

protected

BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength)

Deprecated.
Use BaseNCodec(AbstractBuilder).

protected

BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength, byte pad)

Deprecated.
Use BaseNCodec(AbstractBuilder).

protected

BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength, byte pad, CodecPolicy decodingPolicy)

Deprecated.
Use BaseNCodec(AbstractBuilder).

protected

BaseNCodec(BaseNCodec.AbstractBuilder<?,?> builder)

Constructs a new instance for a subclass.
Method Summary

Modifier and Type

Method

Description

protected boolean

containsAlphabetOrPad(byte[] arrayOctet)

Tests a given byte array to see if it contains any characters within the alphabet or PAD.

byte[]

decode(byte[] array)

Decodes a byte[] containing characters in the Base-N alphabet.

Object

decode(Object obj)

Decodes an Object using the Base-N algorithm.

byte[]

decode(String array)

Decodes a String containing characters in the Base-N alphabet.

byte[]

encode(byte[] array)

Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.

byte[]

encode(byte[] array, int offset, int length)

Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.

Object

encode(Object obj)

Encodes an Object using the Base-N algorithm.

String

encodeAsString(byte[] array)

Encodes a byte[] containing binary data, into a String containing characters in the appropriate alphabet.

String

encodeToString(byte[] array)

Encodes a byte[] containing binary data, into a String containing characters in the Base-N alphabet.

protected byte[]

ensureBufferSize(int size, org.apache.commons.codec.binary.BaseNCodec.Context context)

Ensures that the buffer has room for size bytes

static byte[]

getChunkSeparator()

Gets a copy of the chunk separator per RFC 2045 section 2.1.

CodecPolicy

getCodecPolicy()

Gets the decoding behavior policy.

protected int

getDefaultBufferSize()

Gets the default buffer size.

long

getEncodedLength(byte[] array)

Gets the amount of space needed to encode the supplied array.

protected abstract boolean

isInAlphabet(byte value)

Tests whether or not the octet is in the current alphabet.

boolean

isInAlphabet(byte[] arrayOctet, boolean allowWhitespacePad)

Tests a given byte array to see if it contains only valid characters within the alphabet.

boolean

isInAlphabet(String basen)

Tests a given String to see if it contains only valid characters within the alphabet.

boolean

isStrictDecoding()

Tests whether decoding behavior is strict.

protected static boolean

isWhiteSpace(byte byteToCheck)

Deprecated.
Use Character.isWhitespace(int).

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details
- MIME_CHUNK_SIZE
  public static final int MIME_CHUNK_SIZE
  
  MIME chunk size per RFC 2045 section 6.8.
  The 76 character limit does not count the trailing CRLF, but counts all other characters, including any equal signs.
  
  See Also:
  
  RFC 2045 section 6.8
  
  Constant Field Values
- PEM_CHUNK_SIZE
  public static final int PEM_CHUNK_SIZE
  
  PEM chunk size per RFC 1421 section 4.3.2.4.
  The 64 character limit does not count the trailing CRLF, but counts all other characters, including any equal signs.
  
  See Also:
  
  RFC 1421 section 4.3.2.4
  
  Constant Field Values
- MASK_8BITS
  protected static final int MASK_8BITS
  
  Mask used to extract 8 bits, used in decoding bytes
  
  See Also:
  
  Constant Field Values
- PAD_DEFAULT
  protected static final byte PAD_DEFAULT
  
  Byte used to pad output.
  
  See Also:
  
  Constant Field Values
- DECODING_POLICY_DEFAULT
  
  protected static final CodecPolicy DECODING_POLICY_DEFAULT
  
  The default decoding policy.
  
  Since:
  
  1.15
- PAD
  @Deprecated protected final byte PAD
  
  Deprecated.
  Use pad. Will be removed in 2.0.
  
  Deprecated: Will be removed in 2.0.
  Instance variable just in case it needs to vary later
  
  See Also:
  
  Constant Field Values
- pad
  
  protected final byte pad
  
  Pad byte. Instance variable just in case it needs to vary later.
- lineLength
  
  protected final int lineLength
  
  Chunk size for encoding and strict decoding. A value of zero or less implies no chunking of the encoded data. Rounded down to the nearest multiple of encodedBlockSize.
Constructor Details
- BaseNCodec
  
  protected BaseNCodec(BaseNCodec.AbstractBuilder<?,?> builder)
  
  Constructs a new instance for a subclass.
  
  Parameters:
  
  builder - How to build this portion of the instance.
  
  Since:
  
  1.20.0
- BaseNCodec
  
  @Deprecated protected BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength)
  
  Deprecated.
  Use BaseNCodec(AbstractBuilder).
  
  Constructs a new instance.
  Note lineLength is rounded down to the nearest multiple of the encoded block size. If chunkSeparatorLength is zero, then chunking is disabled.
  
  Parameters:
  
  unencodedBlockSize - The size of an unencoded block (for example Base64 = 3).
  
  encodedBlockSize - The size of an encoded block (for example Base64 = 4).
  
  lineLength - if > 0, use chunking with a length lineLength.
  
  chunkSeparatorLength - The chunk separator length, if relevant.
- BaseNCodec
  
  @Deprecated protected BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength, byte pad)
  
  Deprecated.
  Use BaseNCodec(AbstractBuilder).
  
  Constructs a new instance.
  Note lineLength is rounded down to the nearest multiple of the encoded block size. If chunkSeparatorLength is zero, then chunking is disabled.
  
  Parameters:
  
  unencodedBlockSize - The size of an unencoded block (for example Base64 = 3).
  
  encodedBlockSize - The size of an encoded block (for example Base64 = 4).
  
  lineLength - if > 0, use chunking with a length lineLength.
  
  chunkSeparatorLength - The chunk separator length, if relevant.
  
  pad - byte used as padding byte.
- BaseNCodec
  
  @Deprecated protected BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength, byte pad, CodecPolicy decodingPolicy)
  
  Deprecated.
  Use BaseNCodec(AbstractBuilder).
  
  Constructs a new instance.
  Note lineLength is rounded down to the nearest multiple of the encoded block size. If chunkSeparatorLength is zero, then chunking is disabled.
  
  Parameters:
  
  unencodedBlockSize - The size of an unencoded block (for example Base64 = 3).
  
  encodedBlockSize - The size of an encoded block (for example Base64 = 4).
  
  lineLength - if > 0, use chunking with a length lineLength.
  
  chunkSeparatorLength - The chunk separator length, if relevant.
  
  pad - byte used as padding byte.
  
  decodingPolicy - Decoding policy.
  
  Since:
  
  1.15
Method Details
- getChunkSeparator
  public static byte[] getChunkSeparator()
  
  Gets a copy of the chunk separator per RFC 2045 section 2.1.
  
  Returns:
  
  The chunk separator.
  
  Since:
  
  1.15
  
  See Also:
  
  RFC 2045 section 2.1
- isWhiteSpace
  @Deprecated protected static boolean isWhiteSpace(byte byteToCheck)
  
  Deprecated.
  Use Character.isWhitespace(int).
  
  Tests if a byte value is whitespace or not.
  
  Parameters:
  
  byteToCheck - The byte to check.
  
  Returns:
  
  true if byte is whitespace, false otherwise.
  
  See Also:
  
  Character.isWhitespace(int)
- containsAlphabetOrPad
  
  protected boolean containsAlphabetOrPad(byte[] arrayOctet)
  
  Tests a given byte array to see if it contains any characters within the alphabet or PAD. Intended for use in checking line-ending arrays.
  
  Parameters:
  
  arrayOctet - byte array to test.
  
  Returns:
  
  true if any byte is a valid character in the alphabet or PAD; false otherwise.
- decode
  
  public byte[] decode(byte[] array)
  
  Decodes a byte[] containing characters in the Base-N alphabet.
  Uses this instance's decoding policy. Lenient decoding can accept multiple representations of the same bytes. For canonical Base32 or Base64 input, configure CodecPolicy.STRICT; see the class documentation for examples and guidance on comparing encoded values.
  
  Specified by:
  
  decode in interface BinaryDecoder
  
  Parameters:
  
  array - A byte array containing Base-N character data.
  
  Returns:
  
  A byte array containing binary data.
  
  Throws:
  
  IllegalArgumentException - Thrown when a problem is detected processing data.
- decode
  
  public Object decode(Object obj) throws DecoderException
  
  Decodes an Object using the Base-N algorithm. This method is provided in order to satisfy the requirements of the Decoder interface, and will throw a DecoderException if the supplied object is not of type byte[] or String.
  Uses this instance's decoding policy. Lenient decoding can accept multiple representations of the same bytes. For canonical Base32 or Base64 input, configure CodecPolicy.STRICT; see the class documentation for examples and guidance on comparing encoded values.
  
  Specified by:
  
  decode in interface Decoder
  
  Parameters:
  
  obj - Object to decode.
  
  Returns:
  
  An object (of type byte[]) containing the binary data which corresponds to the byte[] or String supplied.
  
  Throws:
  
  DecoderException - Thrown if the parameter supplied is not of type byte[].
  
  IllegalArgumentException - Thrown when a problem is detected processing data.
- decode
  
  public byte[] decode(String array)
  
  Decodes a String containing characters in the Base-N alphabet.
  Uses this instance's decoding policy. Lenient decoding can accept multiple representations of the same bytes. For canonical Base32 or Base64 input, configure CodecPolicy.STRICT; see the class documentation for examples and guidance on comparing encoded values.
  
  Parameters:
  
  array - A String containing Base-N character data.
  
  Returns:
  
  A byte array containing binary data.
  
  Throws:
  
  IllegalArgumentException - Thrown when a problem is detected processing data.
- encode
  
  public byte[] encode(byte[] array)
  
  Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.
  
  Specified by:
  
  encode in interface BinaryEncoder
  
  Parameters:
  
  array - A byte array containing binary data.
  
  Returns:
  
  A byte array containing only the base N alphabetic character data.
  
  Throws:
  
  IllegalArgumentException - Thrown when a problem is detected processing data.
- encode
  
  public byte[] encode(byte[] array, int offset, int length)
  
  Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.
  
  Parameters:
  
  array - A byte array containing binary data.
  
  offset - initial offset of the subarray.
  
  length - length of the subarray.
  
  Returns:
  
  A byte array containing only the base N alphabetic character data.
  
  Throws:
  
  IllegalArgumentException - Thrown when a problem is detected processing data.
  
  Since:
  
  1.11
- encode
  
  public Object encode(Object obj) throws EncoderException
  
  Encodes an Object using the Base-N algorithm. This method is provided in order to satisfy the requirements of the Encoder interface, and will throw an EncoderException if the supplied object is not of type byte[].
  
  Specified by:
  
  encode in interface Encoder
  
  Parameters:
  
  obj - Object to encode.
  
  Returns:
  
  An object (of type byte[]) containing the Base-N encoded data which corresponds to the byte[] supplied.
  
  Throws:
  
  EncoderException - Thrown if the parameter supplied is not of type byte[].
- encodeAsString
  
  public String encodeAsString(byte[] array)
  
  Encodes a byte[] containing binary data, into a String containing characters in the appropriate alphabet. Uses UTF8 encoding.
  This is a duplicate of encodeToString(byte[]); it was merged during refactoring.
  
  Parameters:
  
  array - A byte array containing binary data.
  
  Returns:
  
  String containing only character data in the appropriate alphabet.
  
  Since:
  
  1.5
- encodeToString
  
  public String encodeToString(byte[] array)
  
  Encodes a byte[] containing binary data, into a String containing characters in the Base-N alphabet. Uses UTF8 encoding.
  
  Parameters:
  
  array - A byte array containing binary data.
  
  Returns:
  
  A String containing only Base-N character data.
- ensureBufferSize
  
  protected byte[] ensureBufferSize(int size, org.apache.commons.codec.binary.BaseNCodec.Context context)
  
  Ensures that the buffer has room for size bytes
  
  Parameters:
  
  size - minimum spare space required.
  
  context - The context to be used.
  
  Returns:
  
  The buffer.
- getCodecPolicy
  
  public CodecPolicy getCodecPolicy()
  
  Gets the decoding behavior policy.
  The default is lenient. Strict decoding rejects invalid trailing bits and, for Base32 and Base64, noncanonical input as described in this class.
  
  Returns:
  
  The decoding policy.
  
  Since:
  
  1.15
- getDefaultBufferSize
  
  protected int getDefaultBufferSize()
  
  Gets the default buffer size. Can be overridden.
  
  Returns:
  
  The default buffer size.
- getEncodedLength
  
  public long getEncodedLength(byte[] array)
  
  Gets the amount of space needed to encode the supplied array.
  
  Parameters:
  
  array - byte[] array which will later be encoded.
  
  Returns:
  
  amount of space needed to encode the supplied array. Returns a long since a max-len array will require > Integer.MAX_VALUE.
- isInAlphabet
  
  protected abstract boolean isInAlphabet(byte value)
  
  Tests whether or not the octet is in the current alphabet. Does not allow whitespace or pad.
  
  Parameters:
  
  value - The value to test.
  
  Returns:
  
  true if the value is defined in the current alphabet, false otherwise.
- isInAlphabet
  
  public boolean isInAlphabet(byte[] arrayOctet, boolean allowWhitespacePad)
  
  Tests a given byte array to see if it contains only valid characters within the alphabet. The method optionally treats whitespace and pad as valid.
  
  Parameters:
  
  arrayOctet - byte array to test.
  
  allowWhitespacePad - if true, then whitespace and PAD are also allowed.
  
  Returns:
  
  true if all bytes are valid characters in the alphabet or if the byte array is empty; false, otherwise.
- isInAlphabet
  public boolean isInAlphabet(String basen)
  
  Tests a given String to see if it contains only valid characters within the alphabet. The method treats whitespace and PAD as valid.
  
  Parameters:
  
  basen - String to test.
  
  Returns:
  
  true if all characters in the String are valid characters in the alphabet or if the String is empty; false, otherwise.
  
  See Also:
  
  isInAlphabet(byte[], boolean)
- isStrictDecoding
  
  public boolean isStrictDecoding()
  
  Tests whether decoding behavior is strict.
  Strict decoding rejects invalid trailing bits and, for Base32 and Base64, noncanonical input as described in this class.
  
  Returns:
  
  true if using strict decoding.
  
  Since:
  
  1.15

Class BaseNCodec

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class Object

Field Details

MIME_CHUNK_SIZE

PEM_CHUNK_SIZE

MASK_8BITS

PAD_DEFAULT

DECODING_POLICY_DEFAULT

PAD

pad

lineLength

Constructor Details

BaseNCodec

BaseNCodec

BaseNCodec

BaseNCodec

Method Details

getChunkSeparator

isWhiteSpace

containsAlphabetOrPad

decode

decode

decode

encode

encode

encode

encodeAsString

encodeToString

ensureBufferSize

getCodecPolicy

getDefaultBufferSize

getEncodedLength

isInAlphabet

isInAlphabet

isInAlphabet

isStrictDecoding