1 files changed, 74 insertions, 0 deletions
diff --git a/debian/README.source b/debian/README.source
new file mode 100644
index 0000000..9063e67
--- /dev/null
+++ b/debian/README.source
@@ -0,0 +1,74 @@
+Shared library conversion
+-------------------------
+
+As explained in the unpatched README.md, upstream intends zxcvbn-c to
+be embedded in the source trees of projects that require it.  For the
+purposes of this Debian package, though, it is compiled as a shared
+library and as a static library.
+
+The word lists, *.txt in the source package, may be either
+  (a) compiled to a file zxcvbn.dict, or
+  (b) included in the object compiled from zxcvbn.c (in our case, in
+      libzxcvbn.so.* & libzxcvbn.a).
+This choice is made by means of the USE_DICT_FILE compiler macro.
+
+Contrary to what you might expect, method (a) does not permit swapping
+out zxcvbn.dict for a different file: CRCs for zxcvbn.dict are
+compiled into the object compiled from zxcvbn.c (in our case, in
+libzxcvbn.so.0 & libzxcvbn.a).
+
+So method (a) is useless when zxcvbn-c is compiled as a shared or
+static library.  Further, it complicates usage: a library user must
+call ZxcvbnInit() with the path to the immutable zxcvbn.dict, and
+later ZxcvbnUninit().
+
+Given the above facts about option (a), I have opted to use option (b)
+for this Debian package.  USE_DICT_FILE is unset.  Calls to
+ZxcvbnInit() and ZxcvbnUninit() are not required, and README.md has
+been patched accordingly.
+
+debian/missing-sources & debian/upstream/scripts
+------------------------------------------------
+
+words-female.txt, words-male.txt and words-surname.txt are not in
+their preferred format for modification.  The raw US census data, and
+the script to produce the words-*.txt files, have been included in the
+debian/missing-sources directory.
+
+Some of the other words-*.txt files were generated by scripts from
+HTML dumps of Wikipedia and Wiktionary articles.  If someone wanted to
+modify these word lists, it would be appropriate to modify the
+words-*.txt files directly, rather than those HTML dumps.
+Consequently, the HTML files have not been included.
+
+In case they are useful to someone, a copy of the scripts have been
+included in debian/upstream/scripts.  A separate directory has been
+used to indicate that these scripts have not been included in order to
+satisfy DFSG.
+
+DFSG repacking
+--------------
+
+In the 2.0 release of zxcvbn-c, upstream replaced words-10k-pass.txt
+with words-passwd.txt.  Both files are based on password lists
+produced by Mark Burnett.  words-passwd.txt is a list of the 47023
+most frequently-occurring passwords in a list of ten million
+passwords.  The list of ten million passwords was released by Burnett
+as an update to his original list of ten thousand passwords.
+
+While Burnett released words-10k-pass.txt under CC-BY-SA-3.0, his
+release of ten million passwords came with the following disclaimer:
+
+    BY DOWNLOADING THIS AUTHENTICATION DATA YOU AGREE NOT TO USE IT IN
+    ANY MANNER WHICH IS UNLAWFUL, ILLEGAL, FRAUDULENT OR HARMFUL, OR
+    IN CONNECTION WITH ANY UNLAWFUL, ILLEGAL, FRAUDULENT OR HARMFUL
+    PURPOSE OR ACTIVITY INCLUDING BUT NOT LIMITED TO FRAUD, IDENTITY
+    THEFT, OR UNAUTHORIZED COMPUTER SYSTEM ACCESS. THIS DATA IS ONLY
+    MADE AVAILABLE FOR ACADEMIC AND RESEARCH PURPOSES.
+
+This violates (at least) DFSG clause 6.  In repacking the upstream
+source, I have replaced words-passwd.txt with the old
+words-10k-pass.txt, and updated the makefile and test suite expected
+values accordingly.
+
+ -- Sean Whitton <spwhitton@spwhitton.name>, Tue, 29 Nov 2016 16:40:19 -0700