Merge branch 'main' of github.com:linnnus/blind-guild

1 files changed, 191 insertions, 0 deletions

diff --git a/notes/certificates.md b/notes/certificates.md
new file mode 100644
index 0000000..c495534
--- /dev/null
+++ b/notes/certificates.md
@@ -0,0 +1,191 @@
+# Certificates
+
+It is necessary to generate self-signed certificates for development.
+If that didn't make sense, read on!
+
+## What are certificates and certificate authorities?
+
+[Public key certificates][certificate] are used in cryptography to prove the authenticity of a public key.
+More specifically,
+they are used in TLS/HTTPS communication to prevent [man in the middle attacks][mitm].
+When the browser wants to send an encrypted request to `blind-guild.org`,
+it receives the server's public key as part of the opening handshake.
+Here, certificates come into play!
+
+The certificate is basically a file that says
+"the public key of `blind-guild.org` is BLAHBLAHBLAH."
+It is signed by a certificate authority.
+That authority is in turn certified by another certificate authority,
+which is *also* certified by another CA...
+all the way up the CA chain!
+At the end of the chain, there are a few "root certificate authorities".
+They are managed usually managed by a component of the operating system.
+
+[certificate]: https://en.wikipedia.org/wiki/Public_key_certificate
+[ca]: https://en.wikipedia.org/wiki/Certificate_authority
+[mitm]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack
+
+## Why do we care about HTTPS
+
+Normally, we only care about HTTPS for production builds
+– we let the reverse proxy handle yucky stuff like that!
+We can do that because we don't care about (our own) security when developing
+and because `localhost` is considered a [secure context][sec-ctx],
+meaning we still have access to all the sweet features
+that are normally limited to pages served over HTTPS.
+
+Unfortunately for us,
+battle.net's API requires a HTTPS callback URI  and does *not* make any exceptions for `localhost`.
+See [the documentation][ssl-req] for more details.
+**So we must generate SSL certificates anyways.**
+
+[sec-ctx]: https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts
+[ssl-req]: https://develop.battle.net/documentation/guides/using-oauth#:~:text=to%20begin%20working.-,Redirect%20URL,-Developers%20registering%20an
+
+## Creating self-signed certificates
+
+For development can get by with self-signed certificates.
+Normally,
+you have to pay a certificate authority for the privilege of
+them signing your certificate signing request.
+For development (and a school project),
+this is a bit too much work.
+Instead,
+we'll set up our own local certificate authority and use *that* to sign our development server's certificate.
+
+To generate the stuff in `pki/`,
+I largely followed the procedure layed out in [this SO answer][self-pki].
+I did, however,  change days of validity from 365 to 328500 (900 years).
+That way,
+I can just check this stuff in to version control,
+and hopefully no-one else will have to bother with generating them.
+For reference,
+here is a transcript of my terminal session:
+
+```sh
+$ openssl req -x509 -nodes \
+  -newkey RSA:2048       \
+  -keyout root-ca.key    \
+  -days 328500           \
+  -out root-ca.crt       \
+  -subj '/CN=root_CA_for_firefox'
+Generating a 2048 bit RSA private key
+.....................................+++++
+....................................................................................................................................................................+++++
+writing new private key to 'root-ca.key'
+-----
+$ ls
+root-ca.crt  root-ca.key
+$ cat root-ca.*
+-----BEGIN CERTIFICATE-----
+MIICujCCAaICCQCgquJyWnHovTANBgkqhkiG9w0BAQsFADAeMRwwGgYDVQQDDBNy
+b290X0NBX2Zvcl9maXJlZm94MCAXDTI0MDQyNDE4MTEyNVoYDzI5MjMwOTE5MTgx
+MTI1WjAeMRwwGgYDVQQDDBNyb290X0NBX2Zvcl9maXJlZm94MIIBIjANBgkqhkiG
+9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0VJEJ+DTEUe85ulf92HjDT6Xr4cDyS+uMJq3
+fNJkLOaMhptVtwGxtL4lh1vO8j9IZVLJ611VjXjAF06cjHgDsCMJ5Rf+05tUtxLW
+Z+QWFwNOS1VCDPpqEq0J+KrD9cuxLKK7nD5bPLxoXXmL3GN4v5kWqkMYDn0R66Nd
+IWCF8Wkgw2MLASIiB5tbYb7xJkpfioTfH3xQBlNtAaU1mtWAHZ2W+oyawcylSKFQ
+IymkjJvCjqRubLf+6q4MXpQC57wS7T+qxW1GRwpF6c5Vkx3bF9d9kXpaWDims6rs
+eevsA2mLhtfJ0RN5AU7spyaIGlHvK2NhSXVnBU8nLedX2qHgCQIDAQABMA0GCSqG
+SIb3DQEBCwUAA4IBAQAZzYQ9B9Lj2oxFMPQ3Eb1fI7zfFxUH1+YCX3J3oAGFd3em
+LTrIZG0IjSdqvSLrkp3/IxVKCx5uEc40UjLSsN9HNqDmF0vVNNfKS4UiuFVEY7wE
+22y9LkCNxYvdKz7iA1Q3m9dyWUUTSrve7zmnnDdnNBXY1lvjBr6EAgDbY8/xVyIE
+4f5+3icYTjFLsdjlkjc7F3RJAKDfeO4CHl6I82QD21UO/hv4b1t7r7ZUfr1RYWb/
+Tv75ISwfBfuge33H0rOIpORY5g7yZSDE58YiRFGgG8kPsOdY3N9y2T5wVDXRHs01
+eJlWXed7w4P7O9NGpwuwrZmrz3RptyqAIlrAaK0u
+-----END CERTIFICATE-----
+-----BEGIN PRIVATE KEY-----
+MIIEwAIBADANBgkqhkiG9w0BAQEFAASCBKowggSmAgEAAoIBAQDRUkQn4NMRR7zm
+6V/3YeMNPpevhwPJL64wmrd80mQs5oyGm1W3AbG0viWHW87yP0hlUsnrXVWNeMAX
+TpyMeAOwIwnlF/7Tm1S3EtZn5BYXA05LVUIM+moSrQn4qsP1y7EsorucPls8vGhd
+eYvcY3i/mRaqQxgOfRHro10hYIXxaSDDYwsBIiIHm1thvvEmSl+KhN8ffFAGU20B
+pTWa1YAdnZb6jJrBzKVIoVAjKaSMm8KOpG5st/7qrgxelALnvBLtP6rFbUZHCkXp
+zlWTHdsX132RelpYOKazqux56+wDaYuG18nRE3kBTuynJogaUe8rY2FJdWcFTyct
+51faoeAJAgMBAAECggEBAKSyEthBqDDHfhU9eHmftlNcdWLxW4Q3lNm/UjHPJGzD
+tbvPiqCkn5rzpXmcPfcS3baDbkZXOJJIePOdscVARL6YwxdTSvhaFky5cKNrrgnL
+WxYg7ghiG4W4SskyK19BNpVFMVJdKdJe98rccLQmPAKcxF2QzuPPeoMqFYPGe30W
+aw4i8ZunXxriQ6kdXHG+QhP0JZVIpHwBlxwJ0R3jM2kZgcJk888HGt2AQZ6fHfoC
+HM0cE6fCKebR+NbujNOFc7UXSMUyEXkkvOlk+r/kxGeE4INP1o27utItYNuNpFqD
+iB+uupH/Q2xxSJ4Cke43sMzlrImjFibMvp/WcfBoxdECgYEA6+7RQCC4CQXg9tYY
+N6lkU5qjKfxiXlCj1ZCpX5lW34MbWgDTc2OpCkE5dbc1wSzwblpBdUe3NHVVMTu7
+7yVvvytfH8dEasb5BWgkFdqNyPzoaP9wN6TC1cyuKsbYmbq7NTM9D1Q5dTtsjGfO
+3PBVUlj3RxHTKj6roAO+D2P3J20CgYEA4yAC/eUZ5ANk9YZrIGsoFjPqYMlKXDUO
+uQnnaSnKcL5E68ehvVvKj5epY/EicsGEKgEeIphJgley9x9AsU40UnlI3/bzqIhV
+GRjHPxiV7W9pB+PR4JWhppgohkIz3/QD4RONQNYYot7Jx+/QP9IAO1Br8kP80BEE
+4HrlNuT/LY0CgYEAz/Qm4hQ0wlc5K7gXjnAy6vHhIS/A8Iq5bZNdhtLcXJPt9s3F
+ku5j35MP927t5YAbx9ir25jDpWxKE+QnySlBLsomxRbZehg5BAf/zndeA6rPm0SS
+/6isxs/rL+8mmZGaUtD/39QH9QnUqokRL3JycevSwQS4EIM+uQKzclNVVJ0CgYEA
+zSSKzzxxCCuwsrs4Y02mJXe6yLTG/0XFCIjThX8DpJWWtsfXZKtV6CB6FRUlojT7
+5NyhlWmra5k+wkpuKjeStrNpiTEKnzyUcFibDnhsYsrwOPojBRDhsxFX+Pwu0qca
+Id+BBADcu68y3e3TUPGi1/Apr+aMoHnex8r44X4wpbkCgYEA33ozRucqlq6IaXVJ
+khESj6rv0CIa0dNUYVR+IuXQTj6MuQhY31BgsQOonSS6I5UsdD2z3Bj0MFz0wN1J
+V/rWseLJbFEgZiFyClhZKSe3oom7ehZvbPBYmWAg+kiUBav/823IJ3JQZQ8t1jU/
+Mk0B0PEYP3KTTMwiO7uEnC73l7c=
+-----END PRIVATE KEY-----
+$ openssl req -nodes \
+  -newkey rsa:2048   \
+  -keyout server.key \
+  -out server.csr    \
+  -subj '/CN=localhost'
+Generating a 2048 bit RSA private key
+...............+++++
+...........................................+++++
+writing new private key to 'server.key'
+-----
+$ openssl x509 -req
+  -CA root-ca.crt    \
+  -CAkey root-ca.key \
+  -in server.csr     \
+  -out server.crt    \
+  -days 328500       \
+  -CAcreateserial    \
+  -extfile <(printf "subjectAltName = DNS:localhost\nauthorityKeyIdentifier = keyid,issuer\nbasicConstraints = CA:FALSE\nkeyUsage = digitalSignature, keyEncipherment\nextendedKeyUsage=serverAuth")
+Signature ok
+subject=/CN=localhost
+Getting CA Private Key
+$ ls
+root-ca.crt  root-ca.key  root-ca.srl  server.crt   server.csr   server.key
+```
+
+[self-pki]: https://stackoverflow.com/a/77009337
+
+## Trusting self-signed certificates
+
+Now, the browser obviously doesn't trust this certificate
+– nor should it!
+It doesn't know anything about our local CA,
+so this certificate may as come from a malicious actor.
+If you attempt to load https://localhost:8080
+without performing the steps in this section,
+the browser will give you an error like `NET::ERR_CERT_AUTHORITY_INVALID`.
+
+For development purposes
+we would like to inform the browser
+that this CA is indeed to be trusted.
+The process varies a bit between different combinations of browsers and operating systems.
+Firefox, for example, maintains its own list of CAs.
+[Here][ff-trust] is a guide on how to install our custom CA into Firefox's trust store.
+Chrome, on the other hand, seems to be using the operating system's certificate store,
+so you'll need to modify this instead.
+[Here][guide-win] is a guide on how to do it on Windows
+and [here][guide-osx] is a guide for MacOS.
+
+N.B. Always keep in mind that we are looking to install our CA, that is the file `pki/root-ca.crt`, NOT the servers certificate, found in `pki/server.crt`.
+
+[ff-trust]: https://javorszky.co.uk/2019/11/06/get-firefox-to-trust-your-self-signed-certificates/
+[guide-win]: https://techcommunity.microsoft.com/t5/windows-server-essentials-and/installing-a-self-signed-certificate-as-a-trusted-root-ca-in/ba-p/396105
+[guide-osx]: https://tosbourn.com/getting-os-x-to-trust-self-signed-ssl-certificates/
+
+## Chrome is annoying
+
+For Firefox, the above is enough.
+It nags you a bit but you can force it to pipe down.
+When presented with the warning,
+just click "Advanced" and then "continue".
+
+Not so much for Chrome.
+It still complains about an invalid CN (common name).
+Luckily, there's one final escape hatch:
+type "[thisisunsafe]" anywhere on the error page.
+
+[thisisunsafe]: https://cybercafe.dev/thisisunsafe-bypassing-chrome-security-warnings/