1aes(n)                Advanced Encryption Standard (AES)                aes(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       aes - Implementation of the AES block cipher
9

SYNOPSIS

11       package require Tcl  8.5
12
13       package require aes  ?1.2.1?
14
15       ::aes::aes ?-mode [ecb|cbc]? ?-dir [encrypt|decrypt]? -key keydata ?-iv
16       vector? ?-hex? ?-out channel? ?-chunksize size? [ -in  channel  |  ?--?
17       data ]
18
19       ::aes::Init mode keydata iv
20
21       ::aes::Encrypt Key data
22
23       ::aes::Decrypt Key data
24
25       ::aes::Reset Key iv
26
27       ::aes::Final Key
28
29______________________________________________________________________________
30

DESCRIPTION

32       This  is  an  implementation in Tcl of the Advanced Encryption Standard
33       (AES) as published by the U.S.  National  Institute  of  Standards  and
34       Technology  [1]. AES is a 128-bit block cipher with a variable key size
35       of 128, 192 or 256 bits.  This  implementation  supports  ECB  and  CBC
36       modes.
37

COMMANDS

39       ::aes::aes ?-mode [ecb|cbc]? ?-dir [encrypt|decrypt]? -key keydata ?-iv
40       vector? ?-hex? ?-out channel? ?-chunksize size? [ -in  channel  |  ?--?
41       data ]
42              Perform the aes algorithm on either the data provided by the ar‐
43              gument or on the data read from the  -in  channel.  If  an  -out
44              channel  is  given then the result will be written to this chan‐
45              nel.
46
47              The -key option must be given. This  parameter  takes  a  binary
48              string  of  either  16,  24 or 32 bytes in length and is used to
49              generate the key schedule.
50
51              The -mode and -dir options are optional and default to cbc  mode
52              and  encrypt respectively. The initialization vector -iv takes a
53              16 byte binary argument which defaults to all zeros.  See  MODES
54              OF OPERATION for more about available modes and their uses.
55
56              AES  is a 128-bit block cipher. This means that the data must be
57              provided in units that are a multiple of 16 bytes.
58

PROGRAMMING INTERFACE

60       Internal state is maintained in an opaque structure  that  is  returned
61       from  the  Init  function. In ECB mode the state is not affected by the
62       input but for CBC mode some input dependent state is maintained and may
63       be reset by calling the Reset function with a new initialization vector
64       value.
65
66       ::aes::Init mode keydata iv
67              Construct a new AES key schedule using the  specified  key  data
68              and  the  given initialization vector. The initialization vector
69              is not used with ECB mode but is important for  CBC  mode.   See
70              MODES OF OPERATION for details about cipher modes.
71
72       ::aes::Encrypt Key data
73              Use  a prepared key acquired by calling Init to encrypt the pro‐
74              vided data. The data argument should be a binary array that is a
75              multiple  of the AES block size of 16 bytes. The result is a bi‐
76              nary array the same size as the input of encrypted data.
77
78       ::aes::Decrypt Key data
79              Decipher data using the key. Note that the same key may be  used
80              to  encrypt  and  decrypt  data provided that the initialization
81              vector is reset appropriately for CBC mode.
82
83       ::aes::Reset Key iv
84              Reset the initialization vector. This permits the programmer  to
85              re-use  a key and avoid the cost of re-generating the key sched‐
86              ule where the same key data is being used multiple times.
87
88       ::aes::Final Key
89              This should be called to clean up resources associated with Key.
90              Once  this  function  has  been  called  the key may not be used
91              again.
92

MODES OF OPERATION

94       Electronic Code Book (ECB)
95              ECB is the basic mode of all block ciphers. Each  block  is  en‐
96              crypted  independently  and so identical plain text will produce
97              identical output when encrypted with the same key.  Any  encryp‐
98              tion errors will only affect a single block however this is vul‐
99              nerable to known plaintext attacks.
100
101       Cipher Block Chaining (CBC)
102              CBC mode uses the output of the last block encryption to  affect
103              the  current block. An initialization vector of the same size as
104              the cipher block size is used to handle  the  first  block.  The
105              initialization  vector should be chosen randomly and transmitted
106              as the first block of the output. Errors  in  encryption  affect
107              the current block and the next block after which the cipher will
108              correct itself. CBC is the most commonly used mode  in  software
109              encryption.  This is the default mode of operation for this mod‐
110              ule.
111

EXAMPLES

113              % set nil_block [string repeat \\0 16]
114              % aes::aes -hex -mode cbc -dir encrypt -key $nil_block $nil_block
115              66e94bd4ef8a2c3b884cfa59ca342b2e
116
117
118
119              set Key [aes::Init cbc $sixteen_bytes_key_data $sixteen_byte_iv]
120              append ciphertext [aes::Encrypt $Key $plaintext]
121              append ciphertext [aes::Encrypt $Key $additional_plaintext]
122              aes::Final $Key
123
124

REFERENCES

126       [1]    "Advanced Encryption Standard", Federal  Information  Processing
127              Standards  Publication  197, 2001 (http://csrc.nist.gov/publica
128              tions/fips/fips197/fips-197.pdf)
129

AUTHORS

131       Thorsten Schloermann, Pat Thoyts
132

BUGS, IDEAS, FEEDBACK

134       This document, and the package it describes, will  undoubtedly  contain
135       bugs and other problems.  Please report such in the category aes of the
136       Tcllib Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please  also
137       report  any  ideas  for  enhancements  you  may have for either package
138       and/or documentation.
139
140       When proposing code changes, please provide unified diffs, i.e the out‐
141       put of diff -u.
142
143       Note  further  that  attachments  are  strongly  preferred over inlined
144       patches. Attachments can be made by going  to  the  Edit  form  of  the
145       ticket  immediately  after  its  creation, and then using the left-most
146       button in the secondary navigation bar.
147

SEE ALSO

149       blowfish(n), des(n), md5(n), sha1(n)
150

KEYWORDS

152       aes, block cipher, data integrity, encryption, security
153

CATEGORY

155       Hashes, checksums, and encryption
156
158       Copyright (c) 2005, Pat Thoyts <patthoyts@users.sourceforge.net>
159       Copyright (c) 2012-2014, Andreas Kupries <andreas_kupries@users.sourceforge.net>
160
161
162
163
164tcllib                               1.2.1                              aes(n)
Impressum