jimw Sun Dec 16 15:38:10 2001 EDT
Modified files:
/phpdoc/en/functions strings.xml
Log:
crypt: clarify a bit, add examples, resist urge to replace all uses of 'encryption'
with 'hashing'
Index: phpdoc/en/functions/strings.xml
diff -u phpdoc/en/functions/strings.xml:1.140 phpdoc/en/functions/strings.xml:1.141
--- phpdoc/en/functions/strings.xml:1.140 Sun Dec 16 05:34:01 2001
+++ phpdoc/en/functions/strings.xml Sun Dec 16 15:38:08 2001
@@ -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 @@
<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 @@
</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 @@
<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>
