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