lib/libc/rpc/des_crypt.3

   1 .\" @(#)des_crypt.3     2.1 88/08/11 4.0 RPCSRC; from 1.16 88/03/02 SMI;
   2 .\" $FreeBSD$
   3 .\"
   4 .Dd October 6, 1987
   5 .Dt DES_CRYPT 3
   6 .Os
   7 .Sh NAME
   8 .Nm des_crypt , ecb_crypt , cbc_crypt , des_setparity
   9 .Nd "fast DES encryption"
  10 .Sh LIBRARY
  11 .Lb libc
  12 .Sh SYNOPSIS
  13 .In rpc/des_crypt.h
  14 .Ft int
  15 .Fn ecb_crypt "char *key" "char *data" "unsigned datalen" "unsigned mode"
  16 .Ft int
  17 .Fn cbc_crypt "char *key" "char *data" "unsigned datalen" "unsigned mode" "char *ivec"
  18 .Ft void
  19 .Fn des_setparity "char *key"
  20 .Sh DESCRIPTION
  21 The
  22 .Fn ecb_crypt
  23 and
  24 .Fn cbc_crypt
  25 functions
  26 implement the
  27 .Tn NBS
  28 .Tn DES
  29 (Data Encryption Standard).
  30 These routines are faster and more general purpose than
  31 .Xr crypt 3 .
  32 They also are able to utilize
  33 .Tn DES
  34 hardware if it is available.
  35 The
  36 .Fn ecb_crypt
  37 function
  38 encrypts in
  39 .Tn ECB
  40 (Electronic Code Book)
  41 mode, which encrypts blocks of data independently.
  42 The
  43 .Fn cbc_crypt
  44 function
  45 encrypts in
  46 .Tn CBC
  47 (Cipher Block Chaining)
  48 mode, which chains together
  49 successive blocks.
  50 .Tn CBC
  51 mode protects against insertions, deletions and
  52 substitutions of blocks.
  53 Also, regularities in the clear text will
  54 not appear in the cipher text.
  55 .Pp
  56 Here is how to use these routines.
  57 The first argument,
  58 .Fa key ,
  59 is the 8-byte encryption key with parity.
  60 To set the key's parity, which for
  61 .Tn DES
  62 is in the low bit of each byte, use
  63 .Fn des_setparity .
  64 The second argument,
  65 .Fa data ,
  66 contains the data to be encrypted or decrypted.
  67 The
  68 third argument,
  69 .Fa datalen ,
  70 is the length in bytes of
  71 .Fa data ,
  72 which must be a multiple of 8.
  73 The fourth argument,
  74 .Fa mode ,
  75 is formed by
  76 .Em OR Ns 'ing
  77 together some things.
  78 For the encryption direction
  79 .Em OR
  80 in either
  81 .Dv DES_ENCRYPT
  82 or
  83 .Dv DES_DECRYPT .
  84 For software versus hardware
  85 encryption,
  86 .Em OR
  87 in either
  88 .Dv DES_HW
  89 or
  90 .Dv DES_SW .
  91 If
  92 .Dv DES_HW
  93 is specified, and there is no hardware, then the encryption is performed
  94 in software and the routine returns
  95 .Er DESERR_NOHWDEVICE .
  96 For
  97 .Fn cbc_crypt ,
  98 the
  99 .Fa ivec
 100 argument
 101 is the 8-byte initialization
 102 vector for the chaining.
 103 It is updated to the next initialization
 104 vector upon return.
 105 .Sh ERRORS
 106 .Bl -tag -width [DESERR_NOHWDEVICE] -compact
 107 .It Bq Er DESERR_NONE
 108 No error.
 109 .It Bq Er DESERR_NOHWDEVICE
 110 Encryption succeeded, but done in software instead of the requested hardware.
 111 .It Bq Er DESERR_HWERR
 112 An error occurred in the hardware or driver.
 113 .It Bq Er DESERR_BADPARAM
 114 Bad argument to routine.
 115 .El
 116 .Pp
 117 Given a result status
 118 .Va stat ,
 119 the macro
 120 .Fn DES_FAILED stat
 121 is false only for the first two statuses.
 122 .Sh SEE ALSO
 123 .\" .Xr des 1 ,
 124 .Xr crypt 3
 125 .Sh RESTRICTIONS
 126 These routines are not available in RPCSRC 4.0.
 127 This information is provided to describe the
 128 .Tn DES
 129 interface expected by
 130 Secure RPC.