YAPET - Yet Another Password Encryption Tool 0.8pre2

YAPET - Design

Rafael Ostertag

   $Id: DESIGN.sgml.in 2904 2009-09-04 05:11:30Z rafi $

   Copyright  2008, 2009, 2010 Rafael Ostertag <rafi@guengel.ch>
     __________________________________________________________________

   Table of Contents

   General
   Master Password
   Encryption Key
   File Structure

        Recognition String
        Header
        Password Records
        Example

   Security
   References

General

   YAPET stores passwords encrypted on disk. Passwords are kept in records
   with additional information. A record is comprised by the following
   components:

   Name
          The name displayed in the Main Screen.

   Host
          The host on which the password is used.

   Username
          The user name the password is associated with.

   Password
          The password to protect.

   Comment
          A comment.

   The encryption and hash functions used by YAPET are provided by the
   crypto(3) library of ssl(3). YAPET does not provide them itself.

Master Password

   YAPET uses a master password provided by the user to generate a key in
   order to encrypt and decrypt the password records. The master password
   is not stored permanently. It has to be entered when a file is opened
   or the screen is locked in order to unlock it.

Encryption Key

   The encryption key is generated by calculating a SHA1 hash of the
   master password. MD5 is used to hash the SHA1 hash. Both hashes are
   concatenated. Finally, RIPEMD-160 is used to generate a hash of the
   SHA1 and MD5 hashes. The RIPEMD-160 hash is then appended to the SHA1
   and MD5 hash, yielding a key of 448 bits. This key will be used for the
   Blowfish encryption algorithm in order to encrypt and decrypt password
   records.

File Structure

   A file created by YAPET has the following basic structure
    1. Clear text recognition string
    2. Clear text header length indicator (prefix)
    3. Encrypted header
    4. Clear text password record length indicator (prefix)
    5. Encrypted password record
    6. Clear text password record length indicator (prefix)
    7. Encrypted password record
    8. ...

   The prefixes are stored in big endian order, regardless of the
   endianess of the platform YAPET is running.

Recognition String

   Each file created by YAPET starts with a unencrypted recognition string
   which currently consists of the 8 bytes YAPET1.0 as depicted in
   Figure 1, "Recognition String".

   Figure 1. Recognition String
+--------+--------+--------+--------+--------+--------+--------+--------+
|   Y    |   A    |   P    |   E    |   T    |   1    |   .    |   0    |
| 1 byte | 1 byte | 1 byte | 1 byte | 1 byte | 1 byte | 1 byte | 1 byte |
+--------+--------+--------+--------+--------+--------+--------+--------+

Header

   After the recognition string a 4 byte unsigned integer which is stored
   in big-endian order follows. This indicator is read to determine how
   many bytes to read in order to get the encrypted header (Figure 2,
   "Encrypted Header").

   Figure 2. Encrypted Header
+--------+--------+--------+--------+
|   Length indicator in big-endian  |
|         order (4 bytes)           |
+--------+--------+--------+--------+--...---+
|  Encrypted header exactly as many bytes    |
|        indicated by the prefix             |
+--------+--------+--------+--------+--...---+

Pre Version 0.6 Header

   The decrypted header (Figure 3, "Pre Version 0.6 Decrypted Header") is
   25 bytes in size. The first byte indicates the version of the file. The
   next 20 bytes are used as control string. After decryption, the control
   string is compared to the predefined clear text control string, in
   order to find out whether or not the key used to decrypt was the same
   used to encrypt. The control string holds all characters from A to Z.

   Figure 3. Pre Version 0.6 Decrypted Header
+--------+
|Version |
| 1 byte |
+--------+--------+--------+--...---+
|          Control String           |
|             20 bytes              |
+--------+--------+--------+--...---+
|  Time when the Password  |
|    was set (4 bytes)     |
+--------+--------+--------+

   The Version field holds the value 1 (YAPET::VERSION_1).

   The length of the header is either 25 bytes on 32bit architectures, or
   29 bytes on 64bit architectures.

   This is considered as design flaw, thus starting from YAPET 0.6, the
   version 0.6 header was introduced, providing a stable size across
   platforms (see the section called "Version 0.6 Header").

Version 0.6 Header

   The pre version 0.6 header was designed with the uneducated assumption
   that time_t is always 4 bytes in size. This is not the case. Therefore,
   the version 0.6 header uses 64 bits for the password set field,
   regardless of the architecture, as shown in Figure 4, "Version 0.6
   Decrypted Header". The Version field will hold the value 2
   (YAPET::VERSION_2).

   Thus, the new header has always a size of 29 bytes, hence being stable
   across platforms.

   Figure 4. Version 0.6 Decrypted Header
