Ubuntu Manpage: des - Implementation of the DES and triple-DES ciphers

NAME

       des - Implementation of the DES and triple-DES ciphers

SYNOPSIS

       package require Tcl  8.2

       package require des  1.1

       ::DES::des  ?-mode  [ecb|cbc|cfb|ofb]?  ?-dir [encrypt|decrypt]? -key keydata ?-iv vector?
       ?-hex? ?-weak? ?-out channel? ?-chunksize size? [ -in channel | data ]

       ::DES::Init mode keydata iv ?weak?

       ::DES::Encrypt Key data

       ::DES::Decrypt Key data

       ::DES::Reset Key iv

       ::DES::Final Key

_________________________________________________________________________________________________

DESCRIPTION

       This is an implementation in Tcl of the Data Encryption Standard (DES) as published by the
       U.S.  National  Institute of Standards and Technology (NIST) [1]. This implementation also
       supports triple DES (3DES) extension to DES. DES is a 64-bit  block  cipher  that  uses  a
       56-bit key. 3DES uses a 168-bit key. DES has now officially been superceeded by AES but is
       in common use in many protocols.

       The tcllib implementation of DES and 3DES uses  an  implementation  by  Mac  Cody  and  is
       available  as  a  separate  download  from  [2]. For anyone concerned about the details of
       exporting this code please see the TclDES web pages. The tcllib specific code is a wrapper
       to  the  TclDES  API that presents same API for the DES cipher as for other ciphers in the
       library.

COMMANDS

       ::DES::des ?-mode [ecb|cbc|cfb|ofb]? ?-dir [encrypt|decrypt]? -key  keydata  ?-iv  vector?
       ?-hex? ?-weak? ?-out channel? ?-chunksize size? [ -in channel | data ]
              Perform  the  DES  algorithm  on either the data provided by the argument or on the
              data read from the -in channel. If an -out channel is given then the result will be
              written to this channel.

              The  -key  option must be given. This parameter takes a binary string of 8 bytes in
              length and is used to generate the key schedule.  In DES only 56 bits of  key  data
              are used. The highest bit from each byte is discarded.

              The  -mode  and  -dir  options  are  optional  and  default to cbc mode and encrypt
              respectively. The initialization vector -iv takes an 8 byte binary  argument.  This
              defaults  to  all zeros. See MODES OF OPERATION for more about -mode and the use of
              the initialization vector.

              DES is a 64-bit block cipher. This means that the data must be  provided  in  units
              that are a multiple of 8 bytes.

PROGRAMMING INTERFACE

       Internal  state  is  maintained  in  an  opaque  structure  that is returned from the Init
       function. In ECB mode the state is not affected by the input  but  for  other  modes  some
       input  dependent state is maintained and may be reset by calling the Reset function with a
       new initialization vector value.

       ::DES::Init mode keydata iv ?weak?
              Construct a new DES key schedule  using  the  specified  key  data  and  the  given
              initialization  vector.  The initialization vector is not used with ECB mode but is
              important for other usage modes.  See MODES OF OPERATION.

              There are a small number of keys that are known to be weak when used with  DES.  By
              default if such a key is passed in then an error will be raised. If there is a need
              to accept such keys then the weak parameter can be set  true  to  avoid  the  error
              being thrown.

       ::DES::Encrypt Key data
              Use  a prepared key acquired by calling Init to encrypt the provided data. The data
              argument should be a binary array that is a multiple of the DES  block  size  of  8
              bytes. The result is a binary array the same size as the input of encrypted data.

       ::DES::Decrypt Key data
              Decipher  data  using  the  key.  Note that the same key may be used to encrypt and
              decrypt data provided that the initialization vector is reset appropriately for CBC
              mode.

       ::DES::Reset Key iv
              Reset  the  initialization  vector. This permits the programmer to re-use a key and
              avoid the cost of re-generating the key schedule where the same key data  is  being
              used multiple times.

       ::DES::Final Key
              This  should  be  called  to  clean  up  resources  associated with Key.  Once this
              function has been called the key may not be used again.

MODES OF OPERATION

Electronic Code Book (ECB)
ECB is the basic mode of all block ciphers. Each block is encrypted independently
and so identical plain text will produce identical output when encrypted with the
same key. Any encryption errors will only affect a single block however this is
vulnerable to known plaintext attacks.

Cipher Block Chaining (CBC)
CBC mode uses the output of the last block encryption to affect the current block.
An initialization vector of the same size as the cipher block size is used to
handle the first block. The initialization vector should be chosen randomly and
transmitted as the first block of the output. Errors in encryption affect the
current block and the next block after which the cipher will correct itself. CBC is
the most commonly used mode in software encryption.

Cipher Feedback (CFB)
CFB mode can be used to convert block ciphers into stream ciphers. In CFB mode the
initialization vector is encrypted and the output is then xor'd with the plaintext
stream. The result is then used as the initialization vector for the next round.
Errors will affect the current block and the next block.

Output Feedback (OFB)
OFB is similar to CFB except that the output of the cipher is fed back into the
next round and not the xor'd plain text. This means that errors only affect a
single block but the cipher is more vulnerable to attack.

EXAMPLES

              % set ciphertext [DES::des -mode cbc -dir encrypt -key $secret $plaintext]
              % set plaintext [DES::des -mode cbc -dir decrypt -key $secret $ciphertext]

              set iv [string repeat \\0 8]
              set Key [DES::Init cbc \\0\\1\\2\\3\\4\\5\\6\\7 $iv]
              set ciphertext [DES::Encrypt $Key "somedata"]
              append ciphertext [DES::Encrypt $Key "moredata"]
              DES::Reset $Key $iv
              set plaintext [DES::Decrypt $Key $ciphertext]
              DES::Final $Key

REFERENCES

       [1]    "Data  Encryption  Standard",  Federal Information Processing Standards Publication
              46-3, 1999, (http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf)

       [2]    "TclDES: munitions-grade Tcl scripting" http://tcldes.sourceforge.net/

AUTHORS

       Jochen C Loewer, Mac Cody, Pat Thoyts

BUGS, IDEAS, FEEDBACK

       This document, and the package it describes,  will  undoubtedly  contain  bugs  and  other
       problems.    Please   report   such   in   the   category   des  of  the  Tcllib  Trackers
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note further that attachments are strongly preferred over inlined patches. Attachments can
       be made by going to the Edit form of the ticket immediately after its creation,  and  then
       using the left-most button in the secondary navigation bar.

KEYWORDS

       3DES, DES, block cipher, data integrity, encryption, security

COPYRIGHT

       Copyright (c) 2005, Pat Thoyts <patthoyts@users.sourceforge.net>