man3/des_crypt.3

   1 '\" t
   2 .\" @(#)des_crypt.3     2.1 88/08/11 4.0 RPCSRC; from 1.16 88/03/02 SMI;
   3 .\"
   4 .\" Taken from libc4 sources, which say:
   5 .\" Copyright (C) 1993 Eric Young - can be distributed under GPL.
   6 .\"
   7 .\" However, the above header line suggests that this file in fact is
   8 .\" Copyright Sun Microsystems, Inc (and is provided for unrestricted use,
   9 .\" see other Sun RPC sources).
  10 .\"
  11 .\" SPDX-License-Identifier: GPL-1.0-or-later
  12 .\"
  13 .TH des_crypt 3 (date) "Linux man-pages (unreleased)"
  14 .SH NAME
  15 des_crypt, ecb_crypt, cbc_crypt, des_setparity, DES_FAILED \- fast
  16 DES encryption
  17 .SH LIBRARY
  18 Standard C library
  19 .RI ( libc ", " \-lc )
  20 .SH SYNOPSIS
  21 .nf
  22 .\" Sun version
  23 .\" .B #include <des_crypt.h>
  24 .B #include <rpc/des_crypt.h>
  25 .P
  26 .BI "[[deprecated]] int ecb_crypt(char *" key ", char " data [. datalen ],
  27 .BI "                             unsigned int " datalen ", \
  28 unsigned int " mode );
  29 .BI "[[deprecated]] int cbc_crypt(char *" key ", char " data [. datalen ],
  30 .BI "                             unsigned int " datalen ", \
  31 unsigned int " mode ,
  32 .BI "                             char *" ivec );
  33 .P
  34 .BI "[[deprecated]] void des_setparity(char *" key );
  35 .P
  36 .BI "[[deprecated]] int DES_FAILED(int " status );
  37 .fi
  38 .SH DESCRIPTION
  39 .BR ecb_crypt ()
  40 and
  41 .BR cbc_crypt ()
  42 implement the
  43 NBS
  44 DES
  45 (Data Encryption Standard).
  46 These routines are faster and more general purpose than
  47 .BR crypt (3).
  48 They also are able to utilize
  49 DES
  50 hardware if it is available.
  51 .BR ecb_crypt ()
  52 encrypts in
  53 ECB
  54 (Electronic Code Book)
  55 mode, which encrypts blocks of data independently.
  56 .BR cbc_crypt ()
  57 encrypts in
  58 CBC
  59 (Cipher Block Chaining)
  60 mode, which chains together
  61 successive blocks.
  62 CBC
  63 mode protects against insertions, deletions, and
  64 substitutions of blocks.
  65 Also, regularities in the clear text will
  66 not appear in the cipher text.
  67 .P
  68 Here is how to use these routines.
  69 The first argument,
  70 .IR key ,
  71 is the 8-byte encryption key with parity.
  72 To set the key's parity, which for
  73 DES
  74 is in the low bit of each byte, use
  75 .BR des_setparity ().
  76 The second argument,
  77 .IR data ,
  78 contains the data to be encrypted or decrypted.
  79 The
  80 third argument,
  81 .IR datalen ,
  82 is the length in bytes of
  83 .IR data ,
  84 which must be a multiple of 8.
  85 The fourth argument,
  86 .IR mode ,
  87 is formed by ORing together some things.
  88 For the encryption direction OR in either
  89 .B DES_ENCRYPT
  90 or
  91 .BR DES_DECRYPT .
  92 For software versus hardware
  93 encryption, OR in either
  94 .B DES_HW
  95 or
  96 .BR DES_SW .
  97 If
  98 .B DES_HW
  99 is specified, and there is no hardware, then the encryption is performed
 100 in software and the routine returns
 101 .BR DESERR_NOHWDEVICE .
 102 For
 103 .BR cbc_crypt (),
 104 the argument
 105 .I ivec
 106 is the 8-byte initialization
 107 vector for the chaining.
 108 It is updated to the next initialization
 109 vector upon return.
 110 .SH RETURN VALUE
 111 .TP
 112 .B DESERR_NONE
 113 No error.
 114 .TP
 115 .B DESERR_NOHWDEVICE
 116 Encryption succeeded, but done in software instead of the requested hardware.
 117 .TP
 118 .B DESERR_HWERROR
 119 An error occurred in the hardware or driver.
 120 .TP
 121 .B DESERR_BADPARAM
 122 Bad argument to routine.
 123 .P
 124 Given a result status
 125 .IR stat ,
 126 the macro
 127 .\" .BR DES_FAILED\c
 128 .\" .BR ( stat )
 129 .BI DES_FAILED( stat )
 130 is false only for the first two statuses.
 131 .\" So far the Sun page
 132 .\" Some additions - aeb
 133 .SH ATTRIBUTES
 134 For an explanation of the terms used in this section, see
 135 .BR attributes (7).
 136 .TS
 137 allbox;
 138 lbx lb lb
 139 l l l.
 140 Interface       Attribute       Value
 141 T{
 142 .na
 143 .nh
 144 .BR ecb_crypt (),
 145 .BR cbc_crypt (),
 146 .BR des_setparity ()
 147 T}      Thread safety   MT-Safe
 148 .TE
 149 .SH STANDARDS
 150 None.
 151 .SH HISTORY
 152 4.3BSD.
 153 glibc 2.1.
 154 Removed in glibc 2.28.
 155 .P
 156 Because they employ the DES block cipher,
 157 which is no longer considered secure,
 158 these functions were removed.
 159 Applications should switch to a modern cryptography library, such as
 160 .BR libgcrypt .
 161 .SH SEE ALSO
 162 .BR des (1),
 163 .BR crypt (3),
 164 .BR xcrypt (3)