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