.\" This file is dual-licensed.  Choose whichever you want.
.\"
.\" The first licence is a regular 2-clause BSD licence.  The second licence
.\" is the CC-0 from Creative Commons. It is intended to release Monocypher
.\" to the public domain.  The BSD licence serves as a fallback option.
.\"
.\" SPDX-License-Identifier: BSD-2-Clause OR CC0-1.0
.\"
.\" ----------------------------------------------------------------------------
.\"
.\" Copyright (c) 2017-2019 Loup Vaillant
.\" Copyright (c) 2017-2018 Michael Savage
.\" Copyright (c) 2019-2020 Fabio Scotoni
.\" All rights reserved.
.\"
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are
.\" met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" ----------------------------------------------------------------------------
.\"
.\" Written in 2017-2020 by Loup Vaillant, Michael Savage and Fabio Scotoni
.\"
.\" To the extent possible under law, the author(s) have dedicated all copyright
.\" and related neighboring rights to this software to the public domain
.\" worldwide.  This software is distributed without any warranty.
.\"
.\" You should have received a copy of the CC0 Public Domain Dedication along
.\" with this software.  If not, see
.\" <https://creativecommons.org/publicdomain/zero/1.0/>
.\"
.Dd March 2, 2020
.Dt CRYPTO_HCHACHA20 3MONOCYPHER
.Os
.Sh NAME
.Nm crypto_hchacha20
.Nd HChacha20 special-purpose hashing
.Sh SYNOPSIS
.In monocypher.h
.Ft void
.Fo crypto_hchacha20
.Fa "uint8_t out[32]"
.Fa "const uint8_t key[32]"
.Fa "const uint8_t in[16]"
.Fc
.Sh DESCRIPTION
.Fn crypto_hchacha20
provides a not-so-cryptographic hash.
It may be used for some specific purposes, such as X25519 key
derivation, or XChacha20 initialisation.
If in doubt, do not use directly.
Use
.Xr crypto_blake2b 3monocypher
instead.
.Pp
The arguments are:
.Bl -tag -width Ds
.It Fa key
A sufficiently random key, such as the output of
.Xr crypto_x25519 3monocypher .
.It Fa in
The space reserved for the Chacha20 nonce and counter.
It does not have to be random.
.It Fa out
A cryptographically secure random number
.Em if
there is enough entropy in
.Fa key .
X25519 shared secrets have enough entropy.
.El
.Sh RETURN VALUES
This function returns nothing.
.Sh EXAMPLES
The following example assumes the existence of
.Fn arc4random_buf ,
which fills the given buffer with cryptographically secure random bytes.
If
.Fn arc4random_buf
does not exist on your system, see
.Xr intro 3monocypher
for advice about how to generate cryptographically secure random bytes.
.Pp
Simple hash:
.Bd -literal -offset indent
uint8_t key[32]; /* Must have enough entropy           */
uint8_t in [16]; /* Does not have to be random         */
uint8_t out[32]; /* Will be random iff the above holds */
arc4random_buf(key, 32);
crypto_hchacha20(out, key, in);
/* Wipe secrets if they are no longer needed */
crypto_wipe(key, 32);
crypto_wipe(in , 16);
.Ed
.Sh SEE ALSO
.Xr crypto_chacha20_encrypt 3monocypher ,
.Xr crypto_key_exchange 3monocypher ,
.Xr intro 3monocypher
.Sh STANDARDS
This function implements HChacha20.
HChacha20 derives from Chacha20 the same way HSalsa20 derives from
Salsa20.
.Sh HISTORY
The
.Fn crypto_hchacha20
function first appeared in Monocypher 0.1 as
.Fn crypto_chacha20_H .
It was renamed to
.Fn crypto_hchacha20
in Monocypher 3.0.0.
.Sh CAVEATS
.Sy This is not a general-purpose cryptographic hash function .