=== About Pathfinder ===

Pathfinder is designed to provide a mechanism for any program to perform 
RFC3280-compliant path validation of X509 certificates, even when some of 
the intermediate certificates are not present on the local machine. It will
automatically download any such certificates (and their CRLs or OCSP 
information) from the Internet as needed using the AIA and CRL distribution 
point extensions of the certificates it is processing.

=== Building Pathfinder ===

Pathfinder uses the CMake build environment, which is analagous to the standard
autoconf/automake system. Building proceeds in two steps:

First, run "cmake .". This will create a set of makefiles which enables you to
actually build pathfinder (this is analagous to running "./configure" with an 
AutoConf-based system). 

Next, run "make". This will actually build the executables and libraries that
form Pathfinder.

To install Pathfinder, run "make install". This will install all files needed
to use Pathfinder into "/usr/local". If you wish to install Pathfinder into a
different prefix, you must specify this at configure time:

cmake -D CMAKE_INSTALL_PREFIX:PATH=<my preferred prefix> .

For example, running cmake as follows would build and install everything into 
/home/wlach/tmp:

cmake -D CMAKE_INSTALL_PREFIX:PATH=/home/wlach/tmp .
make install

Pathfinder only has three dependancies: D-Bus (to provide interprocess 
communication), WvStreams (to provide for downloading of certificates over
HTTP), and OpenSSL (to provide the relevant X509 and cryptographic functions
for path validation). However, in order to run the self tests (see below),
you will also need to have valgrind.

In order to build the pathfinder client libraries, you will need the OpenSSL
and LibNSS devel files.

=== Testing Pathfinder after building ===

To run the self tests on Pathfinder after building, you can run:

make test

which will run all of the various tests in the /t directory. These tests are
designed to ensure that Pathfinder can pass the NIST PKITS tests for PDVal.

If it fails, the failure can be viewed by running:

cat Testing/Temporary/LastTest.log

Please report any failures to:

http://code.google.com/p/pathfinder-pki/issues/list

=== Using Pathfinder ===

The heart of Pathfinder is a central daemon, "pathfinderd". This is the program
that actually does all the work of checking whether a certificate is valid or
not (by discovering a path and verifying it). Programs interface with pathfinder
by calling a D-Bus method which contacts the daemon with a hexified DER-encoded 
representation of the certificate they wish to validate.

How to set up a simple test case:

Say you had three certificates: 

1. CACert.der (self-signed trust anchor; trusted, present on local machine)
2. SubCACert.der (signed by CACert; existing only on a remote server)
3. ClientCert.der (signed by SubCACert; the certificate to be validated)

How would we set up pathfinder to validate them?

First, you would create a directory to store the trusted certificates. In 
this case, we only have one. For the sake of example, we'll put it in 
'/tmp/trusted':

mkdir -p /tmp/trusted
cp CACert.der /tmp/trusted

Now, we want to create a configuration file for the pathfinder daemon which
specifies the trusted location. An example is contained within the pathfinder
distribution:

[Trusted directories]
Extra certs = /tmp/trusted

You may opt to use this config file by referring to it via a command-line 
option. You want to run the pathfinder daemon as root, so it can listen on
the D-Bus system bus. It is also possible to listen on the session bus, for
testing purposes: just specify --session when running pathfinderd: for the
sake of example, let's do that:

./pathfinderd -c ini:pathfinderd.ini.sample --session

Now that we have pathfinderd running, we'll want to validate our certificate.
This can be done using the pathclient program, which will connect to the
pathfinder daemon via D-Bus and attempt to validate the client certificate:

./pathclient --session -t der ClientCert.der 

If everything is set up correctly, you should receive a message stating the
certificate is valid.

=== Configuring Pathfinder ===

The pathfinder configuration file is in ini-style format with the following
sections and keys.

[General]: This section contains keys that pertain to the general operation
of pathfinder.
- CRL Cache Location: This specifies where CRLs previously downloaded from
 the internet will be stored for later retrieval. 
 - Example: CRL Cache Location = /var/cache/pathfinder/crls/

