home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / bsd_srcs / kerberosIV / des / doc / libdes.doc next >
Encoding:
Text File  |  1987-11-09  |  7.5 KB  |  209 lines
  1.  
  2.     How to use the Kerberos encryption library.
  3.  
  4.             Revised        10/15/85    spm
  5.  
  6. 1)    The following include file is needed:
  7.     
  8.     /projects/auth/include/des.h    (VAX)
  9.     ---------------                    (PC8086)
  10.  
  11. 2)    The encryption library that should be linked to is:
  12.     
  13.     /projects/auth/lib/libdes.a        (VAX)
  14. |    /projects/auth/ibm/lib/libdes.a    (PC8086 cross-compilation environment)
  15.  
  16. 3)    For each key that may be simultaneously active,
  17.     allocate (either compile or malloc) a "Key_schedule" struct, 
  18.     defined in "des.h"
  19.  
  20. 4)    Create key schedules, as needed, prior to using the encryption
  21.     routines, via "des_set_key()".
  22.  
  23. 5)  Setup the input and output areas.  Make sure to note the restrictions
  24.     on lengths being multiples of eight bytes.
  25.  
  26. 6)    Invoke the encryption/decryption routines, "ecb_encrypt()"
  27.      or "cbc_encrypt()"
  28.  
  29. 7)    To generate a cryptographic checksum, use "cbc_cksum()"
  30. /*    ----------------------------------------------------------------    */
  31.     
  32.     Routine Interfaces--
  33.  
  34. /*    -----------------------------------------------------------------    */
  35.  
  36. int
  37.     des_set_key(k,schedule)
  38.         C_Block            *k;
  39.         Key_schedule    schedule;
  40.  
  41.     Calculates a key schedule from (all) eight bytes of the input key, and
  42.     puts it into the indicated "Key_schedule" struct;
  43.  
  44.     Make sure to pass valid eight bytes, no padding or other processing
  45.     it done.
  46.  
  47.     The key schedule is then used in subsequent encryption/decryption
  48.     operations.  Many key schedules may be created and cached for later
  49.     use.
  50.  
  51.     The user is responsible to clear keys and schedules no longer needed
  52.     to prevent their disclosure.
  53.  
  54. |    Checks the parity of the key provided, to make sure it is odd per
  55. |    FIPS spec.  Returns 0 value for key ok, 1 for key_parity error.
  56.  
  57. /*    ----------------------------------------------------------------    */
  58.     
  59. int
  60.     ecb_encrypt(input,output,schedule,encrypt)
  61.         C_Block            *input;        /* ptr to eight byte input value */
  62.         C_Block            *output;    /* ptr to eight byte output value */
  63.         int                encrypt;    /* 0 ==> decrypt, else encrypt */
  64.         Key_schedule    schedule;    /* addr of key schedule */
  65.  
  66. This is the low level routine that encrypts or decrypts a single 8-byte
  67. block in electronic code book mode.  Always transforms the input
  68. data into the output data.
  69.  
  70. If encrypt is non-zero, the input (cleartext) is encrypted into the
  71. output (ciphertext) using the specified key_schedule, pre-set via "des_set_key".
  72.  
  73. If encrypt is zero, the input (now ciphertext) is decrypted into
  74. the output (now cleartext).
  75.  
  76. Input and output may be the same space.
  77.  
  78. Does not return any meaningful value.  Void is not used for compatibility
  79. with other compilers.
  80.  
  81. /*    --------------------------------------------------------------    */
  82.  
  83. int    
  84.     cbc_encrypt(input,output,length,schedule,ivec,encrypt)
  85.  
  86.         C_Block            *input;        /* ptr to input data */
  87.         C_Block            *output;    /* ptr to output data */
  88.         int                length;        /* desired length, in bytes */
  89.         Key_schedule    schedule;        /* addr of precomputed schedule */
  90.         C_Block            *ivec;        /* pointer to 8 byte initialization
  91.                                      * vector
  92.                                      */
  93.         int                encrypt        /* 0 ==> decrypt; else encrypt*/
  94.  
  95.  
  96.     If encrypt is non-zero, the routine cipher-block-chain encrypts
  97.     the INPUT (cleartext) into the OUTPUT (ciphertext) using the provided
  98.     key schedule and initialization vector.  If the length is not an integral
  99.     multiple of eight bytes, the last block is copied to a temp and zero 
  100.     filled (highest addresses).  The output is ALWAYS an integral multiple
  101.     of eight bytes.
  102.  
  103.     If encrypt is zero, the routine cipher-block chain decrypts the INPUT
  104.     (ciphertext) into the OUTPUT (cleartext) using the provided key schedule
  105.     and    initialization vector.    Decryption ALWAYS operates on integral
  106.     multiples of 8 bytes, so will round the length provided up to the
  107.     appropriate    multiple. Consequently,    it will always produce the rounded-up
  108.     number of bytes of output cleartext. The application must determine if
  109.     the output cleartext was zero-padded due to cleartext lengths not integral
  110.     multiples of 8.
  111.  
  112.     No errors or meaningful value are returned.  Void is not used for
  113.     compatibility with other compilers.
  114.  
  115.  
  116. /* cbc checksum (MAC) only routine  ---------------------------------------- */
  117. int    
  118.     cbc_cksum(input,output,length,schedule,ivec)
  119.  
  120.     C_Block             *input;        /* >= length bytes of inputtext     */
  121.     C_Block             *output;    /* >= length bytes of outputtext */
  122.     int                length;        /* in bytes                        */
  123.     Key_schedule    schedule;    /* precomputed key schedule       */
  124.     C_Block            *ivec;        /* 8 bytes of ivec               */
  125.  
  126.  
  127.     Produces a cryptographic checksum, 8 bytes, by cipher-block-chain
  128.     encrypting the input, discarding the ciphertext output, and only retaining
  129.     the last ciphertext 8-byte block.  Uses the provided key schedule and ivec.
  130.     The input is effectively zero-padded to an integral multiple of
  131.     eight bytes, though the original input is not modified.
  132.  
  133.     No meaningful value is returned.  Void is not used for compatibility
  134.     with other compilers.
  135.  
  136.  
  137. /*    random_key ----------------------------------------*/
  138. int
  139.     random_key(key)
  140.  
  141.     C_Block    *key;
  142.  
  143.     The start for the random number generated is set from the current time
  144.     in microseconds, then the random number generator is invoked
  145.     to create an eight byte output key (not a schedule).  The key
  146.     generated is set to odd parity per FIPS spec.
  147.  
  148.     The caller must    supply space for the output key, pointed to 
  149.     by "*key", then after getting a new key, call the des_set_key() 
  150.     routine when needed.
  151.  
  152.     No meaningfull value is returned.  Void is not used for compatibility
  153.     with other compilers.
  154.  
  155.  
  156. /* string_to_key --------------------------------------------*/
  157.  
  158. int
  159.     string_to_key(str,key)
  160.     register char        *str;
  161.     register C_Block    *key;
  162.  
  163.     This routines converts an arbitrary length, null terminated string
  164.     to an 8 byte DES key, with each byte parity set to odd, per FIPS spec.
  165.  
  166.     The algorithm is as follows:
  167.  
  168. |    Take the first 8 bytes and remove the parity (leaving 56 bits).
  169. |    Do the same for the second 8 bytes, and the third, etc.  Do this for
  170. |    as many sets of 8 bytes as necessary, filling in the remainder of the
  171. |    last set with nulls.  Fold the second set back on the first (i.e. bit
  172. |    0 over bit 55, and bit 55 over bit 0).  Fold the third over the second
  173. |    (bit 0 of the third set is now over bit 0 of the first set).  Repeat
  174. |    until you have done this to all sets.  Xor the folded sets.  Break the
  175. |    result into 8 7 bit bytes, and generate odd parity for each byte.  You
  176. |    now have 64 bits.  Note that DES takes a 64 bit key, and uses only the
  177. |    non parity bits.
  178.  
  179.  
  180. /* read_password -------------------------------------------*/
  181.  
  182. read_password(k,prompt,verify)
  183.     C_Block    *k;
  184.     char *prompt;
  185.     int    verify;
  186.  
  187. This routine issues the supplied prompt, turns off echo, if possible, and
  188. reads an input string.  If verify is non-zero, it does it again, for use
  189. in applications such as changing a password. If verify is non-zero, both
  190. versions are compared, and the input is requested repeatedly until they
  191. match.  Then, the input string is mapped into a valid DES key, internally
  192. using the string_to_key routine.  The newly created key is copied to the
  193. area pointed to by parameter "k".  
  194.  
  195. No meaningful value is returned.  If an error occurs trying to manipulate
  196. the terminal echo, the routine forces the process to exit.
  197.  
  198. /* get_line ------------------------*/
  199. long get_line(p,max)
  200.     char    *p;
  201.     long    max;
  202.  
  203. Reads input characters from standard input until either a newline appears or
  204. else the max length is reached.  The characters read are stuffed into
  205. the string pointed to, which will always be null terminated.  The newline
  206. is not inserted in the string.  The max parameter includes the byte needed
  207. for the null terminator, so allocate and pass one more than the maximum
  208. string length desired.
  209.