$Id: architecture.txt,v 1.1.1.1 2008/09/10 09:32:57 agcrooks Exp $

Architecture document - BSD Privacy Guard
=========================================

This document contains information about BPG internal
architecture. Section 1 covers the system general design, which
modules conform BPG and how they interact. Section 2 explains the
internals of each module.


1. System design
----------------

The main goal of BPG is to provide applications with a toolkit for
using OpenPGP facilities. For that, we packed that functionality in
libraries.

There are four libraries, corresponding with the four problems BPG
tries to solve: data securizing, key management, trust management and
algorithms.




[INSERT A GRAPHICAL PICTURE OF THE SYSTEM HERE]




Also, a user interface will be included to the project, though it has
no impact on the design being discussed, since we consider it as
another external application making use of the BPG toolkit of
libraries.



2. Modules internals
--------------------

2.1. Data securizing (codename: libbpg)
--------------------

2.1.1. Introduction

This library manages the processing of OpenPGP data, including OpenPGP
general functions (section 2, RFC 2440), which are signing,
encryption, compression and radix-64 conversion.

It also defines all the other data types and formats in OpenPGP that
aren't related to the creation, storage and usage of keys, which are
included in the key management library.


2.1.2. Internal working

This is a rather simple library, since it only needs to build and
understand OpenPGP messages in a high-level. For using algorithms,
keys and compression it relies on external libraries:

* Key management library: PKI keys are especified in the API with
  user-IDs and obtained from the BPG key management library. The key
  management library is the responsible of key decryption if
  necessary.

* Algorithms library: for performing low-level encryption, hashing and
  compression, it uses the BPG algorithms library.

