See parent: pwsafe
Four major file format versions exist. V3 (.psafe3) is the current default. V4 (.psafe4) adds attachment support. V1/V2 are legacy and can be read but not written. The version history is documented in docs/formatV1.txt through docs/formatV4.txt.
The V3 format (spec: docs/formatV3.txt) is:
TAG | SALT | ITER | H(P') | B1 | B2 | B3 | B4 | IV | HDR | R1..Rn | EOF | HMAC• TAG: 4-byte ASCII "PWS3" magic
• SALT: 256-bit random salt
• ITER: 32-bit iteration count for key stretching
• H(P'): SHA-256 of stretched key — used to verify the passphrase
• B1/B2: encryption key K, wrapped with TwoFish(P') ECB
• B3/B4: HMAC key L, wrapped with TwoFish(P') ECB
• IV: 128-bit CBC initialisation vector
• HDR: database header (typed fields, TwoFish CBC)
• R1..Rn: encrypted records (typed fields)
• EOF: 16-byte marker "PWS3-EOFPWS3-EOF" (unencrypted)
• HMAC: HMAC-SHA-256 over all encrypted data
Both the header and each record consist of a sequence of typed fields. Each field has a 1-byte type tag, a 4-byte little-endian length, and the data. Records are terminated by an END field (type 0xFF). Mandatory record fields: UUID, Title, Password.
Defined in src/core/Item.h enum FieldType. Key fields: GROUP (0x02), TITLE (0x03), USER (0x04), NOTES (0x05), PASSWORD (0x06), URL (0x0D), AUTOTYPE (0x0E), EMAIL (0x14), TOTP fields, custom fields.
Entries can be: Normal, AliasBase, Alias (password is a reference to a base entry), ShortcutBase, Shortcut. Aliases and shortcuts share credentials from their base entry at access time.
src/core/PWSfile.cpp — abstract base (factory, CheckPasskey)
src/core/PWSfileV3.cpp — V3 read/write logic
src/core/PWSfileV4.cpp — V4 read/write (adds attachments)
src/core/PWSfileHeader.cpp — header field parsing