Starts on some documentation for certificates

docs/certificate-authority.md

@@ -1,6 +1,39 @@
 # Certificate Authority
 
-At some point, it would be nice if yaip does this automatically, but for now,
-you need to create a certificate authority for yaip to sign requests with.
+On startup, yaip will create a cetificate and key and store them in
+~/.config/yaip/.
 
-;
+In order to intercept HTTPS traffic, yaip needs to become certificate authority.
+It will pretend to be the client to the server, making HTTP requests in the same
+way a browser would. It then pretends to be the server to the client. However,
+this is precisely the kind of "attack" that the certificate system is designed
+to prevent. Without further action, any modern browser will show warnings
+because yaip isn't the server it is pretending to be.
+
+In order to get around this, yaip becomes a certificate authority and verifies
+all the responses that it makes. In order for this to work, it is necessary for
+the authority to be trusted by your browser of choice. Search for "add
+certificate authority in *your favourite browser*" in *your favourite search
+engine*.
+
+## How it works
+
+If you set your browser to use yaip as a proxy, it will initially send a CONNECT
+request to yaip, asking it to create a channel to the server it wants to connect
+to. This looks something like this:
+
+```
+CONNECT example.com HTTP/1.1
+```
+
+For a normal (non intercepting) proxy, the proxy server would open a connection
+to example.com and all traffic going through it would be invisible to the proxy
+server. This is not very useful for us.
+
+YAIP tells the client that it has established such a connection before it
+communicates with the upstream server, by sending a `200 Connection Established`
+response.
+
+The client then begins the SSL/TLS negotiation. However, it negotiates with yaip
+rather than the upstream server. Yaip takes the hostname from the connect
+request so can generate a valid certificate.