* Compression library: BPG will use libzip for compression
  (http://www.nih.at/libzip/).


2.1.3. API

The library provides a single plain API for building OpenPGP
messages.

NOTE: There are not explicit compression functions, since the
compression is done via external libraries and there's no reason for
adding an empty layer on them.


2.1.3.1. Encryption functions

* bgp_encrypt(INPUT, OUTPUT, KEY, ASYMM_ALGORITHM, SYMM_ALGORITHM)

* bpg_decrypt(INPUT, OUTPUT, KEY)


2.1.3.2. Signing functions

* bpg_sign(INPUT, OUTPUT, KEY, SIGN_ALGORITHM, HASH_ALGORITHM)

* bpg_verify(INPUT, OUTPUT, KEY)


2.1.3.3. Radix-64 functions

* bpg_binary_to_radix64(INPUT, OUTPUT)

* bpg_radix64_to_binary(INPUT, OUTPUT)



2.2. Key management (codename: libbpgkey)
-------------------

2.2.1. Introduction

This library manages the creation, storage, use and trust model of the
keys involved in OpenPGP.

The "BPG Key Management" document defines all key-related operations
in BPG in detail.


2.2.2. Internal working

The key managament library is divided into a set of specialized
submodules:

* Key fetcher: receives petitions for a key and performs the necessary
  operations to give it back to the user (or say why it wasn't
  possible).

* Key generator: receives petitions for creating asymmetric or
  symmetric keys.

* Key importer/exporter: this module receives petitions from the user
  to take a key from a location A and insert it into location B, where
  A and B can be files, keyrings or key servers.

* Key interpreter: translates OpenPGP packets containing keys into the
  internal data structure for keys and viceversa.

* Key deliverer: with no public functions, this module performs the
  internal checkouts and commits of keys from and to a file, keyring
  or key server.

Then, the library uses these submodules to perform the different
responsibilities it has:

* Fetching keys: the user calls the key fetcher, who checks out the
  matching keys, gets each's trust, selects the best-fitting key and
  returns it back to the user in a in-memory data structure that the
  rest of the BPG modules can handle.

* Generation (asymmetric keys): the user calls the key generator, who
  uses the BPG algorithm library to create the key pair, obtains the
  passphrase, and commits it to the given location (by default, the
  user keyring).

* Generation (symmetric keys): the user calls the key generator, who
  obtains the password, expands it and returns it back.

* Importing: the user calls the importer/exporter, who fetches the key
  from wherever it is and commits it to the given location.

* Exporting: the user calls the importer/exporter, who fetches the key
  from wherever it is and commits it to the given location.

All this process is further explained in the "BPG Key Management"
document.


2.2.3. API

bpgkey_fetchkey(KEYID, OUTPUT_KEY, SOURCES, MINIMUM_TRUST)
bpgkey_genkeypair(ALGORITHM, SIZE, DESTINATION)
bpgkey_genkey(SIZE, OUTPUT)
bpgkey_import(KEYID, SOURCES, DESTINATION)
bpgkey_export(KEYID, SOURCES, DESTINATION)


2.3. Algorithms (codename: libbpgalgo)
---------------

2.3.1. Introduction

The BPG algorithms library provides a uniform API for using all kind
of symmetric, asymmetric and hashing algorithms, including
user-defined ones.


2.3.2. Internal working

Initially, we will implement a limited but easier to code version of
the library, for immediate use (read 2.3.4. for the extended version).

This version will contain a single external function, which receives
the input and algorithm to be used, and if the algorithm is supported
calls it internally, returning the output.

The initial algorithms supported will be:

* Hash functions: SHA-1.
* Symmetric algorithms: AES.
* Asymmetric algorithms: RSA, DSA.


2.3.3. API

The API of the initial algorithms library contains functions for
encryption, decryption, hashing and key pair creation.

bpgalgo_encrypt(INPUT, OUTPUT, KEY, ALGORITHM, MODE)
bpgalgo_decrypt(INPUT, OUTPUT, KEY, ALGORITHM, MODE)
bpgalgo_hash(INPUT, OUTPUT, ALGORITHM)
bpgalgo_createkeypair(OUTPUT, KEY_LENGTH, ALGORITHM)

where MODE is the operational mode: ECB, CBC, CFB, OFB.


2.3.4. Extension: Algorithms Plugins System

After making a simple version of the algorithms library, as described
above, a refactorization of this module would be desirable. Providing
the BPG algorithms library with a plugins system would take the
extensibility and reusability to a higher level.

The idea is to make the algorithms be stored outside the library, and
make the library use the one we want dinamically.

The algorithms would be written in C, Perl, Python or whichever other
language we consider useful for our project, following the standard
API we define. This would allow a user to easily test his/her own
algorithm or implementation.

There are security and performance issues yet to be studied, but an
initial approach of its working would be something like this:

* The library receives a call for registering an algorithm with its
  location and interpreter ("register algorithm foo, written in
  Perl, located in /algorithms/foo_v1.pl").

* It receives a function call, with the input and the algorithm 'foo'
  in the parameters.

* It searches for the library, returning an error if not found.

* Selects interpreter, in this case the Perl intepreter.

* Executes algorithm.

* Returns output.

Once the plugins system were coded and tested, all other usual
algorithms in PGP-like applications would be included by default .


2.4. Trust management (codename: libbpgtrust)
---------------------

2.4.1. Introduction
-------------------

This library will handle the information about how much do we trust
the keys we have.

In BPG, the trust level of a key depends on how much we trust the
signer of that key.


2.4.2. Internal working
-----------------------

The trust library handles the trust database and the trust policy. The
trust database contains a list of [UserID, trust level] pairs. The
policy defines the rules for deriving trust level of a given key from
the trust database (i.e. OpenPGP web of trust, X.509 hierarchical
trust model, ...).

Read more on this in the "BPG Key Management" document.


2.4.3. API
----------

bpgtrust_gettrust(SIGNER_USERID)


3. Scripting languages support
------------------------------

Each module will be built as a library to be used from other C
programs.

But we also intend to add thin layers written in C for wrapping the
access from most popular scripting languages to each module in BPG.

This access will ease the testing and provide BPG functionality
everywhere.

First wrapper will be written for Ruby, but we also plan to support
Python and Perl in the near future.

Contributions are very welcome here: just write and send to us a C
program compatible with your favourite scripting language and that
supports all functions in the given BPG library.
