PWKeep

PWKeep: Password Keeper

By Mitch Stuart
Copyright © 2003-2004 FullSpan Software - Usage subject to license
Software Version: 1.0 - Document Version: $Revision: 1.13 $, $Date: 2004/02/17 04:46:02 $

Contents

1 Introduction

PWKeep stores passwords (and related information like user IDs) in an encrypted file protected with a single master passphrase. PWKeep has a friendly user interface that allows you to conveniently organize your passwords:

User interface overview

Getting PWKeep

Download a package including binary JAR files, source code, and documentation: [pwkeep.zip] [pwkeep.tar.gz]
Browse the JavaDoc (generated with the -linksource option which allows you to also browse the source code)

2 PWKeep Features

Some of the features offered by PWKeep are:

Simple and clear user interface
Strong encryption with Triple DES
Launch web browser to the URL associated with a PWKeep data item
Copy user ID or password to the clipboard for quick pasting into a login form
Export data to the system clipboard as delimited text or XML

3 PWKeep Concepts

3.1 Data Organization

PWKeep organizes your data as categories and items. An item is a record that contains the user ID and password for a given resource (such as a website, bank account, etc.). A category is a container that holds related items that you want to keep together.

You can think of a category as being analogous to a folder or directory in your operating system, while an item is analagous to a file. In fact, the PWKeep UI looks similar to a typical filesystem browsing program such as Microsoft Windows Explorer, with a tree view on the left and details on the right. However, one difference is that PWKeep does not allow categories to contain other categories (unlike a filesystem, where directories can contain other directories).

3.2 Encryption

PWKeep data is encrypted using the Triple DES algorithm (also known as DESede or TDEA), with a 168-bit key length. PWKeep uses the Sun Java Cryptography Extension as the provider for DESede encryption and decryption.

3.3 Master Passphrase

Each PWKeep data file is protected with a master passphrase that you select. A passphrase is similar to a password: a short amount of text that acts as a secret key to allow access to your data. We use the term passphrase to make it clear that your secret key does not have to be a single word, but can be a phrase.

For example, the passphrase My dog's name is Spot is a stronger key than the password Spot, because:

it is longer
it is harder to guess
it is not vulnerable to a simple "dictionary attack" (where an intruder tries all the words in a dictionary or other list of words)

My dog's name is Spot is still not a great passphrase, because it is not an uncommon phrase and therefore could be guessed or found in a list of phrases. You should consult the many available resources if you need more information on choosing a good passphrase.

PWKeep does not try to check or enforce the quality of the passphrase you pick, but it does enforce the following rules:

The passphrase must be between 8 and 128 characters long.
The passphrase must not have any leading or trailing space characters.

Caution: Do not forget your master passphrase. There is absolutely no way to to recover your data if you do not have your passphrase.

4 User Interface

The main PWKeep window is split into two panes: the left pane contains a tree with all of the categories and items in the current file. The right pane displays the details of whatever is selected in the tree.

4.1 PWKeep Node

When you select the Root node (the PWKeep node) in the tree, the right pane displays a list of all the Categories in the current file:

User interface with root node selected

4.2 Category Node

When you select a Category in the tree, the right pane displays a list of all the Items in that category:

User interface with category node selected

4.3 Item Node

When you select an Item in the tree, the right pane displays a form with the details for that Item:

User interface with item node selected

By default, passwords are not shown in the item view so you will see a series of asterisks (********) in the Password field. As a security measure, the number of asterisks displayed does not vary with the length of the password - the field always displays 8 asterisks.

4.4 Selections and Actions

To perform a task within PWKeep, choose the desired operation from the menu. Some common operations also have graphical buttons on the toolbar.

Depending on which element(s) you select in the user interface, various menu items and toolbar buttons will become enabled or disabled. For example, if you select one category, then all the operations in the Category menu are enabled. But if you select two or more categories, then (for example) the Edit Category operation is disabled ("grayed out"), because you can only edit one category at a time.

Selections
When you select elements in the UI, PWKeep has the following behavior:

In the tree view in the left-hand pane, exactly one item may be selected at any one time.
In the list view in the right-hand pane, any number of items may be selected: zero, one, or more.

