1.\" FreeSec: libcrypt for NetBSD
2.\"
3.\" Copyright (c) 1994 David Burren
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution.
14.\" 4. Neither the name of the author nor the names of other contributors
15.\" may be used to endorse or promote products derived from this software
16.\" without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
| 1.\" FreeSec: libcrypt for NetBSD
2.\"
3.\" Copyright (c) 1994 David Burren
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution.
14.\" 4. Neither the name of the author nor the names of other contributors
15.\" may be used to endorse or promote products derived from this software
16.\" without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
|
30.\" $FreeBSD: head/lib/libcrypt/crypt.3 70422 2000-12-28 11:56:45Z peter $
| 30.\" $FreeBSD: head/lib/libcrypt/crypt.3 70481 2000-12-29 14:08:20Z ru $
|
31.\"
32.\" Manual page, using -mandoc macros
33.\"
34.Dd January 19, 1997
35.Dt CRYPT 3
36.Os "FreeSec 1.0"
37.Sh NAME
38.Nm crypt
39.Nd Trapdoor encryption
40.Sh LIBRARY
41.Lb libcrypt
42.Sh SYNOPSIS
43.Fd #include <unistd.h>
44.Ft char *
45.Fn crypt "const char *key" "const char *salt"
46.Ft const char *
47.Fn crypt_get_format "void"
48.Ft int
49.Fn crypt_set_format "const char *string"
50.Sh DESCRIPTION
51The
52.Fn crypt
53function performs password hashing with additional code added to
54deter key search attempts. Different algorithms can be used to
55in the hash.
56.\"
57.\" NOTICE:
58.\" If you add more algorithms, make sure to update this list
59.\" and the default used for the Traditional format, below.
60.\"
61Currently these include the
62.Tn NBS
63.Tn Data Encryption Standard (DES) ,
64and
65.Tn MD5 .
66The algorithm used will depend upon the format of the Salt (following
67the Modular Crypt Format (MCF)), if
68.Tn DES
69is installed or not, and whether
70.Fn crypt_set_format
71has been called to change the default.
72.Pp
73The first argument to
74.Nm
75is the data to hash (usually a password), in a
76.Dv null Ns -terminated
77string.
78The second is the salt, in one of three forms:
79.Pp
80.Bl -tag -width Traditional -compact -offset indent
81.It Extended
82If it begins with an underscore
83.Pq Dq _
84then the
85.Tn DES
86Extended Format
87is used in interpreting both the the key and the salt, as outlined below.
88.It Modular
89If it begins with the string
90.Dq $digit$
91then the Modular Crypt Format is used, as outlined below.
92.It Traditional
93If neither of the above is true, it assumes the Traditional Format,
94using the entire string as the salt (or the first portion).
95.El
96.Pp
97All routines are designed to be time-consuming. A brief test on a
98.Tn Pentium
99166/MMX shows the
100.Tn DES
101crypt to do approximately 2640 crypts
102a CPU second and MD5 to do about 62 crypts a CPU second.
103.Ss DES Extended Format:
104.Pp
105The
106.Ar key
107is divided into groups of 8 characters (the last group is null-padded)
108and the low-order 7 bits of each each character (56 bits per group) are
109used to form the
110.Tn DES
111key as follows:
112the first group of 56 bits becomes the initial
113.Tn DES
114key.
115For each additional group, the XOR of the encryption of the current
116.Tn DES
117key with itself and the group bits becomes the next
118.Tn DES
119key.
120.Pp
121The salt is a 9-character array consisting of an underscore followed
122by 4 bytes of iteration count and 4 bytes of salt.
123These are encoded as printable characters, 6 bits per character,
124least significant character first.
125The values 0 to 63 are encoded as ``./0-9A-Za-z''.
126This allows 24 bits for both
127.Fa count
128and
129.Fa salt .
130.Pp
131The
132.Fa salt
133introduces disorder in the
134.Tn DES
135algorithm in one of 16777216 or 4096 possible ways
136(ie. with 24 or 12 bits: if bit
137.Em i
138of the
139.Ar salt
140is set, then bits
141.Em i
142and
143.Em i+24
144are swapped in the
145.Tn DES
146E-box output).
147.Pp
148The
149.Tn DES
150key is used to encrypt a 64-bit constant using
151.Ar count
152iterations of
153.Tn DES .
154The value returned is a
155.Dv null Ns -terminated
156string, 20 or 13 bytes (plus null) in length, consisting of the
157.Ar salt
158followed by the encoded 64-bit encryption.
159.Ss "Modular" crypt:
160.Pp
161If the salt begins with the string
162.Fa $digit$
163then the Modular Crypt Format is used. The
164.Fa digit
165represents which algorithm is used in encryption. Following the token is
166the actual salt to use in the encryption. The length of the salt is limited
167to 16 characters--because the length of the returned output is also limited
168(_PASSWORD_LEN). The salt must be terminated with the end of the string
169(NULL) or a dollar sign. Any characters after the dollar sign are ignored.
170.Pp
171Currently supported algorithms are:
172.Pp
| 31.\"
32.\" Manual page, using -mandoc macros
33.\"
34.Dd January 19, 1997
35.Dt CRYPT 3
36.Os "FreeSec 1.0"
37.Sh NAME
38.Nm crypt
39.Nd Trapdoor encryption
40.Sh LIBRARY
41.Lb libcrypt
42.Sh SYNOPSIS
43.Fd #include <unistd.h>
44.Ft char *
45.Fn crypt "const char *key" "const char *salt"
46.Ft const char *
47.Fn crypt_get_format "void"
48.Ft int
49.Fn crypt_set_format "const char *string"
50.Sh DESCRIPTION
51The
52.Fn crypt
53function performs password hashing with additional code added to
54deter key search attempts. Different algorithms can be used to
55in the hash.
56.\"
57.\" NOTICE:
58.\" If you add more algorithms, make sure to update this list
59.\" and the default used for the Traditional format, below.
60.\"
61Currently these include the
62.Tn NBS
63.Tn Data Encryption Standard (DES) ,
64and
65.Tn MD5 .
66The algorithm used will depend upon the format of the Salt (following
67the Modular Crypt Format (MCF)), if
68.Tn DES
69is installed or not, and whether
70.Fn crypt_set_format
71has been called to change the default.
72.Pp
73The first argument to
74.Nm
75is the data to hash (usually a password), in a
76.Dv null Ns -terminated
77string.
78The second is the salt, in one of three forms:
79.Pp
80.Bl -tag -width Traditional -compact -offset indent
81.It Extended
82If it begins with an underscore
83.Pq Dq _
84then the
85.Tn DES
86Extended Format
87is used in interpreting both the the key and the salt, as outlined below.
88.It Modular
89If it begins with the string
90.Dq $digit$
91then the Modular Crypt Format is used, as outlined below.
92.It Traditional
93If neither of the above is true, it assumes the Traditional Format,
94using the entire string as the salt (or the first portion).
95.El
96.Pp
97All routines are designed to be time-consuming. A brief test on a
98.Tn Pentium
99166/MMX shows the
100.Tn DES
101crypt to do approximately 2640 crypts
102a CPU second and MD5 to do about 62 crypts a CPU second.
103.Ss DES Extended Format:
104.Pp
105The
106.Ar key
107is divided into groups of 8 characters (the last group is null-padded)
108and the low-order 7 bits of each each character (56 bits per group) are
109used to form the
110.Tn DES
111key as follows:
112the first group of 56 bits becomes the initial
113.Tn DES
114key.
115For each additional group, the XOR of the encryption of the current
116.Tn DES
117key with itself and the group bits becomes the next
118.Tn DES
119key.
120.Pp
121The salt is a 9-character array consisting of an underscore followed
122by 4 bytes of iteration count and 4 bytes of salt.
123These are encoded as printable characters, 6 bits per character,
124least significant character first.
125The values 0 to 63 are encoded as ``./0-9A-Za-z''.
126This allows 24 bits for both
127.Fa count
128and
129.Fa salt .
130.Pp
131The
132.Fa salt
133introduces disorder in the
134.Tn DES
135algorithm in one of 16777216 or 4096 possible ways
136(ie. with 24 or 12 bits: if bit
137.Em i
138of the
139.Ar salt
140is set, then bits
141.Em i
142and
143.Em i+24
144are swapped in the
145.Tn DES
146E-box output).
147.Pp
148The
149.Tn DES
150key is used to encrypt a 64-bit constant using
151.Ar count
152iterations of
153.Tn DES .
154The value returned is a
155.Dv null Ns -terminated
156string, 20 or 13 bytes (plus null) in length, consisting of the
157.Ar salt
158followed by the encoded 64-bit encryption.
159.Ss "Modular" crypt:
160.Pp
161If the salt begins with the string
162.Fa $digit$
163then the Modular Crypt Format is used. The
164.Fa digit
165represents which algorithm is used in encryption. Following the token is
166the actual salt to use in the encryption. The length of the salt is limited
167to 16 characters--because the length of the returned output is also limited
168(_PASSWORD_LEN). The salt must be terminated with the end of the string
169(NULL) or a dollar sign. Any characters after the dollar sign are ignored.
170.Pp
171Currently supported algorithms are:
172.Pp
|
173.Bl -tag -width 012345678 -compact -offset indent
174.It 1
| 173.Bl -enum -compact -offset indent
174.It
|
175MD5
176.El
177.Pp
178Other crypt formats may be easilly added. An example salt would be:
179.Bl -tag -offset indent
180.It Cm "$3$thesalt$rest"
181.El
182.Pp
183.Ss "Traditional" crypt:
184.Pp
185The algorithm used will depend upon whether
186.Fn crypt_set_format
187has been called and whether a global default format has been specified.
188Unless a global default has been specified or
189.Fn crypt_set_format
190has set the format to something else, the built-in default format is
191used.
192This is currently
193.\"
194.\" NOTICE: Also make sure to update this
195.\"
196DES
197if it is available, or MD5 if not.
198.Pp
199How the salt is used will depend upon the algorithm for the hash. For
200best results, specify at least two characters of salt.
201.Pp
202The
203.Fn crypt_get_format
204function returns a constant string that represents the name of the
205algorithm currently used.
206Valid values are
207.\"
208.\" NOTICE: Also make sure to update this, too, as well
209.\"
210.Ql des
211and
212.Ql md5 .
213.Pp
214The
215.Fn crypt_set_format
216function sets the default encoding format according to the supplied
217.Fa string .
218.Pp
219The global default format can be set using the
220.Pa /etc/auth.conf
221file using the
222.Ql crypt_format
223property.
224.Sh RETURN VALUES
225.Pp
226.Fn crypt
227returns a pointer to the encrypted value on success, and NULL on failure.
228Note: this is not a standard behaviour, AT&T
229.Fn crypt
230will always return a pointer to a string.
231.Pp
232.Fn crypt_set_format
233will return 1 if the supplied encoding format was valid.
234Otherwise, a value of 0 is returned.
235.Sh SEE ALSO
236.Xr login 1 ,
237.Xr passwd 1 ,
238.Xr auth_getval 3 ,
239.Xr cipher 3 ,
240.Xr getpass 3 ,
241.Xr auth.conf 5 ,
242.Xr passwd 5 ,
243.Sh BUGS
244The
245.Fn crypt
246function returns a pointer to static data, and subsequent calls to
247.Fn crypt
248will modify the same data. Likewise,
249.Fn crypt_set_format
250modifies static data.
251.Sh HISTORY
252A rotor-based
253.Fn crypt
254function appeared in
255.At v6 .
256The current style
257.Fn crypt
258first appeared in
259.At v7 .
260.Pp
261The
262.Tn DES
263section of the code (FreeSec 1.0) was developed outside the United
264States of America as an unencumbered replacement for the U.S.-only
265.Nx
266libcrypt encryption library.
267Users should be aware that this code (and programs staticly linked with it)
268may not be exported from the U.S., although it apparently can be imported.
269.Sh AUTHORS
270.An -nosplit
271Originally written by
272.An David Burren Aq davidb@werj.com.au ,
273later additions and changes by
274.An Poul-Henning Kamp ,
275.An Mark R V Murray ,
276.An Kris Kennaway
277and
278.An Brian Feldman .
| 175MD5
176.El
177.Pp
178Other crypt formats may be easilly added. An example salt would be:
179.Bl -tag -offset indent
180.It Cm "$3$thesalt$rest"
181.El
182.Pp
183.Ss "Traditional" crypt:
184.Pp
185The algorithm used will depend upon whether
186.Fn crypt_set_format
187has been called and whether a global default format has been specified.
188Unless a global default has been specified or
189.Fn crypt_set_format
190has set the format to something else, the built-in default format is
191used.
192This is currently
193.\"
194.\" NOTICE: Also make sure to update this
195.\"
196DES
197if it is available, or MD5 if not.
198.Pp
199How the salt is used will depend upon the algorithm for the hash. For
200best results, specify at least two characters of salt.
201.Pp
202The
203.Fn crypt_get_format
204function returns a constant string that represents the name of the
205algorithm currently used.
206Valid values are
207.\"
208.\" NOTICE: Also make sure to update this, too, as well
209.\"
210.Ql des
211and
212.Ql md5 .
213.Pp
214The
215.Fn crypt_set_format
216function sets the default encoding format according to the supplied
217.Fa string .
218.Pp
219The global default format can be set using the
220.Pa /etc/auth.conf
221file using the
222.Ql crypt_format
223property.
224.Sh RETURN VALUES
225.Pp
226.Fn crypt
227returns a pointer to the encrypted value on success, and NULL on failure.
228Note: this is not a standard behaviour, AT&T
229.Fn crypt
230will always return a pointer to a string.
231.Pp
232.Fn crypt_set_format
233will return 1 if the supplied encoding format was valid.
234Otherwise, a value of 0 is returned.
235.Sh SEE ALSO
236.Xr login 1 ,
237.Xr passwd 1 ,
238.Xr auth_getval 3 ,
239.Xr cipher 3 ,
240.Xr getpass 3 ,
241.Xr auth.conf 5 ,
242.Xr passwd 5 ,
243.Sh BUGS
244The
245.Fn crypt
246function returns a pointer to static data, and subsequent calls to
247.Fn crypt
248will modify the same data. Likewise,
249.Fn crypt_set_format
250modifies static data.
251.Sh HISTORY
252A rotor-based
253.Fn crypt
254function appeared in
255.At v6 .
256The current style
257.Fn crypt
258first appeared in
259.At v7 .
260.Pp
261The
262.Tn DES
263section of the code (FreeSec 1.0) was developed outside the United
264States of America as an unencumbered replacement for the U.S.-only
265.Nx
266libcrypt encryption library.
267Users should be aware that this code (and programs staticly linked with it)
268may not be exported from the U.S., although it apparently can be imported.
269.Sh AUTHORS
270.An -nosplit
271Originally written by
272.An David Burren Aq davidb@werj.com.au ,
273later additions and changes by
274.An Poul-Henning Kamp ,
275.An Mark R V Murray ,
276.An Kris Kennaway
277and
278.An Brian Feldman .
|