[//000000001]: # (sha256 \- SHA\-x Message\-Digest Algorithm) [//000000002]: # (Generated from file 'sha256\.man' by tcllib/doctools with format 'markdown') [//000000003]: # (Copyright © 2008, Andreas Kupries ) [//000000004]: # (sha256\(n\) 1\.0\.4 tcllib "SHA\-x Message\-Digest Algorithm")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
# NAME sha256 \- SHA256 Message\-Digest Algorithm # Table Of Contents - [Table Of Contents](#toc) - [Synopsis](#synopsis) - [Description](#section1) - [COMMANDS](#section2) - [PROGRAMMING INTERFACE](#section3) - [EXAMPLES](#section4) - [REFERENCES](#section5) - [Bugs, Ideas, Feedback](#section6) - [See Also](#seealso) - [Keywords](#keywords) - [Category](#category) - [Copyright](#copyright) # SYNOPSIS package require Tcl 8\.2 package require sha256 ?1\.0\.4? [__::sha2::sha256__ ?__\-hex|\-bin__? \[ __\-channel channel__ | __\-file filename__ | ?__\-\-__? *string* \]](#1) [__::sha2::sha224__ ?__\-hex|\-bin__? \[ __\-channel channel__ | __\-file filename__ | ?__\-\-__? *string* \]](#2) [__::sha2::hmac__ *key* *string*](#3) [__::sha2::hmac__ ?__\-hex|\-bin__? __\-key key__ \[ __\-channel channel__ | __\-file filename__ | ?__\-\-__? *string* \]](#4) [__::sha2::SHA256Init__](#5) [__::sha2::SHA224Init__](#6) [__::sha2::SHA256Update__ *token* *data*](#7) [__::sha2::SHA256Final__ *token*](#8) [__::sha2::SHA224Final__ *token*](#9) [__::sha2::HMACInit__ *key*](#10) [__::sha2::HMACUpdate__ *token* *data*](#11) [__::sha2::HMACFinal__ *token*](#12) # DESCRIPTION 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\. This package also includes support for creating keyed message\-digests using the HMAC algorithm from RFC 2104 \(3\) with SHA256 as the message\-digest\. # COMMANDS - __::sha2::sha256__ ?__\-hex|\-bin__? \[ __\-channel channel__ | __\-file filename__ | ?__\-\-__? *string* \] 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 *\-bin*\. The data to be hashed can be specified either as a string argument to the __sha256__ command, or as a filename or a pre\-opened channel\. If the *\-filename* argument is given then the file is opened, the data read and hashed and the file is closed\. If the *\-channel* argument is given then data is read from the channel until the end of file\. The channel is not closed\. *NOTE* use of the channel or filename options results in the internal use of __[vwait](\.\./\.\./\.\./\.\./index\.md\#vwait)__\. To avoid nested event loops in Tk or tclhttpd applications you should use the incremental programming API \(see below\)\. Only one of *\-file*, *\-channel* or *string* should be given\. If the *string* to hash can be mistaken for an option \(leading dash "\-"\), use the option __\-\-__ before it to terminate option processing and force interpretation as a string\. - __::sha2::sha224__ ?__\-hex|\-bin__? \[ __\-channel channel__ | __\-file filename__ | ?__\-\-__? *string* \] Like __::sha2::sha256__, except that the SHA224 digest is returned\. - __::sha2::hmac__ *key* *string* - __::sha2::hmac__ ?__\-hex|\-bin__? __\-key key__ \[ __\-channel channel__ | __\-file filename__ | ?__\-\-__? *string* \] 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 *\-key* are as for the __::sha2::sha256__ command\. If the *string* to hash can be mistaken for an option \(leading dash "\-"\), use the option __\-\-__ before it to terminate option processing and force interpretation as a string\. # 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 __SHA256Init__ to obtain a token and then call __SHA256Update__ as many times as required to add data to the hash\. To release any resources and obtain the hash value, you then call __SHA256Final__\. An equivalent set of functions gives you a keyed digest \(HMAC\)\. If you have __critcl__ and have built the __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\. - __::sha2::SHA256Init__ - __::sha2::SHA224Init__ Begins a new SHA256/SHA224 hash\. Returns a token ID that must be used for the remaining functions\. - __::sha2::SHA256Update__ *token* *data* Add data to the hash identified by token\. Calling *SHA256Update $token "abcd"* is equivalent to calling *SHA256Update $token "ab"* followed by *SHA256Update $token "cb"*\. See [EXAMPLES](#section4)\. Note that this command is used for both SHA256 and SHA224\. Only the initialization and finalization commands of both hashes differ\. - __::sha2::SHA256Final__ *token* - __::sha2::SHA224Final__ *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\. - __::sha2::HMACInit__ *key* This is equivalent to the __::sha2::SHA256Init__ command except that it requires the key that will be included in the HMAC\. - __::sha2::HMACUpdate__ *token* *data* - __::sha2::HMACFinal__ *token* These commands are identical to the SHA256 equivalent commands\. # EXAMPLES % sha2::sha256 "Tcl does SHA256" 0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789 % sha2::hmac Sekret "Tcl does SHA256" 4f9352c64d655e8a36abe73e6163a9d7a54039877c1c92ec90b07d48d4e854e0 % set tok [sha2::SHA256Init] ::sha2::1 % sha2::SHA256Update $tok "Tcl " % sha2::SHA256Update $tok "does " % sha2::SHA256Update $tok "SHA256" % sha2::Hex [sha2::SHA256Final $tok] 0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789 # REFERENCES 1. "Secure Hash Standard", National Institute of Standards and Technology, U\.S\. Department Of Commerce, April 1995\. \([http://www\.itl\.nist\.gov/fipspubs/fip180\-1\.htm](http://www\.itl\.nist\.gov/fipspubs/fip180\-1\.htm)\) 1. Rivest, R\., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992\. \([http://www\.rfc\-editor\.org/rfc/rfc1320\.txt](http://www\.rfc\-editor\.org/rfc/rfc1320\.txt)\) 1. Krawczyk, H\., Bellare, M\. and Canetti, R\. "HMAC: Keyed\-Hashing for Message Authentication", RFC 2104, February 1997\. \([http://www\.rfc\-editor\.org/rfc/rfc2104\.txt](http://www\.rfc\-editor\.org/rfc/rfc2104\.txt)\) # Bugs, Ideas, Feedback This document, and the package it describes, will undoubtedly contain bugs and other problems\. Please report such in the category *sha1* of the [Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas for enhancements you may have for either package and/or documentation\. When proposing code changes, please provide *unified diffs*, i\.e the output of __diff \-u__\. Note further that *attachments* are strongly preferred over inlined patches\. Attachments can be made by going to the __Edit__ form of the ticket immediately after its creation, and then using the left\-most button in the secondary navigation bar\. # SEE ALSO [md4](\.\./md4/md4\.md), [md5](\.\./md5/md5\.md), [ripemd128](\.\./ripemd/ripemd128\.md), [ripemd160](\.\./ripemd/ripemd160\.md), [sha1](sha1\.md) # KEYWORDS [FIPS 180\-1](\.\./\.\./\.\./\.\./index\.md\#fips\_180\_1), [hashing](\.\./\.\./\.\./\.\./index\.md\#hashing), [message\-digest](\.\./\.\./\.\./\.\./index\.md\#message\_digest), [rfc 2104](\.\./\.\./\.\./\.\./index\.md\#rfc\_2104), [security](\.\./\.\./\.\./\.\./index\.md\#security), [sha256](\.\./\.\./\.\./\.\./index\.md\#sha256) # CATEGORY Hashes, checksums, and encryption # COPYRIGHT Copyright © 2008, Andreas Kupries