# Assembly Ownership Ledger

Last audited: 2026-06-23

rscrypto should own its assembly. Namespacing a third-party symbol is useful, but
it is not ownership. This ledger tracks every known assembly lineage so we can
replace vendored kernels deliberately instead of carrying inherited code by
accident.

## Ownership Criteria

An assembly file is rscrypto-owned when all of these are true:

- The algorithm, schedule, ABI, register allocation, and tail behavior were
  written for rscrypto or regenerated from rscrypto-owned source.
- The file has an SPDX header and provenance comment.
- The Rust wrapper documents the ABI, CPU-feature gate, aliasing rules, and
  secret/public timing boundary.
- Tests compare the assembly backend against the portable implementation or a
  published test-vector oracle.
- Any generated tables or generated assembly have a checked-in generator or a
  reproducible derivation note.

Code adapted from another project stays in the "external" bucket until it is
rewritten or regenerated from rscrypto-owned source. License compatibility is
necessary, not sufficient.

## Current Inventory

- 71 tracked `.s` / `.S` files under `src/`.
- 62 Rust files use `asm!`, `core::arch::asm!`, or `global_asm!`.
- 58 tracked assembly files are explicitly external-derived today.
- 6 tracked ML-KEM assembly files are explicitly marked `rscrypto-owned`.
- 7 tracked assembly files look first-party from local history but need explicit
  headers or stronger provenance comments.

## External-Derived Assembly To Replace

### s2n-bignum

These 40 files are adapted from s2n-bignum. They are namespaced for rscrypto,
but they are not rscrypto-owned yet.

- `src/auth/asm/rscrypto_bignum_mod_n256_aarch64_apple_darwin.s`
- `src/auth/asm/rscrypto_bignum_mod_n256_aarch64_unknown_linux.s`
- `src/auth/asm/rscrypto_bignum_mod_n256_x86_64_unknown_linux.S`
- `src/auth/asm/rscrypto_bignum_mod_n384_aarch64_apple_darwin.s`
- `src/auth/asm/rscrypto_bignum_mod_n384_aarch64_unknown_linux.s`
- `src/auth/asm/rscrypto_bignum_mod_n384_x86_64_unknown_linux.S`
- `src/auth/asm/rscrypto_bignum_modinv_aarch64_apple_darwin.s`
- `src/auth/asm/rscrypto_bignum_modinv_aarch64_unknown_linux.s`
- `src/auth/asm/rscrypto_bignum_modinv_x86_64_unknown_linux.S`
- `src/auth/asm/rscrypto_bignum_montinv_p384_aarch64_apple_darwin.s`
- `src/auth/asm/rscrypto_bignum_montinv_p384_aarch64_unknown_linux.s`
- `src/auth/asm/rscrypto_bignum_montinv_p384_x86_64_unknown_linux.S`
- `src/auth/asm/rscrypto_bignum_montmul_p384_aarch64_apple_darwin.s`
- `src/auth/asm/rscrypto_bignum_montmul_p384_aarch64_unknown_linux.s`
- `src/auth/asm/rscrypto_bignum_montmul_p384_alt_x86_64_unknown_linux.S`
- `src/auth/asm/rscrypto_bignum_montmul_p384_x86_64_unknown_linux.S`
- `src/auth/asm/rscrypto_bignum_montsqr_p384_aarch64_apple_darwin.s`
- `src/auth/asm/rscrypto_bignum_montsqr_p384_aarch64_unknown_linux.s`
- `src/auth/asm/rscrypto_bignum_montsqr_p384_alt_x86_64_unknown_linux.S`
- `src/auth/asm/rscrypto_bignum_montsqr_p384_x86_64_unknown_linux.S`
- `src/auth/asm/rscrypto_p256_scalarmulbase_alt_aarch64_apple_darwin.s`
- `src/auth/asm/rscrypto_p256_scalarmulbase_alt_aarch64_unknown_linux.s`
- `src/auth/asm/rscrypto_p256_scalarmulbase_alt_x86_64_unknown_linux.S`
- `src/auth/asm/rscrypto_p256_scalarmulbase_x86_64_unknown_linux.S`
- `src/auth/asm/rscrypto_p384_montjdouble_alt_aarch64_apple_darwin.s`
- `src/auth/asm/rscrypto_p384_montjdouble_alt_aarch64_unknown_linux.s`
- `src/auth/asm/rscrypto_p384_montjdouble_alt_x86_64_unknown_linux.S`
- `src/auth/asm/rscrypto_p384_montjmixadd_alt_aarch64_apple_darwin.s`
- `src/auth/asm/rscrypto_p384_montjmixadd_alt_aarch64_unknown_linux.s`
- `src/auth/asm/rscrypto_p384_montjmixadd_alt_x86_64_unknown_linux.S`
- `src/auth/asm/rscrypto_p384_montjscalarmul_alt_x86_64_unknown_linux.S`
- `src/auth/ed25519/asm/rscrypto_ed25519_aarch64_apple_darwin.s`
- `src/auth/ed25519/asm/rscrypto_ed25519_aarch64_unknown_linux.s`
- `src/auth/ed25519/asm/rscrypto_ed25519_scalarmulbase_aarch64_apple_darwin.s`
- `src/auth/ed25519/asm/rscrypto_ed25519_scalarmulbase_aarch64_unknown_linux.s`
- `src/auth/ed25519/asm/rscrypto_ed25519_scalarmulbase_alt_x86_64_unknown_linux.s`
- `src/auth/ed25519/asm/rscrypto_ed25519_scalarmulbase_x86_64_unknown_linux.s`
- `src/auth/x25519/asm/rscrypto_x25519_aarch64_apple_darwin.s`
- `src/auth/x25519/asm/rscrypto_x25519_aarch64_unknown_linux.s`
- `src/auth/x25519/asm/rscrypto_x25519_x86_64_linux.s`

