xref: /freebsd/lib/libcrypt/crypt.3 (revision f32b1300128afc5171f0a0e0a8489a0850ede5a0)
1e9a56ad5SMark Murray.\" FreeSec: libcrypt for NetBSD
2e9a56ad5SMark Murray.\"
3e9a56ad5SMark Murray.\" Copyright (c) 1994 David Burren
4e9a56ad5SMark Murray.\" All rights reserved.
5e9a56ad5SMark Murray.\"
6e9a56ad5SMark Murray.\" Redistribution and use in source and binary forms, with or without
7e9a56ad5SMark Murray.\" modification, are permitted provided that the following conditions
8e9a56ad5SMark Murray.\" are met:
9e9a56ad5SMark Murray.\" 1. Redistributions of source code must retain the above copyright
10e9a56ad5SMark Murray.\"    notice, this list of conditions and the following disclaimer.
11e9a56ad5SMark Murray.\" 2. Redistributions in binary form must reproduce the above copyright
12e9a56ad5SMark Murray.\"    notice, this list of conditions and the following disclaimer in the
13e9a56ad5SMark Murray.\"    documentation and/or other materials provided with the distribution.
14e9a56ad5SMark Murray.\" 4. Neither the name of the author nor the names of other contributors
15e9a56ad5SMark Murray.\"    may be used to endorse or promote products derived from this software
16e9a56ad5SMark Murray.\"    without specific prior written permission.
17e9a56ad5SMark Murray.\"
18e9a56ad5SMark Murray.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
19e9a56ad5SMark Murray.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20e9a56ad5SMark Murray.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21e9a56ad5SMark Murray.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
22e9a56ad5SMark Murray.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23e9a56ad5SMark Murray.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24e9a56ad5SMark Murray.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25e9a56ad5SMark Murray.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26e9a56ad5SMark Murray.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27e9a56ad5SMark Murray.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28e9a56ad5SMark Murray.\" SUCH DAMAGE.
29e9a56ad5SMark Murray.\"
30e9a56ad5SMark Murray.\"	$FreeBSD$
31e9a56ad5SMark Murray.\"
32e9a56ad5SMark Murray.\" Manual page, using -mandoc macros
33e9a56ad5SMark Murray.\"
34e9a56ad5SMark Murray.Dd January 19, 1997
35e9a56ad5SMark Murray.Dt CRYPT 3
36e9a56ad5SMark Murray.Os "FreeSec 1.0"
37e9a56ad5SMark Murray.Sh NAME
38e9a56ad5SMark Murray.Nm crypt
39e9a56ad5SMark Murray.Nd Trapdoor encryption
40f45f23ddSAlexey Zelkin.Sh LIBRARY
41f45f23ddSAlexey Zelkin.Lb libcrypt
42e9a56ad5SMark Murray.Sh SYNOPSIS
43f92c744fSBruce Evans.Fd #include <unistd.h>
44d3f0d184SBruce Evans.Ft char *
45d3f0d184SBruce Evans.Fn crypt "const char *key" "const char *salt"
46e9a56ad5SMark Murray.Sh DESCRIPTION
47e9a56ad5SMark MurrayThe
48e9a56ad5SMark Murray.Fn crypt
49e9a56ad5SMark Murrayfunction performs password hashing with additional code added to
50e9a56ad5SMark Murraydeter key search attempts.  Different algorithms can be used to
51e9a56ad5SMark Murrayin the hash.
52e9a56ad5SMark Murray.\"
53e9a56ad5SMark Murray.\" NOTICE:
54e9a56ad5SMark Murray.\" If you add more algorithms, make sure to update this list
55e9a56ad5SMark Murray.\" and the default used for the Traditional format, below.
56e9a56ad5SMark Murray.\"
57e9a56ad5SMark MurrayCurrently these include the
58e9a56ad5SMark Murray.Tn NBS
59f45f23ddSAlexey Zelkin.Tn Data Encryption Standard (DES) ,
60f32b1300SKris Kennawayand
61f32b1300SKris Kennaway.Tn MD5 .
62f45f23ddSAlexey ZelkinThe algorithm used will depend upon the format of the Salt--following
63f45f23ddSAlexey Zelkinthe Modular Crypt Format (MCF)--and if
64f45f23ddSAlexey Zelkin.Tn DES
65f45f23ddSAlexey Zelkinis installed or not.
66e9a56ad5SMark Murray.Pp
67e9a56ad5SMark MurrayThe first argument to
68f45f23ddSAlexey Zelkin.Nm
69e9a56ad5SMark Murrayis the data to hash (usually a password), in a
70e9a56ad5SMark Murray.Dv null Ns -terminated
71e9a56ad5SMark Murraystring.
72e9a56ad5SMark MurrayThe second is the salt, in one of three forms:
73e9a56ad5SMark Murray.Pp
74e9a56ad5SMark Murray.Bl -tag -width Traditional -compact -offset indent
75e9a56ad5SMark Murray.It Extended
76f45f23ddSAlexey ZelkinIf it begins with an underscore
77f45f23ddSAlexey Zelkin.Pq Dq _
78f45f23ddSAlexey Zelkinthen the
79f45f23ddSAlexey Zelkin.Tn DES
80f45f23ddSAlexey ZelkinExtended Format
81e9a56ad5SMark Murrayis used in interpreting both the the key and the salt, as outlined below.
82e9a56ad5SMark Murray.It Modular
83f45f23ddSAlexey ZelkinIf it begins with the string
84f45f23ddSAlexey Zelkin.Dq $digit$
85f45f23ddSAlexey Zelkinthen the Modular Crypt Format is used, as outlined below.
86e9a56ad5SMark Murray.It Traditional
87e9a56ad5SMark MurrayIf neither of the above is true, it assumes the Traditional Format,
88e9a56ad5SMark Murrayusing the entire string as the salt (or the first portion).
89e9a56ad5SMark Murray.El
90e9a56ad5SMark Murray.Pp
91e9a56ad5SMark MurrayAll routines are designed to be time-consuming.  A brief test on a
92f45f23ddSAlexey Zelkin.Tn Pentium
93f45f23ddSAlexey Zelkin166/MMX shows the
94f45f23ddSAlexey Zelkin.Tn DES
95f45f23ddSAlexey Zelkincrypt to do approximately 2640 crypts
9600587201SMark Murraya CPU second and MD5 to do about 62 crypts a CPU second.
97e9a56ad5SMark Murray.Ss DES Extended Format:
98e9a56ad5SMark Murray.Pp
99e9a56ad5SMark MurrayThe
100e9a56ad5SMark Murray.Ar key
101e9a56ad5SMark Murrayis divided into groups of 8 characters (the last group is null-padded)
102e9a56ad5SMark Murrayand the low-order 7 bits of each each character (56 bits per group) are
103f45f23ddSAlexey Zelkinused to form the
104f45f23ddSAlexey Zelkin.Tn DES
105f45f23ddSAlexey Zelkinkey as follows:
106f45f23ddSAlexey Zelkinthe first group of 56 bits becomes the initial
107f45f23ddSAlexey Zelkin.Tn DES
108f45f23ddSAlexey Zelkinkey.
109f45f23ddSAlexey ZelkinFor each additional group, the XOR of the encryption of the current
110f45f23ddSAlexey Zelkin.Tn DES
111f45f23ddSAlexey Zelkinkey with itself and the group bits becomes the next
112f45f23ddSAlexey Zelkin.Tn DES
113f45f23ddSAlexey Zelkinkey.
114e9a56ad5SMark Murray.Pp
115e9a56ad5SMark MurrayThe salt is a 9-character array consisting of an underscore followed
116e9a56ad5SMark Murrayby 4 bytes of iteration count and 4 bytes of salt.
117e9a56ad5SMark MurrayThese are encoded as printable characters, 6 bits per character,
118e9a56ad5SMark Murrayleast significant character first.
119e9a56ad5SMark MurrayThe values 0 to 63 are encoded as ``./0-9A-Za-z''.
120e9a56ad5SMark MurrayThis allows 24 bits for both
121e9a56ad5SMark Murray.Fa count
122e9a56ad5SMark Murrayand
123e9a56ad5SMark Murray.Fa salt .
124e9a56ad5SMark Murray.Pp
125e9a56ad5SMark MurrayThe
126e9a56ad5SMark Murray.Fa salt
127e9a56ad5SMark Murrayintroduces disorder in the
128e9a56ad5SMark Murray.Tn DES
129e9a56ad5SMark Murrayalgorithm in one of 16777216 or 4096 possible ways
130e9a56ad5SMark Murray(ie. with 24 or 12 bits: if bit
131e9a56ad5SMark Murray.Em i
132e9a56ad5SMark Murrayof the
133e9a56ad5SMark Murray.Ar salt
134e9a56ad5SMark Murrayis set, then bits
135e9a56ad5SMark Murray.Em i
136e9a56ad5SMark Murrayand
137e9a56ad5SMark Murray.Em i+24
138e9a56ad5SMark Murrayare swapped in the
139e9a56ad5SMark Murray.Tn DES
140e9a56ad5SMark MurrayE-box output).
141e9a56ad5SMark Murray.Pp
142f45f23ddSAlexey ZelkinThe
143f45f23ddSAlexey Zelkin.Tn DES
144f45f23ddSAlexey Zelkinkey is used to encrypt a 64-bit constant using
145e9a56ad5SMark Murray.Ar count
146e9a56ad5SMark Murrayiterations of
147e9a56ad5SMark Murray.Tn DES .
148e9a56ad5SMark MurrayThe value returned is a
149e9a56ad5SMark Murray.Dv null Ns -terminated
150e9a56ad5SMark Murraystring, 20 or 13 bytes (plus null) in length, consisting of the
151e9a56ad5SMark Murray.Ar salt
152e9a56ad5SMark Murrayfollowed by the encoded 64-bit encryption.
153e9a56ad5SMark Murray.Ss "Modular" crypt:
154e9a56ad5SMark Murray.Pp
155e9a56ad5SMark MurrayIf the salt begins with the string
156e9a56ad5SMark Murray.Fa $digit$
157e9a56ad5SMark Murraythen the Modular Crypt Format is used.  The
158e9a56ad5SMark Murray.Fa digit
159e9a56ad5SMark Murrayrepresents which algorithm is used in encryption.  Following the token is
160e9a56ad5SMark Murraythe actual salt to use in the encryption.  The length of the salt is limited
161e9a56ad5SMark Murrayto 16 characters--because the length of the returned output is also limited
162e9a56ad5SMark Murray(_PASSWORD_LEN).  The salt must be terminated with the end of the string
163e9a56ad5SMark Murray(NULL) or a dollar sign.  Any characters after the dollar sign are ignored.
164e9a56ad5SMark Murray.Pp
165e9a56ad5SMark MurrayCurrently supported algorithms are:
166e9a56ad5SMark Murray.Pp
167e9a56ad5SMark Murray.Bl -tag -width 012345678 -compact -offset indent
168e9a56ad5SMark Murray.It 1
169e9a56ad5SMark MurrayMD5
170e9a56ad5SMark Murray.El
171e9a56ad5SMark Murray.Pp
172e9a56ad5SMark MurrayOther crypt formats may be easilly added.  An example salt would be:
173e9a56ad5SMark Murray.Bl -tag -offset indent
174e9a56ad5SMark Murray.It Cm "$3$thesalt$rest"
175e9a56ad5SMark Murray.El
176e9a56ad5SMark Murray.Pp
177e9a56ad5SMark Murray.Ss "Traditional" crypt:
178e9a56ad5SMark Murray.Pp
179f45f23ddSAlexey ZelkinThe algorithm used will depend upon whether
180f45f23ddSAlexey Zelkin.Tn DES
181f45f23ddSAlexey Zelkinis installed or not.  If it is,
182f45f23ddSAlexey Zelkin.Tn DES
183f45f23ddSAlexey Zelkinwill be used.  Otherwise, the best algorithm is used, which is currently
184e9a56ad5SMark Murray.\"
185e9a56ad5SMark Murray.\" NOTICE: Also make sure to update this
186e9a56ad5SMark Murray.\"
18700587201SMark MurrayMD5.
188e9a56ad5SMark Murray.Pp
189e9a56ad5SMark MurrayHow the salt is used will depend upon the algorithm for the hash.  For
190e9a56ad5SMark Murraybest results, specify at least two characters of salt.
191e9a56ad5SMark Murray.Sh RETURN VALUES
192e9a56ad5SMark Murray.Pp
193e9a56ad5SMark Murray.Fn crypt
194e9a56ad5SMark Murrayreturns a pointer to the encrypted value on success, and NULL on failure.
195e9a56ad5SMark MurrayNote: this is not a standard behaviour, AT&T
196e9a56ad5SMark Murray.Fn crypt
197e9a56ad5SMark Murraywill always return a pointer to a string.
198e9a56ad5SMark Murray.Sh SEE ALSO
199e9a56ad5SMark Murray.Xr login 1 ,
200e9a56ad5SMark Murray.Xr passwd 1 ,
20100587201SMark Murray.Xr cipher 3 ,
202e9a56ad5SMark Murray.Xr getpass 3 ,
203e9a56ad5SMark Murray.Xr passwd 5 ,
204e9a56ad5SMark Murray.Sh BUGS
205e9a56ad5SMark MurrayThe
206e9a56ad5SMark Murray.Fn crypt
207e9a56ad5SMark Murrayfunction returns a pointer to static data, and subsequent calls to
208e9a56ad5SMark Murray.Fn crypt
209e9a56ad5SMark Murraywill modify the same data.
210e9a56ad5SMark Murray.Sh HISTORY
211e9a56ad5SMark MurrayA rotor-based
212e9a56ad5SMark Murray.Fn crypt
213e9a56ad5SMark Murrayfunction appeared in
214e9a56ad5SMark Murray.At v6 .
215e9a56ad5SMark MurrayThe current style
216e9a56ad5SMark Murray.Fn crypt
217e9a56ad5SMark Murrayfirst appeared in
218e9a56ad5SMark Murray.At v7 .
219e9a56ad5SMark Murray.Pp
220f45f23ddSAlexey ZelkinThe
221f45f23ddSAlexey Zelkin.Tn DES
222f45f23ddSAlexey Zelkinsection of the code (FreeSec 1.0) was developed outside the United
223f45f23ddSAlexey ZelkinStates of America as an unencumbered replacement for the U.S.-only
224f45f23ddSAlexey Zelkin.Nx
225e9a56ad5SMark Murraylibcrypt encryption library.
226e9a56ad5SMark MurrayUsers should be aware that this code (and programs staticly linked with it)
227e9a56ad5SMark Murraymay not be exported from the U.S., although it apparently can be imported.
228e9a56ad5SMark Murray.Sh AUTHORS
229f45f23ddSAlexey ZelkinOriginally written by
230f45f23ddSAlexey Zelkin.An David Burren Aq davidb@werj.com.au ,
231f45f23ddSAlexey Zelkinlater additions and changes by
232f45f23ddSAlexey Zelkin.An Poul-henning Kamp ,
233f45f23ddSAlexey Zelkin.An Mark R V Murray
234f45f23ddSAlexey Zelkinand
235f45f23ddSAlexey Zelkin.An Kris Kennaway .
236