Hints on self-signed certificates

@gvbgduh

In #503, @gvbgduh mentioned the need to make HTTP/2 requests to a local server. Because of our current implementation (require TLS for HTTP/2, as browsers do), this typically requires to setup a local self-signed certificate for use in tests.

I'm probably not the one most aware of how this can be done — @sethmlarson may have some pointers? But we could at least gather some resources on how to set things up, and then see if/how we can include those to our documentation. This might take the form of a note added here with a link to a relevant how-to guide.

Related: Kludex/uvicorn#47 (comment)

If it's for local development (especially within the context of testing) I highly recommend using trustme to generate the certificates and then configure them as you would any other certificate. That gets you the most realistic scenario of trusting a CA certificate that previously signed the certificate the server is presenting. It wouldn't be hard to whip up a little tool that just hands you the certificates and tells you what to do with each one.

@sethmlarson

Thanks @sethmlarson, it actually works great.

(Btw I'm putting together a little utility that generates certificates in this configuration for you from command line)

I just noticed we currently don't have any usage hints on how to use the cert parameter (just a definition of what it is in the Developer Interface). Would this be a good opportunity to set it up?

Perhaps a "Custom SSL certificates" section in the Advanced docs, that shows how to use a trustme certificate in HTTPX…

@sethmlarson

I just tried out trustme locally as well:

# app.py
from starlette.responses import PlainTextResponse

app = PlainTextResponse("Hello, world!")

# create_certs.py
import trustme


ca = trustme.CA()
cert = ca.issue_cert("localhost")

# For use by clients (eg 'verify' in HTTPX)
ca.cert_pem.write_to_path("ca.pem")

# For use by servers (eg '--ssl-certfile' in Uvicorn)
cert.private_key_and_cert_chain_pem.write_to_path("server.pem")

# example.py
import httpx

# Use CA bundle generated by trustme
r = httpx.get("https://localhost:8000", verify="ca.pem")

Usage:

$ python create_certs.py
$ uvicorn --ssl-certfile=server.pem app:app
$ python example.py

Have I got that right @sethmlarson @gvbgduh?

Looks right to me, I created a little script that does basically what you have in create_certs.py: https://github.com/sethmlarson/trustme-cli

We can mention that in the docs if people aren't using trustme programmatically like with pytest to generate certs within a test suite but instead poking around or running things manually.

Totally agree we should have a section on this as it's not trivial.

@sethmlarson

Awesome @sethmlarson!

Somewhat related — we have the cert and verify parameters. As I understand, verify can be used to tell HTTPX to use a custom CA bundle (i.e. not certifi's), but then in what kind of situations would we use cert?

cert is client cert. It's confusing, but that's Requests' API we're inheriting 🤷‍♂️.

Basically verify is server verification and cert is for the server to do client verification.

Ah. Well that is confusing. 😆 So cert would be used if we have our own certificate, and we want the server to trust that certificate when we connect to it?

@sethmlarson

cert is for client authentication by the server, the certificate says "I'm @sethmlarson" and is signed by a certificate that the server trusts. So if you're interacting with a service that does authentication via TLS certificates then you'd need to provide a cert parameter.

We could choose to digress from requests there, and use client_cert.

At the very least we probably want some more documentation there, yup. I'd not picked up that it was for client certification personally, and it definately falls into the category of "you don't need this, unless you know what you're doing".

Presumably it's outside the realm of what browsers will generally do, right?

(At least not without some fiddly reasonably obscure configuration - https://support.google.com/chrome/a/answer/6080885?hl=en)

@sethmlarson

@sethmlarson trustme-cli works like a charm!

I opened #510 with some basic documentation based on what we've seen so far:

Using a custom certificate
Making HTTPS requests to localhost

Would love to have your feedback there. :-)

@florimondmanca

@florimondmanca @sethmlarson the doco and CLI look fantastic! It'll definitely solve heaps of confusion.

I think it might be reasonable to eventually add a similar section to the uvicorn doco and cover it from the server-side. Probably with a cross-link to the httpx example and an example for pytest. I can do it after some battle-testing.

Navigation Menu

Repository navigation

Hints on self-signed certificates #507

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Hints on self-signed certificates #507

Description

Activity

lovelydinosaur commented on Nov 6, 2019

sethmlarson commented on Nov 6, 2019

gvbgduh commented on Nov 6, 2019

sethmlarson commented on Nov 6, 2019

florimondmanca commented on Nov 6, 2019

florimondmanca commented on Nov 6, 2019

sethmlarson commented on Nov 6, 2019

florimondmanca commented on Nov 6, 2019

sethmlarson commented on Nov 6, 2019

florimondmanca commented on Nov 6, 2019

sethmlarson commented on Nov 6, 2019

lovelydinosaur commented on Nov 6, 2019

florimondmanca commented on Nov 6, 2019

gvbgduh commented on Nov 7, 2019

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions