sys/man/2/sechash

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