-------------------------------------------------------------------------------
---  MIKROLOCK HANDBUCH - Version 1.1  ---------- UTF-8-DATEI --- Juni 2016 ---
-------------------------------------------------------------------------------

OSI Certified Open Source Software

-------------------------------------------------------------------------------

MikroLock verbindet moderne Verschlüsselung mit einfacher Bedienung. Es basiert
auf dem offenen miniLock Dateiformat (https://minilock.io/).


INHALT:
-------------------------------------------------------------------------------

1. Übersicht
2. Wie funktioniert's?
3. Funktionen
4. Kompatibilität mit der miniLock-Browsererweiterung
5. Verwendete Crypto-Funktionen
6. Plattformen
7. Kontakt


1.  Übersicht
-------------------------------------------------------------------------------

MikroLock ist eine schnelle Implementierung der miniLock-Spezifikation 
(https://minilock.io/). Trotz des Namens (und im Gegensatz zum Original) kann 
MikroLock auch mit großen Dateien umgehen.

Hauptziel der Entwicklung ist ein unkomplizierter Austausch verschlüsselter
Daten, z.B. durch E-Mail oder Cloud-Dienste. Die Verschlüsselung basiert auf
modernen Public-Key Verfahren, jedoch ohne aufwändige Konfiguration und
Einarbeitung. Das miniLock-Format kann durch die Chrome Erweiterung auch dann
eingesetzt werden, wenn keine Software wie MikroLock installiert werden kann 
(Firmen-Richtlinien o.ä.).

Dreh- und Angelpunkt der Verschlüsselung ist die Lock-ID, die durch Eingabe
von Mail-Adresse und Passwort auf jedem PC berechnet werden kann. 
Diese MiniLock-ID ist ein kurzer Public-Key, der auf Webseiten, in Mailsigna-
turen, auf Twitter oder sonstwo veröffentlicht wird, damit jedermann in der Lage
ist Inhalte für diese ID zu verschlüsseln. Nur ein Empfänger mit der 
richtigen Passwort/Mail-Kombination zur Erzeugung dieser ID kann die Daten 
wieder entschlüsseln.

Eine Lock-ID sieht wie folgt aus: jrcY8VJWKihbiLsDnaMaNSoL2fZSTiRmEeJcKGBYxnb83

Da diese IDs sehr bequem zu handhaben sind, ist kein aufwändiger Schlüsseltausch 
mit Keyservern oder manuellen Dateikopien notwendig.

Beim Verschlüsseln kann eine Liste von Lock-IDs angegeben werden, um 
mehreren Empfängern zu ermöglichen die Daten zu entschlüsseln. Es muss also 
keine separate Datei für jeden Empfänger erzeugt werden. MiniLock-Dateien 
enthalten keine sichtbaren Hinweise auf Ihre Empfänger.


2. Wie funktioniert's?
-------------------------------------------------------------------------------

A möchte etwas für B verschlüsseln. B gibt seine Mail-Adresse und sein Passwort
in MikroLock ein, um seine Lock-ID zu erhalten. Diese ID sendet er an A.
A verschlüsselt die Datei und gibt die Lock-ID von B als Empfänger-ID an.
A sendet nun die verschlüsselte Datei an B, der sie mit seiner Passwort/Mail-
Kombination entschlüsseln kann.
Wichtig hierbei ist, dass das Passwort geheim bleibt - es werden nur die 
Lock-IDs (=public keys) ausgetauscht.


3.  Funktionen
-------------------------------------------------------------------------------

USAGE: mikrolock [OPTION]...
mikrolock reads and writes encrypted miniLock files (https://minilock.io/)

Available options:

  -E, --encrypt <file>  Encrypt the given file (see -r)
  -D, --decrypt <file>  Decrypt the given miniLock file
  -o, --output <file>   Override the target file name (assumes -D or -E)
  -k, --kdf <name>      Key derivation function to use (name: "scrypt" or "argon2")
                        scrypt is the default, argon2 is experimental
  -m, --mail <string>   Mail address (salt for key derivation)
  -r, --rcpt <string>   Recipient's Lock-ID (may be repeated, assumes -E)

  -h, --help            Print this help screen
  -l, --list <file>     Recipient list text file (contains one Lock-ID per line)
                        ID descriptions may be added using these delimiters: space or one of [,;/|-]
  -p, --pinentry        Use pinentry program to ask for the passphrase
  -q, --quiet           Do not print progress information
  -R, --random-name     Generate random output filename; write to current working directory (assumes -E)
  -v, --version         Print version information
  -x, --exclude-me      Exlude own Lock-ID from recipient list (assumes -E)

If neither -E nor -D is given, mikrolock exits after showing your Lock-ID.


Beispiele:
---------

VERSCHLÜSSELUNG:

mikrolock --encrypt libsodium-1.0.0.tar.gz --mail sendersalt@holygrail.com --rcpt EX9k9VmGzjg7mUBFN9mzc7nkcvhmD6fGZTq3nefEajjxX

Please enter your secret passphrase:
Unlocking...
Your Lock-ID: aUwncs2D48MqB8VFta7RRJ5bjL9PfsmtWF3zYVb3zFLLW
Encrypting file libsodium-1.0.0.tar.gz...
Progress 100%
Calculating file hash...
Progress 100%
Destination file: libsodium-1.0.0.tar.gz.minilock

Die verschlüsselte Datei ist libsodium-1.0.0.tar.gz.minilock
Sie kann vom Empfänger EX9k9VmGzjg7mUBFN9mzc7nkcvhmD6fGZTq3nefEajjxX
entschlüsselt werden.


ENTSCHLÜSSELUNG:

mikrolock --decrypt libsodium-1.0.0.tar.gz.minilock --mail receiver@test.org
Please enter your secret passphrase:
Unlocking...
Your Lock-ID: EX9k9VmGzjg7mUBFN9mzc7nkcvhmD6fGZTq3nefEajjxX
Decrypting file libsodium-1.0.0.tar.gz.minilock...
Calculating file hash...
Writing to file libsodium-1.0.0.tar.gz...


4. Kompatibilität mit der miniLock-Browsererweiterung
-------------------------------------------------------------------------------

Das miniLock Dateiformat wurde mit der Chrome-Erweiterung miniLock eingeführt.
MiniLock-Dateien können mit beiden Programmen verarbeitet werden, allerdings
unterscheiden sich die akzeptierten Eingaben zur Erzeugung der Lock-ID:

 * miniLock akzeptiert nur IDs die mit scrypt erzeugt wurden

 * miniLock nimmt nur gültige Mailadressen als Salt-Wert an; MikroLock jedoch
   jeden Wert

 * miniLock prüft die Mindest-Entropie des Passworts; MikroLock könnte auch
   ein Passwort mit geringerer Entropie akzeptieren

Sollten Sie MikroLock und miniLock im Wechsel benutzen wollen, vwerwenden Sie 
scrypt als KDF und prüfen Sie, ob Salt und Passwort in beiden Programmen gültige 
Eingaben sind.


5. Verwendete Crypto-Funktionen
-------------------------------------------------------------------------------

Die Lock-ID wird wie folgt erzeugt:

secret_key :=      scrypt (blake2(passphrase), mail, 131072, 1) 
               OR argon2i (blake2(passphrase), generichash(mail), 
                           OPSLIMIT_SENSITIVE, MEMLIMIT_SENSITIVE)
          
public_key := crypto_scalarmult_base (secret_key) 

Lock-ID := base58 ( public_key + blake2(public_key) )

Zur Berechnung von secret_key kann vom Benutzer scrypt oder Argon2 gewählt werden.
Die Parameter für scrypt wurden von miniLock übernommen, die für Argon2 ent-
sprechen der Empfehlung für vertrauliche Daten.

Der JSON-Dateiheader der MiniLock-Dateien enthält die Lock-ID des
Senders, die IDs der Empfänger sowie Schlüssel (zufällig erzeugt) und
Hashwert der verschlüsselten Eingabedatei. Diese Informationen werden separat 
mit jeder angegebenen Empfänger-ID als Public-Key mittels crypto_box_easy 
verschlüsselt (Schlüsseltausch: Curve25519; Verfahren: XSalsa20 stream cipher;
Authentifizierung: Poly1305 MAC).

Die Eingabedatei wird mit crypto_secretbox_easy verschlüsselt
(Verfahren: XSalsa20 stream cipher; Authentifizierung: Poly1305 MAC).

Mehr Infos zu den kryptographischen Eigenschaften und dem Dateiformat:
https://minilock.io.

https://doc.libsodium.org/password_hashing/index.html
https://blake2.net
https://en.wikipedia.org/wiki/Base58
https://download.libsodium.org/libsodium/content/password_hashing/scrypt.html
https://download.libsodium.org/libsodium/content/password_hashing/the_argon2i_function.html
https://doc.libsodium.org/advanced/scalar_multiplication.html
https://doc.libsodium.org/public-key_cryptography/authenticated_encryption.html


6.  Plattformen
-------------------------------------------------------------------------------

MikroLock ist für Linux und Windows verfügbar.


7.  Kontakt
-------------------------------------------------------------------------------

Andre Simon
andre.simon1@gmx.de
http://www.andre-simon.de/
http://wiki.andre-simon.de/
