added Oracle 10 & 11 password hashes, with docs & UTs

6 files changed, 204 insertions, 6 deletions

diff --git a/docs/lib/passlib.hash.hex_digests.rst b/docs/lib/passlib.hash.hex_digests.rst
index ff4c00f..cbd1b1a 100644
--- a/docs/lib/passlib.hash.hex_digests.rst
+++ b/docs/lib/passlib.hash.hex_digests.rst
@@ -1,6 +1,6 @@
-==================================================================
-:samp:`passlib.hash.hex_{digest}` - Hexdecimal Standard Digests
-==================================================================
+==============================================================
+:samp:`passlib.hash.hex_{digest}` - Generic Hexdecimal Digests
+==============================================================
 
 .. currentmodule:: passlib.hash
 
diff --git a/docs/lib/passlib.hash.oracle10.rst b/docs/lib/passlib.hash.oracle10.rst
new file mode 100644
index 0000000..45dfa4b
--- /dev/null
+++ b/docs/lib/passlib.hash.oracle10.rst
@@ -0,0 +1,116 @@
+==================================================================
+:class:`passlib.hash.oracle10` - Oracle 10g password hash
+==================================================================
+
+.. currentmodule:: passlib.hash
+
+This class implements the hash algorithm used by the Oracle Database up to
+version 10g Rel.2. It was superceded by a newer algorithm in :class:`Oracle 11 <passlib.hash.oracle11>`.
+
+.. warning::
+
+    This hash is not secure, and should not be used for any purposes
+    besides manipulating existing Oracle 10 password hashes.
+
+.. warning::
+
+    This implementation has not been compared
+    very carefully against the official implementation or reference documentation,
+    and it's behavior may not match under various border cases.
+    It should not be relied on for anything but novelty purposes
+    for the time being.
+
+Usage
+=====
+This class can be used directly as follows (note that this class requires
+a username for all encrypt/verify operations)::
+
+    >>> from passlib.hash import oracle10 as or10
+
+    >>> #encrypt password using specified username
+    >>> h = or10.encrypt("password", "username")
+    >>> h
+    '872805F3F4C83365'
+
+    >>> or10.identify(h) #check if hash is recognized
+    True
+    >>> or10.identify('$1$3azHgidD$SrJPt7B.9rekpmwJwtON31') #check if some other hash is recognized
+    False
+
+    >>> or10.verify("password", h, "username") #verify correct password
+    True
+    >>> or10.verify("password", h, "somebody") #verify correct password w/ wrong username
+    False
+    >>> or10.verify("password", h, "username") #verify incorrect password
+    False
+
+Interface
+=========
+.. autoclass:: oracle10()
+
+Format
+======
+Oracle10 hashes all consist of a series of 16 hexidecimal digits,
+representing the resulting checksum.
+
+.. rst-class:: html-toggle
+
+Algorithm
+=========
+Oracle10 hashes are formed by:
+
+1. Concatenate the username and password together.
+2. Convert the result to upper case
+3. Encoding the result in a multi-byte format [#enc]_ such that ascii characters (eg: ``user``) are represented
+   with additional null bytes inserted (eg: ``\x00u\x00s\x00e\x00r``).
+4. Right-pad the result with null bytes to bring the size to an integer multiple of 8.
+   this is the final input string.
+5. The input string is then encoded using DES-CBC,
+   using the key ``\x01\x23\x45\x67\x89\xAB\xCD\xEF``,
+   and a null initialization vector.
+6. The input string is then run through DES-CBC a second time,
+   using the last block of ciphertext from step 5
+   as the key for the second round.
+7. The last block of ciphertext of step 6 is converted
+   to a hexdecimal string, and returned as the checksum.
+
+Security Issues
+===============
+This algorithm it not suitable for *any* use besides manipulating existing
+Oracle10 account passwords, due to the following flaws:
+
+* It's use of the username as a salt value means that common usernames
+  (eg ``system``) will occur more frequently as salts,
+  weakening the effectiveness of the salt in foiling pre-computed tables.
+
+* The fact that is it case insensitive, and simply concatenates the username
+  and password, greatly reduces the requirements for brute-force
+  or pre-computed attacks.
+
+* It's simplicity makes high-speed brute force attacks much more feasible.
+
+Deviations
+==========
+PassLib's implementation of the Oracle10g hash may deviate from the official
+implementation in unknown ways, as there is no official documentation.
+There is only one known issue:
+
+* Unicode Policy
+  Lack of testing (and test vectors) leaves it unclear
+  as to how Oracle 11g handles passwords containing non-7bit ascii.
+
+  In order to provide support for unicode strings,
+  PassLib will encode unicode passwords using ``utf-16-be``
+  before running them through Oracle11.
+  This behavior may be altered in the future, if further testing
+  reveals another behavior is more in line with the official representation.
+
+  This note applies as well to any provided username,
+  as they are run through the same policy.
+
+References
+==========
+.. [#enc] The exact encoded used in the algorithm is not clear from known references (see below).
+
+.. [#] Description of Oracle10g and Oracle11g algorithms -
+       `<http://www.notesbit.com/index.php/scripts-oracle/oracle-11g-new-password-algorithm-is-revealed-by-seclistsorg/>`_.
diff --git a/docs/lib/passlib.hash.oracle11.rst b/docs/lib/passlib.hash.oracle11.rst
new file mode 100644
index 0000000..0398ae6
--- /dev/null
+++ b/docs/lib/passlib.hash.oracle11.rst
@@ -0,0 +1,81 @@
+==================================================================
+:class:`passlib.hash.oracle11` - Oracle 11g password hash
+==================================================================
+
+.. currentmodule:: passlib.hash
+
+This class implements the hash algorithm introduced in version 11g of the Oracle Database.
+It supercedes the :class:`Oracle 10 <passlib.hash.oracle10>` password hash.
+
+.. warning::
+
+    This implementation has not been compared
+    very carefully against the official implementation or reference documentation,
+    and it's behavior may not match under various border cases.
+    It should not be relied on for anything but novelty purposes
+    for the time being.
+
+Usage
+=====
+PassLib provides an oracle11 class, which can be can be used directly as follows::
+
+    >>> from passlib.hash import oracle11 as or11
+
+    >>> #generate new salt, encrypt password
+    >>> h = or11.encrypt("password")
+    >>> h
+    'S:4143053633E59B4992A8EA17D2FF542C9EDEB335C886EED9C80450C1B4E6'
+
+    >>> or11.identify(h) #check if hash is recognized
+    True
+    >>> or11.identify('JQMuyS6H.AGMo') #check if some other hash is recognized
+    False
+
+    >>> or11.verify("password", h) #verify correct password
+    True
+    >>> or11.verify("secret", h) #verify incorrect password
+    False
+
+Interface
+=========
+.. autoclass:: oracle11(checksum=None, salt=None, strict=False)
+
+Format & Algorithm
+==================
+An example oracle11 hash (of the string ``password``)
+is ``'S:4143053633E59B4992A8EA17D2FF542C9EDEB335C886EED9C80450C1B4E6'``.
+
+An oracle11 hash string has the format :samp:`S:{checksum}{salt}`, where:
+
+* ``S:`` is the prefix used to identify oracle11 hashes
+  (as distinct from oracle10 hashes, which have no constant prefix).
+* :samp:`{checksum}` is 40 hexidecimal characters;
+  encoding a 160-bit checksum (``4143053633E59B4992A8EA17D2FF542C9EDEB335`` in the example).
+* :samp:`{salt}` is 20 hexidecimal characters;
+  providing a 80-bit salt (``C886EED9C80450C1B4E6`` in the example).
+
+The Oracle 11 hash has a very simple algorithm: The salt is decoded
+from it's hexidecimal representation into binary, and the SHA-1 digest
+of :samp:`{password}+{raw_salt}` is then encoded into hexidecimal, and returned as the checksum.
+
+Deviations
+==========
+PassLib's implementation of the Oracle11g hash may deviate from the official
+implementation in unknown ways, as there is no official documentation.
+There is only one known issue:
+
+* Unicode Policy
+  Lack of testing (and test vectors) leaves it unclear
+  as to how Oracle 11g handles passwords containing non-7bit ascii.
+
+  In order to provide support for unicode strings,
+  PassLib will encode unicode passwords using ``utf-8``
+  before running them through Oracle11.
+
+  This behavior may be altered in the future, if further testing
+  reveals another behavior is more in line with the official representation.
+
+References
+==========
+.. [#] Description of Oracle10g and Oracle11g algorithms -
+       `<http://www.notesbit.com/index.php/scripts-oracle/oracle-11g-new-password-algorithm-is-revealed-by-seclistsorg/>`_.
diff --git a/docs/lib/passlib.hash.postgres_md5.rst b/docs/lib/passlib.hash.postgres_md5.rst
index 8a3aa60..9cc7249 100644
--- a/docs/lib/passlib.hash.postgres_md5.rst
+++ b/docs/lib/passlib.hash.postgres_md5.rst
@@ -4,7 +4,7 @@
 
 .. currentmodule:: passlib.hash
 
-This class implemented the md5-based hash algorithm used by PostgreSQL to store
+This class implements the md5-based hash algorithm used by PostgreSQL to store
 it's user account passwords. This scheme was introduced in PostgreSQL 7.2;
 prior to this PostgreSQL stored it's password in plain text.
 
diff --git a/docs/lib/passlib.hash.rst b/docs/lib/passlib.hash.rst
index f163679..0611574 100644
--- a/docs/lib/passlib.hash.rst
+++ b/docs/lib/passlib.hash.rst
@@ -78,7 +78,8 @@ not seen outside those specific contexts:
     passlib.hash.mysql323
     passlib.hash.mysql41
     passlib.hash.postgres_md5
-
+    passlib.hash.oracle10
+    passlib.hash.oracle11
 
 Other Schemes
 -------------
diff --git a/docs/lib/passlib.hash.sun_md5_crypt.rst b/docs/lib/passlib.hash.sun_md5_crypt.rst
index 38ed905..e326672 100644
--- a/docs/lib/passlib.hash.sun_md5_crypt.rst
+++ b/docs/lib/passlib.hash.sun_md5_crypt.rst
@@ -1,5 +1,5 @@
 =================================================================
-:class:`passlib.hash.sun_md5_crypt` - Sun MD5 Crypt password hash
+:class:`passlib.hash.sun_md5_crypt` - Sun MD5 Crypt
 =================================================================
 
 .. currentmodule:: passlib.hash