=pod =head1 README You can use perldoc to read this document: C. =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 run perl Makefile.PL or anythign else nor install the package when the signature cannot be verified ok. B =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 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) for each password. The framework can walk password/key rooms that are described by different types of character sets. For details please see C. 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 to C) 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 for a listing and their meaning. Have a look into the C and C directory, they contains two sample workers. Also noteworthy are the C and C 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 need to C. There is nothing to install. Files that are compiled with the workerframe need to be copied into the servers C 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 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. =head1 DEVELOPMENT To develop a new worker, have a look at the two sample workers included in the distribution: C and C. Anything that is in these two directories (C and C) is needed to build a new worker - nothing more or less ;) See also L. =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)