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  2021-03-22 "" "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 int " datalen ,
  25 .BI "              unsigned int " mode );
  26 .BI "int cbc_crypt(char *" key ", char *" data ", unsigned int " datalen ,
  27 .BI "              unsigned int " mode ", char *" ivec );
  28 .PP
  29 .BI "void des_setparity(char *" key );
  30 .PP
  31 .BI "int DES_FAILED(int " status );
  32 .fi
  33 .SH DESCRIPTION
  34 .BR ecb_crypt ()
  35 and
  36 .BR cbc_crypt ()
  37 implement the
  38 NBS
  39 DES
  40 (Data Encryption Standard).
  41 These routines are faster and more general purpose than
  42 .BR crypt (3).
  43 They also are able to utilize
  44 DES
  45 hardware if it is available.
  46 .BR ecb_crypt ()
  47 encrypts in
  48 ECB
  49 (Electronic Code Book)
  50 mode, which encrypts blocks of data independently.
  51 .BR cbc_crypt ()
  52 encrypts in
  53 CBC
  54 (Cipher Block Chaining)
  55 mode, which chains together
  56 successive blocks.
  57 CBC
  58 mode protects against insertions, deletions, and
  59 substitutions of blocks.
  60 Also, regularities in the clear text will
  61 not appear in the cipher text.
  62 .PP
  63 Here is how to use these routines.
  64 The first argument,
  65 .IR key ,
  66 is the 8-byte encryption key with parity.
  67 To set the key's parity, which for
  68 DES
  69 is in the low bit of each byte, use
  70 .BR des_setparity ().
  71 The second argument,
  72 .IR data ,
  73 contains the data to be encrypted or decrypted.
  74 The
  75 third argument,
  76 .IR datalen ,
  77 is the length in bytes of
  78 .IR data ,
  79 which must be a multiple of 8.
  80 The fourth argument,
  81 .IR mode ,
  82 is formed by ORing together some things.
  83 For the encryption direction OR in either
  84 .BR DES_ENCRYPT
  85 or
  86 .BR DES_DECRYPT .
  87 For software versus hardware
  88 encryption, OR in either
  89 .BR DES_HW
  90 or
  91 .BR DES_SW .
  92 If
  93 .BR DES_HW
  94 is specified, and there is no hardware, then the encryption is performed
  95 in software and the routine returns
  96 .BR DESERR_NOHWDEVICE .
  97 For
  98 .BR cbc_crypt (),
  99 the argument
 100 .I ivec
 101 is the 8-byte initialization
 102 vector for the chaining.
 103 It is updated to the next initialization
 104 vector upon return.
 105 .SH RETURN VALUE
 106 .TP
 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 .PP
 119 Given a result status
 120 .IR stat ,
 121 the macro
 122 .\" .BR DES_FAILED\c
 123 .\" .BR ( stat )
 124 .BI DES_FAILED( stat )
 125 is false only for the first two statuses.
 126 .\" So far the Sun page
 127 .\" Some additions - aeb
 128 .SH VERSIONS
 129 These functions were added to glibc in version 2.1.
 130 .PP
 131 Because they employ the DES block cipher,
 132 which is no longer considered secure,
 133 .BR ecb_crypt (),
 134 .BR ecb_crypt (),
 135 .BR crypt_r (),
 136 and
 137 .BR des_setparity ()
 138 were removed in glibc 2.28.
 139 Applications should switch to a modern cryptography library, such as
 140 .BR libgcrypt .
 141 .SH ATTRIBUTES
 142 For an explanation of the terms used in this section, see
 143 .BR attributes (7).
 144 .ad l
 145 .nh
 146 .TS
 147 allbox;
 148 lbx lb lb
 149 l l l.
 150 Interface       Attribute       Value
 151 T{
 152 .BR ecb_crypt (),
 153 .BR cbc_crypt (),
 154 .BR des_setparity ()
 155 T}      Thread safety   MT-Safe
 156 .TE
 157 .hy
 158 .ad
 159 .sp 1
 160 .SH CONFORMING TO
 161 4.3BSD.
 162 Not in POSIX.1.
 163 .SH SEE ALSO
 164 .BR des (1),
 165 .BR crypt (3),
 166 .BR xcrypt (3)