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