Update readme

1 files changed, 46 insertions, 24 deletions

diff --git a/README.md b/README.md
index e42b001..8403d8a 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,9 @@
 # zxcvbn-c
 This is a C/C++ implementation of the zxcvbn password strength estimation.
 
-The code is intended to be included as part of the source of a C/C++ program. Like the original this code is for character sets which use single byte characters primarily in the code range 0x20 to 0x7E.
+The code is intended to be included as part of the source of a C/C++ program. Like the
+original this code is for character sets which use single byte characters primarily in the
+code range 0x20 to 0x7E.
 
 The original coffee script version is available at 
  https://github.com/lowe/zxcvbn
@@ -11,24 +13,38 @@ https://tech.dropox.com/2012/04/zxcvbn-realistic-password-strength-estimation
 
 ##Building
 
-The makefile will build several test programs to test the code. It shows the steps needed to use the code in C and C++ programs, using the dictionary data read from file or included within the program executable.
-The makefile has only been tried on Linux using GCC version 4.8.4, but should be faily portable to other systems.
+The makefile will build several test programs to test the code. It shows the steps needed
+to use the code in C and C++ programs, using the dictionary data read from file or included
+within the program executable.
+The makefile has only been tried on Linux using GCC version 4.8.4, but should be faily
+portable to other systems.
 
-When dictionary data is included in your program's executable, the files `zxcvbn.c` , `zxcvbn.h` , `dict-src.h` are used in your program. 
+When dictionary data is included in your program's executable, the files `zxcvbn.c` ,
+`zxcvbn.h` , `dict-src.h` are used in your program. 
 
-When dictionary data is read from file, the files `zxcvbn.c` , `zxcvbn.h` ,  `dict-crc.h` and `zxcvbn.dict` are used in your program, compiled with `#define USE_DICT_FILE`. The CRC of the dictionary data file is written to `dict-crc.h` so your executable can detect corruption of the data.
+When dictionary data is read from file, the files `zxcvbn.c` , `zxcvbn.h` ,  `dict-crc.h`
+and `zxcvbn.dict` are used in your program, compiled with `#define USE_DICT_FILE`. The CRC
+of the dictionary data file is written to `dict-crc.h` so your executable can detect
+corruption of the data.
 
 Rename `zxcvbn.c` to `zxcvbn.cpp` (or whatever your compiler uses) to compile as C++.
 
-The `dict*.h` and `zxcvbn.dict` files are generated by the dictgen program compiled from dict-generate.cpp (see makefile for details).
+The `dict*.h` and `zxcvbn.dict` files are generated by the dictgen program compiled from
+dict-generate.cpp (see makefile for details).
 
 ##Using
 
-Initially call `ZxcvbnInit()` with the pathname of the `zxcvbn.dict` file. This can be omitted when dictionary data is included in the executable.
+Initially call `ZxcvbnInit()` with the pathname of the `zxcvbn.dict` file. This can be
+omitted when dictionary data is included in the executable.
 
-Call `ZxcvbnMatch()` with the password and optional user dictionary to get the entropy estimation and optional information on the password parts (which will need freeing with `ZxcvbnFreeInfo()` after use). Do this for each password to be tested, or as each character of it is entered into your program. The optional user dictionary can change between each call.
+Call `ZxcvbnMatch()` with the password and optional user dictionary to get the entropy
+estimation and optional information on the password parts (which will need freeing with
+`ZxcvbnFreeInfo()` after use). Do this for each password to be tested, or as each character
+of it is entered into your program. The optional user dictionary can change between each
+call.
 
-Finally call `ZxcvbnUninit()` to free the dictionary data from read from file. This can be omitted when dictionary data is included in the executable.
+Finally call `ZxcvbnUninit()` to free the dictionary data from read from file. This can be
+omitted when dictionary data is included in the executable.
 
 Review the test program in `test.c` for an example.
 
@@ -37,12 +53,24 @@ Review the test program in `test.c` for an example.
 
 The entropy calculated will sometimes differ from the original because of
 
-* A later version of the 10k password dictionary is used, so some words have different entropy.
-* The UK keyboard layout is also included, so there are additional spacial sequences, e.g. **;'#** is a spacial sequence.
-* Additional date formats are included e.g. two digit years can be used for dates.
-* Characters with ASCII code < 0x20 or > 0x7E add 100 to the cardinality of the password character set.
-* Dijktra's path searching algorithm is used to combine parts of the entered password. This can result in the found components of the password being combined differently than the original coffee script. E.g. the password **bcderty**
-is combined by the original coffee script as **b** (4.7 bits) + **cderty** (14.9 bits) to give total entropy of 19.6 bits. This implementation combines it as **bcde** (6.7 bits) + **rty** (9.8 bits) to give 16.5 bits.
+* The UK keyboard layout is also included, so there are additional spacial sequences, e.g.
+**;'#** is a spacial sequence.
+* The different character classes in a password are taken into account when calculating the
+strength of brute-force matches.
+* Dijktra's path searching algorithm is used to combine parts of the entered password. This
+can result in the found parts of the password being combined differently than the
+original coffee script. E.g. the password **passwordassword**
+is combined by the original coffee script as **p** (3.5 bits) + **asswordassword** (12.6
+bits) + multiple part allowance (1.0bit) to give total entropy of 17.1 bits. This
+implementation combines it as **password** (1.0 bit) + **assword** (11.6 bits) + multiple
+part allowance (1.0bit) to give 13.6 bits.
+* For multi part passwords the original coffee script version multiplies the number of
+guesses needed by the factorial of the number of parts. This is not possible in this
+version as Dijktra's algorithm is used. Instead one bit entropy is added for the part at the
+end of the password, 1.7 bits for each part in the middle of a password and nothing
+for the part at the beginning. This gives similar results compared to the coffee script
+version when there are 4 or less parts, but will differ significantly when there are many
+parts (which is likely to be a rare occurrence).
 
 
 ##References
@@ -50,15 +78,9 @@ is combined by the original coffee script as **b** (4.7 bits) + **cderty** (14.9
 The original coffee-script version is available at 
  https://github.com/lowe/zxcvbn
 
-10000 Most popular Passwords is from 
-https://xato.net/passwords/more-top-worst-passwords by Mark Burnett (this is a later version than the one used by the original coffee script version).
+The dictionary words are taken from the original coffee script version.
 
-The list of names and their popularity is from the US year 2000 census data, as used in the original coffee script version.
-
-40k words are from movies and TV shows, obtained from
-http://en.wiktionary.org/wiki/Wiktionary:Frequency_lists as in the original coffee script version.
-
-Dictionary trie encoding (used for by the word lookup code) based on idea from the Caroline Word Graph from
+Dictionary trie encoding (used for by the word lookup code) based on idea from the Caroline
+Word Graph from
 http://www.pathcom.com/~vadco/cwg.html
 
-