code: purgatorio

ref: 5edeca01b0622463a65c126ebcc29314013fd928
dir: /man/2/keyring-sha1/

.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->SHA1dlen] 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.