Trusted QSL library (tqsllib)
2003-05-30 J. Bloom, KE3Z

If what you want to do is use tqsllib in your own program, consider
using one of the prebuilt packages at:
   http://sourceforge.net/projects/trustedqsl/

To build this library you'll need to have the OpenSSL library
(www.openssl.org). You also need the expat XML library
(http://www.jclark.com/xml/expat.html).

NOTE: Part of this library is exported from a separate source tree used
in LOTW server development. That accounts for some of the weirdness
you'll see in the source files.

Please report any problems and fixes to jbloom@arrl.org

BUILD
=====
Linux/Unix
----------
./configure [--with-openssl=DIR]
make -f Makefile.lib

This will build the library (libtqsllib.a) and some simple test programs.
(See the TESTING section below.)

If the OpenSSL files aren't where the compiler can find them, use the
--with-openssl option to specify the openssl base directory, which
should contain lib and include directories. Example:

   ./configure --with-openssl=/usr/local

The same applies to the expat library using --with-expat. 

Windows
-------
Note: if you are interested only in using tqsllib with your own
programs, you probably can use the prebuilt DLL. See the DEVELOPMENT
section below.

The library is built under MinGW. To build it, you need to install MinGW
and use it to build the OpenSSL library. You also need MSYS (available
from the MinGW site) or a similar environment. With that, you can follow
the instructions given above under Linux/Unix.

A Windows DLL of the expat library can be downloaded; you don't need to
build the library. You will, hovever, need to create an import library
(libexpat.a) using dlltool (part of the MinGW utilities).

tqsllib links with the zlib library (http://www.gzip.org/zlib/).
Since that library is provided with wxWindows and since tqsllib was
developed in an environment where wxWindows was present, Makefile.lib
just picks up zlib from the wxWindows directory. Absent wxWindows,
you'll have to provide zlib and change the makefile.

A DLL (tqsllib.dll) is also created, and the test applications (see the
TESTING section below) are linked against that DLL.

TESTING
=======
Several programs are built to perform simple testing of the library. If
testing is being performed in an environment also used for operation,
you should probably set the TQSLLIB enviromnent variable to point to a
test directory before running the test programs. That will avoid
conflicts with the "real" certificate store.

In the test programs command-line arguments, the DXCC entity is the
entity number, not the name. DXCC entity numbers can be obtained from
dumptqsldata.

dumptqsldata - Lists the configuration information from the tqsllib
configuration file (config.xml), which must be present in the tqsllib
directory.

gen_crq - Generates a simple certificate request using fake address
data.

load_cert - Loads a certificate into the certificate store.

station_loc - Creates a minimal station location for the supplied call
sign and DXCC entity.

converter - Signs an ADIF or Cabrillo file using the specified station
location.

DOCUMENTATION
=============
API documentation can be found in the doxygen directory. You can rebuild
the documentation by simply running doxygen using the Doxyfile
configuraton file.

DEVELOPMENT
===========
A package for Windows development is available at:
   http://sourceforge.net/projects/trustedqsl/
That package contains the tqsllib DLL, needed header files and
documentation.

The header files that may be needed to use tqsllib are:
tqsllib.h
tqslerrno.h
adif.h
cabrillo.h
sysconfig.h
tqslconvert.h

(Additional header files are used to build the library.)

TODO
====
This was developed and build using GCC 2.96. It needs to be built and
tested under GCC 3.x.

Similarly, it needs to be built and tested under openssl later than
0.9.6.

The certificate import, export and delete functions are not yet
implemented.

Configuration/Makefile stuff needs work.

