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.3325
1 files changed, 0 insertions, 325 deletions
diff --git a/src/lib/libc/crypt/crypt.3 b/src/lib/libc/crypt/crypt.3
deleted file mode 100644
index 8415f28b9b..0000000000
--- a/src/lib/libc/crypt/crypt.3
+++ /dev/null
@@ -1,325 +0,0 @@
1.\" $OpenBSD: crypt.3,v 1.28 2012/06/02 00:14:16 guenther 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: June 2 2012 $
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 DES encryption
47.Sh SYNOPSIS
48.Fd #include <stdlib.h>
49.Ft int
50.Fn setkey "const char *key"
51.Pp
52.Fd #include <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.Ft char *
62.Fn bcrypt_gensalt "u_int8_t log_rounds"
63.Ft char *
64.Fn bcrypt "const char *key" "const char *salt"
65.Ft char *
66.Fn md5crypt "const char *key" "const char *salt"
67.Sh DESCRIPTION
68The
69.Fn crypt
70function performs password encryption based on the
71.Tn NBS
72Data Encryption Standard (DES).
73Additional code has been added to deter key search attempts and to use
74stronger hashing algorithms.
75.Pp
76The first argument to
77.Fn crypt
78is a
79.Dv NUL Ns -terminated
80string, typically a user's typed password.
81The second is in one of three forms:
82if it begins with an underscore
83.Pq Ql _
84then an extended format is used
85in interpreting both the key and the setting, as outlined below.
86If it begins
87with a string character
88.Pq Ql $
89and a number then a different algorithm is used depending on the number.
90At the moment a
91.Ql $1
92chooses MD5 hashing and a
93.Ql $2
94chooses Blowfish hashing; see below for more information.
95.Ss Extended crypt
96The
97.Ar key
98is divided into groups of 8 characters (the last group is null-padded)
99and the low-order 7 bits of each character (56 bits per group) are
100used to form the DES key as follows:
101the first group of 56 bits becomes the initial DES key.
102For each additional group, the XOR of the encryption of the current DES
103key with itself and the group bits becomes the next DES key.
104.Pp
105The setting is a 9-character array consisting of an underscore followed
106by 4 bytes of iteration count and 4 bytes of salt.
107These are encoded as printable characters, 6 bits per character,
108least significant character first.
109The values 0 to 63 are encoded as
110.Dq \&./0-9A-Za-z .
111This allows 24 bits for both
112.Fa count
113and
114.Fa salt .
115.Ss "MD5" crypt
116For
117.Tn MD5
118crypt the version number,
119.Fa salt
120and the hashed password are separated by the
121.Ql $
122character.
123The maximum length of a password is limited by
124the length counter of the MD5 context, which is about
1252**64.
126A valid MD5 password entry looks like this:
127.Pp
128.Dq $1$caeiHQwX$hsKqOjrFRRN6K32OWkCBf1 .
129.Pp
130The whole MD5 password string is passed as
131.Fa setting
132for interpretation.
133.Ss "Blowfish" crypt
134The
135.Tn Blowfish
136version of crypt has 128 bits of
137.Fa salt
138in order to make building dictionaries of common passwords space consuming.
139The initial state of the
140.Tn Blowfish
141cipher is expanded using the
142.Fa salt
143and the
144.Fa password
145repeating the process a variable number of rounds, which is encoded in
146the password string.
147The maximum password length is 72.
148The final Blowfish password entry is created by encrypting the string
149.Pp
150.Dq OrpheanBeholderScryDoubt
151.Pp
152with the
153.Tn Blowfish
154state 64 times.
155.Pp
156The version number, the logarithm of the number of rounds and
157the concatenation of salt and hashed password are separated by the
158.Ql $
159character.
160An encoded
161.Sq 8
162would specify 256 rounds.
163A valid Blowfish password looks like this:
164.Pp
165.Dq $2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC .
166.Pp
167The whole Blowfish password string is passed as
168.Fa setting
169for interpretation.
170.Ss "Traditional" crypt
171The first 8 bytes of the key are null-padded, and the low-order 7 bits of
172each character is used to form the 56-bit
173.Tn DES
174key.
175.Pp
176The setting is a 2-character array of the ASCII-encoded salt.
177Thus only 12 bits of
178.Fa salt
179are used.
180.Fa count
181is set to 25.
182.Ss DES Algorithm
183The
184.Fa salt
185introduces disorder in the
186.Tn DES
187algorithm in one of 16777216 or 4096 possible ways
188(i.e., with 24 or 12 bits: if bit
189.Em i
190of the
191.Ar salt
192is set, then bits
193.Em i
194and
195.Em i+24
196are swapped in the
197.Tn DES
198E-box output).
199.Pp
200The DES key is used to encrypt a 64-bit constant using
201.Ar count
202iterations of
203.Tn DES .
204The value returned is a
205.Dv NUL Ns -terminated
206string, 20 or 13 bytes (plus NUL) in length, consisting of the
207.Ar setting
208followed by the encoded 64-bit encryption.
209.Pp
210The functions
211.Fn encrypt ,
212.Fn setkey ,
213.Fn des_setkey ,
214and
215.Fn des_cipher
216provide access to the
217.Tn DES
218algorithm itself.
219.Fn setkey
220is passed a 64-byte array of binary values (numeric 0 or 1).
221A 56-bit key is extracted from this array by dividing the
222array into groups of 8, and ignoring the last bit in each group.
223That bit is reserved for a byte parity check by DES, but is ignored
224by these functions.
225.Pp
226The
227.Fa block
228argument to
229.Fn encrypt
230is also a 64-byte array of binary values.
231If the value of
232.Fa flag
233is 0,
234.Fa block
235is encrypted otherwise it is decrypted.
236The result is returned in the original array
237.Fa block
238after using the key specified by
239.Fn setkey
240to process it.
241.Pp
242The argument to
243.Fn des_setkey
244is a character array of length 8.
245The least significant bit (the parity bit) in each character is ignored,
246and the remaining bits are concatenated to form a 56-bit key.
247The function
248.Fn des_cipher
249encrypts (or decrypts if
250.Fa count
251is negative) the 64-bits stored in the 8 characters at
252.Fa in
253using
254.Xr abs 3
255of
256.Fa count
257iterations of
258.Tn DES
259and stores the 64-bit result in the 8 characters at
260.Fa out
261(which may be the same as
262.Fa in ) .
263The
264.Fa salt
265specifies perturbations to the
266.Tn DES
267E-box output as described above.
268.Pp
269The
270.Fn crypt ,
271.Fn setkey ,
272and
273.Fn des_setkey
274functions all manipulate the same key space.
275.Sh RETURN VALUES
276The function
277.Fn crypt
278returns a pointer to the encrypted value on success, and
279.Dv NULL
280on failure.
281The functions
282.Fn setkey ,
283.Fn encrypt ,
284.Fn des_setkey ,
285and
286.Fn des_cipher
287return 0 on success and 1 on failure.
288.Sh SEE ALSO
289.Xr login 1 ,
290.Xr passwd 1 ,
291.Xr blowfish 3 ,
292.Xr getpass 3 ,
293.Xr md5 3 ,
294.Xr passwd 5
295.Sh HISTORY
296A rotor-based
297.Fn crypt
298function appeared in
299.At v3 .
300The current style
301.Fn crypt
302first appeared in
303.At v7 .
304.Pp
305This library (FreeSec 1.0) was developed outside the United States of America
306as an unencumbered replacement for the U.S.-only libcrypt encryption
307library.
308Programs linked against the
309.Fn crypt
310interface may be exported from the U.S.A. only if they use
311.Fn crypt
312solely for authentication purposes and avoid use of
313the other programmer interfaces listed above.
314Special care has been taken
315in the library so that programs which only use the
316.Fn crypt
317interface do not pull in the other components.
318.Sh AUTHORS
319.An David Burren Aq davidb@werj.com.au
320.Sh BUGS
321The
322.Fn crypt
323function returns a pointer to static data, and subsequent calls to
324.Fn crypt
325will modify the same object.