Replacement target: rewrite fixed-base, field, scalar, and bignum kernels from
rscrypto's scalar field code and ABI needs. Do not bulk-port another bignum
project. If we keep any s2n-derived file temporarily, keep the SPDX and upstream
source path in the header.

### AWS-LC / BoringSSL / OpenSSL / Cloudflare

These 7 files are adapted from generated AWS-LC, BoringSSL, OpenSSL, or
Cloudflare assembly.

- `src/aead/chacha20poly1305/asm/rscrypto_chacha20_poly1305_aarch64_apple_darwin.s`
- `src/aead/chacha20poly1305/asm/rscrypto_chacha20_poly1305_aarch64_linux.s`
- `src/auth/asm/rscrypto_rsa_bignum_mont_aarch64_elf.s`
- `src/auth/asm/rscrypto_rsa_bignum_mont_apple.s`
- `src/auth/asm/rscrypto_rsa_x86_64_elf.S`
- `src/hashes/crypto/sha256/asm/rscrypto_sha256_aarch64_apple_darwin.s`
- `src/hashes/crypto/sha512/asm/rscrypto_sha512_aarch64_apple_darwin.s`

Replacement target: prefer direct rscrypto kernels for SHA-2, RSA Montgomery,
and ChaCha20-Poly1305. If the replacement is not worth owning in assembly,
delete the assembly path and keep the Rust intrinsics path.

### Upstream BLAKE3 x86_64

These 9 files are derived from upstream BLAKE3 x86_64 assembly with symbols
renamed and preprocessor conditionals removed.

- `src/hashes/crypto/blake3/x86_64/asm/rscrypto_blake3_avx2_x86-64_apple_darwin.s`
- `src/hashes/crypto/blake3/x86_64/asm/rscrypto_blake3_avx2_x86-64_unix_linux.s`
- `src/hashes/crypto/blake3/x86_64/asm/rscrypto_blake3_avx2_x86-64_windows_msvc.s`
- `src/hashes/crypto/blake3/x86_64/asm/rscrypto_blake3_avx512_x86-64_apple_darwin.s`
- `src/hashes/crypto/blake3/x86_64/asm/rscrypto_blake3_avx512_x86-64_unix_linux.s`
- `src/hashes/crypto/blake3/x86_64/asm/rscrypto_blake3_avx512_x86-64_windows_msvc.s`
- `src/hashes/crypto/blake3/x86_64/asm/rscrypto_blake3_sse41_x86-64_apple_darwin.s`
- `src/hashes/crypto/blake3/x86_64/asm/rscrypto_blake3_sse41_x86-64_unix_linux.s`
- `src/hashes/crypto/blake3/x86_64/asm/rscrypto_blake3_sse41_x86-64_windows_msvc.s`

Replacement target: either write rscrypto-owned x86_64 assembly, or delete
these files and rely on the Rust intrinsic backends. Keeping both upstream ASM
and intrinsic fallbacks is a maintenance tax unless benchmarks prove the ASM
path still earns its place.

### mlkem-native / NeonNTT / SLOTHY

