Class Base32Codec

java.lang.Object
org.jwcarman.codec.transform.encoding.Base32Codec
All Implemented Interfaces:
Codec<byte[]>
public final class Base32Codec extends Object implements Codec<byte[]>
A byte-to-text-safe-byte transform using Base32: eight ASCII symbols per five bytes, over any alphabet of 32 symbols. Base32 is larger than Base64 but its standard alphabet has no lower-case letters and no symbols, which makes it safe for case-insensitive contexts — DNS labels, file names, and values a person will read aloud or type. It is the encoding used for TOTP secrets.

standard() and hex() are RFC 4648 §6 and §7: upper-case output with = padding. of(String) and of(String, char) take any 32-symbol alphabet — z-base-32, geohash, an alphabet of your own — with the same bit layout (RFC 4648 §3: input bytes most-significant bit first, five bits per symbol, the final partial symbol left-aligned with zero bits, and with padding the output padded to a whole group of eight).

Decoding is strict and canonical: it accepts exactly the strings encode(byte[]) can produce. A symbol outside the alphabet, a length or padding that does not correspond to whole input bytes, a pad symbol before the end, or non-zero trailing bits in the final symbol is rejected with InvalidPayloadException. Canonical decoding gives every value exactly one encoded form, so encoded strings can be compared, deduplicated and signed (RFC 4648 §12). Lower-case input is an opt-in: caseInsensitive(). aliasing(Map) accepts extra characters as named symbols; crockford() uses both, and zBase32() and geohash() are further strict presets.

