unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (4.4BSD-Lite2)
Page:
Section:
Apropos / Subsearch:
optional field



DES_CRYPT(3)         BSD Programmer's Manual         DES_CRYPT(3)


NAME
       des_read_password,    des_string_to_key,   des_random_key,
       des_set_key,       des_ecb_encrypt,       des_cbc_encrypt,
       des_pcbc_encrypt,  des_cbc_cksum,  des_quad_cksum, - (new)
       DES encryption

SYNOPSIS
       #include <&lt;kerberosIV/des.h>&gt;

       int des_read_password(key,prompt,verify)
       des_cblock *key;
       char *prompt;
       int verify;

       int des_string_to_key(str,key)
       char *str;
       des_cblock key;

       int des_random_key(key)
       des_cblock *key;

       int des_set_key(key,schedule)
       des_cblock *key;
       des_key_schedule schedule;

       int des_ecb_encrypt(input,output,schedule,encrypt)
       des_cblock *input;
       des_cblock *output;
       des_key_schedule schedule;
       int encrypt;

       int des_cbc_encrypt(input,output,length,schedule,ivec,encrypt)
       des_cblock *input;
       des_cblock *output;
       long length;
       des_key_schedule schedule;
       des_cblock *ivec;
       int encrypt;

       int des_pcbc_encrypt(input,output,length,schedule,ivec,encrypt)
       des_cblock *input;
       des_cblock *output;
       long length;
       des_key_schedule schedule;
       des_cblock *ivec;
       int encrypt;

       unsigned long des_cbc_cksum(input,output,length,schedule,ivec)
       des_cblock *input;
       des_cblock *output;
       long length;



MIT Project Athena     Kerberos Version 4.0                     1








DES_CRYPT(3)         BSD Programmer's Manual         DES_CRYPT(3)


       des_key_schedule schedule;
       des_cblock *ivec;

       unsigned long quad_cksum(input,output,length,out_count,seed)
       des_cblock *input;
       des_cblock *output;
       long length;
       int out_count;
       des_cblock *seed;


DESCRIPTION
       This library supports various DES encryption related oper-
       ations.  It  differs  from  the crypt, setkey, and encrypt
       library routines in that it provides a  true  DES  encryp-
       tion,  without  modifying the algorithm, and executes much
       faster.

       For each key that may be simultaneously active,  create  a
       des_key_schedule  struct, defined in "des.h". Next, create
       key schedules  (from  the  8-byte  keys)  as  needed,  via
       des_set_key,  prior  to  using  the encryption or checksum
       routines. Then setup the input  and  output  areas.   Make
       sure  to  note the restrictions on lengths being multiples
       of eight bytes. Finally, invoke the  encryption/decryption
       routines,    des_ecb_encrypt    or    des_cbc_encrypt   or
       des_pcbc_encrypt, or, to generate a  cryptographic  check-
       sum, use quad_cksum (fast) or des_cbc_cksum (slow).

       A  des_cblock struct is an 8 byte block used as the funda-
       mental unit for DES data and keys, and is defined as:

       typedef   unsigned char des_cblock[8];

       and a des_key_schedule, is defined as:

       typedef   struct     des_ks_struct     {des_cblock     _;}
       des_key_schedule[16];

       des_read_password writes the string specified by prompt to
       the standard output, turns  off  echo  (if  possible)  and
       reads an input string from standard input until terminated
       with a newline.  If verify is  non-zero,  it  prompts  and
       reads  input again, for use in applications such as chang-
       ing a password; both versions are compared, and the  input
       is   requested   repeatedly   until   they   match.   Then
       des_read_password converts the input string into  a  valid
       DES  key,  internally using the des_string_to_key routine.
       The newly created key is copied to the area pointed to  by
       the  key argument.  des_read_password returns a zero if no
       errors occurred, or a -1 indicating that an error occurred



MIT Project Athena     Kerberos Version 4.0                     2








DES_CRYPT(3)         BSD Programmer's Manual         DES_CRYPT(3)


       trying to manipulate the terminal echo.


       des_string_to_key   converts  an  arbitrary  length  null-
       terminated string to an 8 byte DES key, with odd byte par-
       ity,  per  FIPS specification.  A one-way function is used
       to convert the string to a key, making it  very  difficult
       to  reconstruct the string from the key.  The str argument
       is a pointer to the string, and  key  should  point  to  a
       des_cblock supplied by the caller to receive the generated
       key.  No meaningful value is returned. Void  is  not  used
       for compatibility with other compilers.


       des_random_key  generates  a  random  DES  encryption  key
       (eight bytes), set to odd parity per FIPS  specifications.
       This  routine  uses  the  current  time, process id, and a
       counter as a seed for the random  number  generator.   The
       caller  must   supply space for the output key, pointed to
       by argument key, then after calling des_random_key  should
       call  the  des_set_key routine when needed.  No meaningful
       value is returned.  Void is  not  used  for  compatibility
       with other compilers.


       des_set_key calculates a key schedule from all eight bytes
       of the input key, pointed to by the key argument, and out-
       puts  the  schedule into the des_key_schedule indicated by
       the schedule argument. Make sure to  pass  a  valid  eight
       byte  key;  no padding is done.  The key schedule may then
       be used in subsequent encryption/decryption/checksum oper-
       ations.   Many  key schedules may be cached for later use.
       The user is responsible to clear  keys  and  schedules  as
       soon  as  no  longer  needed, to prevent their disclosure.
       The routine also checks the key parity, and returns a zero
       if  the key parity is correct (odd), a -1 indicating a key
       parity error, or a -2 indicating use of  an  illegal  weak
       key.  If  an  error  is returned, the key schedule was not
       created.


       des_ecb_encrypt is the basic DES encryption  routine  that
       encrypts  or  decrypts a single 8-byte block 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, the input (cleartext)
       is  encrypted  into  the  output  (ciphertext)  using  the
       key_schedule specified by the  schedule  argument,  previ-
       ously set via des_set_key



