Gnu Crypto
===========

1. Mission Statement
---------------------
The gnu.crypto project aims at providing versatile, high-quality, and provably
correct implementations of cryptographic primitives and tools in the Java
programming language for use by programmers and end-users.


2. Versatilitiy
----------------
JavaSoft's JCA/JCE is a de-facto standard of a cryptographic API, but is not
the only one!  Others; eg. GSS-API, exist.  There is also no proof that the jce
_is_ an optimal minimalist API on which to build more elaborate ones.  Needing
access to cryptographic primitive implementations that do not require the heavy
JCA/JCE is a reality; eg. need to encrypt database user credentials data in an
application.  This package should be able to provide this.

This by no means implies that gnu.crypto _replaces_ or obviates the need of the
JCA/JCE.  The gnu.crypto library _is not_ another JCE implementation.  It
should be capable of being used by JCE implementations --a list of such
implementations may include JavaSoft's jdk1.4 (which is supposed to include a
JCE), cryptix (<http://www.cryptix.org>) and bouncycastle
(<http://www.bouncycastle.org/>).

Other framework should also be considered; eg. the now in gestation GSS-API in
Java (see JSR-72 <http://jcp.org/jsr/detail/72.jsp>).


3. High Quality
----------------
By this i mean fast, thread-safe, even multi-threaded, and hardware-friendly
implementations.  If this means different implementations each suited to
specific environments, so be it.  Configuration needs should not be sacrificed
for programmers' convenience.


4. Correctness
---------------
There is no point in having a fast implementation of an algorithm that is not
correct.  Defining what correct means and how to prove it would help us, and
others, learn new techniques to incorporate and follow, in implementations, to
ensure attaining such objective.


5. Tools
---------
Having access to tools that exercise cryptographic primitives to evaluate their
performance and characteristics help programmers and designers when selecting
primitives for their application.  There are always subtle differences between
algorithms --not to mention different implementations of the same algorithm.
Performance is affected by the platform on which the implementation is supposed
to run.  All these imponderables tend to blur the vision of the designer and/or
architect; as a consequence they then choose _one_ algorithm, usually the most
talked about in the magazines they read and forget about it.

Here is a list of features such tools may offer:

* measuring dispersion (white noise quality) with prng implementations,
* pattern detection in cipher output.
* compose, and why not through a GUI :-), ciphers from more basic objects:
  SBox, Feistel, LFSR (Linear Feedback Shift Register), etc...
* comparing output with published test vectors.


6. Coding Style
----------------
Source code in the repository must be written in conformance to the Coding
Style guidelines used in this project; i.e.:

JavaStyle <http://www.gnu.org/software/classpathx/crypto/guide/JavaStyle.html>,
AntStyle <http://www.gnu.org/software/classpathx/crypto/guide/AntStyle.html>.


7. Configuration Parameters
----------------------------
There are two parameters that would impact the behaviour of the binaries.  These
are:

	* DO_MILLER_RABIN: in gnu.crypto.util.Prime, and
	* REPRODUCIBLE: in gnu.crypto.util.PRNG.

7.1. DO_MILLER_RABIN
.....................
In various places throughout this library, large positive prime numbers are
generated and used; e.g. keypair generation, digital signature scheme signing
process.  When needing to test the probable primality of such numbers, the code
in this library invokes the method Prime.isProbablePrime(x), which is then
translated into Prime.isProbablePrime(x, DO_MILLER_RABIN).  By default, this
constant --DO_MILLER_RABIN-- is set to FALSE, implying that if the designated
number passes Euler Criterion (a Java port of Colin Plumb implementation in C,
included in his bnlib version 1.1) the number is then declared a probable prime
and no further tests are carried out.  This is in agreement to Colin's comment
in the code that "...everything else is just gravy..."  However, if you wish to
change this behaviour to conduct a Miller-Rabin strong probabilistic primality
test as described in the literature, then you should change the value of this
constant --DO_MILLER_RABIN-- to TRUE _and_ regenerate the binaries (jars) --if
using ANT, by invoking:

   $ ant jar

Doing so, causes an (additional) invocation to the Prime.passMillerRabin(x)
method, if the designated number passes all other tests.  The final result
becomes then that of the Prime.passMillerRabin() method.

7.2. REPRODUCIBLE
..................
For the sake of convenience, all invocations in this library to generate
cryptographically strong pseudo-random data (bytes) are done through a
classloader Singleton, inside the gnu.crypto.util.PRNG class.  This Singleton
generator is an instance of the pseudo-random number generator based on a
generic hash function --the class gnu.crypto.prng.MDGenerator-- using, in this
case, the Secure Hash Standard (SHS, also known as the Secure Hash Algorithm SHA
with 160-bit output block size).  This is appropriate for two reasons:

	a. this method of generating random data is the one prescribed in the Digital
		Signature Standard (DSS),
	b. other digital signature schemes, implemented so far in this library, do
		not mandate any prescribed way for generating random data.

However, this type of generator works by hashing the output of a previous digest
operation; i.e. the input to the hash function at time N is its output at time
N-1, with the starting input being a 0-long octet string.  The sequence of
generated bytes from such a generator is then _reproducible_.  This is useful
for test and debugging purposes only and obviously should not be the case in any
security-conscious application.

To change this behaviour, change the value of the constant REPRODUCIBLE in the
class gnu.crypto.util.PRNG to FALSE _and_ regenerate the binaries (jars) --if
using ANT, by invoking:

   $ ant jar

Doing so, causes a SEED value, based on the system current time in milliseconds,
to be injected into the initial input.


The home page for this project is at www.gnu.org/software/classpathx/crypto.
See INSTALL for installation instructions.


8. Building
------------
See the file INSTALL in the same directory where this file resides.


9. TODO
--------
* improve the auto-* process; e.g. remove the need to enter the source files by
  hand without losing information about inner classes.
* integrate the gcj/ process into the main one.
* add support for configuring and using Kissme as a replacement for java.
* improve the documentation.
