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