1Crypt::PWSafe3::DatabasUesfeorrmCaotn(t3r)ibuted Perl DoCcruympetn:t:aPtWiSoanfe3::Databaseformat(3)
2
3
4

NAME

6       PasswordSafe database format description version 3.03
7

LICENSE

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

1. Introduction

16       This document defines a file format for the secure storage of passwords
17       and related data. The format is designed according to current
18       cryptographic best practices, and is beleived to be secure, in the
19       sense that without knowledge of the master passphrase, only a brute-
20       force attack or a flaw in the underlying cryptographic algorithm will
21       result in unauthorized access to the data.
22
23       1.1 Design Goals: The PasswordSafe database format is designed to be
24       secure, extensible and platform-independent.
25
26       1.2 History: This specification is an evolution of previous formats.
27       The main differences between version 3 of the format and previous
28       versions are: 1.2.1. This version addresses a minor design flaw in
29       previous versions of the PasswordSafe database format.  1.2.3. This
30       version replaces the underlying cryptographic functions with more
31       advanced versions.  1.2.4. This version allows the detection of a
32       truncated or corrupted/tampered database.
33
34       Meeting these goals is impossible without breaking compatibility: This
35       format is NOT compatible with previous (major) versions. Note, however,
36       that since the data stored in previous versions is a proper subset of
37       the data described here, implementers may read a database written in an
38       older version and store the result in the format described here.
39

2. Format

