man3/des_crypt.3

   1 .\" @(#)des_crypt.3     2.1 88/08/11 4.0 RPCSRC; from 1.16 88/03/02 SMI;
   2 .\"
   3 .\" Taken from libc4 sources, which say:
   4 .\" Copyright (C) 1993 Eric Young - can be distributed under GPL.
   5 .\"
   6 .\" However, the above header line suggests that this file in fact is
   7 .\" Copyright Sun Microsystems, Inc (and is provided for unrestricted use,
   8 .\" see other Sun RPC sources).
   9 .\"
  10 .TH DES_CRYPT 3  2007-05-18 "" "Linux Programmer's Manual"
  11 .SH NAME
  12 des_crypt, ecb_crypt, cbc_crypt, des_setparity, DES_FAILED \- fast
  13 DES encryption
  14 .SH SYNOPSIS
  15 .nf
  16 .\" Sun version
  17 .\" .B #include <des_crypt.h>
  18 .B #include <rpc/des_crypt.h>
  19 .LP
  20 .BI "int ecb_crypt(char *" key ", char *" data ", unsigned " datalen ,
  21 .BI "              unsigned " mode );
  22 .LP
  23 .BI "int cbc_crypt(char *" key ", char *" data ", unsigned " datalen ,
  24 .BI "              unsigned " mode ", char *" ivec );
  25 .LP
  26 .BI "void des_setparity(char *" key );
  27 .LP
  28 .BI "int DES_FAILED(int " status );
  29 .fi
  30 .SH DESCRIPTION
  31 .BR ecb_crypt ()
  32 and
  33 .BR cbc_crypt ()
  34 implement the
  35 NBS
  36 DES
  37 (Data Encryption Standard).
  38 These routines are faster and more general purpose than
  39 .BR crypt (3).
  40 They also are able to utilize
  41 DES
  42 hardware if it is available.
  43 .BR ecb_crypt ()
  44 encrypts in
  45 ECB
  46 (Electronic Code Book)
  47 mode, which encrypts blocks of data independently.
  48 .BR cbc_crypt ()
  49 encrypts in
  50 CBC
  51 (Cipher Block Chaining)
  52 mode, which chains together
  53 successive blocks.
  54 CBC
  55 mode protects against insertions, deletions and
  56 substitutions of blocks.
  57 Also, regularities in the clear text will
  58 not appear in the cipher text.
  59 .LP
  60 Here is how to use these routines.
  61 The first argument,
  62 .IR key ,
  63 is the 8-byte encryption key with parity.
  64 To set the key's parity, which for
  65 DES
  66 is in the low bit of each byte, use
  67 .BR des_setparity ().
  68 The second argument,
  69 .IR data ,
  70 contains the data to be encrypted or decrypted.
  71 The
  72 third argument,
  73 .IR datalen ,
  74 is the length in bytes of
  75 .IR data ,
  76 which must be a multiple of 8.
  77 The fourth argument,
  78 .IR mode ,
  79 is formed by
  80 OR 'ing
  81 together some things.
  82 For the encryption direction OR in either
  83 .BR DES_ENCRYPT
  84 or
  85 .BR DES_DECRYPT .
  86 For software versus hardware
  87 encryption, OR in either
  88 .BR DES_HW
  89 or
  90 .BR DES_SW .
  91 If
  92 .BR DES_HW
  93 is specified, and there is no hardware, then the encryption is performed
  94 in software and the routine returns
  95 .BR DESERR_NOHWDEVICE .
  96 For
  97 .BR cbc_crypt (),
  98 the argument
  99 .I ivec
 100 is the 8-byte initialization
 101 vector for the chaining.
 102 It is updated to the next initialization
 103 vector upon return.
 104 .SH RETURN VALUE
 105 .PD 0
 106 .TP 20
 107 .BR DESERR_NONE
 108 No error.
 109 .TP
 110 .BR DESERR_NOHWDEVICE
 111 Encryption succeeded, but done in software instead of the requested hardware.
 112 .TP
 113 .BR DESERR_HWERROR
 114 An error occurred in the hardware or driver.
 115 .TP
 116 .BR DESERR_BADPARAM
 117 Bad argument to routine.
 118 .PD
 119 .LP
 120 Given a result status
 121 .IR stat ,
 122 the macro
 123 .\" .BR DES_FAILED\c
 124 .\" .BR ( stat )
 125 .BI DES_FAILED( stat )
 126 is false only for the first two statuses.
 127 .\" So far the Sun page
 128 .\" Some additions - aeb
 129 .SH VERSIONS
 130 These routines are present in libc 4.6.27 and later, and in
 131 glibc 2.1 and later.
 132 .SH "CONFORMING TO"
 133 4.3BSD.
 134 Not in POSIX.1-2001.
 135 .SH "SEE ALSO"
 136 .BR des (1),
 137 .BR crypt (3),
 138 .BR xcrypt (3)