====== JokerChain ======
===== Setup und Verwendung =====
==== Nötige Software ====

  * git (plus OpenSLL, ist in git for Windows dabei), Python und VisualStudio Code, siehe [[lehrkraefte:blc:informatik:glf22:technisches|Anleitungen hier]]

==== Setup der JokerChain ====
Screencast dazu auf dem [[https://fginfo.ksbg.ch/~ivo/videos/informatik/22-23/03-setup-der-jokerchain.mp4|Web]] oder auf [[https://web.microsoftstream.com/video/4fa2f480-7175-4ad5-a6bf-72c1b8931047|Stream]]
  * git bash starten
  * in geeigntes Verzeichnis gehen: ''cd pfadangabe''
  * ''git clone https://github.com/techlabksbg/jokerchain.git''
  * ''cd jokerchain''
  * Erster Test: ''python jokerchain.py''
    * Schlägt fehl, weil ein package fehlt. Also dieses installieren mit
    * ''pip install requests''
    * Und dann gleich noch pip updaten mit
    * ''pip install --upgrade pip''
  * Bereits existierende Schlüssel ins Verzeichnis kopieren oder
    * Neue Schlüssel anlegen (nur wenn noch keiner vorhanden): ''python jokerchain.py -n''
    * Die Datei ''public-key-joker.pem'' an ivo.bloechliger@ksbg.ch senden.
    * Die Datei ''secret-private-key-joker.pem'' sicher verwahren und mindestens ein Backup erstellen.

==== Update der Chain ====
  * ''cd'' ins Verzeichnis, wo das Pythonprogramm ''jokerchain.py'' gespeichert ist.
  * ''git pull''  (lädt die neueste Version herunter).

==== Joker einlösen ====
  * ''python jokerchain.py -d 2022-08-29'' wobei das Datum in diesem Format (JJJJ-MM-TT) und in der Zukunft liegen muss.
==== Joker transferieren ====
  * ''python jokerchain.py -t c001f4c3'' wobei nach -t ein existierender Hash eines anderen Nutzers stehen muss. **Achtung**, die Überweisung eines Jokers an den Admin zählt nicht als Einlösen!
==== Transaktionen und Kontostand anschauen ====
  * ''python jokerchain.py''
==== Weitere Optionen ====
  * ''python jokerchain.py -h''  Hilfe anzeigen
  * ''python jokerchain.py -v ...''  Verbose: Anzeigen was, das Programm so alles tut.

====== Technische Umsetzung mit openssl ======
Das Python-Script ''jokerchain.py'' führt die im folgenden erklärten openssl-Kommandos aus. Es ist im Prinzip möglich, alle Manipulation auch «von Hand» auszuführen und so neue valide Einträge zu erstellen.
===== Schlüsselerzeugung =====
In Git-Bash:
<code txt>
openssl ecparam -name prime256v1 -genkey -noout -out secret-private-key-joker.pem
openssl ec -in secret-private-key-joker.pem -pubout -out public-key-joker.pem
</code>

===== Unterschrift =====
==== Unterschreiben ====

in Git-Bash:
<code txt>
openssl dgst -sha256 -sign secret-private-key-joker.pem -out signature.bin ZU_SIGNIERENDE_DATEI
openssl enc -base64 -in signature.bin -out signature.base64
</code>
[[https://opensource.com/article/19/6/cryptography-basics-openssl-part-2|Quelle]]

==== Verifizieren ====
<code txt>
openssl enc -base64 -d -in signature.base64 -out signature.bin
openssl dgst -sha256 -verify public-key-joker.pem -signature signature.bin SIGNIERTE_DATEI
</code>

====== Dateiformat ======
Die «Blockchain» ist im [[https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax|«Markdown» Format]] gespeichert. Damit lässt sich die Datei ebensogut maschinell verarbeiten wie von Menschen gelesen werden.

Die Datei enthält nur ASCII-Zeichen und Zeilenumbrüche sind \n (keine \r\n)

===== Generelle Einträge =====
<code txt>
# Titel (Art des Eintrags)
## Name der Daten
... (Daten)
## Evtl. weitere Einträge
</code>

===== Root-Eintrag (Admin, Verwalter) =====
  * Public-Key vom Verwalter, muss der erste Eintrag in der Datei sein.
<code txt>
# root
## publickey
publickey data
## keyhash
fe736c7d89a8b
</code>
Darauf muss eine rootsignature folgen:
===== Einträge validieren =====
<code txt>
# rootsignature
## timestamp
Datum und Zeit der Unterschrift.
## signature
Signatur der ganzen Datei bis und mit der Zeile davor (inkl. ## signature\n)
</code>

===== User-Konto mit Jokern anlegen =====
<code txt>
# user
## publickey
publickey data
## keyhash
fe736c7d89a8b
## tokens
list of joker tokens
</code>
Darauf muss eine ''# rootsignature'' folgen.
===== Überweisung =====
<code txt>
# transfer
## sender
keyhash
## token
token
## receiver
keyhash
## timestamp
timestamp
## signature
Signatur der ganzen Datei bis und mit ## signature\n
</code>
Hinweis: Der Sender kann auch der Admin sein, der damit neue Joker erschaffen kann. Das ist nötig, wenn z.B. ein Joker eingelöst wurde, die Schülerin aber wegen Krankheit gar nicht anwesend war. Oder sich der Lehrer mal wieder zu spät bewusst wird, dass die Miniaufgabe «ungeeignet» war.

===== Joker Einlösen =====
<code txt>
# usejoker
## sender
hash
## token
token
## usedate
JJJJ-MM-TT
## timestamp
timestatmp
## signature
Signatur der ganzen Datei bis und mit ## signature\n
</code>