Include a page with SSL introduction and best practices

[josevalim]

As mentioned in #747, I think a Plug page on SSL best practices would be very very welcome. Starting with the basics, mentioning the HTTP 2 requirement, and then talking about Plug.SSL as a plug and finally how to configure adapters (effectively Plug.SSL.configure/1) and common gotchas associated to it. If we have such page, then I agree we could move this there.

What do you think? Any takers?

/cc @voltone @idyll

[voltone]

I started working on something, I'll try to get it into reasonable shape and then open it up for discussion.

[idyll]

One thing we need to make sure we include in this guide is a warning about encrypting the private key. If you choose to encrypt your private key with AES encryption Cowboy fails silently. It needs to be encrypted with DES if it is encrypted.

And in my experience it really does just fail silently.

[voltone]

AES-128 should work, as it is supported by OTP. That should be a good alternative for 3DES.

But yes, these are the kind of potential pitfalls that should be documented, it can save a lot of banging heads.

I got a bit sidetracked with x509, but creating it has helped me better understand the behaviour of OTP, so eventually that should make its way into a Plug guide...

[AndrewDryga]

I think this guide should mention that SSL in Erlang/OTP is slow so if you deal with some sorts of scale, then you probably want to do SSL termination on load balancer or Nginx which is set in front of Plug.

[idyll]

If you throw a load balancer in front you're probably not getting H2 connections all the way back to Cowboy. Most load balancers only do H2 on the front end and not on the back end.

I would also expect this to change when OTP 22 is released with TLS 1.3 support.

[voltone]

Progress at last:
https://github.com/voltone/plug/blob/https_guide/guides/https.md

It's not quite ready, but shall I open a PR anyway for tracking comments? Or is this not what people had in mind?

[idyll]

I think it's great. You've done a fantastic job of this.

The only thing I would add is possibly a little bit of an additional explanation of how HSTS works (basically explain the HSTS cookie) so that if a user wants to test that HSTS is working they understand how to set a short-lived HSTS cookie for a dev/test environment. And the idea that it redirects 80 to 443 but all the rest of the ports are assumed to be encrypted.

If I can help at all, let me know. :)

[Gazler]

@voltone this is extremely informative and well written. Should we perhaps add a note discouraging the certificates from being added to source control in this section?

It is possible to bundle the certificate files with the application, possibly for packaging into a release In this case the files must be stored under the application's 'priv' directory.

Maybe add something like:

it is recommended to add these files to .gitignore with priv/**/*.pem

[voltone]

Thanks @idyll and @Gazler! Your feedback is much appreciated, I have incorporated both suggestions in the upcoming draft. I hope I can push an update later today or tomorrow.

[voltone]

Opened PR #803. Technical and editorial feedback, comments, corrections and additions welcome!

[voltone]

I guess we may want to unify this with the SSL section in Phoenix' Endpoint guide. It has some more details on HSTS, which could be merged into the Plug HTTPS guide. The Phoenix guide could then be reduced to a basic example, any Phoenix-specific bits, and a reference to the Plug HTTPS guide.

@chrismccord @Gazler does that sound reasonable?

[Gazler]

I think linking to this guide (when published) from Phoenix is the best idea.

[voltone]

This can be closed, now that #803 has been merged, no?