
=pod

=head1 README

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

=head1 DESCRIPOTION

=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.16.tar.gz.asc

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

=back

If the signature does not verify ok, please notify us immidiately. 
B<DO NOT> run perl Makefile.PL or anythign 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:

	t/		testsuite
	t/target/	test data for the testsuite
	t/output/	expected output for the testsuite

	doc/		additional documentation

	src/		source for the framework
	src/main/	main framework
	src/include/	some include files for src/main/

	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/pwdblock/	(pwds in batches) testworker 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 neccessary 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 commandline 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 debuggable) and avoid dependecies as much as
possible. The workers should (and do) be able to run as simple programs on a
text-console, with no dependecies 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 keyroom 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.14.tar.gz

Replace "2.14" 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.

=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>.

=head2 Supported platforms

We only did extended testing under Linux running on x86 machines.

Some additional build-tests were done on a Compaq iPAQ H3870:

	bash-2.03# gcc -v
	Reading specs from /usr/lib/gcc-lib/arm-linux/2.95.2/specs
	gcc version 2.95.2 20000220 (Debian GNU/Linux)
	bash-2.03# cat /proc/version
	Linux version 2.4.18-rmk3 (andyc@rockhopper.crl.dec.com)
	(gcc version 2.95.2 19991024 (release)) #13 Wed May 1 19:38:27 EDT 2002

	bash-2.03# cat /proc/cpuinfo
	Processor       : Intel StrongARM-1110 rev 9 (v4l)
	BogoMIPS        : 137.21
	Features        : swp half 26bit fastmult
	
	Hardware        : Compaq iPAQ H3800
	Revision        : 0000
	Serial          : 0000000000000000
	bash-2.03# perl -v

	This is perl, version 5.005_03 built for armv4l-linux

	Copyright 1987-1999, Larry Wall

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-2006.

For licensing information please refer to the LICENSE file.

=head2 Contact

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

