Class Base45
- All Implemented Interfaces:
BinaryDecoder,BinaryEncoder,Decoder,Encoder
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 charactersalphabet[n % 45],alphabet[(n / 45) % 45],alphabet[n / 2025] - For a final single byte
b0:n = b0; output 2 charactersalphabet[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:
-
Nested Class Summary
Nested ClassesNested classes/interfaces inherited from class org.apache.commons.codec.binary.BaseNCodec
BaseNCodec.AbstractBuilder<T,B extends BaseNCodec.AbstractBuilder<T, B>>, BaseNCodec.Context -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final intThe number of characters in the Base45 alphabet.private static final intThe square of the Base45 alphabet size (45 * 45 = 2025), used during decoding.(package private) static final intNumber of Base45 characters in an encoded block (encoding 2 unencoded bytes).(package private) static final intNumber of unencoded bytes per full encoding block.(package private) static final byte[]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.(package private) static final byte[]Lookup table translating Base45 values (0–44) to their ASCII character equivalents.private static final intFields inherited from class org.apache.commons.codec.binary.BaseNCodec
CHUNK_SEPARATOR, decodeTable, DECODING_POLICY_DEFAULT, EMPTY_BYTE_ARRAY, encodeTable, EOF, lineLength, MASK_8BITS, MIME_CHUNK_SIZE, pad, PAD, PAD_DEFAULT, PEM_CHUNK_SIZE -
Constructor Summary
ConstructorsModifierConstructorDescriptionBase45()Constructs a Base45 codec using the default settings (strict decoding policy, the only supported policy).privateBase45(Base45.Builder builder) Constructs a Base45 codec from a builder. -
Method Summary
Modifier and TypeMethodDescriptionstatic Base45.Builderbuilder()Creates a newBase45.Builderfor configuring aBase45instance.private static byte[]calculateDecodeTable(byte[] encodeTable) Constructs the decode table matching the given encode table.(package private) voiddecode(byte[] input, int inPos, int inAvail, BaseNCodec.Context context) Decodes all of the provided data, starting atinPos, forinAvailbytes.(package private) voidencode(byte[] input, int inPos, int inAvail, BaseNCodec.Context context) Encodes all of the provided data, starting atinPos, forinAvailbytes.longgetEncodedLength(byte[] array) Gets the number of Base45-encoded characters needed to encode the given byte array, as specified by RFC 9285.booleanisInAlphabet(byte value) Tests whether or not thevalueis a valid Base45 alphabet character.booleanisInAlphabet(byte[] arrayOctet, boolean allowWhitespacePad) Tests a given byte array to see if it contains only valid characters within the alphabet.private static byte[]toDecodeTable(byte[] encodeTable) Gets the decode table that matches the given encode table.Methods inherited from class org.apache.commons.codec.binary.BaseNCodec
available, code, containsAlphabetOrPad, decode, decode, decode, encode, encode, encode, encodeAsString, encodeToString, ensureBufferSize, getChunkSeparator, getCodecPolicy, getDefaultBufferSize, hasData, isInAlphabet, isStrictDecoding, isWhiteSpace, readResults, toUnsignedBytes, validateCanonicalByte, validateCanonicalEnd
-
Field Details
-
BASE
private static final int BASEThe number of characters in the Base45 alphabet.- See Also:
-
BASE_SQUARED
private static final int BASE_SQUAREDThe square of the Base45 alphabet size (45 * 45 = 2025), used during decoding.- See Also:
-
BYTES_PER_ENCODED_BLOCK
static final int BYTES_PER_ENCODED_BLOCKNumber 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_BLOCKNumber of unencoded bytes per full encoding block.- See Also:
-
DECODE_TABLE
static final byte[] DECODE_TABLELookup 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_TABLELookup 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
Constructs a Base45 codec from a builder.- Parameters:
builder- The builder to configure this instance.
-
-
Method Details
-
builder
Creates a newBase45.Builderfor configuring aBase45instance.- 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
Decodes all of the provided data, starting atinPos, forinAvailbytes.This method must be called at least twice: once with the data to decode, and once with
inAvailset to-1to 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:
decodein classBaseNCodec- Parameters:
input- byte array of Base45-encoded character data to decode.inPos- Position to start reading data from.inAvail- Number of bytes available frominputfor decoding, or-1to 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
Encodes all of the provided data, starting atinPos, forinAvailbytes.This method must be called at least twice: once with the data to encode, and once with
inAvailset to-1to 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:
encodein classBaseNCodec- Parameters:
input- byte array of binary data to Base45-encode.inPos- Position to start reading data from.inAvail- Number of bytes available frominputfor encoding, or-1to 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), wherenis the number of unencoded bytes.- Overrides:
getEncodedLengthin classBaseNCodec- 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 thevalueis a valid Base45 alphabet character.- Specified by:
isInAlphabetin classBaseNCodec- Parameters:
value- The byte value to test.- Returns:
trueif the byte corresponds to a character in the Base45 alphabet (RFC 9285);falseotherwise.
-
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
BaseNCodecimplementation, the pad character is not considered valid, because Base45 (RFC 9285) has no padding.- Overrides:
isInAlphabetin classBaseNCodec- Parameters:
arrayOctet- byte array to test.allowWhitespacePad- iftrue, then whitespace is also allowed.- Returns:
trueif all bytes are valid characters in the alphabet or if the byte array is empty;false, otherwise.
-