313 lines
9.4 KiB
Plaintext
313 lines
9.4 KiB
Plaintext
.\" 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.
|