diff options
Diffstat (limited to 'manual/crypt.texi')
| -rw-r--r-- | manual/crypt.texi | 201 |
1 files changed, 0 insertions, 201 deletions
diff --git a/manual/crypt.texi b/manual/crypt.texi index 99d2d8e092..6bbe2bfdc5 100644 --- a/manual/crypt.texi +++ b/manual/crypt.texi @@ -30,21 +30,10 @@ message-digest algorithm that is compatible with modern BSD systems, and the other based on the Data Encryption Standard (DES) that is compatible with Unix systems. -@vindex AUTH_DES -@cindex FIPS 140-2 -It also provides support for Secure RPC, and some library functions that -can be used to perform normal DES encryption. The @code{AUTH_DES} -authentication flavor in Secure RPC, as provided by @theglibc{}, -uses DES and does not comply with FIPS 140-2 nor does any other use of DES -within @theglibc{}. It is recommended that Secure RPC should not be used -for systems that need to comply with FIPS 140-2 since all flavors of -encrypted authentication use normal DES. - @menu * Legal Problems:: This software can get you locked up, or worse. * getpass:: Prompting the user for a password. * crypt:: A one-way function for passwords. -* DES Encryption:: Routines for DES encryption. * Unpredictable Bytes:: Randomness for cryptography purposes. @end menu @@ -223,196 +212,6 @@ The @code{crypt_r} function is a GNU extension. The @code{crypt} and @code{crypt_r} functions are prototyped in the header @file{crypt.h}. -@node DES Encryption -@section DES Encryption - -@cindex FIPS 46-3 -The Data Encryption Standard is described in the US Government Federal -Information Processing Standards (FIPS) 46-3 published by the National -Institute of Standards and Technology. The DES has been very thoroughly -analyzed since it was developed in the late 1970s, and no new -significant flaws have been found. - -However, the DES uses only a 56-bit key (plus 8 parity bits), and a -machine has been built in 1998 which can search through all possible -keys in about 6 days, which cost about US$200000; faster searches would -be possible with more money. This makes simple DES insecure for most -purposes, and NIST no longer permits new US government systems -to use simple DES. - -For serious encryption functionality, it is recommended that one of the -many free encryption libraries be used instead of these routines. - -The DES is a reversible operation which takes a 64-bit block and a -64-bit key, and produces another 64-bit block. Usually the bits are -numbered so that the most-significant bit, the first bit, of each block -is numbered 1. - -Under that numbering, every 8th bit of the key (the 8th, 16th, and so -on) is not used by the encryption algorithm itself. But the key must -have odd parity; that is, out of bits 1 through 8, and 9 through 16, and -so on, there must be an odd number of `1' bits, and this completely -specifies the unused bits. - -@deftypefun void setkey (const char *@var{key}) -@standards{BSD, crypt.h} -@standards{SVID, crypt.h} -@safety{@prelim{}@mtunsafe{@mtasurace{:crypt}}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@aculock{}}} -@c The static buffer stores the key, making it fundamentally -@c thread-unsafe. The locking issues are only in the initialization -@c path; cancelling the initialization will leave the lock held, it -@c would otherwise repeat the initialization on the next call. - -The @code{setkey} function sets an internal data structure to be an -expanded form of @var{key}. @var{key} is specified as an array of 64 -bits each stored in a @code{char}, the first bit is @code{key[0]} and -the 64th bit is @code{key[63]}. The @var{key} should have the correct -parity. -@end deftypefun - -@deftypefun void encrypt (char *@var{block}, int @var{edflag}) -@standards{BSD, crypt.h} -@standards{SVID, crypt.h} -@safety{@prelim{}@mtunsafe{@mtasurace{:crypt}}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@aculock{}}} -@c Same issues as setkey. - -The @code{encrypt} function encrypts @var{block} if -@var{edflag} is 0, otherwise it decrypts @var{block}, using a key -previously set by @code{setkey}. The result is -placed in @var{block}. - -Like @code{setkey}, @var{block} is specified as an array of 64 bits each -stored in a @code{char}, but there are no parity bits in @var{block}. -@end deftypefun - -@deftypefun void setkey_r (const char *@var{key}, {struct crypt_data *} @var{data}) -@deftypefunx void encrypt_r (char *@var{block}, int @var{edflag}, {struct crypt_data *} @var{data}) -@standards{GNU, crypt.h} -@c setkey_r: @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@aculock{}}} -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@aculock{}}} - -These are reentrant versions of @code{setkey} and @code{encrypt}. The -only difference is the extra parameter, which stores the expanded -version of @var{key}. Before calling @code{setkey_r} the first time, -@code{data->initialized} must be cleared to zero. -@end deftypefun - -The @code{setkey_r} and @code{encrypt_r} functions are GNU extensions. -@code{setkey}, @code{encrypt}, @code{setkey_r}, and @code{encrypt_r} are -defined in @file{crypt.h}. - -@deftypefun int ecb_crypt (char *@var{key}, char *@var{blocks}, unsigned int @var{len}, unsigned int @var{mode}) -@standards{SUNRPC, rpc/des_crypt.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} - -The function @code{ecb_crypt} encrypts or decrypts one or more blocks -using DES. Each block is encrypted independently. - -The @var{blocks} and the @var{key} are stored packed in 8-bit bytes, so -that the first bit of the key is the most-significant bit of -@code{key[0]} and the 63rd bit of the key is stored as the -least-significant bit of @code{key[7]}. The @var{key} should have the -correct parity. - -@var{len} is the number of bytes in @var{blocks}. It should be a -multiple of 8 (so that there are a whole number of blocks to encrypt). -@var{len} is limited to a maximum of @code{DES_MAXDATA} bytes. - -The result of the encryption replaces the input in @var{blocks}. - -The @var{mode} parameter is the bitwise OR of two of the following: - -@vtable @code -@item DES_ENCRYPT -@standards{SUNRPC, rpc/des_crypt.h} -This constant, used in the @var{mode} parameter, specifies that -@var{blocks} is to be encrypted. - -@item DES_DECRYPT -@standards{SUNRPC, rpc/des_crypt.h} -This constant, used in the @var{mode} parameter, specifies that -@var{blocks} is to be decrypted. - -@item DES_HW -@standards{SUNRPC, rpc/des_crypt.h} -This constant, used in the @var{mode} parameter, asks to use a hardware -device. If no hardware device is available, encryption happens anyway, -but in software. - -@item DES_SW -@standards{SUNRPC, rpc/des_crypt.h} -This constant, used in the @var{mode} parameter, specifies that no -hardware device is to be used. -@end vtable - -The result of the function will be one of these values: - -@vtable @code -@item DESERR_NONE -@standards{SUNRPC, rpc/des_crypt.h} -The encryption succeeded. - -@item DESERR_NOHWDEVICE -@standards{SUNRPC, rpc/des_crypt.h} -The encryption succeeded, but there was no hardware device available. - -@item DESERR_HWERROR -@standards{SUNRPC, rpc/des_crypt.h} -The encryption failed because of a hardware problem. - -@item DESERR_BADPARAM -@standards{SUNRPC, rpc/des_crypt.h} -The encryption failed because of a bad parameter, for instance @var{len} -is not a multiple of 8 or @var{len} is larger than @code{DES_MAXDATA}. -@end vtable -@end deftypefun - -@deftypefun int DES_FAILED (int @var{err}) -@standards{SUNRPC, rpc/des_crypt.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This macro returns 1 if @var{err} is a `success' result code from -@code{ecb_crypt} or @code{cbc_crypt}, and 0 otherwise. -@end deftypefun - -@deftypefun int cbc_crypt (char *@var{key}, char *@var{blocks}, unsigned int @var{len}, unsigned int @var{mode}, char *@var{ivec}) -@standards{SUNRPC, rpc/des_crypt.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} - -The function @code{cbc_crypt} encrypts or decrypts one or more blocks -using DES in Cipher Block Chaining mode. - -For encryption in CBC mode, each block is exclusive-ored with @var{ivec} -before being encrypted, then @var{ivec} is replaced with the result of -the encryption, then the next block is processed. Decryption is the -reverse of this process. - -This has the advantage that blocks which are the same before being -encrypted are very unlikely to be the same after being encrypted, making -it much harder to detect patterns in the data. - -Usually, @var{ivec} is set to 8 random bytes before encryption starts. -Then the 8 random bytes are transmitted along with the encrypted data -(without themselves being encrypted), and passed back in as @var{ivec} -for decryption. Another possibility is to set @var{ivec} to 8 zeroes -initially, and have the first block encrypted consist of 8 random -bytes. - -Otherwise, all the parameters are similar to those for @code{ecb_crypt}. -@end deftypefun - -@deftypefun void des_setparity (char *@var{key}) -@standards{SUNRPC, rpc/des_crypt.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} - -The function @code{des_setparity} changes the 64-bit @var{key}, stored -packed in 8-bit bytes, to have odd parity by altering the low bits of -each byte. -@end deftypefun - -The @code{ecb_crypt}, @code{cbc_crypt}, and @code{des_setparity} -functions and their accompanying macros are all defined in the header -@file{rpc/des_crypt.h}. - @node Unpredictable Bytes @section Generating Unpredictable Bytes |