(Tools for Compilation): Grammar fixes.
[kopensolaris-gnu/glibc.git] / manual / crypt.texi
1 @c This node must have no pointers.
2 @node Cryptographic Functions
3 @c @node Cryptographic Functions, Debugging Support, System Configuration, Top
4 @chapter DES Encryption and Password Handling
5 @c %MENU% DES encryption and password handling
6
7 On many systems, it is unnecessary to have any kind of user
8 authentication; for instance, a workstation which is not connected to a
9 network probably does not need any user authentication, because to use
10 the machine an intruder must have physical access.
11
12 Sometimes, however, it is necessary to be sure that a user is authorized
13 to use some service a machine provides---for instance, to log in as a
14 particular user id (@pxref{Users and Groups}).  One traditional way of
15 doing this is for each user to choose a secret @dfn{password}; then, the
16 system can ask someone claiming to be a user what the user's password
17 is, and if the person gives the correct password then the system can
18 grant the appropriate privileges.
19
20 If all the passwords are just stored in a file somewhere, then this file
21 has to be very carefully protected.  To avoid this, passwords are run
22 through a @dfn{one-way function}, a function which makes it difficult to
23 work out what its input was by looking at its output, before storing in
24 the file.
25
26 The GNU C library provides a one-way function that is compatible with
27 the behavior of the @code{crypt} function introduced in FreeBSD 2.0.
28 It supports two one-way algorithms: one based on the MD5
29 message-digest algorithm that is compatible with modern BSD systems,
30 and the other based on the Data Encryption Standard (DES) that is
31 compatible with Unix systems.
32
33 It also provides support for Secure RPC, and some library functions that
34 can be used to perform normal DES encryption.
35
36 @menu
37 * Legal Problems::              This software can get you locked up, or worse.
38 * getpass::                     Prompting the user for a password.
39 * crypt::                       A one-way function for passwords.
40 * DES Encryption::              Routines for DES encryption.
41 @end menu
42
43 @node Legal Problems
44 @section Legal Problems
45
46 Because of the continuously changing state of the law, it's not possible
47 to provide a definitive survey of the laws affecting cryptography.
48 Instead, this section warns you of some of the known trouble spots; this
49 may help you when you try to find out what the laws of your country are.
50
51 Some countries require that you have a licence to use, possess, or import
52 cryptography.  These countries are believed to include Byelorussia,
53 Burma, India, Indonesia, Israel, Kazakhstan, Pakistan, Russia, and Saudi
54 Arabia.
55
56 Some countries restrict the transmission of encrypted messages by radio;
57 some telecommunications carriers restrict the transmission of encrypted
58 messages over their network.
59
60 Many countries have some form of export control for encryption software.
61 The Wassenaar Arrangement is a multilateral agreement between 33
62 countries (Argentina, Australia, Austria, Belgium, Bulgaria, Canada, the
63 Czech Republic, Denmark, Finland, France, Germany, Greece, Hungary,
64 Ireland, Italy, Japan, Luxembourg, the Netherlands, New Zealand, Norway,
65 Poland, Portugal, the Republic of Korea, Romania, the Russian
66 Federation, the Slovak Republic, Spain, Sweden, Switzerland, Turkey,
67 Ukraine, the United Kingdom and the United States) which restricts some
68 kinds of encryption exports.  Different countries apply the arrangement
69 in different ways; some do not allow the exception for certain kinds of
70 ``public domain'' software (which would include this library), some
71 only restrict the export of software in tangible form, and others impose
72 significant additional restrictions.
73
74 The United States has additional rules.  This software would generally
75 be exportable under 15 CFR 740.13(e), which permits exports of
76 ``encryption source code'' which is ``publicly available'' and which is
77 ``not subject to an express agreement for the payment of a licensing fee or
78 royalty for commercial production or sale of any product developed with
79 the source code'' to most countries.
80
81 The rules in this area are continuously changing.  If you know of any
82 information in this manual that is out-of-date, please report it using
83 the @code{glibcbug} script. @xref{Reporting Bugs}.
84
85 @node getpass
86 @section Reading Passwords
87
88 When reading in a password, it is desirable to avoid displaying it on
89 the screen, to help keep it secret.  The following function handles this
90 in a convenient way.
91
92 @comment unistd.h
93 @comment BSD
94 @deftypefun {char *} getpass (const char *@var{prompt})
95
96 @code{getpass} outputs @var{prompt}, then reads a string in from the
97 terminal without echoing it.  It tries to connect to the real terminal,
98 @file{/dev/tty}, if possible, to encourage users not to put plaintext
99 passwords in files; otherwise, it uses @code{stdin} and @code{stderr}.
100 @code{getpass} also disables the INTR, QUIT, and SUSP characters on the
101 terminal using the @code{ISIG} terminal attribute (@pxref{Local Modes}).
102 The terminal is flushed before and after @code{getpass}, so that
103 characters of a mistyped password are not accidentally visible.
104
105 In other C libraries, @code{getpass} may only return the first
106 @code{PASS_MAX} bytes of a password.  The GNU C library has no limit, so
107 @code{PASS_MAX} is undefined.
108
109 The prototype for this function is in @file{unistd.h}.  @code{PASS_MAX}
110 would be defined in @file{limits.h}.
111 @end deftypefun
112
113 This precise set of operations may not suit all possible situations.  In
114 this case, it is recommended that users write their own @code{getpass}
115 substitute.  For instance, a very simple substitute is as follows:
116
117 @smallexample
118 @include mygetpass.c.texi
119 @end smallexample
120
121 The substitute takes the same parameters as @code{getline}
122 (@pxref{Line Input}); the user must print any prompt desired.
123
124 @node crypt
125 @section Encrypting Passwords
126
127 @comment crypt.h
128 @comment BSD, SVID
129 @deftypefun {char *} crypt (const char *@var{key}, const char *@var{salt})
130
131 The @code{crypt} function takes a password, @var{key}, as a string, and
132 a @var{salt} character array which is described below, and returns a
133 printable ASCII string which starts with another salt.  It is believed
134 that, given the output of the function, the best way to find a @var{key}
135 that will produce that output is to guess values of @var{key} until the
136 original value of @var{key} is found.
137
138 The @var{salt} parameter does two things.  Firstly, it selects which
139 algorithm is used, the MD5-based one or the DES-based one.  Secondly, it
140 makes life harder for someone trying to guess passwords against a file
141 containing many passwords; without a @var{salt}, an intruder can make a
142 guess, run @code{crypt} on it once, and compare the result with all the
143 passwords.  With a @var{salt}, the intruder must run @code{crypt} once
144 for each different salt.
145
146 For the MD5-based algorithm, the @var{salt} should consist of the string
147 @code{$1$}, followed by up to 8 characters, terminated by either
148 another @code{$} or the end of the string.  The result of @code{crypt}
149 will be the @var{salt}, followed by a @code{$} if the salt didn't end
150 with one, followed by 22 characters from the alphabet
151 @code{./0-9A-Za-z}, up to 34 characters total.  Every character in the
152 @var{key} is significant.
153
154 For the DES-based algorithm, the @var{salt} should consist of two
155 characters from the alphabet @code{./0-9A-Za-z}, and the result of
156 @code{crypt} will be those two characters followed by 11 more from the
157 same alphabet, 13 in total.  Only the first 8 characters in the
158 @var{key} are significant.
159
160 The MD5-based algorithm has no limit on the useful length of the
161 password used, and is slightly more secure.  It is therefore preferred
162 over the DES-based algorithm.
163
164 When the user enters their password for the first time, the @var{salt}
165 should be set to a new string which is reasonably random.  To verify a
166 password against the result of a previous call to @code{crypt}, pass
167 the result of the previous call as the @var{salt}.
168 @end deftypefun
169
170 The following short program is an example of how to use @code{crypt} the
171 first time a password is entered.  Note that the @var{salt} generation
172 is just barely acceptable; in particular, it is not unique between
173 machines, and in many applications it would not be acceptable to let an
174 attacker know what time the user's password was last set.
175
176 @smallexample
177 @include genpass.c.texi
178 @end smallexample
179
180 The next program shows how to verify a password.  It prompts the user
181 for a password and prints ``Access granted.'' if the user types
182 @code{GNU libc manual}.
183
184 @smallexample
185 @include testpass.c.texi
186 @end smallexample
187
188 @comment crypt.h
189 @comment GNU
190 @deftypefun {char *} crypt_r (const char *@var{key}, const char *@var{salt}, {struct crypt_data *} @var{data})
191
192 The @code{crypt_r} function does the same thing as @code{crypt}, but
193 takes an extra parameter which includes space for its result (among
194 other things), so it can be reentrant.  @code{data@w{->}initialized} must be
195 cleared to zero before the first time @code{crypt_r} is called.
196
197 The @code{crypt_r} function is a GNU extension.
198 @end deftypefun
199
200 The @code{crypt} and @code{crypt_r} functions are prototyped in the
201 header @file{crypt.h}.
202
203 @node DES Encryption
204 @section DES Encryption
205
206 The Data Encryption Standard is described in the US Government Federal
207 Information Processing Standards (FIPS) 46-3 published by the National
208 Institute of Standards and Technology.  The DES has been very thoroughly
209 analyzed since it was developed in the late 1970s, and no new
210 significant flaws have been found.
211
212 However, the DES uses only a 56-bit key (plus 8 parity bits), and a
213 machine has been built in 1998 which can search through all possible
214 keys in about 6 days, which cost about US$200000; faster searches would
215 be possible with more money.  This makes simple DES insecure for most
216 purposes, and NIST no longer permits new US government systems
217 to use simple DES.
218
219 For serious encryption functionality, it is recommended that one of the
220 many free encryption libraries be used instead of these routines.
221
222 The DES is a reversible operation which takes a 64-bit block and a
223 64-bit key, and produces another 64-bit block.  Usually the bits are
224 numbered so that the most-significant bit, the first bit, of each block
225 is numbered 1.
226
227 Under that numbering, every 8th bit of the key (the 8th, 16th, and so
228 on) is not used by the encryption algorithm itself.  But the key must
229 have odd parity; that is, out of bits 1 through 8, and 9 through 16, and
230 so on, there must be an odd number of `1' bits, and this completely
231 specifies the unused bits.
232
233 @comment crypt.h
234 @comment BSD, SVID
235 @deftypefun void setkey (const char *@var{key})
236
237 The @code{setkey} function sets an internal data structure to be an
238 expanded form of @var{key}.  @var{key} is specified as an array of 64
239 bits each stored in a @code{char}, the first bit is @code{key[0]} and
240 the 64th bit is @code{key[63]}.  The @var{key} should have the correct
241 parity.
242 @end deftypefun
243
244 @comment crypt.h
245 @comment BSD, SVID
246 @deftypefun void encrypt (char *@var{block}, int @var{edflag})
247
248 The @code{encrypt} function encrypts @var{block} if
249 @var{edflag} is 0, otherwise it decrypts @var{block}, using a key
250 previously set by @code{setkey}.  The result is
251 placed in @var{block}.
252
253 Like @code{setkey}, @var{block} is specified as an array of 64 bits each
254 stored in a @code{char}, but there are no parity bits in @var{block}.
255 @end deftypefun
256
257 @comment crypt.h
258 @comment GNU
259 @deftypefun void setkey_r (const char *@var{key}, {struct crypt_data *} @var{data})
260 @comment crypt.h
261 @comment GNU
262 @deftypefunx void encrypt_r (char *@var{block}, int @var{edflag}, {struct crypt_data *} @var{data})
263
264 These are reentrant versions of @code{setkey} and @code{encrypt}.  The
265 only difference is the extra parameter, which stores the expanded
266 version of @var{key}.  Before calling @code{setkey_r} the first time,
267 @code{data->initialized} must be cleared to zero.
268 @end deftypefun
269
270 The @code{setkey_r} and @code{encrypt_r} functions are GNU extensions.
271 @code{setkey}, @code{encrypt}, @code{setkey_r}, and @code{encrypt_r} are
272 defined in @file{crypt.h}.
273
274 @comment rpc/des_crypt.h
275 @comment SUNRPC
276 @deftypefun int ecb_crypt (char *@var{key}, char *@var{blocks}, unsigned @var{len}, unsigned @var{mode})
277
278 The function @code{ecb_crypt} encrypts or decrypts one or more blocks
279 using DES.  Each block is encrypted independently.
280
281 The @var{blocks} and the @var{key} are stored packed in 8-bit bytes, so
282 that the first bit of the key is the most-significant bit of
283 @code{key[0]} and the 63rd bit of the key is stored as the
284 least-significant bit of @code{key[7]}.  The @var{key} should have the
285 correct parity.
286
287 @var{len} is the number of bytes in @var{blocks}.  It should be a
288 multiple of 8 (so that there is a whole number of blocks to encrypt).
289 @var{len} is limited to a maximum of @code{DES_MAXDATA} bytes.
290
291 The result of the encryption replaces the input in @var{blocks}.
292
293 The @var{mode} parameter is the bitwise OR of two of the following:
294
295 @vtable @code
296 @comment rpc/des_crypt.h
297 @comment SUNRPC
298 @item DES_ENCRYPT
299 This constant, used in the @var{mode} parameter, specifies that
300 @var{blocks} is to be encrypted.
301
302 @comment rpc/des_crypt.h
303 @comment SUNRPC
304 @item DES_DECRYPT
305 This constant, used in the @var{mode} parameter, specifies that
306 @var{blocks} is to be decrypted.
307
308 @comment rpc/des_crypt.h
309 @comment SUNRPC
310 @item DES_HW
311 This constant, used in the @var{mode} parameter, asks to use a hardware
312 device.  If no hardware device is available, encryption happens anyway,
313 but in software.
314
315 @comment rpc/des_crypt.h
316 @comment SUNRPC
317 @item DES_SW
318 This constant, used in the @var{mode} parameter, specifies that no
319 hardware device is to be used.
320 @end vtable
321
322 The result of the function will be one of these values:
323
324 @vtable @code
325 @comment rpc/des_crypt.h
326 @comment SUNRPC
327 @item DESERR_NONE
328 The encryption succeeded.
329
330 @comment rpc/des_crypt.h
331 @comment SUNRPC
332 @item DESERR_NOHWDEVICE
333 The encryption succeeded, but there was no hardware device available.
334
335 @comment rpc/des_crypt.h
336 @comment SUNRPC
337 @item DESERR_HWERROR
338 The encryption failed because of a hardware problem.
339
340 @comment rpc/des_crypt.h
341 @comment SUNRPC
342 @item DESERR_BADPARAM
343 The encryption failed because of a bad parameter, for instance @var{len}
344 is not a multiple of 8 or @var{len} is larger than @code{DES_MAXDATA}.
345 @end vtable
346 @end deftypefun
347
348 @comment rpc/des_crypt.h
349 @comment SUNRPC
350 @deftypefun int DES_FAILED (int @var{err})
351 This macro returns 1 if @var{err} is a `success' result code from
352 @code{ecb_crypt} or @code{cbc_crypt}, and 0 otherwise.
353 @end deftypefun
354
355 @comment rpc/des_crypt.h
356 @comment SUNRPC
357 @deftypefun int cbc_crypt (char *@var{key}, char *@var{blocks}, unsigned @var{len}, unsigned @var{mode}, char *@var{ivec})
358
359 The function @code{cbc_crypt} encrypts or decrypts one or more blocks
360 using DES in Cipher Block Chaining mode.
361
362 For encryption in CBC mode, each block is exclusive-ored with @var{ivec}
363 before being encrypted, then @var{ivec} is replaced with the result of
364 the encryption, then the next block is processed.  Decryption is the
365 reverse of this process.
366
367 This has the advantage that blocks which are the same before being
368 encrypted are very unlikely to be the same after being encrypted, making
369 it much harder to detect patterns in the data.
370
371 Usually, @var{ivec} is set to 8 random bytes before encryption starts.
372 Then the 8 random bytes are transmitted along with the encrypted data
373 (without themselves being encrypted), and passed back in as @var{ivec}
374 for decryption.  Another possibility is to set @var{ivec} to 8 zeroes
375 initially, and have the first the block encrypted consist of 8 random
376 bytes.
377
378 Otherwise, all the parameters are similar to those for @code{ecb_crypt}.
379 @end deftypefun
380
381 @comment rpc/des_crypt.h
382 @comment SUNRPC
383 @deftypefun void des_setparity (char *@var{key})
384
385 The function @code{des_setparity} changes the 64-bit @var{key}, stored
386 packed in 8-bit bytes, to have odd parity by altering the low bits of
387 each byte.
388 @end deftypefun
389
390 The @code{ecb_crypt}, @code{cbc_crypt}, and @code{des_setparity}
391 functions and their accompanying macros are all defined in the header
392 @file{rpc/des_crypt.h}.