help.txt

title: Table of Contents
alias: TOC

- [Using Password Gorilla]
	-- [Starting]
	-- [Choosing a Master Password]
	-- [Organization Into Groups]
	--- [Moving Groups and/or Logins]
	-- [Logins]
	--- [Saving Edits/Changes]
	-- [Preferences]
	--- [General Preferences]
	--- [Database Default Preferences]
	---- [Export Preferences]
	---- [Database Preferences]
	--- [Display]
	--- [Launch Browser]
	-- [Keyboard Shortcuts]
	-- [The "V3" Database Format]
	-- [Data Import]
	-- [DB Merging]
	--- [Performing a Merge]
	--- [Resolving Merge Conflicts]

- [Risks] 
	-- [The Software Itself]
	-- [System Failure]
	-- [Other Users on a Shared Computer]
	-- [Your System Administrator]
	-- [Viruses, Backdoors, etc.]
	-- [Putting Risk In Perspective]

-------------------
title: Using Password Gorilla
alias: Overview

 - [Starting]
 - [Choosing a Master Password]
 - [Organization Into Groups]
 -- [Moving Groups and/or Logins]
 - [Logins]
 -- [Saving Edits/Changes]
 - [Preferences]
 -- [General Preferences]
 -- [Database Default Preferences]
 --- [Export Preferences]
 --- [Database Preferences]
 -- [Display]
 -- [Launch Browser]
 - [Keyboard Shortcuts]
 - [The "V3" Database Format]
 - [Data Import]
 - [DB Merging]
 -- [Performing a Merge]
 -- [Resolving Merge Conflicts]

- [Risks] 
 - [The Software Itself]
 - [System Failure]
 - [Other Users on a Shared Computer]
 - [Your System Administrator]
 - [Viruses, Backdoors, etc.]
 - [Putting Risk In Perspective]
 
 This documentation is written using Keith Vetter's Hypertext Help System.
For copyright and authorship see the About panel.

-------------------
title: Risks

Just like re-using the same passwords over and over again, or keeping
passwords written down on a sticker glued to the bottom of your desk,
some risks are associated with the use of Password Gorilla. This
section is not meant to scare you, but as an educated user, you have
the right to know about potential risks, and to make informed
decisions. Risks should not be ignored, but evaluated and addressed.

There are different threat vectors that can be considered:

 - [The Software Itself]
 - [System Failure]
 - [Other Users on a Shared Computer]
 - [Your System Administrator]
 - [Viruses, Backdoors, etc.]
 - [Putting Risk In Perspective]

-------------------
title: Starting

Upon start-up, Password Gorilla shows the ''Open Password Database''
dialog. It shows a list of recently used password database files,
allows you to browse for a different password database file, and asks
for the database's master password. Once a file is chosen, and the
master password is entered correctly, the password database is opened,
and its contents are shown.

To create a new, empty password database, click the ''New'' button on the ''Open Password Database'' dialog. You will be asked for an initial master password for the new password database.  Alternately a new database can be created by choosing the ''File'' menu and selecting ''New ...''.

-------------------
title: Choosing a Master Password

It goes without saying that the master password should be non-trivial.
I.e., the master password should not be a word in any language nor a
name. Such trivial passwords are subject to dictionary attacks, in
which an attacker could gain access to your master password by simply
using ''brute force,'' by trying all the words in the dictionary.

Equally important is that the master password should not be kept in
the same place as the password database. Ideally, the master password
should not be written down at all, so that it remains in your personal
memory only. If you decide to write down your master password, keep it
away from your computer(s), in a location that only you know of.

Because the password database is encrypted using your master password
(using the peer-reviewed and commercially well-accepted Twofish
algorithm, for the technically inclined), it is imperative that you do
not forget your master password. It is impossible to recover a lost
master password. An encrypted password database can not be "cracked,"
as long as the master password is not trivial (see above).

Note that Password Gorilla does not try to second-guess your choice of
password. It does not check for or complain about passwords that would
generally be considered weak.

-------------------
title: Organization Into Groups

Logins in the password database are shown as a tree, organized into
nested groups. Groups allow you to arrange logins by category. Click
on the symbol next to a group's name (or double click the group
name) in order to view subgroups and logins that the group contains.

New groups and subgroups can be added by right-clicking on a group
name, and choosing the ''Add Subgroup'' option. (Macintosh users, hold
the Control key, and click on a group name.) In the dialog box that
opens, the ''Parent Group'' name will be set automatically, and the name
of the new subgroup can be entered.

Note that empty groups are not stored in the password database file.
If you save and re-open a file, empty groups will disappear.

-------------------
title: Moving Groups and/or Logins

Moving groups and/or logins to new locations in the tree can be accomplished
in any one of several ways.

1) The Login menu contains commands "Move Login ..." and "Move Group ..."
which are active when a login or group is respectively selected in the tree. 
Selecting either of these commands will open a window that shows the current
group location of the selected item on top, and contains an entry on the
bottom into which a new group location may be typed.  Separate group names
with a dot or period character (.) and do not use a dot character within a
group name itself.  Pressing "Ok" after entering a new group name will move
the selected login or group to the entered location.  Additionally, the
destination entry is also a drop down select list with which an existing
group can be selected as a destination.

