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.2?
14
15       ::sha1::sha1 ?-hex|-bin? [ -channel channel | -file filename | string ]
16
17       ::sha1::hmac key string
18
19       ::sha1::hmac ?-hex|-bin? -key key [ -channel channel | -file filename |
20       string ]
21
22       ::sha1::SHA1Init
23
24       ::sha1::SHA1Update token data
25
26       ::sha1::SHA1Final token
27
28       ::sha1::HMACInit key
29
30       ::sha1::HMACUpdate token data
31
32       ::sha1::HMACFinal token
33
34_________________________________________________________________
35

DESCRIPTION

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

COMMANDS

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

PROGRAMMING INTERFACE

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

EXAMPLES

116       % sha1::sha1 "Tcl does SHA1"
117       285a6a91c45a9066bf39fcf24425796ef0b2a8bf
118
119
120       % sha1::hmac Sekret "Tcl does SHA1"
121       ae6251fa51b95b18cba2be95eb031d07475ff03c
122
123
124       % set tok [sha1::SHA1Init]
125       ::sha1::1
126       % sha1::SHA1Update $tok "Tcl "
127       % sha1::SHA1Update $tok "does "
128       % sha1::SHA1Update $tok "SHA1"
129       % sha1::Hex [md5::MD5Final $tok]
130       285a6a91c45a9066bf39fcf24425796ef0b2a8bf
131
132

REFERENCES

134       [1]    "Secure  Hash  Standard",  National  Institute  of Standards and
135              Technology,   U.S.   Department   Of   Commerce,   April   1995.
136              (http://www.itl.nist.gov/fipspubs/fip180-1.htm)
137
138       [2]    Rivest,  R.,  "The MD4 Message Digest Algorithm", RFC 1320, MIT,
139              April 1992. (http://www.rfc-editor.org/rfc/rfc1320.txt)
140
141       [3]    Krawczyk, H., Bellare, M. and Canetti, R.  "HMAC:  Keyed-Hashing
142              for   Message   Authentication",   RFC   2104,   February  1997.
143              (http://www.rfc-editor.org/rfc/rfc2104.txt)
144

SEE ALSO

146       md4, md5, ripemd128, ripemd160
147

KEYWORDS

149       FIPS 180-1, hashing, message-digest, rfc 2104, security, sha1
150
152       Copyright (c) 2005, Pat Thoyts <patthoyts@users.sourceforge.net>
153
154
155
156
157sha1                                 2.0.2                             sha1(n)
Impressum