These 2 files derive their butterfly schedule from mlkem-native / NeonNTT /
SLOTHY work. The final canonicalization epilogue is rscrypto-owned, but the
kernel is not fully rscrypto-owned.

- `src/auth/mlkem/asm/rscrypto_mlkem_ntt_aarch64_apple_darwin.s`
- `src/auth/mlkem/asm/rscrypto_mlkem_ntt_aarch64_linux.s`

Replacement target: regenerate the full forward NTT schedule from an rscrypto
generator or rewrite it manually from the FIPS 203 schedule. Until then, keep
the existing multi-license header and mlkem-native derivation note.

## Explicitly rscrypto-owned Assembly

These 6 files are currently marked `rscrypto-owned`.

- `src/auth/mlkem/asm/rscrypto_mlkem_basemul_aarch64_apple_darwin.s`
- `src/auth/mlkem/asm/rscrypto_mlkem_basemul_aarch64_linux.s`
- `src/auth/mlkem/asm/rscrypto_mlkem_inv_ntt_aarch64_apple_darwin.s`
- `src/auth/mlkem/asm/rscrypto_mlkem_inv_ntt_aarch64_linux.s`
- `src/auth/mlkem/asm/rscrypto_mlkem_rej_uniform_aarch64_apple_darwin.s`
- `src/auth/mlkem/asm/rscrypto_mlkem_rej_uniform_aarch64_linux.s`

Keep these on the owned path by preserving ABI comments, constant-time boundary
notes, backend equivalence tests, and diagnostic digests.

## First-party Candidates That Need Headers

These files look first-party from local history or registry comparison, but they
need explicit SPDX/provenance headers before we can treat them as cleanly owned.

- `src/aead/aes/aarch64/asm/rscrypto_aes_gcm_aarch64_apple_darwin.s`
- `src/aead/aes/x86_64/asm/rscrypto_aes_gcm_x86_64_linux.s`
- `src/auth/asm/rscrypto_rsa_aarch64_apple_darwin.s`
- `src/auth/asm/rscrypto_rsa_aarch64_linux_elf.s`
- `src/hashes/crypto/blake3/aarch64/asm/rscrypto_blake3_hash1_chunk_aarch64_apple_darwin.s`
- `src/hashes/crypto/blake3/aarch64/asm/rscrypto_blake3_hash1_chunk_aarch64_unix_linux.s`
- `src/hashes/crypto/keccak/aarch64_sve2_sha3.S`

Header target:

```text
// Copyright (c) 2026 rscrypto contributors
// SPDX-License-Identifier: Apache-2.0 OR MIT
//
// rscrypto-owned ...
```

Only use that header after confirming no external source was copied or adapted.
If any file was adapted, keep it in the external bucket and record the source.

## Adjacent Non-ASM Provenance

These are not tracked assembly files, but they matter for the same ownership
goal because they carry external algorithm or table lineage.

- `src/aead/aes_round.rs`: Hamburg vperm AES tables sourced from OpenSSL
  `vpaes-x86_64.pl`.
- `src/checksum/crc32/aarch64.rs`: EOR3 CRC32C and ISO-HDLC kernels ported from
  `fast-crc32`.
- `src/checksum/crc64/aarch64.rs`, `src/checksum/crc64/x86_64.rs`,
  `src/checksum/crc64/power.rs`, `src/checksum/crc64/s390x.rs`: CRC64 folding
  algorithm derived from Intel/TiKV folding.

Treat these as separate ownership work. Rewriting assembly while leaving
externally sourced tables or schedules undocumented does not solve provenance.

## Work Plan

1. Add SPDX/provenance headers to first-party candidates.
   Verify with `rg -n --glob '*.{s,S}' 'SPDX|rscrypto-owned|Adapted for rscrypto' src`.

2. Freeze every external-derived file with exact upstream source path and
   license in its header.
   Verify every external bucket above has source and license text in-file.

3. Replace the s2n-bignum public-key assembly first.
   Verify ECDSA, Ed25519, X25519, and RSA tests pass against portable/oracle
   paths after each replacement.

4. Decide whether upstream BLAKE3 x86 ASM is worth owning.
   Verify with benchmarks against the Rust intrinsic paths before rewriting or
   deleting it.

5. Regenerate or rewrite ML-KEM forward NTT.
   Verify ML-KEM ACVP, property tests, backend equivalence, and diagnostic
   digests.

6. Keep this ledger current.
   Verify any new `.s` / `.S` file appears in exactly one section before merge.
