= Keyczar C++ =

== Dependencies ==

- C++ compiler
- Python for running the build system
- OpenSSL (>= 0.9.8b)
- gtest (>= 1.4)
- [Optional]: Zlib (for compression)
- [Optional]: Swig (Python binding)

=== Ubuntu/Debian ===

Packages g++ make libssl-dev zlib1g-dev libgtest-dev python python-dev swig

=== MacOSX Snow Leopard ===

XCode > 3.6 and MacPorts with the following packages: swig

MacPorts is necessary only for the Python (via swig) binding.  If
you are using the C++ API, MacPorts is not necessary.

Previous versions of Mac OS X should also work, but you should test to be
sure.

Download a copy of gtest from https://code.google.com/p/googletest/downloads
and unpack it in a convenient location (you'll need the path for the build
command below).

== Supported architectures and systems ==

Processors: x86, x86_64, ARM
Systems: Linux, MacOSX (with MacPorts), BSD (OpenBSD, FreeBSD)

Note: only Linux x86 has been tested extensively


== Local build ==

For a local build of Keyczar C++ on Linux (or, with small changes, on Mac) run these commands:

 $ cd src && sh ./tools/swtoolkit/hammer.sh -D GTEST_DIR=/usr/src/gtest --mode=opt-linux --compat

- Replace /usr/src/gtest with the path to your gtest src dir (this path is
  correct for Ubuntu).
- Replace opt-linux by opt-bsd or opt-mac depending on your system
- The Python binding is built automatically if swig is detected
- Libraries and executables are assembled under scons-out/opt-linux/
- The keyczart tool is located at scons-out/opt-linux/staging/keyczart.
  You can run it from that location or move it somewhere more
  convenient if you prefer not to install it.

== Install ==

You need to log as root and execute these commands:

  $ cd src && sh ./tools/swtoolkit/hammer.sh -D GTEST_DIR=/usr/src/gtest --mode=opt-linux --compat install

/!\ Note: it is actually highly recommanded to use the compatibility (--compat)
mode. This mode provides full compatibility with previous versions, other
Keyczar implementations (Java, pure Python) and the Google reference
implementation.

- Default prefix paths used are /usr/local/ and
  /usr/lib/python2.x/[site|dist]-packages for Python stuffs. Use
  src/options.conf and read src/tools/installer.py for overriding these
  choices.

- Learn how to use this library by reading the tutorial (on the wiki page), the
  examples located under src/examples/ and the main headers
  src/keyczar/keyczar.h and src/keyczar/keyczar_tool/keyczar_tool.h

== Options ==

--mode=XX  -> where XX can be opt-linux, opt-mac, opt-bsd, dbg-linux, dbg-mac or
              dbg-bsd. 'opt' stands for optimized mode and 'dbg' for debug mode.
--compat   -> ensure compatibility with Keyczar 0.6b specifications (see below)
install    -> install the C++ library and optionally its Python binding
-jX        -> use X threads for compiling it
-c         -> clean up the build and/or remove installed files


== Current Limitations ==

- Does not work on Windows (should be relatively easy to port it using OpenSSL
  however it would require much more work to use MS CAPI instead).
- Build system needs to be improved.


== Compatibility ==

- When compiled with option --compat this implementation is expected to be
  fully compatible with Keyczar 0.6b (see detailed specifications at
  http://code.google.com/p/keyczar/w/).
- When compiled without this option this implementation uses differents
  cryptographic algorithms as defined into algorithms.txt. And further
  modifications could happen in the future.


== This implementation relies on these projects ==

- Chromium:        http://code.google.com/intl/en/chromium/
- Protobuf:        http://code.google.com/p/protobuf/
- gtest:           http://code.google.com/p/googletest/
- Keyczar:         http://code.google.com/p/keyczar/
- OpenSSL:         http://www.openssl.org/docs/crypto/crypto.html
- SCons:           http://www.scons.org/
- Stringencoders:  http://code.google.com/p/stringencoders/
- Swig:            http://www.swig.org/
- Swtoolkit:       http://code.google.com/p/swtoolkit/


Credits to all the authors of those open projects and to the originals authors
and designers of Keyczar.