Crypt::...eformat(3)

📦
version 1.23~20220227git002b0f0 · 2 versions
, in fedora 43

🎀 Crypt::...eformat(3) 🎀

okay bestie, so this is a User Contributed Perl Documentation page — the manual for Crypt::...eformat(3). Sit down, grab a snack, we're doing a deep dive 💅

✨ NAME ✨

PasswordSafe database format description version 3.03

💖 LICENSE 💖

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

🌸 1. Introduction 🌸

This document defines a file format for the secure storage of passwords and related data. The format is designed according to current cryptographic best practices, and is believed to be secure — in the sense that without knowledge of the master passphrase, only a brute-force attack or a flaw in the underlying cryptographic algorithm will result in unauthorized access to the data. no cap 🔥

🦋 1.1 Design Goals

The PasswordSafe database format is designed to be secure, extensible and platform-independent. iconic behavior honestly 👑

🧚 1.2 History

This specification is an evolution of previous formats. The main differences between version 3 of the format and previous versions are:

  1. 1.2.1. This version addresses a minor design flaw in previous versions of the PasswordSafe database format.
  2. 1.2.3. This version replaces the underlying cryptographic functions with more advanced versions.
  3. 1.2.4. This version allows the detection of a truncated or corrupted/tampered database.

Meeting these goals is impossible without breaking compatibility: this format is NOT compatible with previous (major) versions. Note, however, that since the data stored in previous versions is a proper subset of the data described here, implementers may read a database written in an older version and store the result in the format described here. glow-up but make it backwards-readable ✨

💜 2. Format 💜

A V3 format PasswordSafe is structured as follows:

