1 .TH SECHASH 3
2 .SH NAME
3 md4, md5, sha1, hmac_md5, hmac_sha1, md5pickle, md5unpickle, sha1pickle, sha1unpickle \- cryptographically secure hashes
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .br
7 .B #include <libc.h>
8 .br
9 .B #include <mp.h>
10 .br
11 .B #include <libsec.h>
12 .PP
13 .B
14 DigestState*	md4(uchar *data, ulong dlen, uchar *digest,
15 .B
16 			 DigestState *state)
17 .PP
18 .B
19 DigestState*	md5(uchar *data, ulong dlen, uchar *digest,
20 .B
21 			 DigestState *state)
22 .PP
23 .B
24 char*		md5pickle(MD5state *state)
25 .PP
26 .B
27 MD5state*	md5unpickle(char *p);
28 .PP
29 .B
30 DigestState*	sha1(uchar *data, ulong dlen, uchar *digest,
31 .B
32 			 DigestState *state)
33 .PP
34 .B
35 char*		sha1pickle(MD5state *state)
36 .PP
37 .B
38 MD5state*	sha1unpickle(char *p);
39 .PP
40 .B
41 DigestState*	hmac_md5(uchar *data, ulong dlen,
42 .br
43 .B
44 			 uchar *key, ulong klen,
45 .br
46 .B
47 			 uchar *digest, DigestState *state)
48 .PP
49 .B
50 DigestState*	hmac_sha1(uchar *data, ulong dlen,
51 .br
52 .B
53 			 uchar *key, ulong klen,
54 .br
55 .B
56 			 uchar *digest, DigestState *state)
57 .SH DESCRIPTION
58 .PP
59 We support several secure hash functions.  The output of the
60 hash is called a
61 .IR digest .
62 A hash is secure if, given the hashed data and the digest,
63 it is difficult to predict the change to the digest resulting
64 from some change to the data without rehashing
65 the whole data.  Therefore, if a secret is part of the hashed
66 data, the digest can be used as an integrity check of the data by anyone
67 possessing the secret.
68 .PP
69 The routines
70 .IR md4 ,
71 .IR md5 ,
72 .IR sha1 ,
73 .IR hmac_md5 ,
74 and
75 .I hmac_sha1
76 differ only in the length of the resulting digest
77 and in the security of the hash.  Usage for each is the same.
78 The first call to the routine should have
79 .B nil
80 as the 
81 .I state
82 parameter.  This call returns a state which can be used to chain
83 subsequent calls.
84 The last call should have digest non-\fBnil\fR.
85 .I Digest
86 must point to a buffer of at least the size of the digest produced.
87 This last call will free the state and copy the result into
88 .IR digest .
89 For example, to hash a single buffer using
90 .IR md5 :
91 .EX
92 
93 	uchar digest[MD5dlen];
94 
95 	md5(data, len, digest, nil);
96 .EE
97 .PP
98 To chain a number of buffers together,
99 bounded on each end by some secret:
100 .EX
101 
102 	char buf[256];
103 	uchar digest[MD5dlen];
104 	DigestState *s;
105 
106 	s = md5("my password", 11, nil, nil);
107 	while((n = read(fd, buf, 256)) > 0)
108 		md5(buf, n, nil, s);
109 	md5("drowssap ym", 11, digest, s);
110 .EE
111 .PP
112 The constants
113 .IR MD4dlen ,
114 .IR MD5dlen ,
115 and
116 .I SHA1dlen
117 define the lengths of the digests.
118 .PP
119 .I Hmac_md5
120 and
121 .I hmac_sha1
122 are used slightly differently.  These hash algorithms are keyed and require
123 a key to be specified on every call.
124 The digest lengths for these hashes are
125 .I MD5dlen
126 and
127 .I SHA1dlen
128 respectively.
129 .PP
130 The functions
131 .I md5pickle
132 and
133 .I sha1pickle
134 marshal the state of a digest for transmission.
135 .I Md5unpickle
136 and
137 .I sha1unpickle
138 unmarshal a pickled digest.
139 All four routines return a pointer to a newly
140 .IR malloc (3)'d
141 object.
142 .SH SOURCE
143 .B /usr/local/plan9/src/libsec
144 .SH SEE ALSO
145 .IR aes (3),
146 .IR blowfish (3),
147 .IR des (3),
148 .IR elgamal (3),
149 .IR rc4 (3),
150 .IR rsa (3)