Implementation notes on the PKITS test list generator
----------------------------------------------------

The code for the PKITS test list generator is divided into two parts:  the
module that generates the output and the modules that implement the GUI.  The
GUI code was created using Glade. The program was developed on a Linux system,
but should compile on any system that has the GTK+ version 1.x development files
and should run on any system that has the GTK+ version 1.x libraries. The GUI is
very simple, so it should be possible to create an implementation of the GUI for
other platforms with little effort.

The module that generates the output, generate_html.c, was written in C and
should compile on any operating system without the need for modification.  This
module defines 20 global variables.  Each variable must be set to 0 or 1
depending on whether the application or library that is to be testing implements
the corresponding function.  The GUI's only purpose is to allow users to
interactively set these values and to obtain the name of the the file to which
the output is to be written.  If these values are set correctly within the
program for a given path validation module implementation, then program could be
used without an OS dependent GUI by writing a simple main() function that calls
generate_HTML().

generate_html.c is currently designed to create an HTML file.  The generated
HTML file contains a table listing every test from PKITS.  It indicates for each
test: the name of the test; whether the test needs to be run; and the expected
result from running the test.  A column is also included in the table to allow
the tester to specify the actual result from running the test.

The generate_HTML() function generates the table by calling one of two functions
for each test, either print_test_entry() or print_notest_entry().
print_test_entry() is called for tests that need to be run for the given
implementation and print_notest_entry() is called for tests that do not need to
be run. The print_test_entry() and print_notest_entry() functions are each
provided with the same information:  the name of the test and the expected
result in string form.

The print_test_entry() and print_notest_entry() functions are also provided
with following information for each test:

  * the name of the file that contains the self-signed trust anchor certificate
  * the name of the file that contains the end entity certificate
  * the name of the file that contains the PKCS #12 with the end entity's private key
  * the name of the file that contains the sample S/MIME message
  * the user-initial-policy-set as a string with a comma separated list of
    OIDs (a NULL string is any-policy)
  * the value for initial-policy-mapping-inhibit
  * the value for initial-explicit-policy
  * the value for initial-any-policy-inhibit
  * the expected result of the test as an integer (VALID, INVALID_PATH, REVOKED, STATUS_UNKNOWN)

An expected result of VALID means that the path should validate successfully.
An expected result of INVALID_PATH means that path is invalid for some reason
(e.g.,subject/issuer names do not chain, a signature did not verify, a path 
length constraint violation, a name constraint violation, a policy processing 
error,etc.). An expected result of REVOKED means that the certificate is known
to be revoked or on hold.  A expected result of STATUS_UNKNOWN means that for
some certificate in the path there was no valid, up-to-date certificate status
information available so it was not possible to determine whether or not the
certificate was revoked.

This inputs and expected result (the integer version) are not used by the PKITS
test list generator as it is currently written. This information is included in
the calls to print_test_entry() and print_notest_entry() so that the program can
easier to customized for other uses.  For example, one could test a path
validation library by replacing the print_test_entry() function with a function
that uses the provided inputs to call the library's validation function and then
compares the result provided by the library to the expected result. The
print_notest_entry() function could be replaced by a function that does nothing
if one only wanted to perform the minimal testing.