Use the appropriate mouse/keyboard combination for your platform to change the selection. The following are typical:

Single click to select a new element, deselecting any currently-selected elements.
Ctrl-click to select or de-select an element, leaving any currently-selected elements still selected.
Shift-click to select a range of elements.

Double Click
The following table explains what happens when you double-click an entry in the tree or list view:

Tree View

List View

Category

Expand or contract the category in the tree

"Drill down" into the category: select the category in the tree view, and display a list of the category's items in the list view

Item

Select the item in the tree view, display the item in the right-hand pane, and bring up the Edit Item dialog

Select the item in the tree view and display the item in the right-hand pane

Actions
Many actions in PWKeep can be initiated in more than one way. Use whichever method is most comfortable or convenient for you. For example, to copy an item's password to the clipboard you could do any of the following:

Method 1

Right-click the item in the tree view (left pane) and choose Copy Password

Method 2

Select the item in the tree view (left pane)
Choose the Item/Copy Password menu item

Method 3

Select the item in the tree view (left pane)
Click the Copy Password toolbar button:

Method 4

Select the item's category in the tree view (left pane)
Right-click the item in the list view (right pane) and choose Copy Password

Method 5

Select the item's category in the tree view (left pane)
Select the item in the list view (right pane)
Choose the Item/Copy Password menu item

Method 6

Select the item's category in the tree view (left pane)
Select the item in the list view (right pane)
Click the Copy Password toolbar button:

5 Installing PWKeep

Install Java (if you do not already have the required version installed). PWKeep requires Java 1.4 or later. Specifically, PWKeep was tested with Java 1.4.2. You can download Java from the Sun website here . Scroll down to the Download J2SE section. Download Java and install it according to the instructions available on the same page as the download link.
Install the "unlimited strength" encryption package for Java. Sun does not bundle this package with the standard Java distribution, so you need to download and install it separately. Visit the Java download page , scroll down to the Other Downloads section and download the "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 1.4.2". Follow the instructions in the README.txt file.

Note: If you do not install the JCE encryption package properly, you will get the following error message when you try to open or save a file with PWKeep: Unsupported keysize or algorithm parameters. This usually means that you did not put the JCE .jar files in the correct location. One common problem on Windows is that the JCE files need to be placed with the system Java Runtime Environment (JRE), which the Java installer usually places at a standard location. If you run into this issue, I suggest looking in C:\Program Files\Java to see if there is a JRE there that needs to be updated with the JCE files. Or you can search your system for your existing local_policy.jar file, and that should show you where the JCE files need to be placed.
Install PWKeep. Download PWKeep and extract the distribution file to a directory of your choice.

6 Starting PWKeep

Make sure that you have installed PWKeep and the required Java and encryption files as described above.

Note: For the remainder of this document, we will refer to the directory into which you extract the PWKeep distribution as PWKEEP_DIR.

6.1 Windows

Open a command prompt and change to the directory PWKEEP_DIR\build. Run the file pwkeep.bat.

If you have any problems starting or running PWKeep, look for error messages in the file pwkeep.out in the directory from which you launched PWKeep (usually PWKEEP_DIR\build). If you need to do development or debugging of PWKeep, you will probably want to modify pwkeep.bat to make it easier to see the error messages on the screen - see the comments in pwkeep.bat for more information.

After you have verified that you can run PWKeep from a command prompt, you will probably want to set up a Windows shortcut, so that you can double-click on the shortcut to run PWKeep, instead of having to open a command window each time. Create a shortcut with the target set to:

javaw -jar PWKEEP_DIR\build\lib\pwkeep.jar

Notice the use of the javaw command in the above shortcut. The javaw command is the same as the java command, except that it is intended to run GUI applications (as opposed to text mode applications), so it does not open a console (command prompt) window.

6.2 Unix

Open a shell window and run PWKEEP_DIR/build/pwkeep.sh (you do not need to be in any specific directory to run this command).

Note: Because PWKeep has a graphical user interface (GUI), you need to run it from either a local window or a remote XTerm-type window - you cannot run it from a console-type (telnet/ssh) window. If you try to do so, you will get an error message like "Can't connect to X11 window server...".

