Password Purse Files

                PasswordPurse
                =============

Second version (maven build) - 27 August 2010



Sorry this is a bit scruffy!

I hoped you would have checked out the project source code from the
SourceForge repository, built it under maven and so you would run my
sample scripts from your own sandbox.

However, if you have just downloaded the bare files, then you need to set up
the correct directory structure "as if" you have an almost-empty sandbox
in the correct maven structure (maven recommendations leave you with long
and clumsy names), i.e.

any-base-directory/
any-base-directory/passwordpurse/
any-base-directory/passwordpurse/passwordpurse-j2se/
any-base-directory/passwordpurse/passwordpurse-j2se/target/
any-base-directory/passwordpurse/passwordpurse-j2se/target/passwordpurse-j2se-2.1-SNAPSHOT-jar-with-dependencies.jar
any-base-directory/passwordpurse/passwordpurse-j2se/src/
any-base-directory/passwordpurse/passwordpurse-j2se/src/main/
any-base-directory/passwordpurse/passwordpurse-j2se/src/main/samples/
any-base-directory/passwordpurse/passwordpurse-j2se/src/main/samples/passwordPurse.sh
any-base-directory/passwordpurse/passwordpurse-j2se/src/main/samples/passwordPurse.bat

That should do it! You should just be able to run the script that matches
your operating system. If you don't like the structure, you are welcome to
hack the scripts yourself.

Initially, you can simply run without arguments and it will use default values
(see command line arguments later for options). A new purse will be created
if you save it - so don't forget the passphrase that you chose because it
can NEVER be retrieved!!

Have fun...

Brian Burch

p.s. The j2me gui is built under the linux wtk toolkit and runs under the
emulator. The program doesn't do much yet and I haven't managed to deploy
it to a real phone.


Command Hierarchy
-----------------

Note: the command parser accepts abbreviations (often just a single character).

*** Top level: You have not yet opened the Purse, but it has been confirmed
    as existing or not. Your choices are:

  * open - you will be prompted for a passphrase. If the Purse exists
           already, it will be opened... if the passphrase is wrong (in
           even the tiniest way), all sorts of errors are possible because
           the decryption process will be certain to generate garbage. If
           the Purse doesn't exist yet, you will be asked to confirm your
           chosen passphrase (and warned if it isn't very suitable).
  * quit - terminate the program normally
  * exit - terminate the program abnormally


*** Purse Open: The Purse has been opened successfully, you will be told how
    many Pockets it currently holds. Your choices are:
 
  * list - gives you a case-insensitive sorted list of the identities of
           all the Pockets, along with an index number (can be used with the
           pocket command below).
  * pocket - prompts you for an index number or a (case-insensitive) search
           string. If your input matches an existing Pocket, then it is
           opened. If you give an identity that doesn't exist, you will
           be asked if you want to create it.
  * newpass - prompts you for a new password and applies it to the entire
           Purse (including each individual Secrets field).
  * close - closes the Purse, saving any pending changes (assigns a new
           salt value if the contents have changed in any way).
  * quit - terminate the program normally (without saving pending changes).
  * exit - terminate the program abnormally (ditto, obviously).


*** Pocket Open: when an existing Pocket has been opened successfully, your
    choices are:

  * secret - opens (decrypts) and lists the Secrets associated with the
           current Pocket (taking you to the Secrets prompt).
  * delete - deletes the current Pocket and its associated Secrets.
  * rename - prompts you for a new identity for the current Pocket.
  * save - saves any pending changes.
  * quit - close current Pocket (taking you to the Purse-is-Open prompt).
  * exit - terminate the program abnormally (without saving pending changes).


*** Pocket Create: when a new (previously non-existent) Pocket has been named.
    Your choices are:

  * new - provisionally creates the new Pocket with the identity you
          just gave it (taking you to the Secrets prompt).
  * quit - close current Pocket without creating it (taking you back to the
          Purse Open prompt).
  * exit - terminate the program abnormally (without saving pending changes).


*** Secrets Create: when a new (previously non-existent) Pocket needs its
    associated Secrtets to be defined. You must:

  * enter the new Secrets as a comma-separated string, with the userid
    first and the password second. You can also add free-form notes by
    prefixing with a second comma. When you hit the enter key, the new Secrets
    are provisionally saved, taking you back to the Secrets prompt.


*** Secrets Open: when an existing Pocket has been opened and the list
    command has been entered. Your choices are:

  * secret - simply lists the existing decrypted Secrets fields.
  * user - prompts you for a replacement userid field.
  * password - prompts you for a replacement password field.
  * notes - prompts you for a replacement notes field.
  * save - saves any pending changes.
  * quit - close current Secrets without saving pending changes (taking
           you back to the Pocket Open prompt).
  * exit - terminate the program abnormally (without saving pending changes).


=============== end =====================