Heavily update README and example profiles

README.md

@@ -4,14 +4,20 @@ Java based File Syncing Tool
 [![Latest Release](https://img.shields.io/github/release/mgoellnitz/JFileSync3.svg)](https://github.com/mgoellnitz/JFileSync3/releases/latest)
 [![Dependency Status](https://www.versioneye.com/user/projects/54fff1994a1064db0e000071/badge.svg?style=flat)](https://www.versioneye.com/user/projects/54fff1994a1064db0e000071)
 
-File Syncing with optional Compression and Encryption for Local and WebDAV Folders. For local folders encryption can use
+File syncing with optional compression and encryption for local and WebDAV folders. For local folder encryption can use
 EncFS and thus be compatible with encfs4win, BoxCryptor Classic, Encdroid and so on. (With GUI, command line, and stored
 profiles.)
 
-This software was developed because I personally needed a easy to use syncing tool to have everyday backups of highly
+This software was developed because I personally needed an easy to use syncing tool to have everyday backups of highly
 confidential material - business and private. And none of the services I came accross could suite these needs.
 
-It is heavily based on the work of Jens Heidrich and the JFileSync2.2
+The second reason why I find it helpful is, that I very much rely on online-syncing tools for everyday backups and felt
+forced to use more than one of these services. Using too many of them slows down your local machine too much, so I
+identified a set of backup areas which didn't need online syncing but just regular cloud based backup. Some of the
+syncing services available provide WebDAV backends, so I can decide to use a service online or manual (scheduled).
+
+It is heavily based on the work of Jens Heidrich and the JFileSync2.2. After some hacking aroung in his code I felt that
+this one here is a fork, ripping out his original remove backends and changing the purpose quite a lot.
 
 JFileSync is a SourceForge project and available via the following URL:
 
@@ -20,39 +26,43 @@ http://jfilesync.sourceforge.net/
 ```
 
 Don't mix the derived work here and his clean software on sourceforge. Only bother him if it's related to his original
-version. Other complaints go here :-)
+version. Other complaints go here :-) Feel free to add any issues to this project here.
 
 Other contributions - though not directly committed by him - are from https://github.com/srmo
 
-Scenario:
+Online Scenario
+---------------
 
-You replaced regular backups with online syncing tools like SugarSync, Syncplicity, Copy.com, Yandex Drive, Dropbox,
-Wuala, Google Drive, Mega, and so on. After having synced your media files, downloaded software, publicly available
-documents you come to the more confidential stuff...
+You replaced (or want to) your regular backups with online syncing tools and don't have backup media anymore.
+This helps doing backups of your work in remote situations where e.g. don't want to carry confidential backup media
+with you.
 
 Possible Solutions:
 
-a) Trust the providers: Select any of them - I'll write a review for some of them once I find the time.
+a) Trust the providers
 
-b) Trust the providers encryption: use Teamdrive, Wuala, or iDrive Sync. With Teamdrive you can - in some cases - even see the encrypted files depending on the backend you use. With Wuala you once again have to trust that it's really secure especially since they came up with the nice sharing solutions. With iDrive Sync you have to provide a custom password as a base for the generated keys (This rips out some functions like sharing which gives you a hint, that they really do what they are saying).
+Select any of them - I have some personal notes on the in the wiki.
 
-c) Encrypt locally on every file access and thus only sync encrypted stuff which you can still see. Boxcryptor, EncFS come into my mind. Disadvantage here is the de- and encryption on nearly every access. Really locally stored are only the encrypted files.
+b) Trust the providers encryption
 
-d) If you trust your local system and need to store frequently accessed files, you would like to encrypt only short before or on backing up/syncing files. This is where this software fills the gap. It can sync directories, local or webdav, and it can do this with either of these encrypted. Additionally it can sync with encfs volumes stored in local folders (which in turn can be synchronized and used in the net via encfs, encfs4win, BoxCryptor, and Encdroid)
+Use Teamdrive, or iDrive Sync. With Teamdrive you can - in some cases - even see the encrypted files depending on the
+backend you use. With iDrive Sync you have to provide a custom password as a base for the generated keys
+(This rips out some functions like sharing which gives you a hint, that they really do what they are saying).
 
+c) Encrypt locally on every file access and thus only sync encrypted stuff which you can still see.
 
-Introduction
-------------
+Boxcryptor, EncFS come into my mind. Disadvantage here is the de- and encryption on nearly every access.
+Really locally stored are only the encrypted files.
 
-JFileSync is used to synchronize directories of (usually) two different file systems.
+d) If you trust your local system and need to store frequently accessed files, you would like to encrypt only short before or on backing up/syncing files.
 
-What you have to do, to use JFileSync3 for that purpose is specifying an
-appropriate configuration profile for JFileSync3.
+This is where this software fills the gap. It can sync directories, local or webdav, and it can do this with either
+of these encrypted. Additionally it can sync with encfs volumes stored in local folders. It is my common practice, that
+the local encrypted folders are in turn synced with one of the online syncing services.
 
-Nearly all functions of JFileSync3 can be controlled via the Graphical User Interface
-(GUI). However, JFileSync3 provides full access to all features (apart from
-plug-ins) via the command line interface. Call 'bin/JFileSync -help' to
-get an overview of all possible command line options.
+If you use EncFS in this scenario, it is possible to access the encrypted and synced files from mobile devices with
+Boxcryptor Classic for iOS and Android and additionally EncFS tools for android. Also this EncFS solution is
+compatible with encfs4win and of course Linux based encfs.
 
 
 Requirements
@@ -62,18 +72,40 @@ Requirements
 
 - Only when using other algorithms than AES: JCE extension  (see 'http://java.oracle.com')
 
+
 Installation and Application Start
 ----------------------------------
 
-- Unzip the distribution file to a directory of your choice.
-- For simplicity reasons a Windows launcher ('JFileSync3.exe'), a batch file ('bin/JFileSync3.bat') and a Unix
-  shell script ('bin/JFileSync3') are available via the main distribution directory in order to start the application.
-  ATTENTION: Because JFileSync is distributed as a Zip archive, Unix users
-  will have to give executable rights manually before launching the
-  application, e.g.: 'chmod a+rx JFileSync.sh'.
+Unzip the distribution file to a directory of your choice.
+
+You can start the application through
+
+- a Windows launcher ('JFileSync3.exe')
+- a batch file ('bin/JFileSync3.bat')
+- a Unix shell script ('bin/JFileSync3')
+- a Unity launcher script
+
+ATTENTION: Because JFileSync is distributed as a Zip archive, Unix users will have to give executable rights manually
+before launching the application, e.g.: 'chmod a+rx JFileSync.sh'.
+
+Nearly all functions of JFileSync3 can be controlled via the Graphical User Interface (GUI). However, JFileSync3
+provides full access to all features (apart from plug-ins) via the command line interface. Call 'bin/JFileSync -help' to
+get an overview of all possible command line options.
+
+
+Configuration
+-------------
+
+JFileSync works with profiles controlling which folders to use, which files to include or ommit, how to log into
+WebDAV servers, and which encryption cipher and passphrase to use.
+
+These profiles need to be set up and can be stored in XML files. The distribution contains a set of profile file
+examples illustrating all the intended scenarios.
+
 
 License and Usage Terms
 -----------------------
+
 This program is free software; you can redistribute it and/or modify it under
 the terms of the GNU General Public License as published by the Free Software
 Foundation; either version 2 of the License, or (at your option) any later
@@ -115,73 +147,85 @@ Some code in LZMA SDK is based on public domain code from another developers:
 
 - Eclipse icons: the Common Public License - v 1.0.
 
-You can find a copy all licenses of JFileSync3 and the used libraries in the
-'legal' sub directory of this distribution.
+You can find a copy all licenses of JFileSync3 and the used libraries in the 'legal' folder of this distribution.
 
 
 Development Notes
 -----------------
 
 Required packages for JFileSync3 development (not included in the distribution):
+
 - Java 7 SDK >= 1.7.0 (see 'http://java.sun.com') (Java 8 should be working)
-- Gradle >= 1.4 (see 'http://www.gradle.org' - Recommended are versions 2.2 and up)
+- Gradle >= 1.4 (see 'http://www.gradle.org' - Recommended are versions 2.2.1 and up)
+
+Used and as a result recommended development tools:
 
-Used and therewith recommended development tools:
 - Java 7 SDK 1.7.0
 - Netbeans 8.0
 
+The following structure describes all folder and files included in the JFileSync3 source repository:
+
+- src: Java source code
+- legal: The program licenses.
+- profiles: Sample syncing profiles.
+- ubuntu: Ubuntu Unity desktop integration files
+- win: start scripts for parts of the system as tools - and a Windows icon file
+- test: profiles and data for the encryption test suite
+
 The encryption backend tries its very best to avoid known plaintext attacks with filenames like in directory names
 ("src/main/java") and with the contents of the files.
 
 The contents are compressed before they are encrypted (in most cases - depending on size and special file types) and the
-software tries three algorithms to do that: LZMS, BZIP2, Deflate.
+software tries three algorithms to do that - LZMS, BZIP2, Deflate - in parallel.
 
 The filenames are encoded, scrambled and then encrypted.
 
-Metafiles to speed up acces of the directory structures don't have constant names but calculated ones.
+Metafiles to speed up access of the directory structures don't have constant names but calculated ones.
 
 Passwords to derive keys from are not constant along the whole directory structure.
 
-So I now have a two-way synching from plain text directories to encrypted directories which I in turn sync with the internet
-services. As you might see from some code snippets I am playing around or thinking about direct API usage for Dropbox, WebDAV and so on...
-
-You will need the unlimited encryption add-on by Oracle for your JDK if you want to use anything except the default cipher
+You will need the unlimited encryption add-on by Oracle for your JDK, if you want to use anything except the default cipher
 AES.
 
 Feel free to issue bug reports and ideas here.
 
-HOWTO BUILD:
+
+Building and Packaging
+----------------------
+
+
+The software is built through the usual
+
+```bash
+gradle build
+```
+
+and can be started - e.g. for IDE integration - through
+
+```bash
+gradle run
+```
+
+A basic packaging can be generate with
 
 ```bash
 gradle distZip
 ```
 
-Take the ZIP file from build/distributions
+Take the ZIP file from build/distributions.
 
-Optionally if launch4j is installed and available on your path you can build with
+Optionally - if launch4j is installed and available on your path - you can build with
 
 ```bash
 gradle clean build launch4j
 gradle distZip
 ```
 
-so that the distribution will contain an additional JFileSync3.exe executable file.
+so that the distribution will contain an additional JFileSync3.exe executable file. This is the way, the distribution
+packages are generated.
 
 a small test-suite can be found in profiles/test (which is not packaged in the distribtions zip) and can be called via
 
 ```bash
 gradle encryptionTest
 ```
-
-6) Included Directories and Files
-
-The following structure describes all directories and files included in the
-JFileSync3 end user releases containing only resources necessary to run the
-application:
-- src: Java source code
-- legal: The program licenses.
-- lib: Necessary libraries in order to run the system.
-- profiles: Sample syncing profiles.
-- ubuntu: Ubuntu Unity desktop integration files
-- win: start scripts for parts of the system as tools - and a Windows icon file
-- test: profiles and data for the encryption test suite

profiles/Two-Local-Folders.xml → profiles/Copy-To-Local-Folder.xml

@@ -1,4 +1,4 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <jFileSync title="Local Directory Synchronization">
-  <directory src="My Source" tgt="My Target"/>
+  <directory src="profiles" tgt="legal"/>
 </jFileSync>

profiles/Local-To-WebDAV-Folder.xml → profiles/Copy-To-WebDAV-Folder.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <jFileSync title="Syncronize Local Folder with WebDAV Folder">
   <server user="username" passphrase="VerySecret"/>
-  <directory src="Local Folder" tgt="webdav://https://webdav.host/directory/path"/>
+  <directory src="legal" tgt="webdav://https://webdav.host/directory/path"/>
 </jFileSync>

profiles/Encrypt-To-Local-Folder_.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<jFileSync title="Encrypt to Local Folder (without separate Metadata file)">
-  <encryption passphrase="SecretPassword"/>
+<jFileSync title="Encrypt to Local Folder (without separate Metadata file for speed up)">
+  <encryption passphrase="SecretPassphrase" cipher="AES"  shorten="false"/>
   <directory src="PlaintextFolder" tgt="encrypted://C:/storage/EncryptedFolder"/>
 </jFileSync>

profiles/Encrypt-To-WebDAV-Folder.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <jFileSync title="Local Folder to Encrypted WebDAV Folder">
   <server user="username" passphrase="VerySecret"/>
-  <encryption passphrase="SecretPassphrase"/>
+  <encryption passphrase="SecretPassphrase" cipher="AES"  shorten="false"/>
   <directory src="Local Folder" tgt="dav://https://webdav.host/directory/path"/>
 </jFileSync>

profiles/Encrypt-To-WebDAV-Folder_.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<jFileSync title="Local Folder to Encrypted WebDAV Folder (without separate Metadata file for speed up)">
+  <server user="username" passphrase="VerySecret"/>
+  <encryption passphrase="SecretPassphrase" cipher="AES"  shorten="false"/>
+  <directory src="Local Folder" tgt="encdav://https://webdav.host/directory/path"/>
+</jFileSync>