RFC: Store registry tokens in the OS credential store by default#3981
RFC: Store registry tokens in the OS credential store by default#3981quinnjr wants to merge 2 commits into
Conversation
Cargo writes registry tokens to a plaintext credentials.toml by default. Secure credential providers have existed since 1.74 but are opt-in, so the default install remains the vulnerable one. Propose a single cargo:keyring built-in provider (backed by the keyring crate: Keychain, wincred, Secret Service) as the default, with migration of existing plaintext tokens on any credential read including cargo publish, and file fallback for headless/CI.
| # Rationale and alternatives | ||
| [rationale-and-alternatives]: #rationale-and-alternatives | ||
|
|
||
| The obvious alternative is the status quo: the secure providers exist, just turn them on yourself. But a security measure that requires discovering a config key does not protect the default install, and the default install is the threat model here. Defaults matter precisely because most users never change them, and that cuts both ways. Right now it cuts toward plaintext. | ||
|
|
||
| Migrating only on `cargo login` would be simpler, but it leaves every existing user in plaintext indefinitely, since a working token means there's no reason to ever run `login` again. Publish-time migration is what actually moves the installed base. | ||
|
|
||
| The Rust Maintainers could also keep the three separate per-platform providers and just change the default list per platform. That works, but it's three implementations to keep behaviorally in sync where one crate already does the job, and it leaves the BSDs out. |
There was a problem hiding this comment.
Another alternative could be to print a warning/notice when cargo publish (or another subcommand that requires registry authentication) is used interactively with a credentials.toml, prompting users to migrate manually (with the default for new cargo logins using the OS credential store). This wouldn't help much for users who publish infrequently, though.
To aid manual migration, maybe something like cargo login --bikeshed-migrate-credentials-to-keyring could be added that doesn't (re)login but just does the migration from credentials.toml to the OS key store.
There was a problem hiding this comment.
I think a manual migration command would be useful whatever we do here, and also for testing.
There was a problem hiding this comment.
I would agree for testing but I don't agree for the full practice.
Too many people, in my opinion, are going to just never do the migration if it's allowed to be manual. The purpose of the RFC is a forced stance on moving to a safety first approach to benefit users who are less savey about proper security procedures.
There was a problem hiding this comment.
To be clear, I think people should be able to manually migrate before they publish.
(In addition to automatic migration on publish.)
ehuss
added
the
T-cargo
| # Prior art | ||
| [prior-art]: #prior-art | ||
|
|
||
| Cargo's own credential-process RFC ([RFC 2730](https://rust-lang.github.io/rfcs/2730-cargo-token-from-process.html)) and the 1.74 stabilization laid all the groundwork here. This RFC is really just about the default. Outside Rust: `docker-credential-helpers`, `gh auth`, and Python's `keyring` package all made the same move, and their experience (including the headless-fallback problem) is directly applicable. |
There was a problem hiding this comment.
You're absolutely right, The other languages and Tools Migrations would be extremely helpful in understanding where the pitfalls are. What did they do? What worked? What didn't? Where can I read more?
Are there other tools that did different migrations or made different decisions? If so what decisions did they do and why?
| # Drawbacks | ||
| [drawbacks]: #drawbacks | ||
|
|
||
| Keychain access can prompt the user, which is surprising the first time it happens mid-script, though the env-var and file fallbacks mean scripted environments never hit this in practice. Migrating during `publish` makes that first prompt more likely to appear in the middle of a workflow the user thinks of as non-interactive, which is why the notice needs to be loud about what just happened. It also adds the `keyring` crate (and its platform dependencies) to Cargo's dependency tree, which is real supply-chain surface for a security-sensitive code path and would need the usual vetting. |
There was a problem hiding this comment.
Should there be a timeout for the initial transfer to the keychain, in case the user is running non-interactively, but with a GUI/terminal keychain prompt enabled?
Without a timeout, the build process will appear to freeze, and if the user can't see the reason, it will look like a bug. For example, the prompt could appear on a different (virtual/invisible) screen or terminal.
Similar unexpected prompts have led to denial of service issues, although this one isn't remotely triggerable.
| # Rationale and alternatives | ||
| [rationale-and-alternatives]: #rationale-and-alternatives | ||
|
|
||
| The obvious alternative is the status quo: the secure providers exist, just turn them on yourself. But a security measure that requires discovering a config key does not protect the default install, and the default install is the threat model here. Defaults matter precisely because most users never change them, and that cuts both ways. Right now it cuts toward plaintext. | ||
|
|
||
| Migrating only on `cargo login` would be simpler, but it leaves every existing user in plaintext indefinitely, since a working token means there's no reason to ever run `login` again. Publish-time migration is what actually moves the installed base. | ||
|
|
||
| The Rust Maintainers could also keep the three separate per-platform providers and just change the default list per platform. That works, but it's three implementations to keep behaviorally in sync where one crate already does the job, and it leaves the BSDs out. |
There was a problem hiding this comment.
I think a manual migration command would be useful whatever we do here, and also for testing.
| The existing three per-platform providers stay for a deprecation period so nobody's explicit config breaks, but they'd eventually become aliases for `cargo:keyring`. | ||
|
|
||
| # Drawbacks | ||
| [drawbacks]: #drawbacks |
There was a problem hiding this comment.
Another possible drawback is that the file no longer exists in the filesystem (or at least, it's not in the same place). This has multiple drawbacks:
- for backup/migration, if a user has carefully configured their system to backup or transfer everything they need, and they switch to a different device, the credential may be lost on the old machine
- for shared filesystems, the credential will only be on one machine
- for shared credential stores, the credential could be exposed to unexpected users
Since credentials can be re-created via GitHub, the first two issues seem manageable.
Are there any precautions we could take for the third issue?
There was a problem hiding this comment.
Actually, only crates.io credentials can be re-created via GitHub.
if this change applies to other registry credentials, then moving those credentials into personal keychains could potentially violate corporate asset or security policies.
There was a problem hiding this comment.
if the corporate registry mandates use of plaintext tokens they can specify it in the config:
# .cargo/config.toml
[registries.example]
index = 'https://example.com/index'
credential-provider = ['cargo:token']also i don't think that a threat model that - (1) saving valuable corporate asset (the registry login token) into ~/.cargo/credentials.toml on employee's personal computer is fine but (2) being placed on their personal keychain is bad - make any sense at all. Either the corporate issue company computers so there's no "personal" keychain in the first place, or that the employee is totally trusted with the token so placing it anywhere secure is ok
There was a problem hiding this comment.
I don't think we need to worry about corporate access policies being an issue.
Prior art (Github CLI, pip/uv opt-in, etc) have already made the change and there isn't much covered engineering-news wise about lashing back from a corporate policy standpoint.
In my 5 last years, moves to secured credentials via company-owned password vaults and mandating things like 2FA, Passkeys on personal devices, etc, has been the norm, not the outlier.
joshtriplett
added
the
I-cargo-nominated
| # Reference-level explanation | ||
| [reference-level-explanation]: #reference-level-explanation | ||
|
|
||
| Rather than maintaining three separate built-in providers, Cargo's default provider would be a single `cargo:keyring` provider built on the `keyring` crate, which already abstracts over the macOS Security Framework, Windows Credential Manager, and Secret Service (with a kernel keyutils fallback on Linux, and Secret Service coverage on FreeBSD and OpenBSD). The default provider list becomes `["cargo:keyring", "cargo:token"]`: try the keyring, fall back to the file. |
There was a problem hiding this comment.
The cargo team rarely specifies exactly what dependencies we're going to use. I suspect we will be more comfortable merging this RFC if it directly specified the semantics; justifying that those semantics are possible to implement by referencing your recommended implementation.
Something like:
This RFC Described adding a combined Cross-platform built in provider under a common alias like
cargo:keyring. This would have the semantics of using The system correct built in provider on any system. This can be implemented by wrapping the existing providers, or building a new provider based on thekeyringcrate.
If we do take your advice and use the keyring crate. We will also need to have a deep discussion about what infrastructure supports the ongoing maintenance of that crate. Who is on call for any security problems found? Will they still be around and available in three years or five years?
7 participants
This RFC proposes making Cargo store registry tokens in the operating system's credential store (Keychain, Credential Manager, Secret Service) by default instead of plaintext
credentials.toml, using a singlecargo:keyringbuilt-in provider backed by thekeyringcrate.Key points:
["cargo:keyring", "cargo:token"]— keyring first, plaintext file as fallback so headless/CI environments are unaffected.cargo login,cargo publish,cargo yank,cargo owner), not just on re-login, so the installed base actually moves.CARGO_REGISTRY_TOKENand--tokenkeep precedence and are never migrated.Rendered