BSD 4_4_Lite2 development

[unix-history] / usr / share / man / cat3 / des_crypt.0

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


N\bNA\bAM\bME\bE
       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

S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
       #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<k\bke\ber\brb\bbe\ber\bro\bos\bsI\bIV\bV/\b/d\bde\bes\bs.\b.h\bh>\b>

       i\bin\bnt\bt d\bde\bes\bs_\b_r\bre\bea\bad\bd_\b_p\bpa\bas\bss\bsw\bwo\bor\brd\bd(\b(k\bke\bey\by,\b,p\bpr\bro\bom\bmp\bpt\bt,\b,v\bve\ber\bri\bif\bfy\by)\b)
       des_cblock *key;
       char *prompt;
       int verify;

       i\bin\bnt\bt d\bde\bes\bs_\b_s\bst\btr\bri\bin\bng\bg_\b_t\bto\bo_\b_k\bke\bey\by(\b(s\bst\btr\br,\b,k\bke\bey\by)\b)
       c\bch\bha\bar\br *\b*s\bst\btr\br;\b;
       d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk k\bke\bey\by;\b;

       i\bin\bnt\bt d\bde\bes\bs_\b_r\bra\ban\bnd\bdo\bom\bm_\b_k\bke\bey\by(\b(k\bke\bey\by)\b)
       d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*k\bke\bey\by;\b;

       i\bin\bnt\bt d\bde\bes\bs_\b_s\bse\bet\bt_\b_k\bke\bey\by(\b(k\bke\bey\by,\b,s\bsc\bch\bhe\bed\bdu\bul\ble\be)\b)
       d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*k\bke\bey\by;\b;
       d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be s\bsc\bch\bhe\bed\bdu\bul\ble\be;\b;

       i\bin\bnt\bt d\bde\bes\bs_\b_e\bec\bcb\bb_\b_e\ben\bnc\bcr\bry\byp\bpt\bt(\b(i\bin\bnp\bpu\but\bt,\b,o\bou\but\btp\bpu\but\bt,\b,s\bsc\bch\bhe\bed\bdu\bul\ble\be,\b,e\ben\bnc\bcr\bry\byp\bpt\bt)\b)
       d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\bin\bnp\bpu\but\bt;\b;
       d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*o\bou\but\btp\bpu\but\bt;\b;
       d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be s\bsc\bch\bhe\bed\bdu\bul\ble\be;\b;
       i\bin\bnt\bt e\ben\bnc\bcr\bry\byp\bpt\bt;\b;

       i\bin\bnt\bt d\bde\bes\bs_\b_c\bcb\bbc\bc_\b_e\ben\bnc\bcr\bry\byp\bpt\bt(\b(i\bin\bnp\bpu\but\bt,\b,o\bou\but\btp\bpu\but\bt,\b,l\ble\ben\bng\bgt\bth\bh,\b,s\bsc\bch\bhe\bed\bdu\bul\ble\be,\b,i\biv\bve\bec\bc,\b,e\ben\bnc\bcr\bry\byp\bpt\bt)\b)
       d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\bin\bnp\bpu\but\bt;\b;
       d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*o\bou\but\btp\bpu\but\bt;\b;
       l\blo\bon\bng\bg l\ble\ben\bng\bgt\bth\bh;\b;
       d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be s\bsc\bch\bhe\bed\bdu\bul\ble\be;\b;
       d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\biv\bve\bec\bc;\b;
       i\bin\bnt\bt e\ben\bnc\bcr\bry\byp\bpt\bt;\b;

       i\bin\bnt\bt d\bde\bes\bs_\b_p\bpc\bcb\bbc\bc_\b_e\ben\bnc\bcr\bry\byp\bpt\bt(\b(i\bin\bnp\bpu\but\bt,\b,o\bou\but\btp\bpu\but\bt,\b,l\ble\ben\bng\bgt\bth\bh,\b,s\bsc\bch\bhe\bed\bdu\bul\ble\be,\b,i\biv\bve\bec\bc,\b,e\ben\bnc\bcr\bry\byp\bpt\bt)\b)
       d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\bin\bnp\bpu\but\bt;\b;
       d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*o\bou\but\btp\bpu\but\bt;\b;
       l\blo\bon\bng\bg l\ble\ben\bng\bgt\bth\bh;\b;
       d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be s\bsc\bch\bhe\bed\bdu\bul\ble\be;\b;
       d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\biv\bve\bec\bc;\b;
       i\bin\bnt\bt e\ben\bnc\bcr\bry\byp\bpt\bt;\b;

       u\bun\bns\bsi\big\bgn\bne\bed\bd l\blo\bon\bng\bg d\bde\bes\bs_\b_c\bcb\bbc\bc_\b_c\bck\bks\bsu\bum\bm(\b(i\bin\bnp\bpu\but\bt,\b,o\bou\but\btp\bpu\but\bt,\b,l\ble\ben\bng\bgt\bth\bh,\b,s\bsc\bch\bhe\bed\bdu\bul\ble\be,\b,i\biv\bve\bec\bc)\b)
       d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\bin\bnp\bpu\but\bt;\b;
       d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*o\bou\but\btp\bpu\but\bt;\b;
       l\blo\bon\bng\bg l\ble\ben\bng\bgt\bth\bh;\b;



