Baid64 Specification

Overview

Baid64 (Base64 Aided Identities) is an enhanced Base64 encoding scheme designed for secure, human-verifiable identity encoding. It extends standard Base64 with Human Readable Identifiers (HRI), cryptographic check sums, mnemonic representations, and optional formatting features to create a robust encoding system suitable for identity management and secure data representation.

Core Components

1. Custom Alphabet

Baid64 uses a modified Base64 alphabet optimized for URL-safety and human readability:

ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_~

Key differences from standard Base64:

• Uses _ instead of +
• Uses ~ instead of /
• No padding characters (=)

2. Data Structure

A complete Baid64 encoded string consists of the following components:

[HRI:]<base64-data>[#mnemonic]

Where:

• HRI (optional): Human Readable Identifier prefix (max 16 characters)
• base64-data: The encoded payload, optionally with embedded checksum
• mnemonic (optional): Human-readable checksum representation

Encoding Process

Step 1: Checksum Calculation

The checksum is computed using a double SHA-256 hash:

fn check(hri: &str, payload: [u8; LEN]) -> [u8; 4] {
    let key = SHA256(hri.as_bytes())
    let mut sha = SHA256_with_prefix(key)
    sha.update(payload)
    let result = sha.finalize()
    return [result[0], result[1], result[1], result[2]]  // Note: result[1] is duplicated
}

Important: The checksum intentionally duplicates result[1] in positions 1 and 2 of the output array.

Step 2: Base64 Encoding

The payload is encoded using the custom Baid64 alphabet:

1. If EMBED_CHECKSUM is true, append the 4-byte checksum to the payload
2. Encode the combined data using the Baid64 alphabet
3. No padding is added

Step 3: Optional Chunking

When chunking is enabled, the encoded string is formatted as:

• First chunk: 8 characters (configurable via CHUNK_FIRST)
• Subsequent chunks: 7 characters each (configurable via CHUNK_LEN)
• Chunks are separated by hyphens (-)

Example: ABCDEFGH-ijklmno-pqrstuv-wxyz012

Step 4: Format Assembly

The final format follows this pattern:

1. Prefix (if enabled): Add HRI: before the encoded data
2. Encoded Data: The base64-encoded payload (possibly chunked)
3. Suffix (if enabled): Add #mnemonic after the encoded data

Decoding Process

Step 1: Parse Components

1. Extract HRI if present (text before :)
2. Extract mnemonic if present (text after #)
3. Remove any chunking hyphens from the base64 data

Step 2: Base64 Decode

Decode the cleaned base64 string using the Baid64 alphabet to retrieve:

• The original payload (first LEN bytes)
• Optional embedded checksum (last 4 bytes if present)

Step 3: Checksum Verification

1. Calculate the expected checksum using the extracted HRI and payload
2. Compare with:
   • The embedded checksum (if present in the data)
   • The mnemonic-derived checksum (if mnemonic suffix present)
3. Fail if checksums don't match

Step 4: Payload Reconstruction

Return the validated payload bytes.

Configuration Options

The DisplayBaid64 trait provides several configuration constants:

Constant	Type	Description
HRI	&'static str	Human Readable Identifier string
CHUNKING	bool	Enable/disable chunking of output
PREFIX	bool	Include HRI prefix in output
EMBED_CHECKSUM	bool	Embed checksum in base64 data
MNEMONIC	bool	Include mnemonic suffix
CHUNK_FIRST	usize	Length of first chunk (default: 8)
CHUNK_LEN	usize	Length of subsequent chunks (default: 7)

Security Features

1. Checksum Protection

• Uses SHA-256 based checksum with HRI as salt
• Provides 32 bits of error detection
• Checksum can be verified via embedded data or mnemonic

2. Human Verification

• Mnemonic representation allows verbal checksum confirmation
• Chunking improves readability and reduces transcription errors
• HRI provides context and prevents cross-domain confusion

3. Constraints

• Minimum payload length: 4 bytes (ID_MIN_LEN)
• Maximum HRI length: 16 bytes (HRI_MAX_LEN)
• Fixed checksum size: 4 bytes

Error Handling

The system defines several error types:

Error Type	Description
InvalidHri	HRI doesn't match expected value
InvalidLen	Payload length doesn't match expected size
InvalidChecksum	Checksum verification failed
InvalidMnemonicLen	Mnemonic doesn't decode to 4 bytes
InvalidMnemonic	Mnemonic decode error
Base64	Base64 decode error
InvalidPayload	Payload validation failed

Usage Examples

Encoding

let data = TestBaid64 { payload: [1; 32] };
let encoded = data.to_baid64_string();
// Result: "testHRI:AQEBAQEB...#word1-word2-word3"

Decoding

let decoded = TestBaid64::from_baid64_str("testHRI:AQEBAQEB...#word1-word2-word3")?;

Display Variants

Using Rust's format specifiers to control output:

format!("{}", display)   // Default: with prefix and suffix
format!("{:-}", display) // Suppress prefix
format!("{:#}", display) // Suppress suffix

Implementation Notes

1. Checksum Duplication: The checksum algorithm intentionally duplicates sha[1] to create a 4-byte checksum from 3 unique bytes.

2. Mnemonic Integration: The mnemonic encoding is handled by an external mnemonic crate, converting the 4-byte checksum into memorable words.

3. Flexibility: The trait-based design allows different types to customize encoding parameters while maintaining consistent behavior.

4. Round-trip Safety: The encoding and decoding processes are designed to be perfectly reversible when all components are preserved.

Dependencies

• base64: Core Base64 encoding/decoding
• sha2: SHA-256 hashing for checksums
• mnemonic: Checksum to mnemonic word conversion
• amplify: Utility macros and derive support