docs: clarify self-signed certificate limitation.

[bdaehlie]

That is a limitation of webpki and should be noted there.

See this PR for webpki.

[cpu]

Thanks!

[djc]

I don't think this is a good change.

For most users, webpki is an implementation detail of the rustls default verifier. Even if/when we make the webpki verifier more explicit in the API (for example, by making callers pass a WebPkiVerifiers::from(roots) to the config builder API), for a large majority of users rustls is intimately connected with webpki -- that's probably even more true of the relatively unsophisticated users who don't have a good idea about the trade-offs of self-signed certificates.

Instead, I think we should be upfront about this limitation and its nuances. For example, that it can be made to work by implementing a custom verifier, or how easy we can make it to support private CA setups.

[ctz]

How about this?

• Using CA certificates directly to authenticate a server/client. CA certificates should
  only issue other certificates, and cannot be used alone for authentication. All authentication can be turned off -- see our example code.)

Note I'm carefully avoiding saying "self-signed", which I think can be used to mean three different things:

1. a standalone CA certificate that has CN=localhost (or something) and therefore authenticates itself. This is specific case webpki doesn't support.
2. a locally-administered PKI (ie, "i signed this myself, it is self-signed")
3. turn-off-all-authentication-I-don't-care (ie, "don't bother me with this certificate bidness")

[djc]

That's better, although I would say we actually need to have the word "self-signed" in there to make unsophisticated users understand? Could just be a parenthetical "(these are often said to be self-signed certificates)".

[cpu]

@bdaehlie Do you want to iterate on this with the suggested text from the feedback above, or would it be helpful if I adopted this and got it across the line?

[bdaehlie]

If you're able to take this over that would be great, thanks.

[codecov]

Codecov Report

Merging #1480 (9a23112) into main (992e236) will not change coverage.
Report is 4 commits behind head on main.
The diff coverage is n/a.

❗ Current head 9a23112 differs from pull request most recent head 71488bf. Consider uploading reports for the commit 71488bf to get more accurate results

@@           Coverage Diff           @@
##             main    #1480   +/-   ##
=======================================
  Coverage   96.46%   96.46%           
=======================================
  Files          72       72           
  Lines       15105    15105           
=======================================
  Hits        14571    14571           
  Misses        534      534           

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[cpu]

@ctz @djc I updated this branch with the suggestions from above. PTAL

[ctz]

(fwiw)