base32

package
v0.1.59999 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 8, 2026 License: MIT Imports: 6 Imported by: 3

README

base32

-- import "github.com/go-i2p/common/base32"

base32.svg

Package base32 implements utilities for encoding and decoding text using I2P's alphabet.

This package provides I2P-specific base32 encoding/decoding functionality using RFC 3548 with lowercase characters as specified by the I2P protocol. The implementation supports encoding binary data to human-readable strings for I2P destinations, router identifiers, and other network components that require base32 representation.

Key features: - I2P-compatible base32 alphabet using RFC 3548 lowercase (a-z, 2-7) - Consistent lowercase encoding for .b32.i2p domain compatibility - Error handling for invalid input data during decoding operations - High-performance encoding/decoding suitable for network operations

Common usage patterns:

encoded := base32.EncodeToString(binaryData)
decoded, err := base32.DecodeString(encodedString)

Package base32 implements utilities for encoding and decoding text using I2P's

alphabet

Package base32 implements utilities for encoding and decoding text using I2P's

alphabet

Usage

const I2PEncodeAlphabet = "abcdefghijklmnopqrstuvwxyz234567"

I2PEncodeAlphabet defines the base32 character set used throughout the I2P network. This alphabet follows RFC 3548 specifications but uses lowercase letters for consistency with I2P addressing conventions and .b32.i2p domain format requirements. The characters 0, 1, 8, and 9 are not part of the base32 standard alphabet (RFC 3548 uses only a-z and 2-7), which inherently avoids ambiguity with similar-looking characters.

var I2PEncoding *b32.Encoding = b32.NewEncoding(I2PEncodeAlphabet)

I2PEncoding provides the standard base32 encoder/decoder used across I2P components. This encoding instance is configured with the I2P-specific alphabet and is used for generating destination addresses, router identifiers, and other base32-encoded data within the I2P ecosystem. It ensures consistent encoding/decoding behavior.

func DecodeString
func DecodeString(data string) ([]byte, error)

DecodeString decodes a base32 string back to binary data using I2P's encoding alphabet. It converts I2P-compatible base32 strings back to their original byte representation. Returns an error if the input contains invalid base32 characters or padding. Example: DecodeString("jbswy3dp") returns []byte{72, 101, 108, 108, 111}, nil

func EncodeToString
func EncodeToString(data []byte) string

EncodeToString encodes binary data to a base32 string using I2P's encoding alphabet. It converts arbitrary byte data into a human-readable base32 string representation using the I2P-specific lowercase alphabet defined in RFC 3548. Example: EncodeToString([]byte{72, 101, 108, 108, 111}) returns "jbswy3dp"

base32

github.com/go-i2p/common/base32

go-i2p template file

Documentation

Overview

Package base32 implements utilities for encoding and decoding text using I2P's alphabet.

This package provides I2P-specific base32 encoding/decoding functionality using RFC 3548 with lowercase characters as specified by the I2P protocol. The implementation supports encoding binary data to human-readable strings for I2P destinations, router identifiers, and other network components that require base32 representation.

Key features: - I2P-compatible base32 alphabet using RFC 3548 lowercase (a-z, 2-7) - Consistent lowercase encoding for .b32.i2p domain compatibility - Error handling for invalid input data during decoding operations - High-performance encoding/decoding suitable for network operations

Common usage patterns: 

encoded := base32.EncodeToString(binaryData)
decoded, err := base32.DecodeString(encodedString)

Package base32 implements utilities for encoding and decoding text using I2P's alphabet

Package base32 error definitions

Package base32 implements utilities for encoding and decoding text using I2P's alphabet

Package base32 implements utilities for encoding and decoding text using I2P's alphabet

Index

Constants

View Source 
const (
	// FlagTwoByteSigTypes indicates that signature types use 2 bytes each
	// instead of the default 1 byte. Per I2P spec notes: "Don't expect
	// 2-byte sigtypes to ever happen, we're only up to 13."
	FlagTwoByteSigTypes byte = 0x01

	// FlagSecretRequired indicates a secret is needed to decrypt the
	// encrypted leaseset.
	FlagSecretRequired byte = 0x02

	// FlagPerClientAuth indicates per-client authentication (client
	// private key) is required.
	FlagPerClientAuth byte = 0x04

	// B32Suffix is the standard I2P base32 address suffix.
	B32Suffix = ".b32.i2p"

	// StandardB32Chars is the character count of a standard (non-extended)
	// base32 address: 52 chars encoding a 32-byte SHA-256 hash.
	StandardB32Chars = 52
)

Extended base32 address constants, per the I2P naming spec (0.9.40+). See: https://geti2p.net/spec/b32encrypted

View Source 
const I2PEncodeAlphabet = "abcdefghijklmnopqrstuvwxyz234567"

