This is Gwenhywfar, a multi-platform helper library for networking and
security applications and libraries.
It is used by
 - Libchipcard (http://www.libchipcard.de),
 - OpenHBCI2 (http://www.openhbci.de),
 - Simthetic, the simulation tool (http://simthetic.sourceforge.net)
 - AqBanking/AqHBCI (http://www.aqbanking.de/).
 - and others by using one of the projects above



Features
========

This library is written in C, and it follows the object-oriented
programming paradigm for most of its parts.  The header files can
directly be used from C++, too.

Gwenhywfar includes the following features:

- Basic Data types for binary buffers, ring buffers, linked lists,
  error objects, string lists (src/base/), buffered IO operations (src/io/)

- Macros for typesafe list management

- OS abstraction functions for directory and Internet address handling
  and library loading (src/os/)

- Networking functions which allow to manage many connections to be used
  economically even in single threaded applications

- High-level functions for parsing files with a simplified "XML-like"
  format and accessing them like a hierarchical database (src/parser/)
  It is able to process valid XML files, too.

- High-level cryptographic functions on top of OpenSSL functionality
  (src/crypt/)

- Support for interprocess communication (HTTP on top of SSL or plain
  TCP/UDP sockets, with or without certificates for clients and/or servers)

- A tool to generate simple data containers from XML files. It automatically
  generates getters, setters, constructor, destructor, deep-copy function,
  usage counter handling, modification tracking, functions for reading from
  and writing to GWEN_DBs (used by AqBanking to create the transaction class)



Requirements
============

- GnuTLS >= 1.4 (>=2.0.1 recommended)
- libgcrypt (>=1.2.0)



Platforms
=========

Gwenhywfar is being developed on Linux. But the following platforms are also
supported:

- Windows (98, NT and newer; for using this library from Microsoft
  Visual Studio C please see the explanations in test/README.MSVC)

- FreeBSD
- Linux     (i386, amd64, alpha)
- Mac OS-X
- NetBSD    (untested, but most likely to work)
- OpenBSD   (untested, but most likely to work)
- SunOS 5.9 (compiles, untested, but most likely to work)

On Windows, an .exe setup program is provided, created with the Inno
Setup Compiler http://www.jrsoftware.org/isdl.php .


Architectures
=============

According to Debian Gwen runs on the following platforms:
- alpha
- amd64
- arm
- hppa
- i386
- ia64
- m68k
- mips
- mipsel
- powerpc
- s390
- sparc



Environment Variables
=====================

"GWEN_MEMORY_DEBUG"
-------------------

This integer variable tells gwen whether (and how) to print the memory
debugger statistic. This only works for sources compiled with the defined
macro GWEN_MEMORY_DEBUG.
- "0" shows ALL listed objects
- "1" only shows those objects whose count is not 0


"GWEN_SSL_DEBUG"
----------------

If this environment variable exists the SSL code will append data received
via an SSL connection to "/tmp/read.bin" and append data sent via an SSL
connection to /tmp/written.bin".


"GWEN_TLS_CIPHER_PRIORITIES"
--------------------------

If this environment variable is set, the SSL code will initialize the GnuTLS
library with the provided cipher priority list.  If this environment variable
is unset, the default cipher priority list of the GnuTLS library is being used.

For the exact format of the cipher priority list and its default, please
consult the GnuTLS documentation, section "Priority strings":
http://gnutls.org/manual/html_node/Priority-Strings.html


Registry Keys
=============

On Windows platforms Gwen uses some keys below HKEY_CURRENT_USER
to store information about file/folder locations. The keys are set
in the Inno Setup file gwenhywfar.iss, so please check the
[Registry] section in gwenyhwfar.iss.in for the authoritative
source of available registry keys.

"Software\\Gwenhywfar\\Paths\\dbio-plugins"
-------------------------------------------
Complete path to the folder containing GWENs DBIO plugins.
(and some more keys. See gwenhywfar.iss.in)


Documentation
=============

The documentation can be found in the header files. Many header
files already include extensive comments in doxygen-format (however some
don't).
For a more or less complete API documentation use the command
"make srcdoc"
You will need the tool doxygen for this command to run.



Contact
=======

For questions about this library please ask on the mailing list of the
OpenHBCI project aqbanking-devel (subscriber-only, please subscribe
on http://lists.sourceforge.net/lists/listinfo/aqbanking-devel),
since this is where the author(s) hang out.



Authors
=======

This library is being written by and is being maintained by Martin
Preuss <martin@libchipcard.de>.

I also wish to thank Christian Stimming <stimming@tuhh.de> for his
contributions and for adding MSVC support to Gwen (thus making Gwen completely
available on Windows).



Name
====

The name of this library was chosen to honour a very special person ;-)
(that should suffice as an explanation)



Hamburg, Germany 2007/10/31

Currently Darwin does not handle the "__attribute__ ((constructor))"
entries in C files as it seems, so in your programs on Darwin you will
have to call GWEN_Init() yourself before doing anything else...

Currently Solaris does not handle the "__attribute__ ((constructor))"
entries in C files as it seems, so in your programs on Solaris you will
have to call GWEN_Init() yourself before doing anything else...

If programs linked against libgwenhywfar complain about unavailable libraries
upon start (most likely they mention OpenSSL) you should try this:
LD_LIBRARY_PATH="/usr/local/ssl/lib:/usr/local/lib" YOURPROGRAM

The LD_LIBRARY_PATH variable tells the Solaris linker where to search for
libraries in addition to the system folders.

1. Using Gwenhywfar
===================

1.1. Needed Components
----------------------

1.1.1. GNU TLS

We use the precompiled packages from the wireshark project (gnutls 1.6.0)
which also contain all needed libraries such as libgcrypt and libgpg-error.




2. Compiling Gwenhywfar
=======================

2.1. Needed Components
----------------------

2.1.1. MinGW32

Gwenhywfar uses MinGW32 on Windows platforms.
MinGW32 is a project with the goal to provide a free compiler system and a
nearly complete shell environment which allows to execute the configure
script. The resulting DLLs and EXEs only link against Windows libraries, so
there are no licence issues when releasing binary packages.
These EXEs and DLLs don't need MinGW32 to be installed on the target system.
The compiler itself is the very well known GCC.

One configure command line that used to work is the following:

  ./configure CPPFLAGS="$REGEX_INCLUDES $GNUTLS_INCLUDES $INTL_INCLUDES" \
     LDFLAGS="$REGEX_LDFLAGS -lregex $GNUTLS_LDFLAGS $INTL_LDFLAGS -lintl -liconv"

which just means you have to manually supply the -I/some/dir flags and
-L/some/dir/lib flags for libregex, libintl, libiconv, and gnutls.


2.1.2. GnuTLS

We use the precompiled packages from the wireshark project (gnutls 1.6.0)
which also contain all needed libraries such as libgcrypt and libgpg-error.
To compile gwenhywfar you will also need the developer files (ending in
*.dll.a and *.h).




3.2. Cross-compiling on Linux
-----------------------------

3.2.1. Compiling


Gwenhywfar can be cross-compiled. The author uses Debian and its mingw
package. To compile Gwenhywfar in that environment just use the following
commands:

>$ make -fMakefile.cvs mp-w32
>$ make
>$ make install DESTDIR=/tmp/gwen


3.2.2. Preparing Files for Shipping

You must then take the DLLs and executables (EXE) from the folder /tmp/gwen
and copy them into a folder for shipping. When preparing the application
shipping folder you should have the expected file hierarchy (see above) in
mind so that the application will find all DLLs and data.


3.2.3. Installing to the Cross-Compiler Environment

If you want to compile other projects which depend on Gwenhywfar you will
have to install some files to the cross-compilers environment. On Debian
this is /usr/i586-mingw32/. Header files go to /usr/i586-mingw32/include
and libraries must be installed to /usr/i586-mingw32/lib.
Please don't install the DLLs, only the *.dll.a files, because those are
the ones needed to compile depending projects (like AqBanking and
Libchipcard).