Like Base64Codec, put it last in a chain. Instances are immutable and thread-safe.

  • Method Summary

    Modifier and Type
    Method
    Description
    Base32Codec
    aliasing(Map<Character, Character> aliases)
    The same codec, additionally reading each key of aliases as the alphabet symbol it names — Crockford's I, L → 1 and O → 0, for example.
    String
    alphabet()
    The alphabet, in value order.
    Base32Codec
    caseInsensitive()
    The same alphabet and padding, decoding without regard to letter case: a and A both read as whichever of them is in the alphabet.
    static Base32Codec
    crockford()
    Crockford's alphabet (0-9A-Z without I, L, O, U), the encoding of ULIDs: no padding, and decoding that folds case and reads I and L as 1 and O as 0.
    byte[]
    decode(byte[] bytes)
    Decodes bytes back into a value.
    byte[]
    encode(byte[] value)
    Encodes a value to bytes.
    static Base32Codec
    geohash()
    The geohash alphabet (0-9b-z without a, i, l, o): lower case, no padding, strict decoding.
    static Base32Codec
    hex()
    The "extended hex" alphabet (0-9A-V) with = padding, whose encoded form sorts in the same order as the bytes it encodes — useful for sortable keys.
    static Base32Codec
    of(String alphabet)
    A strict codec over alphabet with no padding.
    static Base32Codec
    of(String alphabet, char pad)
    A strict codec over alphabet, padding the output to a whole group of eight symbols with pad.
    static Base32Codec
    standard()
    The standard alphabet (A-Z2-7) with = padding, used by TOTP secrets and most Base32 consumers.
    static Base32Codec
    zBase32()
    z-base-32 (ybndrfg8ejkmcpqxot1uwisza345h769), the alphabet chosen for ease of handwriting and reading aloud, as used by Tahoe-LAFS and Phil Zimmermann's ZRTP: lower case, no padding, strict decoding.

    Methods inherited from class Object

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

    Methods inherited from interface Codec

    andThen, nullSafe, xmap

  • Method Details

    • standard

      public static Base32Codec standard()
      The standard alphabet (A-Z2-7) with = padding, used by TOTP secrets and most Base32 consumers. Decoding is strict: upper case only.
      Returns:
      a codec for RFC 4648 §6 Base32

    • hex

      public static Base32Codec hex()
      The "extended hex" alphabet (0-9A-V) with = padding, whose encoded form sorts in the same order as the bytes it encodes — useful for sortable keys. Decoding is strict: upper case only.
      Returns:
      a codec for RFC 4648 §7 base32hex

    • crockford

      public static Base32Codec crockford()
      Crockford's alphabet (0-9A-Z without I, L, O, U), the encoding of ULIDs: no padding, and decoding that folds case and reads I and L as 1 and O as 0. Crockford's optional check symbol and hyphens are not accepted.
      Returns:
      a codec for Crockford Base32

    • zBase32

      public static Base32Codec zBase32()
      z-base-32 (ybndrfg8ejkmcpqxot1uwisza345h769), the alphabet chosen for ease of handwriting and reading aloud, as used by Tahoe-LAFS and Phil Zimmermann's ZRTP: lower case, no padding, strict decoding.
      Returns:
      a codec for z-base-32

    • geohash

      public static Base32Codec geohash()
      The geohash alphabet (0-9b-z without a, i, l, o): lower case, no padding, strict decoding. Use caseInsensitive() to accept upper-case geohashes.
      Returns:
      a codec for the geohash alphabet

    • of

      public static Base32Codec of(String alphabet)
      A strict codec over alphabet with no padding.
      Parameters:
      alphabet - the 32 symbols in value order; distinct ASCII characters
      Returns:
      a strict, unpadded codec
      Throws:
      NullPointerException - if alphabet is null
      IllegalArgumentException - if the alphabet does not have exactly 32 symbols, or a symbol is not ASCII, or a symbol appears twice

    • of

      public static Base32Codec of(String alphabet, char pad)
      A strict codec over alphabet, padding the output to a whole group of eight symbols with pad.
      Parameters:
      alphabet - the 32 symbols in value order; distinct ASCII characters
      pad - the pad symbol, an ASCII character that is not in the alphabet
      Returns:
      a strict, padded codec
      Throws:
      NullPointerException - if alphabet is null
      IllegalArgumentException - if the alphabet does not have exactly 32 symbols, or a symbol is not ASCII, or a symbol appears twice, or the pad symbol is not ASCII or is in the alphabet

    • alphabet

      public String alphabet()
      The alphabet, in value order.
      Returns:
      the 32 symbols

    • caseInsensitive

      public Base32Codec caseInsensitive()
      The same alphabet and padding, decoding without regard to letter case: a and A both read as whichever of them is in the alphabet. Encoding is unchanged and still emits the alphabet's symbols exactly. The original codec is unaffected.
      Returns:
      a codec that folds case on decode
      Throws:
      IllegalArgumentException - if two alphabet symbols differ only by case, or the pad symbol differs from an alphabet symbol only by case, so folding would be ambiguous

    • aliasing

      public Base32Codec aliasing(Map<Character, Character> aliases)
      The same codec, additionally reading each key of aliases as the alphabet symbol it names — Crockford's I, L → 1 and O → 0, for example. Aliases are exact characters: to accept both cases of an alias, list both. Encoding is unchanged. The original codec is unaffected.
      Parameters:
      aliases - characters to accept on decode, each mapped to the alphabet symbol it stands for
      Returns:
      a codec that also accepts the aliases
      Throws:
      NullPointerException - if aliases is null
      IllegalArgumentException - if an alias is not ASCII, is the pad symbol, or is already accepted (an alphabet symbol, a folded case, or an earlier alias); or if a target is not an alphabet symbol

    • encode

      public byte[] encode(byte[] value)
      Description copied from interface: Codec
      Encodes a value to bytes.
      Specified by:
      encode in interface Codec<byte[]>
      Parameters:
      value - the value to encode
      Returns:
      the encoded bytes

    • decode

      public byte[] decode(byte[] bytes)
      Description copied from interface: Codec
      Decodes bytes back into a value.
      Specified by:
      decode in interface Codec<byte[]>
      Parameters:
      bytes - the bytes to decode
      Returns:
      the decoded value