| 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.

- IJCE.jar is the International JCE. It is intended to stand alone as the support code for any Provider.

- Cryptix.jar is the main body of code for the Cryptix provider. It includes support classes, symmetric and asymmetric encryption algorithms, message digests, message authentication codes, signature algorithms, and tests for all of these.

- OLD.jar includes classes that provide the old Cryptix 2.2 API.

- OLDPGP.jar provides compatibility with the Cryptix 2.2 PGP library.
  Important: OLDPGP.jar contains code that has known security bugs, and should not be put on the CLASSPATH unless it is actually required.

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

- The tests are numbered in order of increasing difficulty. You might like to skip straight to test 2, and work forwards or backwards depending on results.
- this section assumes you are familiar with Java and your platform. If you are not, then seek help locally, as it is impractical to troubleshoot without local knowledge.
- all these examples assume you are in the `classes` directory.

#### 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:

- You may need to set your CLASSPATH variable to the current directory. See below for some examples on setting CLASSPATH.

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:

- The JAR format is not supported, in which case, use `unzip` to extract the classes and either `zip` them into a .zip or use the unzipped hierarchy directly. You might need to put that directory in the CLASSPATH.

- The CLASSPATH is wrong. Note that
  - some systems require that you include the Java archives, some don't.
  - check carefully that you have identified the right archive.
  Consult your manuals or other working examples.

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.

- You should have removed the class files from the previous test, as they will obscure any problems with the JAR archives.

- If you cannot get that to work, then try the previous test (`cryptix.test.TestBR`) again using the above CLASSPATH setup. If that works, there is something wrong with the Cryptix and IJCE archives, probably in the CLASSPATH.

(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.

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