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