This is the README file for Cryptix OpenPGP.

0. What is this

   Cryptix OpenPGP is a Java implementation of the OpenPGP standard as defined
   in RFC 2440 and it's predecessor RFC 1991. 

   Cryptix OpenPGP is not a user application. Instead it's intended audience 
   are developers who want to add PGP encryption or signatures to their 
   application.

   The main author for Cryptix OpenPGP is Edwin Woudt <edwin@cryptix.org>
   Development was in part funded by Systemics Inc. <http://www.systemics.com/>
   
   Other people who have been helpful during the development, providing me with
   code, bug reports, fixes and feedback: [Let me know if I forgot someone]

      Jill Baker
      Ian Brown
      Jeroen C. van Gelderen
      Ian Grigg
      David Hopwood
      Gary Howland
      Guido Jaekel
      Mathias Kolehmainen
      Erwin van der Koogh
      Alex Krolick
      Ingo Luetkebohle
      Tassilo Schuetz
      Al Sutton
      Jure Zvikart


==== Quick Start ==============================================================


1. Dependencies

   Cryptix OpenPGP needs:
   - Cryptix JCE               (see section A below for other JCE's)
   - JDK 1.2, 1.3, 1.4 or 1.5  (see section B below for JDK 1.1)


2. Classpath

   Include the following files in your classpath:
   - From the OpenPGP distribution:
     - cryptix-openpgp-provider.jar
     - cryptix-message-api.jar
     - cryptix-pki-api.jar
     - certpath-compat-api.jar
   - From the Cryptix JCE distribution:
     - cryptix-jce-provider.jar
     - cryptix-jce-api.jar
   
   Note: do NOT include cryptix-jce-compat.jar in your classpath! (Unless you
   are running JDK 1.1, but in that case Cryptix OpenPGP will not run anyway,
   see section A below).
   

3. Installing the providers

   You need to add the following two lines to your java.security file (which 
   lives usually somewhere near $JAVA_HOME/jre/lib/security):
   
      security.provider.x=cryptix.jce.provider.CryptixCrypto
      security.provider.y=cryptix.openpgp.provider.CryptixOpenPGP
   
   Replace x and y by two numbers, so that all providers have sequential 
   numbers.
   
   It is also possible to register the providers dynamically. In that case, put
   the following two lines somewhere in the beginning of your program:

      java.security.Security.addProvider(
          new cryptix.jce.provider.CryptixCrypto() );
      java.security.Security.addProvider(
          new cryptix.openpgp.provider.CryptixOpenPGP() );
   

4. Installing the policy files

   This section only applies if you are running JDK 1.4+ that comes with the
   Sun JCE by default, or JDK 1.2/1.3 if you have installed Sun JCE 1.2 
   manually.
   
   The default distribution of the JCE allows as Sun calls it 'strong, but 
   limited strength cryptography'. This basically means that you cannot use RSA 
   keys bigger than 2048 bits, and no symmetric ciphers that use more than 128 
   bits. ElGamal is not allowed at all, thus DH/DSS cannot be used for 
   encryption.
   
   The solution is to install the Unlimited Strength Jurisdiction Policy files, 
   which can be downloaded from the following URL (note that they are listed 
   entirely at the bottom of the page, in the Other Dowloads section):
   
      http://java.sun.com/j2se/1.4/download.html
      http://java.sun.com/j2se/1.5.0/download.jsp
   
   These files have to be installed in $JAVA_HOME$/jre/lib/security
   

5. Documentation

   In the released versions, documentation can be found in doc/

   Example programs can be found in examples/


6. Support

   Commercial support is available from the main author. See the following URL:
   
     http://woudt.com/cryptix/ 

   Free support is available through a mailing list: the cryptix-users list.
   Subscription instructions are available at:
   
     http://lists.sourceforge.net/lists/listinfo/cryptix-users
     
   Here is a list of things to include in your question. This should help in
   getting a faster and better response:
   
   - Your JVM brand and version
   - Your operating system
   - Your full CLASSPATH, plus the contents of your $JAVA_HOME/jre/lib/ext
     directory (plus any other places for shared jar files)
   - If you get an exception: the full stacktrace
   - Preferably a small example program that demonstrates the problem

   For support questions, please do not mail the developers directly. It's not
   that they do not want to be bothered with support questions, it's just that
   they read the mailing list as well and the prefer to deal with questions
   there. 


==== Here ends the quick start section ========================================


A. Other JCE's

   In theory, Cryptix OpenPGP should work with any JCE 1.2 compatible provider.
   For symmetric ciphers and message digests this should work out of the box.

   For public key encryption and signing things become more difficult. Let us
   have a look at the three most common algorithms:
   
   - DSA: 
       Since JDK 1.1, Sun has included a DSA implementation in the JDK.
       We use this implementation and any other implementation that has the
       same DER-encoded output format for signatures should work allright.
   - RSA: 
       Because the JCE does not specify the output format of encryption and
       singing, Cryptix OpenPGP only works out of the box with providers that
       use the same 'raw' output format as Cryptix JCE. For other output 
       formats some changes to the source code of Cryptix OpenPGP have to be
       made. 
   - ElGamal:
       Because the JDK does not contain common classes for ElGamal keys, it is
       not possible to support different ElGamal providers without making 
       changes to the source code. At the time of writing this readme, the only
       provider implementing ElGamal encryption is the Cryptix JCE, so your
       choices are limited anyway.

   Bottom line: since ElGamal encryption is the most commonly used algorithm
   for OpenPGP (it's the default for both NAI PGP and GnuPG), your choices are
   at the moment limited to Cryptix JCE anyway.
   
   It is however possible and quite easy to use Cryptix OpenPGP with other 
   providers. Some small changes in the source code might however be necessary
   to get it working, but fortunately these are relatively easy.
   

B. JDK 1.1

   Cryptix OpenPGP does not work on JDK 1.1, because it uses (part of) the 
   Collection framework that was added to JDK 1.2. 
   
   Fortunately, this means that getting Cryptix OpenPGP to work on JDK 1.1 is
   relatevily easy: writing a cleanroom implementation of that part of the 
   Collection framework is enough, combined with the Cryptix JCE compatibility
   classes. 
   
   We have not had the time to do this ourselves and we actually hope that some
   volunteer will decide to do this and contribute it back to Cryptix.
   
   
C. What's this 'Cryptix PKI API'?

   The Cryptix PKI API contain extensions on some of the PKI/Certificate 
   classes available in the JDK. A quick overview of the extensions:
   
   - KeyBundle
       A KeyBundle is more or less a collection of Certificate's that belong
       together in some or another way. For example: one keybundle maps to
       one PGP 'key'.
   - KeyID / KeyIDFactory
       An abstract notion of variable length KeyIDs and a factory to create
       keyIDs from keys.
   - CertificateBuilder
       Creating your own certificates was always impossible from within the 
       JDK, this class remedies this.
   - PrincipalBuilder
       Class for creating principals.
   - ExtendedKeyStore / ExtendedCertStore
       Extended KeyStore and CertStore that handle KeyBundles
   
   While the concepts in this API map to technologies like OpenPGP, X.509 and
   SPKI, we only provide an implementation of OpenPGP for now.
   

D. What's this 'Cryptix Message API'?

   The Cryptix Message API is an api for creating and interpreting 
   cryptographic messages.
   
   It can potentially support different formats, like (Open)PGP, PEM, PKCS#7 
   and CMS (the format used by S/MIME), but for now only an OpenPGP 
   implementation is available.


E. Getting the 'real' source from anonymous CVS

   The cvs repository is now located at sourceforge:

      http://cvs.sourceforge.net/viewcvs.py/cryptix-openpgp/openpgp/
      http://sourceforge.net/projects/cryptix-openpgp

   For build instructions, please see the file BUILD.TXT provided with the CVS
   version.


F. Contributing

   If you have anything to contribute, please use the cryptix-users list
   (see section 6) or mail me privately: edwin@cryptix.org
   