Crate base64_ng 

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

The core API provides strict RFC 4648-style behavior, caller-owned output buffers, and an audited scalar fallback. The 1.2.x line admits selected SIMD encode acceleration while keeping decode on the scalar foundation. Any accelerated backend must match the scalar module byte-for-byte and pass the documented admission evidence before dispatch can select it.

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, and strict DecodeError values can include input-derived bytes and indexes. Do not log strict decode errors verbatim for secret-bearing input; log DecodeError::kind instead. Use ct::STANDARD, crate::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. CT behavior is best-effort and build-profile specific. Link-Time Optimization can change generated code shape across crate boundaries, so high-assurance deployments must rerun the dudect and generated-assembly evidence scripts for their exact compiler, target, feature set, and release profile before treating CT decode as acceptable.

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.

DecodeErrorKind

Redacted decoding error class.

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.

clear_bytes

Clears caller-owned bytes with this crate’s best-effort cleanup primitive.

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.

encode_infallible

Encodes input as strict standard padded Base64.

encoded_len

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

secure_wipe

Best-effort dependency-free wipe for caller-owned byte slices.

validate_alphabet

Validates a 64-byte Base64 alphabet table.

wrapped_encoded_len

Returns the encoded length after applying a line wrapping policy.