Pycrack: A README and FAQ
======== = ====== === ===

What is pycrack?
---- -- --------
pycrack is a simple python extension module for interfacing with cracklib. 
Cracklib is a library which protects against weak passwords by checking, for
example, that they are not too short or easily guessable by dictionary attacks. 

What else do I need to use pycrack?
---- ---- -- - ---- -- --- --------
pycrack is a python extension module so to use it you obviously need the Python
language interpreter installed on your system.  You can get Python from its
website [http://www.python.org/].  You also need cracklib, most Linux systems 
already have cracklib installed (since it is used by PAM's passwd 
implementation).  If you don't have cracklib installed go download it from its
website [http://www.crypticide.org/users/alecm/].  

How can I build and install pycrack?
--- --- - ----- --- ------- --------
pycrack uses Python's standard distutils for building and installation.  Most
people will simply need to type the following at their shell prompt:  

  $ python setup.py build
  $ python setup.py install
  
How do I use pycrack?
--- -- - --- --------
Import pycrack into your Python application as you would any other extension
module; "import pycrack".  After this, you have one function available to you
named "FascistCheck()".  This function performs exactly the same as the one in
cracklib of the same name; it takes two string arguments "pw" which is the
password you wish to check and "dictpath" which is the full path to the cracklib
dictionary you wish to check against.  "FascistCheck()" returns None if the
password is ok and it passes all the checks otherwise it will return a string
explaining why the password is poor.  

FacistCheck(pw, dictpath)
    Check a password (pw) using cracklib against the dictionary located at
    "dictpath".  Return a reason as a string if the password is bad or None if
    the password passes all checks.  
    
Is there an example of how to use pycrack?
-- ----- -- ------- -- --- -- --- --------
Yes, in the test directory of the distribution there is a file "pycracktest.py".
This is a simple example of how pycrack can be used.  To try it out run the file
to check out how to use it: 

  $ python pycracktest.py
  
How can I find out more information?
--- --- - ---- --- ---- ------------
Check the documentation for cracklib and Python at their respective websites. 
Use the example in this distribution as a starting point.  Look at the source,
it's very simple and short.  
  
Why did you create pycrack?
--- --- --- ------ --------
I was bored and I thought this would be a very simple way to learn a bit more 
about Python and how to extend it.  I also noticed that some other languages 
already had an interface to cracklib but Python did not appear to. Hopefully 
this effort will fill that gap.

-- 
RJC 02/04/2003 
robin@digitalevacuation.org 
http://www.digitalevacuation.org/
