Content-type: text/html Manpage of TclDES

TclDES

Section: Tcl DES/3DES Library (n)
Updated: OCTOBER 2004
Index Return to Main Contents
 

NAME

TclDES - Tcl-based Data Encryption Standard library  

SYNOPSIS

package require tclDES ?0.8?

::des::createKeys key

::des::keyset oper value

::des::block keyset message encrypt [mode [iv]]

::des::stream keyset message encrypt mode iv [kbits]]

::des::encrypt keyset plaintext [mode [iv [kbits]]]

::des::decrypt keyset ciphertext [mode [iv [kbits]]]

 

DESCRIPTION

TclDES is a pure-Tcl implementation of the NIST Data Encryption Standard (DES). The package can perform encryption and decryption using either the standard DES algorithm or the triple-DES (3DES) algorithm. All four DES modes are supported: Electronic Code Block (ECB), Cipher Block Chaining (CBC), Cipher Feedback (CFB), and Output Feedback (OFB).

This source code is being made publicly available and has been registered with the U.S. Dept. of Commerce Bureau of Industry and Security under export license exception TSU (Technology and Software Unrestricted) for export out of the United States. TclDES is licensed under the same Open Source license as Tcl (BSD). Details can be found in the TclDES source code.

The TclDES commands are contained within the namespace ::des so that working variables shared between the commands are isolated from the global namespace.  

COMMANDS

::des::createKeys key
The ::des::createKeys command generates the 16 or 48 subkeys used by the DES and 3DES algorithms, respectively. The input key must be a binary string of 8 bytes in length if 16 subkeys are to be created. The binary string must be 24 bytes in length if 48 subkeys are to be created. The output is a list of subkeys either 16 or 24 elements in length. An error is generated if any of the keys submitted are one of four DES weak keys. This command is used internally by the ::des::keyset command.
::des::keyset oper value
The ::des::keyset command creates or destroys a keyset created from a 64-bit DES key or a 192-bit 3DES key. The input oper is the operation to be performed. This will be either "create" (make a new keyset) or "destroy" (delete an existing keyset). An error is generated if oper is not "create" or "destroy". The meaning of the argument value depends of the operation performed. If the argument oper is "create", then value is the 64-bit (8 bytes) DES key or the 192-bit (24 bytes) 3DES key. (Note: The lsb of each byte is ignored; odd parity is not required). The ::des::createKeys command is called to generate the keyset. If the argument oper is "destroy", then value is a handle to a keyset that was created previously. If the argument oper is "create", then the output is a handle to the keyset stored in the des namespace. If the argument oper is "destroy", then nothing is returned.
::des::block keyset message encrypt [mode [iv]]
The ::des::block command executes the DES/3DES algorithm for the block mode algorithms ECB and CBC. The input keyset must be a valid handle to a DES key set created through the ::des::keyset procedure. Depending upon the nature of the key set, either the standard DES or the 3DES algorithm will be executed. Message is a binary string that will either be encrypted or decrypted depending on the value of the encrypt flag. If encryption is being performed, the length of message is extended to an integral multiple of eight bytes. If decryption is being performed, the length of message must be an integral multiple of eight bytes. Encryption occurs if the encrypt flag in 1 (the default) and decryption occurs if the flag is 0. The mode flag determines the DES operation mode. The modes available are: 0 - Electronic Code Block (ECB, the default), 1 - Cipher Block Chaining (CBC). If the mode selected is CBC, the name of a variable, iv, containing a binary initialization vector string must be supplied. The binary string must be 8 bytes in length. The output is a binary string of the encrypted or decrypted form of message. The length of the output string is always an integral multiple of eight. The variable, iv, contains the feed-forward cipher block for the last cycle of the algorithm.
::des::stream keyset message encrypt mode iv [kbits]
The ::des::stream command executes the DES/3DES algorithm for the stream mode algorithms CFB and OFB. The input keyset must be a valid handle to a DES key set created through the ::des::keyset procedure. Depending upon the nature of the key set, either the standard DES or the 3DES algorithm will be executed. Message is a binary string that will either be encrypted or decrypted depending on the value of the encrypt flag. Encryption occurs if the encrypt flag in 1 (the default) and decryption occurs if the flag is 0. The mode flag determines the DES operation mode. The modes available are: 0 - Output Feedback and 1 - Cipher Feedback. iv is the name of a variable containing an initialization vector string used to initialize the algorithm. The binary string must be 8 bytes in length. The kbits parameter states the number of bits per data unit processed by the algorithm.(the default is 64). The output is a binary string of the encrypted or decrypted form of message. The length of the output string will be equal to the length of the input string. The variable, iv, contains the feedback block for the last cycle of the algorithm. Note: A copy of the initial value of the initialization vector used for encryption must be retained in order to decrypt the message later. Subsequent calls with new message fragments should use the same initialization vector variable used in the first call.
::des::encrypt keyset plaintext [mode [iv [kbits]]]
The ::des::encrypt command is an encryption-only wrapper for the ::des::block and ::des::stream commands. The inputs keyset, iv, and kbits, are defined as described in the ::des::block and ::des::stream commands. The input plaintext is a binary string to be encrypted. The value of mode can be ecb (the default), cbc, ofb, and cfb. The output is a binary string of the encrypted form of plaintext.
::des::decrypt keyset ciphertext [mode [iv [kbits]]]
The ::des::decrypt command is a decryption-only wrapper for the ::des::block and ::des::stream commands. The inputs keyset, iv, and kbits, are defined as described in the ::des::block and ::des::stream commands. The input ciphertext is a binary string to be decrypted. The value of mode can be ecb (the default), cbc, ofb, and cfb. The output is a binary string of the decrypted form of ciphertext.
Stream Mode Message Size Restriction
Due to the nature of the OFB and CFB modes of DES/3DES, the message/cipher data is considered to be a stream of bits, not blocks of bytes. Since data is normally packed into 8-bit bytes, message fragments processed by ::des::stream must be an integral number of bytes. The value of kbits forces a message fragment to also satisfy the requirement that its length be an integral multiple of kbits in length. The table below lists the minimum length of a message for a given size of kbits:

