xref: /freebsd/lib/libcrypt/crypt.3 (revision a5c28e29e2f183ac36013a51c06bc24a33fb92a5)
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.\"
32*a5c28e29SMark Murray.Dd April 9, 2011
33e9a56ad5SMark Murray.Dt CRYPT 3
34a307d598SRuslan Ermilov.Os
35e9a56ad5SMark Murray.Sh NAME
36e9a56ad5SMark Murray.Nm crypt
37e9a56ad5SMark Murray.Nd Trapdoor encryption
38f45f23ddSAlexey Zelkin.Sh LIBRARY
39f45f23ddSAlexey Zelkin.Lb libcrypt
40e9a56ad5SMark Murray.Sh SYNOPSIS
4132eef9aeSRuslan Ermilov.In unistd.h
42d3f0d184SBruce Evans.Ft char *
43d3f0d184SBruce Evans.Fn crypt "const char *key" "const char *salt"
4404c9749fSBrian Feldman.Ft const char *
4504c9749fSBrian Feldman.Fn crypt_get_format "void"
4604c9749fSBrian Feldman.Ft int
4704c9749fSBrian Feldman.Fn crypt_set_format "const char *string"
48e9a56ad5SMark Murray.Sh DESCRIPTION
49e9a56ad5SMark MurrayThe
50e9a56ad5SMark Murray.Fn crypt
51e9a56ad5SMark Murrayfunction performs password hashing with additional code added to
521a0a9345SRuslan Ermilovdeter key search attempts.
531a0a9345SRuslan ErmilovDifferent algorithms can be used to
54e9a56ad5SMark Murrayin the hash.
55e9a56ad5SMark Murray.\"
56e9a56ad5SMark Murray.\" NOTICE:
57e9a56ad5SMark Murray.\" If you add more algorithms, make sure to update this list
58e9a56ad5SMark Murray.\" and the default used for the Traditional format, below.
59e9a56ad5SMark Murray.\"
60e9a56ad5SMark MurrayCurrently these include the
61e9a56ad5SMark Murray.Tn NBS
62f45f23ddSAlexey Zelkin.Tn Data Encryption Standard (DES) ,
635c129616SMark Murray.Tn MD5
64bf513f69SMark Murrayhash,
65bf513f69SMark Murray.Tn NT-Hash
66bf513f69SMark Murray(compatible with Microsoft's NT scheme)
67f32b1300SKris Kennawayand
685c129616SMark Murray.Tn Blowfish .
6904c9749fSBrian FeldmanThe algorithm used will depend upon the format of the Salt (following
7004c9749fSBrian Feldmanthe Modular Crypt Format (MCF)), if
71f45f23ddSAlexey Zelkin.Tn DES
725c129616SMark Murrayand/or
735c129616SMark Murray.Tn Blowfish
7404c9749fSBrian Feldmanis installed or not, and whether
7504c9749fSBrian Feldman.Fn crypt_set_format
7604c9749fSBrian Feldmanhas been called to change the default.
77e9a56ad5SMark Murray.Pp
78e9a56ad5SMark MurrayThe first argument to
79f45f23ddSAlexey Zelkin.Nm
80e9a56ad5SMark Murrayis the data to hash (usually a password), in a
81e9a56ad5SMark Murray.Dv null Ns -terminated
82e9a56ad5SMark Murraystring.
83e9a56ad5SMark MurrayThe second is the salt, in one of three forms:
84e9a56ad5SMark Murray.Pp
85e9a56ad5SMark Murray.Bl -tag -width Traditional -compact -offset indent
86e9a56ad5SMark Murray.It Extended
87f45f23ddSAlexey ZelkinIf it begins with an underscore
88f45f23ddSAlexey Zelkin.Pq Dq _
89f45f23ddSAlexey Zelkinthen the
90f45f23ddSAlexey Zelkin.Tn DES
91f45f23ddSAlexey ZelkinExtended Format
92a910f192SDima Dorfmanis used in interpreting both the key and the salt, as outlined below.
93e9a56ad5SMark Murray.It Modular
94f45f23ddSAlexey ZelkinIf it begins with the string
95f45f23ddSAlexey Zelkin.Dq $digit$
96f45f23ddSAlexey Zelkinthen the Modular Crypt Format is used, as outlined below.
97e9a56ad5SMark Murray.It Traditional
98e9a56ad5SMark MurrayIf neither of the above is true, it assumes the Traditional Format,
99e9a56ad5SMark Murrayusing the entire string as the salt (or the first portion).
100e9a56ad5SMark Murray.El
101e9a56ad5SMark Murray.Pp
1021a0a9345SRuslan ErmilovAll routines are designed to be time-consuming.
1031a0a9345SRuslan ErmilovA brief test on a
104f45f23ddSAlexey Zelkin.Tn Pentium
105f45f23ddSAlexey Zelkin166/MMX shows the
106f45f23ddSAlexey Zelkin.Tn DES
107f45f23ddSAlexey Zelkincrypt to do approximately 2640 crypts
10800587201SMark Murraya CPU second and MD5 to do about 62 crypts a CPU second.
109e9a56ad5SMark Murray.Ss DES Extended Format:
110e9a56ad5SMark Murray.Pp
111e9a56ad5SMark MurrayThe
112e9a56ad5SMark Murray.Ar key
113e9a56ad5SMark Murrayis divided into groups of 8 characters (the last group is null-padded)
114a910f192SDima Dorfmanand the low-order 7 bits of each character (56 bits per group) are
115f45f23ddSAlexey Zelkinused to form the
116f45f23ddSAlexey Zelkin.Tn DES
117f45f23ddSAlexey Zelkinkey as follows:
118f45f23ddSAlexey Zelkinthe first group of 56 bits becomes the initial
119f45f23ddSAlexey Zelkin.Tn DES
120f45f23ddSAlexey Zelkinkey.
121f45f23ddSAlexey ZelkinFor each additional group, the XOR of the encryption of the current
122f45f23ddSAlexey Zelkin.Tn DES
123f45f23ddSAlexey Zelkinkey with itself and the group bits becomes the next
124f45f23ddSAlexey Zelkin.Tn DES
125f45f23ddSAlexey Zelkinkey.
126e9a56ad5SMark Murray.Pp
127e9a56ad5SMark MurrayThe salt is a 9-character array consisting of an underscore followed
128e9a56ad5SMark Murrayby 4 bytes of iteration count and 4 bytes of salt.
129e9a56ad5SMark MurrayThese are encoded as printable characters, 6 bits per character,
130e9a56ad5SMark Murrayleast significant character first.
131e9a56ad5SMark MurrayThe values 0 to 63 are encoded as ``./0-9A-Za-z''.
132e9a56ad5SMark MurrayThis allows 24 bits for both
133e9a56ad5SMark Murray.Fa count
134e9a56ad5SMark Murrayand
135e9a56ad5SMark Murray.Fa salt .
136e9a56ad5SMark Murray.Pp
137e9a56ad5SMark MurrayThe
138e9a56ad5SMark Murray.Fa salt
139e9a56ad5SMark Murrayintroduces disorder in the
140e9a56ad5SMark Murray.Tn DES
141e9a56ad5SMark Murrayalgorithm in one of 16777216 or 4096 possible ways
1421a0a9345SRuslan Ermilov(i.e., with 24 or 12 bits: if bit
143e9a56ad5SMark Murray.Em i
144e9a56ad5SMark Murrayof the
145e9a56ad5SMark Murray.Ar salt
146e9a56ad5SMark Murrayis set, then bits
147e9a56ad5SMark Murray.Em i
148e9a56ad5SMark Murrayand
149e9a56ad5SMark Murray.Em i+24
150e9a56ad5SMark Murrayare swapped in the
151e9a56ad5SMark Murray.Tn DES
152e9a56ad5SMark MurrayE-box output).
153e9a56ad5SMark Murray.Pp
154f45f23ddSAlexey ZelkinThe
155f45f23ddSAlexey Zelkin.Tn DES
156f45f23ddSAlexey Zelkinkey is used to encrypt a 64-bit constant using
157e9a56ad5SMark Murray.Ar count
158e9a56ad5SMark Murrayiterations of
159e9a56ad5SMark Murray.Tn DES .
160e9a56ad5SMark MurrayThe value returned is a
161e9a56ad5SMark Murray.Dv null Ns -terminated
162e9a56ad5SMark Murraystring, 20 or 13 bytes (plus null) in length, consisting of the
163e9a56ad5SMark Murray.Ar salt
164e9a56ad5SMark Murrayfollowed by the encoded 64-bit encryption.
165e9a56ad5SMark Murray.Ss "Modular" crypt:
166e9a56ad5SMark Murray.Pp
167e9a56ad5SMark MurrayIf the salt begins with the string
168e9a56ad5SMark Murray.Fa $digit$
1691a0a9345SRuslan Ermilovthen the Modular Crypt Format is used.
1701a0a9345SRuslan ErmilovThe
171e9a56ad5SMark Murray.Fa digit
1721a0a9345SRuslan Ermilovrepresents which algorithm is used in encryption.
1731a0a9345SRuslan ErmilovFollowing the token is
1741a0a9345SRuslan Ermilovthe actual salt to use in the encryption.
1751a0a9345SRuslan ErmilovThe length of the salt is limited
17696f68db5STom Rhodesto 8 characters--because the length of the returned output is also limited
1771a0a9345SRuslan Ermilov(_PASSWORD_LEN).
1781a0a9345SRuslan ErmilovThe salt must be terminated with the end of the string
1791a0a9345SRuslan Ermilov(NULL) or a dollar sign.
1801a0a9345SRuslan ErmilovAny characters after the dollar sign are ignored.
181e9a56ad5SMark Murray.Pp
182e9a56ad5SMark MurrayCurrently supported algorithms are:
183e9a56ad5SMark Murray.Pp
18442635956SRuslan Ermilov.Bl -enum -compact -offset indent
185067f2c3fSRuslan Ermilov.It
186e9a56ad5SMark MurrayMD5
187067f2c3fSRuslan Ermilov.It
1885c129616SMark MurrayBlowfish
189bf513f69SMark Murray.It
190bf513f69SMark MurrayNT-Hash
191*a5c28e29SMark Murray.It
192*a5c28e29SMark MurraySHA-256
193*a5c28e29SMark Murray.It
194*a5c28e29SMark MurraySHA-512
195e9a56ad5SMark Murray.El
196e9a56ad5SMark Murray.Pp
1971a0a9345SRuslan ErmilovOther crypt formats may be easily added.
1981a0a9345SRuslan ErmilovAn example salt would be:
199e9a56ad5SMark Murray.Bl -tag -offset indent
200bf513f69SMark Murray.It Cm "$4$thesalt$rest"
201e9a56ad5SMark Murray.El
202e9a56ad5SMark Murray.Pp
203e9a56ad5SMark Murray.Ss "Traditional" crypt:
204e9a56ad5SMark Murray.Pp
205f45f23ddSAlexey ZelkinThe algorithm used will depend upon whether
20604c9749fSBrian Feldman.Fn crypt_set_format
2079886bcdfSPeter Wemmhas been called and whether a global default format has been specified.
2089886bcdfSPeter WemmUnless a global default has been specified or
20904c9749fSBrian Feldman.Fn crypt_set_format
21088b471a1SPeter Wemmhas set the format to something else, the built-in default format is
21188b471a1SPeter Wemmused.
21288b471a1SPeter WemmThis is currently
213e9a56ad5SMark Murray.\"
214e9a56ad5SMark Murray.\" NOTICE: Also make sure to update this
215e9a56ad5SMark Murray.\"
21688b471a1SPeter WemmDES
21788b471a1SPeter Wemmif it is available, or MD5 if not.
218e9a56ad5SMark Murray.Pp
2191a0a9345SRuslan ErmilovHow the salt is used will depend upon the algorithm for the hash.
2201a0a9345SRuslan ErmilovFor
221e9a56ad5SMark Murraybest results, specify at least two characters of salt.
22204c9749fSBrian Feldman.Pp
22304c9749fSBrian FeldmanThe
22404c9749fSBrian Feldman.Fn crypt_get_format
22504c9749fSBrian Feldmanfunction returns a constant string that represents the name of the
22604c9749fSBrian Feldmanalgorithm currently used.
22704c9749fSBrian FeldmanValid values are
22804c9749fSBrian Feldman.\"
22904c9749fSBrian Feldman.\" NOTICE: Also make sure to update this, too, as well
23004c9749fSBrian Feldman.\"
2315c129616SMark Murray.Ql des ,
232bf513f69SMark Murray.Ql blf ,
233*a5c28e29SMark Murray.Ql md5 ,
234*a5c28e29SMark Murray.Ql sha256 ,
235*a5c28e29SMark Murray.Ql sha512
23604c9749fSBrian Feldmanand
237bf513f69SMark Murray.Ql nth .
23804c9749fSBrian Feldman.Pp
23904c9749fSBrian FeldmanThe
24004c9749fSBrian Feldman.Fn crypt_set_format
24104c9749fSBrian Feldmanfunction sets the default encoding format according to the supplied
24204c9749fSBrian Feldman.Fa string .
2439886bcdfSPeter Wemm.Pp
2449886bcdfSPeter WemmThe global default format can be set using the
2459886bcdfSPeter Wemm.Pa /etc/auth.conf
2469886bcdfSPeter Wemmfile using the
2473ea75eb1SRuslan Ermilov.Va crypt_default
2489886bcdfSPeter Wemmproperty.
249e9a56ad5SMark Murray.Sh RETURN VALUES
250e4f2c10bSPhilippe CharnierThe
251e9a56ad5SMark Murray.Fn crypt
252e4f2c10bSPhilippe Charnierfunction returns a pointer to the encrypted value on success, and NULL on
253e4f2c10bSPhilippe Charnierfailure.
254e9a56ad5SMark MurrayNote: this is not a standard behaviour, AT&T
255e9a56ad5SMark Murray.Fn crypt
256e9a56ad5SMark Murraywill always return a pointer to a string.
25704c9749fSBrian Feldman.Pp
258e4f2c10bSPhilippe CharnierThe
25904c9749fSBrian Feldman.Fn crypt_set_format
260e4f2c10bSPhilippe Charnierfunction will return 1 if the supplied encoding format was valid.
26104c9749fSBrian FeldmanOtherwise, a value of 0 is returned.
262e9a56ad5SMark Murray.Sh SEE ALSO
263e9a56ad5SMark Murray.Xr login 1 ,
264e9a56ad5SMark Murray.Xr passwd 1 ,
2659886bcdfSPeter Wemm.Xr auth_getval 3 ,
266e9a56ad5SMark Murray.Xr getpass 3 ,
2679886bcdfSPeter Wemm.Xr auth.conf 5 ,
268eb894267SRuslan Ermilov.Xr passwd 5
269e9a56ad5SMark Murray.Sh HISTORY
270e9a56ad5SMark MurrayA rotor-based
271e9a56ad5SMark Murray.Fn crypt
272e9a56ad5SMark Murrayfunction appeared in
273e9a56ad5SMark Murray.At v6 .
274e9a56ad5SMark MurrayThe current style
275e9a56ad5SMark Murray.Fn crypt
276e9a56ad5SMark Murrayfirst appeared in
277e9a56ad5SMark Murray.At v7 .
278e9a56ad5SMark Murray.Pp
279f45f23ddSAlexey ZelkinThe
280f45f23ddSAlexey Zelkin.Tn DES
281f45f23ddSAlexey Zelkinsection of the code (FreeSec 1.0) was developed outside the United
282f45f23ddSAlexey ZelkinStates of America as an unencumbered replacement for the U.S.-only
283f45f23ddSAlexey Zelkin.Nx
284e9a56ad5SMark Murraylibcrypt encryption library.
285e9a56ad5SMark Murray.Sh AUTHORS
286725ab628SRuslan Ermilov.An -nosplit
287f45f23ddSAlexey ZelkinOriginally written by
288f45f23ddSAlexey Zelkin.An David Burren Aq davidb@werj.com.au ,
289f45f23ddSAlexey Zelkinlater additions and changes by
290725ab628SRuslan Ermilov.An Poul-Henning Kamp ,
29104c9749fSBrian Feldman.An Mark R V Murray ,
292bf513f69SMark Murray.An Michael Bretterklieber ,
2935c129616SMark Murray.An Kris Kennaway ,
2945c129616SMark Murray.An Brian Feldman ,
2955c129616SMark Murray.An Paul Herman
29604c9749fSBrian Feldmanand
2975c129616SMark Murray.An Niels Provos .
29824a0682cSRuslan Ermilov.Sh BUGS
29924a0682cSRuslan ErmilovThe
30024a0682cSRuslan Ermilov.Fn crypt
30124a0682cSRuslan Ermilovfunction returns a pointer to static data, and subsequent calls to
30224a0682cSRuslan Ermilov.Fn crypt
30324a0682cSRuslan Ermilovwill modify the same data.
30424a0682cSRuslan ErmilovLikewise,
30524a0682cSRuslan Ermilov.Fn crypt_set_format
30624a0682cSRuslan Ermilovmodifies static data.
30724a0682cSRuslan Ermilov.Pp
30824a0682cSRuslan ErmilovThe NT-hash scheme does not use a salt,
30924a0682cSRuslan Ermilovand is not hard
31024a0682cSRuslan Ermilovfor a competent attacker
31124a0682cSRuslan Ermilovto break.
31224a0682cSRuslan ErmilovIts use is not recommended.
313