Class Base45

java.lang.Object
org.apache.commons.codec.binary.BaseNCodec
org.apache.commons.codec.binary.Base45
All Implemented Interfaces:
BinaryDecoder, BinaryEncoder, Decoder, Encoder

public class Base45 extends BaseNCodec
Provides Base45 encoding and decoding as defined by RFC 9285.

Base45 is designed for efficient encoding of binary data in environments where a subset of ASCII characters is available, specifically 45 characters chosen from the QR code alphanumeric mode character set. Base45 is used in European Union Digital COVID Certificates (EUDCC) and similar applications.

The Base45 alphabet consists of 45 characters:

 Value Encoding  Value Encoding  Value Encoding  Value Encoding
    0 0           12 C           24 O           36 Space
    1 1           13 D           25 P           37 $
    2 2           14 E           26 Q           38 %
    3 3           15 F           27 R           39 *
    4 4           16 G           28 S           40 +
    5 5           17 H           29 T           41 -
    6 6           18 I           30 U           42 .
    7 7           19 J           31 V           43 /
    8 8           20 K           32 W           44 :
    9 9           21 L           33 X
   10 A           22 M           34 Y
   11 B           23 N           35 Z
 

Encoding

Input bytes are grouped in pairs (2 bytes). Each pair is encoded as 3 Base45 characters. A single remaining byte is encoded as 2 Base45 characters. There is no padding.

  • For each 2-byte pair (b0, b1): n = b0 * 256 + b1; output 3 characters alphabet[n % 45], alphabet[(n / 45) % 45], alphabet[n / 2025]
  • For a final single byte b0: n = b0; output 2 characters alphabet[n % 45], alphabet[n / 45]

Decoding

Input characters are grouped in triples (3 characters). Each triple decodes to 2 bytes. A pair of trailing characters decodes to 1 byte. An input whose length modulo 3 equals 1 is invalid.

This class is thread-safe.

To create an instance, use the default constructor or the builder:

 Base45 codec = new Base45();

 // Or, use the builder to customize the encode table:
 Base45 custom = Base45.builder().setEncodeTable(...).get();
 
Since:
1.23.0
See Also:
  • Field Details

    • BASE

      private static final int BASE
      The number of characters in the Base45 alphabet.
      See Also:
    • BASE_SQUARED

      private static final int BASE_SQUARED
      The square of the Base45 alphabet size (45 * 45 = 2025), used during decoding.
      See Also:
    • BYTES_PER_ENCODED_BLOCK

      static final int BYTES_PER_ENCODED_BLOCK
      Number of Base45 characters in an encoded block (encoding 2 unencoded bytes).
      See Also:
    • TAIL_ENCODED_BLOCK

      private static final int TAIL_ENCODED_BLOCK
      See Also:
    • BYTES_PER_UNENCODED_BLOCK

      static final int BYTES_PER_UNENCODED_BLOCK
      Number of unencoded bytes per full encoding block.
      See Also:
    • DECODE_TABLE

      static final byte[] DECODE_TABLE
      Lookup table translating ASCII character values (0–127) to their Base45 alphabet index (0–44), or -1 if the character is not in the Base45 alphabet.
    • ENCODE_TABLE

      static final byte[] ENCODE_TABLE
      Lookup table translating Base45 values (0–44) to their ASCII character equivalents.

      As specified in RFC 9285: 0-9, A-Z, Space, $, %, *, +, -, ., /, :

  • Constructor Details

    • Base45

      public Base45()
      Constructs a Base45 codec using the default settings (strict decoding policy, the only supported policy).
    • Base45

      private Base45(Base45.Builder builder)
      Constructs a Base45 codec from a builder.
      Parameters:
      builder - The builder to configure this instance.
  • Method Details

    • builder

      public static Base45.Builder builder()
      Creates a new Base45.Builder for configuring a Base45 instance.
      Returns:
      A new Base45.Builder.
    • calculateDecodeTable

      private static byte[] calculateDecodeTable(byte[] encodeTable)
      Constructs the decode table matching the given encode table.
      Parameters:
      encodeTable - The encode table.
      Returns:
      A new decode table.
      Throws:
      IllegalArgumentException - Thrown if the encode table does not contain exactly 45 unique entries.
    • toDecodeTable

      private static byte[] toDecodeTable(byte[] encodeTable)
      Gets the decode table that matches the given encode table.
      Parameters:
      encodeTable - The encode table used to determine the decode lookup table.
      Returns:
      The matching decode table.
    • decode

      void decode(byte[] input, int inPos, int inAvail, BaseNCodec.Context context)
      Decodes all of the provided data, starting at inPos, for inAvail bytes.

      This method must be called at least twice: once with the data to decode, and once with inAvail set to -1 to notify the decoder that EOF has been reached.

      Input characters not in the Base45 alphabet, including CR, LF, and TAB, cause an IllegalArgumentException. Space ' ' is part of the Base45 alphabet and is decoded as data.

      Specified by:
      decode in class BaseNCodec
      Parameters:
      input - byte array of Base45-encoded character data to decode.
      inPos - Position to start reading data from.
      inAvail - Number of bytes available from input for decoding, or -1 to signal EOF.
      context - The context to be used.
      Throws:
      IllegalArgumentException - Thrown if the input contains an invalid character, if the encoded length modulo 3 equals 1, or if an encoded triple decodes to a value exceeding 65535, or if a trailing 2-character sequence decodes to a value greater than 255.
    • encode

      void encode(byte[] input, int inPos, int inAvail, BaseNCodec.Context context)
      Encodes all of the provided data, starting at inPos, for inAvail bytes.

      This method must be called at least twice: once with the data to encode, and once with inAvail set to -1 to notify the encoder that EOF has been reached.

      Each pair of input bytes is encoded to 3 Base45 characters. A final single byte is encoded as 2 Base45 characters. No padding is used.

      Specified by:
      encode in class BaseNCodec
      Parameters:
      input - byte array of binary data to Base45-encode.
      inPos - Position to start reading data from.
      inAvail - Number of bytes available from input for encoding, or -1 to signal EOF.
      context - The context to be used.
    • getEncodedLength

      public long getEncodedLength(byte[] array)
      Gets the number of Base45-encoded characters needed to encode the given byte array, as specified by RFC 9285.

      The formula is: (n / 2) * 3 + (n % 2 != 0 ? 2 : 0), where n is the number of unencoded bytes.

      Overrides:
      getEncodedLength in class BaseNCodec
      Parameters:
      array - The byte array to encode (used only for its length).
      Returns:
      The number of Base45 characters that would be produced by encoding array.
    • isInAlphabet

      public boolean isInAlphabet(byte value)
      Tests whether or not the value is a valid Base45 alphabet character.
      Specified by:
      isInAlphabet in class BaseNCodec
      Parameters:
      value - The byte value to test.
      Returns:
      true if the byte corresponds to a character in the Base45 alphabet (RFC 9285); 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 as valid.

      Unlike the BaseNCodec implementation, the pad character is not considered valid, because Base45 (RFC 9285) has no padding.

      Overrides:
      isInAlphabet in class BaseNCodec
      Parameters:
      arrayOctet - byte array to test.
      allowWhitespacePad - if true, then whitespace is also allowed.
      Returns:
      true if all bytes are valid characters in the alphabet or if the byte array is empty; false, otherwise.