README
¶
base64
-- import "github.com/go-i2p/common/base64"
Package base64 implements I2P-specific base64 encoding and decoding utilities.
This package provides base64 functionality tailored for the I2P (Invisible Internet Project) network, implementing a modified RFC 4648 base64 alphabet that ensures compatibility with I2P protocols and addressing schemes. The key modifications replace problematic characters: "/" becomes "~" to avoid filesystem conflicts, and "+" becomes "-" for URL-safe encoding without percent-encoding requirements.
The package is essential for handling I2P destination addresses, router identifiers, cryptographic key material, and binary data serialization throughout the I2P ecosystem. All encoding operations maintain standard base64 semantics while using the I2P-specific character set.
Usage patterns:
- Encoding binary data for I2P network transmission
- Generating .b64.i2p destination addresses
- Converting cryptographic keys to string representation
- Serializing router information and network database entries
The implementation emphasizes performance and thread safety, providing reusable encoder instances that can be safely used across concurrent operations without synchronization overhead.
Package base64 constants
Package base64 utilities and encoding instances
Usage
const I2PEncodeAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-~"
I2PEncodeAlphabet defines the I2P-specific base64 character set used throughout the network. This alphabet follows RFC 4648 standard base64 encoding with two critical modifications: - "/" is replaced with "~" to avoid filesystem path conflicts - "+" is replaced with "-" to ensure URL-safe encoding without percent-encoding The alphabet maintains the standard ordering: A-Z (0-25), a-z (26-51), 0-9 (52-61), - (62), ~ (63). This encoding is essential for I2P destination addresses, router identifiers, and network data structures. Example usage: Used in .b64.i2p addresses and binary data serialization across I2P protocols.
var I2PEncoding *b64.Encoding = b64.NewEncoding(I2PEncodeAlphabet)
I2PEncoding provides the standard base64 encoder/decoder instance for all I2P components. This encoding instance is pre-configured with the I2P-specific alphabet and optimizes performance by reusing the same encoder across multiple operations. It handles the complex character mapping required for I2P network compatibility while maintaining standard base64 semantics. The instance is thread-safe and can be used concurrently across goroutines. Example: Used internally by EncodeToString and DecodeString for consistent encoding behavior.
func DecodeString
func DecodeString(str string) ([]byte, error)
DecodeString converts I2P-compatible base64 strings back to their original binary form. This function reverses the encoding process, taking base64 strings that use I2P's alphabet and converting them back to the original byte data. It validates input characters against the I2P alphabet and handles standard base64 padding requirements. Returns an error if the input contains invalid characters or malformed padding. Example: DecodeString("SGVsbG8=") returns []byte{72, 101, 108, 108, 111}, nil (Hello decoded)
func EncodeToString
func EncodeToString(data []byte) string
EncodeToString converts arbitrary binary data to I2P-compatible base64 string representation. This function takes raw byte data and produces a human-readable string using I2P's modified base64 alphabet. The output is compatible with I2P destination addresses, router identifiers, and other network protocol elements that require base64 encoding. The encoding process applies standard base64 padding rules with '=' characters as needed. Example: EncodeToString([]byte{72, 101, 108, 108, 111}) returns "SGVsbG8=" (Hello in I2P base64)
base64
github.com/go-i2p/common/base64
Documentation
¶
Overview ¶
Package base64 implements I2P-specific base64 encoding and decoding utilities.
This package provides base64 functionality tailored for the I2P (Invisible Internet Project) network, implementing a modified RFC 4648 base64 alphabet that ensures compatibility with I2P protocols and addressing schemes. The key modifications replace problematic characters: "/" becomes "~" to avoid filesystem conflicts, and "+" becomes "-" for URL-safe encoding without percent-encoding requirements.
The package is essential for handling I2P destination addresses, router identifiers, cryptographic key material, and binary data serialization throughout the I2P ecosystem. All encoding operations maintain standard base64 semantics while using the I2P-specific character set.
Usage patterns:
- Encoding binary data for I2P network transmission
- Generating .b64.i2p destination addresses
- Converting cryptographic keys to string representation
- Serializing router information and network database entries
The implementation emphasizes performance and thread safety, providing reusable encoder instances that can be safely used across concurrent operations without synchronization overhead.
Package base64 constants ¶
Package base64 error definitions ¶
Package base64 utilities for encoding and decoding
Index ¶
- Constants
- Variables
- func DecodeString(str string) ([]byte, error)
- func DecodeStringNoPadding(str string) ([]byte, error)
- func DecodeStringSafe(str string) ([]byte, error)
- func DecodeStringSafeNoPadding(str string) ([]byte, error)
- func DecodeStringStrict(str string) ([]byte, error)
- func EncodeToString(data []byte) string
- func EncodeToStringNoPadding(data []byte) string
- func EncodeToStringSafe(data []byte) (string, error)
- func EncodeToStringSafeNoPadding(data []byte) (string, error)
Constants ¶
const I2PEncodeAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-~"
I2PEncodeAlphabet defines the I2P-specific base64 character set used throughout the network. This alphabet follows RFC 4648 standard base64 encoding with two critical modifications: - "/" is replaced with "~" to avoid filesystem path conflicts - "+" is replaced with "-" to ensure URL-safe encoding without percent-encoding The alphabet maintains the standard ordering: A-Z (0-25), a-z (26-51), 0-9 (52-61), - (62), ~ (63). This encoding is essential for I2P destination addresses, router identifiers, and network data structures. Example usage: Used in .b64.i2p addresses and binary data serialization across I2P protocols.
const MAX_DECODE_SIZE = ((MAX_ENCODE_SIZE + 2) / 3) * 4
MAX_DECODE_SIZE defines the maximum length of a base64 string accepted by DecodeStringSafe. This is derived from MAX_ENCODE_SIZE to ensure decoded output cannot exceed the encode limit.
const MAX_ENCODE_SIZE = 10 * 1024 * 1024 // 10 MB
MAX_ENCODE_SIZE defines the maximum number of bytes that can be base64 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 ¶
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") // ErrEmptyString is returned when attempting to decode an empty string. // Empty strings cannot be meaningfully decoded and likely indicate a programming error. ErrEmptyString = errors.New("cannot decode empty string") // ErrStringTooLarge is returned when a string exceeds MAX_DECODE_SIZE. // This prevents excessive memory allocation and potential DoS attacks during decoding. ErrStringTooLarge = errors.New("string exceeds maximum decodable size") // ErrContainsNewline is returned by DecodeStringStrict when the input contains // embedded \r or \n characters. The Java I2P reference implementation (since 0.9.14) // rejects whitespace in base64 strings. ErrContainsNewline = errors.New("base64 string contains embedded newline") )
var I2PEncoding *b64.Encoding = b64.NewEncoding(I2PEncodeAlphabet)
I2PEncoding provides the standard base64 encoder/decoder instance for all I2P components. This encoding instance is pre-configured with the I2P-specific alphabet and optimizes performance by reusing the same encoder across multiple operations. It handles the complex character mapping required for I2P network compatibility while maintaining standard base64 semantics. The instance is thread-safe and can be used concurrently across goroutines.
var I2PEncodingNoPadding *b64.Encoding = b64.NewEncoding(I2PEncodeAlphabet).WithPadding(b64.NoPadding)
I2PEncodingNoPadding provides a base64 encoder/decoder without padding characters. The Java I2P reference implementation (since 0.9.14) accepts base64 without trailing '=' padding. This encoding instance enables interoperability by encoding and decoding unpadded base64 strings. Use this for data whose byte length is not divisible by 3, such as Ed25519 destinations (391 bytes → 522 base64 chars, no padding).
Functions ¶
func DecodeString ¶
DecodeString converts I2P-compatible base64 strings back to their original binary form. This function reverses the encoding process, taking base64 strings that use I2P's alphabet and converting them back to the original byte data. It validates input characters against the I2P alphabet and handles standard base64 padding requirements.
COMPATIBILITY NOTE: This function is LENIENT — Go's encoding/base64 silently strips \r and \n characters before decoding, which diverges from the Java I2P reference implementation (since 0.9.14) which rejects such whitespace. For strict interoperability with Java I2P and i2pd, use DecodeStringStrict instead. Choose DecodeString only if you are certain your input source has already validated against embedded newlines.
Returns an error if the input contains invalid characters or malformed padding. Example: DecodeString("SGVsbG8=") returns []byte{72, 101, 108, 108, 111}, nil (Hello decoded)
func DecodeStringNoPadding ¶ added in v0.1.5
DecodeStringNoPadding decodes an unpadded I2P base64 string back to binary data. This accepts base64 strings without trailing '=' padding, matching the Java I2P reference implementation's leniency (since 0.9.14).
func DecodeStringSafe ¶ added in v0.1.5
DecodeStringSafe converts I2P-compatible base64 strings back to binary with input validation. Unlike DecodeString, this function validates the input string length to prevent excessive memory allocation and potential DoS attacks. Use this function when decoding untrusted or network-provided data. Returns an error if the string is empty or exceeds MAX_DECODE_SIZE. Example: DecodeStringSafe("SGVsbG8=") returns []byte{72, 101, 108, 108, 111}, nil
func DecodeStringSafeNoPadding ¶ added in v0.1.5
DecodeStringSafeNoPadding decodes an unpadded I2P base64 string with input validation. This combines the unpadded decoding of DecodeStringNoPadding with the size validation of DecodeStringSafe. Use for decoding untrusted unpadded base64 from I2P peers. Returns an error if the string is empty or exceeds MAX_DECODE_SIZE.
func DecodeStringStrict ¶ added in v0.1.5
DecodeStringStrict converts I2P-compatible base64 strings back to binary, rejecting embedded newlines (\r, \n). The Java I2P reference implementation (since 0.9.14) rejects whitespace in base64 strings. Use this function when strict interoperability with the Java implementation is required.
func EncodeToString ¶
EncodeToString converts arbitrary binary data to I2P-compatible base64 string representation. This function takes raw byte data and produces a human-readable string using I2P's modified base64 alphabet. The output is compatible with I2P destination addresses, router identifiers, and other network protocol elements that require base64 encoding. The encoding process applies standard base64 padding rules with '=' characters as needed.
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 "SGVsbG8=" (Hello in I2P base64)
func EncodeToStringNoPadding ¶ added in v0.1.5
EncodeToStringNoPadding encodes binary data to an unpadded I2P base64 string. The Java I2P reference implementation (since 0.9.14) accepts base64 without trailing '=' padding. This function produces unpadded output for interoperability.
Note: EncodeToStringNoPadding(nil) and EncodeToStringNoPadding([]byte{}) both return "" without error. Use EncodeToStringSafeNoPadding for input validation.
func EncodeToStringSafe ¶ added in v0.1.0
EncodeToStringSafe encodes binary data to a base64 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 "SGVsbG8=", nil
func EncodeToStringSafeNoPadding ¶ added in v0.1.5
EncodeToStringSafeNoPadding encodes binary data to an unpadded I2P base64 string with input validation. This combines the unpadded encoding of EncodeToStringNoPadding with the size validation of EncodeToStringSafe. Returns an error if data is empty or exceeds MAX_ENCODE_SIZE.
Types ¶
This section is empty.
Source Files