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 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
  11 .\" can be distributed under GPL.
  12 .\" %%%LICENSE_END
  13 .\"
  14 .TH DES_CRYPT 3  2020-04-11 "" "Linux Programmer's Manual"
  15 .SH NAME
  16 des_crypt, ecb_crypt, cbc_crypt, des_setparity, DES_FAILED \- fast
  17 DES encryption
  18 .SH SYNOPSIS
  19 .nf
  20 .\" Sun version
  21 .\" .B #include <des_crypt.h>
  22 .B #include <rpc/des_crypt.h>
  23 .PP
  24 .BI "int ecb_crypt(char *" key ", char *" data ", unsigned " datalen ,
  25 .BI "              unsigned " mode );
  26 .PP
  27 .BI "int cbc_crypt(char *" key ", char *" data ", unsigned " datalen ,
  28 .BI "              unsigned " mode ", char *" ivec );
  29 .PP
  30 .BI "void des_setparity(char *" key );
  31 .PP
  32 .BI "int DES_FAILED(int " status );
  33 .fi
  34 .SH DESCRIPTION
  35 .BR ecb_crypt ()
  36 and
  37 .BR cbc_crypt ()
  38 implement the
  39 NBS
  40 DES
  41 (Data Encryption Standard).
  42 These routines are faster and more general purpose than
  43 .BR crypt (3).
  44 They also are able to utilize
  45 DES
  46 hardware if it is available.
  47 .BR ecb_crypt ()
  48 encrypts in
  49 ECB
  50 (Electronic Code Book)
  51 mode, which encrypts blocks of data independently.
  52 .BR cbc_crypt ()
  53 encrypts in
  54 CBC
  55 (Cipher Block Chaining)
  56 mode, which chains together
  57 successive blocks.
  58 CBC
  59 mode protects against insertions, deletions and
  60 substitutions of blocks.
  61 Also, regularities in the clear text will
  62 not appear in the cipher text.
  63 .PP
  64 Here is how to use these routines.
  65 The first argument,
  66 .IR key ,
  67 is the 8-byte encryption key with parity.
  68 To set the key's parity, which for
  69 DES
  70 is in the low bit of each byte, use
  71 .BR des_setparity ().
  72 The second argument,
  73 .IR data ,
  74 contains the data to be encrypted or decrypted.
  75 The
  76 third argument,
  77 .IR datalen ,
  78 is the length in bytes of
  79 .IR data ,
  80 which must be a multiple of 8.
  81 The fourth argument,
  82 .IR mode ,
  83 is formed by ORing together some things.
  84 For the encryption direction OR in either
  85 .BR DES_ENCRYPT
  86 or
  87 .BR DES_DECRYPT .
  88 For software versus hardware
  89 encryption, OR in either
  90 .BR DES_HW
  91 or
  92 .BR DES_SW .
  93 If
  94 .BR DES_HW
  95 is specified, and there is no hardware, then the encryption is performed
  96 in software and the routine returns
  97 .BR DESERR_NOHWDEVICE .
  98 For
  99 .BR cbc_crypt (),
 100 the argument
 101 .I ivec
 102 is the 8-byte initialization
 103 vector for the chaining.
 104 It is updated to the next initialization
 105 vector upon return.
 106 .SH RETURN VALUE
 107 .TP
 108 .BR DESERR_NONE
 109 No error.
 110 .TP
 111 .BR DESERR_NOHWDEVICE
 112 Encryption succeeded, but done in software instead of the requested hardware.
 113 .TP
 114 .BR DESERR_HWERROR
 115 An error occurred in the hardware or driver.
 116 .TP
 117 .BR DESERR_BADPARAM
 118 Bad argument to routine.
 119 .PP
 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 functions were added to glibc in version 2.1.
 131 .PP
 132 Because they employ the DES block cipher,
 133 which is no longer considered secure,
 134 .BR ecb_crypt (),
 135 .BR ecb_crypt (),
 136 .BR crypt_r (),
 137 and
 138 .BR des_setparity ()
 139 were removed in glibc 2.28.
 140 Applications should switch to a modern cryptography library, such as
 141 .BR libgcrypt .
 142 .SH ATTRIBUTES
 143 For an explanation of the terms used in this section, see
 144 .BR attributes (7).
 145 .TS
 146 allbox;
 147 lbw25 lb lb
 148 l l l.
 149 Interface       Attribute       Value
 150 T{
 151 .BR ecb_crypt (),
 152 .BR cbc_crypt (),
 153 .BR des_setparity ()
 154 T}      Thread safety   MT-Safe
 155 .TE
 156 .SH CONFORMING TO
 157 4.3BSD.
 158 Not in POSIX.1.
 159 .SH SEE ALSO
 160 .BR des (1),
 161 .BR crypt (3),
 162 .BR xcrypt (3)