DESCRYPT(3) DESCRYPT(3)

NAME
       desreadpassword,        desread2password,        desstringtokey,
       desstringto2key,         desreadpwstring,         desrandomkey,
       dessetkeyschedule, deskeysched, desecbencrypt, des3ecbencrypt,
       descbcencrypt, des3cbcencrypt,  despcbcencrypt,  descfbencrypt,
       desofbencrypt,     descbccksum,    desquadcksum,    desencread,
       desencwrite, dessetoddparity, desisweakkey, crypt -  (non  USA)
       DES encryption

SYNOPSIS
       ##iinncclluuddee <>

       iinntt ddeessrreeaaddppaasssswwoorrdd((kkeeyy,,pprroommpptt,,vveerriiffyy))
       descblock *key;
       char *prompt;
       int verify;

       iinntt ddeessrreeaadd22ppaasssswwoorrdd((kkeeyy11,,kkeeyy22,,pprroommpptt,,vveerriiffyy))
       descblock *key1,*key2;
       char *prompt;
       int verify;

       iinntt ddeessssttrriinnggttookkeeyy((ssttrr,,kkeeyy))
       char *str;
       descblock *key;

       iinntt ddeessssttrriinnggttoo22kkeeyyss((ssttrr,,kkeeyy11,,kkeeyy22))
       char *str;
       descblock *key1,*key2;

       iinntt ddeessrreeaaddppwwssttrriinngg((bbuuff,,lleennggtthh,,pprroommpptt,,vveerriiffyy))
       char *buf;
       int length;
       char *prompt;
       int verify;

       iinntt ddeessrraannddoommkkeeyy((kkeeyy))
       descblock *key;

       iinntt ddeesssseettkkeeyysscchheedduullee((kkeeyy,,sscchheedduullee))
       descblock *key;
       deskeyschedule schedule;

       iinntt ddeesskkeeyysscchheedd((kkeeyy,,sscchheedduullee))
       descblock *key;
       deskeyschedule schedule;

       iinntt ddeesseeccbbeennccrryypptt((iinnppuutt,,oouuttppuutt,,sscchheedduullee,,eennccrryypptt))
       descblock *input;
       descblock *output;
       deskeyschedule schedule;
       int encrypt;

       iinntt ddeess33eeccbbeennccrryypptt((iinnppuutt,,oouuttppuutt,,kkss11,,kkss22,,eennccrryypptt))
       descblock *input;
       descblock *output;
       deskeyschedule ks1,ks2;
       int encrypt;

       iinntt ddeessccbbcceennccrryypptt((iinnppuutt,,oouuttppuutt,,lleennggtthh,,sscchheedduullee,,iivveecc,,eennccrryypptt))
       descblock *input;
       descblock *output;
       long length;
       deskeyschedule schedule;
       descblock *ivec;
       int encrypt;

       iinntt ddeess33ccbbcceennccrryypptt((iinnppuutt,,oouuttppuutt,,lleennggtthh,,sskk11,,sskk22,,iivveecc11,,iivveecc22,,eennccrryypptt))
       descblock *input;
       descblock *output;
       long length;
       deskeyschedule sk1;
       deskeyschedule sk2;
       descblock *ivec1;
       descblock *ivec2;
       int encrypt;

       iinntt ddeessppccbbcceennccrryypptt((iinnppuutt,,oouuttppuutt,,lleennggtthh,,sscchheedduullee,,iivveecc,,eennccrryypptt))
       descblock *input;
       descblock *output;
       long length;
       deskeyschedule schedule;
       descblock *ivec;
       int encrypt;

       iinntt ddeessccffbbeennccrryypptt((iinnppuutt,,oouuttppuutt,,nnuummbbiittss,,lleennggtthh,,sscchheedduullee,,iivveecc,,eennccrryypptt))
       unsigned char *input;
       unsigned char *output;
       int numbits;
       long length;
       deskeyschedule schedule;
       descblock *ivec;
       int encrypt;

       iinntt ddeessooffbbeennccrryypptt((iinnppuutt,,oouuttppuutt,,nnuummbbiittss,,lleennggtthh,,sscchheedduullee,,iivveecc))
       unsigned char *input,*output;
       int numbits;
       long length;
       deskeyschedule schedule;
       descblock *ivec;

       uunnssiiggnneedd lloonngg ddeessccbbcccckkssuumm((iinnppuutt,,oouuttppuutt,,lleennggtthh,,sscchheedduullee,,iivveecc))
       descblock *input;
       descblock *output;
       long length;
       deskeyschedule schedule;
       descblock *ivec;

       uunnssiiggnneedd lloonngg ddeessqquuaaddcckkssuumm((iinnppuutt,,oouuttppuutt,,lleennggtthh,,oouuttccoouunntt,,sseeeedd))
       descblock *input;
       descblock *output;
       long length;
       int outcount;
       descblock *seed;

       iinntt ddeesscchheecckkkkeeyy;;

       iinntt ddeesseennccrreeaadd((ffdd,,bbuuff,,lleenn,,sscchheedd,,iivv))
       int fd;
       char *buf;
       int len;
       deskeyschedule sched;
       descblock *iv;

       iinntt ddeesseennccwwrriittee((ffdd,,bbuuff,,lleenn,,sscchheedd,,iivv))
       int fd;
       char *buf;
       int len;
       deskeyschedule sched;
       descblock *iv;

       eexxtteerrnn iinntt ddeessrrwwmmooddee;;

       vvooiidd ddeesssseettooddddppaarriittyy((kkeeyy))
       descblock *key;

       iinntt ddeessiisswweeaakkkkeeyy((kkeeyy))
       descblock *key;

       cchhaarr **ccrryypptt((ppaasssswwdd,,ssaalltt))
       char *passwd;
       char *salt;


