Cargo mTLS registry authentication #3907

matthague · 2026-01-17T03:24:34Z

This is an RFC aimed at allowing Cargo to present client certificates when forming HTTP connections and support mutual TLS authentication with registries.

It is aimed at forming consensus around the discussion in rust-lang/cargo#10641.

Rendered

Add Git to previous art

bjorn3 · 2026-01-17T12:51:36Z

text/3907-mtls-registry-authentication.md

+    // Response kind: this was a TLS client identity request
+    "kind":"tls-identity",
+    // Base64 byte buffer containing the binary content of your client certificate (empty if unset)
+    "cert_blob":"aGVsbG8...gd29ybGQ=",


Would supporting raw public keys be an option? That way a registry could just store the public key as a token in the database and doesn't need to parse a client certificate and do a whole bunch of checks to see if the certificate is valid, making it much more robust.

This RFC is intended to allow Cargo to present client certificates, not change how the certificates are processed or validated by the server.

In my use case, a registry is being reverse-proxied by a web server like Nginx, Apache, HAproxy, etc... to provide additional features like SSO, SCIM and LDAP in addition to client identity verification.

Using raw public keys wouldn’t support this reverse-proxy use case, since it would require changes to how the proxy validates the client certificates.

I mean having the option for the credential provider to provide raw public keys in case a registry wants to support this for robustness or any other reason. If you use client certificates to authenticate specific clients rather than just any client who gets a certificate from the CA, then whichever side channel is used to communicate the identity of the client from the reverse-proxy to the registry can pass a the raw public key too, right?

Oh I was misunderstanding your previous comment. I think we could add an additional field that allows that, what did you have in mind?

bjorn3 · 2026-01-17T12:57:29Z

text/3907-mtls-registry-authentication.md

+    // The format of your client certificate. With the current curl-based backend, supported formats are “PEM”, “DER”, and "P12" (empty for backend default)
+    "cert_type":"PEM",
+    // Base64 byte buffer containing the binary content of your private key (empty if unset)
+    "key_blob":"aGVsbG8...gd29ybGQ=",


Already mentioned this on Zulip and probably should be omitted in the first version, but it might be nice to support credential providers that can't export the private key but rather act as a signing oracle to support for example TPM or smartcard backed certificates. Rustls should support that through the SigningKey trait.

This would definitely be a nice use case to support, and as you point out, it looks like rustls has support for this, and I also believe libcurl can be persuaded into doing this.

I don’t know enough about how these signing request flows work to propose a sensible protocol, so that’s mainly why I’ve omitted it here. I’d be happy to consider adding it to this RFC, but also agree that it’s a somewhat independent feature that could be added in a later version.

bjorn3 · 2026-01-17T13:04:15Z

text/3907-mtls-registry-authentication.md

+    // Base64 byte buffer containing the binary content of your client certificate (empty if unset)
+    "cert_blob":"aGVsbG8...gd29ybGQ=",
+    // The format of your client certificate. With the current curl-based backend, supported formats are “PEM”, “DER”, and "P12" (empty for backend default)
+    "cert_type":"PEM",


Do we actually need to support PKCS#12 format certificates? The credential provider could just convert it to a PEM certificate + separate private key, right? If you are using PKCS#12 to support private key encryption, the credential provider did have to parse the PKCS#12 file anyway to decrypt the private key as cargo doesn't know the password.

Also I don't think there should be a backend dependent default for the type. Either it should be automatically detected from the file header or it should be always explicitly specified.

I don’t think we need to support PKCS#12, it was listed as a format that libcurl already supports so I listed it too.

If we’re fine explicitly specifying the format a PEM certificate + separate signing key would make sense. It can be on the credential provider to convert objects into that format.

for libcurl to load a password-protected P12 file you'll have to supply CURLOPT_KEYPASSWD as well.

3a16df3 now specifies that the certificates and keys are in PEM format

A PKCS#8 key can also be password-protected. The need of password is not really a question of PEM vs DER vs P12. (We could just say we don't support encrypted private keys)

I’ll add a section saying that this feature won’t support encrypted private keys, and that it’s the credential provider’s responsibility to take care of decryption if necessary.

d1806de adds a section on certificate and key field formats, and specifies that encrypted private keys are not supported

text/3907-mtls-registry-authentication.md

programmerjake · 2026-01-18T01:13:26Z

text/3907-mtls-registry-authentication.md

+    "kind":"tls-identity",
+    // Client certificate chain in PEM format (empty if unset)
+    "certificate":"-----BEGIN CERTIFICATE-----
+                   [Base64 encoded client certificate data]


