doc-en/functions/crack.xml

<!-- D O   N O T   E D I T   T H I S   F I L E   ! ! !  

     it is still here for historical reasons only 
     (as translators may need to check old revision diffs)

     if you want to change things documented in this file
     you should now edit the files found under en/reference
     instead -->
     
     <?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
 <reference id="ref.crack">
  <title>Crack functions</title>
  <titleabbrev>Crack functions</titleabbrev>

  <partintro>
   <para id="crack.intro">
    These functions allow you to use the CrackLib library to test the
    'strength' of a password.  The 'strength' of a password is tested by that
    checks length, use of upper and lower case and checked against the
    specified CrackLib dictionary.  CrackLib will also give helpful diagnostic
    messages that will help 'strengthen' the password.
   </para>

   <section id="crack.requirements">
    <title>Requirements</title>
    <para>
     More information regarding CrackLib along with the library can be found at
     <ulink url="&url.crack;">&url.crack;</ulink>.
    </para>
   </section>
    
   <section id="crack.installation">
    <title>Installation</title>
    <para>
     In order to use these functions, you must compile PHP with Crack support
     by using the <option role="configure">--with-crack[=DIR]</option> option.
    </para>
   </section>

   <section id="crack.configuration">
    <title>Runtime Configuration</title>
     &no.config;
   </section>

   <section id="crack.resources">
    <title>Resource types</title>
     &no.resource;
   </section>

   <section id="crack.constants">
    <title>Predefined constants</title>
     &no.constants;
   </section>

   <section id="crack.examples">
    <title>Example</title>
    <para>
     This example shows how to open a CrackLib dictionary, test a given
     password, retrieve any diagnostic messages, and close the dictionary.
     <example>
      <title>CrackLib example</title>
       <programlisting role="php">
<![CDATA[
<?php
// Open CrackLib Dictionary
$dictionary = crack_opendict('/usr/local/lib/pw_dict')
     or die('Unable to open CrackLib dictionary');

// Perform password check
$check = crack_check($dictionary, 'gx9A2s0x');

// Retrieve messages
$diag = crack_getlastmessage();
echo $diag; // 'strong password'

// Close dictionary
crack_closedict($dictionary);
?>
]]>
       </programlisting>
     </example>
    </para>
    <note>
     <para>
      If <function>crack_check</function> returns &true;,
      <function>crack_getlastmessage</function> will return 'strong password'.
     </para>
    </note>
   </section>
  </partintro>

  <refentry id="function.crack-opendict">
   <refnamediv>
    <refname>crack_opendict</refname>
    <refpurpose>Opens a new CrackLib dictionary</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>resource</type><methodname>crack_opendict</methodname>
       <methodparam><type>string</type><parameter>dictionary</parameter></methodparam>
     </methodsynopsis>
    <para> 
     Returns a dictionary resource identifier on success, or &false; on failure.
    </para>
     &warn.experimental.func;
    <para>
     <function>crack_opendict</function> opens the specified CrackLib 
     <parameter>dictionary</parameter> for use with
     <function>crack_check</function>.
    </para>
    <note>
     <para>
      Only one dictionary may be open at a time.
     </para>
    </note>
    <para>
     See also: <function>crack_check</function>, and
     <function>crack_closedict</function>.
    </para>
   </refsect1>
  </refentry>
	
  <refentry id="function.crack-closedict">
   <refnamediv>
    <refname>crack_closedict</refname>
    <refpurpose>Closes an open CrackLib dictionary </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>crack_closedict</methodname>
      <methodparam choice="opt"><type>resource</type><parameter>dictionary</parameter></methodparam>
     </methodsynopsis>
    <para>
     &return.success;
    </para>
     &warn.experimental.func;
    <para>
     <function>crack_closedict</function> closes the specified
     <parameter>dictionary</parameter> identifier.  If
     <parameter>dictionary</parameter> is not specified, the current
     dictionary is closed.
    </para>
   </refsect1>
  </refentry>
	
  <refentry id="function.crack-check">
   <refnamediv>
    <refname>crack_check</refname>
    <refpurpose>Performs an obscure check with the given password</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>crack_check</methodname>
      <methodparam choice="opt"><type>resource</type><parameter>dictionary</parameter></methodparam>
      <methodparam><type>string</type><parameter>password</parameter></methodparam>
     </methodsynopsis>
    <para> 
     Returns &true; if <parameter>password</parameter> is strong, or &false; otherwise.
    </para>
     &warn.experimental.func;
    <para>
     <function>crack_check</function> performs an obscure check with the given
     <parameter>password</parameter> on the specified <parameter>dictionary
     </parameter>.  If <parameter>dictionary</parameter> is not specified,
     the last opened dictionary is used.
    </para>
   </refsect1>
  </refentry>
	
  <refentry id="function.crack-getlastmessage">
   <refnamediv>
    <refname>crack_getlastmessage</refname>
    <refpurpose>Returns the message from the last obscure check</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>crack_getlastmessage</methodname>
      <void/>
     </methodsynopsis>
     &warn.experimental.func;
    <para>
     <function>crack_getlastmessage</function> returns the message from the
     last obscure check.
    </para>
   </refsect1>
  </refentry>
	
 </reference>
 
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
 sgml-omittag:t
 sgml-shorttag:t
 sgml-minimize-attributes:nil
 sgml-always-quote-attributes:t
 sgml-indent-step:1
 sgml-indent-data:t
 indent-tabs-mode:nil
 sgml-parent-document:nil
 sgml-default-dtd-file:"../../manual.ced"
 sgml-exposed-tags:nil
 sgml-local-catalogs:nil
 sgml-local-ecat-files:nil
 End:
 vim600: syn=xml fen fdm=syntax fdl=2 si
 vim: et tw=78 syn=sgml
 vi: ts=1 sw=1
 -->