-
-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<crypt|/crypt> 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<crypt($plain, $crypted) eq
-$crypted>). This allows your code to work with the standard L<crypt|/crypt>
-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.
+X<crypt> X<digest> X<hash> X<salt> X<plaintext> X<password>
+X<decrypt> X<cryptography> X<passwd> X<encrypt>
+
+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 munitions).
+
+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<Crypt> 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 that 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<crypt($plain, $digest) eq $digest>). The SALT used
+to create the digest is visible as part of the digest. 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<crypt|/crypt> 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.