Cryptix README or Readme Src or Readme Bin
Frequently Asked Questions
API index
Documentation
Java Cryptography Extension Specification
Utility scripts
Copyright and License
Distribution
Cryptix Security Provider
International JCE
JavaSoft documentation
Cryptix

Development

Team

Cryptix TM
Testing of Binary Distribution

Repeating the Distribution Tests

The distribution process writes a test script. This should work (although at the time of writing was untested for DOS-based systems).

In order to repeat the entire distribution tests, run the scripts in ../auto:

     ../auto/testjar.sh
or, for NT/95
     ; this script is untested, and unwritten as of the current dist.
     ..\auto\testjar
These tests are directly written by ../auto/testjar.sh and include all the necessary CLASSPATH settings. They currently take about 10 minutes on a 100MHz Pentium.

Note that if you receive an interim release, then the tests that failed during distribution are commented out within the above scripts. You can uncomment them, but they are unlikely to work. Note also that there should be no failed tests, this is more a tool to assist the distribution process. To date, no 3.0.x distribution has been released with failed tests.

JARs supplied

Follows is a description of how the distribution is structured that will be needed for troubleshooting.

The binary distribution comes with a group of JAR archives within the classes directory. Each JAR is a major module within Cryptix.

In summary, a provider such as Cryptix.jar is a cryptographic library that includes one or more algorithms. It is coupled with a JCE implementation such as IJCE.jar, in order to provide a complete cryptographic solution. The other jar files are for compatibility with earlier versions of Cryptix, and should not normally be needed.

Troubleshooting Strategy

Cryptix generally installs and runs quickly on the common platforms, because most of the installation difficulties are ironed out. In theory, the tests supplied, and especially those run by ../auto/testjar.sh are working and tested at distribution point.

Any failures indicate that there is a portability bug. If you are working with a new platform, then you might experience difficulties. Here's a troubleshooting guide that tries to build up a number of tests to see where problems might occur.

Note that

1. Basic Java

The most basic check is to find out whether you can run any Java in the Cryptix distribution.

For this purpose find these files *:

    cryptix/util/math/BigRegister.class cryptix/util/core/ArrayUtil.class cryptix/test/TestBR.class cryptix/test/BaseTest.class cryptix/test/TestException.class
within Cryptix.jar in the classes directory. Extract the compiled classes out of Cryptix.jar (using jar or unzip) into the obvious hierarchy cryptix/....

Then run the test in the normal fashion:

     java cryptix.test.TestBR

You should see lots of output:

    Start tests...
    
    Binary dump of a BigRegister [64-bit]...
    Byte #:|........|........|........|........|........|........|........|........|
    	 8: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
    
    {big snip}
    Done tests...
    ===========================================================================
    Number of passes:   8
    Number of failures: 0
    Expected passes:    8
which should print out lots of test results. Note that:

If you can't get this far, which is all straight Java, then something is seriously wrong, and you will need to seek help to ascertain that you have correctly loaded Java, and that the Cryptix files you have are OK.

* they are all on one line above so that you can Cut&Paste the classes onto an unzip command.

2. Checking the JAR format

Once we have confirmed that Java is sound, the next step is to confirm that the JARs in the binary distribution are usable. (Remove the above class files if they are in the classes directory, they might confuse the following tests.).

The most basic test is to run the above tests again, but using the JARs. Set your classpath variable to include Cryptix.jar and the current directory (but also save the original classpath for later):

      $ OLD_CP=$CLASSPATH
        CLASSPATH=$OLD_CP:<full path to Cryptix.jar>; export CLASSPATH
or, for systems with DOS batch scripting:
      c:\cryptix>set OLD_CP=%CLASSPATH%
                 set CLASSPATH=%OLD_CP%;<full path to Cryptix.jar>
It is important to use the full path of the .jar file. Using a relative path may work, depending on your version of Java, but is not recommended. Then, run the java test above:
      java cryptix.test.TestBR
Which should produce the same output as test 1, above. If it doesn't work, then the problem might be one of: Note precisely what you had to do for later tests.

3. Testing the IJCE

Next, we need to test the IJCE. This is done by putting both IJCE.jar and Cryptix.jar in your classpath.
      $ CLASSES=<full path to classes directory>
        CLASSPATH=$OLD_CP:$CLASSES/IJCE.jar;$CLASSES/Cryptix.jar
        export CLASSPATH
or, for DOS:
      c:\cryptix>set CLASSES=<full path to classes directory>
                 set CLASSPATH=%OLD_CP%;%CLASSES%\IJCE.jar;%CLASSES%\Cryptix.jar
Note that these should be modified according to the conditions you discovered in the previous test.

Then, run:

     java cryptix.test.TestIJCE

Read the test results carefully. They should show an algorithm being tested, and at the end, the number of tests that have passed and failed.

(In a later release, we'll have a single program that tests the IJCE without needing anything but IJCE.jar in the classpath.)

4. Testing the Algorithms

Now try out the different tests in the cryptix.test package (you can examine this package by opening Cryptix.jar in Winzip, or using unzip -l Cryptix.jar on Unix). For example:
    java cryptix.test.TestDES
    java cryptix.test.TestElGamal
The ElGamal test will take a while: 95 seconds on a P100. ElGamal is new, so please try it out and post any failures.

6. Rewrite the Auto Scripts

Once the all the tests below work, pretty much everything else should work unless there is a bug in the Cryptix software.

The next step is to examine the test script in auto (there is one for Unix and one for DOS-based systems) and then re-write that according to the local conditions you have identified.

Please make sure to post on users@cryptix.org the results of your investigations for any new platform, so that we can fix the distributions for the future.


Cryptix Copyright © 1997 Systemics Ltd
on behalf of the Cryptix Development Team.
All rights reserved.
Cryptix is a trademark of Systemics Ltd.