Update contrib instructions for using TLS

Author: KingMob

.envrc.example

@@ -0,0 +1,2 @@
+# Set this to a local file for curl to write premaster secrets to for Wireshark
+SSLKEYLOGFILE=

CONTRIBUTING.md

@@ -10,8 +10,12 @@ We require a recent version of [Leiningen](https://leiningen.org/), and a minimu
 
 ### TLS/SSL
 
-To develop against TLS, (effectively mandatory for HTTP/2+) it's best to install your own root authority and certificates. The [mkcert](https://github.com/FiloSottile/mkcert) tool is very helpful. 
+To develop against TLS, (effectively mandatory for HTTP/2+) it's helpful to install
+your own root authority and certificates. The [mkcert](https://github.com/FiloSottile/mkcert) tool is ideal for that. 
+While a self-signed certificate will work, it's possible to run into warnings and
+odd behavior.
 
+#### Mkcert
 An example setup:
 ```shell
 # first check $JAVA_HOME is not empty, mkcert will use it to know where to install
@@ -20,24 +24,65 @@ echo $JAVA_HOME
 # this is installs the root certificate authority (CA) for browsers/OS/Java
 mkcert -install 
 
-# if you have multiple JVMs in use, you will need to install the CA for each
+# if you have multiple JVMs in use, you will need to install the CA for each one separately
 export JAVA_HOME=/path/to/some/other/jdk
 TRUST_STORES=java mkcert -install
 
 # this will generate a cert file and a key file in .pem format
 mkcert aleph.localhost localhost 127.0.0.1 ::1
-# e.g., aleph.localhost+3-key.pem and aleph.localhost+3.pem
+# e.g., aleph.localhost+3.pem and aleph.localhost+3-key.pem 
 ```
 
+If you are using an HTTP tool with its own trust store, like Insomnia, you will
+need to add the root CA to its trust store as well.
+
+For Insomnia, it's hidden under the project dropdown in the top center, under 
+Collection Settings > Client Certificates > CA Certificate. (NB: you don't need
+a client certificate, just the CA.)
+
+For curl, you would run something like: `curl --cacert "$(mkcert -CAROOT)/rootCA.pem"`
+
+Warning: As of August 2023, many tools still do not support HTTP/2: Postman, 
+HTTPie, RapidAPI/Paw, and many others.
+
+#### DNS
+You'll need to add `aleph.localhost` to your `/etc/hosts` file, e.g.:
+
+```
+127.0.0.1 aleph.localhost
+::1 aleph.localhost
+```
+
+#### Aleph SslContext
 Then, in code, generate an SslContext like:
 
 ```clojure
 (aleph.netty/ssl-server-context
-  {:private-key       "aleph.localhost+3-key.pem"
-   :certificate-chain "aleph.localhost+3.pem"
+  {:certificate-chain "/path/to/aleph.localhost+3.pem"
+   :private-key       "/path/to/aleph.localhost+3-key.pem"
    ...})
 ```
 
+#### Wireshark and curl
+
+If you need to debug at the wire level, Wireshark is a powerful, but difficult 
+to use, tool. It supports TLS decryption, not via the use of certificates (which are
+only a starting point), but by recording the actual TLS session keys to a file. 
+
+In curl, you can support this by adding an env var called `SSLKEYLOGFILE`, and in
+Wireshark's Preferences > Protocols > TLS, set the "(Pre)-Master-Secret log 
+filename" to the same value. This is a bit of a pain to set up, but once done, 
+it's very useful.
+
+You would then run something like:
+
+```shell
+curl --cacert "$(mkcert -CAROOT)/rootCA.pem" --http2-prior-knowledge --max-time 3 --tls-max 1.2 https://aleph.localhost:11256/
+```
+
+*Note* the `--tls-max 1.2`. In testing, it was required or else the session key 
+log file was empty.
+
 ## Testing
 
 `lein test` should be run, and pass, before pushing up to GitHub.