updated & documentated passlib.hosts module

2 files changed, 141 insertions, 68 deletions

diff --git a/docs/lib/passlib.hosts.rst b/docs/lib/passlib.hosts.rst
index 771f8b7..e702ebe 100644
--- a/docs/lib/passlib.hosts.rst
+++ b/docs/lib/passlib.hosts.rst
@@ -3,29 +3,65 @@
 ============================================
 
 .. module:: passlib.hosts
-    :synopsis: frontend for encrypting & verifying passwords on various operating systems.
+    :synopsis: encrypting & verifying operating system passwords
 
-Contexts
-========
-This module provides some pre-configured :class:`CryptContext` instances,
-tailor to the hashes supported on various unix systems.
+This module provides :class:`!CryptContext` instances for encrypting & verifying password hashes
+tied to user accounts of various operating systems. It currently
+primarily centered around Linux & BSD unix variants.
+(For details about how to *use* a :class:`!CryptContext` instance,
+see the documentation for the :class:`CryptContext` class itself).
+
+Unix-Specific Contexts
+======================
+
+Interface
+---------
+PassLib provides :class:`!CryptContext` instances
+for the following Unix variants:
 
 .. object:: linux_context
 
-    this should recognize the hashes used on most linux systems:
-    :class:`~passlib.hash.des_crypt`,
-    :class:`~passlib.hash.md5_crypt`,
-    :class:`~passlib.hash.sha256_crypt`, and
-    :class:`~passlib.hash.sha512_crypt` (used as the default).
+    context instance which recognizes hashes used
+    by the majority of Linux distributions.
+    encryption defaults to :class:`!sha512_crypt`.
+
+.. object:: freebsd_context
+
+    context instance which recognizes all hashes used by FreeBSD 8.
+    encryption defaults to :class:`!bcrypt`.
+
+.. object:: netbsd_context
+
+    context instance which recognizes all hashes used by NetBSD.
+    encryption defaults to :class:`!bcrypt`.
+
+.. object:: openbsd_context
+
+    context instance which recognizes all hashes used by OpenBSD.
+    encryption defaults to :class:`!bcrypt`.
+
+.. note::
+
+    Unforunately, there is currently no reliable way to detect
+    the exact policy used on the above systems,
+    so each of the above contexts defaults to using the strongest supported scheme.
 
-.. object:: bsd_context
+Supported Schemes
+-----------------
+The linux and bsd contexts above support the following schemes:
 
-    this should recognize the hashes used on most bsd systems:
-    :class:`~passlib.hash.des_crypt`,
-    :class:`~passlib.hash.ext_des_crypt`,
-    :class:`~passlib.hash.nthash`,
-    :class:`~passlib.hash.md5_crypt`,
-    :class:`~passlib.hash.bcrypt` (used as the default).
+==================================== =========== =========== =========== ===========
+Scheme                               Linux       FreeBSD     NetBSD      OpenBSD
+==================================== =========== =========== =========== ===========
+:class:`~passlib.hash.nthash`                    y
+:class:`~passlib.hash.des_crypt`     y           y           y           y
+:class:`~passlib.hash.bsdi_crypt`                            y           y
+:class:`~passlib.hash.md5_crypt`     y           y           y           y
+:class:`~passlib.hash.bcrypt`                    y           y           y
+:class:`~passlib.hash.sha1_crypt`                            y
+:class:`~passlib.hash.sha256_crypt`  y
+:class:`~passlib.hash.sha512_crypt`  y
+==================================== =========== =========== =========== ===========
 
 .. note::
 
@@ -36,22 +72,54 @@ tailor to the hashes supported on various unix systems.
     This same handler will also recognize an empty string as being a wildcard password.
 
 Usage
-=====
-
-.. todo::
-
-    show usage example
-
+-----
+A quick usage example, using the :data:`!linux_context` instance::
+
+    >>> from passlib.hosts import linux_context
+    >>> hash = linux_context.encrypt("password")
+    >>> hash
+    '$6$rounds=31779$X2o.7iqamZ.bAigR$ojbo/zh6sCmUuibhM7lnqR4Vy0aB3xGZXOYVLgtTFgNYiXaTNn/QLUz12lDSTdxJCLXHzsHiWCsaryAlcbAal0'
+    >>> linux_context.verify("password", hash)
+    True
+    >>> linux_context.identify(hash)
+    'sha512_crypt'
+    >>> linux_context.encrypt("password", scheme="des_crypt")
+    '2fmLLcoHXuQdI'
+    >>> linux_context.identify('2fmLLcoHXuQdI')
+    'des_crypt'
+
+Current-Host Contexts
+=====================
+.. object:: host_context
+
+    PassLib provides this object, which will dynamically be an alias
+    for one of the above context instances (based on ``sys.platform``).
+    This can be used in conjunction with stdlib's :mod:`!spwd` module
+    to verify user passwords on the local system::
+
+        >>> #NOTE/WARNING: this example requires running as root on most systems.
+        >>> import spwd, os
+        >>> from passlib.hosts import host_context
+        >>> hash = spwd.getspnam(os.environ['USER']).sp_pwd
+        >>> host_context.verify("toomanysecrets", hash)
+        True
+
+    On non-unix systems, and unix systems whose platform isn't recognized
+    properly by passlib, this will fall back to a context which
+    recognizes no hash schemes besides :class:`unix_fallback`.
 
 .. _modular-crypt-format:
 
 Modular Crypt Format
 ====================
