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:

• The master password (eg. pink fluffy door frame):
  This is a secret that the user shares with nobody.
• The site name (eg. apple.com):
  The user chooses a name for each site. Its domain name is an ideal choice, since it needn't necessarily be remembered.
• The site's password counter (default: 0):
  This is an integer that can be incremented when the user needs a new password for the site.
• The site's password type (default: Long Password):
  This type determines the format of the output password. It can be changed if the site's password policy does not accept passwords of this format.

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

• Determining the master key
• Determining the template seed
• Encoding a user-friendly password

A note on types:

• Any character string is UTF-8 de- or encoded, depending on context.
• Any number is converted to 32-bit network byte order.

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 their 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. 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, the master key, and a counter. The byte array is hashed using the HMAC-SHA-256 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 type in using a keyboard or smartphone, but it should also be compatible with most site's 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:

• Type: Maximum Security Password

  • anoxxxxxxxxxxxxxxxxx
  • axxxxxxxxxxxxxxxxxno

• Type: Long Password

  • CvcvnoCvcvCvcv
  • CvcvCvcvnoCvcv
  • CvcvCvcvCvcvno
  • CvccnoCvcvCvcv
  • CvccCvcvnoCvcv
  • CvccCvcvCvcvno
  • CvcvnoCvccCvcv
  • CvcvCvccnoCvcv
  • CvcvCvccCvcvno
  • CvcvnoCvcvCvcc
  • CvcvCvcvnoCvcc
  • CvcvCvcvCvccno
  • CvccnoCvccCvcv
  • CvccCvccnoCvcv
  • CvccCvccCvcvno
  • CvcvnoCvccCvcc
  • CvcvCvccnoCvcc
  • CvcvCvccCvccno
  • CvccnoCvcvCvcc
  • CvccCvcvnoCvcc
  • CvccCvcvCvccno

• Type: Medium Password

  • CvcnoCvc
  • CvcCvcno

• Type: Short Password

  • Cvcn

• Type: Basic Password

  • aaanaaan
  • aannaaan
  • aaannaaa

• Type: PIN

  • nnnn

Where each of the letters above expand any of the characters in their respective character group:

• Template character: V

  • AEIOU

• Template character: C

  • BCDFGHJKLMNPQRSTVWXYZ

• Template character: v

  • aeiou

• Template character: c

  • bcdfghjklmnpqrstvwxyz

• Template character: A (= V . C)

  • AEIOUBCDFGHJKLMNPQRSTVWXYZ

• Template character: a (= V . v . C . c)

  • AEIOUaeiouBCDFGHJKLMNPQRSTVWXYZbcdfghjklmnpqrstvwxyz

• Template character: n

  • 0123456789

• Template character: o

  • @&%?,=[]_:-+*$#!'^~;()/.

• Template character: X (= a . n . o)

  • AEIOUaeiouBCDFGHJKLMNPQRSTVWXYZbcdfghjklmnpqrstvwxyz0123456789@&%?,=[]_:-+*$#!'^~;()/.

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

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