Crate base64_ng 

base64-ng is a no_std-first Base64 encoder and decoder.

This initial release provides strict scalar RFC 4648-style behavior and caller-owned output buffers. Future SIMD fast paths, including AVX, NEON, and wasm simd128 candidates, will be required to match this scalar module byte-for-byte.

Examples

Encode and decode with caller-owned buffers:

use base64_ng::{STANDARD, checked_encoded_len};

let input = b"hello";
const ENCODED_CAPACITY: usize = match checked_encoded_len(5, true) {
    Some(len) => len,
    None => panic!("encoded length overflow"),
};
let mut encoded = [0u8; ENCODED_CAPACITY];
let encoded_len = STANDARD.encode_slice(input, &mut encoded).unwrap();
assert_eq!(&encoded[..encoded_len], b"aGVsbG8=");

let mut decoded = [0u8; 5];
let decoded_len = STANDARD.decode_slice(&encoded, &mut decoded).unwrap();
assert_eq!(&decoded[..decoded_len], input);

Use the URL-safe no-padding engine:

use base64_ng::URL_SAFE_NO_PAD;

let mut encoded = [0u8; 3];
let encoded_len = URL_SAFE_NO_PAD.encode_slice(b"\xfb\xff", &mut encoded).unwrap();
assert_eq!(&encoded[..encoded_len], b"-_8");

Sensitive Decode Policy

The default engines such as STANDARD and URL_SAFE_NO_PAD are strict scalar encoders/decoders with localized diagnostics. They are not constant-time token validators or key-material decoders: strict decode and validation may branch or return early based on malformed input. Use ct::STANDARD, ct::URL_SAFE_NO_PAD, or Engine::ct_decoder for secret-bearing payloads where decode timing posture matters more than exact error indexes.

Recommended heap-owning pattern for secret-bearing standard Base64:

use base64_ng::ct;

let expected = b"session-key";
let decoded = ct::STANDARD.decode_secret(b"c2Vzc2lvbi1rZXk=").unwrap();

assert!(decoded.constant_time_eq_public_len(expected));

For shared-memory, enclave-adjacent, HSM-style, or multi-principal deployments where even transient writes into caller-owned output are unacceptable, use ct::CtEngine::decode_slice_staged_clear_tail with a private staging buffer.

Zeroization Caveat

Cleanup APIs and redacted buffers use dependency-free best-effort wiping: byte-wise volatile zero writes followed by an architecture-gated inline assembly barrier plus a hardware store-ordering fence where stable Rust supports it, and a compiler fence on all targets. This resists common compiler dead-store elimination and orders the issued zero stores on native supported architectures, but it is not a formal zeroization guarantee and cannot clear historical copies, registers, cache lines, write buffers, swap, hibernation images, core dumps, cold-boot remanence, or OS-level memory snapshots. High-assurance applications should apply their own approved zeroization policy to caller-owned buffers at the protocol boundary. Architectures without a native wipe barrier fail closed by default unless allow-compiler-fence-only-wipe is enabled after platform review. On wasm32, the wipe barrier is compiler-fence-only and cannot constrain downstream wasm runtime JITs. For that reason, wasm32 builds fail closed by default. Enable allow-wasm32-best-effort-wipe only when the deployment explicitly accepts compiler-fence-only cleanup and applies its own memory strategy.

Modules

ct

Constant-time-oriented scalar decoding APIs.

runtime

Runtime backend reporting for security-sensitive deployments.

stream

Streaming Base64 wrappers for std::io.

Macros

define_alphabet

Defines a custom Alphabet from a 64-byte string literal.

Structs

Bcrypt

The bcrypt Base64 alphabet.

Crypt

The Unix crypt(3) Base64 alphabet.

DecodedBuffer

Stack-backed decoded Base64 output.

EncodedBuffer

Stack-backed encoded Base64 output.

Engine

A zero-sized Base64 engine parameterized by alphabet and padding policy.

ExposedDecodedArray

Owned stack array extracted from DecodedBuffer.

ExposedEncodedArray

Owned stack array extracted from EncodedBuffer.

ExposedSecretString

Owned secret UTF-8 text extracted from SecretBuffer.

ExposedSecretVec

Owned secret bytes extracted from SecretBuffer.

LineWrap

Base64 line wrapping policy.

Profile

A named Base64 profile with an engine and optional strict line wrapping.

SecretBuffer

Owned sensitive bytes with redacted formatting and drop-time cleanup.

Standard

The RFC 4648 standard Base64 alphabet.

UrlSafe

The RFC 4648 URL-safe Base64 alphabet.

Enums

AlphabetError

Alphabet validation error.

DecodeError

Decoding error.

EncodeError

Encoding error.

LineEnding

Line ending used by wrapped Base64 output.

Constants

BCRYPT

bcrypt-style no-padding Base64 profile.

BCRYPT_NO_PAD

bcrypt-style Base64 engine without padding.

CRYPT

Unix crypt(3)-style no-padding Base64 profile.

CRYPT_NO_PAD

Unix crypt(3)-style Base64 engine without padding.

MIME

MIME Base64 profile: standard alphabet, padding, 76-column CRLF wrapping.

PEM

PEM Base64 profile: standard alphabet, padding, 64-column LF wrapping.

PEM_CRLF

PEM Base64 profile with CRLF line endings.

STANDARD

Standard Base64 engine with padding.

STANDARD_NO_PAD

Standard Base64 engine without padding.

URL_SAFE

URL-safe Base64 engine with padding.

URL_SAFE_NO_PAD

URL-safe Base64 engine without padding.

Traits

Alphabet

A Base64 alphabet.

Functions

checked_encoded_len

Returns the encoded length, or None if it would overflow usize.

checked_wrapped_encoded_len

Returns the encoded length after line wrapping, or None on overflow or invalid line wrapping.

constant_time_eq

Compares two byte slices with a public length-mismatch branch.

constant_time_eq_fixed_width

Compares two fixed-width byte arrays without a length-mismatch branch.

decode

Decodes strict standard padded Base64 into an owned byte vector.

decode_alphabet_byte

Decodes one byte by scanning a caller-provided alphabet table.

decoded_capacity

Returns the maximum decoded length for an encoded input length.

decoded_len

Returns the exact decoded length implied by input length and padding.

encode

Encodes input as strict standard padded Base64.

encoded_len

Returns the encoded length for an input length and padding policy.

validate_alphabet

Validates a 64-byte Base64 alphabet table.

wrapped_encoded_len

Returns the encoded length after applying a line wrapping policy.