[vset VERSION 1.0.4] [manpage_begin sha256 n [vset VERSION]] [see_also md4] [see_also md5] [see_also ripemd128] [see_also ripemd160] [see_also sha1] [keywords {FIPS 180-1}] [keywords hashing] [keywords message-digest] [keywords {rfc 2104}] [keywords security] [keywords sha256] [moddesc {SHA-x Message-Digest Algorithm}] [copyright {2008, Andreas Kupries }] [titledesc {SHA256 Message-Digest Algorithm}] [category {Hashes, checksums, and encryption}] [require Tcl 8.2] [require sha256 [opt [vset VERSION]]] [description] [para] This package provides an implementation in Tcl of the SHA256 and SHA224 message-digest algorithms as specified by FIPS PUB 180-1 (1). These algorithms take a message and generates a 256-bit (224-bit) digest from the input. The SHA2 algorithms are related to the SHA1 algorithm. [para] This package also includes support for creating keyed message-digests using the HMAC algorithm from RFC 2104 (3) with SHA256 as the message-digest. [section {COMMANDS}] [list_begin definitions] [call [cmd ::sha2::sha256] \ [opt "[option -hex|-bin]"] \ [lb] [option "-channel channel"] | \ [option "-file filename"] | [opt [option --]] [arg "string"] [rb]] The command takes a message and returns the SHA256 digest of this message as a hexadecimal string. You may request the result as binary data by giving [arg "-bin"]. [para] The data to be hashed can be specified either as a string argument to the [cmd "sha256"] command, or as a filename or a pre-opened channel. If the [arg "-filename"] argument is given then the file is opened, the data read and hashed and the file is closed. If the [arg "-channel"] argument is given then data is read from the channel until the end of file. The channel is not closed. [emph NOTE] use of the channel or filename options results in the internal use of [cmd vwait]. To avoid nested event loops in Tk or tclhttpd applications you should use the incremental programming API (see below). [para] Only one of [arg "-file"], [arg "-channel"] or [arg "string"] should be given. [para] If the [arg string] to hash can be mistaken for an option (leading dash "-"), use the option [option --] before it to terminate option processing and force interpretation as a string. [call [cmd ::sha2::sha224] \ [opt "[option -hex|-bin]"] \ [lb] [option "-channel channel"] | \ [option "-file filename"] | [opt [option --]] [arg "string"] [rb]] Like [cmd ::sha2::sha256], except that the SHA224 digest is returned. [call [cmd "::sha2::hmac"] [arg "key"] [arg "string"]] [call [cmd "::sha2::hmac"] \ [opt "[option -hex|-bin]"] \ [option "-key key"] \ [lb] [option "-channel channel"] | \ [option "-file filename"] | [opt [option --]] [arg "string"] [rb]] Calculate an Hashed Message Authentication digest (HMAC) using the SHA256 digest algorithm. HMACs are described in RFC 2104 (3) and provide an SHA256 digest that includes a key. All options other than [arg -key] are as for the [cmd "::sha2::sha256"] command. [para] If the [arg string] to hash can be mistaken for an option (leading dash "-"), use the option [option --] before it to terminate option processing and force interpretation as a string. [list_end] [section {PROGRAMMING INTERFACE}] For the programmer, the SHA256 hash can be viewed as a bucket into which one pours data. When you have finished, you extract a value that is derived from the data that was poured into the bucket. The programming interface to the SHA256 hash operates on a token (equivalent to the bucket). You call [cmd "SHA256Init"] to obtain a token and then call [cmd "SHA256Update"] as many times as required to add data to the hash. To release any resources and obtain the hash value, you then call [cmd "SHA256Final"]. An equivalent set of functions gives you a keyed digest (HMAC). [para] If you have [package critcl] and have built the [package tcllibc] package then the implementation of the hashing function will be performed by compiled code. Failing that there is a pure-tcl equivalent. The programming interface remains the same in all cases. [list_begin definitions] [call [cmd "::sha2::SHA256Init"]] [call [cmd "::sha2::SHA224Init"]] Begins a new SHA256/SHA224 hash. Returns a token ID that must be used for the remaining functions. [call [cmd "::sha2::SHA256Update"] [arg "token"] [arg "data"]] Add data to the hash identified by token. Calling [emph {SHA256Update $token "abcd"}] is equivalent to calling [emph {SHA256Update $token "ab"}] followed by [emph {SHA256Update $token "cb"}]. See [sectref {EXAMPLES}]. Note that this command is used for both SHA256 and SHA224. Only the initialization and finalization commands of both hashes differ. [call [cmd "::sha2::SHA256Final"] [arg "token"]] [call [cmd "::sha2::SHA224Final"] [arg "token"]] Returns the hash value and releases any resources held by this token. Once this command completes the token will be invalid. The result is a binary string of 32/28 bytes representing the 256/224 bit SHA256 / SHA224 digest value. [call [cmd "::sha2::HMACInit"] [arg "key"]] This is equivalent to the [cmd "::sha2::SHA256Init"] command except that it requires the key that will be included in the HMAC. [call [cmd "::sha2::HMACUpdate"] [arg "token"] [arg "data"]] [call [cmd "::sha2::HMACFinal"] [arg "token"]] These commands are identical to the SHA256 equivalent commands. [list_end] [section {EXAMPLES}] [example { % sha2::sha256 "Tcl does SHA256" 0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789 }] [example { % sha2::hmac Sekret "Tcl does SHA256" 4f9352c64d655e8a36abe73e6163a9d7a54039877c1c92ec90b07d48d4e854e0 }] [example { % set tok [sha2::SHA256Init] ::sha2::1 % sha2::SHA256Update $tok "Tcl " % sha2::SHA256Update $tok "does " % sha2::SHA256Update $tok "SHA256" % sha2::Hex [sha2::SHA256Final $tok] 0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789 }] [section {REFERENCES}] [list_begin enumerated] [enum] "Secure Hash Standard", National Institute of Standards and Technology, U.S. Department Of Commerce, April 1995. ([uri http://www.itl.nist.gov/fipspubs/fip180-1.htm]) [enum] Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992. ([uri http://www.rfc-editor.org/rfc/rfc1320.txt]) [enum] Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] [vset CATEGORY sha1] [include ../common-text/feedback.inc] [manpage_end]