diff options
Diffstat (limited to 'docs/lib')
| -rw-r--r-- | docs/lib/passlib.apache.rst | 1 | ||||
| -rw-r--r-- | docs/lib/passlib.apps.rst | 108 | ||||
| -rw-r--r-- | docs/lib/passlib.hash.mysql323.rst | 2 | ||||
| -rw-r--r-- | docs/lib/passlib.hash.mysql41.rst | 2 | ||||
| -rw-r--r-- | docs/lib/passlib.hash.oracle11.rst | 10 | ||||
| -rw-r--r-- | docs/lib/passlib.hash.postgres_md5.rst | 2 | ||||
| -rw-r--r-- | docs/lib/passlib.servers.rst | 53 |
7 files changed, 119 insertions, 59 deletions
diff --git a/docs/lib/passlib.apache.rst b/docs/lib/passlib.apache.rst index b9728a9..0826246 100644 --- a/docs/lib/passlib.apache.rst +++ b/docs/lib/passlib.apache.rst @@ -3,6 +3,7 @@ ============================================= .. module:: passlib.apache + :synopsis: reading/writing htpasswd & htdigest files This module provides utilities for reading and writing Apache's htpasswd and htdigest files; though the use of two helper classes. diff --git a/docs/lib/passlib.apps.rst b/docs/lib/passlib.apps.rst new file mode 100644 index 0000000..8b7e422 --- /dev/null +++ b/docs/lib/passlib.apps.rst @@ -0,0 +1,108 @@ +================================================================== +:mod:`passlib.apps` - Helpers for various applications +================================================================== + +.. module:: passlib.apps + :synopsis: encrypting & verifying passwords used in sql servers and other applications + +This lists a number of :class:`!CryptContext` instances that are predefined +by PassLib for easily handling the multiple formats used by various applications. +(For details about how to *use* a :class:`!CryptContext` instance, +see the documentation for the :class:`CryptContext` class itself). + +.. _quickstart-custom-applications: + +Custom Applications +=================== +.. object:: custom_app_context + + This :class:`!CryptContext` object is provided for new python applications + to quickly and easily add password hashing support. + It offers: + + * Support for :class:`~passlib.hash.sha256_crypt` and :class:`~passlib.hash.sha512_crypt` + * Defaults to SHA256-Crypt under 32 bit systems; SHA512-Crypt under 64 bit systems. + * Comes pre-configured with strong rounds settings. + + For applications which want to quickly add a password hash, + all they need to do is the following:: + + >>> #import the context under an app-specific name (so it can easily be replaced later) + >>> from passlib.apps import custom_app_context as pwd_context + + >>> #encrypting a password... + >>> hash = pwd_context.encrypt("somepass") + + >>> #verifying a password... + >>> ok = pwd_context.verify("somepass", hash) + + >>> #[optional] encrypting a password for an admin account - uses stronger settings + >>> hash = pwd_context.encrypt("somepass", category="admin") + + For applications which started using this preset, but whose needs + have grown beyond it, it is recommended to create your own CryptContext + instance; the configuration used to create this object can be a good starting point. + +LDAP +==== +.. object:: ldap_context + + This object provides a pre-configured :class:`!CryptContext` instance + for handling LDAPv2 password hashes. It recognizes all + the formats in the :doc:`ldap_digests listing <passlib.hash.ldap_digests>`. + + It defaults to using the ``{SSHA}`` password hash. + For times when there should be another default, using code such as the following:: + + >>> from passlib.apps import ldap_context + >>> ldap_context = ldap_context.replace(default="ldap_salted_md5") + + >>> #the new context object will now default to {SMD5}: + >>> ldap_context.encrypt("password") + '{SMD5}T9f89F591P3fFh1jz/YtW4aWD5s=' + + .. warning:: + + PassLib does not currently support the ``{CRYPT}`` password hash method. + +MySQL +===== +This module provides two pre-configured :class:`!CryptContext` instances +for handling MySQL user passwords: + +.. object:: mysql_context + + This object should recognize the new :class:`~passlib.hash.mysql41` hashes, + as well as any legacy :class:`~passlib.hash.mysql323` hashes. + + It defaults to mysql41 when generating new hashes. + + This should be used with MySQL version 4.1 and newer. + +.. object:: mysql3_context + + This object is for use with older MySQL deploys which only recognize + the :class:`~passlib.hash.mysql323` hash. + + This should be used only with MySQL version 3.2.3 - 4.0. + +PostgreSQL +========== +.. object:: postgres_context + + This object should recognize password hashes stores in PostgreSQL's ``pg_shadow`` table; + which are all assumed to follow the :class:`~passlib.hash.postgres_md5` format. + + Note that the username must be provided whenever encrypting or verifying a postgres hash:: + + >>> from passlib.apps import postgres_context + + >>> #encrypting a password... + >>> postgres_context.encrypt("somepass", user="dbadmin") + 'md578ed0f0ab2be0386645c1b74282917e7' + + >>> #verifying a password... + >>> postgres_context.verify("somepass", 'md578ed0f0ab2be0386645c1b74282917e7', user="dbadmin") + True + >>> postgres_context.verify("wrongpass", 'md578ed0f0ab2be0386645c1b74282917e7', user="dbadmin") + False diff --git a/docs/lib/passlib.hash.mysql323.rst b/docs/lib/passlib.hash.mysql323.rst index a28dda0..a94d197 100644 --- a/docs/lib/passlib.hash.mysql323.rst +++ b/docs/lib/passlib.hash.mysql323.rst @@ -19,7 +19,7 @@ hash algorithm was introduced (see :class:`~passlib.hash.mysql41`). Usage ===== -Users will most likely find the frontends provided by :mod:`passlib.servers` +Users will most likely find the frontends provided by :mod:`passlib.apps` to be more useful than accessing this class directly. That aside, this class can be used as follows:: diff --git a/docs/lib/passlib.hash.mysql41.rst b/docs/lib/passlib.hash.mysql41.rst index 745d1d1..eaaf89e 100644 --- a/docs/lib/passlib.hash.mysql41.rst +++ b/docs/lib/passlib.hash.mysql41.rst @@ -18,7 +18,7 @@ used by MySQL, and is still in active use under MySQL 5. Usage ===== -Users will most likely find the frontends provided by :mod:`passlib.servers` +Users will most likely find the frontends provided by :mod:`passlib.apps` to be more useful than accessing this class directly. That aside, this class can be used in the same manner as :class:`~passlib.hash.mysql323`. diff --git a/docs/lib/passlib.hash.oracle11.rst b/docs/lib/passlib.hash.oracle11.rst index 9dc0c8b..84e6ee6 100644 --- a/docs/lib/passlib.hash.oracle11.rst +++ b/docs/lib/passlib.hash.oracle11.rst @@ -42,15 +42,19 @@ Interface Format & Algorithm ================== -An example oracle11 hash (of the string ``password``) -is ``'S:4143053633E59B4992A8EA17D2FF542C9EDEB335C886EED9C80450C1B4E6'``. +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). + encoding a 160-bit checksum. + + (``4143053633E59B4992A8EA17D2FF542C9EDEB335`` in the example) + * :samp:`{salt}` is 20 hexidecimal characters; providing a 80-bit salt (``C886EED9C80450C1B4E6`` in the example). diff --git a/docs/lib/passlib.hash.postgres_md5.rst b/docs/lib/passlib.hash.postgres_md5.rst index d42e258..a04f8b5 100644 --- a/docs/lib/passlib.hash.postgres_md5.rst +++ b/docs/lib/passlib.hash.postgres_md5.rst @@ -15,7 +15,7 @@ prior to this PostgreSQL stored it's password in plain text. Usage ===== -Users will most likely find the frontend provided by :mod:`passlib.servers` +Users will most likely find the frontend provided by :mod:`passlib.apps` to be more useful than accessing this class directly. That aside, this class can be used directly as follows:: diff --git a/docs/lib/passlib.servers.rst b/docs/lib/passlib.servers.rst deleted file mode 100644 index fe98265..0000000 --- a/docs/lib/passlib.servers.rst +++ /dev/null @@ -1,53 +0,0 @@ -================================================================== -:mod:`passlib.servers` - Contexts for SQL Database & Other Servers -================================================================== - -.. module:: passlib.servers - :synopsis: frontend for encrypting & verifying passwords used in various sql databases - -PostgreSQL -========== -This module provides a single pre-configured :class:`CryptContext` instance -which should be capable of recognizing passwords in modern postgres systems: - -.. object:: postgres_context - - This object should recognize password hashes stores in postgres' pg_shadow table. - it can recognize :class:`~passlib.hash.postgres_md5` hashes, - as well as plaintext hashes. - It defaults to postgres_md5 when generating new hashes. - - note that the username must be provided whenever encrypting or verifying a postgres hash. - -MySQL -===== -This module provides two pre-configured :class:`CryptContext` instances -for handling MySQL user passwords: - -.. object:: mysql_context - - This object should recognize the new :class:`~passlib.hash.mysql41` hashes, - as well as any legacy :class:`~passlib.hash.mysql323` hashes. - It defaults to mysql41 when generating new hashes. - - This should be used for all mysql versions from 4.1 onward. - -.. object:: mysql3_context - - This object is for use with older MySQL deploys which only recognize - the :class:`~passlib.hash.mysql323` hash. - - This should be used only for mysql version 3 systems. - -LDAP -==== -This module provides a pre-configured :class:`!CryptContext` instance -for handling LDAPv2 password hashes: - -.. object:: ldap_context - - This object is for use when reading LDAP password hashes. - -.. warning:: - - PassLib does not currently support the ``{CRYPT}`` password hash method. |