41       A V3 format PasswordSafe is structured as follows:
42
43           TAG|SALT|ITER|H(P')|B1|B2|B3|B4|IV|HDR|R1|R2|...|Rn|EOF|HMAC
44
45       Where:
46
47       2.1 TAG is the sequence of 4 ASCII characters "PWS3". This is to serve
48       as a quick way for the application to identify the database as a
49       PasswordSafe version 3 file. This tag has no cryptographic value.
50
51       2.1 SALT is a 256 bit random value, generated at file creation time.
52
53       2.3 P' is the "stretched key" generated from the user's passphrase and
54       the SALT, as defined in by the hash-function-based key stretching
55       algorithm in [KEYSTRETCH] (Section 4.1), with SHA-256 [SHA256] as the
56       hash function, and ITER iterations (at least 2048, i.e., t = 11).
57
58       2.4 ITER is the number of iterations on the hash function to calculate
59       P', stored as a 32 bit little-endian value. This value is stored here
60       in order to future-proof the file format against increases in
61       processing power.
62
63       2.5 H(P') is SHA-256(P'), and is used to verify that the user has the
64       correct passphrase.
65
66       2.6 B1 and B2 are two 128-bit blocks encrypted with Twofish [TWOFISH]
67       using P' as the key, in ECB mode. These blocks contain the 256 bit
68       random key K that is used to encrypt the actual records. (This has the
69       property that there is no known or guessable information on the
70       plaintext encrypted with the passphrase-derived key that allows an
71       attacker to mount an attack that bypasses the key stretching
72       algorithm.)
73
74       2.7 B3 and B4 are two 128-bit blocks encrypted with Twofish using P' as
75       the key, in ECB mode. These blocks contain the 256 bit random key L
76       that is used to calculate the HMAC (keyed-hash message authentication
77       code) of the encrypted data. See description of EOF field below for
78       more details.  Implementation Note: K and L must NOT be related.
79
80       2.8 IV is the 128-bit random Initial Value for CBC mode.
81
82       2.9 All following records are encrypted using Twofish in CBC mode, with
83       K as the encryption key.
84
85       2.9.1 HDR: The database header. The header consists of one or more
86       typed fields (as defined in section 3.2), terminated by the 'END' type
87       field. The version number field is mandatory. Aside from the 'END'
88       field, no order is assumed on the field types.
89
90       2.9.2 R1..Rn: The actual database records. Each record consists of one
91       or more typed fields (as defined in Section 3.2), terminated by the
92       'END' type field. The UUID, Title, and Password fields are mandatory.
93       All non- mandatory fields may either be absent or have zero length.
94       When a field is absent or zero-length, its default value shall be used.
95       Aside from the 'END' field, no order is assumed on the field types.
96
97       2.10 EOF: The ASCII characters "PWS3-EOFPWS3-EOF" (note that this is
98       exactly one block long), unencrypted. This is an implementation
99       convenience to inform the application that the following bytes are to
100       be processed differently.
101
102       2.11 HMAC: The 256-bit keyed-hash MAC, as described in RFC2104, with
103       SHA- 256 as the underlying hash function. The value is calculated over
104       all of the plaintext fields, that is, over all the data stored in all
105       fields (starting from the version number in the header, ending with the
106       last field of the last record). The key L as stored in B3 and B4 is
107       used as the hash key value.
108
109       3. Fields: Data in PasswordSafe is stored in typed fields. Each field
110       consists of one or more blocks. The blocks are the blocks of the
111       underlying encryption algorithm - 16 bytes long for Twofish. The first
112       block contains the field length in the first 4 bytes (little-endian),
113       followed by a one- byte type identifier. The rest of the block contains
114       up to 11 bytes of record data. If the record has less than 11 bytes of
115       data, the extra bytes are filled with random values. The type of a
116       field also defines the data representation.
117

3.1 Data representations

119   3.1.1 UUID
120        The UUID data type is 16 bytes long, as defined in RFC4122. Microsoft
121        Windows has functions for this, and the RFC has a sample
122        implementation.
123
124   3.1.2 Text
125        Text is represented in UTF-8 encoding (as defined in RFC3629), with
126        no byte order marker (BOM) and no end-of-string mark (e.g., null
127        byte). Note that the latter isn't neccessary since the length of the
128        field is provided explicitly. Note that ALL fields described as
129        "text" are UTF-8 encoded unless explicitly stated otherwise.
130
131   3.1.3 Time
132        Timestamps are stored as 32 bit, little endian, unsigned integers,
133        representing the number of seconds since Midnight, January 1, 1970, GMT.
134        (This is equivalent to the time_t type on Windows and POSIX. On the
135        Macintosh, the value needs to be adjusted by the constant value 2082844800
136        to account for the different epoch of its time_t type.)
137        Note that future versions of this format may allow time to be
138        specifed in 64 bits as well.
139
140   3.2 Field types for the PasswordSafe database header:
141                                                        Currently
142        Name                        Value        Type    Implemented      Comments
143        --------------------------------------------------------------------------
144        Version                     0x00        2 bytes       Y              [1]
145        UUID                        0x01        UUID          Y              [2]
146        Non-default preferences     0x02        Text          Y              [3]
147        Tree Display Status         0x03        Text          Y              [4]
148        Timestamp of last save      0x04        time_t        Y              [5]
149        Who performed last save     0x05        Text          Y   [DEPRECATED 6]
150        What performed last save    0x06        Text          Y              [7]
151        Last saved by user          0x07        Text          Y              [8]
152        Last saved on host          0x08        Text          Y              [9]
153        Database Name               0x09        Text          Y              [10]
154        Database Description        0x0a        Text          Y              [11]
155        Database Filters            0x0b        Text          Y              [12]
156        End of Entry                0xff        [empty]       Y              [13]
157
158       [1] The version number of the database format. For this version, the
159       value is 0x0305 (stored in little-endian format, that is, 0x05, 0x03).
160
161       PasswordSafe V3.01 introduced Format 0x0300 PasswordSafe V3.03
162       introduced Format 0x0301 PasswordSafe V3.09 introduced Format 0x0302
163       PasswordSafe V3.12 introduced Format 0x0303 PasswordSafe V3.13
164       introduced Format 0x0304 PasswordSafe V3.14 introduced Format 0x0305
165
166       [2] A universally unique identifier is needed in order to synchronize
167       databases, e.g., between a handheld pocketPC device and a PC.
168       Representation is as described in Section 3.1.1.
169
170       [3] Non-default preferences are encoded in a string as follows: The
171       string is of the form "X nn vv X nn vv..." Where X=[BIS] for binary,
172       integer and string respectively, nn is the numeric value of the enum,
173       and vv is the value, {1 or 0} for bool, unsigned integer for int, and a
174       delimited string for String. Only non-default values are stored. See
175       PWSprefs.cpp for more details.  Note: normally strings are delimited by
176       the doublequote character.  However, if this character is in the string
177       value, an arbitrary character will be chosen to delimit the string.
178
179       [4] If requested to be saved, this is a string of 1s and 0s indicating
180       the expanded state of the tree display when the database was saved.
181       This can be applied at database open time, if the user wishes, so that
182       the tree is displayed as it was. Alternatively, it can be ignored and
183       the tree displayed completely expanded or collapsed. Note that the
184       mapping of the string to the display state is implementation-specific.
185       Introduced in format 0x0301.
186
187       [5] Representation is as described in Section 3.1.3. Note that prior to
188       PasswordSafe 3.09, this field was mistakenly represented as an eight-
189       byte hexadecimal ASCII string. Implementations SHOULD attempt to parse
190       8-byte long timestamps as a hexadecimal ASCII string representation of
191       the timestamp value.
192
193       [6] Text saved in the format: nnnnu..uh..h, where:
194           nnnn = 4 hexadecimal digits giving length of following user name
195       field
196           u..u = user name
197           h..h = host computer name
198           Note: As of format 0x0302, this field is deprecated, and should be
199           replaced by fields 0x07 and 0x08. In databases prior to format
200           0x0302, this field should be maintained. 0x0302 and later may
201           either maintain this field in addition to fields 0x07 and 0x08,
202           for backwards compatability, or not write this field. If both this
203           field and 0x07, 0x08 exist, they MUST represent the same values.
204
205       [7] Free form text giving the application that saved the database.  For
206       example, the Windows PasswordSafe application will use the text
207       "Password Safe Vnn.mm", where nn and mm are the major and minor version
208       numbers. The major version will contain only the significant digits
209       whereas the minor version will be padded to the left with zeroes e.g.
210       "Password Safe V3.02".
211
212       [8] Text containing the username (e.g., login, userid, etc.) of the
213       user who last saved the database, as determined by the appropriate
214       operating-system dependent function. This field was introduced in
215       format version 0x0302, as a replacement for field 0x05. See Comment
216       [6].
217
218       [9] Text containing the hostname (e.g., machine name, hostid, etc.) of
219       the machine on which the database was last saved, as determined by the
220       appropriate operating-system dependent function. This field was
221       introduced in format version 0x0302, as a replacement for field 0x05.
222       See Comment [6].
223
224       [10] Database name. A logical name for a database which can be used by
225       applications in place of the possibly lengthy filepath notion. Note
226       that this field SHOULD be limited to what can be displayed in a single
227       line. This field was introduced in format version 0x0302.
228
229       [11] Database Description. A purely informative description concerning
230       the purpose or other practical use of the database. This field was
231       introduced in format version 0x0302.
232
233       [12] Specfic filters for this database.  This is the text equivalent to
234       the XML export of the filters as defined by the filter schema. The text
235       'image' has no 'print formatting' e.g. tabs and carraige return/line
236       feeds, since XML processing does not require this. This field was
237       introduced in format version 0x0305.
238
239       [13] An explicit end of entry field is useful for supporting new fields
240       without breaking backwards compatability.
241
242   3.3 Field types for database Records:
243                                                        Currently
244        Name                        Value        Type    Implemented      Comments
245        --------------------------------------------------------------------------
246        UUID                        0x01        UUID          Y              [1]
247        Group                       0x02        Text          Y              [2]
248        Title                       0x03        Text          Y
249        Username                    0x04        Text          Y
250        Notes                       0x05        Text          Y
251        Password                    0x06        Text          Y              [3,4]
252        Creation Time               0x07        time_t        Y              [5]
253        Password Modification Time  0x08        time_t        Y              [5]
254        Last Access Time            0x09        time_t        Y              [5,6]
255        Password Expiry Time        0x0a        time_t        Y              [5,7]
256        *RESERVED*                  0x0b        4 bytes       -              [8]
257        Last Modification Time      0x0c        time_t        Y              [5,9]
258        URL                         0x0d        Text          Y              [10]
259        Autotype                    0x0e        Text          Y              [11]
260        Password History            0x0f        Text          Y              [12]
261        Password Policy             0x10        Text          Y              [13]
262        Password Expiry Interval    0x11        2 bytes       Y              [14]
263        End of Entry                0xff        [empty]       Y              [15]
264
265       [1] Per-record UUID to assist in sync, merge, etc. Representation is as
266       described in Section 3.1.1.
267
268       [2] The "Group" supports displaying the entries in a tree-like manner.
269       Groups can be hierarchical, with elements separated by a period,
270       supporting groups such as "Finance.credit cards.Visa", "Finance.credit
271       cards.Mastercard", Finance.bank.web access", etc. Dots entered by the
272       user should be "escaped" by the application.
273
274       [3] If the entry is an alias, the password will be saved in a special
275       form of "[[uuidstr]]", where "uuidstr" is a 32-character representation
276       of the alias' associated base entry's UUID (field type 0x01).  This
277       representation is the same as the standard 36-character string
278       representation as defined in RFC4122 but with the four hyphens removed.
279       If an entry with this UUID is not in the database, this is treated just
280       as an 'unusual' password.  The alias will only use its base's password
281       entry when copying it to the clipboard or during Autotype.
282
283       [4] If the entry is a shortcut, the password will be saved in a special
284       form of "[~uuidstr~]", where "uuidstr" is a 32-character representation
285       of the shortcut's associated base entry's UUID (field type 0x01).  This
286       representation is the same as the standard 36-character string
287       representation as defined in RFC4122 but with the four hyphens removed.
288       If an entry with this UUID is not in the database, this is treated just
289       as an 'unusual' password. The shortcut will use all its base's data
290       when used in any action.  It has no fields of its own.
291
292       [5] Representation is as described in Section 3.1.3.
293
294       [6] This will be updated whenever any part of this entry is accessed
295       i.e., to copy its username, password or notes to the clipboard; to
296       perform autotype or to browse to url.
297
298       [7] This will allow the user to enter an expiry date for an entry. The
299       application can then prompt the user about passwords that need to be
300       changed. A value of zero means "forever".
301
302       [8] Although earmarked for Password Policy, the coding in versions
303       prior to V3.12 does not correctly handle the presence of this field.
304       For this reason, this value cannot be used for any future V3 field
305       without causing a potential issue when a user opens a V3.12 or later
306       database with program version V3.11 or earlier.  See note [14].
307
308       [9] This is the time that any field of the record was modified, useful
309       for merging databases.
310
311       [10] The URL will be passed to the shell when the user chooses the
312       "Browse to" action for this entry. In version 2 of the format, this was
313       extracted from the Notes field. By placing it in a separate field, we
314       are no longer restricted to a URL - any action that may be executed by
315       the shell may be specified here.
316
317       [11] The text to be 'typed' by PasswordSafe upon the "Perform Autotype"
318       action maybe specified here. If unspecified, the default value of
319       'username, tab, password, tab, enter' is used. In version 2 of the
320       format, this was extracted from the Notes field. Several codes are
321       recognized here, e.g, '%p' is replaced by the record's password. See
322       the user documentation for the complete list of codes. The replacement
323       is done by the application at runtime, and is not stored in the
324       database.
325
326       [12] Password History is an optional record. If it exists, it stores
327       the creation times and values of the last few passwords used in the
328       current entry, in the following format:
329           "fmmnnTLPTLP...TLP" where:
330           f  = {0,1} if password history is on/off
331           mm = 2 hexadecimal digits max size of history list (i.e. max = 255)
332           nn = 2 hexadecimal digits current size of history list
333           T  = Time password was set (time_t written out in %08x)
334           L  = 4 hexadecimal digit password length (in TCHAR)
335           P  = Password No history being kept for a record can be represented
336       either by the lack of the PWH field (preferred), or by a header of
337       _T("00000"):
338           flag = 0, max = 00, num = 00 Note that 0aabb, where bb <= aa, is
339       possible if password history was enabled in the past and has then been
340       disabled but the history hasn't been cleared.
341
342       [13] This field allows a specific Password Policy per entry.  The
343       format is:
344
345           "ffffnnnllluuudddsss"
346
347       where:
348
349            ffff = 4 hexadecimal digits representing the following flags
350               UseLowercase =      0x8000  - can have a minimum length
351               UseUppercase =      0x4000  - can have a minimum length
352               UseDigits =         0x2000  - can have a minimum length
353               UseSymbols =        0x1000  - can have a minimum length
354               UseHexDigits =      0x0800 (if set, then no other flags can be set)
355               UseEasyVision =     0x0400
356               MakePronounceable = 0x0200
357               Unused              0x01ff
358           nnn  = 3 hexadecimal digits password total length
359           lll  = 3 hexadecimal digits password minimum number of lowercase characters
360           uuu  = 3 hexadecimal digits password minimum number of uppercase characters
361           ddd  = 3 hexadecimal digits password minimum number of digit characters
362           sss  = 3 hexadecimal digits password minimum number of symbol characters
363
364       [14] Password Expiry Interval, in days, before this password expires.
365       Once set, this value is used when the password is first generated and
366       thereafter whenever the password is changed, until this value is unset.
367       Valid values are 1-3650 corresponding to up to approximately 10 years.
368       A value of zero is equivalent to this field not being set.
369
370       [15] An explicit end of entry field is useful for supporting new fields
371       without breaking backwards compatability.
372

4. Extensibility

374       4.1 Forward compatability: Implementations of this format SHOULD NOT
375       discard or report an error when encountering a filed of an unknown
376       type. Rather, the field(s) type and data should be read, and perserved
377       when the database is saved.
378
379       4.2 Field type identifiers: This document specifies the field type
380       identifiers for the current version of the format. Compliant
381       implementations MUST support the mandatory fields, and SHOULD support
382       the other fields described herein. Future versions of the format may
383       specify other type identifiers.  4.2.1 Application-unique type
384       identifiers: The type identifiers 0xc0-0xdf are available for
385       application developers on a first-come first-serve basis. Application
386       developers interested in reserving a type identifier for their
387       application should contact the maintainer of this document (Currently
388       the PasswordSafe project administrator at SourceForge).  4.2.2
389       Application-specific type identifiers: The type identifiers 0xe0-0xfe
390       are reserved for implementation-specific purposes, and will NOT be
391       specified in this or future versions of the format description.  4.2.3
392       All unassigned identifiers except as listed in the previous two
393       subsections are reserved, and should not be used by other
394       implementations of this format specification in the interest of
395       interoperablity.
396

5. References:

398       [TWOFISH] http://www.schneier.com/paper-twofish-paper.html [SHA256]
399       http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf
400       [KEYSTRETCH] http://www.schneier.com/paper-low-entropy.pdf
401
402       End of Format description.
403

SEE ALSO

405       Original source of this file:
406
407       http://passwordsafe.svn.sourceforge.net/viewvc/passwordsafe/trunk/pwsafe/pwsafe/docs/formatV3.txt?revision=2139
408
409
410
411perl v5.38.0                      2023-07-20 Crypt::PWSafe3::Databaseformat(3)
Impressum