3.1.1 UUID

 The UUID data type is 16 bytes long, as defined in RFC4122. Microsoft
 Windows has functions for this, and the RFC has a sample
 implementation.

3.1.2 Text

 Text is represented in UTF-8 encoding (as defined in RFC3629), with
 no byte order marker (BOM) and no end-of-string mark (e.g., null
 byte). Note that the latter isn't neccessary since the length of the
 field is provided explicitly. Note that ALL fields described as
 "text" are UTF-8 encoded unless explicitly stated otherwise.

3.1.3 Time

 Timestamps are stored as 32 bit, little endian, unsigned integers,
 representing the number of seconds since Midnight, January 1, 1970, GMT.
 (This is equivalent to the time_t type on Windows and POSIX. On the
 Macintosh, the value needs to be adjusted by the constant value 2082844800
 to account for the different epoch of its time_t type.)
 Note that future versions of this format may allow time to be
 specifed in 64 bits as well.

3.2 Field types for the PasswordSafe database header:

                                                 Currently
 Name                        Value        Type    Implemented      Comments
 --------------------------------------------------------------------------
 Version                     0x00        2 bytes       Y              [1]
 UUID                        0x01        UUID          Y              [2]
 Non-default preferences     0x02        Text          Y              [3]
 Tree Display Status         0x03        Text          Y              [4]
 Timestamp of last save      0x04        time_t        Y              [5]
 Who performed last save     0x05        Text          Y   [DEPRECATED 6]
 What performed last save    0x06        Text          Y              [7]
 Last saved by user          0x07        Text          Y              [8]
 Last saved on host          0x08        Text          Y              [9]
 Database Name               0x09        Text          Y              [10]
 Database Description        0x0a        Text          Y              [11]
 Database Filters            0x0b        Text          Y              [12]
 End of Entry                0xff        [empty]       Y              [13]

[1] The version number of the database format. For this version, the value is 0x0305 (stored in little-endian format, that is, 0x05, 0x03).

PasswordSafe V3.01 introduced Format 0x0300 PasswordSafe V3.03 introduced Format 0x0301 PasswordSafe V3.09 introduced Format 0x0302 PasswordSafe V3.12 introduced Format 0x0303 PasswordSafe V3.13 introduced Format 0x0304 PasswordSafe V3.14 introduced Format 0x0305

[2] A universally unique identifier is needed in order to synchronize databases, e.g., between a handheld pocketPC device and a PC. Representation is as described in Section 3.1.1.

[3] Non-default preferences are encoded in a string as follows: The string is of the form "X nn vv X nn vv..." Where X=[BIS] for binary, integer and string respectively, nn is the numeric value of the enum, and vv is the value, {1 or 0} for bool, unsigned integer for int, and a delimited string for String. Only non-default values are stored. See PWSprefs.cpp for more details. Note: normally strings are delimited by the doublequote character. However, if this character is in the string value, an arbitrary character will be chosen to delimit the string.

[4] If requested to be saved, this is a string of 1s and 0s indicating the expanded state of the tree display when the database was saved. This can be applied at database open time, if the user wishes, so that the tree is displayed as it was. Alternatively, it can be ignored and the tree displayed completely expanded or collapsed. Note that the mapping of the string to the display state is implementation-specific. Introduced in format 0x0301.

[5] Representation is as described in Section 3.1.3. Note that prior to PasswordSafe 3.09, this field was mistakenly represented as an eight-byte hexadecimal ASCII string. Implementations SHOULD attempt to parse 8-byte long timestamps as a hexadecimal ASCII string representation of the timestamp value.

[6] Text saved in the format: nnnnu..uh..h, where: nnnn = 4 hexadecimal digits giving length of following user name field u..u = user name h..h = host computer name Note: As of format 0x0302, this field is deprecated, and should be replaced by fields 0x07 and 0x08. In databases prior to format 0x0302, this field should be maintained. 0x0302 and later may either maintain this field in addition to fields 0x07 and 0x08, for backwards compatability, or not write this field. If both this field and 0x07, 0x08 exist, they MUST represent the same values.

[7] Free form text giving the application that saved the database. For example, the Windows PasswordSafe application will use the text "Password Safe Vnn.mm", where nn and mm are the major and minor version numbers. The major version will contain only the significant digits whereas the minor version will be padded to the left with zeroes e.g. "Password Safe V3.02".

[8] Text containing the username (e.g., login, userid, etc.) of the user who last saved the database, as determined by the appropriate operating-system dependent function. This field was introduced in format version 0x0302, as a replacement for field 0x05. See Comment [6].

[9] Text containing the hostname (e.g., machine name, hostid, etc.) of the machine on which the database was last saved, as determined by the appropriate operating-system dependent function. This field was introduced in format version 0x0302, as a replacement for field 0x05. See Comment [6].

[10] Database name. A logical name for a database which can be used by applications in place of the possibly lengthy filepath notion. Note that this field SHOULD be limited to what can be displayed in a single line. This field was introduced in format version 0x0302.

[11] Database Description. A purely informative description concerning the purpose or other practical use of the database. This field was introduced in format version 0x0302.

[12] Specfic filters for this database. This is the text equivalent to the XML export of the filters as defined by the filter schema. The text 'image' has no 'print formatting' e.g. tabs and carraige return/line feeds, since XML processing does not require this. This field was introduced in format version 0x0305.

[13] An explicit end of entry field is useful for supporting new fields without breaking backwards compatability.