[Trusted directories]: This section is used to specify directories containing
trusted certificates, in format "identifier" = "value"
 - Example: Trusted certs = /tmp/trusted

[Policy]: This section is used to specify policies to use for application
names sent to the pathfinder daemon in a validate request (see below).
 - Example: apache = 1.2.3.4

[Verification Options]: This section is used to specify options for altering
the way that pathfinder verifies certificates. This is intended primarily
for debugging and troubleshooting purposes, and in general users shouldn't
try to modify it.
 - Skip Revocation Check: If not set to 0 (or blank), disable revocation 
 checking for the pathfinder daemon.
  - Example: Skip Revocation Check = 0

[Bridges]: Specifies bundles that can be used to bridge trust between PKIs
(from an untrusted PKI, across the bridge, to a trusted anchor). Typically
such a bundle is published by a bridge, and contains 2 cross-certificates
for each bridged PKI: one issued by the bridge and one issued *to* the
bridge.  Specify one bundle per line.
 - Example: My bridge = /var/pathfinder/bridges/mybridge.p7c

[Intermediate CAs]: Specifies the AKIs of intermediate CA that may be
preferable when constructing a path or examining a bridge bundle. 
This is *not* essential for bridging to work, but it can improve
performance by choosing "your" CA certificate first when evaluating a
bridge bundle instead of iterating through other untrusted ones first.
For this section, the AKI is the key, the value should simply be 1.
 - Example: E0:26:A2:10:00:7D:D5:96:95:14:0C:F2:2E:54:63:F1:65:66:D9:0E = 1

[CRL Location]: Specifies a location on disk which should be used to find
a CRL associated with a particular CA. For client certificates of this CA,
this CRL will simply be loaded off of disk, instead of going over the network
for download. Note that the keys for the specified CA names should have slashes
escaped as %2f, and = signs escaped as %3d.  Names should be specified with
fields delimited by a (escaped) slash.
 - Example: %2FC%3DCA%2FO%3DSigning CA%2FCN%3DSubscriber Cert Signing Authority = /var/pathfinder/crls/mycrl.crl

[CA Location]: Specifies a location on disk which should be used to find
a specific CA (instead of looking in the AIA extension of the client 
certicate). Note that the keys for the specified CA names should have slashes
escaped as %2f, and = signs escaped as %3d.  Names should be specified with
fields delimited by a (escaped) slash.
 - Example: %2FC%3DCA%2FO%3DRoot CA%2FCN%3DCA Cert Signing Authority = /var/pathfinder/cas/myca.ca

=== Adding support for Pathfinder to your program ===

Pathfinder provides a D-Bus interface that allows you to contact the pathfinder 
daemon and request validation of a certificate. Currently, the interface only
contains one method "validate".

Interface name: ca.carillon.pathfinder
Object name: /ca/carillon/pathfinder
Method name: validate
Method parameters: String, String, Bool, Bool, (String)
 - String1: The certificate, in hexified der-encoded format. 
 - String2: The set of policies that you wish to enforce, in tcl-list format. 
   Examples: "2.5.29.32.0" (the anyPolicy OID), "{ 1.2.3.4 1.2.3.5 }" (two 
   policies: 1.2.3.4 and 1.2.3.5)
 - Bool1: Whether or not the initial explicit policy should be set as a
   verification parameter. This demands a valid policy tree at the end of 
   validation. Except in the case that very strict validation is desired, it
   is recommended to set this value to 'false'.
 - Bool2: Whether to inhibit policy mapping: this will disallow policy mapping
   at the very beginning of the validation process. Except in the case that 
   very strict validation is desired, it is recommended to set this value to 
   'false'.
 - String3 (optional): If present, this will tell the pathfinder daemon to use
   a security policy associated with a particular application or name, if it is
   specified in the configuration file. For example, you might specify a 
   particular policy with "apache". You can specify these security policies in 
   the main configuration file, see above.

For the convenience of those using OpenSSL or NSS (Netscape Security Services),
two libraries containing a callback suitable for use with an SSL connection are
provided. The "nsstest" and "openssltest" programs provided with the pathfinder
distribution provide examples of their use.