you have to use the \n escape for new lines in json, you can't just have a literal newline.

ae27ce7 specifies that newlines have to be escaped

Eh2406

Just some first impressions from a first read.

Eh2406 · 2026-01-19T16:41:10Z

text/3907-mtls-registry-authentication.md

+    "kind":"tls-identity",
+    // Registry information (see https://doc.rust-lang.org/cargo/reference/credential-provider-protocol.html#registry-information)
+    "registry":{"index-url":"sparse+https://registry-url/index/"},
+    // Additional command-line args (optional)


What do these args represent? Where do they come from?

Eh2406 · 2026-01-19T16:44:39Z

text/3907-mtls-registry-authentication.md

+
+## Certificate and key formats
+
+The `certificate` and `key` fields are expected to correspond to the same TLS client identity. If a credential provider is unable to supply a usable client identity, it may return empty fields.


When should it be returning "empty fields" vs "Err":{"kind":"not-found"}?

Eh2406 · 2026-01-19T16:48:55Z

text/3907-mtls-registry-authentication.md

+
+The `certificate` field contains the client certificate chain in PEM format, with newlines escaped using `\n`. If multiple certificates are present, they are expected to be concatenated PEM blocks.
+
+The `key` field contains the private key corresponding to the client certificate, in PEM format, with newlines escaped using `\n`.


Every Cryptography expert I've ever talked to has strong opinions about PEM. The fact that it is widely used means that it's widely supported, but that doesn't necessarily mean we should start using it. I would want opinions from Rust Crypto before making this decision.

Eh2406 · 2026-01-19T16:56:51Z

text/3907-mtls-registry-authentication.md

+Authentication at the TLS level is different from the token-based methods for [Registry Authentication](https://doc.rust-lang.org/cargo/reference/registry-authentication.html) exposed by the [Credential Provider Protocol](https://doc.rust-lang.org/cargo/reference/credential-provider-protocol.html) since it takes place before the connection to the registry is established. It is not currently possible to write a [credential plugin](https://doc.rust-lang.org/cargo/reference/registry-authentication.html#credential-plugins) that enables this type of authentication with a registry, but an extension to that protocol would make this possible.
+
+# Guide-level explanation
+[guide-level-explanation]: #guide-level-explanation


What is our guidance on how registries should implement authentication? Should registries use MTLS? Should registries use tokens? Should registries use both? If the answer is, as it probably is, "It's complicated" then what are the factors that would drive that decision?

Matt Hague and others added 5 commits November 18, 2025 22:05

Create RFC for cargo mTLS support

73a123b

Update 0000-mtls-registry-authentication

905eb14

Add Git to previous art

Update RFC based on zulip feedback

704d24f

Merge branch 'master' of github.com:matthague/rfcs

e461aed

Update file with PR number

92fdb37

Noratrieb added the T-cargo Relevant to the Cargo team, which will review and decide on the RFC. label Jan 17, 2026

github-project-automation bot added this to Cargo status tracker Jan 17, 2026

bjorn3 reviewed Jan 17, 2026

View reviewed changes

Specify that certificates and keys use PEM format

3a16df3

bjorn3 reviewed Jan 17, 2026

View reviewed changes

text/3907-mtls-registry-authentication.md Outdated Show resolved Hide resolved

Remove double base64'ing of PEM formatted data

24a2881

programmerjake reviewed Jan 18, 2026

View reviewed changes

matthague and others added 2 commits January 17, 2026 20:39

Specify escaped newlines in certificate and key fields

ae27ce7

Add explicit section on certificate and key format

d1806de

Eh2406 reviewed Jan 19, 2026

View reviewed changes

ehuss moved this to RFC needs review in Cargo status tracker Jan 20, 2026


		## Certificate and key formats

		The `certificate` and `key` fields are expected to correspond to the same TLS client identity. If a credential provider is unable to supply a usable client identity, it may return empty fields.


		The `certificate` field contains the client certificate chain in PEM format, with newlines escaped using `\n`. If multiple certificates are present, they are expected to be concatenated PEM blocks.

		The `key` field contains the private key corresponding to the client certificate, in PEM format, with newlines escaped using `\n`.

Cargo mTLS registry authentication #3907

Are you sure you want to change the base?

Cargo mTLS registry authentication #3907

Conversation

matthague commented Jan 17, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Eh2406 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

matthague commented Jan 17, 2026 •

edited by rustbot

Loading