2) In the right-click menu that appears from right-clicking a login or group
there is a sub-menu item "Move login to:" or "Move group to:".  Selecting
this item will cause a second menu to appear listing all current groups in
the database.  Selecting one of the current group names will cause the
right-clicked login to be moved to the selected group. 

3) A set of groups or logins can be selected by clicking with the left mouse
button.  Use shift plus click or control plus click to select multiple
items.  If the button is held down and the mouse is moved a short distance,
a drag and drop operation will begin.  When this happens the cursor will
change to a double vertical arrow and a floating window will appear showing
the title of the item(s) being dragged.  As the item(s) are being dragged
the active drop location will be highlighted in the tree and will correspond
to the tree item that is underneath the cursor.  Drop the item by releasing
the mouse button with the cursor located above a line in the tree.

Dropping a login or a group onto a login name will perform a move to the
group location where the drop occurred.  Dropping a login or a group onto a
group name will perform a move into the group where the drop occurred.

4) Within the edit login dialog the entry for group name for the login is
also a drop down select list containing all current group names.  To move a
login to a new group while editing, either type a new group into the group
entry, or drop down the select list with the mouse and choose an existing
group name.  When edits to the login entry are complete any changes to the
group of the login will be stored into the database.


-------------------
title: Logins

Groups can contain any number of logins. To add a new login, right-click on
a group, and choose the ''Add Login'' option, or select ''Login'' -> ''Add
Login'' from the pull down menu.  Adding a login via the pulldown menu when
an existing login is selected will result in the new login defaulting to
initially being added to the same group as the selected login.  To edit an
existing login, right-click on a login, and select the ''Edit Login''
option. (Macintosh users, hold down the Control key, and click on a group
name.)

The following information is managed for each login:

'''Group'''

 | The name of the group to which this login belongs. The names of
hierarchical groups are concatenated, separated by a dot. A login can be
moved to a different group by editing this field.

'''Title'''

 | The login's title is shown in the main window, so that you can identify
the service that this login information belongs to, e.g., ''E-Mail.''

'''URL (V3 format only.)'''

 | The service's URL, if any. In the tree view, you can right-click on a
login and choose ''Copy URL to Clipboard'' in order to copy this data to the
clipboard, for pasting it into your browser's address bar. This field is
only available when using the ''V3'' database format; see the discussion of
the [V3] format below for more information.

'''Username'''

 | Your username for this service. In the tree view, you can right-click on
a login and choose ''Copy Username To Clipboard'' in order to copy this data
to the clipboard, for pasting it into the service's login prompt.

'''Password'''

 | The password that is associated with this login. In the tree view, you
can right-click on a login and choose ''Copy Password To Clipboard'' in order
to paste it into the service's password prompt.

'''Notes'''

 | You can use the notes field for arbitrary information that you wish to
associate with the login. E.g., you could note questions and answers to a
service's security questions (of the "What is your mother's maiden name?"
kind). Also, you can use the field for the service's URL. If the notes
include a string that starts with ''http'' or ''https'', or if they contain the
token ''url:'' followed by a URL (put the URL in quotes, if it contains
spaces), then you can right-click on an login and choose ''Copy URL To
Clipboard'' in order to paste the URL into your Web browser.

When editing a login, the password is not shown, for added protection
from curious onlookers. You can click the ''Show Password'' button to
toggle visibility of the password.

Clicking on ''Generate Password'' generates a new pseudo-random password
according to the current password policy (which is a per-database
setting that can be set using the ''Password Policy'' option in the
''Security'' menu). If the ''Override Password Policy'' box is checked, you
can edit the password policy to use for this one password.

The password policy allows you to set the length of randomly generated
passwords, and the characters to use. Check the ''use easy to read
characters only'' option to avoid characters that look similar. This
excludes the lower- and uppercase letters 'i', 'j', 'l' and 'o', the
digits '0' and '1', and the exclamation mark, pipe symbol, and
parentheses. Note: to generate random hexadecimal passwords, the ''use
hexadecimal digits'' option should be checked exclusively, and the
password length should be an even number.

The default password policy for the current database can be set using
the ''Password Policy'' dialog from the ''Security'' menu.

-------------------
title: Saving Edits/Changes

The password editing window shown for both ''Add Login'' and ''Edit Login''
operates upon a temporary copy of the data for a password record.  No
changes are made to the master database as an immediate result of changes
made to the fields in the editing window.  Only after the ''Ok'' button is
pressed will the contents of the fields of the edit window be stored into
the master database (overwriting existing data if the operation is an edit). 
If an existing password entry is opened for editing, and it is desired to
discard the changes made, pressing the ''Cancel'' button will discard the
changes and leave the master database unchanged.

Note that a side-effect of this operation of the editing window is that the
''Auto-save'' feature will not activate until the ''Ok'' button is
depressed.  This provides some small security against accidential changes to
a password record being saved into the master database unintentionally.

-------------------
title: Preferences

General, database default and export preferences can be configured
using the ''Preferences'' dialog from the ''File'' menu. Database
preferences, which are specific to the current password database, can
be configured using ''Customize ...'' from the ''Security'' menu,
when a database is open.

