From b880108746d1c9126a10f2f1b0b3933b7e1088ea Mon Sep 17 00:00:00 2001 From: Jonathan Hodgson Date: Sun, 30 Jan 2022 12:34:03 +0000 Subject: [PATCH] Starts on some documentation for certificates --- docs/certificate-authority.md | 39 ++++++++++++++++++++++++++++++++--- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/docs/certificate-authority.md b/docs/certificate-authority.md index 3a328f3..4cbc1a8 100644 --- a/docs/certificate-authority.md +++ b/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.