diff options
| author | Eli Collins <elic@assurancetechnologies.com> | 2013-12-27 13:49:41 -0500 |
|---|---|---|
| committer | Eli Collins <elic@assurancetechnologies.com> | 2013-12-27 13:49:41 -0500 |
| commit | bcdf0cd2a97fa8dfb4cc06352faa0934ccbf236b (patch) | |
| tree | 36c3549889c3d8bf8f531b30bb588920c23cc681 /docs | |
| parent | 10ddd0c4bf75c21bdd75a3cb0781f020147778b3 (diff) | |
| download | passlib-bcdf0cd2a97fa8dfb4cc06352faa0934ccbf236b.tar.gz | |
massive cleanup of documentation typos, thanks to Thomas Waldmann (issue 27, comment 7) (transplant of r1f5b8860b743 from default branch)
Diffstat (limited to 'docs')
50 files changed, 165 insertions, 165 deletions
diff --git a/docs/conf.py b/docs/conf.py index 61f9b5a..190f564 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -51,7 +51,7 @@ extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.todo', - # add autdoc support for ReST sections in class/function docstrings + # add autodoc support for ReST sections in class/function docstrings 'cloud_sptheme.ext.autodoc_sections', # adds extra ids & classes to genindex html, for additional styling diff --git a/docs/install.rst b/docs/install.rst index 6f9eb38..df99878 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -99,7 +99,7 @@ you will need to: 2. Install the `Cloud Sphinx Theme <http://packages.python.org/cloud_sptheme>`_ (1.5 or newer). 3. Download the Passlib source 4. From the Passlib source directory, run :samp:`python setup.py build_sphinx`. -5. Once Sphinx completes it's run, point a web browser to the file at :samp:`{SOURCE}/build/sphinx/html/index.html` +5. Once Sphinx completes its run, point a web browser to the file at :samp:`{SOURCE}/build/sphinx/html/index.html` to access the Passlib documentation in html format. 6. Alternately, steps 4 & 5 can be replaced by running :samp:`python setup.py docdist`, which will build a zip file of the documentation in :samp:`{SOURCE}/dist`. diff --git a/docs/lib/passlib.apache.rst b/docs/lib/passlib.apache.rst index 60cb954..4fb89a7 100644 --- a/docs/lib/passlib.apache.rst +++ b/docs/lib/passlib.apache.rst @@ -21,7 +21,7 @@ htpasswd and htdigest files; though the use of two helper classes. Htpasswd Files ============== The :class:`!HTpasswdFile` class allows managing of htpasswd files. -A quick summary of it's usage:: +A quick summary of its usage:: >>> from passlib.apache import HtpasswdFile diff --git a/docs/lib/passlib.apps.rst b/docs/lib/passlib.apps.rst index c10496f..e82d81b 100644 --- a/docs/lib/passlib.apps.rst +++ b/docs/lib/passlib.apps.rst @@ -223,7 +223,7 @@ The following contexts are available for reading Roundup password hash fields: .. data:: roundup15_context Roundup 1.4.17 adds support for :class:`~passlib.hash.ldap_pbkdf2_sha1` - as it's preferred hash format. + as its preferred hash format. This context supports all the :data:`roundup10_context` hashes, but adds that hash as well (and uses it as the default). diff --git a/docs/lib/passlib.context-tutorial.rst b/docs/lib/passlib.context-tutorial.rst index e3c3ee9..d63f87c 100644 --- a/docs/lib/passlib.context-tutorial.rst +++ b/docs/lib/passlib.context-tutorial.rst @@ -50,7 +50,7 @@ Tutorial / Walkthrough Basic Usage ----------- -At it's base, the :class:`!CryptContext` class is just a list of +At its base, the :class:`!CryptContext` class is just a list of :class:`~passlib.ifc.PasswordHash` objects, imported by name from the :mod:`passlib.hash` module. The following snippet creates a new context object which supports three hash algorithms @@ -179,8 +179,8 @@ could of course be done in one step:: This is not much more useful, since these settings still have to be hardcoded somewhere in the application. This is where the CryptContext's serialization abilities come into play. As a starting point, -every CryptContext object can dump it's configuration as a dictionary -suitable for passing back into it's constructor:: +every CryptContext object can dump its configuration as a dictionary +suitable for passing back into its constructor:: >>> myctx.to_dict() {'schemes': ['sha256_crypt', 'ldap_salted_md5'], diff --git a/docs/lib/passlib.context.rst b/docs/lib/passlib.context.rst index 96a6b69..6df24ba 100644 --- a/docs/lib/passlib.context.rst +++ b/docs/lib/passlib.context.rst @@ -24,7 +24,7 @@ The CryptContext Class Helper for encrypting passwords using different algorithms. - At it's base, this is a proxy object that makes it easy to use + At its base, this is a proxy object that makes it easy to use multiple :class:`~passlib.ifc.PasswordHash` objects at the same time. Instances of this class can be created by calling the constructor with the appropriate keywords, or by using one of the alternate @@ -107,7 +107,7 @@ Options which directly affect the behavior of the CryptContext instance: new hashes. This parameter is optional; if omitted, the first non-deprecated algorithm in ``schemes`` will be used. You can use the :meth:`~CryptContext.default_scheme` method - to retreive the name of the current default scheme. + to retrieve the name of the current default scheme. As an example, the following demonstrates the effect of this parameter on the :meth:`~CryptContext.encrypt` method:: @@ -344,8 +344,8 @@ For example, a CryptContext could be set up as follows:: Primary Methods --------------- -The main interface to the CryptContext object deliberate mirrors -the :ref:`PasswordHash <password-hash-api>` interface, since it's central +The main interface to the CryptContext object deliberately mirrors +the :ref:`PasswordHash <password-hash-api>` interface, since its central purpose is to act as a container for multiple password hashes. Most applications will only need to make use two methods in a CryptContext instance: @@ -403,7 +403,7 @@ This is done through three methods: Examining the Configuration --------------------------- -The CryptContext object also supports basic inspection of it's +The CryptContext object also supports basic inspection of its current configuration: .. automethod:: CryptContext.schemes @@ -423,7 +423,7 @@ using one of the serialization methods: Configuration Errors -------------------- The following errors may be raised when creating a :class:`!CryptContext` instance -via any of it's constructors, or when updating the configuration of an existing +via any of its constructors, or when updating the configuration of an existing instance: :raises ValueError: diff --git a/docs/lib/passlib.ext.django.rst b/docs/lib/passlib.ext.django.rst index b1a2c1d..ce10dd9 100644 --- a/docs/lib/passlib.ext.django.rst +++ b/docs/lib/passlib.ext.django.rst @@ -14,9 +14,9 @@ support for Django 1.3 and earlier, and require Django 1.4 or newer. This module contains a `Django <http://www.djangoproject.com>`_ plugin which -overriddes all of Django's password hashing functions, replacing them +overrides all of Django's password hashing functions, replacing them with wrappers around a Passlib :ref:`CryptContext <context-overview>` object -whose configuration is controled from Django's ``settings``. +whose configuration is controlled from Django's ``settings``. While this extension's utility is diminished with the advent of Django 1.4's *hashers* framework, this plugin still has a number of uses: @@ -65,7 +65,7 @@ options, you can customize it using the following options in Django's ``settings This option specifies the CryptContext configuration options that will be used when the plugin is loaded. - * It's value will usually be an INI-formatted string or a dictionary, containing + * Its value will usually be an INI-formatted string or a dictionary, containing options to be passed to :class:`~passlib.context.CryptContext`. * Alternately, it can be the name of any preset supported by @@ -77,7 +77,7 @@ options, you can customize it using the following options in Django's ``settings At any point after this plugin has been loaded, you can serialize - it's current configuration to a string:: + its current configuration to a string:: >>> from passlib.ext.django.models import password_context >>> print password_context.to_string() @@ -99,7 +99,7 @@ options, you can customize it using the following options in Django's ``settings to have per-category policies, such as a larger number of iterations for the superuser account. - This option allows overidding the function which performs this mapping, + This option allows overriding the function which performs this mapping, so that more fine-grained / alternate user categories can be used. If specified, the function should have the call syntax ``get_category(user) -> category_string|None``. diff --git a/docs/lib/passlib.hash.apr_md5_crypt.rst b/docs/lib/passlib.hash.apr_md5_crypt.rst index 883f44e..6c8a489 100644 --- a/docs/lib/passlib.hash.apr_md5_crypt.rst +++ b/docs/lib/passlib.hash.apr_md5_crypt.rst @@ -6,8 +6,8 @@ .. warning:: - As of 2012-6-7, the MD5-Crypt algorithm is "no longer considered safe" - by it's author, who urges migration to newer hash algorithms. + As of 2012-6-7, the MD5-Crypt algorithm is "no longer considered safe" + by its author, who urges migration to newer hash algorithms. .. currentmodule:: passlib.hash @@ -32,12 +32,12 @@ Format & Algorithm This format and algorithm of Apache's MD5-Crypt is identical to the original MD5-Crypt, except for two changes: -1. The encoded string uses ``$apr1$`` as it's prefix, while md5-crypt uses ``$1$``. +1. The encoded string uses ``$apr1$`` as its prefix, while md5-crypt uses ``$1$``. 2. The algorithm uses ``$apr1$`` as a constant in the step where md5-crypt uses - ``$1$`` in it's calculation of digest B (see the :ref:`md5-crypt algorithm <md5-crypt-algorithm>`). + ``$1$`` in its calculation of digest B (see the :ref:`md5-crypt algorithm <md5-crypt-algorithm>`). Because of this change, even raw checksums generated by apr-md5-crypt and md5-crypt - are not compatible with eachother. + are not compatible with each other. See :doc:`md5_crypt <passlib.hash.md5_crypt>` for the format & algorithm descriptions, as well as security notes. diff --git a/docs/lib/passlib.hash.atlassian_pbkdf2_sha1.rst b/docs/lib/passlib.hash.atlassian_pbkdf2_sha1.rst index c240127..f863bfc 100644 --- a/docs/lib/passlib.hash.atlassian_pbkdf2_sha1.rst +++ b/docs/lib/passlib.hash.atlassian_pbkdf2_sha1.rst @@ -39,11 +39,11 @@ A example hash (of ``password``) is: ``{PKCS5S2}DQIXJU038u4P7FdsuFTY/+35bm41kfjZa57UrdxHp2Mu3qF2uy+ooD+jF5t1tb8J`` -Once decoded, the salt value (in hexdecimal octets) is: +Once decoded, the salt value (in hexadecimal octets) is: ``0d0217254d37f2ee0fec576cb854d8ff`` -and the checksum value (in hexidecimal octets) is: +and the checksum value (in hexadecimal octets) is: ``edf96e6e3591f8d96b9ed4addc47a7632edea176bb2fa8a03fa3179b75b5bf09`` diff --git a/docs/lib/passlib.hash.bcrypt.rst b/docs/lib/passlib.hash.bcrypt.rst index eafe7ac..041a2bf 100644 --- a/docs/lib/passlib.hash.bcrypt.rst +++ b/docs/lib/passlib.hash.bcrypt.rst @@ -64,7 +64,7 @@ Interface .. warning:: The pure-python backend (#5) is disabled by default! - That backend is currently too slow to be usuable given the number of rounds required + That backend is currently too slow to be usable given the number of rounds required for security. That said, if you have no other alternative and need to use it, set the environmental variable ``PASSLIB_BUILTIN_BCRYPT="enabled"`` before importing Passlib. @@ -77,7 +77,7 @@ Interface Format & Algorithm ================== Bcrypt is compatible with the :ref:`modular-crypt-format`, and uses ``$2$`` and ``$2a$`` as the identifying prefix -for all it's strings (``$2$`` is seen only for legacy hashes which used an older version of Bcrypt). +for all its strings (``$2$`` is seen only for legacy hashes which used an older version of Bcrypt). An example hash (of ``password``) is: ``$2a$12$GhvMmNVjRW29ulnudl.LbuAnUtN/LRfe1JsBm1Xu6LE3059z5Tr8m`` @@ -89,7 +89,7 @@ Bcrypt hashes have the format :samp:`$2a${rounds}${salt}{checksum}`, where: * :samp:`{salt}` is a 22 character salt string, using the characters in the regexp range ``[./A-Za-z0-9]`` (``GhvMmNVjRW29ulnudl.Lbu`` in the example). * :samp:`{checksum}` is a 31 character checksum, using the same characters as the salt (``AnUtN/LRfe1JsBm1Xu6LE3059z5Tr8m`` in the example). -While BCrypt's basic algorithm is described in it's design document [#f1]_, +While BCrypt's basic algorithm is described in its design document [#f1]_, the OpenBSD implementation [#f2]_ is considered the canonical reference, even though it differs from the design document in a few small ways. @@ -116,7 +116,7 @@ This implementation of bcrypt differs from others in a few ways: BCrypt does not specify what the behavior should be when passed a salt string outside of the regexp range ``[./A-Za-z0-9]``. - In order to avoid this situtation, Passlib strictly limits salts to the + In order to avoid this situation, Passlib strictly limits salts to the allowed character set, and will throw a :exc:`ValueError` if an invalid salt character is encountered. diff --git a/docs/lib/passlib.hash.bigcrypt.rst b/docs/lib/passlib.hash.bigcrypt.rst index d7e8b24..a958aa5 100644 --- a/docs/lib/passlib.hash.bigcrypt.rst +++ b/docs/lib/passlib.hash.bigcrypt.rst @@ -108,12 +108,12 @@ BigCrypt is dangerously flawed: * It suffers from all the flaws of :class:`~passlib.hash.des_crypt`. -* Since each checksum compontent in it's hash is essentially a separate +* Since each checksum component in its hash is essentially a separate des-crypt checksum, they can be attacked in parallel. * It reveals information about the length of the encoded password (to within 8 characters), further reducing the keyspace that needs - to be searched for each of the invididual segments. + to be searched for each of the individual segments. * The last checksum typically contains only a few characters of the passphrase, and once cracked, diff --git a/docs/lib/passlib.hash.bsdi_crypt.rst b/docs/lib/passlib.hash.bsdi_crypt.rst index 3492dcc..c41bc16 100644 --- a/docs/lib/passlib.hash.bsdi_crypt.rst +++ b/docs/lib/passlib.hash.bsdi_crypt.rst @@ -113,7 +113,7 @@ Security Issues =============== BSDi Crypt should not be considered sufficiently secure, for a number of reasons: -* It's use of the DES stream cipher, which is vulnerable to practical pre-image attacks, +* Its use of the DES stream cipher, which is vulnerable to practical pre-image attacks, and considered broken, as well as having too-small key and block sizes. * The 24-bit salt is too small to defeat rainbow-table attacks @@ -126,7 +126,7 @@ BSDi Crypt should not be considered sufficiently secure, for a number of reasons as they may reveal the hash used one of the weak DES keys [#weak]_. This information could theoretically allow an attacker to perform a brute-force attack on a reduced keyspace and against only 1-2 rounds of DES. - (This issue is mitagated by the fact that few passwords are both valid *and* + (This issue is mitigated by the fact that few passwords are both valid *and* result in a weak key). This algorithm is none-the-less stronger than :class:`!des_crypt` itself, diff --git a/docs/lib/passlib.hash.cisco_pix.rst b/docs/lib/passlib.hash.cisco_pix.rst index 311409b..1f95c33 100644 --- a/docs/lib/passlib.hash.cisco_pix.rst +++ b/docs/lib/passlib.hash.cisco_pix.rst @@ -50,7 +50,7 @@ Interface .. note:: - This hash algorithm has a context-sensitive percularity. + This hash algorithm has a context-sensitive peculiarity. It takes in an optional username, used to salt the hash, but with specific restrictions... @@ -91,12 +91,12 @@ Security Issues This algorithm is not suitable for *any* use besides manipulating existing Cisco PIX hashes, due to the following flaws: -* It's use of the username as a salt value (and only the first four characters +* Its use of the username as a salt value (and only the first four characters at that), means that common usernames (e.g. ``admin``, ``cisco``) will occur more frequently as salts, weakening the effectiveness of the salt in foiling pre-computed tables. -* It's truncation of the ``password+user`` combination to 16 characters +* Its truncation of the ``password+user`` combination to 16 characters additionally limits the keyspace, and the effectiveness of the username as a salt; making pre-computed and brute force attacks much more feasible. @@ -104,7 +104,7 @@ Cisco PIX hashes, due to the following flaws: existing MD5 lookup tables have an increased chance of being able to reverse common hashes. -* It's simplicity, and the weakness of MD5, makes high-speed brute force attacks +* Its simplicity, and the weakness of MD5, makes high-speed brute force attacks much more feasible. * Furthermore, it discards of 1/4 of MD5's already small 16 byte digest, diff --git a/docs/lib/passlib.hash.cisco_type7.rst b/docs/lib/passlib.hash.cisco_type7.rst index dee0a70..e419201 100644 --- a/docs/lib/passlib.hash.cisco_type7.rst +++ b/docs/lib/passlib.hash.cisco_type7.rst @@ -55,7 +55,7 @@ Interface Format & Algorithm ================== The Cisco Type 7 encoding consists of two decimal digits -(encoding the salt), followed a series of hexdecimal characters, +(encoding the salt), followed a series of hexadecimal characters, two for every byte in the encoded password. An example encoding (of ``"password"``) is ``044B0A151C36435C0D``. This has a salt/offset of 4 (``04`` in the example), @@ -83,7 +83,7 @@ The algorithm is a straightforward XOR Cipher: a. let ``j=(i + salt) % 53`` b. XOR the :samp:`{i}`'th byte of the password with the :samp:`{j}`'th byte of the magic constant. - c. encode the resulting byte as uppercase hexidecimal, + c. encode the resulting byte as uppercase hexadecimal, and append to the encoded string. Deviations diff --git a/docs/lib/passlib.hash.crypt16.rst b/docs/lib/passlib.hash.crypt16.rst index de9eff7..101d9dd 100644 --- a/docs/lib/passlib.hash.crypt16.rst +++ b/docs/lib/passlib.hash.crypt16.rst @@ -89,7 +89,7 @@ Crypt16 is dangerously flawed: * It suffers from all the flaws of :class:`~passlib.hash.des_crypt`. -* Compared to des-crypt, it's smaller number of rounds +* Compared to des-crypt, its smaller number of rounds makes it even *more* vulnerable to brute-force attacks. * For a given salt, passwords under 9 characters all have the same 2nd checksum. diff --git a/docs/lib/passlib.hash.cta_pbkdf2_sha1.rst b/docs/lib/passlib.hash.cta_pbkdf2_sha1.rst index 2acc2a6..7d0eedd 100644 --- a/docs/lib/passlib.hash.cta_pbkdf2_sha1.rst +++ b/docs/lib/passlib.hash.cta_pbkdf2_sha1.rst @@ -36,7 +36,7 @@ where: * ``$p5k2$`` is used as the :ref:`modular-crypt-format` identifier. * :samp:`{rounds}` is the number of PBKDF2 iterations to perform, - stored as lowercase hexidecimal number with no zero-padding (in the example: ``2710`` or 10000 iterations). + stored as lowercase hexadecimal number with no zero-padding (in the example: ``2710`` or 10000 iterations). * :samp:`{salt}` is the salt string encoding using base64 (with ``-_`` as the high values). @@ -48,9 +48,9 @@ where: ``AU2JLf2rNxWoZxWxRCluY0u6h6c=`` in the example. In order to generate the checksum, the password is first encoded into UTF-8 if it's unicode. -The salt is decoded from it's base64 representation. +The salt is decoded from its base64 representation. PBKDF2 is called using the encoded password, the full salt, -the specified number of rounds, and using HMAC-SHA1 as it's psuedorandom function. +the specified number of rounds, and using HMAC-SHA1 as its pseudorandom function. 20 bytes of derived key are requested, and the resulting key is encoded and used as the checksum portion of the hash. diff --git a/docs/lib/passlib.hash.des_crypt.rst b/docs/lib/passlib.hash.des_crypt.rst index f0ed330..5ae26df 100644 --- a/docs/lib/passlib.hash.des_crypt.rst +++ b/docs/lib/passlib.hash.des_crypt.rst @@ -95,7 +95,7 @@ Security Issues =============== DES-Crypt is no longer considered secure, for a variety of reasons: -* It's use of the DES stream cipher, which is vulnerable to practical pre-image attacks, +* Its use of the DES stream cipher, which is vulnerable to practical pre-image attacks, and considered broken, as well as having too-small key and block sizes. * The 12-bit salt is considered to small to defeat rainbow-table attacks diff --git a/docs/lib/passlib.hash.django_std.rst b/docs/lib/passlib.hash.django_std.rst index d8a8dee..8daf54b 100644 --- a/docs/lib/passlib.hash.django_std.rst +++ b/docs/lib/passlib.hash.django_std.rst @@ -93,7 +93,7 @@ Both of Django's PBKDF2 hashes have the same basic format, * :samp:`{checksum}` is the base64 encoding the PBKDF2 digest. -The digest porition is generated by passing the ``utf-8`` encoded password, +The digest portion is generated by passing the ``utf-8`` encoded password, the ``ascii``-encoded salt string, and the number of rounds into PBKDF2 using the HMAC-SHA256 prf; and generated a 32 byte checksum, which is then encoding using base64. @@ -152,13 +152,13 @@ Both of Django's salted hashes have the same basic format, * :samp:`{ident}` is an identifier (``sha1`` in the case of the example, ``md5`` for :class:`!django_salted_md5`). -* :samp:`{salt}` consists of (usually 5) lowercase hexidecimal digits (``f8793`` in the example). +* :samp:`{salt}` consists of (usually 5) lowercase hexadecimal digits (``f8793`` in the example). -* :samp:`{checksum}` is lowercase hexidecimal encoding of the checksum. +* :samp:`{checksum}` is lowercase hexadecimal encoding of the checksum. The checksum is generated by concatenating the salt digits followed by the password, and hashing them using the specified digest (MD5 or SHA-1). -The digest is then encoded to hexidecimal. +The digest is then encoded to hexadecimal. If the password is unicode, it is converted to ``utf-8`` first. Security Issues @@ -172,7 +172,7 @@ Django's salted hashes should not be considered very secure. of entropy in their salt, which is borderline insufficient to defeat rainbow tables. -* They digest the encoded hexidecimal salt, not the raw bytes, +* They digest the encoded hexadecimal salt, not the raw bytes, increasing the odds that a particular salt+password string will be present in a pre-computed tables of ascii digests. @@ -189,7 +189,7 @@ as the salted hashes: :samp:`{ident}${salt}${checksum}`, where: * :samp:`{ident}` is the identifier ``crypt``. -* :samp:`{salt}` is 5 lowercase hexidecimal digits (``cd1a4`` in the example). +* :samp:`{salt}` is 5 lowercase hexadecimal digits (``cd1a4`` in the example). * :samp:`{checksum}` is a :class:`!des_crypt` hash (``cdlRbNJGImptk`` in the example). diff --git a/docs/lib/passlib.hash.dlitz_pbkdf2_sha1.rst b/docs/lib/passlib.hash.dlitz_pbkdf2_sha1.rst index d353fae..4b62520 100644 --- a/docs/lib/passlib.hash.dlitz_pbkdf2_sha1.rst +++ b/docs/lib/passlib.hash.dlitz_pbkdf2_sha1.rst @@ -41,7 +41,7 @@ where: * ``$p5k2$`` is used as the :ref:`modular-crypt-format` identifier. * :samp:`{rounds}` is the number of PBKDF2 iterations to perform, - stored as lowercase hexidecimal number with no zero-padding (in the example: ``2710`` or 10000 iterations). + stored as lowercase hexadecimal number with no zero-padding (in the example: ``2710`` or 10000 iterations). * :samp:`{salt}` is the salt string, which can be any number of characters, drawn from the :data:`hash64 charset <passlib.utils.HASH64_CHARS>` @@ -54,7 +54,7 @@ where: In order to generate the checksum, the password is first encoded into UTF-8 if it's unicode. Then, the entire configuration string (all of the hash except the checksum, ie :samp:`$p5k2${rounds}${salt}`) is used as the PBKDF2 salt. PBKDF2 is called using the encoded password, the full salt, -the specified number of rounds, and using HMAC-SHA1 as it's psuedorandom function. +the specified number of rounds, and using HMAC-SHA1 as its pseudorandom function. 24 bytes of derived key are requested, and the resulting key is encoded and used as the checksum portion of the hash. diff --git a/docs/lib/passlib.hash.fshp.rst b/docs/lib/passlib.hash.fshp.rst index 7328ca4..28efbde 100644 --- a/docs/lib/passlib.hash.fshp.rst +++ b/docs/lib/passlib.hash.fshp.rst @@ -7,8 +7,8 @@ .. note:: While the SHA-2 variants of PBKDF1 have no critical security vulnerabilities, - PBKDF1 itself has been deprecated in favor of it's successor, PBKDF2. - Furthermore, FSHP has been listed as insecure by it's author (for unspecified reasons); + PBKDF1 itself has been deprecated in favor of its successor, PBKDF2. + Furthermore, FSHP has been listed as insecure by its author (for unspecified reasons); so this scheme should probably only be used to support existing hashes. .. currentmodule:: passlib.hash @@ -68,11 +68,11 @@ A example hash (of ``password``) is: * :samp:`{data}` is a base64-encoded string which, when decoded, contains a salt string of the specified size, followed by the checksum. In the example, the data portion decodes to - a salt value (in hexdecimal octets) of: + a salt value (in hexadecimal octets) of: ``3eda2a70651eb66544cbfb91f3bd794c`` - and a checksum value (in hexidecimal octets) of: + and a checksum value (in hexadecimal octets) of: ``da8a6bcfad78c17da993b5940f6524d526d444012cf67ea8f44b7843c7ab2e82`` @@ -94,7 +94,7 @@ Security Issues * Since PBKDF1 is based on repeated composition of a hash, it is vulnerable to any first-preimage attacks on the underlying hash. This has led to the deprecation of using SHA-1 or earlier hashes with PBKDF1. - In contrast, it's successor PBKDF2 was designed to mitigate + In contrast, its successor PBKDF2 was designed to mitigate this weakness (among other things), and enjoys much stronger preimage resistance when used with the same cryptographic hashes. diff --git a/docs/lib/passlib.hash.grub_pbkdf2_sha512.rst b/docs/lib/passlib.hash.grub_pbkdf2_sha512.rst index 279ac57..891f2ab 100644 --- a/docs/lib/passlib.hash.grub_pbkdf2_sha512.rst +++ b/docs/lib/passlib.hash.grub_pbkdf2_sha512.rst @@ -38,14 +38,14 @@ A example hash (of ``password``) is :: All of this scheme's hashes have the format :samp:`grub.pbkdf2.sha512.{rounds}.{salt}.{checksum}`, where :samp:`{rounds}` is the number of iteration stored in decimal, -:samp:`{salt}` is the salt string encoded using upper-case hexdecimal, +:samp:`{salt}` is the salt string encoded using upper-case hexadecimal, and :samp:`{checksum}` is the resulting 64-byte derived key, also -encoded in upper-case hexidecimal. It can be identified by the prefix ``grub.pdkdf2.sha512.``. +encoded in upper-case hexadecimal. It can be identified by the prefix ``grub.pdkdf2.sha512.``. The algorithm used is the same as :class:`pbkdf2_sha1`: the password is encoded into UTF-8 if not already encoded, and passed through :func:`~passlib.utils.pbkdf2.pbkdf2` along with the decoded salt, and the number of rounds. -The result is then encoded into hexidecimal. +The result is then encoded into hexadecimal. .. Hash Translation diff --git a/docs/lib/passlib.hash.hex_digests.rst b/docs/lib/passlib.hash.hex_digests.rst index aea7ea2..a9b8391 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}` - Generic Hexdecimal Digests -============================================================== +=============================================================== +:samp:`passlib.hash.hex_{digest}` - Generic Hexadecimal Digests +=============================================================== .. warning:: @@ -12,7 +12,7 @@ .. currentmodule:: passlib.hash Some existing applications store passwords by storing them using -hexidecimal-encoded message digests, such as MD5 or SHA1. +hexadecimal-encoded message digests, such as MD5 or SHA1. Such schemes are *extremely* vulnerable to pre-computed brute-force attacks, and should not be used in new applications. However, for the sake of backwards compatibility when converting existing applications, @@ -47,7 +47,7 @@ Interface .. class:: hex_sha256() .. class:: hex_sha512() - Each of these classes implements a plain hexidecimal encoded + Each of these classes implements a plain hexadecimal encoded message digest, using the relevant digest function from :mod:`!hashlib`, and following the :ref:`password-hash-api`. @@ -61,5 +61,5 @@ Interface Format & Algorithm ================== All of these classes just report the result of the specified digest, -encoded as a series of lowercase hexidecimal characters; +encoded as a series of lowercase hexadecimal characters; though upper case is accepted as input. diff --git a/docs/lib/passlib.hash.ldap_other.rst b/docs/lib/passlib.hash.ldap_other.rst index 75007f1..f2439a0 100644 --- a/docs/lib/passlib.hash.ldap_other.rst +++ b/docs/lib/passlib.hash.ldap_other.rst @@ -15,22 +15,22 @@ but are not part of any standard. * :ref:`ldap-hashes` for a full list of RFC 2307 style hashes. -Hexidecimal Digests +Hexadecimal Digests =================== All of the digests specified in RFC 2307 use base64 encoding. -The following are non-standard versions which use hexdecimal +The following are non-standard versions which use hexadecimal encoding, as is found in some applications. .. class:: ldap_hex_md5 - hexidecimal version of :class:`ldap_md5`, + hexadecimal version of :class:`ldap_md5`, this is just the md5 digest of the password. an example hash (of ``password``) is ``{MD5}5f4dcc3b5aa765d61d8327deb882cf99``. .. class:: ldap_hex_sha1 - hexidecimal version of :class:`ldap_sha1`, + hexadecimal version of :class:`ldap_sha1`, this is just the sha1 digest of the password. an example hash (of ``password``) is ``{SHA}5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8``. diff --git a/docs/lib/passlib.hash.ldap_pbkdf2_digest.rst b/docs/lib/passlib.hash.ldap_pbkdf2_digest.rst index 909bce9..90934ae 100644 --- a/docs/lib/passlib.hash.ldap_pbkdf2_digest.rst +++ b/docs/lib/passlib.hash.ldap_pbkdf2_digest.rst @@ -20,17 +20,17 @@ Interface .. class:: ldap_pbkdf2_sha1() this is the same as :class:`pbkdf2_sha1`, except that it - uses ``{PBKDF2}`` as it's identifying prefix instead of ``$pdkdf2$``. + uses ``{PBKDF2}`` as its identifying prefix instead of ``$pdkdf2$``. .. class:: ldap_pbkdf2_sha256() this is the same as :class:`pbkdf2_sha256`, except that it - uses ``{PBKDF2-SHA256}`` as it's identifying prefix instead of ``$pdkdf2-sha256$``. + uses ``{PBKDF2-SHA256}`` as its identifying prefix instead of ``$pdkdf2-sha256$``. .. class:: ldap_pbkdf2_sha512() this is the same as :class:`pbkdf2_sha512`, except that it - uses ``{PBKDF2-SHA512}`` as it's identifying prefix instead of ``$pdkdf2-sha512$``. + uses ``{PBKDF2-SHA512}`` as its identifying prefix instead of ``$pdkdf2-sha512$``. .. rubric:: Footnotes diff --git a/docs/lib/passlib.hash.lmhash.rst b/docs/lib/passlib.hash.lmhash.rst index efc0613..e0335de 100644 --- a/docs/lib/passlib.hash.lmhash.rst +++ b/docs/lib/passlib.hash.lmhash.rst @@ -18,7 +18,7 @@ This class implements the LanManager Hash (aka *LanMan* or *LM* hash). It was used by early versions of Microsoft Windows to store user passwords, until it was supplanted (though not entirely replaced) by the :doc:`nthash <passlib.hash.nthash>` algorithm in Windows NT. -It continues to crop up in production due to it's integral role +It continues to crop up in production due to its integral role in the legacy NTLM authentication protocol. This class can be used directly as follows:: @@ -57,7 +57,7 @@ details about the known interoperability issues. It's a mess of codepages. Format & Algorithm ================== -A LM hash consists of 32 hexidecimal digits, +A LM hash consists of 32 hexadecimal digits, which encode the 16 byte digest. An example hash (of ``password``) is ``e52cac67419a9a224a3b108f3fa6cb6d``. @@ -82,7 +82,7 @@ The digest is calculated as follows: 4. Step 3 is repeated using the second 7 bytes of the password from step 2, resulting in the second 8 bytes of the final digest. -5. The combined digests from 3 and 4 are then encoded to hexidecimal. +5. The combined digests from 3 and 4 are then encoded to hexadecimal. Security Issues =============== @@ -94,10 +94,10 @@ dedicated to LMHASH, this algorithm should be considered broken. The major flaws * It limits the password to 14 characters, and converts the password to uppercase before hashing, greatly reducing the keyspace. -* By breaking the password into two independant chunks, - they can be attacked independantly and simultaneously. +* By breaking the password into two independent chunks, + they can be attacked independently and simultaneously. -* The independance of the chunks reveals significant information +* The independence of the chunks reveals significant information about the original password: The second 8 bytes of the digest are the same for all passwords < 8 bytes; and for passwords of 8-9 characters, the second chunk can be broken *much* faster, diff --git a/docs/lib/passlib.hash.md5_crypt.rst b/docs/lib/passlib.hash.md5_crypt.rst index e730d20..0cc705e 100644 --- a/docs/lib/passlib.hash.md5_crypt.rst +++ b/docs/lib/passlib.hash.md5_crypt.rst @@ -7,7 +7,7 @@ .. warning:: As of 2012-6-7, this algorithm is "no longer considered safe" - by it's author [#phk]_, citing the increased + by its author [#phk]_, citing the increased speed of the MD5 hash on modern hardware, and MD5-Crypt's lack of a variable time-cost parameter. See Passlib's :ref:`recommended hashes <recommended-hashes>` for a replacement. @@ -17,7 +17,7 @@ This algorithm was developed for FreeBSD in 1994 by Poul-Henning Kamp, to replace the aging :class:`passlib.hash.des_crypt`. It has since been adopted by a wide variety of other Unix flavors, and is found -in many other contexts as well. Due to it's origins, it's sometimes referred to as "FreeBSD MD5 Crypt". +in many other contexts as well. Due to its origins, it's sometimes referred to as "FreeBSD MD5 Crypt". Security-wise it should now be considered weak, and most Unix flavors have since replaced it with stronger schemes (such as :class:`~passlib.hash.sha512_crypt` and :class:`~passlib.hash.bcrypt`). @@ -162,10 +162,10 @@ MD5-Crypt has a couple of issues which have weakened severely: * It relies on the MD5 message digest, for which theoretical pre-image attacks exist [#f2]_. -* More seriously, it's fixed number of rounds (combined with the availability +* More seriously, its fixed number of rounds (combined with the availability of high-throughput MD5 implementations) means this algorithm is increasingly vulnerable to brute force attacks. - It is this issue which has motivated it's replacement + It is this issue which has motivated its replacement by new algorithms such as :class:`~passlib.hash.bcrypt` and :class:`~passlib.hash.sha512_crypt`. @@ -175,7 +175,7 @@ Passlib's implementation of md5-crypt differs from the reference implementation * Restricted salt string character set: - The underlying algorithm can unambigously handle salt strings + The underlying algorithm can unambiguously handle salt strings which contain any possible byte value besides ``\x00`` and ``$``. However, Passlib strictly limits salts to the :data:`hash64 <passlib.utils.HASH64_CHARS>` character set, diff --git a/docs/lib/passlib.hash.msdcc.rst b/docs/lib/passlib.hash.msdcc.rst index ead1eea..610a358 100644 --- a/docs/lib/passlib.hash.msdcc.rst +++ b/docs/lib/passlib.hash.msdcc.rst @@ -57,7 +57,7 @@ Interface Format & Algorithm ================== Much like :class:`!lmhash` and :class:`!nthash`, MS DCC hashes -consists of a 16 byte digest, usually encoded as 32 hexidecimal characters. +consists of a 16 byte digest, usually encoded as 32 hexadecimal characters. An example hash (of ``"password"`` with the account ``"Administrator"``) is ``25fd08fa89795ed54207e6e8442a6ca0``. @@ -74,7 +74,7 @@ The digest is calculated as follows: 4. The username from step 3 is appended to the digest from step 2; and the MD4 digest of the result is calculated. -5. The result of step 4 is encoded into hexidecimal, +5. The result of step 4 is encoded into hexadecimal, this is the DCC hash. Security Issues @@ -82,7 +82,7 @@ Security Issues This algorithm is should not be used for any purpose besides manipulating existing DCC v1 hashes, due to the following flaws: -* It's use of the username as a salt value (and lower-case at that), +* Its use of the username as a salt value (and lower-case at that), means that common usernames (e.g. ``Administrator``) will occur more frequently as salts, weakening the effectiveness of the salt in foiling pre-computed tables. diff --git a/docs/lib/passlib.hash.msdcc2.rst b/docs/lib/passlib.hash.msdcc2.rst index 6cd99aa..f89edf1 100644 --- a/docs/lib/passlib.hash.msdcc2.rst +++ b/docs/lib/passlib.hash.msdcc2.rst @@ -14,7 +14,7 @@ by Windows Vista and newer to cache and verify remote credentials when the relev server is unavailable. It is known by a number of other names, including "mscache2" and "mscash2" (Microsoft CAched haSH). It replaces the weaker :doc:`msdcc v1<passlib.hash.msdcc>` hash used by previous releases -of Windows. Security wise it is not particularly weak, but due to it's +of Windows. Security wise it is not particularly weak, but due to its use of the username as a salt, it should probably not be used for anything but verifying existing cached credentials. This class can be used directly as follows:: @@ -52,7 +52,7 @@ Format & Algorithm ================== Much like :class:`!lmhash`, :class:`!nthash`, and :class:`!msdcc`, MS DCC v2 hashes consists of a 16 byte digest, usually encoded as 32 -hexidecimal characters. An example hash (of ``"password"`` with the +hexadecimal characters. An example hash (of ``"password"`` with the account ``"Administrator"``) is ``4c253e4b65c007a8cd683ea57bc43c76``. The digest is calculated as follows: @@ -67,12 +67,12 @@ The digest is calculated as follows: not ``SOMEDOMAIN\\User``) 4. The username from step 3 is appended to the digest from step 2; and the MD4 digest of the result - is calculated (The result of this is identicial to the + is calculated (The result of this is identical to the :class:`~passlib.hash.msdcc` digest). 5. :func:`PBKDF2-HMAC-SHA1 <passlib.utils.pbkdf2.pbkdf2>` is then invoked, using the result of step 4 as the secret, the username from step 3 as the salt, 10240 rounds, and resulting in a 16 byte digest. -6. The result of step 5 is encoded into hexidecimal; +6. The result of step 5 is encoded into hexadecimal; this is the DCC2 hash. Security Issues @@ -93,7 +93,7 @@ Deviations but the actual value of this limit is unclear; sources report it to be set at assorted values from 26 to 128 characters, and it may in fact vary between Windows releases. - The one consistent peice of information is that + The one consistent piece of information is that passwords above the limit are simply not allowed (rather than truncated ala :class:`~passlib.hash.des_crypt`). Because of this, Passlib does not currently enforce a size limit: diff --git a/docs/lib/passlib.hash.mssql2000.rst b/docs/lib/passlib.hash.mssql2000.rst index 84a285f..8594047 100644 --- a/docs/lib/passlib.hash.mssql2000.rst +++ b/docs/lib/passlib.hash.mssql2000.rst @@ -12,7 +12,7 @@ .. currentmodule:: passlib.hash This class implements the hash algorithm used by Microsoft SQL Server 2000 -to store it's user account passwords, until it was replaced +to store its user account passwords, until it was replaced by a slightly more secure variant (:class:`~passlib.hash.mssql2005`) in MSSQL 2005. This class can be used directly as follows:: @@ -45,7 +45,7 @@ Interface Format & Algorithm ================== MSSQL 2000 hashes are usually presented as a series of 92 upper-case -hexidecimal characters, prefixed by ``0x``. An example MSSQL 2000 hash +hexadecimal characters, prefixed by ``0x``. An example MSSQL 2000 hash (of ``"password"``):: 0x0100200420C4988140FD3920894C3EDC188E94F428D57DAD5905F6CC1CBAF950CAD4C63F272B2C91E4DEEB5E6444 @@ -73,7 +73,7 @@ MSSQL 2005 removed the second digest, and thus became case sensitive. MSSQL 2000 hashes do not actually have a native textual format, as they are stored as raw bytes in an SQL table. However, when external programs - deal with them, MSSQL generally encodes raw bytes as upper-case hexidecimal, + deal with them, MSSQL generally encodes raw bytes as upper-case hexadecimal, prefixed with ``0x``. This is the representation Passlib uses. Security Issues @@ -85,7 +85,7 @@ following flaws: * The fact that it is case insensitive greatly reduces the keyspace that must be searched by brute-force or pre-computed attacks. -* It's simplicity, and years of research on high-speed SHA1 +* Its simplicity, and years of research on high-speed SHA1 implementations, makes efficient brute force attacks much more feasible. .. rubric:: Footnotes diff --git a/docs/lib/passlib.hash.mssql2005.rst b/docs/lib/passlib.hash.mssql2005.rst index f74b04e..cca8026 100644 --- a/docs/lib/passlib.hash.mssql2005.rst +++ b/docs/lib/passlib.hash.mssql2005.rst @@ -12,7 +12,7 @@ .. currentmodule:: passlib.hash This class implements the hash algorithm used by Microsoft SQL Server 2005 -to store it's user account passwords, replacing the slightly less secure +to store its user account passwords, replacing the slightly less secure :class:`~passlib.hash.mssql2000` variant. This class can be used directly as follows:: @@ -44,7 +44,7 @@ Interface Format & Algorithm ================== MSSQL 2005 hashes are usually presented as a series of 52 upper-case -hexidecimal characters, prefixed by ``0x``. An example MSSQL 2005 hash +hexadecimal characters, prefixed by ``0x``. An example MSSQL 2005 hash (of ``"password"``):: 0x01006ACDF9FF5D2E211B392EEF1175EFFE13B3A368CE2F94038B @@ -67,14 +67,14 @@ digest used by MSSQL 2000. MSSQL 2005 hashes do not actually have a native textual format, as they are stored as raw bytes in an SQL table. However, when external programs - deal with them, MSSQL generally encodes raw bytes as upper-case hexidecimal, + deal with them, MSSQL generally encodes raw bytes as upper-case hexadecimal, prefixed with ``0x``. This is the representation Passlib uses. Security Issues =============== This algorithm is reasonably weak, and shouldn't be used for any purpose besides manipulating existing MSSQL 2005 hashes. This mainly due to -it's simplicity, and years of research on high-speed SHA1 +its simplicity, and years of research on high-speed SHA1 implementations, which makes efficient brute force attacks feasible. .. rubric:: Footnotes diff --git a/docs/lib/passlib.hash.mysql323.rst b/docs/lib/passlib.hash.mysql323.rst index f5fac6a..1d09001 100644 --- a/docs/lib/passlib.hash.mysql323.rst +++ b/docs/lib/passlib.hash.mysql323.rst @@ -13,7 +13,7 @@ password hashes. This class implements the first of MySQL's password hash functions, -used to store it's user account passwords. Introduced in MySQL 3.2.3 +used to store its user account passwords. Introduced in MySQL 3.2.3 under the function ``PASSWORD()``, this function was renamed to ``OLD_PASSWORD()`` under MySQL 4.1, when a newer password hash algorithm was introduced (see :class:`~passlib.hash.mysql41`). @@ -45,7 +45,7 @@ Interface Format & Algorithm ================== -A mysql-323 password hash consists of 16 hexidecimal digits, +A mysql-323 password hash consists of 16 hexadecimal digits, directly encoding the 64 bit checksum. MySQL always uses lower-case letters, and so does Passlib (though Passlib will recognize upper case letters as well). diff --git a/docs/lib/passlib.hash.mysql41.rst b/docs/lib/passlib.hash.mysql41.rst index bf3f9b1..b38d481 100644 --- a/docs/lib/passlib.hash.mysql41.rst +++ b/docs/lib/passlib.hash.mysql41.rst @@ -13,7 +13,7 @@ password hashes. This class implements the second of MySQL's password hash functions, -used to store it's user account passwords. Introduced in MySQL 4.1.1 +used to store its user account passwords. Introduced in MySQL 4.1.1 under the function ``PASSWORD()``, it replaced the previous algorithm (:class:`~passlib.hash.mysql323`) as the default used by MySQL, and is still in active use under MySQL 5. @@ -34,13 +34,13 @@ Interface Format & Algorithm ================== A mysql-41 password hash consists of an asterisk ``*`` followed -by 40 hexidecimal digits, directly encoding the 160 bit checksum. +by 40 hexadecimal digits, directly encoding the 160 bit checksum. An example hash (of ``password``) is ``*2470C0C06DEE42FD1618BB99005ADCA2EC9D1E19``. MySQL always uses upper-case letters, and so does Passlib (though Passlib will recognize lower-case letters as well). The checksum is calculated simply, as the SHA1 hash of the SHA1 hash of the password, -which is then encoded into hexidecimal. +which is then encoded into hexadecimal. Security Issues =============== diff --git a/docs/lib/passlib.hash.nthash.rst b/docs/lib/passlib.hash.nthash.rst index d85b7ac..eda18b0 100644 --- a/docs/lib/passlib.hash.nthash.rst +++ b/docs/lib/passlib.hash.nthash.rst @@ -41,12 +41,12 @@ Interface Format & Algorithm ================== -A nthash consists of 32 hexidecimal digits, which encode the digest. +A nthash consists of 32 hexadecimal digits, which encode the digest. An example hash (of ``password``) is ``8846f7eaee8fb117ad06bdd830b7586c``. The digest is calculated by encoding the secret using ``UTF-16-LE``, taking the :mod:`~passlib.utils.md4` digest, and then encoding -that as hexidecimal. +that as hexadecimal. FreeBSD Variant =============== diff --git a/docs/lib/passlib.hash.oracle10.rst b/docs/lib/passlib.hash.oracle10.rst index 5d878ba..a274c0f 100644 --- a/docs/lib/passlib.hash.oracle10.rst +++ b/docs/lib/passlib.hash.oracle10.rst @@ -10,7 +10,7 @@ besides manipulating existing Oracle 10 password hashes. 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>`. +version 10g Rel.2. It was superseded by a newer algorithm in :class:`Oracle 11 <passlib.hash.oracle11>`. This class can be used directly as follows (note that this class requires a username for all encrypt/verify operations):: @@ -37,7 +37,7 @@ a username for all encrypt/verify operations):: 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. + and its behavior may not match under various border cases. *caveat emptor*. Interface @@ -48,7 +48,7 @@ Interface Format & Algorithm ================== -Oracle10 hashes all consist of a series of 16 hexidecimal digits, +Oracle10 hashes all consist of a series of 16 hexadecimal digits, representing the resulting checksum. Oracle10 hashes can be formed by the following procedure: @@ -67,14 +67,14 @@ Oracle10 hashes can be formed by the following procedure: a block of null bytes is still used as the CBC initialization vector. All but the last block of ciphertext is discarded. 7. The last block of ciphertext of step 6 is converted - to a hexdecimal string, and returned as the checksum. + to a hexadecimal 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 [#flaws]_: -* It's use of the username as a salt value means that common usernames +* Its use of the username as a salt value means that common usernames (e.g. ``system``) will occur more frequently as salts, weakening the effectiveness of the salt in foiling pre-computed tables. @@ -82,7 +82,7 @@ Oracle10 account passwords, due to the following flaws [#flaws]_: and password, greatly reduces the keyspace that must be searched by brute-force or pre-computed attacks. -* It's simplicity, and decades of research on high-speed DES +* Its simplicity, and decades of research on high-speed DES implementations, makes efficient brute force attacks much more feasible. Deviations diff --git a/docs/lib/passlib.hash.oracle11.rst b/docs/lib/passlib.hash.oracle11.rst index 68f21c6..943c08b 100644 --- a/docs/lib/passlib.hash.oracle11.rst +++ b/docs/lib/passlib.hash.oracle11.rst @@ -27,7 +27,7 @@ This class can be can be used directly as follows:: 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. + and its behavior may not match under various border cases. *caveat emptor*. Interface @@ -44,17 +44,17 @@ 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; +* :samp:`{checksum}` is 40 hexadecimal characters; encoding a 160-bit checksum. (``4143053633E59B4992A8EA17D2FF542C9EDEB335`` in the example) -* :samp:`{salt}` is 20 hexidecimal characters; +* :samp:`{salt}` is 20 hexadecimal 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. +from its hexadecimal representation into binary, and the SHA-1 digest +of :samp:`{password}{raw_salt}` is then encoded into hexadecimal, and returned as the checksum. Deviations ========== diff --git a/docs/lib/passlib.hash.pbkdf2_digest.rst b/docs/lib/passlib.hash.pbkdf2_digest.rst index 8fc5f59..c829edf 100644 --- a/docs/lib/passlib.hash.pbkdf2_digest.rst +++ b/docs/lib/passlib.hash.pbkdf2_digest.rst @@ -89,9 +89,9 @@ follow the same format, :samp:`$pbkdf2-{digest}${rounds}${salt}${checksum}`. * :samp:`{checksum}` - this is the :func:`adapted base64 encoding <passlib.utils.ab64_encode>` of the raw derived key bytes returned from the PBKDF2 function. - Each scheme uses the digest size of it's specific hash algorithm (:samp:`{digest}`) + Each scheme uses the digest size of its specific hash algorithm (:samp:`{digest}`) as the size of the raw derived key. This is enlarged - by appromixately 4/3 by the base64 encoding, + by approximately 4/3 by the base64 encoding, resulting in a checksum size of 27, 43, and 86 for each of the respective algorithms listed above. The algorithm used by all of these schemes is deliberately identical and simple: diff --git a/docs/lib/passlib.hash.phpass.rst b/docs/lib/passlib.hash.phpass.rst index 66d79de..c94d445 100644 --- a/docs/lib/passlib.hash.phpass.rst +++ b/docs/lib/passlib.hash.phpass.rst @@ -10,8 +10,8 @@ This algorithm is used primarily by PHP software which uses PHPass [#pp]_, a PHP library similar to Passlib. The PHPass Portable Hash is a custom password hash used by PHPass as a fallback -when none of it's other hashes are available. -Due to it's reliance on MD5, and the simplistic implementation, +when none of its other hashes are available. +Due to its reliance on MD5, and the simplistic implementation, other hash algorithms should be used if possible. .. seealso:: diff --git a/docs/lib/passlib.hash.postgres_md5.rst b/docs/lib/passlib.hash.postgres_md5.rst index 72144e5..bea5de8 100644 --- a/docs/lib/passlib.hash.postgres_md5.rst +++ b/docs/lib/passlib.hash.postgres_md5.rst @@ -12,8 +12,8 @@ .. currentmodule:: passlib.hash 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. +its user account passwords. This scheme was introduced in PostgreSQL 7.2; +prior to this PostgreSQL stored its password in plain text. 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:: @@ -44,7 +44,7 @@ Interface Format & Algorithm ================== Postgres-MD5 hashes all have the format :samp:`md5{checksum}`, -where :samp:`{checksum}` is 32 hexidecimal digits, encoding a 128-bit checksum. +where :samp:`{checksum}` is 32 hexadecimal digits, encoding a 128-bit checksum. This checksum is the MD5 message digest of the password concatenated with the username. Security Issues @@ -52,14 +52,14 @@ Security Issues This algorithm it not suitable for *any* use besides manipulating existing PostgreSQL account passwords, due to the following flaws: -* It's use of the username as a salt value means that common usernames +* Its use of the username as a salt value means that common usernames (e.g. ``admin``, ``root``, ``postgres``) will occur more frequently as salts, weakening the effectiveness of the salt in foiling pre-computed tables. * Since the keyspace of ``user+password`` is still a subset of ascii characters, existing MD5 lookup tables have an increased chance of being able to reverse common hashes. -* It's simplicity makes high-speed brute force attacks much more feasible [#brute]_ . +* Its simplicity makes high-speed brute force attacks much more feasible [#brute]_ . .. rubric:: Footnotes diff --git a/docs/lib/passlib.hash.rst b/docs/lib/passlib.hash.rst index 8817f74..c4d7574 100644 --- a/docs/lib/passlib.hash.rst +++ b/docs/lib/passlib.hash.rst @@ -8,10 +8,10 @@ Overview ======== The :mod:`!passlib.hash` module contains all the password hash algorithms built into Passlib. -While each hash has it's own options and output format, they all share a common interface, +While each hash has its own options and output format, they all share a common interface, documented in detail in the :ref:`password-hash-api`. The following pages describe the common interface, and then describe each hash in detail -(including it's format, underlying algorithm, and known security issues). +(including its format, underlying algorithm, and known security issues). .. seealso:: :doc:`Quickstart Guide </new_app_quickstart>` -- advice on choosing an appropriately secure hash for your new application. diff --git a/docs/lib/passlib.hash.scram.rst b/docs/lib/passlib.hash.scram.rst index a186685..3adc8c4 100644 --- a/docs/lib/passlib.hash.scram.rst +++ b/docs/lib/passlib.hash.scram.rst @@ -23,7 +23,7 @@ of the hash algorithms the server wishes to support over SCRAM. Since this format is PBKDF2-based, it has equivalent security to Passlib's other :doc:`pbkdf2 hashes <passlib.hash.pbkdf2_digest>`, and can be used to authenticate users using either the normal :ref:`password-hash-api` -or the SCRAM-specific class methods documentated below. +or the SCRAM-specific class methods documented below. .. note:: @@ -73,7 +73,7 @@ Additionally, this class provides a number of useful methods for SCRAM-specific the SCRAM needs to authenticate against a specific mechanism:: >>> # this returns (salt_bytes, rounds, digest_bytes) - >>> scram.extact_digest_info(hash, "sha-1") + >>> scram.extract_digest_info(hash, "sha-1") ('F\xc8\x19\xa3\xb4\xf6\xfe_+\x05@H', 1000, 'u\x17\x04\xd8\x05#\x00\xb2\xc5\xb5~C\xb2\xd7K\tv}\x01\xfc') @@ -95,7 +95,7 @@ Interface ========= .. note:: - This hash format is new in Passlib 1.6, and it's SCRAM-specific API + This hash format is new in Passlib 1.6, and its SCRAM-specific API may change in the next few releases, depending on user feedback. .. autoclass:: scram() @@ -159,7 +159,7 @@ always be supported, this will generally be the weakest link, since the other digests will generally be stronger ones (e.g. SHA2-256). None-the-less, since PBKDF2 is sufficiently collision-resistant -on it's own, any pre-image weakenesses found in SHA1 should be mitigated +on its own, any pre-image weaknesses found in SHA1 should be mitigated by the PBKDF2-HMAC-SHA1 wrapper; and should have no flaws outside of brute-force attacks on PBKDF2-HMAC-SHA1. diff --git a/docs/lib/passlib.hash.sha1_crypt.rst b/docs/lib/passlib.hash.sha1_crypt.rst index 9c184f8..88c205e 100644 --- a/docs/lib/passlib.hash.sha1_crypt.rst +++ b/docs/lib/passlib.hash.sha1_crypt.rst @@ -46,9 +46,9 @@ An sha1-crypt hash string has the format :samp:`$sha1${rounds}${salt}${checksum} Algorithm ========= The checksum is calculated using a modified version of PBKDF1 [#pbk]_, -replacing it's use of the SHA1 message digest with HMAC-SHA1, +replacing its use of the SHA1 message digest with HMAC-SHA1, (which does not suffer from the current vulnerabilities that SHA1 itself does, -as well as providing some of the advancements made in PDKDF2). +as well as providing some of the advancements made in PBKDF2). * first, the HMAC-SHA1 digest of :samp:`{salt}$sha1${rounds}` is generated, using the password as the HMAC-SHA1 key. @@ -85,7 +85,7 @@ in a few ways: * Restricted salt string character set: - The underlying algorithm can unambigously handle salt strings + The underlying algorithm can unambiguously handle salt strings which contain any possible byte value besides ``\x00`` and ``$``. However, Passlib strictly limits salts to the :data:`hash64 <passlib.utils.HASH64_CHARS>` character set, diff --git a/docs/lib/passlib.hash.sha256_crypt.rst b/docs/lib/passlib.hash.sha256_crypt.rst index c0f44d8..800c7a4 100644 --- a/docs/lib/passlib.hash.sha256_crypt.rst +++ b/docs/lib/passlib.hash.sha256_crypt.rst @@ -93,7 +93,7 @@ and other implementations, in a few ways: * Restricted salt string character set: - The underlying algorithm can unambigously handle salt strings + The underlying algorithm can unambiguously handle salt strings which contain any possible byte value besides ``\x00`` and ``$``. However, Passlib strictly limits salts to the :data:`hash64 <passlib.utils.HASH64_CHARS>` character set, diff --git a/docs/lib/passlib.hash.sha512_crypt.rst b/docs/lib/passlib.hash.sha512_crypt.rst index 7e52d50..2e21098 100644 --- a/docs/lib/passlib.hash.sha512_crypt.rst +++ b/docs/lib/passlib.hash.sha512_crypt.rst @@ -38,7 +38,7 @@ the following notable differences: * it uses the :ref:`modular crypt prefix <modular-crypt-format>` ``$6$``, whereas SHA256-Crypt uses ``$5$``. * it uses the SHA-512 message digest in place of the SHA-256 message digest. -* it's output hash is correspondingly larger in size, +* its output hash is correspondingly larger in size, with an 86-character encoded checksum, instead of 43 characters. See :doc:`sha256_crypt <passlib.hash.sha256_crypt>` diff --git a/docs/lib/passlib.hash.sun_md5_crypt.rst b/docs/lib/passlib.hash.sun_md5_crypt.rst index dd9e406..21d70b0 100644 --- a/docs/lib/passlib.hash.sun_md5_crypt.rst +++ b/docs/lib/passlib.hash.sun_md5_crypt.rst @@ -58,7 +58,7 @@ The algorithm used is based around the MD5 message digest and the "Muffett Coin .. _smc-digest-step: -2. an initial MD5 digest is created from the concatentation of the password, +2. an initial MD5 digest is created from the concatenation of the password, and the configuration string (using the format :samp:`$md5,rounds={rounds}${salt}$`, or :samp:`$md5${salt}$` if rounds is 0). @@ -120,7 +120,7 @@ using the following formula: Bare Salt Issue --------------- According to the only existing documentation of this algorithm [#mct]_, -it's hashes were supposed to have the format :samp:`$md5${salt}${checksum}`, +its hashes were supposed to have the format :samp:`$md5${salt}${checksum}`, and include only the bare string :samp:`$md5${salt}` in the salt digest step (see :ref:`step 2 <smc-digest-step>`, above). @@ -136,7 +136,7 @@ implementation's parser. This bug causes the implementation to return It returns the intended original format & checksum only if there is at least one letter after the ``$``, e.g. :samp:`$md5${salt}$x`. -Passlib attempts to accomodate both formats using the special ``bare_salt`` +Passlib attempts to accommodate both formats using the special ``bare_salt`` keyword. It is set to ``True`` to indicate a configuration or hash string which contains only a single ``$``, and does not incorporate it into the hash calculation. The ``$$`` hash is encountered more often in production since it seems diff --git a/docs/lib/passlib.registry.rst b/docs/lib/passlib.registry.rst index 9aadca9..3087f25 100644 --- a/docs/lib/passlib.registry.rst +++ b/docs/lib/passlib.registry.rst @@ -15,7 +15,7 @@ querying Passlib to detect what algorithms are available. .. warning:: This module is primarily used as an internal support module. - It's interface has not been finalized yet, and may be changed somewhat + Its interface has not been finalized yet, and may be changed somewhat between major releases of Passlib, as the internal code is cleaned up and simplified. @@ -45,7 +45,7 @@ Example showing how to use :func:`!registry_crypt_handler_path`:: >>> from passlib.registry import register_crypt_handler_path >>> register_crypt_handler_path("myhash", "myapp.support.hashes") - >>> # even before being loaded, it's name will show up as available + >>> # even before being loaded, its name will show up as available >>> from passlib.registry import list_crypt_handlers >>> 'myhash' in list_crypt_handlers() True diff --git a/docs/lib/passlib.utils.handlers.rst b/docs/lib/passlib.utils.handlers.rst index be948af..aad970a 100644 --- a/docs/lib/passlib.utils.handlers.rst +++ b/docs/lib/passlib.utils.handlers.rst @@ -11,7 +11,7 @@ .. warning:: This module is primarily used as an internal support module. - It's interface has not been finalized yet, and may be changed somewhat + Its interface has not been finalized yet, and may be changed somewhat between major releases of Passlib, as the internal code is cleaned up and simplified. @@ -30,7 +30,7 @@ For classes, Passlib does not make any requirements about what a class instance should look like (if the implementation even uses them). That said, most of the handlers built into Passlib are based around the :class:`GenericHandler` -class, and it's associated mixin classes. While deriving from this class is not required, +class, and its associated mixin classes. While deriving from this class is not required, doing so will greatly reduce the amount of additional code that is needed for all but the most convoluted password hash schemes. @@ -54,7 +54,7 @@ workflow for hashes is some combination of the following: 1. parse hash into constituent parts - performed by :meth:`~GenericHandler.from_string`. 2. validate constituent parts - performed by :class:`!GenericHandler`'s constructor, and the normalization functions such as :meth:`~GenericHandler._norm_checksum` and :meth:`~HasSalt._norm_salt` - which are provided by it's related mixin classes. + which are provided by its related mixin classes. 3. calculate the raw checksum for a specific password - performed by :meth:`~GenericHandler._calc_checksum`. 4. assemble hash, including new checksum, into a new string - performed by :meth:`~GenericHandler.to_string`. @@ -137,7 +137,7 @@ Examples .. todo:: - Show some walk-through examples of how to use GenericHandler and it's mixins + Show some walk-through examples of how to use GenericHandler and its mixins The StaticHandler class ======================= @@ -158,7 +158,7 @@ Other Constructors Testing Hash Handlers ===================== -Within it's unittests, Passlib provides the :class:`~passlib.tests.utils.HandlerCase` class, +Within its unittests, Passlib provides the :class:`~passlib.tests.utils.HandlerCase` class, which can be subclassed to provide a unittest-compatible test class capable of checking if a handler adheres to the :ref:`password-hash-api`. diff --git a/docs/lib/passlib.utils.rst b/docs/lib/passlib.utils.rst index 6427111..db2d3f3 100644 --- a/docs/lib/passlib.utils.rst +++ b/docs/lib/passlib.utils.rst @@ -8,11 +8,11 @@ .. warning:: This module is primarily used as an internal support module. - It's interface has not been finalized yet, and may be changed somewhat + Its interface has not been finalized yet, and may be changed somewhat between major releases of Passlib, as the internal code is cleaned up and simplified. -This module primarily contains utility functions used interally by Passlib. +This module primarily contains utility functions used internally by Passlib. However, end-user applications may find some of the functions useful, in particular: diff --git a/docs/modular_crypt_format.rst b/docs/modular_crypt_format.rst index a0f0cc0..0d19bd4 100644 --- a/docs/modular_crypt_format.rst +++ b/docs/modular_crypt_format.rst @@ -26,7 +26,7 @@ History ======= Historically, most unix systems supported only :class:`~passlib.hash.des_crypt`. Around the same time, many incompatible variations were also developed, -but their hashes were not easily distingiushable from each other +but their hashes were not easily distinguishable from each other (see :ref:`archaic-unix-schemes`); making it impossible to use multiple hashes on one system, or progressively migrate to a newer scheme. @@ -159,7 +159,7 @@ by the following operating systems and platforms: **MacOS X** Darwin's native :func:`!crypt` provides limited functionality, supporting only :class:`~passlib.hash.des_crypt` and :class:`~passlib.hash.bsdi_crypt`. OS X uses a separate - system for it's own password hashes. + system for its own password hashes. **Google App Engine** As of 2011-08-19, Google App Engine's :func:`!crypt` implementation appears to match that of a typical Linux diff --git a/docs/new_app_quickstart.rst b/docs/new_app_quickstart.rst index 96f793a..7832061 100644 --- a/docs/new_app_quickstart.rst +++ b/docs/new_app_quickstart.rst @@ -4,7 +4,7 @@ New Application Quickstart Guide Need to quickly get password hash support added into your new application, and don't have time to wade through pages of documentation, -comparing and constrasting all the different schemes? Read on... +comparing and contrasting all the different schemes? Read on... Really Quick Start ================== @@ -56,7 +56,7 @@ For new applications, there are really only three choices [#choices]_: All three password hashes share the following properties: - * no known vulnerabilties. + * no known vulnerabilities. * based on documented & widely reviewed algorithms. * basic algorithm has seen heavy scrutiny and use for at least 10 years. @@ -172,7 +172,7 @@ over all of the above hashes; the primary feature being that it has a variable *memory* cost as well as time cost. It is incredibly well designed, and looks to likely replace all the others in this section. -However, it is still young by comparison to the others; and has not been as throughly +However, it is still young by comparison to the others; and has not been as thoroughly tested, or widely implemented. The only Python wrapper that exists does not even expose the underlying :func:`!scrypt` function, but is rather a file encryption tool. diff --git a/docs/password_hash_api.rst b/docs/password_hash_api.rst index bb323cc..69e0d5c 100644 --- a/docs/password_hash_api.rst +++ b/docs/password_hash_api.rst @@ -39,7 +39,7 @@ defined by the following abstract base class: * :meth:`~PasswordHash.identify` - check if hash belongs to this algorithm. Each hash algorithm also provides a number of :ref:`informational attributes <informational-attributes>`, - allowing programmatic inspection of it's options and parameter limits. + allowing programmatic inspection of its options and parameter limits. .. _password-hash-examples: @@ -78,9 +78,9 @@ using the :class:`~passlib.hash.sha256_crypt` hash as an example:: .. note:: - Whether a hash supports a particular configuration keywoard (such as ``rounds``) - can be determined from it's documentation page; but also programmatically from - it's :attr:`~PasswordHash.setting_kwds` attribute. + Whether a hash supports a particular configuration keyword (such as ``rounds``) + can be determined from its documentation page; but also programmatically from + its :attr:`~PasswordHash.setting_kwds` attribute. That concludes the most basic example, but there are a few more common use-cases, such as how to use the :meth:`~PasswordHash.identify` method:: @@ -131,8 +131,8 @@ An example of this is the :class:`~passlib.hash.oracle10` algorithm:: .. note:: Whether a hash requires external parameters (such as ``user``) - can be determined from it's documentation page; but also programmatically from - it's :attr:`~PasswordHash.context_kwds` attribute. + can be determined from its documentation page; but also programmatically from + its :attr:`~PasswordHash.context_kwds` attribute. .. _primary-methods: @@ -270,7 +270,7 @@ and hash comparison. otherwise non-ASCII passwords may not :meth:`!verify` successfully. * For historical reasons, :class:`~passlib.hash.lmhash` uses ``cp437`` - as it's default encoding. It will handle :class:`!unicode` correctly; + as its default encoding. It will handle :class:`!unicode` correctly; but non-ASCII passwords provided as :class:`!bytes` must either be encoded using ``"cp437"``, or :class:`!lmhash`'s ``encoding`` keyword must be set to indicate which encoding was used. @@ -399,7 +399,7 @@ There is currently one additional support method, :meth:`~PasswordHash.identify` A small number of the hashes supported by Passlib lack a reliable method of identification (e.g. :class:`~passlib.hash.lmhash` - and :class:`~passlib.hash.nthash` both consist of 32 hexidecimal characters, + and :class:`~passlib.hash.nthash` both consist of 32 hexadecimal characters, with no distinguishing features). For such hashes, this method may return false positives. @@ -486,7 +486,7 @@ the hashes in passlib: ``rounds`` If present, this means the hash can vary the number - of internal rounds used in some part of it's algorithm, + of internal rounds used in some part of its algorithm, allowing the calculation to take a variable amount of processor time, for increased security. @@ -723,7 +723,7 @@ Choosing the right rounds value For hash algorithms which support a variable time-cost, Passlib's default ``rounds`` choices attempt to be secure enough for the average [#avgsys]_ system. But the "right" value for a given hash -is dependant on the server, it's cpu, it's expected load, and it's users. +is dependant on the server, its cpu, its expected load, and its users. Since larger values mean increased work for an attacker, *the right* ``rounds`` *value for a given hash & server should be the largest possible value that doesn't cause intolerable delay for your users*. |