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 These functions implement
60 the cryptographic hash functions MD4, MD5, and SHA1.  The output of the
61 hash is called a
62 .IR digest .
63 A hash is secure if, given the hashed data and the digest,
64 it is difficult to predict the change to the digest resulting
65 from some change to the data without rehashing
66 the whole data.  Therefore, if a secret is part of the hashed
67 data, the digest can be used as an integrity check of the data by anyone
68 possessing the secret.
69 .PP
70 The routines
71 .IR md4 ,
72 .IR md5 ,
73 .IR sha1 ,
74 .IR hmac_md5 ,
75 and
76 .I hmac_sha1
77 differ only in the length of the resulting digest
78 and in the security of the hash.  Usage for each is the same.
79 The first call to the routine should have
80 .B nil
81 as the 
82 .I state
83 parameter.  This call returns a state which can be used to chain
84 subsequent calls.
85 The last call should have digest non-\fBnil\fR.
86 .I Digest
87 must point to a buffer of at least the size of the digest produced.
88 This last call will free the state and copy the result into
89 .IR digest .
90 For example, to hash a single buffer using
91 .IR md5 :
92 .EX
93 
94 	uchar digest[MD5dlen];
95 
96 	md5(data, len, digest, nil);
97 .EE
98 .PP
99 To chain a number of buffers together,
100 bounded on each end by some secret:
101 .EX
102 
103 	char buf[256];
104 	uchar digest[MD5dlen];
105 	DigestState *s;
106 
107 	s = md5("my password", 11, nil, nil);
108 	while((n = read(fd, buf, 256)) > 0)
109 		md5(buf, n, nil, s);
110 	md5("drowssap ym", 11, digest, s);
111 .EE
112 .PP
113 The constants
114 .IR MD4dlen ,
115 .IR MD5dlen ,
116 and
117 .I SHA1dlen
118 define the lengths of the digests.
119 .PP
120 .I Hmac_md5
121 and
122 .I hmac_sha1
123 are used slightly differently.  These hash algorithms are keyed and require
124 a key to be specified on every call.
125 The digest lengths for these hashes are
126 .I MD5dlen
127 and
128 .I SHA1dlen
129 respectively.
130 .PP
131 The functions
132 .I md5pickle
133 and
134 .I sha1pickle
135 marshal the state of a digest for transmission.
136 .I Md5unpickle
137 and
138 .I sha1unpickle
139 unmarshal a pickled digest.
140 All four routines return a pointer to a newly
141 .MR malloc (3) 'd
142 object.
143 .SH SOURCE
144 .B \*9/src/libsec
145 .SH SEE ALSO
146 .MR aes (3) ,
147 .MR blowfish (3) ,
148 .MR des (3) ,
149 .MR elgamal (3) ,
150 .MR rc4 (3) ,
151 .MR rsa (3)