base64-ng 0.7.0

no_std-first Base64 encoding and decoding with strict APIs and a security-heavy release process
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155

# SIMD Admission Policy

`base64-ng` is intentionally scalar-only in the `0.7.0` release. The crate uses
`#![deny(unsafe_code)]` and permits reviewed `allow(unsafe_code)` exceptions
only for the volatile wipe helper in `src/lib.rs` and the private `src/simd.rs`
boundary. The `simd` feature remains reserved until architecture-specific code
has enough evidence to justify enabling it.

This is a security decision, not a rejection of hardware acceleration. SIMD
must be added only when it can be isolated, tested, and reviewed without
weakening the scalar trust base.

## Current Status

- Default builds compile one audited unsafe volatile wipe helper; scalar
  encode/decode remains safe Rust.
- `scripts/validate-unsafe-boundary.sh` verifies that `allow(unsafe_code)` is
  confined to the volatile wipe helper and `src/simd.rs`.
- `docs/UNSAFE.md` inventories every current unsafe site and its invariants.
- The scalar implementation is the reference behavior.
- Encode and decode entry points already pass through an internal backend
  boundary, currently backed only by the scalar implementation.
- With the `simd` feature enabled, the private dispatch scaffold detects
  AVX-512 VBMI, AVX2, SSSE3/SSE4.1, NEON, and wasm `simd128` candidates but
  still activates only the scalar backend.
- AVX-512 VBMI detection is reporting-only until an implementation has scalar
  differential tests, fuzz coverage, and benchmark evidence. Detection requires
  the full planned feature bundle: `avx512f`, `avx512bw`, `avx512vl`, and
  `avx512vbmi`.
- An inactive AVX-512 fixed-block encode prototype exists behind the SIMD
  boundary and is tested against scalar output only when the full AVX-512
  Base64 feature bundle is available.
- Runtime backend identifiers expose their required CPU feature bundles through
  `runtime::Backend::required_cpu_features()`.
- Runtime backend reports include `candidate_required_cpu_features=[...]` in
  their stable key/value display output for audit logs.
- Runtime backend reports expose `snapshot()` for structured audit logging
  without parsing formatted strings.
- SSSE3/SSE4.1 detection is reporting-only until an implementation has scalar
  differential tests, fuzz coverage, and benchmark evidence.
- An inactive SSSE3/SSE4.1 fixed-block encode prototype exists behind the SIMD
  boundary and is tested against scalar output only when SSSE3/SSE4.1 is
  available.
- An inactive AVX2 fixed-block encode prototype exists behind the SIMD boundary
  and is tested against scalar output only when AVX2 is available.
- An inactive NEON fixed-block encode prototype exists behind the same boundary
  and is tested against scalar output only on NEON-capable ARM targets.
- wasm `simd128` detection is reporting-only when `wasm32` is compiled with
  `target-feature=+simd128`; no wasm accelerated backend is active.
- `runtime::backend_report()` reports the active backend, detected candidate,
  SIMD feature status, and scalar-only security posture.
- `runtime::require_backend_policy()` allows deployments to enforce scalar
  execution, disabled SIMD features, or no detected SIMD candidate.
- `BackendPolicy::HighAssuranceScalarOnly` combines scalar execution, disabled
  SIMD features, no detected SIMD candidate, and unsafe-boundary enforcement.
- Runtime backend, posture, and policy enums provide stable string identifiers
  for logs and release evidence.
- Runtime backend reports and policy failures format as stable key/value
  strings suitable for CI and audit logs.
- Unit tests compare dispatch behavior against the scalar reference for
  canonical inputs, malformed inputs, and undersized output buffers.
- The `simd` feature does not enable accelerated code yet.
- `v0.7` is scoped as a scalar-only evidence release. Candidate detection and
  inactive prototypes may be reported, but active SIMD dispatch is out of scope
  for that release.
- CI checks the reserved `simd` feature in `no_std` mode for x86_64, aarch64,
  FreeBSD, wasm32, and Cortex-M targets.
- Performance claims must be backed by local benchmark evidence, not roadmap
  language.

Run the same target check locally for every installed target:

```sh
scripts/check_targets.sh
```

Run a specific target:

```sh
scripts/check_targets.sh aarch64-unknown-linux-gnu
```

Compile-check the reserved SIMD feature bundles:

```sh
scripts/check_simd_feature_bundles.sh
```

This does not execute accelerated code. It proves the reserved AVX2,
AVX-512, SSSE3/SSE4.1, NEON, and wasm `simd128` feature-gated code still
compiles under `no_std` when the corresponding Rust targets are installed.

Capture local backend and prototype evidence:

```sh
scripts/check_backend_evidence.sh
```

This prints the runtime backend-report test and runs the gated SIMD prototype
scalar-equivalence tests with `--nocapture`, so local CPU evidence is easy to
copy into release notes or issue discussion.

## Required Before SIMD Code Lands

Any AVX2, NEON, AVX-512, wasm `simd128`, or runtime-dispatch implementation
must include:

- The dedicated `src/simd.rs` boundary for all architecture-specific code.
- Crate-level `deny(unsafe_code)` must continue to reject unsafe outside the
  volatile wipe helper and SIMD module.
- A local safety comment for every unsafe block.
- Deterministic differential tests against scalar encode/decode behavior.
- Fuzz differential coverage for strict and legacy-compatible inputs where
  applicable.
- Runtime dispatch tests that prove unsupported CPUs fall back to scalar.
- Miri coverage for scalar and dispatch-level code that Miri can execute.
- Architecture-specific CI evidence or documented local evidence for each
  enabled target.
- Benchmark evidence that reports hardware, OS, Rust version, command, and raw
  output.

## Admission Gate

`scripts/validate-simd-admission.sh` keeps SIMD dispatch scalar-only until the
admission evidence is deliberately updated. The gate currently requires:

- `ActiveBackend` to expose only the `Scalar` variant.
- `active_backend()` to return `ActiveBackend::Scalar`.
- No accelerated `ActiveBackend::Avx*`, `ActiveBackend::Neon`,
  `ActiveBackend::Sse*`, `ActiveBackend::Wasm*`, or generic SIMD dispatch
  variants in source.
- Documentation for benchmark evidence, release-note restrictions, and
  vector-register retention cleanup strategy to remain packaged.

When an accelerated backend is ready for admission, update this gate in the
same commit as the scalar differential tests, fuzz evidence, unsafe inventory,
benchmark evidence, and release notes.

## Dispatch Rules

- Scalar remains the fallback for every build.
- Candidate detection must not imply activation; a detected candidate may still
  execute scalar until the accelerated backend is admitted.
- Prototype functions may exercise target-feature and unsafe plumbing without
  being eligible for dispatch.
- Runtime CPU detection may be used only behind `std`.
- Compile-time target-feature paths must be explicit and documented.
- Unsupported CPU features must never panic at runtime.
- SIMD paths must preserve strict error indexes, canonical padding rejection,
  and output sizing behavior.

## Release Rule

Do not advertise SIMD acceleration in release notes until accelerated code is
actually enabled, tested, and measured for that release.