1 files changed, 142 insertions, 0 deletions
diff --git a/man/2/keyring-sha1 b/man/2/keyring-sha1
new file mode 100644
index 00000000..e453a25c
--- /dev/null
+++ b/man/2/keyring-sha1
@@ -0,0 +1,142 @@
+.TH KEYRING-SHA1 2
+.SH NAME
+keyring: sha1, md4, md5, hmac_sha1, hmac_md5, sign, verify \- cryptographic digests and digital signatures
+.SH SYNOPSIS
+.EX
+include "keyring.m";
+keyring := load Keyring Keyring->PATH;
+
+.ta \w'verify:\ 'u +\w'fn(\ \ \ 'u
+sha1:	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;
+.EE
+.SH DESCRIPTION
+.BR Sha1 ,
+.B md4
+and
+.B md5
+are cryptographically secure hash functions that produce output called a message digest.
+Each function computes a hash of
+.I n
+bytes of the data in
+.IR buf ,
+and updates the current
+.IR state .
+They can be called iteratively to form a single digest for many data blocks.
+The state is kept in the
+.B DigestState
+value referenced by
+.I state
+between calls.
+.I State
+should be
+.B nil
+on the first call, and a newly allocated
+.B DigestState
+will be returned for use in subsequent calls.
+On a call in which
+.I digest
+is not
+.BR nil ,
+the hash is completed and copied into the
+.I digest
+array.
+.B Sha1
+produces a 20-byte hash
+.RB ( SHA1dlen ),
+.B md4
+and
+.B md5
+a 16-byte one
+.RB ( MD4len
+and
+.BR MD5len ).
+.PP
+.B Hmac_sha1
+and
+.B hmac_md5
+are keyed versions of the hashing functions, following Internet RFC2104.
+The
+.I key
+must be provided in each call, but otherwise
+the calling conventions are those of
+.BR sha1 .
+The
+.I key
+must currently be no more than 64 bytes.
+.PP
+.B Sign
+creates a digital signature of a digest from the concatenation of: a message, the name of the signer, and an expiration time.
+.I State
+is the digest state after running
+.BR sha1 ,
+.B md4
+or
+.B md5
+over the message.
+.I Ha
+is a string specifying the hash algorithm to use:
+.B
+"sha"\fR,
+.B
+"sha1"\fR,
+.B
+"md4"\fR
+or
+.B
+"md5"\fR.
+.B Sign
+extends the digest to cover the signer's name
+(taken from the private key,
+.IR sk )
+and the expiration time.
+It returns a certificate containing the digital signature of the digest, signer name, hash algorithm and signature algorithm.
+If any parameter is invalid,
+.B sign
+returns nil.
+The signature algorithm is implied by the type of the private key.
+.PP
+.B Verify
+uses public key
+.I pk
+to verify a certificate.
+It returns non-zero (true) if the certificate is valid; zero (false) otherwise.
+.I State
+is the digest state after running the chosen digest algorithm
+over the message.
+.SH EXAMPLES
+A program to read a file and hash it using SHA might contain the following inner loop:
+.IP
+.EX
+state: ref DigestState = nil;
+while((n := sys->read(fd, buf, len buf)) > 0)
+	state = kr->sha1(buf, n, nil, state);
+digest := array[kr->SHAdlen] of byte;
+kr->sha1(buf, 0, digest, state);
+.EE
+.SH SOURCE
+.B /libinterp/keyring.c
+.br
+.B /libcrypt/hmac.c
+.br
+.B /libcrypt/md4.c
+.br
+.B /libcrypt/md5.c
+.br
+.B /libcrypt/sha1.c
+.SH BUGS
+The MD4 algorithm is included only to allow communication with software
+that might still use it; it should not otherwise be used now, because it
+is easily broken.