MIT Project Athena     Kerberos Version 4.0                     1








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


       d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be s\bsc\bch\bhe\bed\bdu\bul\ble\be;\b;
       d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\biv\bve\bec\bc;\b;

       u\bun\bns\bsi\big\bgn\bne\bed\bd l\blo\bon\bng\bg q\bqu\bua\bad\bd_\b_c\bck\bks\bsu\bum\bm(\b(i\bin\bnp\bpu\but\bt,\b,o\bou\but\btp\bpu\but\bt,\b,l\ble\ben\bng\bgt\bth\bh,\b,o\bou\but\bt_\b_c\bco\bou\bun\bnt\bt,\b,s\bse\bee\bed\bd)\b)
       d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\bin\bnp\bpu\but\bt;\b;
       d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*o\bou\but\btp\bpu\but\bt;\b;
       l\blo\bon\bng\bg l\ble\ben\bng\bgt\bth\bh;\b;
       i\bin\bnt\bt o\bou\but\bt_\b_c\bco\bou\bun\bnt\bt;\b;
       d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*s\bse\bee\bed\bd;\b;


D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
       This library supports various DES encryption related oper-
       ations.  It  differs  from  the _\bc_\br_\by_\bp_\bt_\b, _\bs_\be_\bt_\bk_\be_\by_\b, _\ba_\bn_\bd _\be_\bn_\bc_\br_\by_\bp_\bt
       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
       d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be  struct, defined in "des.h". Next, create
       key schedules  (from  the  8-byte  keys)  as  needed,  via
       _\bd_\be_\bs_\b__\bs_\be_\bt_\b__\bk_\be_\by_\b,  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,    _\bd_\be_\bs_\b__\be_\bc_\bb_\b__\be_\bn_\bc_\br_\by_\bp_\bt    or    _\bd_\be_\bs_\b__\bc_\bb_\bc_\b__\be_\bn_\bc_\br_\by_\bp_\bt   or
       _\bd_\be_\bs_\b__\bp_\bc_\bb_\bc_\b__\be_\bn_\bc_\br_\by_\bp_\bt_\b, or, to generate a  cryptographic  check-
       sum, use _\bq_\bu_\ba_\bd_\b__\bc_\bk_\bs_\bu_\bm (fast) or _\bd_\be_\bs_\b__\bc_\bb_\bc_\b__\bc_\bk_\bs_\bu_\bm (slow).

       A  _\bd_\be_\bs_\b__\bc_\bb_\bl_\bo_\bc_\bk struct is an 8 byte block used as the funda-
       mental unit for DES data and keys, and is defined as:

       t\bty\byp\bpe\bed\bde\bef\bf   u\bun\bns\bsi\big\bgn\bne\bed\bd c\bch\bha\bar\br d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk[\b[8\b8]\b];\b;

       and a _\bd_\be_\bs_\b__\bk_\be_\by_\b__\bs_\bc_\bh_\be_\bd_\bu_\bl_\be_\b, is defined as:

       t\bty\byp\bpe\bed\bde\bef\bf   s\bst\btr\bru\buc\bct\bt     d\bde\bes\bs_\b_k\bks\bs_\b_s\bst\btr\bru\buc\bct\bt     {\b{d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk     _\b_;\b;}\b}
       d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be[\b[1\b16\b6]\b];\b;

       _\bd_\be_\bs_\b__\br_\be_\ba_\bd_\b__\bp_\ba_\bs_\bs_\bw_\bo_\br_\bd writes the string specified by _\bp_\br_\bo_\bm_\bp_\bt to
       the standard output, turns  off  echo  (if  possible)  and
       reads an input string from standard input until terminated
       with a newline.  If _\bv_\be_\br_\bi_\bf_\by 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
       _\bd_\be_\bs_\b__\br_\be_\ba_\bd_\b__\bp_\ba_\bs_\bs_\bw_\bo_\br_\bd converts the input string into  a  valid
       DES  key,  internally using the _\bd_\be_\bs_\b__\bs_\bt_\br_\bi_\bn_\bg_\b__\bt_\bo_\b__\bk_\be_\by routine.
       The newly created key is copied to the area pointed to  by
       the  _\bk_\be_\by argument.  _\bd_\be_\bs_\b__\br_\be_\ba_\bd_\b__\bp_\ba_\bs_\bs_\bw_\bo_\br_\bd 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.


       _\bd_\be_\bs_\b__\bs_\bt_\br_\bi_\bn_\bg_\b__\bt_\bo_\b__\bk_\be_\by   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 _\bs_\bt_\br argument
       is a pointer to the string, and  _\bk_\be_\by  should  point  to  a
       _\bd_\be_\bs_\b__\bc_\bb_\bl_\bo_\bc_\bk supplied by the caller to receive the generated
       key.  No meaningful value is returned. Void  is  not  used
       for compatibility with other compilers.


       _\bd_\be_\bs_\b__\br_\ba_\bn_\bd_\bo_\bm_\b__\bk_\be_\by  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 _\bk_\be_\by_\b, then after calling _\bd_\be_\bs_\b__\br_\ba_\bn_\bd_\bo_\bm_\b__\bk_\be_\by  should
       call  the  _\bd_\be_\bs_\b__\bs_\be_\bt_\b__\bk_\be_\by routine when needed.  No meaningful
       value is returned.  Void is  not  used  for  compatibility
       with other compilers.


       _\bd_\be_\bs_\b__\bs_\be_\bt_\b__\bk_\be_\by calculates a key schedule from all eight bytes
       of the input key, pointed to by the _\bk_\be_\by argument, and out-
       puts  the  schedule into the _\bd_\be_\bs_\b__\bk_\be_\by_\b__\bs_\bc_\bh_\be_\bd_\bu_\bl_\be indicated by
       the _\bs_\bc_\bh_\be_\bd_\bu_\bl_\be 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.


       _\bd_\be_\bs_\b__\be_\bc_\bb_\b__\be_\bn_\bc_\br_\by_\bp_\bt is the basic DES encryption  routine  that
       encrypts  or  decrypts a single 8-byte block in e\bel\ble\bec\bct\btr\bro\bon\bni\bic\bc
       c\bco\bod\bde\be b\bbo\boo\bok\bk mode.  It  always  transforms  the  input  data,
       pointed  to  by _\bi_\bn_\bp_\bu_\bt_\b, into the output data, pointed to by
       the _\bo_\bu_\bt_\bp_\bu_\bt argument.

       If the _\be_\bn_\bc_\br_\by_\bp_\bt argument is non-zero, the _\bi_\bn_\bp_\bu_\bt (cleartext)
       is  encrypted  into  the  _\bo_\bu_\bt_\bp_\bu_\bt  (ciphertext)  using  the
       key_schedule specified by the  _\bs_\bc_\bh_\be_\bd_\bu_\bl_\be  argument,  previ-
       ously set via _\bd_\be_\bs_\b__\bs_\be_\bt_\b__\bk_\be_\by



