Add longer internal_ssl documentation to main docs

docs/source/reference/proxy.md

@@ -62,6 +62,15 @@ These methods **may** be  coroutines.
 `c.Proxy.should_start` is a configurable flag that determines whether the
 Hub should call these methods when the Hub itself starts and stops.
 
+## Encryption
+
+When using `internal_ssl` to encrypt traffic behind the proxy, at minimum,
+your `Proxy` will need client ssl certificates which the `Hub` must be made 
+aware of. These can be provided to the hub via the `jupyterhub_config.py` file
+by providing a `dict` of named paths to the `external_authorities` option. The
+hub will include all certificates provided in that `dict` in the trust bundle
+utilized by all internal components.
+
 ### Purely external proxies
 
 Probably most custom proxies will be externally managed,

docs/source/reference/spawners.md

@@ -223,3 +223,30 @@ in the single-user notebook server when a guarantee is being provided.
 **The spawner's underlying system or cluster is responsible for enforcing these
 limits and providing these guarantees.** If these values are set to `None`, no
 limits or guarantees are provided, and no environment values are set.
+
+### Encryption
+
+Communication between the `Proxy`, `Hub`, and `Notebook` can be secured by
+turning on `internal_ssl` in `jupyterhub_config.py`. For a custom spawner to
+utilize these certs, there are two methods of interest on the base `Spawner`
+class: `.create_certs` and `.move_certs`.
+
+The first method, `.create_certs` will sign a key-cert pair using an internally
+trusted authority for notebooks.  During this process, `.create_certs` can
+apply `ip` and `dns` name information to the cert via an `alt_names` `kwarg`.
+This is used for certificate authentication (verification). Without proper
+verification, the `Notebook` will be unable to communicate with the `Hub` and
+vice versa when `internal_ssl` is enabled. For example, given a deployment
+using the `DockerSpawner` which will start containers with `ips` from the
+`docker` subnet pool, the `DockerSpawner` would need to instead choose a
+container `ip` prior to starting and pass that to `.create_certs` (TODO: edit).
+
+In general though, this method will not need to be changed and the default
+`ip`/`dns` (localhost) info will suffice.
+
+When `.create_certs` is run, it will `.create_certs` in a default, central
+location specified by `c.JupyterHub.internal_certs_location`. For `Spawners`
+that need access to these certs elsewhere (i.e. on another host altogether),
+the `.move_certs` method can be overridden to move the certs appropriately.
+Again, using `DockerSpawner` as an example, this would entail moving certs
+to a directory that will get mounted into the container this spawner starts.

docs/source/reference/websecurity.md

@@ -99,6 +99,23 @@ single-user server, and not the environment(s) in which the user's kernel(s)
 may run. Installing additional packages in the kernel environment does not
 pose additional risk to the web application's security.
 
+### Encrypt internal connections with SSL/TLS
+
+By default, all communication on the server, between the proxy, hub, and single
+-user notebooks is performed unencrypted. Setting the `internal_ssl` flag in
+`jupyterhub_config.py` secures the aforementioned routes. Turning this
+feature on does require that the enabled `Spawner` can use the certificates
+generated by the `Hub` (the default `LocalProcessSpawner` can, for instance).
+
+It is also important to note that this encryption **does not** (yet) cover the
+`zmq tcp` sockets between the Notebook client and kernel. While users cannot
+submit arbitrary commands to another user's kernel, they can bind to these
+sockets and listen. When serving untrusted users, this eavesdropping can be
+mitigated by setting `KernelManager.transport` to `ipc`. This applies standard
+Unix permissions to the communication sockets thereby restricting
+communication to the socket owner. The `internal_ssl` option will eventually
+extend to securing the `tcp` sockets as well.
+
 ## Security audits
 
 We recommend that you do periodic reviews of your deployment's security. It's