mlock manual

mlock reads and writes encrypted miniLock files.

Overview

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

A short description of minilock's benefits (source: https://minilock.io):
" Enter your miniLock passphrase on any computer, and you'll get access to your miniLock ID. No key storage or management — just a single passphrase to access your miniLock identity anywhere. miniLock uses modern cryptographic primitives to accomplish this securely. "

A minilock ID is a short public key derived from a secret passphrase and an E-mail address. This ID may 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 this ID can decrypt the content.

A minilock ID looks like this: jrcY8VJWKihbiLsDnaMaNSoL2fZSTiRmEeJcKGBYxnb83

Since the minilock 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 minilock 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 mlock to obtain his miniLock ID. He sends this ID to A.
A encrypts the file and adds B's miniLock 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 miniLock IDs (=public keys) are being exchanged.

The graphical interface

After the program starts it asks for your mail adress and passphrase. With this information a key pair is generated (private and public key).
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.

It is also possible to enter Unicode characters:

The mail icon shows whether the mail adress is valid:

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

The signal icon gives you following information::

	the passphrase is too short or does not contain enough words (separated by spaces)
	the passphrase will most likely be refused by the original MiniLock-Plugin for Chrome
	the passphrase offers sufficient security

After clicking "Generate my miniLock ID" your ID will be shown at the window bottom. You are able to copy it nearby.

Now the input/output dialog is displayed:

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:

Using the upper list you can define up to 50 miniLock IDs of your file recipients.
Using "Read list file" you can import a text file which contains one miniLock 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 the own miniLock-ID from the recipients.
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, mlock also offers a command line executable.

USAGE: mlock [OPTION]...
mlock 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)
  -m, --mail <string>   User mail address (salt)
  -r, --rcpt <string>   Recipient's miniLock ID (may be repeated up to 50x, assumes -E)
  -R, --random-name     Generate random output filename; write to current working directory (assumes -E)
  -x, --exclude-me      Exlude own miniLock ID from recipient list (assumes -E)
  -p, --pinentry        Use pinentry for passphrase input
  -q, --quiet           Do not print progress information
  -h, --help            Print this help screen
  -v, --version         Print version information

If neither -E nor -D is given, mlock exits after showing your miniLock ID.

Command line examples

File encryption

mlock --encrypt libsodium-1.0.0.tar.gz --mail sendersalt@holygrail.com --rcpt EX9k9VmGzjg7mUBFN9mzc7nkcvhmD6fGZTq3nefEajjxX
Please enter your secret passphrase:
Unlocking...
Your miniLock-ID: aUwncs2D48MqB8VFta7RRJ5bjL9PfsmtWF3zYVb3zFLLW
Encrypting file libsodium-1.0.0.tar.gz...
Calculating file hash...
Task completed.

The encrypted file is libsodium-1.0.0.tar.gz.minilock
This file can be decrypted by the receiver EX9k9VmGzjg7mUBFN9mzc7nkcvhmD6fGZTq3nefEajjxX

File decryption

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

Applied crypto functions

The Minilock-ID is defined as:

secret := scrypt(blake2(passphrase), mail, 131072, 1)
id := base58( crypto_scalarmult_base(secret) + blake2(secret) )

The JSON header of a miniLock file contains the sender's miniLock 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 with crypto_secretbox_easy (encryption: XSalsa20 stream cipher; authentication: Poly1305 MAC).

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