MIT Project Athena     Kerberos Version 4.0                     3








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


       If   encrypt  is  zero,  the  _\bi_\bn_\bp_\bu_\bt  (now  ciphertext)  is
       decrypted into the _\bo_\bu_\bt_\bp_\bu_\bt (now cleartext).

       Input and output may overlap.

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


       _\bd_\be_\bs_\b__\bc_\bb_\bc_\b__\be_\bn_\bc_\br_\by_\bp_\bt  encrypts/decrypts using the c\bci\bip\bph\bhe\ber\br-\b-b\bbl\blo\boc\bck\bk-\b-
       c\bch\bha\bai\bin\bni\bin\bng\bg m\bmo\bod\bde\be o\bof\bf D\bDE\bES\bS.\b.  If the  _\be_\bn_\bc_\br_\by_\bp_\bt  argument  is  non-
       zero,  the routine cipher-block-chain encrypts the cleart-
       ext data pointed to by the _\bi_\bn_\bp_\bu_\bt argument into the cipher-
       text  pointed  to  by  the  _\bo_\bu_\bt_\bp_\bu_\bt argument, using the key
       schedule provided by the _\bs_\bc_\bh_\be_\bd_\bu_\bl_\be argument,  and  initial-
       ization  vector  provided  by  the  _\bi_\bv_\be_\bc argument.  If the
       _\bl_\be_\bn_\bg_\bt_\bh 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   _\be_\bn_\bc_\br_\by_\bp_\bt  is  zero,  the  routine  cipher-block  chain
       decrypts the (now) ciphertext data pointed to by the _\bi_\bn_\bp_\bu_\bt
       argument  into  (now)  cleartext  pointed to by the _\bo_\bu_\bt_\bp_\bu_\bt
       argument using the key schedule provided by  the  _\bs_\bc_\bh_\be_\bd_\bu_\bl_\be
       argument,  and  initialization vector provided by the _\bi_\bv_\be_\bc
       argument. Decryption ALWAYS operates on integral multiples
       of 8 bytes, so it will round the _\bl_\be_\bn_\bg_\bt_\bh 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,  _\bd_\be_\bs_\b__\bp_\bc_\bb_\bc_\b__\be_\bn_\bc_\br_\by_\bp_\bt  is  STRONGLY recom-
       mended for applications where  indefinite  propagation  of
       errors is required in order to detect modifications.


       _\bd_\be_\bs_\b__\bp_\bc_\bb_\bc_\b__\be_\bn_\bc_\br_\by_\bp_\bt  encrypts/decrypts using a modified block
       chaining  mode.  Its  calling  sequence  is  identical  to
       _\bd_\be_\bs_\b__\bc_\bb_\bc_\b__\be_\bn_\bc_\br_\by_\bp_\bt_\b.   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.

       _\bd_\be_\bs_\b__\bp_\bc_\bb_\bc_\b__\be_\bn_\bc_\br_\by_\bp_\bt 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.

       _\bd_\be_\bs_\b__\bc_\bb_\bc_\b__\bc_\bk_\bs_\bu_\bm produces an 8 byte cryptographic checksum by
       cipher-block-chain  encrypting  the cleartext data pointed
       to by the _\bi_\bn_\bp_\bu_\bt 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  _\bo_\bu_\bt_\bp_\bu_\bt  argu-
       ment.   It uses the key schedule, provided by the _\bs_\bc_\bh_\be_\bd_\bu_\bl_\be
       argument and initialization vector provided  by  the  _\bi_\bv_\be_\bc
       argument.   If the _\bl_\be_\bn_\bg_\bt_\bh 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.


       _\bq_\bu_\ba_\bd_\b__\bc_\bk_\bs_\bu_\bm produces a checksum by chaining quadratic oper-
       ations on the cleartext data pointed to by the _\bi_\bn_\bp_\bu_\bt argu-
       ment. The _\bl_\be_\bn_\bg_\bt_\bh 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 _\bo_\bu_\bt_\b__\bc_\bo_\bu_\bn_\bt argument is 2, 3 or 4, and the optional _\bo_\bu_\bt_\b-
       _\bp_\bu_\bt 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 _\bs_\be_\be_\bd 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  _\bo_\bu_\bt_\bp_\bu_\bt 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)


F\bFI\bIL\bLE\bES\bS
       /usr/include/kerberosIV/des.h
       /usr/lib/libdes.a

S\bSE\bEE\bE A\bAL\bLS\bSO\bO
D\bDI\bIA\bAG\bGN\bNO\bOS\bST\bTI\bIC\bCS\bS
B\bBU\bUG\bGS\bS
       This software has not  yet  been  compiled  or  tested  on
       machines other than the VAX and the IBM PC.

A\bAU\bUT\bTH\bHO\bOR\bRS\bS
       Steve  Miller, MIT Project Athena/Digital Equipment Corpo-
       ration

R\bRE\bES\bST\bTR\bRI\bIC\bCT\bTI\bIO\bON\bNS\bS
       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