Skip to content

io: add AsyncFd::register and deprecate AsyncFd::new - #8587

Merged
Darksonn merged 5 commits into
tokio-rs:tokio-1.51.xfrom
Darksonn:f01
Oct 10, 2026
Merged

Darksonn merged 5 commits into
tokio-rs:tokio-1.51.xfrom
Darksonn:f01

Conversation

@Darksonn

@Darksonn Darksonn commented Oct 3, 2026

Copy link
Copy Markdown
Member

Tokio's AsyncFd was added before the concept of I/O safety was stabilized, so for historical reasons it requires T: AsRawFd instead of T: AsFd. However, Tokio's IO driver tracks per-IO resource information in an allocated object, and the user data given to epoll is a pointer to said object. This means that if epoll returns a readiness event for an fd after its object is removed, that leads to use-after-free.

Unfortunately, this situation can happen if AsyncFd is misused in safe code. For example, if the underlying fd is closed while the AsyncFd exists. We recently merged #8540, which avoids the UAF in common cases, but it's not a perfect mitigation, and as seen in #8539 it's still possible to trigger UAF today.

There are only really two ways to fix this issue:

  1. Stop storing pointers in the epoll user data, and instead store a key into a hash map or similar data structure, so that UAF can be detected safely.
  2. Adopt I/O safety for AsyncFd.

This PR takes the second approach. Specifically, AsyncFd::new is deprecated, and a new, unsafe AsyncFd::register is added to replace it.

Note that AsyncFd::register has to be an unsafe constructor. It's not enough to just accept T: AsFd instead of T: AsRawFd because the AsFd trait does not promise that every call to as_fd() returns the same file descriptor.

I also considered the option of defining a new unsafe trait AsyncFdSafe with a safety requirement that every call to as_fd() returns the same file descriptor. However, that's not enough either because of AsyncFd::get_mut(), which lets the end-user mem::swap the I/O resource for another one. And we can't get rid of get_mut()-like methods on AsyncFd, because AsyncFd fundamentally relies on the user manually invoking read() and write() directly on the inner I/O resource.

Fixes: #8539

@Darksonn Darksonn added A-tokio Area: The main tokio crate M-io Module: tokio/io labels Oct 3, 2026
@Darksonn

Darksonn commented Oct 3, 2026 •

Copy link
Copy Markdown
Member Author

@ADD-SP ADD-SP left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: I prefer new2 instead of register. I know it looks ugly. However, there are some benefits:

  • new2 still follows the common naming pattern of constructor, less surprise.
  • Developers already using AsyncFd::new can quickly infer from the name AsyncFd::new2 that this is an (almost) drop-in replacement. Otherwise, developers might need a dozen or so seconds to ensure that it is (almost) a drop-in replacement.

@martin-g

martin-g commented Oct 4, 2026

Copy link
Copy Markdown
Member

Or 'newer' 😀

@ADD-SP

ADD-SP commented Oct 6, 2026

Copy link
Copy Markdown
Member

nit: I prefer new2 instead of register. I know it looks ugly. However, there are some benefits:

* `new2` still follows the common naming pattern of constructor, less surprise.

* Developers already using `AsyncFd::new` can quickly infer  from the name `AsyncFd::new2` that this is an (almost) drop-in replacement.  Otherwise, developers might need a dozen or so seconds to ensure that it is (almost) a drop-in replacement.

Haha, it looks like a bad idea based on the GitHub reaction. Anyway, not a blocker.

@Darksonn Darksonn added C-enhancement Category: A PR with an enhancement or bugfix. S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Oct 6, 2026
@Darksonn

Darksonn commented Oct 7, 2026 •

Copy link
Copy Markdown
Member Author

Any opinions on whether this is something we should backport to LTS?

Potentially backport the new methods, but not the #[deprecated] annotations?

@ADD-SP

ADD-SP commented Oct 7, 2026

Copy link
Copy Markdown
Member

Any opinions on whether this is something we should backport to LTS?

Potentially backport the new methods, but not the #[deprecated] annotations?

I'd skip the backport. LTS only takes patch releases, but new public methods and new deprecation lints are both minor changes (RFC 1105)

Since #8540 already mitigates the UB, and the full fix needs new API, so it would be better landing the deprecation annotations and new method in the next minor release.

@xtqqczze

xtqqczze commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

According to the bug patching policy, LTS releases are specifically intended to allow bug fixes in patch releases. From an outside perspective, backporting this seems justified: this is a soundness issue in an existing API rather than a new feature.

I understand the concern around adding #[deprecated] in a patch release, given the new warnings it can introduce. But if the API is considered unsound, it also seems useful to communicate that rather than leave it looking unchanged.

Since the new API provides the migration path, would it make sense to backport both the new API and the deprecation? That would let LTS users stay on the LTS line while getting both the fix and a clear indication that they should move away from the problematic API.

@Darksonn

Darksonn commented Oct 7, 2026

Copy link
Copy Markdown
Member Author

