Documentation

Fisy is a command line application dedicated to copy and backup files. All the control and the setting of the tasks for copying is done via a single configuration file of type XML whose description can be found in the following documentation.
Once the configuration file has been created, execute Fisy with the command line :  fisy configurationFileName.xml

Configuration file

This XML configuration file is a file where you will define all your backup choice. For example, which files should be saved (specify the source and destination), what type of copy to launch, should we use ciphering features, what is the level of traceability tasks (logs), etc...
For that you can get inspiration of files "configuration_example.xml" and "configuration_template.xml" present in the installation directory of Fisy and containing configuration examples. Note that an XML file is a plain text file readable for an human, so you can create it one or open it one with a text editor such as Notepad for those under Windows system.

Here is a minimal example of a configuration file Fisy defining a copy task of type "synchronization" from c:\data\source to d:\backup\target <?xml version="1.0" encoding="UTF-8"?>
<fisy>
  <task name="MyFirstTask" type="SYNCHRONIZE">
    <src path="c:\data\source" />
    <dest path="d:\data\target" />
    <log path="d:\data\log" level="INFO" />
  </task>
</fisy>

With :

  • name : an identifier representing the name of the task.
  • type : a task of type synchronization (see below).
  • src : the source directory.
  • dest : the destination directory.
  • log : the traceability of the synchronization (see below).
It is quite possible to link several copy tasks, for that you have to declare the tags task one behind the other in the configuration.

Task Type

Fisy is able to make copies of files by three methods.

Synchronization SYNCHRONIZE

Unidirectional synchronization from a source directory to a destination directory. At the end of this task, the destination is the same as the source.
Actions : 

  • - If the file or directory found in the destination does not exist in the source then remove it from the destination.
  • - If the file or directory found in the source does not exist in the destination then create/copy it to the destination.
  • - If the file found in the source is also present in the destination then copy/replace if the source is newer than the destination (note that Fisy do not care about the date of the directories in this case).

Timestamp copyTIMESTAMP_COPY

Save a file tree into a timestamp directory.
Actions : 

  • - Creates a directory in the timestamp destination.
  • - Copies all the source in this directory.

If a constraint is defined (property constaint on tag task) then Fisy compares the date of the last backup and the exclusion range "[today, today - time of the constraint]". If the last backup is in this range that means it is too early to make another backup and Fisy does not perform the task.

Example, save 1 times per week :  <fisy>
  <task name="MyConstraintTask" type="TIMESTAMP_COPY" constraint="1W" >
...

If a retention time is defined (property retainTime on tag task) then Fisy search all older backups than "today - retention time" and deletes them. This property allows deleting the backups too old.

Example, delete backups older than one year :  <fisy>
  <task name="MyRetainTask" type="TIMESTAMP_COPY" retainTime="1Y" >
...

A timestamp directory is a directory containing a time stamp information. Here the directory has the name YYYYmmDD_HHMMSS_<Task name>.

Full copy OVERWRITE_COPY

Full backup. All files and directories are copied from the source to the destination directory. At the end of this task, the destination is the same as the source.
Actions : 

  • - Deletes all contents of the destination directory.
  • - Makes a copy from the source to the destination.
As seen in the various actions, Fisy is able to remove or replace a file in the destination directory. If we summarize.
SYNCHRONIZE : deletes files and directories in the destination if not present in the source. Replaces the destination files if they are older than the source.
TIMESTAMP_COPY : deletes old backups if the property retainTime is defined.
OVERWRITE_COPY : deletes all in destination before making the copy task.

Logs (traceability)

The logs are used to trace all operations performed by Fisy during the execution of the task of copy and backup.
There are three levels of verbosity defining our logging DEBUG, INFO and ERROR, and must be entered in the property level for the tag log (We advise you to set the logs to INFO).
If a retention time is defined (property retainTime on tag task) then Fisy search all older logs than "today - retention time" and deletes them. This property allows deleting the logs too old.

Log example :  X#20140926:183319#Start synchronize
I#20140926:183319#Delete 'D:\data\target\dir1\file1.txt'
I#20140926:183319#Copy 'C:\data\source\dir2\file2.txt' to 'D:\data\target\dir2\file2.txt'
I#20140926:183319#Mkdir 'D:\data\target\dir3\'
I#20140926:183319#Copy 'C:\data\source\dir3\file3.txt' to 'D:\data\target\dir3\file3.txt'
X#20140926:183319#End synchronize

RetainTime and Constraint

