summaryrefslogtreecommitdiff
path: root/src/lib/libc/crypt/crypt.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libc/crypt/crypt.3')
-rw-r--r--src/lib/libc/crypt/crypt.3318
1 files changed, 0 insertions, 318 deletions
diff --git a/src/lib/libc/crypt/crypt.3 b/src/lib/libc/crypt/crypt.3
deleted file mode 100644
index f4a78781da..0000000000
--- a/src/lib/libc/crypt/crypt.3
+++ /dev/null
@@ -1,318 +0,0 @@
1.\" $OpenBSD: crypt.3,v 1.34 2014/03/19 02:34:45 tedu Exp $
2.\"
3.\" FreeSec: libcrypt
4.\"
5.\" Copyright (c) 1994 David Burren
6.\" All rights reserved.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\" notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\" notice, this list of conditions and the following disclaimer in the
15.\" documentation and/or other materials provided with the distribution.
16.\" 4. Neither the name of the author nor the names of other contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" Manual page, using -mandoc macros
33.\"
34.Dd $Mdocdate: March 19 2014 $
35.Dt CRYPT 3
36.Os
37.Sh NAME
38.Nm crypt ,
39.Nm setkey ,
40.Nm encrypt ,
41.Nm des_setkey ,
42.Nm des_cipher ,
43.Nm bcrypt_gensalt ,
44.Nm bcrypt ,
45.Nm md5crypt
46.Nd password hashing
47.Sh SYNOPSIS
48.In stdlib.h
49.Ft int
50.Fn setkey "const char *key"
51.Pp
52.In unistd.h
53.Ft char *
54.Fn crypt "const char *key" "const char *setting"
55.Ft int
56.Fn encrypt "char *block" "int flag"
57.Ft int
58.Fn des_setkey "const char *key"
59.Ft int
60.Fn des_cipher "const char *in" "char *out" "int32_t salt" "int count"
61.In pwd.h
62.Ft char *
63.Fn bcrypt_gensalt "u_int8_t log_rounds"
64.Ft char *
65.Fn bcrypt "const char *key" "const char *salt"
66.Ft char *
67.Fn md5crypt "const char *key" "const char *salt"
68.Sh DESCRIPTION
69The
70.Fn crypt
71function performs password hashing based on the
72.Tn NBS
73Data Encryption Standard (DES).
74Additional code has been added to deter key search attempts and to use
75stronger hashing algorithms.
76.Pp
77The first argument to
78.Fn crypt
79is a
80.Dv NUL Ns -terminated
81string, typically a user's typed password.
82The second is in one of three forms:
83if it begins with an underscore
84.Pq Ql _
85then an extended format is used
86in interpreting both the key and the setting, as outlined below.
87If it begins
88with a string character
89.Pq Ql $
90and a number then a different algorithm is used depending on the number.
91At the moment a
92.Ql $1
93chooses MD5 hashing and a
94.Ql $2
95chooses Blowfish hashing; see below for more information.
96.Ss Extended crypt
97The
98.Ar key
99is divided into groups of 8 characters (the last group is null-padded)
100and the low-order 7 bits of each character (56 bits per group) are
101used to form the DES key as follows:
102the first group of 56 bits becomes the initial DES key.
103For each additional group, the XOR of the encryption of the current DES
104key with itself and the group bits becomes the next DES key.
105.Pp
106The setting is a 9-character array consisting of an underscore followed
107by 4 bytes of iteration count and 4 bytes of salt.
108These are encoded as printable characters, 6 bits per character,
109least significant character first.
110The values 0 to 63 are encoded as
111.Dq \&./0-9A-Za-z .
112This allows 24 bits for both
113.Fa count
114and
115.Fa salt .
116.Ss "MD5" crypt
117For
118.Tn MD5
119crypt the version number,
120.Fa salt
121and the hashed password are separated by the
122.Ql $
123character.
124The maximum length of a password is limited by
125the length counter of the MD5 context, which is about
1262**64.
127A valid MD5 password entry looks like this:
128.Pp
129.Dq $1$caeiHQwX$hsKqOjrFRRN6K32OWkCBf1 .
130.Pp
131The whole MD5 password string is passed as
132.Fa setting
133for interpretation.
134.Ss "Blowfish" crypt
135The
136.Tn Blowfish
137version of crypt has 128 bits of
138.Fa salt
139in order to make building dictionaries of common passwords space consuming.
140The initial state of the
141.Tn Blowfish
142cipher is expanded using the
143.Fa salt
144and the
145.Fa password
146repeating the process a variable number of rounds, which is encoded in
147the password string.
148The maximum password length is 72.
149The final Blowfish password entry is created by encrypting the string
150.Pp
151.Dq OrpheanBeholderScryDoubt
152.Pp
153with the
154.Tn Blowfish
155state 64 times.
156.Pp
157The version number, the logarithm of the number of rounds and
158the concatenation of salt and hashed password are separated by the
159.Ql $
160character.
161An encoded
162.Sq 8
163would specify 256 rounds.
164A valid Blowfish password looks like this:
165.Pp
166.Dq $2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC .
167.Pp
168The whole Blowfish password string is passed as
169.Fa setting
170for interpretation.
171.Ss "Traditional" crypt
172The first 8 bytes of the key are null-padded, and the low-order 7 bits of
173each character is used to form the 56-bit
174.Tn DES
175key.
176.Pp
177The setting is a 2-character array of the ASCII-encoded salt.
178Thus only 12 bits of
179.Fa salt
180are used.
181.Fa count
182is set to 25.
183.Ss DES Algorithm
184The
185.Fa salt
186introduces disorder in the
187.Tn DES
188algorithm in one of 16777216 or 4096 possible ways
189(i.e., with 24 or 12 bits: if bit
190.Em i
191of the
192.Ar salt
193is set, then bits
194.Em i
195and
196.Em i+24
197are swapped in the
198.Tn DES
199E-box output).
200.Pp
201The DES key is used to encrypt a 64-bit constant using
202.Ar count
203iterations of
204.Tn DES .
205The value returned is a
206.Dv NUL Ns -terminated
207string, 20 or 13 bytes (plus NUL) in length, consisting of the
208.Ar setting
209followed by the encoded 64-bit encryption.
210.Pp
211The functions
212.Fn encrypt ,
213.Fn setkey ,
214.Fn des_setkey ,
215and
216.Fn des_cipher
217provide access to the
218.Tn DES
219algorithm itself.
220.Fn setkey
221is passed a 64-byte array of binary values (numeric 0 or 1).
222A 56-bit key is extracted from this array by dividing the
223array into groups of 8, and ignoring the last bit in each group.
224That bit is reserved for a byte parity check by DES, but is ignored
225by these functions.
226.Pp
227The
228.Fa block
229argument to
230.Fn encrypt
231is also a 64-byte array of binary values.
232If the value of
233.Fa flag
234is 0,
235.Fa block
236is encrypted otherwise it is decrypted.
237The result is returned in the original array
238.Fa block
239after using the key specified by
240.Fn setkey
241to process it.
242.Pp
243The argument to
244.Fn des_setkey
245is a character array of length 8.
246The least significant bit (the parity bit) in each character is ignored,
247and the remaining bits are concatenated to form a 56-bit key.
248The function
249.Fn des_cipher
250encrypts (or decrypts if
251.Fa count
252is negative) the 64-bits stored in the 8 characters at
253.Fa in
254using
255.Xr abs 3
256of
257.Fa count
258iterations of
259.Tn DES
260and stores the 64-bit result in the 8 characters at
261.Fa out
262(which may be the same as
263.Fa in ) .
264The
265.Fa salt
266specifies perturbations to the
267.Tn DES
268E-box output as described above.
269.Pp
270The
271.Fn crypt ,
272.Fn setkey ,
273and
274.Fn des_setkey
275functions all manipulate the same key space.
276.Sh RETURN VALUES
277The function
278.Fn crypt
279returns a pointer to the encrypted value on success, and
280.Dv NULL
281on failure.
282The functions
283.Fn setkey ,
284.Fn encrypt ,
285.Fn des_setkey ,
286and
287.Fn des_cipher
288return 0 on success and 1 on failure.
289.Sh SEE ALSO
290.Xr encrypt 1 ,
291.Xr login 1 ,
292.Xr passwd 1 ,
293.Xr blowfish 3 ,
294.Xr getpass 3 ,
295.Xr md5 3 ,
296.Xr passwd 5
297.Sh HISTORY
298A rotor-based
299.Fn crypt
300function appeared in
301.At v3 .
302The current style
303.Fn crypt
304first appeared in
305.At v7 .
306.Sh AUTHORS
307.An David Burren Aq Mt davidb@werj.com.au
308wrote the original DES functions.
309.Sh BUGS
310The
311.Fn crypt
312function returns a pointer to static data, and subsequent calls to
313.Fn crypt
314will modify the same object.
315.Pp
316With DES hashing, passwords containing the byte 0x80 use less key entropy
317than other passwords.
318This is an implementation bug, not a bug in the DES cipher.