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 hmac_x, hmac_md5,
   7 hmac_sha1, hmac_sha2_224, hmac_sha2_256, hmac_sha2_384, hmac_sha2_512,
   8 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*     hmac_x(uchar *p, ulong len, uchar *key, ulong klen, uchar *digest, DS *s, DS*(*x)(uchar*, ulong, uchar*, DS*), int xlen)
  62 .Ti
  63 DS*     hmac_md5(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DS *state)
  64 .Ti
  65 DS*     hmac_sha1(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DS *state)
  66 .Ti
  67 DS*     hmac_sha2_224(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DS *state)
  68 .Ti
  69 DS*     hmac_sha2_256(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DS *state)
  70 .Ti
  71 DS*     hmac_sha2_384(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DS *state)
  72 .Ti
  73 DS*     hmac_sha2_512(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DS *state)
  74 .SH DESCRIPTION
  75 .DT
  76 We support several secure hash functions.  The output of a
  77 hash is called a
  78 .IR digest .
  79 A hash is secure if, given the hashed data and the digest,
  80 it is difficult to predict the change to the digest resulting
  81 from some change to the data without rehashing
  82 the whole data.  Therefore, if a secret is part of the hashed
  83 data, the digest can be used as an integrity check of the data by anyone
  84 possessing the secret.
  85 .PP
  86 The routines
  87 .IR md4 ,
  88 .IR md5 ,
  89 .IR sha1 ,
  90 .IR sha2_224 ,
  91 .IR sha2_256 ,
  92 .IR sha2_384 ,
  93 .IR sha2_512 ,
  94 .IR ripemd160 ,
  95 .IR hmac_md5 ,
  96 .IR hmac_sha1 ,
  97 .IR hmac_sha2_224 ,
  98 .IR hmac_sha2_256 ,
  99 .IR hmac_sha2_384 ,
 100 and
 101 .IR hmac_sha2_512
 102 differ only in the length of the resulting digest
 103 and in the security of the hash.
 104 .I Sha2_*
 105 and
 106 .I hmac_sha2_*
 107 are the SHA-2 functions; the number after the final underscore
 108 is the number of bits in the resulting digest.
 109 Usage for each is the same.
 110 The first call to the routine should have
 111 .B nil
 112 as the
 113 .I state
 114 parameter.  This call returns a state which can be used to chain
 115 subsequent calls.
 116 The last call should have digest
 117 .RL non- nil .
 118 .I Digest
 119 must point to a buffer of at least the size of the digest produced.
 120 This last call will free the state and copy the result into
 121 .IR digest .
 122 .PP
 123 The constants
 124 .IR MD4dlen ,
 125 .IR MD5dlen ,
 126 .IR SHA1dlen ,
 127 .IR SHA2_224dlen ,
 128 .IR SHA2_256dlen ,
 129 .IR SHA2_384dlen,
 130 .IR SHA2_512dlen ,
 131 and
 132 .I AESdlen
 133 define the lengths of the digests.
 134 .PP
 135 .IR Hmac_md5 ,
 136 .IR hmac_sha1 ,
 137 .IR hmac_sha2_224 ,
 138 .IR hmac_sha2_256 ,
 139 .IR hmac_sha2_384 ,
 140 and
 141 .IR hmac_sha2_512
 142 are used slightly differently.  These hash algorithms are keyed and require
 143 a key to be specified on every call.
 144 The digest lengths for these hashes are the obvious ones from
 145 the above list of length constants.
 146 These routines all call
 147 .I hmac_x
 148 internally, but
 149 .I hmac_x
 150 is not intended for general use.
 151 .PP
 152 The functions
 153 .I md5pickle
 154 and
 155 .I sha1pickle
 156 marshal the state of a digest for transmission.
 157 .I Md5unpickle
 158 and
 159 .I sha1unpickle
 160 unmarshal a pickled digest.
 161 All four routines return a pointer to a newly
 162 .IR malloc (2)'d
 163 object.
 164 .SH EXAMPLES
 165 To hash a single buffer using
 166 .IR md5 :
 167 .IP
 168 .EX
 169 uchar digest[MD5dlen];
 170
 171 md5(data, len, digest, nil);
 172 .EE
 173 .PP
 174 To chain a number of buffers together,
 175 bounded on each end by some secret:
 176 .IP
 177 .EX
 178 char buf[256];
 179 uchar digest[MD5dlen];
 180 DigestState *s;
 181
 182 s = md5("my password", 11, nil, nil);
 183 while((n = read(fd, buf, 256)) > 0)
 184         md5(buf, n, nil, s);
 185 md5("drowssap ym", 11, digest, s);
 186 .EE
 187 .SH SOURCE
 188 .B /sys/src/libsec
 189 .SH SEE ALSO
 190 .IR blowfish (2),
 191 .IR des (2),
 192 .IR elgamal (2),
 193 .IR rc4 (2),
 194 .IR rsa (2)
 195 .PD 0
 196 .TF /lib/rfc/rfc2104
 197 .TP
 198 .B /lib/rfc/rfc2104
 199 HMAC specification