
=pod

=head1 README

You can use perldoc to read this document: C<perldoc README>.

=head1 DESCRIPTION

=head2 Verify

Before you do anything with the downloaded package, verify the signature.

Download our GnuPG key from http://www.bsi.bund.de/produkte/dicop/download.htm
and import it into GnuPG.

=over 2

=item *

Verify the signature of the .tar.gz file by downloading the .tar.gz.asc file
and run 

	gpg Dicop-Workerframe-2.19.tar.gz.asc

Replace "2.19" with the actual version number you got.

=back

If the signature does not verify ok, please notify us immediately. 
B<DO NOT> run perl Makefile.PL or anything else nor install the package when
the signature cannot be verified ok. B<Your system might get compromised!>

=head2 File Layout

These files are in the Dicop-Workerframe package:

	doc/			additional documentation

	src/			source for the framework
	src/main/		main framework source
	src/include/		some include files for src/main/
	src/include/encoding/	auto-generated tables for encoding and decoding

	src/test/		an example (test) worker
	src/pwdtest/		(single pwd at a time) testworker for the testsuite
	src/extract/		example test worker for extraction from image files
	src/test_par/		(pwds in batches) testing the parallel interface
	src/test_conv/		test charset conversion
	src/test_enc/		test encodings and their conversion
	src/test_sbc/		test single-byte encodings

	lib/			libdicop is build and put into this directory

	build/			files for package management and build process
	t/			testsuite
	t/test-worker		test workers are created in this directory
	t/target/		test data for the testsuite
	t/output/		expected output for the testsuite

=head2 Short Overview

This is a framework for generating so-called workers (hence the name
workerframe) for the DiCoP project. The resulting executables are able to be
run standalone, but their real purpose is to be run in an DiCoP cluster
environment.

So you should install the DiCoP server and client first. See
L<http://www.bsi.bund.de/> and search for "dicop", then download and install
the server and at least one client.

This framework provides all the necessary routines to get an "empty" worker
done, e.g. something that just walks a bit of a password/key space and
applies an "empty check" (e.g. none at all) to each password/key.

Workers are usually called by the DiCoP client and take their arguments from
the command line and/or additional files. They print their results to
STDOUT, which is then collected by the client.

All the initialization is done by the framework. The framework contains a
password generator (actually more than one), and this generator cycles through
all passwords in the given range and calls a check function (called
C<dofunction>) for each password.

The framework can walk password/key rooms that are described by different
types of character sets. For details please see C<doc/API.pod>.

The idea behind this to keep the system simple, the communication
human-readable (thus easily debugable) and avoid dependencies as much as
possible. The workers should (and do) be able to run as simple programs on a
text-console, with no dependencies except for the c library. This makes it
easier to deploy them on systems with quite different operating systems or
hardware.

To simplify the development of workers further, the common parts were
relocated into the workerframe. This frame manages all the boring things
like the interaction between client and worker, the setup of the password
generator (which is the thing that know how to walk the key room from C<start>
to C<end>) and then the actual generating of all keys in the key room.

There are only a couple of functions you need to fill in. Please refer
to C<doc/API.pod> for a listing and their meaning.

Have a look into the C<src/pwdtest> and C<src/test> directory, they contains
two sample workers. Also noteworthy are the C<test.pl> and C<prime.pl> test
workers distributed with the DiCoP project.

That's all, folks!

=head1 INSTALLATION

=head2 Testing

The worker framework does not need to be installed, nor to be copied into
the server/client. It is just there to build new workers for the cluster.

Just untar/ungzip the package to a directory of your choice:

	tar -xzf Dicop-Workerframe-2.19.tar.gz

Replace "2.19" by the actual version you got.

        perl Makefile.PL
        make test

to run the testsuite. It should pass all the tests. If not, please notify us.

=head3 Windows

Under mswin32, replace C<make> by C<nmake>:

        perl Makefile.PL
        nmake test

=head2 Install

You do B<NOT> need to C<make install>. There is nothing to install.

Files that are compiled with the workerframe need to be copied into the
servers C<worker/> dir, where they can be picked up by the clients.

They will use a file for the charsets, this file is written by the server
whenever the charsets change. The default name for that file is charsets.def
and it is located in the C<worker/> dir. Each worker will try to find this file
from it's own directory, and if this fails, one directory up. Here is a sample
layout:

	worker/charsets.def		generated by server
	worker/linux/test
	worker/os2/test			etc, pp.

All workers will use the same charsets.def file, which is generated by
the server and distributed to the clients automatically.

A sample charsets.def file (used by the testsuite) is included with this
package, you can find it in C<t/test-worker/charsets.def>.

=head1 DEVELOPMENT

To develop a new worker, have a look at the two sample workers included in
the distribution: C<test> and C<pwdtest>. Anything that is in these two
directories (C<src/test> and C<src/pwdtest>) is needed to build a new worker
- nothing more or less ;) See also L<DESCRIPTION|DESCRIPTION>.

=head1 Supported platforms

The latest version of this framework was tested the following platforms:

=head2 Linux with GCC

We tested with GCC 3.3.5 and GCC 4.1.0.

=head2 Windows with MS Visual C++

The project should compile cleanly under a modern Windows using Microsoft
Visual C++ 2003. You need 64 bit support for file pointers, e.g.
C<fseeki64> and C<ftelloi64> must exist.

When compiling under Microsoft Visual C++ 8, you need to specify

        /NODEFAULTLIB:libc

in the linker flags, or it will complain. *sigh*

=head2 Others

It should work on other platforms, too. However, we can not guaranty that
it will work on all platforms. If you experience any problems, please contact
us (see below).

=head1 AUTHOR

(C) Bundesamt fuer Sicherheit in der Informationstechnik 1998-2007.

For licensing information please refer to the LICENSE file.

=head2 Contact

Address: BSI
	 Referat 123
	 Godesberger Allee 185-189
	 53175 Bonn
	 Germany
email:	 dicop @ bsi.bund.de	(for public key see dicop.asc or web site)

