diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/conf.texi | 2 | ||||
| -rw-r--r-- | manual/crypt.texi | 201 | ||||
| -rw-r--r-- | manual/string.texi | 82 |
3 files changed, 43 insertions, 242 deletions
diff --git a/manual/conf.texi b/manual/conf.texi index f1dce4aa44..dbd1d30287 100644 --- a/manual/conf.texi +++ b/manual/conf.texi @@ -778,6 +778,8 @@ Inquire about the parameter corresponding to @code{_XOPEN_LEGACY}. @item _SC_XOPEN_CRYPT @standards{X/Open, unistd.h} Inquire about the parameter corresponding to @code{_XOPEN_CRYPT}. +@Theglibc no longer implements the @code{_XOPEN_CRYPT} extensions, +so @samp{sysconf (_SC_XOPEN_CRYPT)} always returns @code{-1}. @item _SC_XOPEN_ENH_I18N @standards{X/Open, unistd.h} 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 diff --git a/manual/string.texi b/manual/string.texi index b07cfb4550..a1c58e58fa 100644 --- a/manual/string.texi +++ b/manual/string.texi @@ -36,8 +36,8 @@ too. for delimiters. * Erasing Sensitive Data:: Clearing memory which contains sensitive data, after it's no longer needed. -* strfry:: Function for flash-cooking a string. -* Trivial Encryption:: Obscuring data. +* Shuffling Bytes:: Or how to flash-cook a string. +* Obfuscating Data:: Reversibly obscuring data from casual view. * Encode Binary Data:: Encoding and Decoding of Binary Data. * Argz and Envz Vectors:: Null-separated string vectors. @end menu @@ -2426,73 +2426,73 @@ functionality under a different name, such as @code{explicit_memset}, systems it may be in @file{strings.h} instead. @end deftypefun -@node strfry -@section strfry + +@node Shuffling Bytes +@section Shuffling Bytes The function below addresses the perennial programming quandary: ``How do I take good data in string form and painlessly turn it into garbage?'' -This is actually a fairly simple task for C programmers who do not use -@theglibc{} string functions, but for programs based on @theglibc{}, -the @code{strfry} function is the preferred method for -destroying string data. +This is not a difficult thing to code for oneself, but the authors of +@theglibc{} wish to make it as convenient as possible. -The prototype for this function is in @file{string.h}. +To @emph{erase} data, use @code{explicit_bzero} (@pxref{Erasing +Sensitive Data}); to obfuscate it reversibly, use @code{memfrob} +(@pxref{Obfuscating Data}). @deftypefun {char *} strfry (char *@var{string}) @standards{GNU, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Calls initstate_r, time, getpid, strlen, and random_r. -@code{strfry} creates a pseudorandom anagram of a string, replacing the -input with the anagram in place. For each position in the string, -@code{strfry} swaps it with a position in the string selected at random -(from a uniform distribution). The two positions may be the same. +@code{strfry} performs an in-place shuffle on @var{string}. Each +character is swapped to a position selected at random, within the +portion of the string starting with the character's original position. +(This is the Fisher-Yates algorithm for unbiased shuffling.) + +Calling @code{strfry} will not disturb any of the random number +generators that have global state (@pxref{Pseudo-Random Numbers}). The return value of @code{strfry} is always @var{string}. @strong{Portability Note:} This function is unique to @theglibc{}. - +It is declared in @file{string.h}. @end deftypefun -@node Trivial Encryption -@section Trivial Encryption -@cindex encryption - - -The @code{memfrob} function converts an array of data to something -unrecognizable and back again. It is not encryption in its usual sense -since it is easy for someone to convert the encrypted data back to clear -text. The transformation is analogous to Usenet's ``Rot13'' encryption -method for obscuring offensive jokes from sensitive eyes and such. -Unlike Rot13, @code{memfrob} works on arbitrary binary data, not just -text. +@node Obfuscating Data +@section Obfuscating Data @cindex Rot13 -For true encryption, @xref{Cryptographic Functions}. +The @code{memfrob} function reversibly obfuscates an array of binary +data. This is not true encryption; the obfuscated data still bears a +clear relationship to the original, and no secret key is required to +undo the obfuscation. It is analogous to the ``Rot13'' cipher used on +Usenet for obscuring offensive jokes, spoilers for works of fiction, +and so on, but it can be applied to arbitrary binary data. -This function is declared in @file{string.h}. -@pindex string.h +Programs that need true encryption---a transformation that completely +obscures the original and cannot be reversed without knowledge of a +secret key---should use a dedicated cryptography library, such as +@uref{https://www.gnu.org/software/libgcrypt/,,libgcrypt}. + +Programs that need to @emph{destroy} data should use +@code{explicit_bzero} (@pxref{Erasing Sensitive Data}), or possibly +@code{strfry} (@pxref{Shuffling Bytes}). @deftypefun {void *} memfrob (void *@var{mem}, size_t @var{length}) @standards{GNU, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@code{memfrob} transforms (frobnicates) each byte of the data structure -at @var{mem}, which is @var{length} bytes long, by bitwise exclusive -oring it with binary 00101010. It does the transformation in place and -its return value is always @var{mem}. +The function @code{memfrob} obfuscates @var{length} bytes of data +beginning at @var{mem}, in place. Each byte is bitwise xor-ed with +the binary pattern 00101010 (hexadecimal 0x2A). The return value is +always @var{mem}. -Note that @code{memfrob} a second time on the same data structure -returns it to its original state. - -This is a good function for hiding information from someone who doesn't -want to see it or doesn't want to see it very much. To really prevent -people from retrieving the information, use stronger encryption such as -that described in @xref{Cryptographic Functions}. +@code{memfrob} a second time on the same data returns it to +its original state. @strong{Portability Note:} This function is unique to @theglibc{}. - +It is declared in @file{string.h}. @end deftypefun @node Encode Binary Data |