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 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