DESCRIPTION
       This library contains a fast implementation of the DES encryption algo-
       rithm.

       There are two phases to the use of DES encryption.  The  first  is  the
       generation  of  a deskeyschedule from a key, the second is the actual
       encryption.  A des key is of type descblock.  This type is made from 8
       characters with odd parity.  The least significant bit in the character
       is the parity bit.  The key schedule is an expanded form of the key; it
       is used to speed the encryption process.

       desreadpassword writes the string specified by prompt to the standard
       output, turns off echo and reads an input string  from  standard  input
       until terminated with a newline.  If verify is non-zero, it prompts and
       reads the input again and verifies that both entered passwords are  the
       same.   The  entered  string  is  converted into a des key by using the
       desstringtokey routine.  The new key is  placed  in  the  descblock
       that  was  passed  (by  reference)  to  the  routine.  If there were no
       errors, desreadpassword returns 0, -1 is returned if there was a ter-
       minal error and 1 is returned for any other error.

       desread2password operates in the same way as desreadpassword except
       that it generates 2 keys by using the desstringto2key function.

       desreadpwstring is called by desreadpassword to read and verify  a
       string  from  a  terminal  device.  The string is returned in buf.  The
       size of buf is passed to the routine via the length parameter.

       desstringtokey converts a string into a valid des key.

       desstringto2key converts a string into 2 valid des keys.  This  rou-
       tine   is   best  suited  for  used  to  generate  keys  for  use  with
       des3ecbencrypt.

       desrandomkey returns a random key that is made of  a  combination  of
       process id, time and an increasing counter.

       Before  a  des  key can be used it is converted into a deskeyschedule
       via the dessetkeyschedule routine.  If  the  descheckkey  flag  is
       non-zero, dessetkeyschedule will check that the key passed is of odd
       parity and is not a week or semi-weak key.  If  the  parity  is  wrong,
       then  -1  is  returned.  If the key is a weak key, then -2 is returned.
       If an error is returned, the key schedule is not generated.

       deskeysched is another name for the dessetkeyschedule function.

       The following routines mostly operate on an input and output stream  of
       descblock's.

       desecbencrypt  is  the  basic DES encryption routine that encrypts or
       decrypts a single 8-byte descblock in electronic code book  mode.   It
       always  transforms the input data, pointed to by input, into the output
       data, pointed to by the output argument.  If the  encrypt  argument  is
       non-zero  (DESENCRYPT),  the  input (cleartext) is encrypted in to the
       output (ciphertext) using the keyschedule specified  by  the  schedule
       argument,  previously set via dessetkeyschedule.  If encrypt is zero
       (DESDECRYPT), the input (now ciphertext) is decrypted into the  output
       (now cleartext).  Input and output may overlap.  No meaningful value is
       returned.

       des3ecbencrypt encrypts/decrypts the input block by using triple  ecb
       DES  encryption.   This involves encrypting the input with ks1, decryp-
       tion with the key schedule ks2, and  then  encryption  with  the  first
       again.   This routine greatly reduces the chances of brute force break-
       ing of DES and has the advantage of if ks1 and ks2 are the same, it  is
       equivalent to just encryption using ecb mode and ks1 as the key.

       descbcencrypt  encrypts/decrypts using the cipher-block-chaining mode
       of DES.  If the encrypt argument is non-zero, the routine cipher-block-
       chain encrypts the cleartext data pointed to by the input argument into
       the ciphertext pointed to by the output argument, using the key  sched-
       ule  provided  by the schedule argument, and initialisation vector pro-
       vided by the ivec argument.  If the length argument is not an  integral
       multiple  of  eight bytes, the last block is copied to a temporary area
       and zero filled.  The output is always an integral  multiple  of  eight
       bytes.   To  make  multiple cbc encrypt calls on a large amount of data
       appear to be one descbcencrypt call, the  ivec  of  subsequent  calls
       should be the last 8 bytes of the output.

       des3cbcencrypt  encrypts/decrypts the input block by using triple cbc
       DES encryption.  This involves encrypting the input with  key  schedule
       ks1, decryption with the key schedule ks2, and then encryption with the
       first again.  2 initialisation vectors are required, ivec1  and  ivec2.
       Unlike  descbcencrypt,  these  initialisation vectors are modified by
       the subroutine.  This routine greatly  reduces  the  chances  of  brute
       force  breaking  of DES and has the advantage of if ks1 and ks2 are the
       same, it is equivalent to just encryption using cbc mode and ks1 as the
       key.

       despcbcencrypt encrypt/decrypts using a modified block chaining mode.
       It provides better error propagation characteristics than  cbc  encryp-
       tion.

       descfbencrypt  encrypt/decrypts  using  cipher  feedback  mode.  This
       method takes an array of characters as input and outputs and  array  of
       characters.   It  does  not  require any padding to 8 character groups.
       Note: the ivec variable is changed and the new changed value  needs  to
       be  passed to the next call to this function.  Since this function runs
       a complete DES ecb encryption per numbits, this function is  only  sug-
       gested for use when sending small numbers of characters.

       desofbencrypt  encrypt using output feedback mode.  This method takes
       an array of characters as input and outputs and  array  of  characters.
       It  does not require any padding to 8 character groups.  Note: the ivec
       variable is changed and the new changed value needs to be passed to the
       next  call  to  this function.  Since this function runs a complete DES
       ecb encryption per numbits, this function is  only  suggested  for  use
       when sending small numbers of characters.

       descbccksum  produces  an  8  byte checksum based on the input stream
       (via cbc encryption).  The last 4 bytes of the checksum is returned and
       the complete 8 bytes is placed in output.

       desquadcksum  returns  a  4  byte checksum from the input bytes.  The
       algorithm can be iterated over the input, depending on outcount, 1, 2,
       3  or  4  times.   If output is non-NULL, the 8 bytes generated by each
       pass are written into output.

       desencwrite is used to write len bytes to  file  descriptor  fd  from
       buffer  buf.   The  data  is encrypted via pcbcencrypt (default) using
       sched for the key and iv as a starting vector.  The  actual  data  send
       down  fd  consists  of  4  bytes (in network byte order) containing the
       length of the following encrypted data.  The encrypted data  then  fol-
       lows, padded with random data out to a multiple of 8 bytes.

       desencread  is  used  to  read len bytes from file descriptor fd into
       buffer buf.  The data being read from fd is assumed to have  come  from
       desencwrite  and is decrypted using sched for the key schedule and iv
       for the initial vector.  The  desencread/desencwrite  pair  can  be
       used  to  read/write  to files, pipes and sockets.  I have used them in
       implementing a version of rlogin in which all data is encrypted.

       desrwmode is  used  to  specify  the  encryption  mode  to  use  with
       desencread and desendwrite.  If set to DESPCBCMODE (the default),
       despcbcencrypt is used.  If set to  DESCBCMODE  descbcencrypt  is
       used.   These  two routines and the variable are not part of the normal
       MIT library.

       dessetoddparity sets the parity of the passed key to odd.  This rou-
       tine is not part of the standard MIT library.

       desisweakkey  returns  1 is the passed key is a weak key (pick again
       :-), 0 if it is ok.  This routine is  not  part  of  the  standard  MIT
       library.

       crypt  is a replacement for the normal system crypt.  It is much faster
       than the system crypt.


