Merge branch 'develop'

Author: mguentner

README.md

@@ -2,6 +2,7 @@
 *tssh* manages [TPM](https://trustedcomputinggroup.org/resource/tpm-library-specification/)-backed keys that are ready to use with *ssh*.
 Its main focus is to be as stateless as possible by leveraging the fact that TPMs can derive keys deterministically.
 By default, TSSH uses the username, hostname and port as the salt for key derivation, thereby ensuring that each host has a unique public key. Furthermore, TSSH ensures that the SSH server is offered only the correct key.
+Check further down for detailed diagrams.
 
 ## Prerequisites
 
@@ -20,7 +21,7 @@ Execute the following from the project route:
 
 
  ```console
-cargo --path ./tssh/ --locked
+cargo install --path ./tssh/ --locked
  ```
 
 ## Nix tests
@@ -77,6 +78,23 @@ localhost $> ssh user@example.com
 user@example.com $>
 ```
 
+# Diagrams
+
+## Architecture
+<div style="width: 100%;">
+  <img src="architecture.svg" style="width: 100%;" alt="Diagram of the architecture of tssh" />
+</div>
+
+## Key Creation
+<div style="width: 100%;">
+  <img src="key-creation.svg" style="width: 100%;" alt="Diagram of how keys are created by tssh" />
+</div>
+
+## SSH Login
+<div style="width: 100%;">
+  <img src="ssh-login.svg" style="width: 100%;" alt="Diagram of how a ssh login work with tssh" />
+</div>
+
 # Features planned
 * [ ] Key import
 * [ ] Keys with pin

architecture.d2

@@ -0,0 +1,27 @@
+vars: {
+  d2-config: {
+    layout-engine: elk
+  }
+}
+
+CLIENT: Client {
+  PKCS: PKCS11\nDynamic lib
+  TPM: TPM {
+    shape: page
+  }
+  FILE: SSH Config
+  SQLITE: SQlite
+  TSSH: TSSH
+  SSH: SSH Client
+  TSSH -> FILE
+  TSSH <-> SQLITE
+  TSSH <-> TPM
+  PKCS <-> TPM
+  PKCS <-> SQLITE
+  SSH -> PKCS
+  SSH <- FILE
+}
+
+HOST: SSH Server
+
+HOST <-> CLIENT.SSH

architecture.svg

@@ -0,0 +1,16 @@
+TSSH Key creation flow: {
+  shape: sequence_diagram
+
+  TSSH: TSSH
+  TPM: TPM
+  SQLITE: SQlite
+  FILE: SSH Config Files
+
+  TSSH -> TSSH: Derive best core template:\nAlgorithm,..
+  TSSH -> TSSH: Enrich template with salt:\nuser@host:22
+  TSSH -> TPM: Request public key\n for template
+  TPM -> TPM: Derive key pair\n with template
+  TPM -> TSSH: Public key
+  TSSH -> SQLite: Store Template
+  TSSH -> File: Write host config
+}

key-creation.d2

@@ -0,0 +1,24 @@
+SSH Login flow: {
+  shape: sequence_diagram
+
+  CLIENT: SSH Client
+  SQLITE: SQlite
+  FILE: SSH Config Files
+  PKCS11: PKCS11 lib
+  TPM: TPM
+  SERVER: SSH Server
+
+  CLIENT -> FILE: Lookup public key for user@host
+  FILE -> CLIENT: Public key
+  CLIENT -> SERVER: Offer public key
+  SERVER -> CLIENT: Challenge
+  CLIENT -> PKCS11: Key, challenge
+  PKCS11 -> SQLite: Lookup key
+  SQLITE -> PKCS11: Template
+  PKCS11 -> TPM: Derive key pair\nfor template
+  TPM -> TPM: Key pair
+  PKCS11 -> TPM: Challenge
+  TPM -> PKCS11: Solved challenge
+  PKCS11 -> CLIENT: Solved challenge
+  CLIENT -> SERVER: Solve challenge
+}