Read Me

INTRODUCTION

This software can be used to create visually encrypted images of a given text.
The papercrypt.jar file can either be executed directly as a program for already
predefined purposes, or it can serve as a library for integration in other
software products. In both cases, you have to adhere to the



LICENSE

"GNU Affero General Public License Version 3" (and Version 3 ONLY),
see the LICENSE file for details. If you have any questions about this license
you can look at the following website for further information on this license:
http://www.gnu.org/licenses/agpl-3.0.html



REQUIREMENTS

- Sun Java Runtime Environment (JRE) 6.20 or above (older versions untested,
  before you waste your time: JRE 1.4.x is never going to work)



PROGRAM USE

If you use this software as a program, no modifications are necessary, but you
have to live with the options already offered by the program.

Simply launch this program with some of the following options:

----------------------------------------------------------
Usage: java -jar papercrypt.jar [OPTION] ...
Run program with OPTION(s)

  --batch            batch mode
  --charsperline     characters per line in text mode
  --dpi              image resolution
  --force            overwrite existing files
  --format           output file format
  --help             display this help and exit
  --mode             mode of operation (required)
  --outfile          output file basename (required)
  --papermode        set to 1 to use normal paper
  --pixeldiameter    size of each subpixel
  --pixelsize        size of one pixel in cm
  --text             cleartext to encrypt (required)
  -b                 see --batch
  -c                 see --charsperline
  -d                 see --dpi
  -f                 see --format
  -h                 see --help
  -m                 see --mode
  -o                 see --outfile
  -p                 see --pixeldiameter
  -pm                see --papermode
  -ps                see --pixelsize
  -t                 see --text

See the manual for details.
----------------------------------------------------------

A word of caution before we go into the detailed description of the options:
Unless set otherwise this program will create two images, the first one will
be horizontally flipped. When you try to overlay them normally, you will not
see the specified text. You have to print the horizontally flipped image on
the back of the first page (hence the horizontal flip). If it is an option for
you, you can simply flip the first page before doing the overlaying. 

As you can see, the options are divided into two parts, those starting with
"--" and those starting with only one "-". The later ones are only aliases
to the first ones, the have exact the same meaning as their corresponding long
versions, you can choose the version at your discretion.

Some options are required, these are:

--mode <modename>	sets the mode the program is to be run in. Possible values
					for <modename> are either "pin" (which will put the text
					in only one line) or "text", which will divide the text
					to be encrypt into lines of equal size and create 2 images
					for each line.

--outfile <file>	sets the output file base name, meaning every part of the
					full filename except for the file extension. Since at
					least 2 images are created, "-1" for the first file and
					"-2" for the second	file are appended together with the
					file extension. In "text" mode the line number will also
					be inserted before the "-".

--text <text>		is the most important parameter of all, it contains the
					cleartext which is to be encrypted. Please note, that if
					you intend to encrypt text containing a "whitespace"
					character, you need to put <text> into "" for the
					parameter to be parsed correctly.

All other options are not mandatory, but can be used to modify the outcome.

--batch <file>      starts the program in batch mode, by reading an ascii text
					file containing a set of lines with comma separated values
					like 'filename','text'. For all these lines the desired
					actions are performed.

--charsperline <n> 	sets the <n> of characters per line in text mode. All
					created images will be of equal size, should the last line
					contain less than <n> characters, it is filled with
					whitespace characters for security reasons.
					Default value: 6 

--dpi <n>			sets the image resolution of the created images where
					supported (.png and .jpg files).
					Default value: 300 (unless --pixelsize is set, in which
					case the resolution will be determined automatically)

--force				causes the program to overwrite existing files. If this
					option is omitted the file will not be created if a file
					with the same name already exists at the specified
					location.

--format <format>	sets output image format. Possible values are "png", "jpg"
					and "svg".
					Default value: "png" (strongly recommended)

--help				displays the above help

--papermode <0|1>	set to 0 if you want to print at least one image on a
					transparent slide, omit this option if you want to print
					the images onto normal paper.
					Default value: 1

--pixeldiameter	<n>	how many "real" pixels should a subpixel contain in both
					x- and y-dimension? Bigger values will enlarge the images,
					but also make them more transparent (if on normal paper)
					Default value: 6 (unless --pixelsize is set, in which case
					the diameter will be determined automatically to achieve
					the desired size)

--pixelsize <float>	sets the size of one subpixel in cm. There is no default
					value in favor of --dpi and --pixeldiameter (which are
					overridden by this option, if it is set).



EXAMPLES

Encrypt the text "I hid the champaign in the cellar" with 8 characters per
line/image and a pixel size of 0.04cm:
 
java -jar papercrypt.jar --text "I HID THE CHAMPAIGN IN THE CELLAR" --mode text --charsperline 8 --pixelsize 0.04 --outfile secrettext   

Create encrypted images of the PIN "081522" with a pixel size of 0.05:

java -jar papercrypt.jar --text 081522 --mode pin --pixelsize 0.05 --outfile secretpin  



LIBRARY USE

Explanation of the use of this library would take quite some time, which is
why you should look at the up-to-date javadoc instead. The sources also come
with 3 demo classes (org.papercrypt.demo.Demo*) which should get you on the right
path.



ADDITIONAL HINTS

For further information on how this program came to be and principally works,
please look at the document "Visual cryptography on ordinary paper" which
was also published by the author, and is available free of charge.



ABOUT THE AUTHOR

My name is Matthias Jung, I am a computer scientist with a lot of (good and
bad ideas), sometimes I realize some of these ideas in my free time - at least
the fun ones.

If you want to contact me, try this mail address:

matthias.jung@udo.edu

Please note, that depending on my current workload, it can take some time
until I answer. Also have in mind, that I do this for fun, so it is unlikely
you will get a lot of support when trying to integrate this library into your
project.