CODEX release 1.0 ----------------- CODEX provides a symmetric key distribution service with strong security guarantees of confidentiality, integrity, and availability. This implementation is in C++, with a handful of bash and perl scripts for local certificate management. It is designed to be easily portable to any reasonably POSIX-compliant system, though the only systems on which it has presently been tested are x86-Linux and Solaris. The release is structured as a "scripts" directory containing a few utilities principally intended for setting up a certification authority and a "src" directory containing the actual source code to build CODEX. For information on the scripts, please see the README file in the scripts directory. The remainder of this file will deal with the source code. When fully compiled and linked, including generating the documentation, CODEX requires approximately 180MB of disk space. The documentation accounts for about 10MB of this. See the file LICENSE for copyright and licensing information. For questions or comments, please contact Michael Marsh, mmarsh@umiacs.umd.edu ************************************************************************** NOTE (PLEASE READ): The CODEX_Ciphers library contains implementations of the RSA and ElGamal cryptosystems. Consequently, it is subject to US export regulations. As publicly available source code, CODEX is eligible for the license exception TSU, which allows unrestricted export and re-export EXCEPT to those countries listed in EAR section 740.13(e)(4) and their nationals. At the time of writing, these include Cuba, Iran, Iraq, Libya, North Korea, Sudan, and Syria. ************************************************************************** Getting the Source ------------------ The latest version of the source is available from http://www.umiacs.umd.edu/~mmarsh/CODEX packaged as a gzipped tar file. After downloading the tar file, cd to the directory in which you'd like to install the source and type: gunzip -c | tar xvf - or, if using GNU's version of tar: tar zxvf This file should appear as CODEX/README. Additional Packages Needed -------------------------- gcc/g++ (3.0.4 or later recommended) For portability, CODEX requires GNU's g++ compiler (http://www.gnu.org). The reason for this is that many C++ compilers are somewhat idiosyncratic, and in the few places where compiler idiosyncrasies become relevant we have chosen to code to a single "standard". Since the GNU Compiler Collection is available on nearly all systems, this was the simplest choice. Due to a bug in the implementation of the basic_string<> template, some earlier but still common versions of g++ will not work (3.0.4 and above seem to work). For those who are really interested, the most relevant compiler issues can be seen by looking at the macro files in src/CODEX_Basics. If seeing the implementation details from STL exposed makes you gag, you will have some understanding of why only one compiler was considered. Where possible, all CODEX source code should be fully ANSI/ISO-compliant. OpenSSL (0.9.7a or later recommended) CODEX uses the OpenSSL (http://www.openssl.org) toolkit for the SSL/TLS protocols, configuration file management, arbitrarily large numbers, and ASN.1 serialization. The API for OpenSSL has changed in the course of the 0.9.6 series, and CODEX takes advantage of some changes that occurred later in the series. Generally these changes relate to whether arguments to certain functions can be const or not. To be safe, you should use version 0.9.7a or later. Security patches to earlier versions (such as what some Linux distributors do) will not work unless the function prototypes have been updated as well. Doxygen (optional, any version) graphviz (optional, any version) The CODEX source is commented to take advantage of the Doxygen (http://www.stack.nl/~dimitri/doxygen/index.html) autogeneration utility. All versions of Doxygen should work, though there might be a few documentation features that do not work correctly. Doxygen uses the dot utility (http://www.research.att.com/sw/tools/graphviz) to generate class diagrams. If you do not have graphviz installed, Doxygen will generate a lot of errors. Configuring and Building the Source ----------------------------------- [ The short version: cd CODEX/src ./configure make all Libraries will appear in CODEX/src/lib, executables in CODEX/src/bin, and HTML documentation in CODEX/src/doc/html. ] If, after reading the following and doing everything it suggests, you still can't get CODEX to compile, PLEASE SEND EMAIL TO mmarsh@umiacs.umd.edu . We want this to compile successfully with minimal effort on as many platforms as possible. Once you have the source unpacked, cd into the CODEX/src directory. CODEX uses autoconf for portability, so the first thing you need to do is run ./configure You might need to specify some options to configure. Try it without any options first, since it's somewhat likely that no options will be needed. If the version of OpenSSL that configure finds is not recent enough, you might have to install a later version. 0.9.7a was used to develop CODEX, and will work. You can specify a custom installation with ./configure --with-ssldir= Some installations of OpenSSL are compiled with Kerberos support. In most cases the Kerberos header files will be located in /usr/include/kerberos, but on some systems the location will be different. For example, RedHat Linux places the Kerberos headers in /usr/kerberos/include. If this is the case for your system, you can use the "--with-ssldir=" option to specify the Kerberos header file path. If you need to supply both, you can use ./configure --with-ssldir=" " Yes, this is a hack. No, we don't plan to make it more elegant, since the problem is with (eg) RedHat's configuration. If the version of GCC on your system is too old, or if you have multiple versions installed and need to specify the non-default compiler, you can force the $CXX environment variable to select the appropriate compiler. For example, if g++ is version 2.95.x and g++3 is version 3.x you could invoke configure as ./configure CXX=g++3 You will probably also want to set $CC appropriately, such as ./configure CXX=g++3 CC=gcc3 For debugging, you can invoke configure as ./configure --enable-debug This will turn off optimization and turn on the compiler debug flag. For a complete list of options, type ./configure --help or ./configure --help=short One configured, building CODEX is done by typing make This assumes a version of make compatible with the GNU makefile format. You might see a number of warning messages go by, complaining of comparisons between signed and unsigned values. These are generally due to third-party requirements for signed types on something that is fundamentally an unsigned quantity. Rest assured that signs have been tested prior to the comparison or assignment about which g++ is complaining, so we're never going to have "if ( neg_int > my_uint )" problems. If instead you type make all The documentation will also be generated. If not generated at compile time, documentation can be built later with the command make docs Doxygen should produce one warning, for char_traits< unsigned char > missing documentation. If you see any other warnings, please let us know. Please note that the "docs" target will always completely rebuild the documentation and can take a fair amount of time. All libraries and executables remain in the CODEX distribution, so no "make install" step is needed. Libraries will be in the lib subdirectory and executables in bin. If you really want them to be installed elsewhere, you should copy (or link) them by hand. Running Servers and Clients --------------------------- One of the executables produced is codex_server. This will start a local instance of CODEX, which is configured through an OpenSSL CONF-style configuration file. See the documentation for codex_server for the format of this file. codex_server does not need to be run with elevated privileges. Before CODEX is run, keys and key shares will need to be generated. RSA keys can be generated using the scripts provided, if they are not already present. ElGamal keys can be generated using the generate_elgamal_key executable. Keys are split into shares with the split_private_keys program, and the shares must then be (securely) distributed to all hosts on which CODEX servers will run, one share of each private key for each server. Public key certificates must be given to all servers. The validity of shares can be tested prior to distribution using verify_private_keys. Two client examples are given in src/CODEX_Binaries, and are compiled into the bin directory. These are timing_client.cc and test_c_client.c. The functionality of both is the same (up to programmed-in delays). An additional example is found in src/CODEX_Client/example_client.cc. timing_client.cc and example_client.cc are written in C++, and use the interface provided by src/CODEX_Client/Client.h. test_c_client.c uses the C interface that wraps Client.h and is provided in src/CODEX_Client/client_functions.h. The documentation for timing_client contains an example configuration file. Programming with the CODEX Libraries ------------------------------------ One of the ideas behind the CODEX implementation was to create a set of libraries that can be used to quickly produce new services. Each library defines a unique namespace to avoid name collisions. In a library are collected a number of classes relevant to a specific functionality. For example, CODEX_ASN1 contains the basic classes that allow you to build complicated self-serializing objects with a minimum of effort. The three most independent and "functional" libraries are CODEX_ASN1, CODEX_Events (the event-based concurrency system) and CODEX_Quorum (networking). CODEX_KeyService and CODEX_APSS are the highest-level libraries, and are useful for seeing how all of the classes fit together. The source code in src/CODEX_Binaries/codex_server.cc shows how to instantiate services and connect them into the CODEX_Server service-management package. See the HTML documentation for detailed descriptions of the libraries and classes. The file src/doc/html/index.html is the place to start, or src/doc/html/main.html for the frames-free version. Ciphers ------- The "ciphers" variable in the sample configuration file for codex_server is very short. The full list of ciphers specified for the tests of CODEX is: ciphers = EDH-RSA-DES-CBC3-SHA:EDH-DSS-DES-CBC3-SHA:DES-CBC3-SHA:DHE-DSS-RC4-SHA:RC4-SHA:RC4-MD5:EXP1024-DHE-DSS-RC4-SHA:EXP1024-RC4-SHA:EXP1024-DHE-DSS-DES-CBC-SHA:EXP1024-DES-CBC-SHA:EXP1024-RC2-CBC-MD5:EXP1024-RC4-MD5:EDH-RSA-DES-CBC-SHA:EDH-DSS-DES-CBC-SHA:DES-CBC-SHA:EXP-EDH-RSA-DES-CBC-SHA:EXP-EDH-DSS-DES-CBC-SHA:EXP-DES-CBC-SHA:EXP-RC2-CBC-MD5:EXP-RC4-MD5 In reality, if every server is configured to use the same cipher, you really only need one, such as: ciphers = EDH-RSA-DES-CBC3-SHA Having additional cipher algorithms listed certainly can't hurt, though, since a particular installation might be missing one or more. $Id: README,v 1.5 2004/05/19 19:42:25 mmarsh Exp $