lh | 9ed821d | 2023-04-07 01:36:19 -0700 | [diff] [blame] | 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 | @Theglibc{} 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 | @vindex AUTH_DES |
| 34 | @cindex FIPS 140-2 |
| 35 | It also provides support for Secure RPC, and some library functions that |
| 36 | can be used to perform normal DES encryption. The @code{AUTH_DES} |
| 37 | authentication flavor in Secure RPC, as provided by @theglibc{}, |
| 38 | uses DES and does not comply with FIPS 140-2 nor does any other use of DES |
| 39 | within @theglibc{}. It is recommended that Secure RPC should not be used |
| 40 | for systems that need to comply with FIPS 140-2 since all flavors of |
| 41 | encrypted 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 | |
| 53 | Because of the continuously changing state of the law, it's not possible |
| 54 | to provide a definitive survey of the laws affecting cryptography. |
| 55 | Instead, this section warns you of some of the known trouble spots; this |
| 56 | may help you when you try to find out what the laws of your country are. |
| 57 | |
| 58 | Some countries require that you have a licence to use, possess, or import |
| 59 | cryptography. These countries are believed to include Byelorussia, |
| 60 | Burma, India, Indonesia, Israel, Kazakhstan, Pakistan, Russia, and Saudi |
| 61 | Arabia. |
| 62 | |
| 63 | Some countries restrict the transmission of encrypted messages by radio; |
| 64 | some telecommunications carriers restrict the transmission of encrypted |
| 65 | messages over their network. |
| 66 | |
| 67 | Many countries have some form of export control for encryption software. |
| 68 | The Wassenaar Arrangement is a multilateral agreement between 33 |
| 69 | countries (Argentina, Australia, Austria, Belgium, Bulgaria, Canada, the |
| 70 | Czech Republic, Denmark, Finland, France, Germany, Greece, Hungary, |
| 71 | Ireland, Italy, Japan, Luxembourg, the Netherlands, New Zealand, Norway, |
| 72 | Poland, Portugal, the Republic of Korea, Romania, the Russian |
| 73 | Federation, the Slovak Republic, Spain, Sweden, Switzerland, Turkey, |
| 74 | Ukraine, the United Kingdom and the United States) which restricts some |
| 75 | kinds of encryption exports. Different countries apply the arrangement |
| 76 | in different ways; some do not allow the exception for certain kinds of |
| 77 | ``public domain'' software (which would include this library), some |
| 78 | only restrict the export of software in tangible form, and others impose |
| 79 | significant additional restrictions. |
| 80 | |
| 81 | The United States has additional rules. This software would generally |
| 82 | be 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 |
| 85 | royalty for commercial production or sale of any product developed with |
| 86 | the source code'' to most countries. |
| 87 | |
| 88 | The rules in this area are continuously changing. If you know of any |
| 89 | information in this manual that is out-of-date, please report it to |
| 90 | the bug database. @xref{Reporting Bugs}. |
| 91 | |
| 92 | @node getpass |
| 93 | @section Reading Passwords |
| 94 | |
| 95 | When reading in a password, it is desirable to avoid displaying it on |
| 96 | the screen, to help keep it secret. The following function handles this |
| 97 | in 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 |
| 111 | terminal without echoing it. It tries to connect to the real terminal, |
| 112 | @file{/dev/tty}, if possible, to encourage users not to put plaintext |
| 113 | passwords in files; otherwise, it uses @code{stdin} and @code{stderr}. |
| 114 | @code{getpass} also disables the INTR, QUIT, and SUSP characters on the |
| 115 | terminal using the @code{ISIG} terminal attribute (@pxref{Local Modes}). |
| 116 | The terminal is flushed before and after @code{getpass}, so that |
| 117 | characters of a mistyped password are not accidentally visible. |
| 118 | |
| 119 | In 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 | |
| 123 | The prototype for this function is in @file{unistd.h}. @code{PASS_MAX} |
| 124 | would be defined in @file{limits.h}. |
| 125 | @end deftypefun |
| 126 | |
| 127 | This precise set of operations may not suit all possible situations. In |
| 128 | this case, it is recommended that users write their own @code{getpass} |
| 129 | substitute. For instance, a very simple substitute is as follows: |
| 130 | |
| 131 | @smallexample |
| 132 | @include mygetpass.c.texi |
| 133 | @end smallexample |
| 134 | |
| 135 | The 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 | |
| 152 | The @code{crypt} function takes a password, @var{key}, as a string, and |
| 153 | a @var{salt} character array which is described below, and returns a |
| 154 | printable ASCII string which starts with another salt. It is believed |
| 155 | that, given the output of the function, the best way to find a @var{key} |
| 156 | that will produce that output is to guess values of @var{key} until the |
| 157 | original value of @var{key} is found. |
| 158 | |
| 159 | The @var{salt} parameter does two things. Firstly, it selects which |
| 160 | algorithm is used, the MD5-based one or the DES-based one. Secondly, it |
| 161 | makes life harder for someone trying to guess passwords against a file |
| 162 | containing many passwords; without a @var{salt}, an intruder can make a |
| 163 | guess, run @code{crypt} on it once, and compare the result with all the |
| 164 | passwords. With a @var{salt}, the intruder must run @code{crypt} once |
| 165 | for each different salt. |
| 166 | |
| 167 | For the MD5-based algorithm, the @var{salt} should consist of the string |
| 168 | @code{$1$}, followed by up to 8 characters, terminated by either |
| 169 | another @code{$} or the end of the string. The result of @code{crypt} |
| 170 | will be the @var{salt}, followed by a @code{$} if the salt didn't end |
| 171 | with 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 | |
| 175 | For the DES-based algorithm, the @var{salt} should consist of two |
| 176 | characters 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 |
| 178 | same alphabet, 13 in total. Only the first 8 characters in the |
| 179 | @var{key} are significant. |
| 180 | |
| 181 | The MD5-based algorithm has no limit on the useful length of the |
| 182 | password used, and is slightly more secure. It is therefore preferred |
| 183 | over the DES-based algorithm. |
| 184 | |
| 185 | When the user enters their password for the first time, the @var{salt} |
| 186 | should be set to a new string which is reasonably random. To verify a |
| 187 | password against the result of a previous call to @code{crypt}, pass |
| 188 | the result of the previous call as the @var{salt}. |
| 189 | @end deftypefun |
| 190 | |
| 191 | The following short program is an example of how to use @code{crypt} the |
| 192 | first time a password is entered. Note that the @var{salt} generation |
| 193 | is just barely acceptable; in particular, it is not unique between |
| 194 | machines, and in many applications it would not be acceptable to let an |
| 195 | attacker know what time the user's password was last set. |
| 196 | |
| 197 | @smallexample |
| 198 | @include genpass.c.texi |
| 199 | @end smallexample |
| 200 | |
| 201 | The next program shows how to verify a password. It prompts the user |
| 202 | for 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 | |
| 216 | The @code{crypt_r} function does the same thing as @code{crypt}, but |
| 217 | takes an extra parameter which includes space for its result (among |
| 218 | other things), so it can be reentrant. @code{data@w{->}initialized} must be |
| 219 | cleared to zero before the first time @code{crypt_r} is called. |
| 220 | |
| 221 | The @code{crypt_r} function is a GNU extension. |
| 222 | @end deftypefun |
| 223 | |
| 224 | The @code{crypt} and @code{crypt_r} functions are prototyped in the |
| 225 | header @file{crypt.h}. |
| 226 | |
| 227 | @node DES Encryption |
| 228 | @section DES Encryption |
| 229 | |
| 230 | @cindex FIPS 46-3 |
| 231 | The Data Encryption Standard is described in the US Government Federal |
| 232 | Information Processing Standards (FIPS) 46-3 published by the National |
| 233 | Institute of Standards and Technology. The DES has been very thoroughly |
| 234 | analyzed since it was developed in the late 1970s, and no new |
| 235 | significant flaws have been found. |
| 236 | |
| 237 | However, the DES uses only a 56-bit key (plus 8 parity bits), and a |
| 238 | machine has been built in 1998 which can search through all possible |
| 239 | keys in about 6 days, which cost about US$200000; faster searches would |
| 240 | be possible with more money. This makes simple DES insecure for most |
| 241 | purposes, and NIST no longer permits new US government systems |
| 242 | to use simple DES. |
| 243 | |
| 244 | For serious encryption functionality, it is recommended that one of the |
| 245 | many free encryption libraries be used instead of these routines. |
| 246 | |
| 247 | The DES is a reversible operation which takes a 64-bit block and a |
| 248 | 64-bit key, and produces another 64-bit block. Usually the bits are |
| 249 | numbered so that the most-significant bit, the first bit, of each block |
| 250 | is numbered 1. |
| 251 | |
| 252 | Under that numbering, every 8th bit of the key (the 8th, 16th, and so |
| 253 | on) is not used by the encryption algorithm itself. But the key must |
| 254 | have odd parity; that is, out of bits 1 through 8, and 9 through 16, and |
| 255 | so on, there must be an odd number of `1' bits, and this completely |
| 256 | specifies 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 | |
| 267 | The @code{setkey} function sets an internal data structure to be an |
| 268 | expanded form of @var{key}. @var{key} is specified as an array of 64 |
| 269 | bits each stored in a @code{char}, the first bit is @code{key[0]} and |
| 270 | the 64th bit is @code{key[63]}. The @var{key} should have the correct |
| 271 | parity. |
| 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 | |
| 280 | The @code{encrypt} function encrypts @var{block} if |
| 281 | @var{edflag} is 0, otherwise it decrypts @var{block}, using a key |
| 282 | previously set by @code{setkey}. The result is |
| 283 | placed in @var{block}. |
| 284 | |
| 285 | Like @code{setkey}, @var{block} is specified as an array of 64 bits each |
| 286 | stored 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 | |
| 298 | These are reentrant versions of @code{setkey} and @code{encrypt}. The |
| 299 | only difference is the extra parameter, which stores the expanded |
| 300 | version of @var{key}. Before calling @code{setkey_r} the first time, |
| 301 | @code{data->initialized} must be cleared to zero. |
| 302 | @end deftypefun |
| 303 | |
| 304 | The @code{setkey_r} and @code{encrypt_r} functions are GNU extensions. |
| 305 | @code{setkey}, @code{encrypt}, @code{setkey_r}, and @code{encrypt_r} are |
| 306 | defined 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 | |
| 313 | The function @code{ecb_crypt} encrypts or decrypts one or more blocks |
| 314 | using DES. Each block is encrypted independently. |
| 315 | |
| 316 | The @var{blocks} and the @var{key} are stored packed in 8-bit bytes, so |
| 317 | that 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 |
| 319 | least-significant bit of @code{key[7]}. The @var{key} should have the |
| 320 | correct parity. |
| 321 | |
| 322 | @var{len} is the number of bytes in @var{blocks}. It should be a |
| 323 | multiple 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 | |
| 326 | The result of the encryption replaces the input in @var{blocks}. |
| 327 | |
| 328 | The @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 |
| 334 | This 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 |
| 340 | This 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 |
| 346 | This constant, used in the @var{mode} parameter, asks to use a hardware |
| 347 | device. If no hardware device is available, encryption happens anyway, |
| 348 | but in software. |
| 349 | |
| 350 | @comment rpc/des_crypt.h |
| 351 | @comment SUNRPC |
| 352 | @item DES_SW |
| 353 | This constant, used in the @var{mode} parameter, specifies that no |
| 354 | hardware device is to be used. |
| 355 | @end vtable |
| 356 | |
| 357 | The 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 |
| 363 | The encryption succeeded. |
| 364 | |
| 365 | @comment rpc/des_crypt.h |
| 366 | @comment SUNRPC |
| 367 | @item DESERR_NOHWDEVICE |
| 368 | The encryption succeeded, but there was no hardware device available. |
| 369 | |
| 370 | @comment rpc/des_crypt.h |
| 371 | @comment SUNRPC |
| 372 | @item DESERR_HWERROR |
| 373 | The encryption failed because of a hardware problem. |
| 374 | |
| 375 | @comment rpc/des_crypt.h |
| 376 | @comment SUNRPC |
| 377 | @item DESERR_BADPARAM |
| 378 | The encryption failed because of a bad parameter, for instance @var{len} |
| 379 | is 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{}} |
| 387 | This 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 | |
| 396 | The function @code{cbc_crypt} encrypts or decrypts one or more blocks |
| 397 | using DES in Cipher Block Chaining mode. |
| 398 | |
| 399 | For encryption in CBC mode, each block is exclusive-ored with @var{ivec} |
| 400 | before being encrypted, then @var{ivec} is replaced with the result of |
| 401 | the encryption, then the next block is processed. Decryption is the |
| 402 | reverse of this process. |
| 403 | |
| 404 | This has the advantage that blocks which are the same before being |
| 405 | encrypted are very unlikely to be the same after being encrypted, making |
| 406 | it much harder to detect patterns in the data. |
| 407 | |
| 408 | Usually, @var{ivec} is set to 8 random bytes before encryption starts. |
| 409 | Then the 8 random bytes are transmitted along with the encrypted data |
| 410 | (without themselves being encrypted), and passed back in as @var{ivec} |
| 411 | for decryption. Another possibility is to set @var{ivec} to 8 zeroes |
| 412 | initially, and have the first the block encrypted consist of 8 random |
| 413 | bytes. |
| 414 | |
| 415 | Otherwise, 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 | |
| 423 | The function @code{des_setparity} changes the 64-bit @var{key}, stored |
| 424 | packed in 8-bit bytes, to have odd parity by altering the low bits of |
| 425 | each byte. |
| 426 | @end deftypefun |
| 427 | |
| 428 | The @code{ecb_crypt}, @code{cbc_crypt}, and @code{des_setparity} |
| 429 | functions and their accompanying macros are all defined in the header |
| 430 | @file{rpc/des_crypt.h}. |