
Copyright (c) 2003-2008 Rony Shapiro <ronys@users.sourceforge.net>.
All rights reserved. Use of the code is allowed under the Artistic
License terms, as specified in the LICENSE file distributed with this
code, or available from
http://www.opensource.org/licenses/artistic-license-2.0.php 

Build Environment:
==================
PasswordSafe was originally built using MSVC++ 6.0, along
with the HTML Help Workshop (downloadable from Microsoft's web site).
Later MSVS2003 was used, again with the HTML Help Workshop.
As of version 3.05, PasswordSafe is built with MSVS2005. HTML Help
Workshop is no longer needed to build the project, but is still used
to generate the .chm help file.

File format:
============
Following is a description of the "v1.9" file format. For v2 and v3
formats, see the formatv2.txt and formatv3.txt files, respectively.

v1.9 files are arranged as follows:

RND|H(RND)|SALT|IP|Name1|Password1|Notes1|...|NameN|PasswordN|NotesN

Where:

RND is an 8 byte random value, used along with H(RND) to quickly
verify the password.

H(RND) is SHA1_init_state_zero(Cipher(RND)|{0x00,0x00});
       tempSalt = SHA1(RND|{0x00,0x00}|password);
       Cipher(RND) is 1000 encryptions of RND, with tempSalt as the
       encryption key. In short, a kind of HMAC dependant on the
       password. Written before the HMAC RFC came out, no good reason
       to change. (If it ain't broke...)

SHA1_init_state_zero() is the same as the normal SHA1 but the initial
state of the hash is all zero's instead of the proscribed initial
values (0x67452301, 0xEFCDAB89 and so forth). This (as well as the two
zero bytes passed to SHA1) is an apparent artifact (bug?) of the
original implementation. Changing it now would break all existing
databases...

[Thanks to Nicolas Dade for refining the above description - see
https://sourceforge.net/forum/message.php?msg_id=2387939]
[Thanks again to Jason Diamond for correcting my correction (private
correspondence)]

SALT is the salt used for encrypting the data (you know, to protect
against dictionary attacks)

IP is the initial initialization vector value

Name, Password & Notes are stored sequentially as 8 byte blocks, with
the first block holding an int with the length (in bytes) of the
actual value, which follows immediately.

Apparently as a hack to upgrade from previous versions, the Name field
is actually two fields, "Title" and "Username", separated by
SPLTCHR. Furthermore, if the Username is DEFUSERCHR, then it is
replaced by the user's "default user name", as specified in
options. It works, but is not a pretty sight.


Registry:
=========
Currently, PasswordSafe stores configuration information in the
database and under the following registry tree:

HKEY_CURRENT_USER/Software/Counterpane Systems/Password Safe/


Security issues:
================
MainDlg::OnPasswordChange
- I [Jim Russell] see that the main-passkey is constantly in memory.
This seems like trouble.  Are we directly encrypting using the
main-passkey?  We should be just as secure by hashing the main-passkey
on entry, keeping *that* in memory, and tossing the entered password
into the Gutmann Void.
- Resolution: The main-passkey is no longer kept in the clear in memory.

- It seems that the biggest problem is the overuse of the secured
'CMyString' class.  This class is intended to securely delete the
memory used upon destruction, but it has automatic conversion
constructors for CStrings and 'C' strings.  If you've spent any time
reading things like 'Efficient C++', you know that C++ spends half its
time creating temporary copies of objects, mostly during automatic
type conversions.  I [Jim Russell] think that it is too hard a job to
keep track of all these, so I propose a new secure string class with
no automatic conversions whatsoever.  It will be much less convenient
to work with, and that is by design.  Most of the strings in this
program have no need to be secured, so let's just concentrate on the
ones that do.

I [Rony Shapiro], OTOH, think that CMyString is just fine, as long as
function parameters are declared as const CMyString & instead of plain
CMyString - this way, we avoid unnecessary object
contruction. Declaring a couple of cast operators also goes a long way
to keeping everyone happy. CMyString has been tweaked to make the
underlying CString m_mystring private, paving the way to replacing it
with an STL string, if/when we get to porting to a non-MS platform.