+--------+
|Version |
| 1 byte |
+--------+--------+--------+--------+--------+--------+--...---+
|                     Control String                           |
|                        20 bytes                              |
+--------+--------+--------+--------+--------+--------+--...---+--------+
|            Time when the Password was set (8 bytes)                   |
|                                                                       |
+--------+--------+--------+--------+--------+--------+--------+--------+

   YAPET 0.6 or later is still able to read pre version 0.6 headers in
   order to maintain backwards compatibility with earlier releases. It
   will however write a version 0.6 header upon password change.

   YAPET 0.5 or earlier is able to read version 0.6 headers. If the master
   password on a version 0.6 file is changed using YAPET 0.5 or earlier,
   it will automatically become a pre version 0.6 file, and the
   restrictions for version 0.5 applies.

   Table 1, "File Compatibility Matrix of YAPET 0.5 or earlier" lists the
   compatibility between different processor architectures and YAPET 0.5.

   The tests were conducted mainly on Linux boxes.

   Table 1. File Compatibility Matrix of YAPET 0.5 or earlier
   YAPET running on File created
   Version 0.5 or earlier Version 0.6
   Little Endian Big Endian Little Endian Big Endian
   32bit 64bit 32bit 64bit 32bit 64bit 32bit 64bit

   Little

   Endian
   32bit ARM XScale yes yes yes yes^[a] yes^[a] yes^[a] yes^[a] yes^[a]
   i386 yes yes yes yes^[a] yes^[a] yes^[a] yes^[a] yes^[a]
   MIPS Loongson yes yes yes yes^[a] yes^[a] yes^[a] yes^[a] yes^[a]
   64bit AMD Opteron no yes no yes^[a] yes^[a] yes^[a] yes^[a] yes^[a]
   IA64 no yes no yes^[a] yes^[a] yes^[a] yes^[a] yes^[a]
   Xeon no yes no yes^[a] yes^[a] yes^[a] yes^[a] yes^[a]

   Big

   Endian
   32bit PA-RISC yes yes yes yes^[a] yes^[a] yes^[a] yes^[a] yes^[a]
   PowerPC G4 yes yes yes yes^[a] yes^[a] yes^[a] yes^[a] yes^[a]
   PowerPC G5 yes yes yes yes^[a] yes^[a] yes^[a] yes^[a] yes^[a]
   SPARC yes yes yes yes^[a] yes^[a] yes^[a] yes^[a] yes^[a]
   64bit PowerPC G5 no yes^[a] no yes yes yes yes yes
   SPARC no yes^[a] no yes yes yes yes yes

   ^[a] The password set field will be incorrectly read and displayed as
   Thu Jan 1 01:00:00 1970 in YAPET.

   Table 1, "File Compatibility Matrix of YAPET 0.5 or earlier" boils down
   to Table 2, "Summary of File Compatibility Matrix of YAPET 0.5 or
   earlier"

   Table 2. Summary of File Compatibility Matrix of YAPET 0.5 or earlier
   YAPET running on File created
   Version 0.5 or earlier Version 0.6
   Little Endian Big Endian Little Endian Big Endian
   32bit 64bit 32bit 64bit 32bit 64bit 32bit 64bit
   Little Endian 32bit yes yes yes yes yes yes yes yes
   Little Endian 64bit no yes no yes yes yes yes yes
   Big Endian 32bit yes yes yes yes yes yes yes yes
   Big Endian 64bit no yes no yes yes yes yes yes

Password Records

   Each encrypted password record is prefixed by a 4 byte unsigned integer
   which is stored in big-endian order. That integer is used to indicate
   the length of the following encrypted data chunk.

   Figure 5. Encrypted Password Record
+--------+--------+--------+--------+
|   Length indicator in big-endian  |
|         order (4 bytes)           |
+--------+--------+--------+--------+--...---+
|  Encrypted password record of exactly as   |
|   many bytes as indicated by the prefix    |
+--------+--------+--------+--------+--...---+
|   Length indicator in big-endian  |
|         order (4 bytes)           |
+--------+--------+--------+--------+--...---+
|  Encrypted password record of exactly as   |
|   many bytes as indicated by the prefix    |
+--------+--------+--------+--------+--...---+
              [ . . . ]

Example

   Putting this together, an encrypted file created by YAPET may look like
   this

   Figure 6. Encrypted File Example
+--------+--------+--------+--------+--------+--------+--------+--------+
|   Y    |   A    |   P    |   E    |   T    |   1    |   .    |   0    |
| 1 byte | 1 byte | 1 byte | 1 byte | 1 byte | 1 byte | 1 byte | 1 byte |
+--------+--------+--------+--------+--------+--------+--------+--------+
|   Length indicator in big-endian  |
|         order (4 bytes)           |
+--------+--------+--------+--------+--...---+
|  Encrypted header exactly as many bytes    |
|        indicated by the prefix             |
+--------+--------+--------+--------+--...---+
|   Length indicator in big-endian  |
|         order (4 bytes)           |
+--------+--------+--------+--------+--...---+
|  Encrypted password record of exactly as   |
|   many bytes as indicated by the prefix    |
+--------+--------+--------+--------+--...---+
|   Length indicator in big-endian  |
|         order (4 bytes)           |
+--------+--------+--------+--------+--...---+
|  Encrypted password record of exactly as   |
|   many bytes as indicated by the prefix    |
+--------+--------+--------+--------+--...---+
              [ . . . ]

Security

   Memory used for storing sensitive information is cleared by setting it
   to zero upon de-allocation. This is default behavior of YAPET
   functions. However, YAPET cannot alter the way functions provided by
   crypto(3) and curses(3X) de-allocates memory. An attempt to make
   curses(3X) more secure is taken by calling wclear(3X) before calling
   delwin(3X), in the hope that it clears the memory associated with the
   curses window.

   YAPET uses setrlimit(2) to suppress the creation of core dumps. It also
   sets up signal handlers for SIGHUP, SIGINT, SIGQUIT, SIGTERM, and
   SIGKILL for doing a proper cleanup and clearing of allocated memory.

   Apart from memory clearing, YAPET locks the screen after ten minutes of
   inactivity.

   YAPET does not keep the password records decrypted in memory. It
   decrypts only the name of the password record in order to show it to
   the user. Password records are only decrypted for displaying and
   editing, when the user chooses to open a record.

References

   See also the code documentation that comes along with the source
   tarball of YAPET.
