Rewrite of crypt library to be more modular, and addition of the

Secure Hashing Algorithm - 1 (SHA-1), along with the further
refinement of what $x$salt$hash means.  With this new crypt the
following are all acceptable:

    $1$
    $MD5$
    $SHA1$

Note: $2$ is used by OpenBSD's Blowfish, which I considered adding
as $BF$, but there is no actual need for it with SHA-1.  However,
somebody wishing to add OpenBSD password support could easilly add
it in now.

There is also a malloc_crypt() available in the library now, which
behaves exactly the same as crypt(), but it uses a malloced buffer
instead of a static buffer.  However, this is not standard so will
likely not be used much (at all).

Also, for those interested I did a brief speed test Pentium 166/MMX,
which shows the DES crypt to do approximately 2640 crypts a CPU second,
MD5 to do about 62 crypts a CPU second and SHA1 to do about 18 crypts
a CPU second.

Reviewed by:	Mark Murray

1 files changed, 201 insertions, 0 deletions

diff --git a/lib/libcrypt/crypt.3 b/lib/libcrypt/crypt.3
new file mode 100644
index 0000000..f07cf90
--- /dev/null
+++ b/lib/libcrypt/crypt.3
@@ -0,0 +1,201 @@
+.\" 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$
+.\"
+.\" Manual page, using -mandoc macros
+.\"
+.Dd January 19, 1997
+.Dt CRYPT 3
+.Os "FreeSec 1.0"
+.Sh NAME
+.Nm crypt
+.Nd Trapdoor encryption
+.Sh SYNOPSIS
+.Ft char
+.Fn *crypt "const char *key" "const char *salt"
+.Ft char
+.Fn *malloc_crypt "const char *key" "const char *salt"
+.Sh DESCRIPTION
+The
+.Fn crypt
+function performs password hashing with additional code added to
+deter key search attempts.  Different algorithms can be used to
+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 these include the
+.Tn NBS
+Data Encryption Standard (DES), MD5 or SHS.  The algorithm
+used will depend upon the format of the Salt--following the Modular
+Crypt Format (MCF)--and if DES is installed or not.
+.Pp
+The first argument to
+.Nm crypt
+is the data to hash (usually a password), in a
+.Dv null Ns -terminated
+string.
+The second is the salt, in one of three forms:
+.Pp
+.Bl -tag -width Traditional -compact -offset indent
+.It Extended
+If it begins with an underscore (``_'') then the DES Extended Format
+is used in interpreting both the the key and the salt, as outlined below.
+.It Modular
+If it begins with the string ``$token$'' (where ``token'' is a digit or
+alphanumeric token) then the Modular Crypt Format is used, as outlined
+below.
+.It Traditional
+If neither of the above is true, it assumes the Traditional Format,
+using the entire string as the salt (or the first portion).
+.El
+.Pp
+The function
+.Fn malloc_crypt
+differs from
+.Fn crypt
+in not using a static buffer.  The results are instead returned in a
+string buffer allocated with
+.Fn malloc .
+.Pp
+All routines are designed to be time-consuming.  A brief test on a
+Pentium 166/MMX shows the DES crypt to do approximately 2640 crypts
+a CPU second, MD5 to do about 62 crypts a CPU second and SHA1
+to do about 18 crypts a CPU second.
+.Ss DES Extended Format:
+.Pp
+The
+.Ar key
+is divided into groups of 8 characters (the last group is null-padded)
+and the low-order 7 bits of each each character (56 bits per group) are
+used to form the DES key as follows:
+the first group of 56 bits becomes the initial DES key.
+For each additional group, the XOR of the encryption of the current DES
+key with itself and the group bits becomes the next DES key.
+.Pp
+The salt is a 9-character array consisting of an underscore followed
+by 4 bytes of iteration count and 4 bytes of salt.
+These are encoded as printable characters, 6 bits per character,
+least significant character first.
+The values 0 to 63 are encoded as ``./0-9A-Za-z''.
+This allows 24 bits for both
+.Fa count
+and
+.Fa salt .
+.Pp
+Note: this should be clarified.
+.Ss "Modular" crypt:
+.Pp
+If the salt begins with the string 
+.Fa $token$
+(where 
+.Fa token
+is a digit or alphanumeric token) then the Modular Crypt Format is used.  The
+.Fa token
+represents which algorithm is used in encryption.  Following the token is
+the actual salt to use in the encryption.  The length of the salt is limited
+to 16 characters--because the length of the returned output is also limited
+(_PASSWORD_LEN).  The salt must be terminated with the end of the string
+(NULL) or a dollar sign.  Any characters after the dollar sign are ignored.
+.Pp
+Currently supported tokens are:
+.Pp
+.Bl -tag -width 012345678 -compact -offset indent
+.It MD5
+MD5 encryption--a token of 1 will also work.
+.It SHA1
+SHA1 encryption.
+.El
+.Pp
+Other crypt formats may be easilly added.  An example salt would be:
+.Bl -tag -offset indent
+.It Cm "$SHA1$thesalt$rest"
+.El
+.Pp
+.Ss "Traditional" crypt:
+.Pp
+The algorithm used will depend upon if DES is installed or not.  If it is,
+DES will be used.  Otherwise, the best algorithm is used, which is currently
+.\"
+.\" NOTICE: Also make sure to update this
+.\"
+SHA-1.
+.Pp
+How the salt is used will depend upon the algorithm for the hash.  For
+best results, specify at least two characters of salt.
+.Sh RETURN VALUES
+.Pp
+.Fn crypt
+returns a pointer to the encrypted value on success, and NULL on failure.
+Note: this is not a standard behaviour, AT&T
+.Fn crypt
+will always return a pointer to a string.
+.Pp
+.Fn malloc_crypt
+returns a pointer to the encrypted value, which is in a dynamically
+allocated buffer rather than a static buffer, using
+.Fn malloc .
+.Sh SEE ALSO
+.Xr login 1 ,
+.Xr passwd 1 ,
+.Xr getpass 3 ,
+.Xr passwd 5 ,
+.Xr descrypt 3 ,
+.Xr shs 3 ,
+.Sh BUGS
+The
+.Fn crypt
+function returns a pointer to static data, and subsequent calls to
+.Fn crypt
+will modify the same data.
+.Fn malloc_crypt
+can be used to avoid this problem--but it is not standard (so your code
+will not be portable).
+.Sh HISTORY
+A rotor-based
+.Fn crypt
+function appeared in
+.At v6 .
+The current style
+.Fn crypt
+first appeared in
+.At v7 .
+.Pp
+The DES section of the code (FreeSec 1.0) was developed outside the United
+States of America as an unencumbered replacement for the U.S.-only NetBSD
+libcrypt encryption library.
+Users should be aware that this code (and programs staticly linked with it)
+may not be exported from the U.S., although it apparently can be imported.
+.Sh AUTHORS
+Originally written by David Burren <davidb@werj.com.au>, later additions
+and changes by Brandon Gillespie, Poul-henning Kamp and Mark R V Murray.
+SHS Library written and Copyright 1995, 1996 by Paul C. Kocher.