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

NAME

8       sha1 - SHA1 Message-Digest Algorithm
9

SYNOPSIS

11       package require Tcl  8.2
12
13       package require sha1  ?2.0.4?
14
15       ::sha1::sha1  ?-hex|-bin?  [  -channel  channel | -file filename | ?--?
16       string ]
17
18       ::sha1::hmac key string
19
20       ::sha1::hmac ?-hex|-bin? -key key [ -channel channel | -file filename |
21       ?--? string ]
22
23       ::sha1::SHA1Init
24
25       ::sha1::SHA1Update token data
26
27       ::sha1::SHA1Final token
28
29       ::sha1::HMACInit key
30
31       ::sha1::HMACUpdate token data
32
33       ::sha1::HMACFinal token
34
35______________________________________________________________________________
36

DESCRIPTION

38       This  package provides an implementation in Tcl of the SHA1 message-di‐
39       gest algorithm as specified by FIPS PUB 180-1 (1). This algorithm takes
40       a message and generates a 160-bit digest from the input. The SHA1 algo‐
41       rithm is related to the MD4 algorithm  (2)  but  has  been  strengthend
42       against  certain  types of cryptographic attack. SHA1 should be used in
43       preference to MD4 or MD5 in new applications.
44
45       This package also includes support for creating  keyed  message-digests
46       using the HMAC algorithm from RFC 2104 (3) with SHA1 as the message-di‐
47       gest.
48

COMMANDS

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

PROGRAMMING INTERFACE

86       For  the programmer, the SHA1 hash can be viewed as a bucket into which
87       one pours data. When you have finished, you extract a value that is de‐
88       rived  from  the  data that was poured into the bucket. The programming
89       interface to the SHA1 hash operates  on  a  token  (equivalent  to  the
90       bucket).  You  call SHA1Init to obtain a token and then call SHA1Update
91       as many times as required to add data to the hash. To release  any  re‐
92       sources  and obtain the hash value, you then call SHA1Final. An equiva‐
93       lent set of functions gives you a keyed digest (HMAC).
94
95       If you have critcl and have built the tcllibc package then  the  imple‐
96       mentation  of  the hashing function will be performed by compiled code.
97       Failing that if you have the Trf package then this can be  used  other‐
98       wise  there is a pure-tcl equivalent. The programming interface remains
99       the same in all cases.
100
101       ::sha1::SHA1Init
102              Begins a new SHA1 hash. Returns a token ID that must be used for
103              the remaining functions.
104
105       ::sha1::SHA1Update token data
106              Add  data  to  the  hash identified by token. Calling SHA1Update
107              $token "abcd" is equivalent to calling  SHA1Update  $token  "ab"
108              followed by SHA1Update $token "cb". See EXAMPLES.
109
110       ::sha1::SHA1Final token
111              Returns  the  hash value and releases any resources held by this
112              token. Once this command completes the token  will  be  invalid.
113              The  result  is a binary string of 20 bytes representing the 160
114              bit SHA1 digest value.
115
116       ::sha1::HMACInit key
117              This is equivalent to the ::sha1::SHA1Init command  except  that
118              it requires the key that will be included in the HMAC.
119
120       ::sha1::HMACUpdate token data
121
122       ::sha1::HMACFinal token
123              These commands are identical to the SHA1 equivalent commands.
124

EXAMPLES

126              % sha1::sha1 "Tcl does SHA1"
127              285a6a91c45a9066bf39fcf24425796ef0b2a8bf
128
129
130
131              % sha1::hmac Sekret "Tcl does SHA1"
132              ae6251fa51b95b18cba2be95eb031d07475ff03c
133
134
135
136              % set tok [sha1::SHA1Init]
137              ::sha1::1
138              % sha1::SHA1Update $tok "Tcl "
139              % sha1::SHA1Update $tok "does "
140              % sha1::SHA1Update $tok "SHA1"
141              % sha1::Hex [sha1::SHA1Final $tok]
142              285a6a91c45a9066bf39fcf24425796ef0b2a8bf
143
144

REFERENCES

146       [1]    "Secure  Hash  Standard",  National  Institute  of Standards and
147              Technology,   U.S.   Department   Of   Commerce,   April   1995.
148              (http://www.itl.nist.gov/fipspubs/fip180-1.htm)
149
150       [2]    Rivest,  R.,  "The MD4 Message Digest Algorithm", RFC 1320, MIT,
151              April 1992. (http://www.rfc-editor.org/rfc/rfc1320.txt)
152
153       [3]    Krawczyk, H., Bellare, M. and Canetti, R.  "HMAC:  Keyed-Hashing
154              for   Message   Authentication",   RFC   2104,   February  1997.
155              (http://www.rfc-editor.org/rfc/rfc2104.txt)
156

BUGS, IDEAS, FEEDBACK

158       This document, and the package it describes, will  undoubtedly  contain
159       bugs  and  other  problems.  Please report such in the category sha1 of
160       the  Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please
161       also  report any ideas for enhancements you may have for either package
162       and/or documentation.
163
164       When proposing code changes, please provide unified diffs, i.e the out‐
165       put of diff -u.
166
167       Note  further  that  attachments  are  strongly  preferred over inlined
168       patches. Attachments can be made by going  to  the  Edit  form  of  the
169       ticket  immediately  after  its  creation, and then using the left-most
170       button in the secondary navigation bar.
171

SEE ALSO

173       md4, md5, ripemd128, ripemd160
174

KEYWORDS

176       FIPS 180-1, hashing, message-digest, rfc 2104, security, sha1
177

CATEGORY

179       Hashes, checksums, and encryption
180
182       Copyright (c) 2005, Pat Thoyts <patthoyts@users.sourceforge.net>
183
184
185
186
187tcllib                               2.0.4                             sha1(n)
Impressum