TAG|SALT|ITER|H(P')|B1|B2|B3|B4|IV|HDR|R1|R2|...|Rn|EOF|HMAC

Where:

🍓 2.1 TAG

TAG is the sequence of 4 ASCII characters "PWS3". This is to serve as a quick way for the application to identify the database as a PasswordSafe version 3 file. This tag has no cryptographic value. it's just a lil name tag, not a security guard 🏷️

🌈 2.1 SALT

SALT is a 256 bit random value, generated at file creation time.

⭐ 2.3 P'

P' is the "stretched key" generated from the user's passphrase and the SALT, as defined in by the hash-function-based key stretching algorithm in [KEYSTRETCH] (Section 4.1), with SHA-256 [SHA256] as the hash function, and ITER iterations (at least 2048, i.e., t = 11).

💫 2.4 ITER

ITER is the number of iterations on the hash function to calculate P', stored as a 32 bit little-endian value. This value is stored here in order to future-proof the file format against increases in processing power. forward thinking queen 💅

🔥 2.5 H(P')

H(P') is SHA-256(P'), and is used to verify that the user has the correct passphrase.

🫶 2.6 B1 and B2

B1 and B2 are two 128-bit blocks encrypted with Twofish [TWOFISH] using P' as the key, in ECB mode. These blocks contain the 256 bit random key K that is used to encrypt the actual records. (This has the property that there is no known or guessable information on the plaintext encrypted with the passphrase-derived key that allows an attacker to mount an attack that bypasses the key stretching algorithm.)

👑 2.7 B3 and B4

B3 and B4 are two 128-bit blocks encrypted with Twofish using P' as the key, in ECB mode. These blocks contain the 256 bit random key L that is used to calculate the HMAC (keyed-hash message authentication code) of the encrypted data. See description of EOF field below for more details.

Implementation Note: K and L must NOT be related. like, they cannot be siblings, besties, cousins, nothing. keep them strangers fr fr 😭

🌸 2.8 IV

IV is the 128-bit random Initial Value for CBC mode.

🦋 2.9

All following records are encrypted using Twofish in CBC mode, with K as the encryption key.

💖 2.9.1 HDR

The database header. The header consists of one or more typed fields (as defined in section 3.2), terminated by the 'END' type field. The version number field is mandatory. Aside from the 'END' field, no order is assumed on the field types.

🎀 2.9.2 R1..Rn

The actual database records. Each record consists of one or more typed fields (as defined in Section 3.2), terminated by the 'END' type field. The UUID, Title, and Password fields are mandatory. All non-mandatory fields may either be absent or have zero length. When a field is absent or zero-length, its default value shall be used. Aside from the 'END' field, no order is assumed on the field types.

💜 2.10 EOF

EOF is the ASCII characters "PWS3-EOFPWS3-EOF" (note that this is exactly one block long), unencrypted. This is an implementation convenience to inform the application that the following bytes are to be processed differently. it's giving "heads up, next part hits different" 📢

🌈 2.11 HMAC

HMAC is the 256-bit keyed-hash MAC, as described in RFC2104, with SHA-256 as the underlying hash function. The value is calculated over all of the plaintext fields, that is, over all the data stored in all fields (starting from the version number in the header, ending with the last field of the last record). The key L as stored in B3 and B4 is used as the hash key value.

⭐ 3. Fields ⭐

Data in PasswordSafe is stored in typed fields. Each field consists of one or more blocks. The blocks are the blocks of the underlying encryption algorithm — 16 bytes long for Twofish. The first block contains the field length in the first 4 bytes (little-endian), followed by a one-byte type identifier. The rest of the block contains up to 11 bytes of record data. If the record has less than 11 bytes of data, the extra bytes are filled with random values. The type of a field also defines the data representation.

🧚 3.1 Data representations

💫 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

okay here's the lineup bestie, every field, its value, its type, whether it's currently implemented, and its comment ref ✨

  • Version — value 0x00, type 2 bytes, currently implemented Y, comments [1]
  • UUID — value 0x01, type UUID, currently implemented Y, comments [2]
  • Non-default preferences — value 0x02, type Text, currently implemented Y, comments [3]
  • Tree Display Status — value 0x03, type Text, currently implemented Y, comments [4]
  • Timestamp of last save — value 0x04, type time_t, currently implemented Y, comments [5]
  • Who performed last save — value 0x05, type Text, currently implemented Y, comments [DEPRECATED 6]
  • What performed last save — value 0x06, type Text, currently implemented Y, comments [7]
  • Last saved by user — value 0x07, type Text, currently implemented Y, comments [8]
  • Last saved on host — value 0x08, type Text, currently implemented Y, comments [9]
  • Database Name — value 0x09, type Text, currently implemented Y, comments [10]
  • Database Description — value 0x0a, type Text, currently implemented Y, comments [11]
  • Database Filters — value 0x0b, type Text, currently implemented Y, comments [12]
  • End of Entry — value 0xff, type [empty], currently implemented Y, comments [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. yeah it was a whole thing, we don't talk about it 🙈

[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].

and that's only half the tea bestie, there's more where this came from 👀

  • [9] — Text containing the hostname (think machine name, hostid, whatever) of the machine where the database was last saved, as worked out by the appropriate operating-system dependent function. Bestie, this field showed up in format version 0x0302, replacing field 0x05. Check Comment [6]. 💖
  • [10] — Database name. It's a logical name for a database that apps can use instead of the potentially super long filepath situation. Note that this field SHOULD be limited to what can be displayed in a single line. Introduced in format version 0x0302. ✨
  • [11] — Database Description. Purely informative, just vibes about the purpose or other practical use of the database. Introduced in format version 0x0302.
  • [12] — Specfic filters for this database.</...> okay literally the original says "Specfic" so I'm keeping it fr. 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. Introduced in format version 0x0305. 🎀
  • [13] — An explicit end of entry field is useful for supporting new fields without breaking backwards compatability. iykyk, this is the load-bearing one.

🦋 3.3 Field types for database Records 🦋

Here's the whole roster, bestie. Name, value, type, whether it's currently implemented, and which comment to go read:

  • UUID — value 0x01, type UUID, implemented: Y — see [1]
  • Group — value 0x02, type Text, implemented: Y — see [2]
  • Title — value 0x03, type Text, implemented: Y
  • Username — value 0x04, type Text, implemented: Y
  • Notes — value 0x05, type Text, implemented: Y
  • Password — value 0x06, type Text, implemented: Y — see [3,4]
  • Creation Time — value 0x07, type time_t, implemented: Y — see [5]
  • Password Modification Time — value 0x08, type time_t, implemented: Y — see [5]
  • Last Access Time — value 0x09, type time_t, implemented: Y — see [5,6]
  • Password Expiry Time — value 0x0a, type time_t, implemented: Y — see [5,7]
  • *RESERVED* — value 0x0b, type 4 bytes, implemented: - — see [8]
  • Last Modification Time — value 0x0c, type time_t, implemented: Y — see [5,9]
  • URL — value 0x0d, type Text, implemented: Y — see [10]
  • Autotype — value 0x0e, type Text, implemented: Y — see [11]
  • Password History — value 0x0f, type Text, implemented: Y — see [12]
  • Password Policy — value 0x10, type Text, implemented: Y — see [13]
  • Password Expiry Interval — value 0x11, type 2 bytes, implemented: Y — see [14]
  • End of Entry — value 0xff, type [empty], implemented: Y — see [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].
🚩 Bestie this one is a genuine trap. Read it twice before you touch 0x0b.
  • [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.
💀 Yes, that means shell execution. It's giving "powerful but be careful."
  • [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.

🌈 4. Extensibility 🌈

4.1 Forward compatability

Implementations of this format SHOULD NOT discard or report an error when encountering a filed of an unknown type. Rather, the field(s) type and data should be read, and perserved when the database is saved.

(Yes, the original says "filed" and "perserved". Not me, I'm just the messenger. 💖)

4.2 Field type identifiers

This document specifies the field type identifiers for the current version of the format. Compliant implementations MUST support the mandatory fields, and SHOULD support the other fields described herein. Future versions of the format may specify other type identifiers.

4.2.1 Application-unique type identifiers

The type identifiers 0xc0-0xdf are available for application developers on a first-come first-serve basis. Application developers interested in reserving a type identifier for their application should contact the maintainer of this document (Currently the PasswordSafe project administrator at SourceForge). 👑

4.2.2 Application-specific type identifiers

The type identifiers 0xe0-0xfe are reserved for implementation-specific purposes, and will NOT be specified in this or future versions of the format description.

4.2.3

All unassigned identifiers except as listed in the previous two subsections are reserved, and should not be used by other implementations of this format specification in the interest of interoperablity.

🧚 5. References: 🧚

End of Format description. 🎀

💜 SEE ALSO 💜

Original source of this file:

http://passwordsafe.svn.sourceforge.net/viewvc/passwordsafe/trunk/pwsafe/pwsafe/docs/formatV3.txt?revision=2139

okay bestie that's the whole thing, we ate and left absolutely no crumbs 💅✨ this page came from perl v5.42.0, dated 2025-07-25, and it lives at Crypt::...eformat(3) — go forth and parse responsibly, ily 🫶🌸

📦 where this page comes from