If you have any problems starting or running PWKeep, look for error messages in the file pwkeep.out in the directory where pwkeep.sh is located (usually PWKEEP_DIR/build). If you need to do development or debugging of PWKeep, you will probably want to modify pwkeep.sh to make it easier to see the error messages on the screen - see the comments in pwkeep.sh for more information.

After you have verified that you can run PWKeep from a command prompt, you may wish set up a desktop icon for launching PWKeep. Follow the procedures for your operating system and desktop environment, and specify the command line: PWKEEP_DIR/build/pwkeep.sh.

7 PWKeep Example Session

The following example session will take you through some PWKeep features.

Start PWKeep as described above. After a few seconds you should see the main window.
Open the sample file that is included with PWKeep. Select the File / Open menu item, and open the file PWKEEP_DIR/build/sample.pwk. When you click the Open button in the dialog box you will be prompted to enter the passphrase. The passphrase for the sample file is: testpass.
Click around a bit to get a feel for the PWKeep user interface. Notice how the display changes as you select different items in the tree.
Select the Category / New Category menu item. In the dialog box, enter News in the Name field and click OK.
Click on the News entry in the tree (if it is not already selected). Select the Item / New Item menu item. Enter Wall Street Journal in the Name field and http://www.wsj.com/login in the URL field. If you happen to have a Wall Street Journal account, enter your user ID in the User ID field. If not, just enter your first name in the User ID field. Click OK to finish editing the new Item.
Click on the Wall Street Journal entry in the tree (if it is not already selected). Notice that the right pane now shows the details of the Item.
Select the Item / Launch URL and Copy User ID menu item, or the equivalent toolbar button: . Your web browser should launch, and navigate to the login page for the Wall Street Journal. Click in the User Name field and use your browser's "paste" key (typically Ctrl-V) to paste in the User ID. You should see the User ID that you entered in PWKeep.

(If your web browser does not launch properly, the default browser settings in PWKeep are probably not correct for your environment. You can use the Options dialog to set the browser command.)

8 Using PWKeep

This section describes each of the PWKeep menu items. As discussed earlier, many of the menu items are also available by right-clicking a UI element and using the pop-up context menu, or by using toolbar buttons.

8.1 File Menu

New
Creates a new, empty PWKeep file. This closes any existing file that you have open.

Open
Opens a PWKeep file. This displays the standard Java file dialog, with file types *.pwk displayed by default. After you select a file to open, you will be prompted to enter the passphrase for that file. This closes any existing file that you have open.

Save
Saves the current file. If the current file has not been saved before, this is equivalent to the Save As action.

Save As
Saves the current file under a new name. This displays the standard Java file dialog, with file types *.pwk displayed by default. Note: the Java file dialog does not automatically append the .pwk extension to the filename that you type in the dialog. For example, if you want to save the file as foo.pwk, you need to actually type foo.pwk, not just foo.

If the current file has not been saved before, you will be prompted for a passphrase for this file. Caution: do not forget your passphrase - there is no way to recover your passphrase or your data if you forget it.

Change Passphrase
Changes the passphrase for the current file. Caution: do not forget your passphrase - there is no way to recover your passphrase or your data if you forget it.

Exit
Exits the program.

Recent Files
By default, PWKeep displays the last few most-recently-opened files on the File menu, so you can easily reopen those files by clicking on the filename. You can disable this feature, or change the number of recent files displayed, in the Options dialog.

Export
PWKeep can export its data in two formats: delimited text or XML. PWKeep purposely does not allow the data to be exported to a file, because the whole point of PWKeep is to keep your data private, so it is not advisable to save unencrypted data to a file. Instead, PWKeep exports the data to the system clipboard, and you can then paste the data into a program of your choice and work with it.

Caution:

Make sure to clear the clipboard after you have pasted your data.
If you print your data make sure to keep the printout in a secure location.
It is recommended that you do not save your unencrypted data into a file. Doing so would put your unencrypted data on the disk where it is vulnerable to unauthorized users. If you find it necessary to save your unencrypted data, you should physically secure the disk drive or other media on which you save it, and/or delete the data as soon as possible. Keep in mind that when you delete a disk file, the data is not really deleted, it is still present on the disk and can often be viewed or recovered. You need to securely wipe the file to truly delete it.

