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