1[manpage_begin sha256 n 1.0.3]
2[moddesc   {SHA-x Message-Digest Algorithm}]
3[copyright {2008, Andreas Kupries <andreas_kupries@users.sourceforge.net>}]
4[titledesc {SHA256 Message-Digest Algorithm}]
5[category  {Hashes, checksums, and encryption}]
6[require Tcl 8.2]
7[require sha256 [opt 1.0.3]]
8[description]
9[para]
10
11This package provides an implementation in Tcl of the SHA256 and
12SHA224 message-digest algorithms as specified by FIPS PUB 180-1
13(1). These algorithms take a message and generates a 256-bit (224-bit)
14digest from the input. The SHA2 algorithms are related to the SHA1
15algorithm.
16
17[para]
18
19This package also includes support for creating keyed message-digests
20using the HMAC algorithm from RFC 2104 (3) with SHA256 as the
21message-digest.
22
23[section {COMMANDS}]
24
25[list_begin definitions]
26
27[call [cmd ::sha2::sha256] \
28        [opt "[arg -hex|-bin]"] \
29        [lb] [arg "-channel channel"] | \
30        [arg "-file filename"] | [arg "string"] [rb]]
31
32The command takes a message and returns the SHA256 digest of this
33message as a hexadecimal string. You may request the result as binary
34data by giving [arg "-bin"].
35
36[para]
37
38The data to be hashed can be specified either as a string argument to
39the [cmd "sha256"] command, or as a filename or a pre-opened channel. If the 
40[arg "-filename"] argument is given then the file is opened, the data read
41and hashed and the file is closed. If the [arg "-channel"] argument is
42given then data is read from the channel until the end of file. The
43channel is not closed. [emph NOTE] use of the channel or filename
44options results in the internal use of [cmd vwait]. To avoid nested
45event loops in Tk or tclhttpd applications you should use the
46incremental programming API (see below).
47
48[para]
49
50Only one of [arg "-file"], [arg "-channel"] or [arg "string"] should be given.
51
52[call [cmd ::sha2::sha224] \
53        [opt "[arg -hex|-bin]"] \
54        [lb] [arg "-channel channel"] | \
55        [arg "-file filename"] | [arg "string"] [rb]]
56
57Like [cmd ::sha2::sha256], except that the SHA224 digest is returned.
58
59
60[call [cmd "::sha2::hmac"] [arg "key"] [arg "string"]]
61[call [cmd "::sha2::hmac"] \
62        [opt "[arg -hex|-bin]"] \
63        [arg "-key key"] \
64        [lb] [arg "-channel channel"] | \
65        [arg "-file filename"] | [arg "string"] [rb]]
66
67Calculate an Hashed Message Authentication digest (HMAC) using the
68SHA256 digest algorithm. HMACs are described in RFC 2104 (3) and
69provide an SHA256 digest that includes a key. All options other than
70[arg -key] are as for the [cmd "::sha2::sha256"] command.
71
72[list_end]
73
74[section {PROGRAMMING INTERFACE}]
75
76For the programmer, the SHA256 hash can be viewed as a bucket into
77which one pours data. When you have finished, you extract a value that
78is derived from the data that was poured into the bucket. The
79programming interface to the SHA256 hash operates on a token
80(equivalent to the bucket). You call [cmd "SHA256Init"] to obtain a
81token and then call [cmd "SHA256Update"] as many times as required to
82add data to the hash. To release any resources and obtain the hash
83value, you then call [cmd "SHA256Final"]. An equivalent set of
84functions gives you a keyed digest (HMAC).
85
86[para]
87
88If you have [package critcl] and have built the [package tcllibc]
89package then the implementation of the hashing function will be
90performed by compiled code. Failing that there is a pure-tcl
91equivalent. The programming interface remains the same in all cases.
92
93[list_begin definitions]
94
95[call [cmd "::sha2::SHA256Init"]]
96[call [cmd "::sha2::SHA224Init"]]
97
98Begins a new SHA256/SHA224 hash. Returns a token ID that must be used
99for the remaining functions.
100
101[call [cmd "::sha2::SHA256Update"] [arg "token"] [arg "data"]]
102
103Add data to the hash identified by token. Calling 
104[emph {SHA256Update $token "abcd"}] is equivalent to calling
105[emph {SHA256Update $token "ab"}] followed by 
106[emph {SHA256Update $token "cb"}]. See [sectref {EXAMPLES}].
107
108Note that this command is used for both SHA256 and SHA224. Only the
109initialization and finalization commands of both hashes differ.
110
111[call [cmd "::sha2::SHA256Final"] [arg "token"]]
112[call [cmd "::sha2::SHA224Final"] [arg "token"]]
113
114Returns the hash value and releases any resources held by this
115token. Once this command completes the token will be invalid. The
116result is a binary string of 32/28 bytes representing the 256/224 bit
117SHA256 / SHA224 digest value.
118
119[call [cmd "::sha2::HMACInit"] [arg "key"]]
120
121This is equivalent to the [cmd "::sha2::SHA256Init"] command except
122that it requires the key that will be included in the HMAC.
123
124[call [cmd "::sha2::HMACUpdate"] [arg "token"] [arg "data"]]
125[call [cmd "::sha2::HMACFinal"] [arg "token"]]
126
127These commands are identical to the SHA256 equivalent commands.
128
129[list_end]
130
131[section {EXAMPLES}]
132
133[example {
134% sha2::sha256 "Tcl does SHA256"
1350b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789
136}]
137
138[example {
139% sha2::hmac Sekret "Tcl does SHA256"
1404f9352c64d655e8a36abe73e6163a9d7a54039877c1c92ec90b07d48d4e854e0
141}]
142
143[example {
144% set tok [sha2::SHA256Init]
145::sha2::1
146% sha2::SHA256Update $tok "Tcl "
147% sha2::SHA256Update $tok "does "
148% sha2::SHA256Update $tok "SHA256"
149% sha2::Hex [sha2::SHA256Final $tok]
1500b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789
151}]
152
153[section {REFERENCES}]
154
155[list_begin enumerated]
156
157[enum]
158        "Secure Hash Standard", National Institute of Standards
159        and Technology, U.S. Department Of Commerce, April 1995.
160	([uri http://www.itl.nist.gov/fipspubs/fip180-1.htm])
161
162[enum]
163       Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT,
164       April 1992. ([uri http://www.rfc-editor.org/rfc/rfc1320.txt])
165
166[enum]
167      Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for 
168      Message Authentication", RFC 2104, February 1997.
169	([uri http://www.rfc-editor.org/rfc/rfc2104.txt])
170
171[list_end]
172
173[see_also sha1 md4 md5 ripemd128 ripemd160]
174
175[section {BUGS, IDEAS, FEEDBACK}]
176
177This document, and the package it describes, will undoubtedly contain
178bugs and other problems.
179
180Please report such in the category [emph sha1] of the
181[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}].
182
183Please also report any ideas for enhancements you may have for either
184package and/or documentation.
185
186
187[keywords sha256 hashing security message-digest {FIPS 180-1} {rfc 2104}]
188[manpage_end]
189