MIT Project Athena     Kerberos Version 4.0                     3








DES_CRYPT(3)         BSD Programmer's Manual         DES_CRYPT(3)


       If   encrypt  is  zero,  the  input  (now  ciphertext)  is
       decrypted into the output (now cleartext).

       Input and output may overlap.

       No meaningful value is returned.  Void  is  not  used  for
       compatibility with other compilers.


       des_cbc_encrypt  encrypts/decrypts using the cipher-block-
       chaining mode of DES.  If the  encrypt  argument  is  non-
       zero,  the routine cipher-block-chain encrypts the cleart-
       ext data pointed to by the input argument into the cipher-
       text  pointed  to  by  the  output argument, using the key
       schedule provided by the schedule argument,  and  initial-
       ization  vector  provided  by  the  ivec argument.  If the
       length argument is  not  an  integral  multiple  of  eight
       bytes,  the last block is copied to a temp and zero filled
       (highest addresses).  The output  is  ALWAYS  an  integral
       multiple of eight bytes.

       If   encrypt  is  zero,  the  routine  cipher-block  chain
       decrypts the (now) ciphertext data pointed to by the input
       argument  into  (now)  cleartext  pointed to by the output
       argument using the key schedule provided by  the  schedule
       argument,  and  initialization vector provided by the ivec
       argument. Decryption ALWAYS operates on integral multiples
       of 8 bytes, so it will round the length provided up to the
       appropriate multiple. Consequently, it will always produce
       the  rounded-up  number  of bytes of output cleartext. The
       application must determine if  the  output  cleartext  was
       zero-padded  due  to  original cleartext lengths that were
       not integral multiples of 8.

       No errors or meaningful values are returned.  Void is  not
       used for compatibility with other compilers.

       A characteristic of cbc mode is that changing a single bit
       of the cleartext, then encrypting using cbc mode,  affects
       ALL  the  subsequent ciphertext.  This makes cryptanalysis
       much more difficult. However, modifying a  single  bit  of
       the  ciphertext, then decrypting, only affects the result-
       ing cleartext from the modified block and  the  succeeding
       block.   Therefore,  des_pcbc_encrypt  is  STRONGLY recom-
       mended for applications where  indefinite  propagation  of
       errors is required in order to detect modifications.


       des_pcbc_encrypt  encrypts/decrypts using a modified block
       chaining  mode.  Its  calling  sequence  is  identical  to
       des_cbc_encrypt.   It  differs  in  its  error propagation



MIT Project Athena     Kerberos Version 4.0                     4








DES_CRYPT(3)         BSD Programmer's Manual         DES_CRYPT(3)


       characteristics.

       des_pcbc_encrypt is highly recommended for most encryption
       purposes,  in  that  modification  of  a single bit of the
       ciphertext will  affect  ALL  the  subsequent  (decrypted)
       cleartext. Similarly, modifying a single bit of the clear-
       text will affect ALL the  subsequent  (encrypted)  cipher-
       text.  "PCBC" mode, on encryption, "xors" both the cleart-
       ext of block N and the ciphertext resulting from  block  N
       with the cleartext for block N+1 prior to encrypting block
       N+1.

       des_cbc_cksum produces an 8 byte cryptographic checksum by
       cipher-block-chain  encrypting  the cleartext data pointed
       to by the input argument. All of the ciphertext output  is
       discarded,  except the last 8-byte ciphertext block, which
       is written into the area pointed to by  the  output  argu-
       ment.   It uses the key schedule, provided by the schedule
       argument and initialization vector provided  by  the  ivec
       argument.   If the length argument is not an integral mul-
       tiple of eight bytes, the last cleartext block  is  copied
       to a temp and zero filled (highest addresses).  The output
       is ALWAYS eight bytes.

       The routine also returns an unsigned long,  which  is  the
       last  (highest  address)  half of the 8 byte checksum com-
       puted.


       quad_cksum produces a checksum by chaining quadratic oper-
       ations on the cleartext data pointed to by the input argu-
       ment. The length argument  specifies  the  length  of  the
       input -- only exactly that many bytes are included for the
       checksum, without any padding.

       The algorithm may be iterated over the same input data, if
       the out_count argument is 2, 3 or 4, and the optional out-
       put argument is a non-null pointer .  The default  is  one
       iteration, and it will not run more than 4 times. Multiple
       iterations run slower, but provide a  longer  checksum  if
       desired. The seed argument provides an 8-byte seed for the
       first iteration. If multiple iterations are requested, the
       results  of  one  iteration  are automatically used as the
       seed for the next iteration.

       It returns both an unsigned long checksum  value,  and  if
       the  output argument is not a null pointer, up to 16 bytes
       of the computed checksum are written into the output.






MIT Project Athena     Kerberos Version 4.0                     5








DES_CRYPT(3)         BSD Programmer's Manual         DES_CRYPT(3)


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

SEE ALSO
DIAGNOSTICS
BUGS
       This software has not  yet  been  compiled  or  tested  on
       machines other than the VAX and the IBM PC.

AUTHORS
       Steve  Miller, MIT Project Athena/Digital Equipment Corpo-
       ration

RESTRICTIONS
       COPYRIGHT 1985,1986 Massachusetts Institute of Technology

       This software may not be exported outside of the US  with-
       out a special license from the US Dept of Commerce. It may
       be replaced by any secret  key  block  cipher  with  block
       length and key length of 8 bytes, as long as the interface
       is the same as described here.
































MIT Project Athena     Kerberos Version 4.0                     6