1 files changed, 111 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..655be3c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,111 @@
+## What is JP-Hash?
+
+JP-Hash is an algorithm which converts any piece of text or other datum into a
+textual digest, which has the following properties:
+
+* length between 8 and 21 characters.
+
+* consists mostly of lower-case letters.
+
+* includes one digit.
+
+* includes one non-alphanumeric character from the set
+  `!`, `#`, `@`, `$`, `%`, `^`, `&`, `*`, `?` and `/`.
+
+By amazing coincidence, these requirements are very similar to
+common requirements imposed on people are creating or
+changing a password.
+
+Additionally:
+
+* The digest string is based on combinations of vowels from the Japanese
+  language, written in romanized form. This means that many of the digests are
+  memorable and pronounceable, and have a vibe to them that is pleasing to
+  enthusiasts for things Japanese.
+
+## How do I get it?
+
+See the reference implementation source files. Code is given in
+TXR Lisp, C and Javascript for the browser as well as Node.js.
+
+The self-contained <code>jp-hash.html</code> file should load in any browser,
+providing a simple UI.
+
+## What are the details of the algorithm?
+
+1. First, the input is hashed via the standard SHA256 sum.
+
+2. Next, the first 18 bytes of the digest are interpreted as an array of 9
+   (nine) 16-bit words, little endian.  This array is referred to as `word[0]`
+   through `word[8]`.
+
+3. Six pseudo-Japanese syllables are derived from `word[0]` through `word[5]`
+   as follows: each of these word values is reduced to the remainder modulo 97.
+   Then, the remainder is used as an index into the following array of 97
+   strings.  The first letter of the first syllable is then capitalized.
+
+```
+["a", "i", "u", "e", "o", "ya", "yu", "yo", "wa",
+ "ka", "ki", "ku", "ke", "ko", "ga", "gi", "gu", "ge", "go",
+ "sa", "shi", "su", "se", "so", "za", "ji", "zu", "ze", "zo",
+ "ta", "chi", "tsu", "te", "to", "da", "de", "do",
+ "na", "ni", "nu", "ne", "no", "ha", "hi", "fu", "he", "ho",
+ "pa", "pi", "pu", "pe", "po", "ba", "bi", "bu", "be", "bo",
+ "ma", "mi", "mu", "me", "mo", "ra", "ri", "ru", "re", "ro",
+ "kya", "kyu", "kyo", "gya", "gyu", "gyo", "sha", "shu", "sho",
+ "ja", "ju", "jo", "cha", "chu", "cho", "nya", "nyu", "nyo",
+ "hya", "hyu", "hyo", "pya", "pyu", "pyo", "bya", "byu", "byo",
+ "mya", "myu", "myo", "rya", "ryu", "ryo"]
+```
+
+4. A digit is chosen using the modulo 10 remainder of `word[6]` as an index
+   into the digits `0` through `9`.
+
+5. Similarly, a symbol is chosen using the modulo 10 remainder of `word[7]` as
+   an index into the aforementioned list `!`, `#`, `@`, `$`, `%`, `^`, `&`,
+   `*`, `?` and `/`.
+
+6. The modulo 8 value of `word[8]` is used to select eight cases (0 to 7) for
+   combining the above values into an output string.  The last four of these
+   cases insert the `n` (letter n) character into certain places of the string.
+   The details are in the reference implementation.
+
+## How many JP-Hash digests are there?
+
+Since there are six syllables chosen from a set of 92, plus two characters each
+from a set of ten, the initial steps yield a space of 83,297,200,492,900 (83.3
+(American) trillion). The 8 cases in step (6) all yield distinct results, and
+so multiply the space eight-fold to 666,377,603,943,200 possibilities (666.4
+trillion).
+
+## Are JP-Hash digests secure for password use?
+e
+JP-Hash is not advertised as being for a specific purpose. In a security
+setting, each user must perform their own analysis to understand the security
+risks of using any tool in certain ways and with certain inputs.
+
+## Examples
+
+These examples come from the `testvec` file.
+
+```
+a --> Mina4gai@gashan
+y --> Shaba%megyu2shize
+Mike --> !Tosuda2bukyochon
+Romeo --> Potsun&gaso5machi
+Sierra --> Nodon&yanu6zuchi
+Tango --> Gyoda#hosa6segi
+Whiskey --> Muji?pyuna6gyage
+sashimi --> Izu0gyubya/gyumyu
+ramen --> Byumi$betsu0nyohe
+soba --> Arushin^hyapyuryu2
+futon --> Kyoriton#kyaseku1
+```
+
+## License
+
+The JP-Hash reference code is offered under the a one-clause variant of the BSD
+license. See the copyright headers in the source files.
+
+If you publish altered versions of this algorithm, please don't call it
+JP-Hash, thanks! If it doesn't pass the `testvec`, it isn't JP-Hash.