Export Delimited Text
Exports the current file to the system clipboard as tab-delimited text, suitable for pasting or importing into another program such as a spreadsheet like Microsoft Excel.

PWKeep has an example template that you can open in Microsoft Excel (or another spreadsheet program that supports the Excel file format): PWKEEP_DIR/build/pwkeep-print-template.xls. You can use this template as follows:

Open the PWKeep file that you want to work with (for example, sample.pwk).
Choose File / Export / Export Delimited Text. This will place the PWKeep data on the clipboard.
Open pwkeep-print-template.xls in Excel or a similar program.
Go to cell A2 in the spreadsheet and choose Edit / Paste to paste the PWKeep data into the spreadsheet (only a portion of the data is shown here):

Now you can use the features of Excel to print your data or view it in whatever way you want.

The delmited text data is created by taking the internal XML representation of your PWKeep data, and transforming it with an XSLT stylesheet. You can modify the format of the delimited text data by editing the file PWKEEP_DIR/src/java/com/fullspan/pwkeep/resource/exportDelimited.xsl and rebuilding PWKeep.

Export XML Exports the current file to the system clipboard as XML text. You can then paste the text into a text editor or word processor to view or work with it. For example, if you export sample.pwk, it looks like this (only a portion of the data is shown here):


<?xml version="1.0" encoding="UTF-8"?>
<pwkeep>
   <version>1.0.0</version>
   <cryptomarker>cryptomarker</cryptomarker>
   <categories>
      <category>
         <name>Banking and Finance</name>
         <items>
            <item>
               <name>Bank of America</name>
               <userid />
               <password />
               <url>http://www.bankofamerica.com/</url>
               <comments />
            </item>
            . . .

Export / Clear Clipboard
Clears the system clipboard. After you export your data to the clipboard, and you are done pasting it into another application, it is advisable to clear the clipboard so that your private data does not remain available to other applications.

Options
Displays the options dialog. The option dialog looks like this:

Options dialog

Show passwords in item display
By default, passwords are not shown in the item display (when you have selected an item in the tree view). Passwords are shown when you are creating or editing an item. If you want to see passwords in the item display, you can enable this option.

Keep in mind:

In many cases, it is not necessary to display the password in order to use it. Instead, you can use the PWKeep feature that allows you to copy the password to the system clipboard.
Checking Show passwords in the option dialog is a persistent setting (that is, it will be remembered the next time you run PWKeep). If you just want to show passwords during your current PWKeep session, you can use the Item / Show Passwords action to turn the display of passwords on and off.

Automatically open most recent file
By default, PWKeep remembers the most recent file that you opened, and automatically opens it the next time you start PWKeep. Before PWKeep opens the file, it prompts you for the file's passphrase. Uncheck this option if you do not want PWKeep to automatically open the most recent file.

Command to launch web browser
PWKeep has a feature to launch a web browser to navigate to the URL associated with a PWKeep item (this feature is discussed as part of the Item menu below). PWKeep needs to know the command to run to launch your web browser. The command is specified in a somewhat strange format that allows PWKeep to reliably construct the proper command:

The command and parameter(s) for the command line are separated with commas.
The text {0} is used as a placeholder for the URL - PWKeep will replace this text with the actual URL for the selected item when launching the browser.

For Windows, the default browser command is: C:\Program Files\Internet Explorer\IEXPLORE.EXE,{0}. For Unix, the default browser command is: mozilla,{0}. If the default does not work for you, use the options dialog to set the browser launch command to the proper value for your environment.

Option Data Storage
When you exit PWKeep, the current option settings are automatically saved in the file HOME/.pwkeep/pwkeep-options.properties. HOME is your home directory as identified by the Java API call System.getProperty("user.home"). For Unix this is equal to $HOME (for example, /home/jdoe). For Windows this is equal to %USERPROFILE% (for example, C:\Documents and Settings\jdoe).

