update README

README.md

@@ -7,7 +7,7 @@ title = 'Kyleguy Inception'
 # README.md
 What could be more helpful than a guide more interested in a party trick than solving its stated purpose?  Probably any other guide right?  Our 'trick' is that this `README.md` is the same guide used to create the site that you are now reading.  In the same manner, this [repository](https://git.pebbleguy.com/kyle/kyleguy) also contains this file and describes how it was [built](#repositorySetup).  Alright.  Maybe it isn't that cool of a trick but I bet if you didn't think about it too much you'd think so.  We are showcasing static webpages.  More percisely a static site generator.
 
- - [x] 1. [Introduction](#prelude)
+ - [x] 1. [Introduction](#intro)
  - [x] 2. [Prerequisites](#prelude)
  - [x]   a. domain
  - [x]   b. webhost
@@ -16,7 +16,12 @@ What could be more helpful than a guide more interested in a party trick than so
  - [x]   a. [putty](#putty)
  - [x]   b. [keygen](#keygen)
  - [x]   c. [pebbleguy.com](#installKey)
- - [x] 3. [Repository Setup](#repositorySetup)
+ - [x]   d. [pageant-start](#pageantAutoStart)
+ - [x]   e. [pageant-key](#pageantNiceToMeetKey)
+ - [x] 3. [Rclone](#rclone)
+ - [x]   a. [install](#rcloneInstall)
+ - [x]   b. [config](#rcloneConfig)
+ - [x] 4. [Repository Setup](#repositorySetup)
  - [x]   a. [domain](#configureRegistration)
 
 ## <a name="intro" id="intro"></a> Introduction
@@ -80,34 +85,58 @@ Install PuTTY by [Simon Tatham](https://www.chiark.greenend.org.uk/~sgtatham/put
 
 ![launch-puttygen](images/launch-puttygen.png)
 
-One can generate any number of ssh-keys, I usually do a 4096-bit RSA key, but I think there is a bug in the `Raspberry PiOS` SecureShell confiuration options that the `Raspberry Pi Foundation` employees have yet to resolve.  The other keys types that I commonly use are `ECDSA` and `Ed25519`.  If you select the `EdDSA` radio button you can follow along, but feel free to try one of the other key types I mentioned.  You then click genrate and move your mouse around a bit in the `Key` window to add a little more noise that what would normally be provided by Windows' entropy pool.  Once the key generates, add a comment and a passphrase.  You may use one of the passwords that you normally give to Microsoft, your bank, and Amazon.  You aren't securing anything super important.  Just trying to obscure access like you normally would with your financial details.  Is that a tongue in my cheek?  Heh.
+One can generate any number of ssh-keys[^6], RSA, ECDSA, and ED25519 are all good options.  If you select the `EdDSA` radio button you can follow along, but feel free to try one of the other key types I mentioned.  
+
+You then click genrate and move your mouse around a bit in the `Key` window to add a little more noise that what would normally be provided by Windows' entropy pool.
+
+Once the key generates, add a comment and a passphrase.  You may use one of the passwords that you normally give to Microsoft, your bank, and Amazon.  You aren't securing anything super important.  You are just trying to obscure access like you normally would with your financial details.  Is that a tongue in my cheek?  Heh.
 
 The last thing to do is save the private key somewhere.  I just put it on my Desktop.  It is encrypted it isn't going to be useful to anybody without my passphrase.
 
+[^6]: I usually generate 4096-bit RSA keys, but I think there is a bug in the `Raspberry PiOS` SSH confiuration options that the `Raspberry Pi Foundation` employees have yet to resolve.  
+
+
 ![generated-private-key](images/generated-private-key.png)
 ---
 
 <a name="installKey" id="installKey"></a> **Copy the public key to pebbleguy.com**
 
-In the above screenshot you can see the public key.  I will copy this key to pebbleguy.com.  The private key stays on this local Windows computer on my desktop.  You can just copy the public key to your clipboard and add it to your user's `authorized keys` on pebbleguy.com.  When you sign into pebbleguy.com with SecureShell it looks at your authorized keys (a list of public keys) to determine what private keys could be used for authentication.  Connect to pebbleguy.com and run the below command.  Replace your public key.  You can put my public key if you want but I can already sign into my own user using my key so...  `echo '{{YOUR_PUBLIC_KEY}}' |tee -a ~/.ssh/authorized_keys`.
+In the above screenshot you can see the public key in the `PuTTYgen` window.  I will copy my key to pebbleguy.com and you will copy yours.
+You may copy the public key to your clipboard then paste it into your users' `authorized keys`[^7] on pebbleguy.com.  
 
-*If you used `ssh-keygen` to generate a key there should be a companion tool, `ssh-copy-id` that can be used to help install the public key on a remote server.*
+[^7]: When you sign into pebbleguy.com with SSH it looks at your authorized keys (a list of public keys) to determine what private keys could be used for authentication.  
+The private key stays on my local Windows computer in my Desktop directory.  
+
+To copy your public key[^8], connect to pebbleguy.com and run the below command (make sure to substitue your public key).
+
+[^8]: You can use my public key if you want but I can already sign into my own user using my key so and you won't have my private key so it does not benefit either of us.  `echo '{{YOUR_PUBLIC_KEY}}' |tee -a ~/.ssh/authorized_keys`.
 
 ```
 echo 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGYtvZuiyun9DQe/6xrxby0iQeLy+jE1JKrpgRrHKbrT windows computer rclone key for kyleguy' |tee -a ~/.ssh/authorized_keys
 ```
+
+*If you used `ssh-keygen` to generate a key there should be a companion tool, `ssh-copy-id` that can be used to help install the public key on a remote server.*
 ---
 
-**Add a Pageant shortcut to Windows startup**
+<a name="pageantAutoStart" id="pageantAutoStart"></a> **Add a Pageant shortcut to Windows startup**
+
+The `Rclone` software that we will use to synchronize our website files does not support decryption of private keys.  They do however support requesting an external program to decrypt a key, unfortunatley not the `Windows Credential Store` [^9].  Luckly though, the author of `PuTTY` also wrote a minimal keystore[^10] called `Pageant`.  
+
+We could also use `Gpg4win` which was funded by [Bundesamt f&uuml;r Sicherheit in der Informationstechnik](https://www.bsi.bund.de/DE/Home/home_node.html) (Germany's Federal Office for Information Security).  I would have recommended this path but I didn't have time to explore it fully.
+
+The `Pageant` software is bundled with the `PuTTY` installer so once you install `PuTTY` we can setup `Pageant` to load when Windows loads.
+
+[^9]: Encrypting one's private keys exposes them to some harsh realities.  The `Windows Credential Store` is not well known, lacks documentation, and is riddled with Microsoftisms.  Whenever I write software targeting the Microsoft platform it's these little burdens that end up wasting the most time.  I expect the developers of `Rclone` to face similar roadblocks and it could be an explination for why they do not have native support for decrypting private keys.
+
+[^10]: It only supports ssh-keys but with ssh-keys being the defacto key this really doesn't matter.  
 
-Encrypting private keys to prevent a number of security flaws will expose us to some harsh realities.  Windows' keystore, `Windows Credential Store` is not well known, lacks documentation and is riddled with Microsoftisms.  Towards this guide the unsupported nature of the keystore is most impactful.  We are going to be using `Rclone` which doesn't natively support decrypting private keys.  They do however support requesting an external program to decrypt a key, but not the `Windows Credential Store`.  Luckly though, the author of `PuTTY` also wrote a minimal keystore called `Pageant`.  It only supports ssh-keys but with ssh-keys being the defacto key this really doesn't matter.  We could also use `Gpg4win` which was funded by [Bundesamt für Sicherheit in der Informationstechnik](https://www.bsi.bund.de/DE/Home/home_node.html) (Germany's Federal Office for Information Security)  but since we are focused on ssh-keys we are going to use the smaller footprint solution.  I say smaller, in today's world both these solutions are microscopic specs of dust compared to the softwares that are considered "lightweight".  The `Pageant` software is bundled with the `PuTTY` installer so once you install `PuTTY` we can setup `Pageant` to load when Windows loads.
 
 *If you are using `ssh-keygen` you should also have access to `ssh-agent` which can be configured to aid `Rclone` with encrypted keys.  GNU's `GPG-agent` would do the same thing but I'm not sure what would happen if `Rclone` made a request.*
 
 ![run-shell-startup](images/shell-startup.png)
 ---
 
-**Tell Pageant about our key**
+<a name="pageantNiceToMeetKey" id="pageantNiceToMeetKey"></a> **Tell Pageant about our key**
 
 Using the shortcut we just created, we will provide `Pageant` a way to find our key.
 
@@ -118,12 +147,15 @@ The Windows properties dialog window has a tab, `Shortcut` with a `taget` proper
 "C:\Program Files\PuTTY\pageant.exe" --encrypted C:\Users\valued-customer\Desktop\windows-rclone-key-for-kyleguy.ppk
 ```
 
-The `--encrypted` is a flag that tells `Pageant` that the key is encrypted and to not prompt for the user to enter a passphrase until it is used for the first time.  This is an annoyance preventer as by default it will startup with Windows and immediately prompt for the passphrase regardless if you are going to be using the key.  When `Pageant` launches it will put a task manager GUI shortcut in the taskbar.  One can view what keys `Pageant` knows about.  Later `Rclose` will be able to ask `Pageant` to authenticate ourselves with pebbleguy.com.
+The `--encrypted` flag that tells `pageant` that the key is encrypted and to not prompt for the user to enter a passphrase until it is used for the first time.  This is an stops it from immediately prompting for the passphrase regardless of you using the key.  When `pageant` launches it will put a task manager GUI shortcut in the taskbar.  One can view what keys `pageant` knows about.  Later `Rclone` will be able to ask `pageant` to authenticate ourselves with pebbleguy.com.
 
 ![shortcut-properties](images/shortcut-properties.png)
 --- 
 
-**Install Rclone**
+## <a name="rclone" id="rclone"></a> Rclone
+
+<a name="rcloneInstall" id="rcloneInstall"></a> **Install Rclone**
+
 Windows does not have any good generic file synchronization tools.  Nick Craig-Wood wrote a synchronization tool focused on commercial cloud storage products and his team ported it to Windows.  I've never used it but [Rclone](https://rclone.org/) seems well liked and well supported.  Compiled released binaries can be had using the Windows package manager `winget`.
 
 ```
@@ -131,7 +163,7 @@ winget install Rclone.Rclone
 ```
 ---
 
-**Add an Rclone config for kyleguy**
+<a name="rcloneConfig" id="rcloneConfig"></a> **Add an Rclone config for kyleguy**
 
 We can tell `Rclone` about our website and a scheme to update the webserver with changes made to our local static site by providing it configuration directives.  Using a Windows terminal, we can issue this `Rclone` command to generate a config file.  Additional configuration [documentation](https://rclone.org/commands/rclone_config/) is available online.  This will make it easier to provide all the details to `Rclone` every time it is envoked.