Password Purse Files

                 PasswordPurse
                 -------------

PasswordPurse is a pure java application. It manages cryptographic containers
of security credential by protecting them under a single cleartext passphrase.

This is a very lightweight but flexible application, suited to running on
many platforms such as mobile phones and PDA's. Only one encryption
algorithm is currently supported - Bruce Schneier's Blowfish algorithm. A
subset of its implementation from the Legion of the Bouncy Castle has been
incorporated into the application.

There is a comprehensive set of jUnit tests which exercise each important
class within the application.


Container Architecture
----------------------

A set of credentials can be associated with a particular secure service,
comprising a userid, a password and optional free-form notes. These three
fileds are used to create an an instance of the Secrets class. The set is
separately encrypted under the current (global) passphrase to become an
instance of the EncryptedField class.

Each encrypted collection of credentials is then identified by a
case-insensitve name within an instance of the Pocket class.

A collection of Pockets is maintained by an instance of the Purse class,
which is also encrypted under the global passphrase to become an instance
of the EncryptedPurse class.

When an EncryptedPurse instance is saved to external storage, the change
from the previous version might be quite small. To conceal the scope of
changes, a cryptographically-strong random number (called "salt") is
associated with each generation of a Purse. The salt is stored inside the
EncryptedPurse, but also stored externally in cleartext to be used as a
random introduction to the encryption stream.

All of these container classes (except the external salt) implement a
simple Interface called SelfDefinedField.

The structure of an externalised Purse is...

     { SALT + EncryptedPurse SelfDefinedField }

The structure of an unencrypted Purse is...

     { SALT SelfDefinedField + Version SelfDefinedField
       + PocketCount SelfDefinedField + multiple Pocket SelfDefinedFields }

The structure of a Pocket is...

     { Identifier SelfDefinedField + EncryptedField (Secrets) SelfDefinedField }

The structure of an unencrypted Secrets is...

     { Userid SelfDefinedField + Password SelfDefinedField
       + Notes SelfDefinedField }

The structure of a SelfDefinedField is...

     { inclusive length + SelfDefinedField type + UTF-8 String payload }


Security Considerations
-----------------------

1. The passphrase is not held anywhere within the externalised
   EncryptedPurse byte array.

2. The external salt and SelfDefinedField header are in cleartext and
   so vulnerable to simplistic editing. However, the salt is simply a
   random number and so does not leak any important information.

3. The salt value is also stored within the EncryptedPurse and so it can
   be validated once the Purse has been decrypted.

4. The EncryptedPurse SelfDefinedField header has a self-evident format.
   Most tampering attempts will leave the EncryptedPurse impossible to
   open successfully. Validation is intended to be comprehensive.

5. Once a purse has been opened, the individual Pockets can be searched,
   renamed or deleted without needing to open the associated encrypted
   Secrets.

6. When the Secrets within an individual Pocket have been decrypted, the
   Secrets within all the other Pockets are still held in encrypted form.
   Only one Pocket is opened (decrypted) at a time.

7. The cleartext passphrase is internalised by a CryptoManager instance.
   Classes that need to manipulate EncryptedFields are passed a reference
   to the relevant CryptoManager, thus minimising the number of cleartext
   passphrase String instances left in the garbage collection queue.
   Eventually, a finalizer will be implemented to zero out these Strings.


Manager Architecture
--------------------

Manager classes are used to collect and manipulate the more important
container classes mentioned above.

The CryptoManager class encapsulates a cleartext passphrase and an
encryption engine. It is used to validate a proposed passphrase, encrypt
or decrypt a payload and generate a salt value.

The SecretsManager class opens (decrypts), updates and closes (encrypts) a
coupled pair of Secrets and EncryptedField instances.

The PocketManager class opens, updates and closes a Pocket Identity and its
associated Secrets (via a SecretsManager).

The PurseManager class opens (decrypts), updates and closes (encrypts) a
collection of Pocket instances.


Controller Architecture
-----------------------

In version 1, the Controller architecture is in need of refactoring. It is
a "proof of concept" implementation for a simple command-line program.

The Purse Controller manages the movement of an EncryptedPurse between
memory and external storage. Currently, it uses an operating system
binary file as its external medium. It supports a large set of Purse
operations, such as locate, load, open, save, close. It also supports a
collection of update operations on the individual Pockets.

The PurseCommand class is a finite state machine that interprets end-user
commands and responses, issues appropriate prompts, status and error messages.
It uses the PurseController and various Manager classes to manipulate the
Purse for the end-user.


User Interfaces
--------------

The first user interface program is a simple (hierarchical) command-line
processor. The next development is intended to be a simple gui that runs
under the java ME environment.

-------------------------------------