Version 0.1 Date: 28 May 2005
This helptext is based on program version 0.1.0. Its validity may extend to higher program versions in part or in total.
USAGE
Parameters: <command> [<option> [<option>]..]
Call: a) "java -jar fhl-0-0-1.jar <parameters>" (Java package call)
b) "fhl <parameters>" (DOS/Windows batch call)
For both calls you need to be in console modus in the directory where the Java
package is located.
COMMANDS
-e <file> [<target>] : creates an encrypted file from cleartext <file>
-d <file> [<target>] : creates a cleartext file from encrypted <file>
[ -b <batch> [<target>] : operates a batch-file <batch> (into <target> dir) ]
-v <file> : verify an encrypted <file> (prints registry)
-h <target> : creates this user manual document into <target>
-t : performs a security package selftest
OPTIONS
+c:"<comment>" : sets a user comment
+b:<size> : activates random file-size blurring with max=<size>
+d:<date> : sets the file timestamp (use YYYYMMDD[,hhmm])
+n : sets actual time as file timestamp
+z : activates ZIP compression
+v : activates file content verification
+w : wipe the cleartext file (implies +v)
+p:"<passphrase>" : sets the encryption passphrase
+i : takes input passphrase from console (shows text)
+o : overwrite existing target files
+t:<dir> : sets <dir> for temporary files folder
+s : silent mode (if possible)
+k : use 16-byte encryption keylength
CALL EXAMPLES
fhl -e doc/myfairy.doc a:/safes/ +v +z "+c:fairy meets dogfish tale, 10.2003"
fhl -d a:/safes/myfairy.doc.fhl c:/mail/postout
fhl -v a:/safes/myfairy.doc.fhl "+p:peter ging nach lourd" +v
FileHashler is a security utility program capable to transfer any single file (up to 2,1 GB) into an encrypted form and back from an encrypted form into the cleartext form. This service protects the contents of the file to be seen by unauthorised readers. Authorised access to an encrypted file is checked through a symmetric user keyword or passphrase. "Symmetric" hereby means that you use the same key to encrypt and decrypt the file. Such a key is also named a "secret key". Decryption performs fail-safe; that means the utility authenticates legitimate access by the key value and will not produce any results if access fails to be legitimate.
Basically encrypted file and cleartext file are designed to coexist while the utility makes some effort to keep namespaces of both file types separated. There is an option, however, by which the cleartext file can get erased in a safe way after encryption is completed.
-- Self-Documentation and Archive Feature FileHashler encrypted files store internal information about the original file they keep transformed. This comprises the cleartext file's cataloging information as well as an optional user comment about it. The utility has a "Verify" function which controls data integrity of the encrypted file and shows a printout of the information about the contained cleartext file. Only authenticated access can perform this function. By this it is possible to use FileHashler files as shrowded archive files including an integrity validation functionality. E.g. you may change the filename of encrypted files to meaningless gibberish or misleading names and still are able to obtain the original identity of the file at any time - if you know the access key. By the same method you can at any time make a check whether your archive file is still uncorrupted, in the physical sense.
-- Cryptographical Methods
For encryption FileHashler makes use of the TWOFISH algorithm as presented by Bruce Schneier et.al. (http://www.schneier.com/twofish.html). This algorithm is held for one of the leading technologies in combining execution speed and security. It was accepted as one of the fife top candidates for the AES encryption standard in 1999 by the American NIST institute (http://csrc.nist.gov/CryptoToolkit/aes/). The default technical encryption key length is 32 bytes which is the maximum security that can be obtained by this algorithm. By user option this key length can be reduced to 16 bytes, which however lowers the security status of the transformation and therefore is not recommended.
The user passphrase is never used directly for the encryption algorithm. It takes it a long and multi-layered path through various program levels until it finally becomes, in a terribly disfigured form, the input of Schneier's encryption machine. An important additional element of security is the application of key modulation based on random data. The effect is that it is impossible to make inferences by the shape of an encrypted file to identify a singular cleartext file. Or in other words, the same cleartext file will result in different encrypted shapes from different encryption processes with the same access key. The drawing of random data is cryptographically optimised so that a deterministic relation between random data and the system time does not exist. To make the confusion of adversary agents perfect, the utility allows to blur the resulting file size by a dimension which the user can determine (see option "+b").
A sane cryptographical hash function is at the basis of any reliable encryption service. SHA-256 is used for this purpose here (http://csrc.nist.gov/cryptval/shs.htm). This is a function with a 32 byte hash digest. It was recommended since the common SHA-1 is currently at the verge of becoming outdated and risky (http://www.schneier.com/blog/archives/2005/02/sha1_broken.html).
-- User Access Keys
User access keys (or encryption passphrases) require a minimum quality. They must be at least 8 bytes long and possess 6 different characters. If these requirements are not met, the utility will report "bad access key" and terminate undone or repeat the request for user input, depending on the function called.
-- Self-Test Capability
The program has the ability to perform self-tests of the security relevant software modules, such as SHA-256 and Twofish. Ultimately, the target of this feature is to sufficiently control the software code of the program you use and make sure it has not been tampered with or gotten corrupted. This target can be reached at only gradually. At present this functionality is very basic, but does detect accidental corruption. It is marked, however, for further development in future editions.
COMMANDS
-e <file> [<target>] : creates an encrypted file from cleartext <file>
-d <file> [<target>] : creates a cleartext file from encrypted <file>
-b <batch> [<target>] : operates a batch-file <batch> (into <target> dir)
-v <file> : verify an encrypted <file> (prints registry)
-h <target> : creates a user manual document into <target>
-t : performs a security package selftest
*** General
"file" is a variable for a single user-specified file, while
"target" refers to an output destination that can be either a single file or a directory.
"batch" is a single file containing formated text with the target to present a sequence of executable commands.
Password input is required for most of the commands. By standard execution the password is fetched from a small popup dialog window which hides the input text from vision. By option password input can be ordered to come from the console; in this case the input is visible on the screen.
Password values may be entered using the local default character set of the Java VM you are operating on. Care should be taken, however, about the values chosen if cross-locale availability of encrypted files has to be guaranteed. In this case it is recommended to use only values consisting of the US-ASCII character set. Password values must conform to a minimum quality of input. This quality is: minimum length = 8 characters, minimum character variance = 6. It is recommended to use either random-generated passwords or values that comprise several words of natural language, at best amplified by numeric elements or special symbol characters. More or less it is left to you to determine the security level of you encryption by choosing an appropriate password value!
Overwrite protection is incorporated with all file producing commands. The user is given notice before any existing target file might get overwritten, except for the case that option "+o" is stated in the commandline.
*** -e <file> [<target>]
Encrypts a single file <file> (cleartext) into the target <target>, thereby creating a single password-protected ciphertext file. If the target is left void or constitues a directory, a suitable filename is created by FileHashler through appending the extention ".fhl" to the cleartext filename.
Functional options for this command: +c +b +d +n +z +v +w +p +i +o +t +s +k
*** -d <file> [<target>]
Decrypts a single file <file> (ciphertext) into the target <target>, thereby creating a single cleartext file. If the target is left void or constitues a directory, the internally stored original filename of the cleartext file is used as a name for the created file.
Functional options for this command: +d +n +v +p +i +o +s +k
*** -b <batch> [<target>]
The batch command is currently not operative. It is designed, however, to execute any list of valid FHL commandlines in a later release.
*** -v <file>
Verifies a ciphertext file <file> and prints a list of its contents. The verify encompasses an integrity control of the entire encrypted file (ciphertext) and optionally an integrity control of the contained cleartext file (with option +v).
Functional options for this command: +v +p +i +s +k
*** -h <target>
Creates a new user manual document (US-ASCII, EN) into destination <target> (well, the content happens to be this text you are reading now). If the target is a directory, the standard name "fhl-help.txt" is used for the destination file. If the destination file already exists, the function terminates undone.
Functional options for this command: - none -
*** -t
Performs a self-test of the security relevant software modules.
Functional options for this command: - none -
OPTIONS
+c:"<comment>" : sets a user comment
+b:<size> : activates file-size blurring with max=<size>
+d:<date> : sets the file timestamp (use YYYYMMDD[,hhmm])
+n : sets actual time as file timestamp
+z : activates ZIP compression
+v : activates file verification
+w : wipe cleartext file (implies +v)
+p:"<passphrase>" : sets an encryption passphrase
+i : takes input passphrase from console
+o : overwrite existing target files
+t:<dir> : sets <dir> for temporary files
+s : silent mode (if possible)
+k : use 16-byte encryption keylength
*** General
Options are either plain literals or literals followed by a variable value. In the latter case a variable value is separated from the literal by a ":" char. If the value contains blanks, it must be enclosed in quotation marks. (A note for users of the DOS-batch: the quotation marks should be applied over the entire parameter, e.g. "+c:peter ging nach lourd" instead of +c:"peter ging nach lourd".)
*** +c:"<comment>"
Adds a user comment on the file that goes into the ciphertext file. This line will display during the execution of the "-v" (verify) command. Usually a semantical, descriptive reference to the file, the maximum length of this line is not defined. The encoding is in Unicode and should result in correct display wherever the local VM's default charset supports the text.
*** +b:<size>
Activates filesize blurring and sets the Blur Base Value (BBV) to the value <size>. Filesize blurring adds a random value, which is at least one third of the BBV, to the ciphertext file length during its creation. If you are a security fanatic, you can thereby avoid identification of your cleartext file or possible conclusions derived from the ciphertext file length.
*** +d:<date>
Sets the file timestamp (catalog time) for a produced file (ciphertext or cleartext) to the value specified in <date>. The format of <date> values is described by "YYYYMMDD[,hhmm]" where Y=year, M=month, D=day, h=hour, m=minute. Example: "20040321,2115" for 21. April 2004 21:15h. The time specification can be left away and 0:00h will be assumed. (In fact any other non-digit characters in a value will be tolerated by the program and discarded as meaningless, so it is allowed to write a value like "2004-03-21 21:15".)
*** +n
Sets the actual system time as the file timestamp (catalog time) for a produced file (ciphertext or cleartext).
*** +z
Activates GZIP compression for the production of a ciphertext file. This will first compress the content from a cleartext file and after this encrypt it. Possibly a temporary file is required for the compression act and therefore care must be taken about the location and accessibility of the temporary files directory (which can be set for the duration of a command execution by option "+t"). The default directory is the VM's "tempdir" directory. A temporary file is always cleared out by the secure wipe algorithm before a command terminates.
*** +v
Causes the activation of special content verification algorithms for the commands for creation ("-e", "-d") or verification ("-v") of a file. This intends to ensure that in the case of file creation the transformed content state of a file corresponds correctly to the original be re-reading and comparing both. In the case of file verification (command "-v") this extends CRC file integrity check to the decrypted cleartext content of the contained file (which is normally not necessary).
*** +w
This option for the creation of ciphertext files causes the source cleartext file to be erased by the secure wipe algorithm after the target file is created and verified. This option is only available for encryption and also implies the "+v" option active.
*** +p:"<passphrase>"
This option directly enters an encryption user key <passphrase> via the FileHashler call commandline. A limit to the length of this phrase is not defined. For more information see the "General" paragraph of the "Commands" chapter. You may wish to use this for convenience if you think your environment is secure enough for the purpose. Note, however, that this method of key entry has a considerably increased security risk of hostile key capture compared to dialog input.
*** +i
Directs user input to be drawn from the console commandline. This has security relevant consequences, but might again be convenient in cases where you feel secure enough or where technical environment demands it. The input will be visible on the screen and uncontrollable data trash of the VM might increase the risk of unauthorised password capture.
*** +o
Allows command execution to overwrite any existing target file without prior notice to the user.
*** +t:<dir>
Sets the local folder for temporary process related files to the variable value <dir>.
*** +s
Triggers silent operation mode for the duration of a command. In silent mode commandline text output of the program is reduce to cases of the inevitable. Successful "-e" and "-d" commands can be expected to run output free.
*** +k
Sets the application of a reduced security level for the Twofish encryption algorithm (key length = 16). Other than perhaps dealing with legal issues, this does not bring operational benefit. Not recommended.
LEGAL NOTES AND DISCLAIMER
Third party Java (at best knowledge):
Security Module References:
This program is not freeware software but copyright protected to the author(s) stated above. However, you can use, redistribute and/or modify it cost-free under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 of the License. Furthermore, any such modification must constitute a product under a different name.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA, or go to http://www.gnu.org/copyleft/gpl.html.
This program was designed carefully and is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
We do not take any responsibility for violations of law that the application of this software might cause in the particular circumstance of an environment. It is within the responsibility of the user of this software to decide whether and where to perform it and obtain the knowledge if its performance is conforming to applicable laws.