Subversion Repositories planix.SVN

Rev

Rev 22 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
2 - 1 
.TH SECHASH 2
2 
.SH NAME
3 
md4, md5,
4 
sha1, sha2_224, sha2_256, sha2_384, sha2_512,
5 
aes, hmac_x, hmac_md5,
6 
hmac_sha1, hmac_sha2_224, hmac_sha2_256, hmac_sha2_384, hmac_sha2_512,
7 
hmac_aes, md5pickle, md5unpickle,
8 
sha1pickle, sha1unpickle \- cryptographically secure hashes
9 
.SH SYNOPSIS
10 
.nr Wd \w'\fLDS* \fP'u
11 
.nr In \w'\fLDS*   \fP'u
12 
.ta \n(Wdu \w'\fLSHA1state* \fP'u +\n(Wdu +\n(Wdu +\n(Wdu +\n(Wdu
13 
.
14 
.de Ti
15 
.PP
16 
.in +\\n(Inu
17 
.ti -\\n(Inu
18 
.B
19 
.nh
20 
..
21 
.
22 
.ft L
23 
.nf
24 
#include <u.h>
25 
#include <libc.h>
26 
#include <mp.h>
27 
#include <libsec.h>
28 
#define DS DigestState	/* only to abbreviate SYNOPSIS */
29 
.fi
30 
.
31 
.Ti
32 
DS*	md4(uchar *data, ulong dlen, uchar *digest, DS *state)
33 
.Ti
34 
DS*	md5(uchar *data, ulong dlen, uchar *digest, DS *state)
35 
.PP
36 
.B
37 
char*	md5pickle(MD5state *state)
38 
.PP
39 
.B
40 
MD5state*	md5unpickle(char *p);
41 
.Ti
42 
DS*	sha1(uchar *data, ulong dlen, uchar *digest, DS *state)
43 
.PP
44 
.B
45 
char*	sha1pickle(SHA1state *state)
46 
.PP
47 
.B
48 
SHA1state*	sha1unpickle(char *p);
49 
.Ti
50 
DS*	sha2_224(uchar *data, ulong dlen, uchar *digest, DS *state)
51 
.Ti
52 
DS*	sha2_256(uchar *data, ulong dlen, uchar *digest, DS *state)
53 
.Ti
54 
DS*	sha2_384(uchar *data, ulong dlen, uchar *digest, DS *state)
55 
.Ti
56 
DS*	sha2_512(uchar *data, ulong dlen, uchar *digest, DS *state)
57 
.Ti
58 
DS*	aes(uchar *data, ulong dlen, uchar *digest, DS *state)
59 
.Ti
60 
DS*	hmac_x(uchar *p, ulong len, uchar *key, ulong klen, uchar *digest, DS *s, DS*(*x)(uchar*, ulong, uchar*, DS*), int xlen)
61 
.Ti
62 
DS*	hmac_md5(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DS *state)
63 
.Ti
64 
DS*	hmac_sha1(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DS *state)
65 
.Ti
66 
DS*	hmac_sha2_224(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DS *state)
67 
.Ti
68 
DS*	hmac_sha2_256(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DS *state)
69 
.Ti
70 
DS*	hmac_sha2_384(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DS *state)
71 
.Ti
72 
DS*	hmac_sha2_512(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DS *state)
73 
.Ti
74 
DS*	hmac_aes(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DS *state)
75 
.SH DESCRIPTION
76 
.DT
77 
We support several secure hash functions.  The output of a
78 
hash is called a
79 
.IR digest .
80 
A hash is secure if, given the hashed data and the digest,
81 
it is difficult to predict the change to the digest resulting
82 
from some change to the data without rehashing
83 
the whole data.  Therefore, if a secret is part of the hashed
84 
data, the digest can be used as an integrity check of the data by anyone
85 
possessing the secret.
86 
.PP
87 
The routines
88 
.IR md4 ,
89 
.IR md5 ,
90 
.IR sha1 ,
91 
.IR sha2_224 ,
92 
.IR sha2_256 ,
93 
.IR sha2_384 ,
94 
.IR sha2_512 ,
95 
.IR aes ,
96 
.IR hmac_md5 ,
97 
.IR hmac_sha1 ,
98 
.IR hmac_sha2_224 ,
99 
.IR hmac_sha2_256 ,
100 
.IR hmac_sha2_384 ,
101 
.IR hmac_sha2_512 ,
102 
and
103 
.I hmac_aes
104 
differ only in the length of the resulting digest
105 
and in the security of the hash.
106 
.I Sha2_*
107 
and
108 
.I hmac_sha2_*
109 
are the SHA-2 functions; the number after the final underscore
110 
is the number of bits in the resulting digest.
111 
Usage for each is the same.
112 
The first call to the routine should have
113 
.B nil
114 
as the
115 
.I state
116 
parameter.  This call returns a state which can be used to chain
117 
subsequent calls.
118 
The last call should have digest
119 
.RL non- nil .
120 
.I Digest
121 
must point to a buffer of at least the size of the digest produced.
122 
This last call will free the state and copy the result into
123 
.IR digest .
124 
.PP
125 
The constants
126 
.IR MD4dlen ,
127 
.IR MD5dlen ,
128 
.IR SHA1dlen ,
129 
.IR SHA2_224dlen ,
130 
.IR SHA2_256dlen ,
131 
.IR SHA2_384dlen,
132 
.IR SHA2_512dlen ,
133 
and
134 
.I AESdlen
135 
define the lengths of the digests.
136 
.PP
137 
.IR Hmac_md5 ,
138 
.IR hmac_sha1 ,
139 
.IR hmac_sha2_224 ,
140 
.IR hmac_sha2_256 ,
141 
.IR hmac_sha2_384 ,
142 
.IR hmac_sha2_512 ,
143 
and
144 
.I hmac_aes
145 
are used slightly differently.  These hash algorithms are keyed and require
146 
a key to be specified on every call.
147 
The digest lengths for these hashes are the obvious ones from
148 
the above list of length constants.
149 
These routines all call
150 
.I hmac_x
151 
internally, but
152 
.I hmac_x
153 
is not intended for general use.
154 
.PP
155 
The functions
156 
.I md5pickle
157 
and
158 
.I sha1pickle
159 
marshal the state of a digest for transmission.
160 
.I Md5unpickle
161 
and
162 
.I sha1unpickle
163 
unmarshal a pickled digest.
164 
All four routines return a pointer to a newly
165 
.IR malloc (2)'d
166 
object.
167 
.SH EXAMPLES
168 
To hash a single buffer using
169 
.IR md5 :
170 
.IP
171 
.EX
172 
uchar digest[MD5dlen];
173 
 
174 
md5(data, len, digest, nil);
175 
.EE
176 
.PP
177 
To chain a number of buffers together,
178 
bounded on each end by some secret:
179 
.IP
180 
.EX
181 
char buf[256];
182 
uchar digest[MD5dlen];
183 
DigestState *s;
184 
 
185 
s = md5("my password", 11, nil, nil);
186 
while((n = read(fd, buf, 256)) > 0)
187 
	md5(buf, n, nil, s);
188 
md5("drowssap ym", 11, digest, s);
189 
.EE
190 
.SH SOURCE
191 
.B /sys/src/libsec
192 
.SH SEE ALSO
193 
.IR aes (2),
194 
.IR blowfish (2),
195 
.IR des (2),
196 
.IR elgamal (2),
197 
.IR rc4 (2),
198 
.IR rsa (2)
199 
.PD 0
200 
.TF /lib/rfc/rfc2104
201 
.TP
202 
.B /lib/rfc/rfc2104
203 
HMAC specification