sys/man/2/sechash

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