I2PEncodeAlphabet defines the base32 character set used throughout the I2P network. This is the standard RFC 3548/4648 base32 alphabet in lowercase form. The lowercase variant is required for I2P .b32.i2p address compatibility. The base32 standard inherently uses only a-z and 2-7 (26+6=32 symbols).

View Source 
const MAX_DECODE_SIZE = (MAX_ENCODE_SIZE*8 + 4) / 5 // ~16 MB of base32 text

MAX_DECODE_SIZE defines the maximum length of a base32 string that can be decoded in a single operation. This is the base32-encoded expansion of MAX_ENCODE_SIZE (ceil(10MB * 8/5)). For I2P .b32.i2p addresses, the expected input is 52 characters; this limit provides ample headroom while preventing memory exhaustion from untrusted input.

View Source 
const MAX_ENCODE_SIZE = 10 * 1024 * 1024 // 10 MB

MAX_ENCODE_SIZE defines the maximum number of bytes that can be base32 encoded in a single operation. This limit prevents excessive memory allocation and ensures reasonable processing times. The limit of 10MB is sufficient for all I2P protocol needs including router infos, destinations, and lease sets, while preventing potential DoS through memory exhaustion.

Variables

View Source 
var (
	// ErrEmptyData is returned when attempting to encode empty data.
	// Empty data cannot be meaningfully encoded and likely indicates a programming error.
	ErrEmptyData = errors.New("cannot encode empty data")

	// ErrDataTooLarge is returned when data exceeds MAX_ENCODE_SIZE.
	// This prevents excessive memory allocation and potential DoS attacks.
	ErrDataTooLarge = errors.New("data exceeds maximum encodable size")

	// ErrInputTooLarge is returned when a base32 string to decode exceeds MAX_DECODE_SIZE.
	// This prevents excessive memory allocation when decoding untrusted input.
	ErrInputTooLarge = errors.New("base32 input string exceeds maximum decodable size")

	// ErrInvalidSuffix is returned when a hostname does not end with ".b32.i2p".
	ErrInvalidSuffix = errors.New("hostname must end with .b32.i2p")

	// ErrNotExtended is returned when attempting to decode a standard-length
	// base32 address (52 chars) as an extended address.
	ErrNotExtended = errors.New("address is standard length, not an extended address")

	// ErrAddressTooShort is returned when decoded address data is too short
	// to contain the required extended address header fields.
	ErrAddressTooShort = errors.New("decoded address data too short for extended format")

	// ErrEmptyPublicKey is returned when an extended address has no public key bytes.
	ErrEmptyPublicKey = errors.New("public key must not be empty")

	// ErrInvalidFlags is returned when reserved flag bits (3–7) are non-zero.
	ErrInvalidFlags = errors.New("reserved flag bits must be zero")

	// ErrKeyTooShort is returned when the public key is too short to produce
	// an extended address distinguishable from a standard 52-char address.
	// Extended addresses require >32 bytes of encoded data (>52 base32 chars).
	ErrKeyTooShort = errors.New("public key too short for a valid extended address")
)
View Source 
var I2PEncoding *b32.Encoding = b32.NewEncoding(I2PEncodeAlphabet)

I2PEncoding provides the standard base32 encoder/decoder used across I2P components. This encoding instance is configured with the I2P-specific alphabet and is used for generating destination addresses, router identifiers, and other base32-encoded data within the I2P ecosystem. It ensures consistent encoding/decoding behavior.

View Source 
var I2PEncodingNoPadding *b32.Encoding = b32.NewEncoding(I2PEncodeAlphabet).WithPadding(b32.NoPadding)

I2PEncodingNoPadding provides a base32 encoder/decoder without padding characters. I2P base32 addresses (.b32.i2p) use unpadded base32 encoding: a 32-byte SHA-256 hash encodes to exactly 52 characters with no trailing '=' padding. Use this encoding for I2P address compatibility.

Functions

func DecodeString 

func DecodeString(data string) ([]byte, error)

DecodeString decodes a base32 string back to binary data using I2P's encoding alphabet. It converts I2P-compatible base32 strings back to their original byte representation. Returns an error if the input contains invalid base32 characters or padding. Example: DecodeString("jbswy3dp") returns []byte{72, 101, 108, 108, 111}, nil

func DecodeStringNoPadding added in v0.1.5 

func DecodeStringNoPadding(data string) ([]byte, error)

DecodeStringNoPadding decodes an unpadded base32 string back to binary data. This accepts the standard I2P .b32.i2p address format (52 unpadded characters for a 32-byte hash).

func DecodeStringSafe added in v0.1.5 

func DecodeStringSafe(data string) ([]byte, error)

