SECHASH(2)                                             SECHASH(2)

     NAME
          md4, md5, sha1, sha2_224, sha2_256, sha2_384, sha2_512,
          ripemd160, poly1305, hmac_x, hmac_md5, hmac_sha1,
          hmac_sha2_224, hmac_sha2_256, hmac_sha2_384, hmac_sha2_512,
          md5pickle, md5unpickle, sha1pickle, sha1unpickle -
          cryptographically secure hashes

     SYNOPSIS
          #include <u.h>
          #include <libc.h>
          #include <mp.h>
          #include <libsec.h>
          #define DS DigestState /* only to abbreviate SYNOPSIS */

          DS* md4(uchar *data, ulong dlen, uchar *digest, DS *state)

          DS* md5(uchar *data, ulong dlen, uchar *digest, DS *state)

          char*      md5pickle(MD5state *state)

          MD5state*  md5unpickle(char *p);

          DS* sha1(uchar *data, ulong dlen, uchar *digest, DS *state)

          char*      sha1pickle(SHA1state *state)

          SHA1state* sha1unpickle(char *p);

          DS* sha2_224(uchar *data, ulong dlen, uchar *digest, DS
                *state)

          DS* sha2_256(uchar *data, ulong dlen, uchar *digest, DS
                *state)

          DS* sha2_384(uchar *data, ulong dlen, uchar *digest, DS
                *state)

          DS* sha2_512(uchar *data, ulong dlen, uchar *digest, DS
                *state)

          DS* ripemd160(uchar *data, ulong dlen, uchar *digest, DS
                *state)

          DS* poly1305(uchar *p, ulong len, uchar *key, ulong klen,
                uchar *digest, DS *state)

          DS* hmac_x(uchar *p, ulong len, uchar *key, ulong klen,
                uchar *digest, DS *s, DS*(*x)(uchar*, ulong, uchar*,
                DS*), int xlen)

     SECHASH(2)                                             SECHASH(2)

          DS* hmac_md5(uchar *data, ulong dlen, uchar *key, ulong
                klen, uchar *digest, DS *state)

          DS* hmac_sha1(uchar *data, ulong dlen, uchar *key, ulong
                klen, uchar *digest, DS *state)

          DS* hmac_sha2_224(uchar *data, ulong dlen, uchar *key, ulong
                klen, uchar *digest, DS *state)

          DS* hmac_sha2_256(uchar *data, ulong dlen, uchar *key, ulong
                klen, uchar *digest, DS *state)

          DS* hmac_sha2_384(uchar *data, ulong dlen, uchar *key, ulong
                klen, uchar *digest, DS *state)

          DS* hmac_sha2_512(uchar *data, ulong dlen, uchar *key, ulong
                klen, uchar *digest, DS *state)

     DESCRIPTION
          We support several secure hash functions.  The output of a
          hash is called a digest. A hash is secure if, given the
          hashed data and the digest, it is difficult to predict the
          change to the digest resulting from some change to the data
          without rehashing the whole data.  Therefore, if a secret is
          part of the hashed data, the digest can be used as an
          integrity check of the data by anyone possessing the secret.

          The routines md4, md5, sha1, sha2_224, sha2_256, sha2_384,
          sha2_512, ripemd160, poly1305, hmac_md5, hmac_sha1,
          hmac_sha2_224, hmac_sha2_256, hmac_sha2_384, and
          hmac_sha2_512 differ only in the length of the resulting
          digest and in the security of the hash.  Sha2_* and
          hmac_sha2_* are the SHA-2 functions; the number after the
          final underscore is the number of bits in the resulting
          digest.  Usage for each is the same.  The first call to the
          routine should have nil as the state parameter.  This call
          returns a state which can be used to chain subsequent calls.
          The last call should have digest non-`nil'.  Digest must
          point to a buffer of at least the size of the digest pro-
          duced.  This last call will free the state and copy the
          result into digest.

          The constants MD4dlen, MD5dlen, SHA1dlen, SHA2_224dlen,
          SHA2_256dlen, SHA2_384dlen, SHA2_512dlen, and AESdlen define
          the lengths of the digests.

          Hmac_md5, hmac_sha1, hmac_sha2_224, hmac_sha2_256,
          hmac_sha2_384, and hmac_sha2_512 are used slightly differ-
          ently.  These hash algorithms are keyed and require a key to
          be specified on every call.  The digest lengths for these
          hashes are the obvious ones from the above list of length
          constants.  These routines all call hmac_x internally, but

     SECHASH(2)                                             SECHASH(2)

          hmac_x is not intended for general use.

          Poly1305 is a one-time authenticator designed by D. J. Bern-
          stein. It takes a 32-byte one-time key and a message and
          produces a 16-byte tag.

          The functions md5pickle and sha1pickle marshal the state of
          a digest for transmission.  Md5unpickle and sha1unpickle
          unmarshal a pickled digest.  All four routines return a
          pointer to a newly malloc(2)'d object.

     EXAMPLES
          To hash a single buffer using md5:

               uchar digest[MD5dlen];

               md5(data, len, digest, nil);

          To chain a number of buffers together, bounded on each end
          by some secret:

               char buf[256];
               uchar digest[MD5dlen];
               DigestState *s;

               s = md5("my password", 11, nil, nil);
               while((n = read(fd, buf, 256)) > 0)
                    md5(buf, n, nil, s);
               md5("drowssap ym", 11, digest, s);

     SOURCE
          /sys/src/libsec

     SEE ALSO
          blowfish(2), des(2), elgamal(2), rc4(2), rsa(2)
          /lib/rfc/rfc2104  HMAC specification