-------------------
title: General Preferences
alias: General

'''Clear clipboard after <nn> seconds'''

 | If this value is set to a non-zero value, the system clipboard is
cleared, the specified number of seconds after copying a user name, password
or URL to the clipboard. This ensures that no password remains in the
clipboard forever.

'''Remember <nn> database names'''
  
 | Makes Password Gorilla only remember the given number of most recently
used database file names. If set to zero, Password Gorilla will not remember
database file names at all. The current list of file names in the most
recently used list can be cleared with the button next to this option.

'''When double clicking a login'''
  
 | Configures what to do when you double-click on a login. The options are
to copy the login's password to the clipboard, to open the login for
editing, or to do neither.

'''Backup database on save'''

 | If enabled, then a backup file of the password database is made whenever
the database is saved. The backup file is located in the same directory and
has the same name as the database itself, but with the ''.bak'' extension.

'''Remember sizes of dialog boxes'''

 | Password Gorilla allows you to resize its main window, and most of its
dialogs, should you find the default sizes inconvenient. If this option is
enabled, Password Gorilla will remember the size of dialog boxes across
restarts.

'''Use Gorilla auto-copy'''

 | If this option is selected then Password Gorilla will automatically copy
the password of a login to the clipboard after a paste of the associated
username has occurred.  This allows a website's login/password fields to be
filled in one immediately after the other without returning to Password
Gorilla in between.

 | If this option is utilized in combination with the '''Also copy username
to clipboard''' option of the [Browser] tab then it allows logging into a
website with only one touch of Password Gorilla (for websites that follow
the username plus password standard).

 | At the present time, this option is operational only for Linux or Unix
X11 based machines.  The Windows and MacOS clipboard is implemented in a
different manner such that Windows and MacOS do not inform Gorilla of the
occurrence of a paste operation.  Without OS support to determine that a
paste operation has occurred, Gorilla has no way to know when to
subsequently copy a login's password to the clipboard.

 | Additionally, this option interacts badly with clipboard management
applications, e.g. xclipboard.  Clipboard management programs function by
performing an automatic paste as soon as data is placed into the clipboard,
which fools Password Gorilla into believing that a paste into a web-site
login field has occurred.  The result of this bad interaction is that the
Password Gorilla status line will flash "Username copied..." followed
immediately by "Password copied...".  If this occurs, there are only two
solutions:

 | 1) Disable this option in Password Gorilla
 | 2) Disable the clipboard manager program which is interfering

-------------------
title: Database Default Preferences

Database default preferences are applied to new databases, but do not
affect existing databases. To change a setting for an existing
database, go to ''Customize'' in the ''Security'' menu. See the
discussion of [Database Preferences] below.

-------------------
title: Export Preferences

Export preferences apply to the exporting of a password database to a
plain-text file.

'''Include password field'''

 | If enabled, the password is included in the exported file. If disabled,
"********" is substituted for the password.

'''Include ''Notes'' field'''

 | If enabled, the ''Notes'' are included in the exported file.

'''Field separator'''

 | Configures the character to separate fields. This character should not
appear in any user name or password. Common separators are ":" (colon) and
"," (comma).

'''Show security warning'''

 | If enabled, reminds the user, before exporting the database, that the
exported plain-text file is not encrypted or password protected.

-------------------
title: Database Preferences

These database preferences can be configured using ''Customize'' from the
''Security'' menu.

'''Lock when idle after <nn> minutes'''

 | If this preference is set to a non-zero value, Password Gorilla will lock
the database after a period of inactivity. In that case, a dialog box opens,
prompting for the database's master password. The dialog also allows to exit
Password Gorilla. Note that this allows a malicious user to exit the
application, discarding changes. However, this is not a security issue: a
malicious user, having access to your desktop, could just as well kill the
application (e.g., from the console or the the Task Manager). A better
choice is to lock your desktop while unattended.

'''Auto-save database immediately when changed'''

 | If enabled, then the database will automatically be saved after each
change.

'''Use Password Safe 3 format'''

 | If this option is enabled (i.e., checked), the password database, when
saved, will use the new ''Password Safe 3'' encryption format. The database
will be compatible with Password Safe 3, but will not be compatible with
versions of Password Safe prior to 3.0, or versions of Password Gorilla
prior to 1.4. If this option is disabled (i.e., not checked), the old
Password Safe 2 database format is used: the database will be compatible
with Password Safe 2.0 or higher, and Password Gorilla 1.0 or higher.

 | It is highly recommended to enable this option, and to upgrade existing
databases to the Password Safe 3 format, which features enhanced security.
See [The "V3" Database Format] for more information.

'''V2 Unicode support'''

 | Whether the database file uses Unicode. This is the default for the
Password Safe 3 format; this option only applies if the ''Use Password Safe 3
format'' option is disabled (i.e., not checked). If this option is enabled,
database files containing international characters can safely be exchanged
across locales, e.g., when you want to use the same password database in
both a Western European and Russian locale. The caveat is that, if you use
both Password Gorilla and Password Safe, the latter will not read accented
characters correctly. (The database will open, but non-ASCII characters will
not show up correctly.) This option has no effect if your database uses only
ASCII characters.

