Flawed `InvariantsEq` safety proof for `Unalign` incorrectly assumes `try_deref` is total

Open Beginner friendly
#3,764 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
84/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
rust
Domain
documentation

Research direction

Read the InvariantsEq implementations and SAFETY comment at zerocopy/src/pointer/transmute.rs:396-403, then inspect Unalign::try_deref in zerocopy/src/wrappers.rs:202-211. Update the safety rationale to state the aligned coexistence precondition or the relevant layout properties, leaving the sound implementation unchanged.

Written by the indexing model from the issue text.

Description

Agent-discovered bug, and agent-authored writeup.

Summary

In zerocopy/src/pointer/transmute.rs, the InvariantsEq trait denotes that two types have identical safety invariants: specifically, that it is sound for safe code to operate on a &T and a &Self pointing to the same referent at the same time.

The // SAFETY: comment for the InvariantsEq<T> for Unalign<T> implementation (zerocopy/src/pointer/transmute.rs:396-403) justifies this contract as follows:

Given u: &Unalign<T>, it is already possible to obtain let t = u.try_deref().unwrap() because try_deref doesn't consume self, and thus it must be sound for these two references to exist at the same time.

However, Unalign::<T>::try_deref (zerocopy/src/wrappers.rs:202-211) is a partial function that checks alignment via inner.try_into_aligned() and returns Err(AlignmentError) when self is not aligned to align_of::<T>(). On a valid, unaligned &Unalign<T> reference (e.g., at offset 1 inside a #[repr(C, packed)] struct where align_of::<T>() > 1), u.try_deref().unwrap() panics rather than producing a &T.

The implementation itself is sound—no Undefined Behavior is reachable—because:

  1. The InvariantsEq contract only constrains referents where both &T and &Unalign<T> can validly exist at the same time, and the existence of a valid &T already implies the referent address is aligned to align_of::<T>() (in which case u.try_deref() does succeed).
  2. Structurally, Unalign<T> is a single-field #[repr(C, packed)] wrapper around T, so it has identical size, bit validity, and UnsafeCell byte ranges as T.
  3. Downstream pointer transmutations (Ptr::transmute) preserve the Unaligned alignment invariant state, requiring an explicit try_into_aligned() check before materializing &T.
Affected Files
  • zerocopy/src/pointer/transmute.rs
  • zerocopy/src/wrappers.rs

Suggested Fix

Update the // SAFETY: comment on unsafe impl<T> InvariantsEq<T> for Unalign<T> and unsafe impl<T> InvariantsEq<Unalign<T>> for T at zerocopy/src/pointer/transmute.rs:396-403 to note that the InvariantsEq precondition assumes a referent at which both &T and &Unalign<T> can coexist (which implies the referent is aligned for T, making u.try_deref().unwrap() succeed in that precondition domain), or justify the implementation directly from Unalign<T>'s #[repr(C, packed)] single-field layout having identical size, bit validity, and UnsafeCell coverage to T.

Dominant language
Rust
Stars
2.6k
Forks
194
Avg merge
18h 15m
Merged PRs (30d)
14

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from google/zerocopy

All issues in google/zerocopy

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.