+
+A side note regarding password hashes beginning with :samp:`${identifier}$`:
+
 A vast majority of the schemes used on unix systems (and supported by this library)
 follow the "Modular Crypt Format", introduced around the time :class:`~passlib.hash.md5_crypt` was developed.
 This scheme allows hashes generates by multiple schemes to co-exist within a database,
-by requiring that all hash string begin with a unique prefix ``$identifier$``;
-where ``identifier`` is a short alphanumeric string globally identifying
+by requiring that all hash string begin with a unique prefix :samp:`${identifier}$`;
+where :samp:`{identifier}` is a short alphanumeric string globally identifying
 hashes generated by that algorithm.
 
 While not part of the specification, most modular crypt -compatible hashes
@@ -66,21 +134,3 @@ this can be violated on some systems if the user intervenes.
 .. note::
     :class:`passlib.hash.des_crypt` and :class:`passlib.hash.bsdi_crypt`
     do not follow this protocol, since they predate it by many years.
-
-OS Format Support
-=================
-The following table details which operating systems
-are known to support which schemes:
-
-==================================== =========== =========== =========== ===========
-Scheme                               Linux       FreeBSD     NetBSD      OpenBSD
-==================================== =========== =========== =========== ===========
-:class:`~passlib.hash.nthash`                    y
-:class:`~passlib.hash.des_crypt`     y           y           y           y
-:class:`~passlib.hash.bsdi_crypt`                            y           y
-:class:`~passlib.hash.md5_crypt`     y           y           y           y
-:class:`~passlib.hash.bcrypt`                    y           y           y
-:class:`~passlib.hash.sha1_crypt`                            y
-:class:`~passlib.hash.sha256_crypt`  y
-:class:`~passlib.hash.sha512_crypt`  y
-==================================== =========== =========== =========== ===========
diff --git a/passlib/hosts.py b/passlib/hosts.py
index b6a3d03..ac19b70 100644
--- a/passlib/hosts.py
+++ b/passlib/hosts.py
@@ -2,65 +2,88 @@
 #=========================================================
 #imports
 #=========================================================
+#core
+import sys
 #pkg
 from passlib.context import CryptContext
 #local
 __all__ = [
-    "default_context",
     "linux_context", "linux2_context",
-    "bsd_context",
-        "openbsd_context",
-        "netbsd_context",
-        "freebsd_context",
-
+    "openbsd_context",
+    "netbsd_context",
+    "freebsd_context",
+    "host_context",
 ]
 
 #=========================================================
-#build default context objects
+#linux support
 #=========================================================
 
-#default context for quick use.. recognizes common algorithms, uses SHA-512 as default
-#er... should we promote bcrypt as default?
-##default_context = CryptContext(["sha512_crypt",  "sha256_crypt", "bcrypt", "md5_crypt", "des_crypt", "unix_disabled" ])
+#known platform names - linux2
+
+linux_context = linux2_context = CryptContext(
+    schemes = [ "sha512_crypt", "sha256_crypt", "md5_crypt",
+               "des_crypt", "unix_fallback" ],
+    deprecated = [ "des_crypt" ],
+    )
 
 #=========================================================
-#some general os-context helpers (these may not match your os policy exactly, but are generally useful)
+#bsd support
 #=========================================================
 
-
-#referencing linux shadow...
-# linux - des,md5, sha256, sha512
-
-linux_context = linux2_context = CryptContext([ "sha512_crypt", "sha256_crypt", "md5_crypt", "des_crypt", "unix_fallback" ])
+#known platform names -
+#   freebsd2
+#   freebsd3
+#   freebsd4
+#   freebsd5
+#   freebsd6
+#   freebsd7
+#
+#   netbsd1
 
 #referencing source via -http://fxr.googlebit.com
 # freebsd 6,7,8 - des, md5, bcrypt, nthash
 # netbsd - des, ext, md5, bcrypt, sha1
 # openbsd - des, ext, md5, bcrypt
-bsd_context = CryptContext(["bcrypt",  "md5_crypt", "bsdi_crypt", "des_crypt", "nthash", "unix_fallback" ])
+
 freebsd_context = CryptContext([ "bcrypt", "md5_crypt", "nthash", "des_crypt", "unix_fallback" ])
 openbsd_context = CryptContext([ "bcrypt", "md5_crypt", "bsdi_crypt", "des_crypt", "unix_fallback" ])
 netbsd_context = CryptContext([ "bcrypt", "sha1_crypt", "md5_crypt", "bsdi_crypt", "des_crypt", "unix_fallback" ])
 
+#=========================================================
+#current host
+#=========================================================
+
+#context we fall back to if not on a unix system,
+#or if we don't recognize platform
+fallback_context = CryptContext(["unix_fallback"])
+
+if sys.platform == "linux2":
+    host_context = linux2_context
+elif sys.platform.startswith("freebsd"):
+    host_context = freebsd_context
+elif sys.platform.startswith("netbsd"):
+    host_context = netbsd_context
+elif sys.platform.startswith("openbsd"):
+    host_context = openbsd_context
+else:
+    host_context = fallback_context
+
+#=========================================================
+#other platforms
+#=========================================================
 
+#known platform strings -
 #aix3
 #aix4
 #atheos
 #beos5
 #darwin
-#freebsd2
-#freebsd3
-#freebsd4
-#freebsd5
-#freebsd6
-#freebsd7
 #generic
 #hp-ux11
 #irix5
 #irix6
-#linux2
 #mac
-#netbsd1
 #next3
 #os2emx
 #riscos