DecodeStringSafe decodes a base32 string back to binary data with input validation. Unlike DecodeString, this function validates the input string length to prevent excessive memory allocation when processing untrusted data (e.g., user-supplied .b32.i2p addresses from the network). Returns an error if the input is empty or exceeds MAX_DECODE_SIZE.

func DecodeStringSafeNoPadding added in v0.1.5 

func DecodeStringSafeNoPadding(data string) ([]byte, error)

DecodeStringSafeNoPadding decodes an unpadded base32 string with input validation. This combines the unpadded decoding of DecodeStringNoPadding with the size validation of DecodeStringSafe. Use for decoding untrusted .b32.i2p addresses.

func EncodeExtendedAddress added in v0.1.5 

func EncodeExtendedAddress(addr *ExtendedAddress) (string, error)

EncodeExtendedAddress constructs an extended base32 .b32.i2p hostname from the given address components, following the I2P naming specification.

Returns the full hostname (e.g., "{56 chars}.b32.i2p") or an error.

func EncodeToString 

func EncodeToString(data []byte) string

EncodeToString encodes binary data to a base32 string using I2P's encoding alphabet. It converts arbitrary byte data into a human-readable base32 string representation using the I2P-specific lowercase alphabet defined in RFC 3548.

Note: EncodeToString(nil) and EncodeToString([]byte{}) both return "" without error. These two cases are indistinguishable in the output. Use EncodeToStringSafe for input validation that rejects nil and empty data.

Example: EncodeToString([]byte{72, 101, 108, 108, 111}) returns "jbswy3dp"

func EncodeToStringNoPadding added in v0.1.5 

func EncodeToStringNoPadding(data []byte) string

EncodeToStringNoPadding encodes binary data to an unpadded base32 string using I2P's encoding alphabet. This is the standard format for I2P .b32.i2p addresses: a 32-byte SHA-256 hash encodes to exactly 52 characters with no trailing '=' padding.

func EncodeToStringSafe added in v0.1.0 

func EncodeToStringSafe(data []byte) (string, error)

EncodeToStringSafe encodes binary data to a base32 string with input validation. Unlike EncodeToString, this function validates the input data size to prevent excessive memory allocation and potential DoS attacks. Use this function when encoding untrusted or user-provided data. Returns an error if data is empty or exceeds MAX_ENCODE_SIZE. Example: EncodeToStringSafe([]byte{72, 101, 108, 108, 111}) returns "jbswy3dp", nil

func EncodeToStringSafeNoPadding added in v0.1.5 

func EncodeToStringSafeNoPadding(data []byte) (string, error)

EncodeToStringSafeNoPadding encodes binary data to an unpadded base32 string with input validation. This combines the unpadded encoding of EncodeToStringNoPadding with the size validation of EncodeToStringSafe. This is the recommended function for generating I2P .b32.i2p addresses from untrusted or user-provided data, as it validates input size and produces the standard unpadded 52-character format for 32-byte SHA-256 hashes. Returns an error if data is empty or exceeds MAX_ENCODE_SIZE.

func IsExtendedAddress added in v0.1.5 

func IsExtendedAddress(hostname string) bool

IsExtendedAddress returns true if the hostname appears to be an extended base32 address (more than 52 characters before the .b32.i2p suffix).

Types

type ExtendedAddress added in v0.1.5 

type ExtendedAddress struct {
	// PubKeySigType is the signature type of the destination's public key.
	// Common value: 7 (EdDSA_SHA512_Ed25519).
	PubKeySigType uint16

	// BlindedSigType is the signature type used for the blinded key.
	// Common value: 11 (RedDSA_SHA512_Ed25519).
	BlindedSigType uint16

	// PublicKey is the raw public key bytes. Length is determined by the
	// signature type (e.g., 32 bytes for Ed25519).
	PublicKey []byte

	// SecretRequired indicates a secret is needed to decrypt the
	// encrypted leaseset.
	SecretRequired bool

	// PerClientAuth indicates per-client authentication (client private
	// key) is required.
	PerClientAuth bool
}

ExtendedAddress represents an I2P extended base32 address for encrypted leasesets, as defined in the I2P naming specification (0.9.40+).

Extended addresses encode the destination's public key along with signature type metadata, enabling clients to fetch and decrypt encrypted leasesets without requiring a full destination from an address book.

Standard base32 addresses are 52 characters (32-byte SHA-256 hash). Extended addresses are 56+ characters and contain the public key directly.

func DecodeExtendedAddress added in v0.1.5 

func DecodeExtendedAddress(hostname string) (*ExtendedAddress, error)

DecodeExtendedAddress decodes a .b32.i2p hostname string into its constituent extended address components.

Returns ErrNotExtended if the address is standard length (52 chars). Returns ErrInvalidSuffix if the hostname does not end with ".b32.i2p".

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.