cvs: phpdoc /en/functions strings.xml

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>