aboutsummaryrefslogtreecommitdiff
path: root/lib/libc/gen/crypt.3
blob: ace61d6acc928fff410f34edd4b0f361e7f6d994 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
.\" Copyright (c) 1989, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)crypt.3	8.2 (Berkeley) 12/11/93
.\"     $Id$
.\"
.Dd December 11, 1993
.Dt CRYPT 3
.Os
.Sh NAME
.Nm crypt ,
.Nm setkey ,
.Nm encrypt ,
.Nm des_setkey ,
.Nm des_cipher
.Nd DES encryption
.Sh SYNOPSIS
.Fd #include <unistd.h>
.Ft char *
.Fn crypt "const char *key" "const char *setting"
.Ft int
.Fn setkey "const char *key"
.Ft int
.Fn encrypt "char *block" "int flag"
.Ft int
.Fn des_setkey "const char *key"
.Ft int
.Fn des_cipher "const char *in" "char *out" "long salt" "int count"
.Sh DESCRIPTION
The
.Fn crypt
function
performs password encryption.
It is derived from the
.Tn NBS
Data Encryption Standard.
Additional code has been added to deter
key search attempts.
The first argument to
.Nm crypt
is
a
.Dv NUL Ns -terminated
string (normally a password typed by a user).
The second is a character array, 9 bytes in length, consisting of an
underscore (``_'') followed by 4 bytes of iteration count and 4 bytes
of salt.
Both the iteration
.Fa count
and the 
.Fa salt
are encoded with 6 bits per character, least significant bits first.
The values 0 to 63 are encoded by the characters ``./0-9A-Za-z'',
respectively.
.Pp
The
.Fa salt
is used to induce disorder in to the
.Tn DES
algorithm
in one of 16777216
possible ways
(specifically, if bit
.Em i
of the
.Ar salt
is set then bits
.Em i
and
.Em i+24
are swapped in the
.Tn DES
``E'' box output).
The
.Ar key
is divided into groups of 8 characters (a short final group is null-padded)
and the low-order 7 bits of each character (56 bits per group) are
used to form the DES key as follows: the first group of 56 bits becomes the
initial DES key.
For each additional group, the XOR of the group bits and the encryption of
the DES key with itself becomes the next DES key.
Then the final DES key is used to perform
.Ar count
cumulative encryptions of a 64-bit constant.
The value returned is a
.Dv NUL Ns -terminated
string, 20 bytes in length, consisting
of the
.Ar setting
followed by the encoded 64-bit encryption.
.Pp
For compatibility with historical versions of
.Xr crypt 3 ,
the
.Ar setting
may consist of 2 bytes of salt, encoded as above, in which case an
iteration
.Ar count
of 25 is used, fewer perturbations of
.Tn DES
are available, at most 8
characters of
.Ar key
are used, and the returned value is a
.Dv NUL Ns -terminated
string 13 bytes in length.
.Pp
The
functions,
.Fn encrypt ,
.Fn setkey ,
.Fn des_setkey
and
.Fn des_cipher
allow limited access to the
.Tn DES
algorithm itself.
The
.Ar key
argument to
.Fn setkey
is a 64 character array of
binary values (numeric 0 or 1).
A 56-bit key is derived from this array by dividing the array
into groups of 8 and ignoring the last bit in each group.
.Pp
The
.Fn encrypt
argument
.Fa block
is also a 64 character array of
binary values.
If the value of
.Fa flag
is 0,
the argument
.Fa block
is encrypted, otherwise it
is decrypted.
The encryption or decryption is returned in the original
array
.Fa block
after using the
key specified
by
.Fn setkey
to process it.
.Pp
The
.Fn des_setkey
and
.Fn des_cipher
functions are faster but less portable than
.Fn setkey
and
.Fn encrypt .
The argument to
.Fn des_setkey
is a character array of length 8.
The
.Em least
significant bit in each character is ignored and the next 7 bits of each
character are concatenated to yield a 56-bit key.
The function
.Fn des_cipher
encrypts (or decrypts if
.Fa count
is negative) the 64-bits stored in the 8 characters at
.Fa in
using
.Xr abs 3
of
.Fa count
iterations of
.Tn DES
and stores the 64-bit result in the 8 characters at
.Fa out .
The
.Fa salt
specifies perturbations to
.Tn DES
as described above.
.Pp
The function
.Fn crypt
returns a pointer to the encrypted value on success and NULL on failure.
The functions
.Fn setkey ,
.Fn encrypt ,
.Fn des_setkey ,
and
.Fn des_cipher
return 0 on success and 1 on failure.
Historically, the functions
.Fn setkey
and
.Fn encrypt
did not return any value.
They have been provided return values primarily to distinguish
implementations where hardware support is provided but not
available or where the DES encryption is not available due to the
usual political silliness.
.Pp
Use of
.Fn crypt
requires linking with the
.Nm libcrypt
library.  The 
.Fn setkey ,
.Fn encrypt ,
.Fn des_setkey
and
.Fn des_cipher
can be found in the
.Nm libcipher
library (the standard C library,
.Nm libc ,
only contains stubs to these routines).
.Sh SEE ALSO
.Xr login 1 ,
.Xr passwd 1 ,
.Xr getpass 3 ,
.Xr passwd 5
.Rs
.%T "Mathematical Cryptology for Computer Scientists and Mathematicians"
.%A Wayne Patterson
.%D 1987
.%N ISBN 0-8476-7438-X
.Re
.Rs
.%T "Password Security: A Case History"
.%A R. Morris
.%A Ken Thompson
.%J "Communications of the ACM"
.%V vol. 22
.%P pp. 594-597
.%D Nov. 1979
.Re
.Rs
.%T "DES will be Totally Insecure within Ten Years"
.%A M.E. Hellman
.%J "IEEE Spectrum"
.%V vol. 16
.%P pp. 32-39
.%D July 1979
.Re
.Sh HISTORY
A rotor-based
.Fn crypt
function appeared in
.At v6 .
The current style
.Fn crypt
first appeared in
.At v7 .
.Sh BUGS
Dropping the
.Em least
significant bit in each character of the argument to
.Fn des_setkey
is ridiculous.
.Pp
The
.Fn crypt
function leaves its result in an internal static object and returns
a pointer to that object.
Subsequent calls to
.Fn crypt
will modify the same object.