FILES       /usr/include/des.h
       /usr/lib/libdes.a

       The encryption routines have been tested  on  16bit,  32bit  and  64bit
       machines of various endian and even works under VMS.


BUGS
       If  you  think this manual is sparse, read the descrypt(3) manual from
       the MIT kerberos (or bones outside of the USA) distribution.

       descfbencrypt and desofbencrypt operates on input of 8 bits.   What
       this means is that if you set numbits to 12, and length to 2, the first
       12 bits will come from the 1st input byte and the low half of the  sec-
       ond input byte.  The second 12 bits will have the low 8 bits taken from
       the 3rd input byte and the top 4 bits taken from the  4th  input  byte.
       The same holds for output.  This function has been implemented this way
       because most people will be using a multiple of 8 and because once  you
       get into pulling bytes input bytes apart things get ugly!

       desreadpwstring  is  the most machine/OS dependent function and nor-
       mally generates the most problems when porting this code.

       desstringtokey is probably different  from  the  MIT  version  since
       there  are  lots  of fun ways to implement one-way encryption of a text
       string.

       The routines are optimised for 32 bit machines and so are not efficient
       on IBM PCs.

       NOTE:  extensive work has been done on this library since this document
       was origionally written.  Please try to read des.doc  from  the  libdes
       distribution  since  it is far more upto date and documents more of the
       functions.  Libdes is now also being shipped as part of SSLeay, a  gen-
       eral   cryptographic   library  that  amonst  other  things  implements
       netscapes SSL protocoll.  The most  recent  version  can  be  found  in
       SSLeay distributions.

AUTHOR       Eric Young (eay@mincom.oz.au or eay@psych.psy.uq.oz.au)



                                                                  DESCRYPT(3)