KEYRING-SHA(2)                                     KEYRING-SHA(2)

     NAME
          sha, md4, md5, hmac_sha1, hmac_md5, sign, verify -
          cryptographic digests and digital signatures

     SYNOPSIS
          include "keyring.m";
          keyring := load Keyring Keyring->PATH;

          sha:    fn(buf: array of byte, n: int, digest: array of byte,
                        state: ref DigestState): ref DigestState;
          md4:    fn(buf: array of byte, n: int, digest: array of byte,
                        state: ref DigestState): ref DigestState;
          md5:    fn(buf: array of byte, n: int, digest: array of byte,
                        state: ref DigestState): ref DigestState;
          hmac_sha1:    fn(buf: array of byte, n: int, key: array of byte, digest: array of byte,
                        state: ref DigestState): ref DigestState;
          hmac_md5:     fn(buf: array of byte, n: int, key: array of byte, digest: array of byte,
                        state: ref DigestState): ref DigestState;
          sign:   fn(sk: ref SK, exp: int, state: ref DigestState,
                        ha: string): ref Certificate;
          verify: fn(pk: ref PK, cert: ref Certificate,
                        state: ref DigestState): int;

     DESCRIPTION
          Sha, md4 and md5 are cryptographically secure hash functions
          that produce output called a message digest.  Each function
          computes a hash of n bytes of the data in buf, and updates
          the current state. They can be called iteratively to form a
          single digest for many data blocks.  The state is kept in
          the DigestState value referenced by state between calls.
          State should be nil on the first call, and a newly allocated
          DigestState will be returned for use in subsequent calls.
          On a call in which digest is not nil, the hash is completed
          and copied into the digest array.  Sha produces a 20-byte
          hash (SHA1dlen), md4 and md5 a 16-byte one (MD4len and
          MD5len).

          Hmac_sha1 and hmac_md5 are keyed versions of the hashing
          functions, following Internet RFC2104.  The key must be pro-
          vided in each call, but otherwise the calling conventions
          are those of sha.  The key must currently be no more than 64
          bytes.

          Sign creates a digital signature of a digest from the con-
          catenation of: a message, the name of the signer, and an
          expiration time.  State is the digest state after running
          sha, md4 or md5 over the message.  Ha is a string specifying
          the hash algorithm to use: "sha", "sha1", "md4" or "md5".
          Sign extends the digest to cover the signer's name (taken
          from the private key, sk) and the expiration time.  It

     Page 1                       Plan 9             (printed 3/28/24)

     KEYRING-SHA(2)                                     KEYRING-SHA(2)

          returns a certificate containing the digital signature of
          the digest, signer name, hash algorithm and signature algo-
          rithm.  If any parameter is invalid, sign returns nil.  The
          signature algorithm is implied by the type of the private
          key.

          Verify uses public key pk to verify a certificate.  It
          returns non-zero (true) if the certificate is valid; zero
          (false) otherwise.  State is the digest state after running
          the chosen digest algorithm over the message.

     EXAMPLES
          A program to read a file and hash it using SHA might contain
          the following inner loop:

               state: ref DigestState = nil;
               while((n := sys->read(fd, buf, len buf)) > 0)
                       state = kr->sha(buf, n, nil, state);
               digest := array[kr->SHAdlen] of byte;
               kr->sha(buf, 0, digest, state);

     SOURCE
          /interp/keyring.c
          /crypt/hmac.c
          /crypt/md4.c
          /crypt/md5.c
          /crypt/sha.c

     Page 2                       Plan 9             (printed 3/28/24)