--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/stdlibs/libcrypt/doc/crypt.3 Tue Nov 02 19:23:22 2010 +0530
@@ -0,0 +1,174 @@
+.\" Portions Copyright © 2005-2006 Nokia. All rights reserved.
+.\" FreeSec: libcrypt for NetBSD
+.\"
+.\" Copyright (c) 1994 David Burren
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 4. Neither the name of the author nor the names of other contributors
+.\" may be used to endorse or promote products derived from this software
+.\" without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD: src/lib/libcrypt/crypt.3,v 1.31 2005/02/09 18:03:14 ru Exp $
+.\"
+.Dd January 19, 1997
+.Dt CRYPT 3
+.Os
+.Sh NAME
+.Nm crypt
+.Nd password and data encryption
+.Sh LIBRARY
+.Lb libcrypt
+.Sh SYNOPSIS
+.In unistd.h
+.Ft char *
+.Fn crypt "const char *key" "const char *salt"
+.Sh RETURN VALUES
+The
+.Fn crypt
+function returns a pointer to the encrypted value on success, and NULL on
+failure.
+.Pp
+.Sh DESCRIPTION
+The
+.Fn crypt
+function performs password hashing with additional code added to
+thwart dictionary attack.
+Different algorithms can be used in the hash.
+.\"
+.\" NOTICE:
+.\" If you add more algorithms, make sure to update this list
+.\" and the default used for the Traditional format, below.
+.\"
+Currently the implementation supports
+.Tn Data Encryption Standard (DES)
+and
+.Tn MD5
+hash algorithms. However, the actual algorithm used during the call to
+.Fn crypt
+depends on the
+.Fn salt
+parameter.
+.Pp
+The first argument to
+.Fn crypt
+is the data to hash (usually a password), in a
+.Dv NULL Ns -terminated
+string.
+The second is the salt, in one of two forms:
+.Pp
+.Bl -tag -width Traditional -compact -offset indent
+.It Modular
+If
+.Fn salt
+begins with the string
+.Dq $digit$
+then the Modular Crypt Format is used.
+.It Traditional
+.Fn salt
+parameter is a two-character string chosen from the set [a-zA-Z0-9./].
+.El
+.Pp
+.Ss "Modular" crypt:
+.Pp
+If
+.Fn salt
+begins with the string
+.Fa $digit$
+then Modular Crypt Format is used.
+The
+.Fa digit
+identifies the algorithm used for encryption. Currently MD5 hash is implemented. So
+.Fa digit
+will be 1 and hence the second argument to this function will be a string beginning with
+.Dq $1$
+followed by at most 8 characters (actual salt to be used in the encryption), and optionally
+terminated by
+.Dq $
+.
+If the optional
+.Dq $
+is included then the characters following the dollar sign are ignored.
+The output of this operation will be a string
+containing 34 characters in the format
+.Dq $1$<string>$
+.Pp
+.Dq <string>
+consists of the actual salt (the at most 8 characters string following
+.Dq $1$
+in the
+.Fn salt),
+followed by 22 bytes of data from the set [a-zA-Z0-9./].
+.El
+.Pp
+Other crypt formats may be easily added.
+An example salt would be:
+.Bl -tag -offset indent
+.It Cm "$4$thesalt$rest"
+.El
+.Pp
+.Ss "Traditional" crypt:
+.Pp
+It is based on Data Encryption Standard algorithm (DES).
+.Fn salt
+is a two-character string chosen from the set [a-zA-Z0-9./]. In order to thwart the
+Dictionary Attack, the two-character
+.Fn salt
+is used to perturb the algorithm in 4096 ways.
+.Pp
+The 56-bit key for the DES algorithm is obtained by taking the lowest 7 bits of each
+of the first eight characters of the
+.Fn key.
+The key thus obtained is used to encrypt a constant string (a string containing all zeroes).
+.Pp
+The return value of this function is a pointer to a static buffer. So the function
+is not reentrant.
+
+.Sh Example
+.Bd -literal -offset indent
+#include <stdlib.h>
+#include <unistd.h>
+
+void crypt_user()
+{
+ char *p = NULL,
+ *q = NULL;
+
+ /* Invoke crypt() to perform password hashing */
+ p = crypt("password", "S1"); /* p contains the hash of "password"
+ * when "S1" is used as the key. DES
+ * encryption algoritm is used in this
+ * scenario
+ */
+
+ q = crypt("password", "$1$Salt1");
+ /* q contains the hash of "password"
+ * as computed by the MD5 hash algorithm
+ */
+}
+.Ed
+.Sh SEE ALSO
+.Sh BUGS
+Output of
+.Fn crypt
+differs from that of Linux's when NULL passed as
+.Fn salt .