"Fossies" - the Fresh Open Source Software Archive

Member "mikrolock-1.2.1/README" (2 Sep 2019, 7692 Bytes) of package /linux/privat/mikrolock-1.2.1.tar.bz2:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README": 1.2_vs_1.2.1.

    1 -------------------------------------------------------------------------------
    2 ---  MIKROLOCK MANUAL - Version 1.2  ------------ UTF-8 FILE --- March 2018 ---
    3 -------------------------------------------------------------------------------
    4 
    5 OSI Certified Open Source Software
    6 
    7 -------------------------------------------------------------------------------
    8 
    9 MikroLock combines modern cryptography and ease of use. It is based on the open
   10 miniLock file format (https://minilock.io/).
   11 
   12 
   13 CONTENT:
   14 -------------------------------------------------------------------------------
   15 
   16 1. Overview
   17 2. How does it work?
   18 3. Features
   19 4. Compatibility with the miniLock browser extension
   20 5. Applied crypto functions
   21 6. Platforms
   22 7. Contact
   23 
   24 
   25 1.  Overview
   26 -------------------------------------------------------------------------------
   27 
   28 MikroLock is a fast native implementation of the minilock file format.
   29 Despite its name (and in contrast to the original implementation), it can also 
   30 handle BIG files.
   31 
   32 The main goal of development is to provide an easy exchange of encrypted data
   33 using mail or cloud services. MikroLock is based on modern public key encryption
   34 without configuration or learning efforts. The miniLock file format may also be
   35 applied using the Chrome extension, this might help if corporate rules do not
   36 allow an installation of MikroLock.
   37 
   38 The key element of encryption is the Lock-ID, which can be calculated on 
   39 any computer, based on a mail address and a passphrase.
   40 This Lock-ID is a short public key to be published on websites, mail
   41 signatures, twitter etc. to enable anyone to encrypt data for this ID. 
   42 Only the receiver who applies the correct mail and passphrase to derive the 
   43 same ID can decrypt the content.
   44 
   45 A Lock-ID looks like this: jrcY8VJWKihbiLsDnaMaNSoL2fZSTiRmEeJcKGBYxnb83
   46 
   47 Since Lock-IDs are very comfortable to handle, there is no need for a
   48 cumbersome key exchange process like using keyservers or manually copying key
   49 files to hosts.
   50 
   51 A sender can define a list of Lock-IDs to let multiple recipients decrypt 
   52 the file. There is no need to generate a new file for each receiver.
   53 A minilock file does not contain any visible information about its recipients.
   54 
   55 Read more about the cryptographic details: https://minilock.io.
   56 
   57 
   58 2. How does it work?
   59 -------------------------------------------------------------------------------
   60 
   61 A wants to encrypt a file for B. B enters his mail address and passphrase into
   62 MikroLock to obtain his Lock-ID. He sends this ID to A.
   63 A encrypts the file and adds B's Lock-ID as recipient ID. A now sends the
   64 encrypted file to B, who is able to decrypt it using his passphrase/mail
   65 combination.
   66 It is important to keep the passphrase secret - only the Lock-IDs (=public
   67 keys) are being exchanged.
   68 
   69 
   70 3.  Features
   71 -------------------------------------------------------------------------------
   72 
   73 USAGE: mikrolock [OPTION]...
   74 mikrolock reads and writes encrypted miniLock files (https://minilock.io/)
   75 
   76 Available options:
   77 
   78   -E, --encrypt <file>  Encrypt the given file (see -r)
   79   -D, --decrypt <file>  Decrypt the given miniLock file
   80   -o, --output <file>   Override the target file name (assumes -D or -E)
   81   -k, --kdf <name>      Key derivation function to use (name: "scrypt" or "argon2")
   82                         scrypt is the default, argon2 is experimental
   83   -m, --mail <string>   Mail address (salt for key derivation)
   84   -r, --rcpt <string>   Recipient's Lock-ID (may be repeated, assumes -E)
   85 
   86   -h, --help            Print this help screen
   87   -l, --list <file>     Recipient list text file (contains one Lock-ID per line)
   88                         ID descriptions may be added using these delimiters: space or one of [,;/|-]
   89   -p, --pinentry        Use pinentry program to ask for the passphrase
   90   -q, --quiet           Do not print progress information
   91   -R, --random-name     Generate random output filename; write to current working directory (assumes -E)
   92   -v, --version         Print version information
   93   -x, --exclude-me      Exlude own Lock-ID from recipient list (assumes -E)
   94 
   95 If neither -E nor -D is given, mikrolock exits after showing your Lock-ID.
   96 
   97 
   98 Examples:
   99 ---------
  100 
  101 ENCRYPTION
  102 
  103 mikrolock --encrypt secret.data --mail sendersalt@holygrail.com --rcpt EX9k9VmGzjg7mUBFN9mzc7nkcvhmD6fGZTq3nefEajjxX
  104 
  105 Please enter your secret passphrase:
  106 Unlocking...
  107 Your Lock-ID: aUwncs2D48MqB8VFta7RRJ5bjL9PfsmtWF3zYVb3zFLLW
  108 Encrypting file secret.data...
  109 Progress 100%
  110 Calculating file hash...
  111 Progress 100%
  112 Destination file: secret.data.minilock
  113 
  114 The encrypted file is secret.data.minilock
  115 This file can be decrypted by the receiver EX9k9VmGzjg7mUBFN9mzc7nkcvhmD6fGZTq3nefEajjxX
  116 
  117 
  118 DECRYPTION
  119 
  120 mikrolock --decrypt secret.data.minilock --mail receiver@test.org
  121 Please enter your secret passphrase:
  122 Unlocking...
  123 Your Lock-ID: EX9k9VmGzjg7mUBFN9mzc7nkcvhmD6fGZTq3nefEajjxX
  124 Decrypting file secret.data.minilock...
  125 Calculating file hash...
  126 Progress 100%
  127 Writing to file secret.data...
  128 Progress 100%
  129 Destination file: secret.data
  130 
  131 
  132 4. Compatibility with the miniLock browser extension
  133 -------------------------------------------------------------------------------
  134 
  135 The miniLock file format was established by the miniLock Chrome browser
  136 extension. While the produced files are interchangeable with each program, the
  137 accepted input to obtain a Lock-ID differs:
  138 
  139  * miniLock only supports Lock-IDs generated by scrypt
  140  
  141  * miniLock accepts only valid mail addresses as salt; MikroLock accepts any
  142    value
  143 
  144  * miniLock applies a passphrase entropy check; MikroLock may accept passphrases
  145    with lower entropy
  146 
  147 If you are going to use MikroLock and miniLock in parallel, choose scrypt as kdf, 
  148 and check whether salt and passphrase are being accepted in both applications.
  149 
  150 
  151 5. Applied crypto functions
  152 -------------------------------------------------------------------------------
  153 
  154 A Lock-ID is defined as:
  155 
  156 secret_key :=      scrypt (blake2(passphrase), mail, 131072, 1) 
  157                OR argon2i (blake2(passphrase), generichash(mail), 
  158                            OPSLIMIT_SENSITIVE, MEMLIMIT_SENSITIVE)
  159           
  160 public_key := crypto_scalarmult_base (secret_key) 
  161 
  162 Lock-ID := base58 ( public_key + blake2(public_key) )
  163 
  164 The user may choose scrypt or Argon2 to calculate the secret_key.
  165 Scrypt parameters were taken from miniLock, whereas Argon2 parameters are 
  166 recommended for handling sensitive data.
  167 
  168 The JSON header of a miniLock file contains the sender's Lock-ID,
  169 the recipient's IDs, file hash and the random key of the encrypted input file.
  170 This information is encrypted separately with each given recipient ID as public
  171 key using crypto_box_easy
  172 (key exchange: Curve25519; encryption: XSalsa20 stream cipher; authentication:
  173 Poly1305 MAC).
  174 
  175 The input file is encrypted using crypto_secretbox_easy
  176 (encryption: XSalsa20 stream cipher; authentication: Poly1305 MAC).
  177 
  178 Read more about the cryptographic details and the file format:
  179 https://minilock.io.
  180 
  181 https://doc.libsodium.org/password_hashing/index.html
  182 https://blake2.net
  183 https://en.wikipedia.org/wiki/Base58
  184 https://download.libsodium.org/libsodium/content/password_hashing/scrypt.html
  185 https://download.libsodium.org/libsodium/content/password_hashing/the_argon2i_function.html
  186 https://doc.libsodium.org/advanced/scalar_multiplication.html
  187 https://doc.libsodium.org/public-key_cryptography/authenticated_encryption.html
  188 
  189 
  190 6.  Platforms
  191 -------------------------------------------------------------------------------
  192 
  193 MikroLock is currently available for Linux and Windows.
  194 
  195 
  196 7.  Contact
  197 -------------------------------------------------------------------------------
  198 
  199 Andre Simon
  200 andre.simon1@gmx.de
  201 http://www.andre-simon.de/
  202 
  203 Git-Repo: https://gitlab.com/saalen/mikrolock