3.3 Field types for database Records:

                                                 Currently
 Name                        Value        Type    Implemented      Comments
 --------------------------------------------------------------------------
 UUID                        0x01        UUID          Y              [1]
 Group                       0x02        Text          Y              [2]
 Title                       0x03        Text          Y
 Username                    0x04        Text          Y
 Notes                       0x05        Text          Y
 Password                    0x06        Text          Y              [3,4]
 Creation Time               0x07        time_t        Y              [5]
 Password Modification Time  0x08        time_t        Y              [5]
 Last Access Time            0x09        time_t        Y              [5,6]
 Password Expiry Time        0x0a        time_t        Y              [5,7]
 *RESERVED*                  0x0b        4 bytes       -              [8]
 Last Modification Time      0x0c        time_t        Y              [5,9]
 URL                         0x0d        Text          Y              [10]
 Autotype                    0x0e        Text          Y              [11]
 Password History            0x0f        Text          Y              [12]
 Password Policy             0x10        Text          Y              [13]
 Password Expiry Interval    0x11        2 bytes       Y              [14]
 End of Entry                0xff        [empty]       Y              [15]

[1] Per-record UUID to assist in sync, merge, etc. Representation is as described in Section 3.1.1.

[2] The "Group" supports displaying the entries in a tree-like manner. Groups can be hierarchical, with elements separated by a period, supporting groups such as "Finance.credit cards.Visa", "Finance.credit cards.Mastercard", Finance.bank.web access", etc. Dots entered by the user should be "escaped" by the application.

[3] If the entry is an alias, the password will be saved in a special form of "[[uuidstr]]", where "uuidstr" is a 32-character representation of the alias' associated base entry's UUID (field type 0x01). This representation is the same as the standard 36-character string representation as defined in RFC4122 but with the four hyphens removed. If an entry with this UUID is not in the database, this is treated just as an 'unusual' password. The alias will only use its base's password entry when copying it to the clipboard or during Autotype.

[4] If the entry is a shortcut, the password will be saved in a special form of "[~uuidstr~]", where "uuidstr" is a 32-character representation of the shortcut's associated base entry's UUID (field type 0x01). This representation is the same as the standard 36-character string representation as defined in RFC4122 but with the four hyphens removed. If an entry with this UUID is not in the database, this is treated just as an 'unusual' password. The shortcut will use all its base's data when used in any action. It has no fields of its own.

[5] Representation is as described in Section 3.1.3.

[6] This will be updated whenever any part of this entry is accessed i.e., to copy its username, password or notes to the clipboard; to perform autotype or to browse to url.

[7] This will allow the user to enter an expiry date for an entry. The application can then prompt the user about passwords that need to be changed. A value of zero means "forever".

[8] Although earmarked for Password Policy, the coding in versions prior to V3.12 does not correctly handle the presence of this field. For this reason, this value cannot be used for any future V3 field without causing a potential issue when a user opens a V3.12 or later database with program version V3.11 or earlier. See note [14].

[9] This is the time that any field of the record was modified, useful for merging databases.

[10] The URL will be passed to the shell when the user chooses the "Browse to" action for this entry. In version 2 of the format, this was extracted from the Notes field. By placing it in a separate field, we are no longer restricted to a URL - any action that may be executed by the shell may be specified here.

[11] The text to be 'typed' by PasswordSafe upon the "Perform Autotype" action maybe specified here. If unspecified, the default value of 'username, tab, password, tab, enter' is used. In version 2 of the format, this was extracted from the Notes field. Several codes are recognized here, e.g, '%p' is replaced by the record's password. See the user documentation for the complete list of codes. The replacement is done by the application at runtime, and is not stored in the database.

[12] Password History is an optional record. If it exists, it stores the creation times and values of the last few passwords used in the current entry, in the following format: "fmmnnTLPTLP...TLP" where: f = {0,1} if password history is on/off mm = 2 hexadecimal digits max size of history list (i.e. max = 255) nn = 2 hexadecimal digits current size of history list T = Time password was set (time_t written out in %08x) L = 4 hexadecimal digit password length (in TCHAR) P = Password No history being kept for a record can be represented either by the lack of the PWH field (preferred), or by a header of _T("00000"): flag = 0, max = 00, num = 00 Note that 0aabb, where bb <= aa, is possible if password history was enabled in the past and has then been disabled but the history hasn't been cleared.

[13] This field allows a specific Password Policy per entry. The format is:

    "ffffnnnllluuudddsss"

where:

     ffff = 4 hexadecimal digits representing the following flags
        UseLowercase =      0x8000  - can have a minimum length
        UseUppercase =      0x4000  - can have a minimum length
        UseDigits =         0x2000  - can have a minimum length
        UseSymbols =        0x1000  - can have a minimum length
        UseHexDigits =      0x0800 (if set, then no other flags can be set)
        UseEasyVision =     0x0400
        MakePronounceable = 0x0200
        Unused              0x01ff
    nnn  = 3 hexadecimal digits password total length
    lll  = 3 hexadecimal digits password minimum number of lowercase characters
    uuu  = 3 hexadecimal digits password minimum number of uppercase characters
    ddd  = 3 hexadecimal digits password minimum number of digit characters
    sss  = 3 hexadecimal digits password minimum number of symbol characters

[14] Password Expiry Interval, in days, before this password expires. Once set, this value is used when the password is first generated and thereafter whenever the password is changed, until this value is unset. Valid values are 1-3650 corresponding to up to approximately 10 years. A value of zero is equivalent to this field not being set.

[15] An explicit end of entry field is useful for supporting new fields without breaking backwards compatability.