1sha256(n)               SHA-x Message-Digest Algorithm               sha256(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       sha256 - SHA256 Message-Digest Algorithm
9

SYNOPSIS

11       package require Tcl  8.2
12
13       package require sha256  ?1.0.3?
14
15       ::sha2::sha256  ?-hex|-bin?  [ -channel channel | -file filename | ?--?
16       string ]
17
18       ::sha2::sha224 ?-hex|-bin? [ -channel channel | -file filename  |  ?--?
19       string ]
20
21       ::sha2::hmac key string
22
23       ::sha2::hmac ?-hex|-bin? -key key [ -channel channel | -file filename |
24       ?--? string ]
25
26       ::sha2::SHA256Init
27
28       ::sha2::SHA224Init
29
30       ::sha2::SHA256Update token data
31
32       ::sha2::SHA256Final token
33
34       ::sha2::SHA224Final token
35
36       ::sha2::HMACInit key
37
38       ::sha2::HMACUpdate token data
39
40       ::sha2::HMACFinal token
41
42______________________________________________________________________________
43

DESCRIPTION

45       This package provides an implementation in Tcl of the SHA256 and SHA224
46       message-digest  algorithms  as  specified  by FIPS PUB 180-1 (1). These
47       algorithms take a message and generates a 256-bit (224-bit) digest from
48       the input. The SHA2 algorithms are related to the SHA1 algorithm.
49
50       This  package  also includes support for creating keyed message-digests
51       using the HMAC algorithm from RFC 2104 (3) with SHA256 as the  message-
52       digest.
53

COMMANDS

55       ::sha2::sha256  ?-hex|-bin?  [ -channel channel | -file filename | ?--?
56       string ]
57              The command takes a message and returns  the  SHA256  digest  of
58              this message as a hexadecimal string. You may request the result
59              as binary data by giving -bin.
60
61              The data to be hashed can be specified either as a string  argu‐
62              ment  to  the  sha256  command, or as a filename or a pre-opened
63              channel. If the -filename argument is given  then  the  file  is
64              opened,  the data read and hashed and the file is closed. If the
65              -channel argument is given then data is read  from  the  channel
66              until  the  end  of file. The channel is not closed. NOTE use of
67              the channel or filename options results in the internal  use  of
68              vwait.  To  avoid  nested event loops in Tk or tclhttpd applica‐
69              tions you  should  use  the  incremental  programming  API  (see
70              below).
71
72              Only one of -file, -channel or string should be given.
73
74              If  the  string  to  hash can be mistaken for an option (leading
75              dash "-"), use the option -- before it to terminate option  pro‐
76              cessing and force interpretation as a string.
77
78       ::sha2::sha224  ?-hex|-bin?  [ -channel channel | -file filename | ?--?
79       string ]
80              Like ::sha2::sha256, except that the SHA224 digest is returned.
81
82       ::sha2::hmac key string
83
84       ::sha2::hmac ?-hex|-bin? -key key [ -channel channel | -file filename |
85       ?--? string ]
86              Calculate  an  Hashed Message Authentication digest (HMAC) using
87              the SHA256 digest algorithm. HMACs are described in RFC 2104 (3)
88              and  provide  an  SHA256 digest that includes a key. All options
89              other than -key are as for the ::sha2::sha256 command.
90
91              If the string to hash can be mistaken  for  an  option  (leading
92              dash  "-"), use the option -- before it to terminate option pro‐
93              cessing and force interpretation as a string.
94

PROGRAMMING INTERFACE

96       For the programmer, the SHA256 hash can be  viewed  as  a  bucket  into
97       which  one pours data. When you have finished, you extract a value that
98       is derived from the data that was poured into the bucket. The  program‐
99       ming  interface  to  the SHA256 hash operates on a token (equivalent to
100       the bucket). You call SHA256Init  to  obtain  a  token  and  then  call
101       SHA256Update  as  many  times  as  required to add data to the hash. To
102       release any  resources  and  obtain  the  hash  value,  you  then  call
103       SHA256Final.  An  equivalent  set of functions gives you a keyed digest
104       (HMAC).
105
106       If you have critcl and have built the tcllibc package then  the  imple‐
107       mentation  of  the hashing function will be performed by compiled code.
108       Failing that there is a pure-tcl equivalent. The programming  interface
109       remains the same in all cases.
110
111       ::sha2::SHA256Init
112
113       ::sha2::SHA224Init
114              Begins a new SHA256/SHA224 hash. Returns a token ID that must be
115              used for the remaining functions.
116
117       ::sha2::SHA256Update token data
118              Add data to the hash identified by token.  Calling  SHA256Update
119              $token  "abcd" is equivalent to calling SHA256Update $token "ab"
120              followed by SHA256Update $token "cb". See EXAMPLES.   Note  that
121              this  command  is used for both SHA256 and SHA224. Only the ini‐
122              tialization and finalization commands of both hashes differ.
123
124       ::sha2::SHA256Final token
125
126       ::sha2::SHA224Final token
127              Returns the hash value and releases any resources held  by  this
128              token.  Once  this  command completes the token will be invalid.
129              The result is a binary string of 32/28  bytes  representing  the
130              256/224 bit SHA256 / SHA224 digest value.
131
132       ::sha2::HMACInit key
133              This is equivalent to the ::sha2::SHA256Init command except that
134              it requires the key that will be included in the HMAC.
135
136       ::sha2::HMACUpdate token data
137
138       ::sha2::HMACFinal token
139              These commands are identical to the SHA256 equivalent commands.
140

EXAMPLES

142              % sha2::sha256 "Tcl does SHA256"
143              0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789
144
145
146
147              % sha2::hmac Sekret "Tcl does SHA256"
148              4f9352c64d655e8a36abe73e6163a9d7a54039877c1c92ec90b07d48d4e854e0
149
150
151
152              % set tok [sha2::SHA256Init]
153              ::sha2::1
154              % sha2::SHA256Update $tok "Tcl "
155              % sha2::SHA256Update $tok "does "
156              % sha2::SHA256Update $tok "SHA256"
157              % sha2::Hex [sha2::SHA256Final $tok]
158              0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789
159
160

REFERENCES

162       [1]    "Secure Hash Standard",  National  Institute  of  Standards  and
163              Technology,   U.S.   Department   Of   Commerce,   April   1995.
164              (http://www.itl.nist.gov/fipspubs/fip180-1.htm)
165
166       [2]    Rivest, R., "The MD4 Message Digest Algorithm", RFC  1320,  MIT,
167              April 1992. (http://www.rfc-editor.org/rfc/rfc1320.txt)
168
169       [3]    Krawczyk,  H.,  Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing
170              for  Message   Authentication",   RFC   2104,   February   1997.
171              (http://www.rfc-editor.org/rfc/rfc2104.txt)
172

BUGS, IDEAS, FEEDBACK

174       This  document,  and the package it describes, will undoubtedly contain
175       bugs and other problems.  Please report such in the  category  sha1  of
176       the  Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please
177       also report any ideas for enhancements you may have for either  package
178       and/or documentation.
179
180       When proposing code changes, please provide unified diffs, i.e the out‐
181       put of diff -u.
182
183       Note further that  attachments  are  strongly  preferred  over  inlined
184       patches.  Attachments  can  be  made  by  going to the Edit form of the
185       ticket immediately after its creation, and  then  using  the  left-most
186       button in the secondary navigation bar.
187

SEE ALSO

189       md4, md5, ripemd128, ripemd160, sha1
190

KEYWORDS

192       FIPS 180-1, hashing, message-digest, rfc 2104, security, sha256
193

CATEGORY

195       Hashes, checksums, and encryption
196
198       Copyright (c) 2008, Andreas Kupries <andreas_kupries@users.sourceforge.net>
199
200
201
202
203tcllib                               1.0.3                           sha256(n)
Impressum