MikroLock manual

MikroLock combines modern cryptography and ease of use. It is based on the open miniLock file format (https://minilock.io/).

Overview

MikroLock is a fast native implementation of the minilock file format. Despite its name (and in contrast to the original Chrome extension), it can also handle BIG files.

The main goal of development is to provide an easy exchange of encrypted data using mail or cloud services. MikroLock is based on modern public key encryption without configuration or learning efforts. The miniLock file format is also understood by the Chrome browser extension of the same name, this might help if corporate rules do not allow an installation of MikroLock.

The key element of encryption is the Lock-ID, which can be calculated on any computer, based on a mail address and a passphrase. This Lock-ID is a short public key to be published on websites, mail signatures, twitter etc. to enable anyone to encrypt data for this ID. Only the receiver who applies the correct mail and passphrase to derive the same ID can decrypt the content.

A Lock-ID looks like this: jrcY8VJWKihbiLsDnaMaNSoL2fZSTiRmEeJcKGBYxnb83

Since the Lock-IDs are very comfortable to handle, there is no need for a cumbersome key exchange process like using keyservers or manually copying key files to hosts.

A sender can define a list of Lock-IDs to let multiple recipients decrypt the file. A minilock file does not contain any visible information about its recipients.

How does it work?

A wants to encrypt a file for B. B enters his mail address and passphrase into MikroLock to obtain his Lock-ID. He sends this ID to A.
A encrypts the file and adds B's Lock-ID as recipient ID. A now sends the encrypted file to B, who is able to decrypt it using his passphrase/mail combination.
It is important to keep the passphrase secret - only the Lock-IDs (=public keys) are being exchanged.

The graphical interface

After the program starts it asks for your mail adress and passphrase. Using this information a pair of private and public key is generated using the selected key derivation function (scrypt or Argon2).
Important: To calculate a specific Lock-ID you need to enter the same combination of mail address, password and function.
You do not need to enter a valid mail address unless you want to use the miniLock Chrome extension.
To achieve a secure encryption, a passphrase less than 40 characters needs to consist of several random words.



MikroLock GUI 1

It is also possible to enter Unicode characters:



MikroLock GUI 1

The mail icon shows whether the mail adress is valid:

Icon 1 the mail address appears to be valid
Icon 1 the mail address appears to be invalid


The signal icon gives you following information::
Icon 1 the passphrase is too short (minimum length: 20 characters)
Icon 1 the passphrase needs to consist of at least five words. It might be refused by the original MiniLock-Plugin for Chrome
Icon 1 the passphrase offers sufficient security
After clicking "Generate my Lock-ID" your ID will be shown at the window bottom. You are able to copy it nearby.

Now the input/output dialog is displayed:



MikroLock GUI 1

Here you choose the destination directory and the file to encrypt or decrypt (if the program was called with a file as argument, its path is shown in the statusbar).
You may also drag and drop a file onto the window.
If a minilock file was selected, it will be automatically decrypted. Any other file will be encrypted in the next screen:



MikroLock GUI 1

Using the upper list you define the Lock-IDs of your file recipients.
Press "Read list file" to import a text file which contains one Lock-ID per line. The recipient's names may be entered behind their IDs as follows:

y5qBLmncv36r98tFMw5YVoc9SHkfLDg8Wz7zf9yrPYPh2 / Andre Simon
8SmHNEEZiK1RgWoN9xryJb8opBky9Kh7txhmgb1RLrUrW ; Customer XYZ
sVXHR7smwqXkSbphn8gdH3Ah6a1nvbYtuXPpxG6qKT321 - Schmidt
ULgpTbP7isNNV6kgDbNVtQo5YRuUhc4N5AAEEbne9bjJi | Jane
The information behind the separators will be displayed as tooltips.

The button "Clear recipients" will delete the ID entries.
The option "Omit my ID" removes your own Lock-ID from the recipients, preventing you from opening the encrypted file.
Applying "Generate a random output filename" will save the encrypted file using a randomized name.

After clicking "Encrypt the file" the minilock file will be stored in the previously defined destination directory.

The command line interface

Apart from the graphical user interface, MikroLock also offers a command line executable.

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.

Command line examples

File encryption

mikrolock --encrypt secret.data --mail sendersalt@holygrail.com --rcpt EX9k9VmGzjg7mUBFN9mzc7nkcvhmD6fGZTq3nefEajjxX
Please enter your secret passphrase:
Unlocking...
Your Lock-ID: aUwncs2D48MqB8VFta7RRJ5bjL9PfsmtWF3zYVb3zFLLW
Encrypting file secret.data...
Progress 100%
Calculating file hash...
Progress 100%
Destination file: secret.data.minilock

The encrypted file is secret.data.minilock
This file can be decrypted by the receiver EX9k9VmGzjg7mUBFN9mzc7nkcvhmD6fGZTq3nefEajjxX

File decryption

mikrolock --decrypt secret.data.minilock --mail receiver@test.org
Please enter your secret passphrase:
Unlocking...
Your Lock-ID: EX9k9VmGzjg7mUBFN9mzc7nkcvhmD6fGZTq3nefEajjxX
Decrypting file secret.data.minilock...
Calculating file hash...
Progress 100%
Writing to file secret.data...
Progress 100%
Destination file: secret.data

Compatibility with the miniLock browser extension

The miniLock file format was established by the miniLock Chrome browser extension.
While the produced files are interchangeable with each program, the accepted input to obtain a Lock-ID differs:

If you are going to use MikroLock and miniLock in parallel, choose a salt and passphrase which is accepted in both applications.

Applied crypto functions

A Lock-ID is defined as:

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) )

The user may choose scrypt or Argon2 to calculate the secret_key. Scrypt parameters were taken from miniLock, whereas Argon2 parameters are recommended for handling sensitive data.

The JSON header of a miniLock file contains the sender's Lock-ID, the recipient's IDs, file hash and the random key of the encrypted input file.

This information is encrypted separately with each given recipient ID as public key using crypto_box_easy (key exchange: Curve25519; encryption: XSalsa20 stream cipher; authentication: Poly1305 MAC).

The input file is encrypted using crypto_secretbox_easy (encryption: XSalsa20 stream cipher; authentication: Poly1305 MAC).

Read more about the cryptographic details and the file format: https://minilock.io.