From: Michael G. Schwern Date: Sat, 23 Jul 2005 17:25:18 +0000 (-0700) Subject: [PATCH perlfunc.pod/crypt] crypt() digests, not encrypts X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=ef2e6798a9ad64ac4636e238695c54b37d9fefa9;p=p5sagit%2Fp5-mst-13.2.git [PATCH perlfunc.pod/crypt] crypt() digests, not encrypts Date: Sat, 23 Jul 2005 17:25:18 -0700 Message-ID: <20050724002518.GB4918@windhund.schwern.org> Subject: Re: [PATCH perlfunc.pod/crypt] crypt() digests, not encrypts From: Michael G Schwern Date: Sun, 24 Jul 2005 13:49:25 -0700 Message-ID: <20050724204925.GC13275@windhund.schwern.org> p4raw-id: //depot/perl@25220 --- diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 43dc07b..761bd3a 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -885,31 +885,42 @@ function, or use this relation: =item crypt PLAINTEXT,SALT -Encrypts a string exactly like the crypt(3) function in the C library -(assuming that you actually have a version there that has not been -extirpated as a potential munition). This can prove useful for checking -the password file for lousy passwords, amongst other things. Only the -guys wearing white hats should do this. - -Note that L is intended to be a one-way function, much like -breaking eggs to make an omelette. There is no (known) corresponding -decrypt function (in other words, the crypt() is a one-way hash -function). As a result, this function isn't all that useful for -cryptography. (For that, see your nearby CPAN mirror.) - -When verifying an existing encrypted string you should use the -encrypted text as the salt (like C). This allows your code to work with the standard L -and with more exotic implementations. In other words, do not assume -anything about the returned string itself, or how many bytes in -the encrypted string matter. +Creates a digest string exactly like the crypt(3) function in the C +library (assuming that you actually have a version there that has not +been extirpated as a potential munition). + +crypt() is a one-way hash function. The PLAINTEXT and SALT is turned +into a short string, called a digest, which is returned. The same +PLAINTEXT and SALT will always return the same string, but there is no +(known) way to get the original PLAINTEXT from the hash. Small +changes in the PLAINTEXT or SALT will result in large changes in the +digest. + +There is no decrypt function. This function isn't all that useful for +cryptography (for that, look for F modules on your nearby CPAN +mirror) and the name "crypt" is a bit of a misnomer. Instead it is +primarily used to check if two pieces of text are the same without +having to transmit or store the text itself. An example is checking +if a correct password is given. The digest of the password is stored, +not the password itself. The user types in a password which is +crypt()'d with the same salt as the stored digest. If the two digests +match the password is correct. + +When verifying an existing digest string you should use the digest as +the salt (like C). The SALT used +to create the digest is visible as part of the digest so this ensures +crypt() will hash the new string with the same salt as the digest. +This allows your code to work with the standard L and +with more exotic implementations. In other words, do not assume +anything about the returned string itself, or how many bytes in the +digest matter. Traditionally the result is a string of 13 bytes: two first bytes of the salt, followed by 11 bytes from the set C<[./0-9A-Za-z]>, and only -the first eight bytes of the encrypted string mattered, but -alternative hashing schemes (like MD5), higher level security schemes -(like C2), and implementations on non-UNIX platforms may produce -different strings. +the first eight bytes of the digest string mattered, but alternative +hashing schemes (like MD5), higher level security schemes (like C2), +and implementations on non-UNIX platforms may produce different +strings. When choosing a new salt create a random two character string whose characters come from the set C<[./0-9A-Za-z]> (like C function is unsuitable for encrypting large quantities +The L function is unsuitable for hashing large quantities of data, not least of all because you can't get the information -back. Look at the F and F directories -on your favorite CPAN mirror for a slew of potentially useful -modules. +back. Look at the L module for more robust algorithms. If using crypt() on a Unicode string (which I has characters with codepoints above 255), Perl tries to make sense