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