document the SipHash24 api. some more could be done for history and

where its appropriate to use it, but that can happen later.

discussed with djm@
tweaks from jmc@

2 files changed, 113 insertions, 2 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index bcaac45d0f9..865c72d1c71 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.221 2014/11/01 21:45:54 mpi Exp $
+#	$OpenBSD: Makefile,v 1.222 2014/11/04 23:27:02 dlg Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -27,7 +27,7 @@ MAN=	aml_evalnode.9 atomic_add_int.9 atomic_cas_uint.9 \
 	pool.9 powerhook_establish.9 ppsratecheck.9 printf.9 psignal.9 \
 	radio.9 arc4random.9 rasops.9 ratecheck.9 resettodr.9 rssadapt.9 \
 	route.9 rt_ifa_add.9 rt_timer_add.9 rtalloc.9 rtable_add.9 \
-	rtlabel_id2name.9 rtrequest1.9 rwlock.9 sensor_attach.9 \
+	rtlabel_id2name.9 rtrequest1.9 rwlock.9 SipHash24.9 sensor_attach.9 \
 	shutdownhook_establish.9 tsleep.9 spl.9 startuphook_establish.9 \
 	socreate.9 sosplice.9 style.9 syscall.9 systrace.9 sysctl_int.9 \
 	task_add.9 tc_init.9 time.9 timeout.9 tvtohz.9 uiomove.9 uvm.9 \
@@ -345,6 +345,8 @@ MLINKS+=rwlock.9 rw_init.9 rwlock.9 rw_enter.9 rwlock.9 rw_exit.9 \
 	rwlock.9 RWLOCK_INITIALIZER.9 rwlock.9 rrw_init.9 \
 	rwlock.9 rrw_enter.9 rwlock.9 rrw_exit.9 \
 	rwlock.9 rrw_status.9
+MLINKS+=SipHash24.9 SipHash24_Init.9 SipHash24.9 SipHash24_Update.9 \
+	SipHash24.9 SipHash24_End.9 SipHash24.9 SipHash24_Final.9
 MLINKS+=sensor_attach.9 sensordev_install.9 \
 	sensor_attach.9 sensordev_deinstall.9 \
 	sensor_attach.9 sensordev_get.9 \
diff --git a/share/man/man9/SipHash24.9 b/share/man/man9/SipHash24.9
new file mode 100644
index 00000000000..be484d32688
--- /dev/null
+++ b/share/man/man9/SipHash24.9
@@ -0,0 +1,109 @@
+.\"	$OpenBSD: SipHash24.9,v 1.1 2014/11/04 23:27:02 dlg Exp $
+.\"
+.\" Copyright (c) 2014 David Gwynne <dlg@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: November 4 2014 $
+.Dt SIPHASH24 9
+.Os
+.Sh NAME
+.Nm SipHash24_Init ,
+.Nm SipHash24_Update ,
+.Nm SipHash24_End ,
+.Nm SipHash24_Final ,
+.Nm SipHash24
+.Nd calculate SipHash24 hashes
+.Sh SYNOPSIS
+.In crypto/siphash.h
+.Ft void
+.Fn "SipHash24_Init" "SIPHASH_CTX *ctx" "const SIPHASH_KEY *key"
+.Ft void
+.Fn "SipHash24_Update" "SIPHASH_CTX *ctx" "const void *data" "size_t len"
+.Ft u_int64_t
+.Fn "SipHash24_End" "SIPHASH_CTX *ctx"
+.Ft void
+.Fn "SipHash24_Final" "void *digest" "SIPHASH_CTX *ctx"
+.Ft u_int64_t
+.Fn "SipHash24" "const SIPHASH_KEY *key" "const void *data" "size_t len"
+.Sh DESCRIPTION
+The SipHash algorithm is a keyed hash algorithm optimised for short
+inputs and produces a 64-bit digest of data.
+The SipHash24 functions implement the algorithm with 2 compression
+rounds and 4 finalisation rounds.
+.Pp
+.Fn SipHash24_Init
+initialises a
+.Vt SIPHASH_CTX
+context
+.Fa ctx
+with the secret
+.Fa key .
+.Pp
+.Fn SipHash24_Update
+adds
+.Fa data
+of length
+.Fa len
+to the context
+.Fa ctx .
+.Pp
+.Fn SipHash24_End
+is called after all data has been added to
+.Fa ctx
+via
+.Fn SipHash24_Update
+and returns a message digest in the hosts native endian.
+.Pp
+.Fn SipHash24_Final
+is called after all data has been added to
+.Fa ctx
+via
+.Fn SipHash24_Update
+and stores the message digest at the address specified by the
+.Fa digest
+parameter.
+The buffer at
+.Fa digest
+must be
+.Dv SIPHASH_DIGEST_LENGTH
+bytes long.
+.Pp
+.Fn SipHash24
+calculates the digest of
+.Fa data
+of length
+.Fa len
+with the secret
+.Fa key .
+.Pp
+If SipHash is being used to mitigate against hash-table flooding
+attacks, it is recommended that the
+.Vt SIPHASH_KEY
+key be generated with
+.Xr arc4random_buf 9 .
+.Sh CONTEXT
+.Fn SipHash24_Init ,
+.Fn SipHash24_Update ,
+.Fn SipHash24_End ,
+.Fn SipHash24_Final
+and
+.Fn SipHash24
+can be called during autoconf, from process context, or from interrupt context.
+.Sh RETURN VALUES
+.Fn SipHash24_End
+and
+.Fn SipHash24
+returns the 64-bit message digest in the hosts native endian representation.
+.Sh SEE ALSO
+.Xr arc4random_buf 9