=======================================================================
:class:`passlib.hash.des_crypt` - Tradtional Unix (DES) Crypt
=======================================================================

.. currentmodule:: passlib.hash

.. warning::

    This algorithm is extremely weak by modern standards,
    and should not be used for new applications.
    It suffers from it's use of the DES cipher, a small number of salt bits,
    and fact that it uses only the first 8 characters of the password.

This class implements the original DES-based Unix Crypt algorithm.
While no longer in active use, it is supported for legacy purposes
by many unix variants.

Usage
=====
This class can be used directly as follows::

    >>> from passlib.hash import des_crypt as dc

    >>> dc.encrypt("password") #generate new salt, encrypt password
    'JQMuyS6H.AGMo'

    >>> dc.identify('JQMuyS6H.AGMo') #check if hash is recognized
    True
    >>> dc.identify('$1$3azHgidD$SrJPt7B.9rekpmwJwtON31') #check if some other hash is recognized
    False

    >>> dc.verify("password", 'JQMuyS6H.AGMo') #verify correct password
    True
    >>> dc.verify("secret", 'JQMuyS6H.AGMo') #verify incorrect password
    False

Functions
=========
.. autoclass:: des_crypt

Format
======
A des-crypt hash string consists of 13 characters, drawn from ``[./0-9A-Za-z]``.
The first 2 characters form a :mod:`hash64 <passlib.utils.h64>`-encoded
12 bit integer used as the salt, with the remaining characters
forming a hash64-encoded 64-bit integer checksum.

A des-crypt configuration string is also accepted by this module,
consists of only the first 2 characters, corresponding to the salt only.

An example hash (of ``password``) is ``JQMuyS6H.AGMo``, where the salt is ``JQ``, and the checksum ``MuyS6H.AGMo``.

Algorithm
=========
The checksum is formed by a modified version of the DES cipher in encrypt mode:

* First, the lower 7 bits of the first 8 characters of the password are used
  to form a 56-bit DES key. The remainder of the password is ignored.
  Passwords less than 8 characters are null-padded.

* The checksum is then generated by recursively performing 25 rounds of DES encryption,
  starting with a null input block. The 12 bit salt is used to mutate
  the action performed by each block of the DES key schedule,
  in a manner dependant on the previous block (see the source
  of :func:`~passlib.utils.des.mdes_encrypt_int_block` for details).

* The checksum and salt are then encoded according the format, as described above.

Deviations
==========
This implementation of des-crypt differs from others in a few ways:

* Before generating a hash, PassLib encodes unicode passwords using UTF-8.
  The original des-crypt was designed for 7-bit us-ascii, so this should not
  conflict with most existing hashes. As of this writing, the authors
  know of no specification defining the official behavior that should be used
  in this situtation.

* Some implementations accept empty and single-character salt strings,
  as well as salt strings containing other characters. The various
  implementation of des-crypt vary wildy in how they deal with these
  border cases, including errors, non-standard algorithms, and unpredicateble results.
  To avoid all this, Passlib will throw an "invalid salt" ValueError for these cases.

References
==========
* `<http://www.dynamic.net.au/christos/crypt/UnixCrypt2.txt>`_ - java implementation of des-crypt, used as base for pure-python implementation