glenda.party
term% ls -F
term% cat index.txt
SECHASH(2)                    System Calls Manual                   SECHASH(2)



NAME
       md4,  md5,  sha1,  sha2_224, sha2_256, sha2_384, sha2_512, aes, hmac_x,
       hmac_md5,  hmac_sha1,  hmac_sha2_224,   hmac_sha2_256,   hmac_sha2_384,
       hmac_sha2_512,    hmac_aes,    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* aes(uchar *data, ulong dlen, 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)

       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)

       DS* hmac_aes(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,
       aes, hmac_md5, hmac_sha1, hmac_sha2_224, hmac_sha2_256,  hmac_sha2_384,
       hmac_sha2_512,  and hmac_aes 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 Digest must point to a buffer of at least the
       size of the digest produced.  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,
       hmac_sha2_512, and hmac_aes are used slightly differently.  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 hmac_x is not intended for general use.

       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
       aes(2), blowfish(2), des(2), elgamal(2), rc4(2), rsa(2)
       /lib/rfc/rfc2104
              HMAC specification



                                                                    SECHASH(2)