docs: further proofing on 'the secure shell' (#199)

Author: dwmkerr

docs/06-advanced-techniques/31-the-secure-shell/diagrams/asymmetric-encryption-share-secret.drawio

@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2022-04-19T03:08:27.914Z" agent="5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/17.4.2 Chrome/100.0.4896.60 Electron/18.0.1 Safari/537.36" etag="-pOFAqGIufpV7Ygc9S9D" version="17.4.2" type="device"><diagram id="zMdPa7TFIofes7aEGqtK" name="Page-1">7Vhtb9MwEP41EZ+o8tqmH9d2GxJDDA3E+ITc5JqYOrnKcdeWX4+dOGlSZxtjG3TApK7247NTP8/d+RzLm2bbc05W6TuMgVmuHW8tb2a5ruPYQ/mlkF2FhJ5fAQmnsTbaA1f0O2jQ1uiaxlB0DAUiE3TVBSPMc4hEByOc46ZrtkDWfeqKJGAAVxFhJvqZxiKt9zUc7wfeAE1S/ejQHVUDGamN9U6KlMS4aUHeqeVNOaKoWtl2CkyRV/NSzTu7ZbT5YRxy8TMTtuGnBfl6/Sbyt9NhcIbL+MPJa7da5Yawtd7wlAMRoNjLY/kf8ojvVkL15ecKIg5C70fsapI4rvMY1HNsy5tsUirgakUiNbqRbiGxVGRM9hzZLOQIzZOPuNL2GriAhegiExQCsy4me4HsmZvXfNwAF7BtQZqMc8AMBN9JEz3qBdUM7ZhOrdOmJXONpS2Fhxoj2rOSZuU9+bKh+X+AFr6hxQTnBtfSjVaquc7YSSSQSzLUnql02QsyB3aJBRUUc2ky1/w1BieMJmpA4IEmuBaM5jBtgsh+Go5Du8NxD8Xe72Q4MBi23CGTT53MuWwlotz1ISJZi+BVYQ5crudyyMTfwu5W2XKUwXVvjMxJtEzKqHpfKaPxmPDlexUIQjFqD+wnigWnq5Mz9g2hwh6hHPu5lBr+klIyXvp0uiVrHbskx6bJqEeTA0pbfN2blIhORpHkCFQaY8py0tA8Raaym1zWW5R/tyayQnBcNsez2yCtFWw7tM/KY6Q+he1SuyJtjq3aHbJtokqZAcViNKCyrigGDKOlsnsSXR3/QNeRoavrm7p6zyVraKgIsSyBdBe5SDHBnLDTPTrpHvh7mwssT3Wl/zcQYqfrObIW2I0myR/fXev5ZedLGT1B3Z1t24OzXS2SIFycqLpOeQ4jRSETsIbPKNsvH9dGOapQVYgev/NoU1u/U0UOjAh6060O+zTRUy+R5qJVdIwPqg5/PAi6i8itJCD0vHY9d7CUE9y7VIFrHoGxVOkmzZ5+3XPGRkI4barFOufqMrKA8ku6gWuX52mv05W5ousoRpY4TAEZjePKJ6Gg38m8XE9pvFLbLokIJlYw61X9roAwQrq5ZOiHWO06vi/UX9sDxw69au4jHcfxujNwsSjgWVSta4GWrDOoZdUn7N91ETiMyT9+E3AcQ4L+oHlRlwHfP67bgGNefh93HeD0prw6v/z7gDc6tuKzzn//q8/HCRseWfXpmG89/rWbnj88umDre1HyP9geLOzoJ4Jt2BNs3oN1ld39m+SqEty/j/dOfwA=</diagram></mxfile>

docs/06-advanced-techniques/31-the-secure-shell/diagrams/asymmetric-encryption.drawio

@@ -1 +1 @@
-<mxfile host="Electron" modified="2022-04-05T05:58:06.492Z" agent="5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/15.4.0 Chrome/91.0.4472.164 Electron/13.5.0 Safari/537.36" etag="WB49tPhE24BtVEzryK7K" version="15.4.0" type="device"><diagram id="zMdPa7TFIofes7aEGqtK" name="Page-1">3VfbUtswEP2aPJKRrTikj+QC7RQGpulM26eOYiu2GtvryjKJ+fqubPmGk0A7gYHygnS02mjP2V1LAzqLdleSJcENeDwc2MTbDeh8YNuWRcb4TyN5iUzsSQn4UnjGqAGW4oEbkBg0Ex5PO4YKIFQi6YIuxDF3VQdjUsK2a7aGsPurCfN5D1i6LOyj34Sngiqu8Ydm4SMXfqCq+M7LhYhVxiaSNGAebFsQXQzoTAKochTtZjzU5FW8lPsuD6zWB5M8Vs/Z8EV+yleLW0c6V78p8ZQD/OeZieKehZkJ+E6Ke6b4wB6H6Ha6kjjy9egzz00gKq/YwZgSPYwBd9DpNhCKLxPmamyLCYFYoKIQZ5b2xdyNLyGLvdtMhSLmBveY3NziLqF0kpAhcRA0B+NS8d3BiK2aR0xADhFXEg9Jqg0jQ73JPWqNyvm2UXJiTIKWhhYxIDPJ49euG35xYCj+C7qdHoPcw3QzU5AqAB9iFi4adFoQxrVXgrPG5hogMQT+4krlpnZYpqBLO7Il8+9mfzH5UdDsVNP5rr04z82sPKs+4HH+MR7IpMuPxF1VLpM+V0fs6H49JQ+ZEvfdc5xcnHGvFpY89hBZxK7ME8X1+IanqW4Z+3S8Zivsfh3uWSj8GMcuUsYlAjqhBbaXC7MQCc8rZeapeGCrwp9mPwERqyJEZzpw5scqwvQ+s7npOG2lDqfjwfI5I0OLTGjp69kSGHd3+vitUqTdHbBep5gJjyWrD/HvKlo9FY18bfGwA2ADsEnd7Mi+7tatvCeaW6obWOx/LYqSNMA1X6suMgWlIOpiODtV07O7Tc+ummCr6dU27a43fqmmZ/cUweR3+yVUfUyyKLxwFbSrpaisO0iFEqCrZmUo7JWTgkeyQPmlmdXXA3IimsdOh2ZrD830NVmmPZbn/HDeZyuU4H9K+9HkraX9qCfIFFbvO+kd+40l/aTHcY/gFi1PEtv7WofaclpfW2cQaoXQLV0XfwfFSJWETf1isGuk5YGQCbksaqF6GJDiLpwGde1VyRHtfP26GgpIz4cCP/fpMAR3o+1Oc08edWSl1nlPVnvUl5W+lKzV46/9LDEd6/2/Shzyeq8SnDYPzPKG1TzT6eIP</diagram></mxfile>
+<mxfile host="Electron" modified="2022-04-19T03:07:47.494Z" agent="5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/17.4.2 Chrome/100.0.4896.60 Electron/18.0.1 Safari/537.36" etag="0053nhGjT17ZatS2FRu0" version="17.4.2" type="device"><diagram id="zMdPa7TFIofes7aEGqtK" name="Page-1">3VjbUtswEP2aTJ/IyHYczGNupB1gyJDOlD51FFux1cjeVJZz4esr2bIdR0mATmCgvCAdrdbSObsrKS1nEG/GHC+jOwgIa9ko2LScYcu2LQt15T+FbAvEczoFEHIaaKMamNInokGk0YwGJG0YCgAm6LIJ+pAkxBcNDHMO66bZHFjzq0scEgOY+piZ6A8aiKjcV/eqHvhKaBjpT3v2ZTEQ49JY7ySNcADrHcgZtZwBBxBFK94MCFPklbwU866PjFYL4yQRL5nwwL9tZ6N7l7vjPw4KhAvk14XexQqzTG+4ZXeZ9NefcdkKVctEeoz65EtqDkw4XWFBzIEbstUsiG1JrSRkqZoJyBlOfx1RQaZL7CtsLaNJYpGImexZyhf2FyGHLAnuM8FoQjQeYL64l7OoUBGG2sjNl7zPjaZrRbggmx1IczUmEBPB5SKRHr1yixk6bh1Lx+26jgJPKxvt6G8hDWIdeGHludZGNrQ8r5DKNQgkgQxV3QUuIgghwWxUo/2cL6K8ItmrbW4Blpq/30SIrc47nAlosi7549tHPT/v/MxZdsvucLM7ONzq3lEBUsi4T05ss0xyzEMiTtg5hZ3i4KScnDAs6KqZzmcXp2vk0ZQkgUQm2Uwmi2wcygC1+Fs8kyWzQTpmNExk25fkES4BFbVU1qSeHohpEBT6kpQ+4VnuT9G+BJqIfG9uv+UODwpxKriM9KgKq/5Io3YdSpsL1LaQp8V5Mffa3UQtv/ZlOc0ZMJ+nMib2taoW8e/yWYZ8Y5IQnpeyQjk0wZQbAjbz65kKlqoqlYTf89RDNXBL5qKJ9EEIiJuY7J2pslnliaRLm91BRmmrbHZrW/etSptt0J+fMEdPjCxmPV/AbmrkaTSBlAoKKkVmmkIjdwTsyQLFcTKoLhAn69craO42TxDrAM3Oe7LsmDVKcqgivDrPT5erTxntHe+jRXvH0KEPs88d6679wWLdMzg2CN6h5VlijROZKct+dSUdAFMKSbfOPP87KkYqOCyqp4RdITseEPLQdZ4L5YsB5ffcNKpyrwyOeBOqZ1ebQnrZpvKoTtsM/IWyO8sd+KqhqmNdGqraHVNV561ULR+FZ3uu6Gr3+V8rLkJ7Ur3jc+WR9rB1N7t52OAJvaajbmd4ceBK9f9IdeCabKh3/F7gvd/LUnbrHxiKy3L9M40z+gs=</diagram></mxfile>

docs/06-advanced-techniques/31-the-secure-shell/index.mdx

@@ -37,15 +37,28 @@ Now in reality there are ways to obscure and protect this secret somewhat, but n
 
 ### Asymmetric Encryption
 
-We we use asymmetric encryption, Alice first creates a 'key pair'. This is two files - a public key and a private key. Alice keeps the private key. She uses this to encrypt the message. Bob receives the public key - he can use this to decrypt the message:
+We we use asymmetric encryption, Alice first creates a 'key pair'. This is two files - a public key and a private key. Alice keeps the private key and sends the public key to Bob:
 
 import asymmetricEncryption from '!!raw-loader!./diagrams/asymmetric-encryption.drawio';
 
 <Drawio content={asymmetricEncryption} />
 
-The fantastic thing about this mechanism is that _only Alice can encrypt messages_ - Bob can decrypt and read the messages, but cannot encrypt them on behalf of Alice. So Alice can keep her key private. Her public key is not sensitive - it can only be used to verify that a message has come from Alice, decrypt the message and ensure the message has not been tampered with.
+Now that Bob has the public key, he creates a secret that only he knows and then encrypts it with Alice's public key. He then sends this secret to Alice. The secret was encrypted by Alice's Public Key - meaning only the associated Private Key can decrypt it. This means _even if someone intercepts the secret_ they cannot decrypt it! Only Alice can, as only Alice has the private key:
 
-Almost all modern day encryption is built on this mechanism - when you open a secure connection to a website, an exchange of keys is made between you and the server[^2].
+
+import asymmetricEncryptionShareSecret from '!!raw-loader!./diagrams/asymmetric-encryption-share-secret.drawio';
+
+<Drawio content={asymmetricEncryptionShareSecret} />
+
+Now Alice has Bob's secret and only she can decrypt it. Once she decrypts it both she and Bob have a shared secret - that no one has been able to intercept. They can now use Symmetric Encryption to exchange messages, safe in the knowledge that the secret is kept just between them.
+
+The fantastic thing about this mechanism is that _only Alice can decrypt messages encrypted with her public key_. Alice can keep her key private. Her public key is not sensitive - it can only be used to encrypt messages for Alice.
+
+Alice can also encrypt messages with her Private Key - anyone who has the Public Key can decrypt them. This means that this is not a secure way to encrypt a message - but it is a very good way to _sign_ a message. Given that only Alice has the private key, only she can encrypt messages with it. This means if she sends a message encrypted with her private key anyone who has the public key can decrypt it to assert it was sent by Alice - she's the only person with the private key.
+
+This method of signing messages with the Private Key is typically called 'signing' - it is not used to keep the message private but instead to verify the identity of the sender.
+
+Most modern day cryptography protocols are based on this technique. In many of them Bob will not actually send back a secret - instead he'll generate _his own_ key-pair and return the Public Key. This is called a 'key exchange'. Almost all modern day encryption is built on this mechanism - when you open a secure connection to a website, an exchange of keys is made between you and the server[^2].
 
 When we use the secure shell to communicate with a remote machine, we will give the remote machine our _public key_, and we will encrypt our communications with the _private key_. This is essential because _other users_ might have access to the remote machine - we don't want them seeing our sensitive data such as passwords or private keys.
 
@@ -309,6 +322,37 @@ ssh effective-shell-aws-linux
 
 There are many other options available for the SSH config file, you can see them all with `man ssh_config`. We'll see some other options in [Chapter 33 - Master the Multiplexer](../33-master-the-multiplexer/index.md).
 
+## Running SSH Commands
+
+You don't need to actually run a shell on a remote machine over SSH to execute commands. You can simply provide the commands that you want to run to the `ssh` program and it will execute them on the server.
+
+Here's an example:
+
+```
+$ ssh effective-shell-aws-linux 'curl effective.sh | ES_EXISTING_FOLDER_ACTION=o sh'
+...
+effective-shell: installed samples version 0.25.1 to '/home/ec2-user/effective-shell'
+effective-shell: read 'effective shell' online at: www.effective-shell.com
+```
+
+In this example we downloaded and ran the Effective Shell samples installer on the server. Now normally when we install the samples, the installer will ask the user whether to overwrite, delete or keep the existing samples. This means that it will be requesting input from the terminal. The `ssh` program is not actually attaching _stdin_ to the remote machine, so we use the `ES_EXISTING_FOLDER_ACTION=o` option to tell the installer to overwrite the samples.
+
+If we wanted to be able to interact with the server, using our terminal to provide input, we can use the `-t` (_request TTY_) parameter:
+
+```
+$ ssh -t effective-shell-aws-linux 'curl effective.sh | sh'
+...
+effective-shell: downloaded samples, version 0.25.1
+effective-shell: preparing to install the 'effective-shell.com' samples...
+effective-shell: the '/home/ec2-user/effective-shell' folder already exists, would you like to:
+effective-shell: [d]elete - remove the existing folder
+effective-shell: [o]verwrite - extract over the existing folder
+effective-shell: [q]uit
+Your choice (d/o/q): d
+```
+
+In this example my terminal is attached to the remote server via SSH, meaning I can use the keyboard to provide input to the installer script.
+
 ## Handling Disconnections
 
 One thing that will soon become a pain if you are regularly SSH-ing into virtual machines is disconnections. This can occur when you lose network connectivity. You might not even notice that a disconnection has occurred - I find it is more common that the `ssh` session is simply frozen and not responding to any input at all.
@@ -386,6 +430,7 @@ We can see that our lookup program has been copied to our server and we can run
 Let's save this definition then close our connection to the server, then copy the definition back to our local machine:
 
 ```
+[ec2-user@ip-172-31-23-196 ~]$ chmod +x ./lookup.py
 [ec2-user@ip-172-31-23-196 ~]$ ./lookup.py cryptography > definition.txt
 [ec2-user@ip-172-31-23-196 ~]$ exit
 logout
@@ -401,12 +446,13 @@ on of messages, and many other related issues), regardless of the used medium su
 ch as pencil and paper or computers.
 ```
 
-That's all there is to it! Copying files and folders to and from remote machines is remarkably easy to do with `scp` once you know the basics of how `ssh` works.
+Before we ran the script on the server, we used the `chmod` (_change file permissions_) command to ensure the script can be executed. That's all there is to it! Copying files and folders to and from remote machines is remarkably easy to do with `scp` once you know the basics of how `ssh` works.
 
 There are many other operations that you can perform with `scp`, you can read more about the tool with `man scp`.
 
 ## Summary
 
 In this chapter we discussed the SSH protocol, and how keys are used to protect connections to remote servers. We saw how to setup an AWS account, create a virtual machine with a given public key, connect to it with the `ssh` program, and configure SSH with an alias to make future connections faster. We also saw some of the challenges we can face with network connectivity - which we'll see techniques to handle in Chapter 33. Finally, we looked at how to copy files to and from remote machines.
 
-[^1]: This process is very useful to know about, it is called Diffie–Hellman key exchange. There are many great articles online that explain it in detail.
+[^1]: My favourite book on this topic is "Applied Cryptography: Protocols, Algorithms, and Source Code in C - Bruce Schneier". There are more details at the end of the chapter and in the [Reading List](../../xx-appendices/reading-list.md).
+[^2]: This process is very useful to know about, it is called Diffie–Hellman key exchange. There are many great articles online that explain it in detail.

sidebars.js

@@ -90,6 +90,7 @@ const sidebars = {
       type: 'category',
       label: 'Appendices',
       items: [
+        'xx-appendices/reading-list',
         'xx-appendices/thanks',
       ]
     },