'''Timestamp Backup'''

 | If the option ''Auto-Save'' is enabled then the copy can be saved with
a timestamp in the chosen backup directory. The timestamp format is: YYYY-mm-dd-hh-mm-ss

'''Backup Path'''

 | If no backup path is entered then the backup copy has the suffix ".bak" and is
put into the same directory as the Password database itself.

'''V3 key stretching iterations'''

 | The Password Safe 3 format supports ''variable key stretching'', which is a
means of protecting a database against brute-force attacks (an attempt to find
the password by trying all possible password character combinations). Key
stretching is a complex operation that must be performed when validating a
master password for correctness.  When an authorized user enters the correct
password, this may take a second and is barely noticeable.  But it slows down
mass-testing password guesses by an automated program.  The ''iterations''
parameter indicates the complexity of the key stretching: the higher this
value, the longer it takes to open a database, and the longer it takes an
attacker to test one password.

 | The correct choice for this value depends upon several factors, one of
which is the expected computational performance that an attacker may utilize
against any given password database file.  It should be chosen such that an
attacker can only test a few password possibilities per second instead of
testing millions or billions of possibilities per second.  A rule of thumb
is to pick a value such that it takes Gorilla about 1-2 seconds during the
"Please be patient. Verifying password ..." phase of opening a database. 
The value can range from a low of 2,048 to a high of 2,147,483,647.  Use
care in searching for a reasonable value, setting too large a value
initially will create a password safe file which can take a very long time
to open later.

 | Note that this option can only be changed on a per-database basis and
does not appear in the Database Default Preferences Menu. This prevents a
malicious user from changing the preference in the registry and degrading
the protection of future databases.

'''Calculate delay time'''

 | Pressing the ''Calculate'' button in this section will cause Gorilla to
display how long it took to perform PasswordSafe V3 format keystretching
using the number of iterations in the ''V3 key stretching iterations'' box. 
If this option has not been previously utilized, underscores ("___") will be
present where the time value is to appear.

'''Automatic iteration calculation'''

 | This section allows for automatic calculation of an iteration value
that produces approximately the number of seconds delay present in the
''Delay for X seconds'' area.  The range for seconds is from 1 to 600 (ten
minutes).  Simply enter or use the up/down arrows to select a desired number
of seconds of delay, and press the adjacent ''Calculate'' button.  Gorilla
will compute a value and automatically fill in the ''V3 key stretching
iterations'' box with the new value.

 | Note that the computation of the value occurs by measuring the time delay
for a small iteration count and then scaling that count by the requested
length of time.  As a result the actual computed value will depend upon
several factors out of Gorilla's control, including the CPU load level when
the calculate button is depressed.  The computed value should be close to
the proper value but may need to be manually adjusted slightly to achieve
exactly the selected seconds of delay.  Utilize the ''Calculate delay time''
section to determine the amount of time consumed by the calculated iteration
value.

-------------------
title: Display

'''Language'''

The menubutton Language offers you all the languages whose dictionary
files *.msg are found in the subdirectory msgs. Your choice will be
saved on exiting in the rc-file and the next time you start Gorilla it
is showing the preferred language.

'''Size'''

 | Choose the font size which shows the best results on your monitor.

'''Show Gorilla Icon'''

 | If you like the gorilla icon then check the button. The next time it will
greet you.

'''Iconify upon auto-lock'''

 | If this option is selected then Password Gorilla will also
iconify/minimize its windows when the lock after idle timer (see [Database
Preferences]) expires.

'''Hide login name in tree view'''

 | Selecting this option will prevent Password Gorilla from showing login
names alongside titles for each login in the main tree view window.  Note
that this is a global setting, either no login names are shown, or all login
names are shown.  This setting only takes full effect after exiting and
restarting Password Gorilla, or saving and reopening the current or another
database.

-------------------
title: Launch Browser
alias: Browser

Password Gorilla can launch a browser directly to the URL stored within a
login entry provided that the user preferences have been configured to
indicate what browser to launch and how to launch the browser.

Once configured as described below, to launch a browser directly to a URL,
right click upon a login entry in the tree and select '''Open URL'''. 
Alternately, under the '''General''' tab in '''File''' -> '''Preferences'''
if the selection '''Launch Browser directed to URL''' within '''When double
clicking a login ...''' is selected then a double click upon a login will
launch a browser to the URL stored in the login.

'''Configuration of Launch Browser functionality'''

 | Under '''File''' -> '''Preferences''' is a tab labeled ''Browser''.  On this
tab are two entry fields labeled ''Browser executable to launch'' and
''Command line parameter (if any) to pass''.  At a minimum, at least the
first field must be filled in to enable the ability to launch a browser
directly to a URL stored in a login entry.

'''Browser executable to launch'''

 | This field should be filled in with the name of the executable file to
launch the browser.  I.e., for Firefox on Linux this would usually be
'''firefox''' and for Firefox on Windows this would usually be
'''firefox.exe'''.  If the executable is present upon the OS executable search
path, only the name of the executable is required.  If the executable is not
present upon the search path, then the full path name to the executable
should be entered into this field.

 | To simplify the insertion of a full path name to the executable file, the
