9886bcdf93
one-way hash functions for authentication purposes. There is no more "set the libcrypt->libXXXcrypt" nightmare. - Undo the libmd.so hack, use -D to hide the md5c.c internals. - Remove the symlink hacks in release/Makefile - the algorthm is set by set_crypt_format() as before. If this is not called, it tries to heuristically figure out the hash format, and if all else fails, it uses the optional auth.conf entry to chose the overall default hash. - Since source has non-hidden crypto in it there may be some issues with having the source it in some countries, so preserve the "secure/*" division. You can still build a des-free libcrypt library if you want to badly enough. This should not be a problem in the US or exporting from the US as freebsd.org had notified BXA some time ago. That makes this stuff re-exportable by anyone. - For consistancy, the default in absence of any other clues is md5. This is to try and minimize POLA across buildworld where folk may suddenly be activating des-crypt()-hash support. Since the des hash may not always be present, it seemed sensible to make the stronger md5 algorithm the default. All things being equal, no functionality is lost. Reviewed-by: jkh (flame-proof suit on)
277 lines
7.5 KiB
Groff
277 lines
7.5 KiB
Groff
.\" 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 LIBRARY
|
|
.Lb libcrypt
|
|
.Sh SYNOPSIS
|
|
.Fd #include <unistd.h>
|
|
.Ft char *
|
|
.Fn crypt "const char *key" "const char *salt"
|
|
.Ft const char *
|
|
.Fn crypt_get_format "void"
|
|
.Ft int
|
|
.Fn crypt_set_format "const char *string"
|
|
.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
|
|
.Tn Data Encryption Standard (DES) ,
|
|
and
|
|
.Tn MD5 .
|
|
The algorithm used will depend upon the format of the Salt (following
|
|
the Modular Crypt Format (MCF)), if
|
|
.Tn DES
|
|
is installed or not, and whether
|
|
.Fn crypt_set_format
|
|
has been called to change the default.
|
|
.Pp
|
|
The first argument to
|
|
.Nm
|
|
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
|
|
.Pq Dq _
|
|
then the
|
|
.Tn 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
|
|
.Dq $digit$
|
|
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
|
|
All routines are designed to be time-consuming. A brief test on a
|
|
.Tn Pentium
|
|
166/MMX shows the
|
|
.Tn DES
|
|
crypt to do approximately 2640 crypts
|
|
a CPU second and MD5 to do about 62 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
|
|
.Tn DES
|
|
key as follows:
|
|
the first group of 56 bits becomes the initial
|
|
.Tn DES
|
|
key.
|
|
For each additional group, the XOR of the encryption of the current
|
|
.Tn DES
|
|
key with itself and the group bits becomes the next
|
|
.Tn 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
|
|
The
|
|
.Fa salt
|
|
introduces disorder in the
|
|
.Tn DES
|
|
algorithm in one of 16777216 or 4096 possible ways
|
|
(ie. with 24 or 12 bits: if bit
|
|
.Em i
|
|
of the
|
|
.Ar salt
|
|
is set, then bits
|
|
.Em i
|
|
and
|
|
.Em i+24
|
|
are swapped in the
|
|
.Tn DES
|
|
E-box output).
|
|
.Pp
|
|
The
|
|
.Tn DES
|
|
key is used to encrypt a 64-bit constant using
|
|
.Ar count
|
|
iterations of
|
|
.Tn DES .
|
|
The value returned is a
|
|
.Dv null Ns -terminated
|
|
string, 20 or 13 bytes (plus null) in length, consisting of the
|
|
.Ar salt
|
|
followed by the encoded 64-bit encryption.
|
|
.Ss "Modular" crypt:
|
|
.Pp
|
|
If the salt begins with the string
|
|
.Fa $digit$
|
|
then the Modular Crypt Format is used. The
|
|
.Fa digit
|
|
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 algorithms are:
|
|
.Pp
|
|
.Bl -tag -width 012345678 -compact -offset indent
|
|
.It 1
|
|
MD5
|
|
.El
|
|
.Pp
|
|
Other crypt formats may be easilly added. An example salt would be:
|
|
.Bl -tag -offset indent
|
|
.It Cm "$3$thesalt$rest"
|
|
.El
|
|
.Pp
|
|
.Ss "Traditional" crypt:
|
|
.Pp
|
|
The algorithm used will depend upon whether
|
|
.Fn crypt_set_format
|
|
has been called and whether a global default format has been specified.
|
|
Unless a global default has been specified or
|
|
.Fn crypt_set_format
|
|
has set the format to something else, the best algorithm is used
|
|
which is currently
|
|
.\"
|
|
.\" NOTICE: Also make sure to update this
|
|
.\"
|
|
MD5.
|
|
.Pp
|
|
How the salt is used will depend upon the algorithm for the hash. For
|
|
best results, specify at least two characters of salt.
|
|
.Pp
|
|
The
|
|
.Fn crypt_get_format
|
|
function returns a constant string that represents the name of the
|
|
algorithm currently used.
|
|
Valid values are
|
|
.\"
|
|
.\" NOTICE: Also make sure to update this, too, as well
|
|
.\"
|
|
.Ql des
|
|
and
|
|
.Ql md5 .
|
|
.Pp
|
|
The
|
|
.Fn crypt_set_format
|
|
function sets the default encoding format according to the supplied
|
|
.Fa string .
|
|
.Pp
|
|
The global default format can be set using the
|
|
.Pa /etc/auth.conf
|
|
file using the
|
|
.Ql crypt_format
|
|
property.
|
|
.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 crypt_set_format
|
|
will return 1 if the supplied encoding format was valid.
|
|
Otherwise, a value of 0 is returned.
|
|
.Sh SEE ALSO
|
|
.Xr login 1 ,
|
|
.Xr passwd 1 ,
|
|
.Xr auth_getval 3 ,
|
|
.Xr cipher 3 ,
|
|
.Xr getpass 3 ,
|
|
.Xr auth.conf 5 ,
|
|
.Xr passwd 5 ,
|
|
.Sh BUGS
|
|
The
|
|
.Fn crypt
|
|
function returns a pointer to static data, and subsequent calls to
|
|
.Fn crypt
|
|
will modify the same data. Likewise,
|
|
.Fn crypt_set_format
|
|
modifies static data.
|
|
.Sh HISTORY
|
|
A rotor-based
|
|
.Fn crypt
|
|
function appeared in
|
|
.At v6 .
|
|
The current style
|
|
.Fn crypt
|
|
first appeared in
|
|
.At v7 .
|
|
.Pp
|
|
The
|
|
.Tn 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
|
|
.Nx
|
|
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
|
|
.An -nosplit
|
|
Originally written by
|
|
.An David Burren Aq davidb@werj.com.au ,
|
|
later additions and changes by
|
|
.An Poul-Henning Kamp ,
|
|
.An Mark R V Murray ,
|
|
.An Kris Kennaway
|
|
and
|
|
.An Brian Feldman .
|