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