This repository has been archived by the owner on Jun 5, 2018. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 2
/
README
202 lines (144 loc) · 7.49 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
-------------------------------------------------------------------------------
--- MIKROLOCK MANUAL - Version 1.1 ------------- UTF-8 FILE --- June 2016 ---
-------------------------------------------------------------------------------
OSI Certified Open Source Software
-------------------------------------------------------------------------------
MikroLock combines modern cryptography and ease of use. It is based on the open
miniLock file format (https://minilock.io/).
CONTENT:
-------------------------------------------------------------------------------
1. Overview
2. How does it work?
3. Features
4. Compatibility with the miniLock browser extension
5. Applied crypto functions
6. Platforms
7. Contact
1. Overview
-------------------------------------------------------------------------------
MikroLock 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.
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 may also be
applied using the Chrome extension, 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 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. There is no need to generate a new file for each receiver.
A minilock file does not contain any visible information about its recipients.
Read more about the cryptographic details: https://minilock.io.
2. 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.
3. Features
-------------------------------------------------------------------------------
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.
Examples:
---------
ENCRYPTION
mikrolock --encrypt secret.data --mail [email protected] --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
DECRYPTION
mikrolock --decrypt secret.data.minilock --mail [email protected]
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
4. 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:
* miniLock only supports Lock-IDs generated by scrypt
* miniLock accepts only valid mail addresses as salt; MikroLock accepts any
value
* miniLock applies a passphrase entropy check; MikroLock may accept passphrases
with lower entropy
If you are going to use MikroLock and miniLock in parallel, choose scrypt as kdf,
and check whether salt and passphrase are being accepted in both applications.
5. 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.
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. Platforms
-------------------------------------------------------------------------------
MikroLock is currently available for Linux and Windows.
7. Contact
-------------------------------------------------------------------------------
Andre Simon
http://www.andre-simon.de/
http://wiki.andre-simon.de/