I guess part of the concern is that if we file a soundness advisory to RUSTSEC, we have to mark which versions have fixed the soundness issue, and I don't want the LTS branches to be listed as affected by an advisory.

@xtqqczze

xtqqczze commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Given these constraints, and the fact that anyone could file a RUSTSEC advisory, it doesn't seem like we can really treat the backport as optional. It seems like we need to backport both the new API and the deprecation so the LTS branches can be considered fixed.

@ADD-SP

ADD-SP commented Oct 7, 2026 •

Copy link
Copy Markdown
Member

Strictly speaking, As long as the AsyncFd::new is still there, tokio should still be considered as affected until removing it completely. So in the RUSTSEC advisory, tokio 1.x.y should be flagged affected.

Previously, we have released a breaking change without deprecation cycle and major release (#3345) as the the impact is minimal at that time. However, now, it is pretty hard for us to do similar thing (remove AsyncFd::new in tokio 1.x).

@Darksonn

Darksonn commented Oct 7, 2026

Copy link
Copy Markdown
Member Author

We're not going to remove ::new and I absolutely will mark any version with new deprecated as fixed.

@ADD-SP

This comment was marked as outdated.

@ADD-SP

ADD-SP commented Oct 7, 2026

Copy link
Copy Markdown
Member

Just to be clear, I'm not trying to block it, just raising the concerns I had. It is fine for me to backport deprecation annotation plus new APIs.

@xtqqczze

xtqqczze commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Strictly speaking, As long as the AsyncFd::new is still there, tokio should still be considered as affected until removing it completely. So in the RUSTSEC advisory, tokio 1.x.y should be flagged affected.

@djc Would you consider a version to still be affected by a soundness advisory if the unsound API remains available but is deprecated?

@djc

djc commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Strictly speaking, As long as the AsyncFd::new is still there, tokio should still be considered as affected until removing it completely. So in the RUSTSEC advisory, tokio 1.x.y should be flagged affected.

@djc Would you consider a version to still be affected by a soundness advisory if the unsound API remains available but is deprecated?

No, I agree with @Darksonn's judgement here (as usual).

(For good measure, I might also mark it as #[doc(hidden)] maybe.)

Tokio's `AsyncFd` was added before the concept of I/O safety was
stabilized, so for historical reasons it requires `T: AsRawFd` instead
of `T: AsFd`. However, Tokio's IO driver tracks per-IO resource
information in an allocated object, and the user data given to epoll is
a pointer to said object. This means that if epoll returns a readiness
event for an fd after its object is removed, that leads to
use-after-free.

Unfortunately, this situation can happen if `AsyncFd` is misused in safe
code. For example, if the underlying fd is closed while the `AsyncFd`
exists. We recently merged tokio-rs#8540, which avoids the UAF in common cases,
but it's not a perfect mitigation, and as seen in tokio-rs#8539 it's still
possible to trigger UAF today.

There are only really two ways to fix this issue:

1. Stop storing pointers in the epoll user data, and instead store a key
   into a hash map or similar data structure, so that UAF can be
   detected safely.
2. Adopt I/O safety for `AsyncFd`.

This PR takes the second approach. Specifically, `AsyncFd::new` is
deprecated, and a new, unsafe `AsyncFd::register` is added to replace
it.

Note that `AsyncFd::register` has to be an unsafe constructor. It's not
enough to just accept `T: AsFd` instead of `T: AsRawFd` because the
`AsFd` trait does not promise that every call to `as_fd()` returns the
*same* file descriptor.

I also considered the option of defining a new `unsafe trait
AsyncFdSafe` with a safety requirement that every call to `as_fd()`
returns the same file descriptor. However, that's not enough either
because of `AsyncFd::get_mut()`, which lets the end-user `mem::swap` the
I/O resource for another one. And we can't get rid of `get_mut()`-like
methods on `AsyncFd`, because `AsyncFd` fundamentally relies on the user
manually invoking `read()` and `write()` directly on the inner I/O
resource.

Fixes: tokio-rs#8539
@Darksonn
Darksonn changed the base branch from master to tokio-1.51.x October 8, 2026 14:54
Comment thread tokio/src/io/async_fd.rs Resolved
@Darksonn

Copy link
Copy Markdown
Member Author

I think we do want to mark them #[doc(hidden)], but in a follow-up PR so that there's at least one release where people will see them when they go looking for why they got a deprecation warning.

@xtqqczze

Copy link
Copy Markdown
Contributor

the AsFd trait does not promise that every call to as_fd() returns the same file descriptor.

In that case, the documentation for std::os::fd::AsFd should be updated to clarify this point, as it is currently documented as "a trait to borrow the file descriptor from an underlying object".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-tokio Area: The main tokio crate C-enhancement Category: A PR with an enhancement or bugfix. M-io Module: tokio/io

Projects

None yet

Development

Successfully merging this pull request may close these issues.

AsyncFd accepting AsRawFd violates I/O safety and can lead to UB

7 participants