CppForDevelopers

Keyczar C++ for Developers

Implementing a new Reader

A new reader would be useful for reading keys and metadata from a new support or for being stored under a different format.

Keyczar::Read() (keyczar.h) initially expects string locations and automatically instanciates a KeysetFileReader object. However its Read() method is overloaded and also accepts Reader (keyset_reader.h) objects, so it is possible to use new readers (for example KeysetEncryptedFileReader is used exactly like this).

Implementing a new Writer

The main reason for implementing a new writer would be the need to create and update metadata and keys on a new support or represented in a different format. Note: in this case it would also be necessary to modify keyczart. Hopefully keyczart relies on KeyczarTool (keyczar_tool.h) which is designed to be generic and instanciate its readers and writers through a factory. The steps for creating a new working writer would be:

1. Implement a new writer inheriting from KeysetWriter (keyset_writer.h)
2. Update the enum type inside keyczar_tool.h to accept this new LocationType.
3. Update keyczart keyczart.cc to support this new writer there is an hidden option --form dedicated to this purpose.

Supporting a new architecture

For supporting a new architecture e.g. Win it would be necessary to accomplish the following steps:

• Update the build scripts src/main.scons, src/keyczar/build.scons, swtoolkit/site_scons/site_init.py and add a new target_platform_xxx into swtoolkit/site_scons/site_tools.
• Most compatibility/portability issues will likely located into base directory. Update the architecture dependent files. The corresponding Chromium base/ directory might help for this task.
• Maybe few others modifications would be needed in src/keyczar/, likely here.
• Read the next section.

Implementing a new crypto backend

If one had to port this code to Win it would probably make sense to use MS CryptoAPI or CNG to implement the cryptographic operations. Roughly, what would then be required would be to implement a new subdirectory keyczar/capi/, for replacing the default implementation provided by keyczar/openssl/.

Then the factory methods implemented inside CryptoFactory (see crypto_factory.h) would have to be updated. The switch between the implementations could then be operated at compile time by defines or at execution by implementing a switch(){}.

For more insights on this design read the comments inside key.h.

If the cryptographic library has special steps for initializing the random number engine, implement what is required inside a RandImpl::Init() (rand_impl.h) method and be sure to call it before any cryptographic operation using random numbers has to be performed. For example see run_all_unittests.cc and rand.h for how this initialization is implemented and should be called.

Generating key sets of reference

testdata_gen is used for generating the content of the subdirectory data. This code needs to be updated each time a new cryptographic algorithm is implemented or modified.

Advanced use

KeyczarTool

It could be useful to use KeyczarTool (keyczar_tool.h) for something else than for implementing keyczart. For example testdata_gen (testdata_gen.cc) sucessfully use it for generating all the key sets of reference.

Keyczar

A Keyczar (keyczar.h) subclass can directly be instanciated with a Keyset (keyczar/keyset.h) object as argument. Likewise it is possible to access the key set of a Keyczar instance by calling the keyset() method.

Key sets writers observers

Observers are used for signaling key set writers that the in-memory key set has been updated and that these changes should be written. FIXME.

Code development

C++ Style

This project use this style guide for all C++ code.

Exceptions

C++ exceptions are not used for this project. The source code is compiled with -fno-exceptions. For a rationale read this page

Base directory src/keyczar/base/

• There are two kinds of asserts CHECK() and DCHECK() (see logging.h). Both are fatals but only CHECK is triggered once the code is compiled with mode=opt-linux. DCHECK is triggered only during debug mode. As principle this project tries to avoid fatal interruptions during optimized mode execution. So the preferred way of handling errors is by returning NULL or false values. On irrecoverable errors however CHECK can be used.
• scoped_ptr (see scoped_ptr.h) and scoped_refptr (see ref_counted.h) are used for managing pointers. Altough multiple references should be avoided, Key objects (key.h) are managed through scoped_refptr mostly because a Keyset (keyset.h) must maintains two references on each key.