1Crypt::PWSafe3::DatabasUesfeorrmCaotn(t3r)ibuted Perl DoCcruympetn:t:aPtWiSoanfe3::Databaseformat(3)
2
6 PasswordSafe database format description version 3.03
7
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
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 1.1 Design Goals: The PasswordSafe database format is designed to be
24 secure, extensible and platform-independent.
25 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 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
41 A V3 format PasswordSafe is structured as follows:
42 TAG|SALT|ITER|H(P')|B1|B2|B3|B4|IV|HDR|R1|R2|...|Rn|EOF|HMAC
44 Where:
46 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 2.1 SALT is a 256 bit random value, generated at file creation time.
52 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 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 2.5 H(P') is SHA-256(P'), and is used to verify that the user has the
64 correct passphrase.
65 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 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 2.8 IV is the 128-bit random Initial Value for CBC mode.
81 2.9 All following records are encrypted using Twofish in CBC mode, with
83 K as the encryption key.
84 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 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 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 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 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
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 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 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 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 [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 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 [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 [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 [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 [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 [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 [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 [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 [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 [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 [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 [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 [13] An explicit end of entry field is useful for supporting new fields
240 without breaking backwards compatability.
241 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 [1] Per-record UUID to assist in sync, merge, etc. Representation is as
266 described in Section 3.1.1.
267 [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 [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 [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 [5] Representation is as described in Section 3.1.3.
293 [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 [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 [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 [9] This is the time that any field of the record was modified, useful
309 for merging databases.
310 [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 [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 [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 [13] This field allows a specific Password Policy per entry. The
343 format is:
344 "ffffnnnllluuudddsss"
346 where:
348 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 [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 [15] An explicit end of entry field is useful for supporting new fields
371 without breaking backwards compatability.
372
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 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
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 End of Format description.
403
405 Original source of this file:
406 http://passwordsafe.svn.sourceforge.net/viewvc/passwordsafe/trunk/pwsafe/pwsafe/docs/formatV3.txt?revision=2139
408perl v5.36.0 2023-01-20 Crypt::PWSafe3::Databaseformat(3)