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