'''Find Browser''' button will launch a file browser with which you may
navigate to and select the proper executable.  Upon selecting the proper
executable, the full path to that executable will be automatically added to
the entry.

'''Command line parameter (if any) to pass'''

 | This field is optional.  If left blank Password Gorilla will simply pass the
URL value from the login entry directly to the program executable from the
first entry.

 | However, if special command line switches and/or parameters are necessary to
launch the browser to a particular URL, then those switches and/or
parameters must be entered into this field.  If this is the case, then the
special character sequence '''%url%''' must be utilized at the point that
the actual URL should be placed within the switches and/or parameters.  E.g.
entering '''parameter(%url%)''' would result in the browser receiving
'''parameter(http://www.example.com)'''.  What parameters may be required
for various browsers is beyond the scope of Password Gorilla.  Please
consult your browser documentation to determine if any special command line
parameters are required to launch directly to a URL.

 | If any parameter contains spaces, you must surround that parameter with
double quotes (") to ensure that the spaces are properly passed through to
the browser during the launch process.  I.e., C:\Documents and Settings\ 
would be entered as: "C:\Documents and Settings\".

'''Also copy username to clipboard'''

 | If this checkbox is selected, then as part of the launch browser sequence
Password Gorilla will also copy the username from the selected password
entry to the clipboard.  This will allow for an immediate paste of the
username into the related website login form once the browser is open and
has retrieved the website content.  Use the below '''Clipboard autoclear
multiplier''' setting to control clearing of the clipboard when this option
is utilized.

 | If this option is utilized in combination with the '''Use Gorilla
auto-copy''' option of the [General] tab then the '''Clipboard autoclear
multiplier''' will only apply to the username.  The associated password will
continue to be cleared from the clipboard after expiration of the '''Clear
clipboard after <nn> seconds''' timer option from the [General] tab.

'''Clipboard autoclear multiplier'''

 | This setting controls how Password Gorilla handles clearing of the
clipboard contents if the '''Also copy username to clipboard''' option is
selected.  The value set in the '''Clear clipboard after''' box on the
'''General''' tab of the preferences is multiplied by the value set in this
box.  As a result there are three possible choices of values:

 | 0 (zero) Do not clear clipboard when opening a url, overriding the time set
on the '''General''' tab;

 | 1 (one) Clear clipboard after the length of time set on the '''General'''
tab;

 | 2 ... 20 (two to twenty) Clear clipboard after twice (up to twenty times)
the length of time set on the '''General''' tab.

'''Notes for Windows Users'''

 | On Windows, Internet Explorer is generally named 'iexplore.exe' and is often
located in the C:\Program Files\Internet Explorer\ directory (at least on
Win XP SP3).  In order to launch IE, you will need to enter this full path
(i.e. C:\Program Files\Internet Explorer\iexplore.exe) in the '''Browser
executable to launch''' field.  It may be easier to utilize the '''Find
Browser''' button and then navigate to and select the iexplore.exe
executable.

'''Notes for Mac Users'''

 | The value ''open'' is preset per default for the '''Browser executable to launch''' entry.
If the url entry of the login record contains a value like ''http://www.google.com''
then the default browser will launch with this site. To choose a default Web browser other
than Safari you

 | 1. Open Safari (/Applications).
 | 2. Choose Preferences from the Safari menu.
 | 3. Click the General button.
 | 4. Choose a different browser from the Default Web Browser pop-up menu.

 | If you want to launch a Web browser independently from the Safari installation
mechanism you have to add the path of the browser's executable, e.g.

 | ''/Applications/Firefox.app/Contents/MacOS/firefox''

'''Notes for Unix/Linux Users'''

 | Usually, under most Unix/Linux distributions, the various browser executable
files are located in standard executable search path directories.  In most
instances you will simply have to enter the browser name only, i.e.
'''firefox''' for the Firefox browser, in order to launch a browser from
inside Password Gorilla.  If this does not work, then please enter a full
path to your browser of choice, or utilize the '''Find Browser''' button to
navigate to and select your chosen browser.

'''Notes for all users'''

 | If the URL fields of your database records store full URL's, including the
''http://'' prefix, there is nothing special that you should need to do
unless you utilize a browser that requires extra command line parameters.

 | However, if the URL fields of your database records store website names,
i.e. ''www.example.com'' instead of ''http://www.example.com'' then you may
need to enter '''http://%url%''' in the '''Command line parameter''' entry
in order to properly launch your browser to the correct location. 

-------------------
title: Keyboard Shortcuts

'''Menu shortcuts'''

The Meta key for Linux and Windows shortcuts is the ''Control'' key, whereas the Mac uses the ''Command'' key:

 | Meta-o		Open Database
 | Meta-s		Save Database
 | Meta-x		Quit Password Gorilla
 | Meta-u		Copy Username to Clipboard
 | Meta-p		Copy Password to Clipboard
 | Meta-u		Copy Url to Clipboard
 | Meta-c		Clear Clipboard
 | Meta-f		Find
 | Meta-g		Find next
 | Meta-a		Add Login
 | Meta-e		Edit Login

'''Editing shortcuts'''

For single line entries and the notes box (note, in the lists below, C-
stands for Control, S- stands for Shift, and M- stands for Meta):

 | C-/ 		Select all text
 | C-Left 		Move cursor left by one word
 | C-Right		Move cursor right by one word
 | C-S-Left		Move cursor left by one word and select the word
 | C-S-Right		Move cursor right by one word and select the word
 | C-b		Move cursor left
 | C-f 		Move cursor right
 | C-a		Move cursor to start of text
 | C-e	 	Move cursor to end of text
 | C-h		Same action as Backspace
 | C-d		Delete character to right of cursor
 | C-k		Delete all characters to right of cursor

'''For the notes box only:'''

 | M-Backspace		Delete word to left of cursor
 | M-Delete 		Delete word to left of cursor
 | M-d 		Delete word to right of cursor
 | M-w		Copy selection to clipboard
 | C-w 		Cuts selection to clipboard
 | C-y		Inserts clipboard at cursor position

'''For the master password entry box:'''

 | C-Backspace		Delete all text

-------------------
title: The "V3" Database Format
alias: V3

'''"V3" Format Introduction'''

Password Gorilla 1.4 added support for a new encrypted format for
password databases, as introduced by version 3 of Password Safe --
therefore also called the ''V3'' format. This new format is based on the
years of experience with and analysis of the prior ''V2'' database
format, and features enhanced security (see below, V2 Format
Weakness for details). The new format offers:

 * Support for non-ASCII character sets by default.
 * A stand-alone field for a URL.
 * A checksum to detect tampering or truncation.
 * Use of the improved Twofish encryption algorithm.
 * Stronger protection against brute-force attacks on the master password.

It is recommended to use the new format, and to upgrade existing
password databases, unless you require compatibility with software
that supports the old format only, such as Password Safe 2.x, or
versions of Password Gorilla prior to 1.4.

'''Switching between the V2 and V3 Formats'''

Password Gorilla defaults to the V3 format for newly created
databases, but it does not automatically upgrade existing V2
databases. Upgrading, as well as downgrading, a database is
accomplished by enabling the Use Password Safe 3 format checkbox in
the Database Preferences menu (see above).

Password Safe recommends to use the ''.psafe3'' extension for V3-format
database files, and the ''.dat'' extension for V2-format files.
(Password Gorilla allows password database files in either format to
have any extension.)

'''V2 Format Weakness'''

In the interest of full disclosure, it should be noted that a
potential weakness was discovered with the old Password Safe 2 (''V2'')
file format. This issue affected the ''key stretching'' process that is
intended to slow down a brute force attack against a database's master
password (i.e., repeated attempts at guessing the password). The
weakness in the file format's design allowed brute force attacks 1000
times faster than intended. The number sounds worse than it is: a
good, long master password is one among billions of billions of
combinations, and a factor of 1000 does not make a practical
difference. However, the factor may have an impact on the security of
password databases that use a short, more easily guessable master
password. The Password Safe 3 format avoids this issue by depending on
the result of the key stretching operation (which is computationally
expensive) as an input to decryption -- therefore, the operation can
not be bypassed.

-------------------
title: The Software Itself

First of all, the software itself may be a risk. For all you know, the
software's author could be a sociopath who tries to talk you into
downloading and installing buggy software that secretly broadcasts
your passwords. If you want, you can trust the author, third-party
recommendations, you can inspect the source code for trap doors, or
trust a third-party code inspection.

Maybe the software is not bug-free. In an extreme scenario, a bug in
Password Gorilla could destroy your password database. It is good
advice to keep a backup copy of your password database in a safe
place.

-------------------
title: System Failure

Sometimes, computers have the annoying habit to crash at the most
unfortunate time. Many users have lost data due to an unpredicted
crash. This can be problematic, e.g., when you just added or modified
a login, and did not get around to saving the updated password
database. If a password was randomly generated, it may be lost.

The easy workaround is to not confirm your password with the online
service before saving the password database. I.e., when creating a new
login, first add it in Password Gorilla, and immediately save the
database (using ''Save'' from the ''File'' menu). Only then go to your
online service -- e.g., the Web site that required registration, and
complete its signup process. When modifying a login, e.g., changing
the password, there is a chance that the computer might crash after
saving the database, but before completing the service's password
change process. In this case, the old password will still be available
in the password database's backup file -- assuming that you have a
backup copy, of course.


-------------------
title: Other Users on a Shared Computer

Common sense will go a long way in protecting your password database
from other users that you share a computer with. Never keep Password
Gorilla running when you leave the desktop unlocked. Make sure that
the database file is not readable by other users -- while the database
format is considered secure, this prevents other users from copying
the file, and making a brute-force attempt of guessing the master
password offline.

For Linux/Unix users, Password Gorilla creates and saves database files
using your login's current file-creation mask ("umask") setting.  If you
wish to have a specific particular set of access permissions applied to your
password database files then adjust your "umask" setting before executing
Password Gorilla.  See "man umask" and your shell's man page for details
about the umask setting.

If you follow these precautions, there is nothing to worry about here.

-------------------
title: Your System Administrator

If your computer is administered by somebody else than you, then you
need to trust the administrator(s). An administrator can bypass the
operating system's security measures, and inspect a running program's
in-memory data. Password Gorilla obviously needs to have the decrypted
contents of your password database in memory, so a malicious
administrator could access Password Gorilla's memory, and gain access
to your passwords. In an attempt to foil naive attackers, Password
Gorilla takes some care by not storing data in clear text, but
encrypted using a temporary key. However, because the key is also kept
in memory by necessity, a motivated attacker could find both the
encrypted password and its key.

Of course, malicious administrators have a wide range of tools at
their disposal that invade on your privacy, in order to gain access to
your passwords. An administrator could replace the Password Gorilla
software with a trojan version that looks and acts the same, but sends
your passwords to the administrator's account. Even if you are not
using Password Gorilla, the administrator could install a key logger,
or monitor your internet connection, to find passwords as you type
them.

The added risk of using Password Gorilla is that a malicious
administrator could compromise all passwords at once, instead of only
intercepting the few passwords that you actually use and transmit in
one session.

-------------------
title: Viruses, Backdoors, etc.

If your computer is infected by spyware or viruses, then external
malicious users may have control over your computer. Such users could
use the same attacks as described for a system administrator above. It
is a good idea to check for viruses and spyware on a regular basis.
Password Gorilla should obviously not be used on a compromised
computer.

-------------------
title: Putting Risk In Perspective

The above does not necessarily imply that Password Gorilla is too
insecure to use. They are merely a set of risks that need to be
considered and evaluated in order to make an informed decision, and to
take some common sense precautions. The author believes that using
Password Gorilla is a better idea than the alternative of writing down
passwords, or of reusing passwords.

As the example of the malicious system administrator shows, there is a
wide range of attacks that are possible even if you were not using
Password Gorilla.

Saying that Password Gorilla should not be used on a computer that is
infected with spyware, viruses, or backdoors, is good advice, but
redundant, as the problem is not limited to Password Gorilla. A
compromised computer should not be used for anything, especially not
for private communication.

Also, while technical attacks receive a lot of publicity, it should
not be forgotten that social engineering attacks are usually more
effective. In a study that I read about, a sizeable fraction of users
revealed their passwords to strangers on the street, for a mere piece
of chocolate. In one of the Hollywood movies that treat this subject
better than others, War Games, the protagonist gains access not by
pressing a magic button, or by bypassing security, but by spending
countless hours trying to get into the designer's mind, in a social
engineering attack to guess the designer's most likely choice of
password -- another reason to prefer random passwords.

-------------------
title: Data Import

Password Gorilla has the ability to import data from CSV (Comma Separated
Value) files.  Exporting of data from other applications into CSV format is
beyond the scope of this document or Password Gorilla.

The format of CSV files that Password Gorilla accepts is somewhat flexible. 
The format of the CSV data itself must adhere to the requirements of the
TclLib csv module, which documents the format as:

 | 1    Each  record  of a csv file (comma-separated values, as exported
e.g. by Excel) is a set of ASCII values separated by ",".  For other
languages it may be ";" however, although this is not important for this
case as the functions provided here allow any separator character.

 | 2    If  and  only if a value contains itself the separator ",", then it
(the value) has to be put between "". If the value does not contain the
separator character then quoting is optional.

 | 3    If  a  value  contains the character ", that character is
represented by "".

 | 4    The output string "" represents the value ". In other words, it is
assumed that it was created through rule 3, and only this rule, i.e. that
the value was not quoted.

The CSV file itself is interpreted as a utf-8 encoded file, this allows for
transparent handling of plain ASCII files as well as importation of Unicode
extended characters simultaneously.

There are twelve possible data values (columns) that may be present within
the CSV file.  The file must contain at least one column.  Other than
requiring at least one column, the file may contain any number of columns
from one to twelve.

The first CSV record in the file (which must be the first line of the file)
defines how many data columns are expected to be present in the remainder of
the file, and what internal data fields correspond to those columns.

The twelve possible data columns are named: create-time group last-access
last-modified last-pass-change lifetime notes password title url user uuid

These names, and only these names, must be used as the first record of the
CSV file to define which data values are present.  I.e., for a CSV file that
contained user names, passwords, and urls only, in that order, the first
line of the CSV file would read:

user, password, url

Subsequent lines would contain username, password, and url formatted as per
the rules above from the TclLib csv module.

There are some restrictions on the formatting of some of the data fields,
these restrictions are:

create-time, last-access, last-modified, last-pass-change, lifetime

 | These fields contain date and time values.  The format of a date and time
value for import purposes is:

 | YYYY-MM-DD HH-MM-SS TZ

 | All values except TZ are numerical and contain a number of digits equal
to the number of letters above.  YYYY stands for year, MM is month, DD is
day, HH is hour (24 hour clock), MM is minute, SS is seconds.  TZ is the
timezone within which the date and time should be interpreted.  TZ accepts
many standard timezone names, however the simpliest option if you know your
offset from UTC is to simply add +HHMM or -HHMM where HH is hours and MM is
minutes (e.g., -0500 for five hours before UTC).

uuid

 | This field must be formatted like so:
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where each "x" is a hexadecimal
character (0-9a-f).

group

 | This field must be formatted in the manner of group names in the Password
Safe database format.  That is, group names separated by dots (periods). 
Escape embedded periods with a slash (\) (e.g., \. ).  Escape embedded
slashes with a slash (e.g., \\).

notes

 | This field has only one special requirement.  Newline characters (Unix
newline characters, ASCII line feed) ''must'' be encoded as \n.  Other ASCII
control characters can also be encoded in the same way, i.e., \t for tab,
etc., but are not required to be so encoded.

Example

uuid,group,title,user,password,notes
fdc2aff8-04e1-4766-4ef4-ddae08377ba6,Group 1.Sub Group 1,A Title,A User Name,A Password,A note about this entry 
63a1b066-148a-4bf6-40bc-a2b9afda00c6,Group 1.Sub Group 2,A Title,A User Name,A Password,A note about this entry 
f29b9ef7-9e62-41e1-7dfd-14ae13986059,Group 2,A Title,A User Name,A Password,A note with \n an embedded newline 

-------------------
title: DB Merging

Password Gorilla also has the ability to merge separate PWsafe databases
together into a single database.  This feature is most useful if you
maintain the same password file on multiple computers, say a desktop and
laptop machine.  As you go about your daily routine, you can make changes to
either file, and then periodically merge the two different databases together to
produce an identical database on both machines.  

-------------------
title: Performing a Merge

Merging always happens in the context of the currently open database.  Step
one is to open the PWsafe database file into which you wish to merge another
database (the "master database").  Once you have open the database you wish
to merge into, then choose "File" -> "Merge ..." and select and open the
PWsafe database you wish to merge into the currently open database (the
"merge database").  Once you supply the correct master password for the
merge database, Password Gorilla will perform a merge.  Password records
that are identical between both databases will be unchanged, and only one
record will remain after the merge is complete.  Password records that only
exist in the merge database will become new records in the master database. 
Password records that overlap between both databases will produce "conflict"
records in the master database.

Once the merge is complete, Password Gorilla will alert you to the number of
total password entries merged, the number of identical entries
(overlapping), the number of newly added entries, and the number of
conflicting entries.  The status window which reports these values will then
ask if you wish to view a detailed report.  The detailed report will list
each entry that is conflicting, each entry which was added, and the entries
that were identical between both files.

-------------------
title: Resolving Merge Conflicts

If any merged password entries were conflicting (meaning they were the same
record, with small differences) then there are two ways to access the
conflict resolution dialog.  The first method is to push the "Resolve
Conflicts" button at the bottom of the detailed merge report window.  The
second method is to use the "File" -> "Resolve Conflicts ..." menu entry. 
Both methods will cause the entry conflict resolution dialog to appear.

The conflict resolution dialog is a tabbed window, each tab containing one
pair of conflicting password entries from a merge operation.  The contents
of each tab list the group, title, url, username, password, and notes fields
from both conflicting entries adjacent to each other so you may see what
differs and decide how you wish to handle the differences in the data.  Each
individual entry is proceeded by a radio button, the radio button is used to
select which one of the two entries you wish to keep in a merged record. 
I.e., for the title value, there are two entries, if the radio button for
the first title entry is checked, then when you combine and save the whole
password entry the first title entry value will be utilized as the value to
be inserted into the password database.

Entries that are identical default to already having the first radio button
checked.  Entries that differ do not have any radio button checked, and are
also highlighted in a light green background color.

All fields may be edited, but only the field adjacent to the checked radio
button will be inserted into the password database.

The password field initially defaults to a display of stars "*" for the
password for security reasons.  Clicking the right mouse button within the
password entries will toggle between display of stars and display of the
actual password contents.

To resolve conflicts, you should view each tab, select the radio buttons for
the fields you wish to keep, make any additional edits you desire to the
fields you wish to keep, and press the "Combine and Save" button when you
have made all your selections.  The "Combine and Save" button will only
become enabled once you have made a radio button selection in all
conflicting fields (green background).

If you wish to reset your edits, then press the "Reset Values" button.  That
will undo all edits you have made to all fields and return the values to
their initial condition.

If you do not wish to resolve an individual conflict at this time, press the
"Ignore Conflict" button.  You can return to the conflict resolution dialog
at a later time to finish resolving the conflicts.  However, once you exit
Password Gorilla the list of conflicting records will be lost, so please
resolve all conflicts before exiting.  No password data will be lost
however, as if you do not resolve a conflict but do save the database, you
will simply have a pair of records in your database that you can manually
resolve at a later time.

Both the "Combine and Save" and "Ignore Conflict" buttons will remove the
current tab when pressed.  Once there is only a single tab remaining then
both buttons will also remove the conflict merge window from your screen. 
If you ignored any conflicts, you can return to the conflict merge window by
using the "File" -> "Resolve Conflicts ..." menu entry.

Note, the merge system and conflict dialog are not infallible.  It is
generally best to resolve all conflicts before performing a additional merge
with another password safe database.  No harm occurs if this suggestion is
not followed, but duplicate or nearly duplicate entries may result if plural
merges are performed without resolving conflicts between each merge.  The
duplicate or nearly duplicate entries will simply need to be manually
resolved.