kbits size message size kbits size message size
   1 bit       1 byte       33 bits    165 bytes
   2 bits      1 byte       34 bits    170 bytes
   3 bits      3 bytes      35 bits    175 bytes
   4 bits      1 byte       36 bits    180 bytes
   5 bits      5 bytes      37 bits    185 bytes
   6 bits      6 bytes      38 bits    190 bytes
   7 bits      7 bytes      39 bits    195 bytes
   8 bits      1 byte       40 bits      5 bytes
   9 bits     18 bytes      41 bits    246 bytes
  10 bits     20 bytes      42 bits    252 bytes
  11 bits     22 bytes      43 bits    258 bytes
  12 bits     24 bytes      44 bits    264 bytes
  13 bits     26 bytes      45 bits    270 bytes
  14 bits     28 bytes      46 bits    276 bytes
  15 bits     30 bytes      47 bits    282 bytes
  16 bits      2 bytes      48 bits      6 bytes
  17 bits     51 bytes      49 bits    343 bytes
  18 bits     54 bytes      50 bits    350 bytes
  19 bits     57 bytes      51 bits    357 bytes
  20 bits     60 bytes      52 bits    364 bytes
  21 bits     63 bytes      53 bits    371 bytes
  22 bits     66 bytes      54 bits    378 bytes
  23 bits     69 bytes      55 bits    385 bytes
  24 bits      3 bytes      56 bits      7 bytes
  25 bits    100 bytes      57 bits    456 bytes
  26 bits    104 bytes      58 bits    464 bytes
  27 bits    108 bytes      59 bits    472 bytes
  28 bits    112 bytes      60 bits    480 bytes
  29 bits    116 bytes      61 bits    488 bytes
  30 bits    120 bytes      62 bits    496 bytes
  31 bits    124 bytes      63 bits    504 bytes
  32 bits      4 bytes      64 bits      8 bytes

Note that the actual message length can be an integral multiple of the corresponding message lengths stated above.

 

AUTHOR

Mac A. Cody <maccody at comcast dot net>

 

SEE ALSO

binary(n)

 

KEYWORDS

DES, 3DES, Tcl, package
 

Index

NAME
SYNOPSIS
DESCRIPTION
COMMANDS
AUTHOR
SEE ALSO
KEYWORDS
This document was created by man2html, using the manual pages.
Time: 03:03:45 GMT, October 26, 2004