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