Master Password

Master Password

So how does it work?

The theory behind Master Password is simple. The user remembers a single, secure password. The user only ever uses that password to log into the Master Password application. This master password is then used as a seed to generate a different password based on the name of the site to generate a password for.

The result is that each master password generates its own unique sequence of passwords for any site name. Since the only input data is the master password and the site name (along with a password counter, see below), there is no need for any kind of storage to recreate a site's password. All that's needed is the correct master password and the correct algorithm implementation. What that does for you is make it almost impossible to lose your passwords. It also makes it nearly impossible for hackers to steal your online identity.

The Algorithm

Master Password uses a stateless algorithm that relies solely on its implementation and the user's inputs. The user is expected to remember the following information:

In short, the algorithm is comprised of the following steps:

A note on types:

The Master Password

The user chooses a single master password, preferably sufficiently long to harden against brute-force attacks. Master Password recommends absurd three or four-word sentences as they're easily remembered and generally sufficiently high in entropy.

The application then creates a scrypt key derivative from the user's password. This process takes quite a bit of processing time and memory. This step exists to make brute-force attempts at guessing the master password from a given output password far more difficult, to practically infeasible, even for otherwise vulnerable password strings. 

                key   = scrypt( P, S, N, r, p, dkLen )
                where
                P     = master password
                S     = "com.lyndir.masterpassword" . name length . name
                N     = 32768
                r     = 8
                p     = 2
                dkLen = 64

The result is a 64-byte key derived from the user's master password. This key will be fed into the rest of the algorithm to produce output passwords that are as private to the user as his master password is.

Combining The Inputs

The theory behind Master Password requires that all inputs are given by the user. The two main inputs are the master password that we used to determine the key and the site's name. There is a third input value, the password counter, which is a 32-bit unsigned integer value that is used to salt the input. Initially, the password counter should be zero, but a user may specify a non-zero counter value in case he wants to force the algorithm to produce a new output password for the site.

These input values are combined in a byte array, separated by a single NUL byte. In order, the input values are the site name (UTF-8 decoded), the master key, and a salt (this is the password counter, a 32-bit unsigned integer in network byte order). The byte array is hashed using the SHA-1 algorithm to yield the seed as a result. 

                seed = hmac-sha256( key, "com.lyndir.masterpassword" . site name length . site name . counter )

Generating The Output

We now have a seed which is a sufficiently long seemingly-arbitrary string of bytes that is unique to the site and the user. This string of bytes, however, is not very useful for a user to use as a password. We have two additional problems that need to be solved: The output password must be easy for a user to read and copy, but it should also be compatible with most password policies.

Password policies are strict rules imposed by applications on their users, designed to limit the types of passwords these users are allowed to use with the application. Usually, these policies exist to force users into thinking about passwords with a healthy entropy. Often, they exist purely as a side-effect of bad password handling such as storing the clear-text passwords in a database.

Since the idea is that the output password can be used directly as a password to protect the user's account on the site, it needs to be able to pass the site's password policy. Master Password addresses this problem by introducing password types. Each password type describes what an output password must look like and maps to a set of templates. Templates describe the resulting output password using a series of characters that map to character groups of candidate output characters. A template has the same length as the output password it yields. Each character in the template maps to a specific character group. At each position of the output password, a character is chosen from the character group identified by the character in the template at the same position.

The following templates are defined:

By default, Master Password uses the Long Password type for any new passwords. The user is able to choose a different password type, which is normally only done if the site's password policy is incompatible with the output password produced by this type.

To create the create the output password, the bytes in the seed are encoded according to the template. The first seed byte is used to determine which of the type's templates to use for encoding an output password. We take the byte value of the first seed byte modulo the amount of templates set for the chosen password type and use the result as a zero-based index in the template list for the password type. 

                templates = [ "CvcvCvcvnoCvcv", "CvcvnoCvcvCvcv", "CvcvCvcvCvcvno", ... ]
                template  = templates[ seed[0] % count( templates ) ]

Now that we know what template to use for building our output password, all that's left is to iterate the template, and produce a character of password output for each step. When we iterate the template (index i), we look in the character group identified by the character (string passChars) in the template at index i.

The following character groups (passChars) are defined:

We use the seed's byte value at index i + 1 modulo the amount of characters in the character class to determine which character (passChar) in the class to use for the output password at index i. 

                passChar    = passChars[ seed[i + 1] % count( passChars ) ]
                passWord[i] = passChar