8.2 Category Menu

New Category
Creates a new category. The category name must be unique.

Edit Category
Edits the currently-selected category.

Delete Category
Deletes the currently-selected category or categories.

New Item
Creates a new item in the currently-selected category. The item name must be unique within the category (you can create items with the same name, as long as they are in different categories).

8.3 Item Menu

Show Passwords Switches the password display on and off for the item display screen. Passwords are not displayed by default. If this menu item is checked, passwords will be shown. Enabling password display affects the current PWKeep session only. To save this setting persistently, use the Options dialog.

New Item
If a category is selected, creates a new item in the currently-selected category. If an item is currently selected, creates a new item in the same category as the currently-selected item.

Edit Item
Edits the currently-selected item.

Delete Item
Deletes the currently-selected item or items.

Copy User ID
Copies the user ID from the currently-selected item to the system clipboard.

Copy Password
Copies the password from the currently-selected item to the system clipboard.

Launch URL
Launches a web browser, navigating to the URL for the currently-selected item.

Launch URL and Copy User ID
Copies the user ID from the currently-selected item to the system clipboard, then launches a web browser, navigating to the URL for the currently-selected item.

Launch URL and Copy Password
Copies the password from the currently-selected item to the system clipboard, then launches a web browser, navigating to the URL for the currently-selected item.

9 Building PWKeep

To build PWKeep using Ant , change to the PWKEEP_DIR directory and run ant. This will use the build.xml build file in that directory. The build file has other targets such as ant doc to build the documentation/JavaDoc. View the build file for further details.

To build PWKeep using Eclipse , import the PWKEEP_DIR directory into Eclipse. This directory includes the necessary Eclipse files (such as .project and .classpath).

10 License and External Libraries

PWKeep is released under the FullSpan license. PWKeep uses the FSJUtil library, which is released under the same license.

In addition, PWKeep uses several external libraries, which are used and distributed under license from their copyright holders:

Component

Description

License

Apache Commons Codec

Base64 encoder/decoder

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

License text: license-apache.txt

Eclipse

Toolbar button images (some of which have been modified)

