.\" 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) 2018 Michael Savage
.\" Copyright (c) 2017, 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 31, 2020
.Dt CRYPTO_BLAKE2B 3MONOCYPHER
.Os
.Sh NAME
.Nm crypto_blake2b ,
.Nm crypto_blake2b_general ,
.Nm crypto_blake2b_general_init ,
.Nm crypto_blake2b_init ,
.Nm crypto_blake2b_update ,
.Nm crypto_blake2b_final
.Nd cryptographic hashing
.Sh SYNOPSIS
.In monocypher.h
.Ft void
.Fo crypto_blake2b
.Fa "uint8_t hash[64]"
.Fa "const uint8_t *message"
.Fa "size_t message_size"
.Fc
.Ft void
.Fo crypto_blake2b_general
.Fa "uint8_t *hash"
.Fa "size_t hash_size"
.Fa "const uint8_t *key"
.Fa "size_t key_size"
.Fa "const uint8_t *message"
.Fa "size_t message_size"
.Fc
.Ft void
.Fo crypto_blake2b_init
.Fa "crypto_blake2b_ctx *ctx"
.Fc
.Ft void
.Fo crypto_blake2b_general_init
.Fa "crypto_blake2b_ctx *ctx"
.Fa "size_t hash_size"
.Fa "const uint8_t *key"
.Fa "size_t key_size"
.Fc
.Ft void
.Fo crypto_blake2b_update
.Fa "crypto_blake2b_ctx *ctx"
.Fa "const uint8_t *message"
.Fa "size_t message_size"
.Fc
.Ft void
.Fo crypto_blake2b_final
.Fa "crypto_blake2b_ctx *ctx"
.Fa "uint8_t *hash"
.Fc
.Sh DESCRIPTION
BLAKE2b is a fast cryptographically secure hash, based on the ideas of
Chacha20.
It is faster than MD5, yet just as secure as SHA-3.
.Pp
Note that BLAKE2b itself is not suitable for hashing passwords and
deriving keys from them;
use the
.Xr crypto_argon2i 3monocypher
family of functions for that purpose instead.
.Pp
BLAKE2b is immune to length extension attacks, and as such does not
require any specific precautions, such as using the HMAC algorithm.
.Pp
The arguments are:
.Bl -tag -width Ds
.It Fa hash
The output hash.
.It Fa hash_size
Length of
.Fa hash ,
in bytes.
Must be between 1 and 64.
Anything below 32 is discouraged when using Blake2b as a general-purpose
hash function;
anything below 16 is discouraged when using Blake2b as a message
authentication code.
.It Fa key
Some secret key.
One cannot predict the final hash without it.
May be
.Dv NULL
if
.Fa key_size
is 0, in which case no key is used.
Keys can be used to create a message authentication code (MAC).
Use
.Xr crypto_verify16 3monocypher ,
.Xr crypto_verify32 3monocypher ,
or
.Xr crypto_verify64 3monocypher
to compare MACs created this way.
Choose the size of the hash accordingly.
Users may want to wipe the key with
.Xr crypto_wipe 3monocypher
once they are done with it.
.It Fa key_size
Length of
.Fa key ,
in bytes.
Must be between 0 and 64.
32 is a good default.
.It Fa message
The message to hash.
May overlap with
.Fa hash .
May be
.Dv NULL
if
.Fa message_size
is 0.
.It Fa message_size
Length of
.Fa message ,
in bytes.
.El
.Ss Direct interface
The direct interface has two functions,
.Fn crypto_blake2b
and
.Fn crypto_blake2b_general .
.Fn crypto_blake2b
is provided for convenience, and is equivalent to calling
.Fn crypto_blake2b_general
with no key and a 64-byte hash.
.Pp
.Fn crypto_blake2b_general
users can specify the size of the hash, and use a secret key to
make the hash unpredictable \(en useful for message authentication
codes.
Even when using a key, you do not have to wipe the context struct with
.Xr crypto_wipe 3monocypher .
.Ss Incremental interface
The incremental interface is useful for handling streams of data or
large files without using too much memory.
This interface uses three steps:
.Bl -bullet
.It
initialisation with
.Fn crypto_blake2b_general_init
or
.Fn crypto_blake2b_init ,
which sets up a context with the hashing parameters;
.It
update with
.Fn crypto_blake2b_update ,
which hashes the message chunk by chunk, and keep the intermediary
result in the context;
.It
and finalisation with
.Fn crypto_blake2b_final ,
which produces the final hash.
The
.Ft crypto_blake2b_ctx
is automatically wiped upon finalisation.
.El
.Pp
The invariants of the parameters are the same as for
.Fn crypto_blake2b_general .
.Fn crypto_blake2b_init
is a convenience initialisation function that
specifies a 64-byte hash and no key.
This is considered a good default.
.Sh RETURN VALUES
These functions return nothing.
.Sh EXAMPLES
The following examples assume 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
Hashing a message all at once:
.Bd -literal -offset indent
uint8_t hash   [64]; /* Output hash (64 bytes)          */
uint8_t message[12] = "Lorem ipsum"; /* Message to hash */
crypto_blake2b(hash, message, 12);
.Ed
.Pp
Computing a message authentication code all at once:
.Bd -literal -offset indent
uint8_t hash   [16];
uint8_t key    [32];
uint8_t message[11] = "Lorem ipsu"; /* Message to authenticate */
arc4random_buf(key, 32);
crypto_blake2b_general(hash, 16, key, 32, message, 11);
/* Wipe secrets if they are no longer needed */
crypto_wipe(message, 11);
crypto_wipe(key, 32);
.Ed
.Pp
Hashing a message incrementally (without a key):
.Bd -literal -offset indent
uint8_t hash   [ 64]; /* Output hash (64 bytes) */
uint8_t message[500] = {1}; /* Message to hash  */
crypto_blake2b_ctx ctx;
crypto_blake2b_init(&ctx);
for (size_t i = 0; i < 500; i += 100) {
    crypto_blake2b_update(&ctx, message + i, 100);
}
crypto_blake2b_final(&ctx, hash);
.Ed
.Pp
Computing a message authentication code incrementally:
.Bd -literal -offset indent
uint8_t hash   [ 16];
uint8_t key    [ 32];
uint8_t message[500] = {1}; /* Message to authenticate         */
crypto_blake2b_ctx ctx;
arc4random_buf(key, 32);
crypto_blake2b_general_init(&ctx, 16, key, 32);
/* Wipe the key */
crypto_wipe(key, 32);
for (size_t i = 0; i < 500; i += 100) {
    crypto_blake2b_update(&ctx, message + i, 100);
    /* Wipe secrets if they are no longer needed */
    crypto_wipe(message + i, 100);
}
crypto_blake2b_final(&ctx, hash);
.Ed
.Sh SEE ALSO
.Xr crypto_key_exchange 3monocypher ,
.Xr crypto_lock 3monocypher ,
.Xr intro 3monocypher
.Sh STANDARDS
These functions implement BLAKE2b, described in RFC 7693.
.Sh HISTORY
The
.Fn crypto_blake2b ,
.Fn crypto_blake2b_general ,
.Fn crypto_blake2b_general_init ,
.Fn crypto_blake2b_init ,
.Fn crypto_blake2b_update ,
and
.Fn crypto_blake2b_final
functions first appeared in Monocypher 0.1.
.Sh CAVEATS
Monocypher does not perform any input validation.
Any deviation from the specified input and output length ranges results
in
.Sy undefined behaviour .
Make sure your inputs are correct.
.Sh SECURITY CONSIDERATIONS
BLAKE2b is a general-purpose cryptographic hash function;
this means that it is not suited for hashing passwords and deriving
cryptographic keys from passwords in particular.
While cryptographic keys usually have hundreds of bits of entropy,
passwords are often much less complex.
When storing passwords as hashes or when deriving keys from them,
the goal is normally to prevent attackers from quickly iterating all
possible passwords.
Because passwords tend to be simple,
it is important to artificially slow down attackers by using especially
computationally difficult hashing algorithms.
Monocypher therefore provides
.Xr crypto_argon2i 3monocypher
for password hashing and deriving keys from passwords.