Retain time and constraint are temporal informations used in the logs and in copy tasks of type TIMESTAMP_COPY. They allow to not perform a task if it is too recent (property constraint) or delete items if they are too old (property retainTime in tags log and task -- only for timestamp copy --).
The syntax is : <amount><unit>.
Examples : 

  • 2H = 2 hours.
  • 10W = 10 weeks.
  • 5D = 5 days.
  • 2M = 2 months.
  • 1Y = 1 year.

Encryption

Since version 2.0, Fisy is able to cipher (and decipher) the data on the fly during the execution of a copy tasks. For this, the application uses the AES encryption algorithm that applies to the file names, directory names and file contents. Thus the data become unreadable without a key to deciphering and can be sent to a remote service such as the Cloud while remaining safe from prying eyes.
To enable encryption, simply add the tag cipher in the task of copy, inform key (property keyFile) and finally the direction of the cipher (property direction).

Example : 
<?xml version="1.0" encoding="UTF-8"?>
<fisy>
  <task name="MyFirstTask" type="SYNCHRONIZE">
    <src path="c:\data\source" />
    <dest path="d:\data\target" />
    <log path="d:\data\log" level="INFO" />
    <cipher keyFile="c:\my_key.dat" direction="PLAIN_CIPHER" />
  </task>
</fisy>

With :

  • direction : direction of the cipher, PLAIN_CIPHER = cipher, CIPHER_PLAIN = dédecipher.

Generate the key

To generate the cipher key simply use the application "Fisy Key Generator" provided with Fisy and presents in the installation directory.
His execution is done via the following command line :  fisyKeyGen <key size> <key file>

With :

  • key size : the size of the key. There are 3 possible values 128, 192 and 256 representing the standard key sizes used by AES.
  • key file : name of the file containing the key.

For example, to create a 128-bit key stored in the "my_key.dat" file, execute the command line :  fisyKeyGen 128 my_key.dat

Please note that the default version of Java is able to generate key beyond 128 bits but is unable to use them for encryption ! (Because of laws in some countries). If you want to work with keys 192 and 256, you should return to the Java official website and download the extension "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files". This extension is a patch that you need to apply to your JVM (see the file readme.txt).
Do not lose the key ! Without this key it is not possible to decipher the data and there is no solution or workaround to retrieve it.
Do not hesitate too to duplicate/copy it in safe places and avoid "dumb" situations like a backup of a data disk in the Cloud and leave the key on this disk. If this one crash data are saved but the key is lost...

Technical specification of encryption

As indicated above, data ciphering occurs via AES with the use a choice of one of the 3 key sizes 128, 192 or 256.
To improve the cipher, the mode of operation "CBC" was affixed to the AES algorithm involving the definition of an initialization vector (IV) for the encryption/decryption processes. Technically this IV is a table of 16 bytes that must be created for each ciphering of a message and used to complexity the encryptions of block cipher (such as AES) -- see Wikipedia --. Once this IV used it is transmitted with the encrypted message for the inverse operation of deciphering, moreover, contrary as expected, these IV can be transmitted in the clear.
At Fisy side, these IV are inserted at the beginning of the file in the case of an encryption of type "file content" and are converted into base 64 and then inserted at the beginning of the file name in the case of an encryption of type "file name". As for the first type, this process lends itself well, as for type "file name" that can cause some problems because we are limited by the size of the names.
So the choice had been made to cut the encryption into 2 separate parties. One for the contents of files fully complies with the AES/CBC standard and the other for file names complies with the AES/CBC but with an initialization vector a little smaller than the standard in order to not reach the maximum size. This weakness is minimized by the fact that there is few data to cipher (a file name is very small in front of a file content) and decipher a file name has a range limited if we do not know its contents. More is always better than an encryption without IV (ECB mode).
Note that this separation results in the generation of 2 cipher keys and not one in the application "Fisy Key Generator". Of course, these two keys are generated randomly and have no connection or dependency between them.

Make your own encryption module

For anyone wishing to improve encryption in Fisy and mastering the Java programming language, it is quite possible to create your own encryption module. The procedure is quite simple, just take the sources of CpasCipher library (supplied with Fisy) and redefine the class AESFileFunction which contains the implementation of the 2 ciphers of type "file content" and "file name".
Here are the methods to modify :  public String encryptPath(String path) throws GeneralSecurityException;
public String decryptPath(String path) throws GeneralSecurityException;
public void encryptFile(File fileIn, File fileOut) throws IOException, GeneralSecurityException;
public void decryptFile(File fileIn, File fileOut) throws IOException, GeneralSecurityException; Once development is complete, it will recompile the sources of the library while ensuring to put in the classpath and in the manifest the library commons-codec-1.9.jar.