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
This commit is contained in:
jim winstead 2001-12-16 20:38:08 +00:00
parent 172ea2c8cf
commit 9f1a57c304

View file

@ -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>