Safe C String Library v1.0.3 (January 30, 2005)
(c) Copyright 2003-2005 Matt Messier and John Viega

1. Introduction

The goal of the SafeStr library is to provide a rich string-handling library
for C that has safe semantics yet interoperates with legacy library code in a
straightforward manner.  Additionally, porting code that uses standard C string
handling should be straightforward.  The library should work on all modern
Unix-like platforms, as well as any 32-bit Microsoft Windows OS.

The overt security goals of the library are as follows:
    1) Buffer overflows should not be possible when using the API.
    2) Format string problems should be impossible when using the API.
    3) The API should be capable of tracking whether strings are "trusted", a
       la Perl's taint mode.

The API is meant to provide rich functionality and be easy to use, all the
while improving security.

2. Requirements

The Safe String library will work on Unix (including Linux) systems as well as
any 32-bit version of Microsoft's Windows operating system.  It uses only
standard ANSI C functions.

In addition, SafeStr requires XXL, which is an exception and asset management
library for C and C++.  You can obtain a copy of XXL from:

    http://www.zork.org/xxl/

Please see XXL's distribution for information on building and installing it on
your system.

Beginning with SafeStr 0.9.6, the latest version of XXL is bundled.  If it is
not already installed on your system, SafeStr's build process will build (and
install) it.

3. Building

On Unix, building the Safe String library requires that you have XXL installed
on your system (see 2. Requirements).  Once you have XXL installed, you must
configure SafeStr by running the configure script included in the distribution:

    ./configure

The configure script is a standard autoconf generated shell script that will
check your system for the various header files, libraries, and compiler
characteristics that SafeStr requires to build successfully.  Configure's
default options are generally acceptable, but you may run the script with
--help to obtain a list of options that may be adjusted.  Once the configure
script has run successfully, compile the source by running make.  

On Windows, a Microsoft Visual Studio 6.0 project file is included
(safestr.dsp), which you may use to build the Safe String library on your
system.  It expects to find XXL's header file, xxl.h, in the include path, and
XXL's import library, xxl.lib, in the library path.

4. Installation

On Unix, installation is performed by running make with a target of install:

    make install

The default installation path is /usr/local, but this location may be changed
by specifying an alternative path to the configure script during the build
process.

The Unix install process will install the SafeStr header file, safestr.h, into
${prefix}/include.  In addition, libraries that are built will be placed into
${prefix}/lib.  Finally, complete manual pages are included with the SafeStr
distribution that will be installed into ${prefix}/man/man3.

On Windows, there is no automated installation process.  You should place the
files that result from building SafeStr into the appropriate locations.  The
file safestr.h should be placed in directory in your INCLUDE path, safestr.lib
should be placed in a directory in your LIB path, and safestr.dll should be
placed in a directory in your PATH.

5. Contact

The official distribution site for the Safe String library is:

    http://www.zork.org/safestr/

The authors, Matt Messier and John Viega, may be contacted at safestr@zork.org.
Please report problems to the same address.  Patches may be contributed to the
same address; inclusion in the official distribution is subject to the approval
of the authors.

6. License

The Safe String library is licensed under the BSD license.

The distribution tarball (Unix) or zip file (Windows) should contain the file
LICENSE that contains the details of the license.  If it does not, you do not
have a complete distribution!  Please obtain a copy of the distribution from
the official distribution site (see above).

7. Known Issues

* Functions that deal with floating point types call underlying C runtime
  functions to deal with them.  Notably, the printf-style formatting functions
  call sprintf() for the %e, %f, and %g format specifiers.  Additionally,
  safestr_todouble() calls strtod().
* Because the printf-style formatting functions call sprintf() for the %e, %f,
  and %g format specifiers, the L (long double) length modifier may not produce
  output with the proper precision on some platforms.  The reason is because
  some sprintf() implementations cast the long double value down to a double,
  which results in a loss of precision.
* Support does not exist in the printf-style formatting functions for %a and
  %A, which are both specified by C99.  The reason for lack of support is that
  not all underlying sprintf() functions support them.
* The manual pages contained in this distribution are out of date.  They are
  largely accurate, but they do contain some information that is incorrect due
  to changes in the library since the last alpha release.
