.\"	$OpenBSD: SipHash24_Init.3,v 1.1 2019/08/30 22:20:43 deraadt 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: August 30 2019 $
.Dt SIPHASH24 3
.Os
.Sh NAME
.Nm SipHash24_Init ,
.Nm SipHash24_Update ,
.Nm SipHash24_End ,
.Nm SipHash24_Final ,
.Nm SipHash24
.Nd calculate SipHash24 hashes
.Sh SYNOPSIS
.In 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 uint64_t
.Fn SipHash24_End "SIPHASH_CTX *ctx"
.Ft void
.Fn SipHash24_Final "void *digest" "SIPHASH_CTX *ctx"
.Ft uint64_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 which 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 host's 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
It is recommended that the
.Vt SIPHASH_KEY
key be generated with
.Xr arc4random_buf 3 .
.Sh RETURN VALUES
.Fn SipHash24_End
and
.Fn SipHash24
return the 64-bit message digest in the host's native endian representation.
.Sh SEE ALSO
.Xr arc4random_buf 3
.Sh HISTORY
These functions appeared in
.Ox 5.7 .