This product includes software developed by the Eclipse Project (http://www.eclipse.org/).

License text: license-eclipse.html

JDOM

A Java library for XML: "We intend to provide a solution for using XML from Java that is as simple as Java itself."

This product includes software developed by the JDOM Project (http://www.jdom.org/).

License text: license-jdom.txt

JGoodies Forms

JGoodies Looks

"The JGoodies Forms framework helps you lay out and implement elegant Swing panels quickly and consistently."

"The JGoodies look & feels make your Swing applications and applets look better."

This product includes software developed by JGoodies (http://www.jgoodies.com/).

License text: license-jgoodies.txt

11 Programming Information

PWKeep was developed and tested with Java version 1.4.2 . This section discusses some topics that may be of interest for programmers who want to understand or modify the PWKeep source code.

11.1 Data File

The PWKeep data file is stored in XML format using JDOM , and is encrypted with the Triple DES algorithm using JCE. I considered two approaches to encrypting the data file:

Create the XML data, encrypt it as one large block, and store the encrypted block in the data file. In this case, the data file would be a binary file that has to be decrypted before any information about it could be determined.
Create the XML data, separately encrypt the text of each XML element, and store XML data in the data file. In this case, the data file would be a well-formed XML file that can be viewed in a text editor and processed with XML tools. The user data is encrypted and appears as meaningless strings of characters.

I decided to take the second approach, because this makes the file easier to manage.

As an example of the PWKeep file format, the sample.pwk file included with the PWKeep distribution looks like this (only a portion of the data is shown here):

<?xml version="1.0" encoding="UTF-8"?>
<pwkeep>
 <version>1.0.0</version>
 <cryptomarker encrypted="true" salt="w8P2Qa3DS3w=">ff2w9ezH/nR0xs70oHwiSQ==</cryptomarker>
 <categories>
  <category>
   <name encrypted="true" salt="59D2Jy9C3Mk=">VePuwEycvnXs4S9PV1hJSg8PNcGrkvkG</name>
   <items>
    <item>
     <name encrypted="true" salt="evnnYvmoqrs=">VuiaDyi3hUhin1fpK3HlLw==</name>
     <userid />
     <password />
     <url encrypted="true" salt="CuJza3kPoLI=">xVLy94s/AS1kMU6x5amfYFpaM68dkwqNzU+uydIjkV4=</url>
     <comments />
    </item>
    <item>
     <name encrypted="true" salt="h1Untr0psY8=">3/3uHpa9nU7AkjgY65vQXA==</name>
     <userid />
     <password />
     <url encrypted="true" salt="KIadtZI9gYM=">lGpGTWxV2300LyYhyRalRckCUECjvF0gK0oeQ/uTQlI=</url>
     <comments />
    </item>
   </items>
  </category>
  . . .

Using the file format as shown above, we can easily:

Confirm that the file is well-formed XML.
Validate the file against the PWKeep DTD.
Store unencrypted metadata, such as the version number of the file format.
Transmit the file as a text file (for example, in the body of an email) without having to do the special handling sometimes required for binary files.
Validate the user passphrase by using it to encrypt a fixed text string, and comparing that string with a specific XML element. This allows us to validate the passphrase without requiring us to decrypt the entire file.

However, there are some drawbacks to this approach:

Some meta information about the user data can be gleaned from the data file. In particular, the number of categories and items is immediately visible. I don't think a typical user would consider this to be a security weakness, but in some environments it might not be acceptable.
It is generally less secure to encrypt multiple small strings than to encrypt one large string. The multiple small strings make the file more easily subject to a dictionary attack. I've compensated for this by assigning a unique random salt value to each encrypted data element.

11.2 User Interface

PWKeep uses Java Swing for its user interface. To improve the appearance, I used the JGoodies Forms layout manager, and the JGoodies Looks Plastic3D look and feel.

The PWKeep UI code should be fairly straightforward to understand and modify, but there is one area that may require some explanation. One of the common tasks in any user interface is "wiring up" a user action (such as a menu selection or a toolbar button click) to the code that executes the operation that the user selected. Swing supports the use of actions , which allow multiple user interface elements (for example, both a toolbar button and a menu item) to perform the same operation.

Two common techniques for handling user interface actions are:

Have a separate class (often an anonymous inner class) to handle each operation. This tends to result in a lot of small classes with only one method.
Have a single class/method with a list of if conditions. This tends to result in a long chain of ifs that is difficult to read and maintain.

PWKeep uses a different technique: a generic action manager class that uses a naming convention for its attributes and event dispatching.

Action Handler Example
As an illustration of the action handling strategy, the following example shows how to add a new action to PWKeep. We'll show how to add the File / Save action to PWKeep.

If the action will have a toolbar or menu icon, add the icon to src/java/com/fullspan/pwkeep/resource/icons. For example: file-save.gif.
Edit messages.properties and add the menu text and short description. For example:
```
   action.FileSave.menutext=Save
   action.FileSave.shortdesc=Save the current file
```
If there is an icon, also add a property for the icon file. For example:
```
   action.FileSave.icon=file-save.gif
```
Edit PwkActionMgr.java and add an instance of PwkAction to the ACTIONS array. For example:
```
   new PwkAction("FileSave"),
```

Edit PwkMenuMgr.java and add the PwkAction from the above step to one or more menus and/or toolbars. For example:

   menu.add(new JMenuItem(m_actionMgr.getAction("FileSave")));
   . . .
   m_toolBar.add(m_actionMgr.getAction("FileSave"));

Edit PwkGui.java and add a handler method to the inner class PwkActionHandler. For example:
```
   public boolean handleFileSave()
   {
      // code here to save the file
   }
```
The method can do whatever processing is required, or it can delegate to a method in the containing PwkGui class or elsewhere.

Notice the naming convention: the method name must match the form handleXyz where Xyz is the name of the PwkAction you created. If you add a PwkAction without a corresponding handler method, this will be detected at startup time and an exception will be thrown.

For further information on action handling in PWKeep, see the JavaDoc and source code for the following classes: PwkActionMgr, PwkAction, and IPwkActionHandler.