README.rdoc in affine-0.2.1 vs README.rdoc in affine-0.2.2

@@ -1,11 +1,38 @@
 = affine
 
-Simple affine cipher
+An affine cipher is a monoalphabetic substitution cipher, that uses
+math to generate the substitution alphabet based on three paramaters:
 
+[modulus] specifies how many different plaintexts and ciphertexts
+          are available.
+[a_key] multiplied against the plaintext. <b>Must be coprime with
+        the modulus.</b>
+[b_key] added to the multiplied plaintext.  No restrictions, but
+        it's modulus math, so making it larger than +modulus+ is
+        useless.
+
+These parameters are passed in order to the Cipher constructor:
+
     a = Affine::Cipher.new(2176782371, 65182241782, 123235151)
     r = rand(123235150) # (should be smaller then the modulus)
-    r == a.decipher(a.encipher r)
+    ciphertext = a.encipher r
+    # ciphertext = ((r * 65182241782) + 123235151) % 2176782371
+    r == a.decipher(ciphertext)
+
+== Giant security caveat
+
+Don't use this cipher for security related tasks.  I'm using it
+to make primary keys alphanumeric and less-predictable:
+http://github.com/bkerley/have-code/
+
+== How to crack it
+
+Know two plaintexts and their ciphertexts, put into linear system, solve.
+
+Know the relation between two plaintexts, predict future ciphertexts.
+
+Know lots of ciphertexts, guess it's English, solve like a cryptogram.
 
 == Copyright
 
 Copyright (c) 2009 Bryce Kerley. See LICENSE for details.