From 9f1a57c304a22d5c1b00b88ba14f357bca16d2d9 Mon Sep 17 00:00:00 2001
From: jim winstead <jimw@php.net>
Date: Sun, 16 Dec 2001 20:38:08 +0000
Subject: [PATCH] crypt: clarify a bit, add examples, resist urge to replace
 all uses of 'encryption' with 'hashing'

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@65324 c90b9560-bf6c-de11-be94-00142212c4b1
---
 functions/strings.xml | 89 +++++++++++++++++++++++++++----------------
 1 file changed, 56 insertions(+), 33 deletions(-)

diff --git a/functions/strings.xml b/functions/strings.xml
index 3bdc4ea01b..9cebcfc79c 100644
--- a/functions/strings.xml
+++ b/functions/strings.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.140 $ -->
+<!-- $Revision: 1.141 $ -->
  <reference id="ref.strings">
   <title>String functions</title>
   <titleabbrev>Strings</titleabbrev>
@@ -419,7 +419,7 @@ $new_string = chunk_split(base64_encode($data));
   <refentry id="function.crypt">
    <refnamediv>
     <refname>crypt</refname>
-    <refpurpose>DES-encrypt a string</refpurpose>
+    <refpurpose>One-way string encryption (hashing)</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -434,38 +434,40 @@ $new_string = chunk_split(base64_encode($data));
     </funcsynopsis>
     <para>
      <function>crypt</function> will return an encrypted string using the
-     standard Unix <abbrev>DES</abbrev> encryption method.  Arguments
-     are a string to be encrypted and an optional two-character salt
-     string to base the encryption on.  See the Unix man page for your
-     crypt function for more information.
+     standard Unix <abbrev>DES</abbrev>-based encryption algorithm or
+     alternative algorithms that may be available on the system.  Arguments
+     are a string to be encrypted and an optional salt string to base the
+     encryption on.  See the Unix man page for your crypt function for more
+     information.
     </para>
     <simpara>
      If the salt argument is not provided, one will be randomly
      generated by PHP.
     </simpara>
     <simpara>
-     Some operating systems support more than one type of encryption.
-     In fact, sometimes the standard DES encryption is replaced by an
-     MD5 based encryption algorithm.  The encryption type is triggered
-     by the salt argument.  At install time, PHP determines the
-     capabilities of the crypt function and will accept salts for
-     other encryption types.  If no salt is provided, PHP will
-     auto-generate a standard 2-character DES salt by default, unless
-     the default encryption type on the system is MD5, in which case a
-     random MD5-compatible salt is generated.  PHP sets a constant
-     named CRYPT_SALT_LENGTH which tells you whether a regular
-     2-character salt applies to your system or the longer 12-char MD5
-     salt is applicable.
+     Some operating systems support more than one type of encryption.  In
+     fact, sometimes the standard DES-based encryption is replaced by an
+     MD5-based encryption algorithm.  The encryption type is triggered by the
+     salt argument.  At install time, PHP determines the capabilities of the
+     crypt function and will accept salts for other encryption types.  If no
+     salt is provided, PHP will auto-generate a standard two character salt by
+     default, unless the default encryption type on the system is MD5, in
+     which case a random MD5-compatible salt is generated.  PHP sets a
+     constant named CRYPT_SALT_LENGTH which tells you whether a regular two
+     character salt applies to your system or the longer twelve character salt
+     is applicable.
     </simpara>
     <simpara>
-     If you are using the supplied salt, you should be aware that the
-     salt is generated once. If you are calling this function
-     recursively, this may impact both appearance and, to a certain
-     extent, security.
+     If you are using the supplied salt, you should be aware that the salt is
+     generated once. If you are calling this function recursively, this may
+     impact both appearance and security.
     </simpara>
     <simpara>
-     The standard DES encryption <function>crypt</function> contains
-     the salt as the first two characters of the output.
+     The standard DES-based encryption <function>crypt</function> returns the
+     salt as the first two characters of the output. It also only uses the
+     first eight characters of <parameter>str</parameter>, so longer strings
+     that start with the same eight characters will generate the same result
+     (when the same salt is used).
     </simpara>
     <simpara>
      On systems where the crypt() function supports multiple
@@ -475,33 +477,54 @@ $new_string = chunk_split(base64_encode($data));
     <itemizedlist>
      <listitem>
       <simpara>
-       CRYPT_STD_DES - Standard DES encryption with a 2-char SALT
+       CRYPT_STD_DES - Standard DES-based encryption with a two character salt
       </simpara>
      </listitem>
      <listitem>
       <simpara>
-       CRYPT_EXT_DES - Extended DES encryption with a 9-char SALT
+       CRYPT_EXT_DES - Extended DES-based encryption with a nine character salt
       </simpara>
      </listitem>
      <listitem>
       <simpara>
-       CRYPT_MD5 - MD5 encryption with a 12-char SALT starting with
+       CRYPT_MD5 - MD5 encryption with a twelve character salt starting with
        $1$
       </simpara>
      </listitem>
      <listitem>
       <simpara>
-       CRYPT_BLOWFISH - Extended DES encryption with a 16-char SALT
+       CRYPT_BLOWFISH - Blowfish encryption with a sixteen character salt
        starting with $2$
       </simpara>
      </listitem>
     </itemizedlist>
+    <note>
+     <simpara>
+      There is no decrypt function, since <function>crypt</function>
+      uses a one-way algorithm.
+     </simpara>
+     </note>
+    <example>
+     <title><function>crypt</function> examples</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$password = crypt("My1sTpassword"); # let salt be generated
+
+# You should pass the entire results of crypt() as the salt for comparing a
+# password, to avoid problems when different hashing algorithms are used. (As
+# it says above, standard DES-based password hashing uses a 2-character salt,
+# but MD5-based hashing uses 12.)
+if (crypt($user_input,$password) == $password) {
+   echo "Password verified!";
+}
+?>
+]]>
+     </programlisting>
+    </example>
     <simpara>
-     There is no decrypt function, since <function>crypt</function>
-     uses a one-way algorithm.
-    </simpara>
-    <simpara>
-     See also: <function>md5</function>.
+     See also <function>md5</function> and <link linkend="ref.mcrypt">the
+     Mcrypt extension</link>.
     </simpara>
    </refsect1>
   </refentry>