.\" 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) 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 2019-2020 by 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_HMAC_SHA512 3MONOCYPHER
.Os
.Sh NAME
.Nm crypto_hmac_sha512 ,
.Nm crypto_hmac_sha512_init ,
.Nm crypto_hmac_sha512_update ,
.Nm crypto_hmac_sha512_final
.Nd cryptographic hash-based message authentication code with SHA-512
.Sh SYNOPSIS
.In monocypher-ed25519.h
.Ft void
.Fo crypto_hmac_sha512
.Fa "uint8_t hmac[64]"
.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_hmac_sha512_init
.Fa "crypto_hmac_sha512_ctx *ctx"
.Fa "const uint8_t *key"
.Fa "size_t key_size"
.Fc
.Ft void
.Fo crypto_hmac_sha512_update
.Fa "crypto_hmac_sha512_ctx *ctx"
.Fa "const uint8_t *message"
.Fa "size_t message_size"
.Fc
.Ft void
.Fo crypto_hmac_sha512_final
.Fa "crypto_hmac_sha512_ctx *ctx"
.Fa "uint8_t hmac[64]"
.Fc
.Sh DESCRIPTION
HMAC with SHA-512 is a cryptographically secure message authentication
code (MAC),
provided to enable compatibility with other cryptographic systems.
It is generally recommended to use
.Xr crypto_blake2b_general 3monocypher
instead,
as it performs faster on x86_64 CPUs.
.Pp
The arguments are:
.Bl -tag -width Ds
.It Fa hmac
The output MAC,
which is always 64 bytes long.
.It Fa key
Some secret key.
One cannot predict the final hash without it.
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.
32 is a good default.
Keys longer than 128 bytes will be reduced to 64 bytes by hashing
the key with SHA-512.
.It Fa message
The message to compute the HMAC for.
May overlap with
.Fa hmac .
May be
.Dv NULL
if
.Fa message_size
is 0.
.It Fa message_size
Length of
.Fa message ,
in bytes.
.El
.Pp
An incremental interface is provided.
It 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_hmac_sha512_init ,
which sets up a context with the hashing parameters;
.It
update with
.Fn crypto_hmac_sha512_update ,
which hashes the message chunk by chunk, and keep the intermediary
result in the context;
.It
and finalisation with
.Fn crypto_hmac_sha512_final ,
which produces the final hash.
The
.Ft crypto_hmac_sha512_ctx
is automatically wiped upon finalisation.
.El
.Pp
.Fn crypto_hmac_sha512
is a convenience function that
performs
.Fn crypto_hmac_sha512_init ,
.Fn crypto_hmac_sha512_update ,
and
.Fn crypto_hmac_sha512_final .
.Pp
MACs may be truncated safely down to at most 16 bytes;
the
.Xr crypto_verify64 3monocypher ,
.Xr crypto_verify32 3monocypher ,
and
.Xr crypto_verify16 3monocypher
functions can be used to to compare (possibly truncated) MACs.
.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
Computing a message authentication code all at once:
.Bd -literal -offset indent
uint8_t hash   [64]; /* Output hash  (between 1 and 64 bytes)  */
uint8_t key    [32]; /* Key          (at least 1 byte)         */
uint8_t message[10] = "Lorem ipsu"; /* Message to authenticate */
arc4random_buf(key, 32);
crypto_hmac_sha512(hash, key, 32, message, 500);
/* Wipe secrets if they are no longer needed */
crypto_wipe(message, 500);
crypto_wipe(key, 32);
.Ed
.Pp
Computing a message authentication code incrementally:
.Bd -literal -offset indent
uint8_t hash   [64]; /* Output hash  (between 1 and 64 bytes)  */
uint8_t key    [32]; /* Key          (at least 1 byte)         */
uint8_t message[500] = {1}; /* Message to authenticate         */
crypto_hmac_sha512_ctx ctx;
arc4random_buf(key, 32);
crypto_hmac_sha512_init(&ctx, key, 32);
/* Wipe the key */
crypto_wipe(key, 32);
for (size_t i = 0; i < 500; i += 100) {
    crypto_hmac_sha512_update(&ctx, message + i, 100);
    /* Wipe secrets if they are no longer needed */
    crypto_wipe(message + i, 100);
}
crypto_hmac_sha512_final(&ctx, hash);
.Ed
.Sh SEE ALSO
.Xr crypto_blake2b 3monocypher ,
.Xr crypto_lock 3monocypher ,
.Xr crypto_poly1305 3monocypher ,
.Xr crypto_sha512 3monocypher ,
.Xr intro 3monocypher
.Sh STANDARDS
These functions implement HMAC with SHA-512.
HMAC and SHA-512 itself are described in RFC 6234;
SHA-512 is also described in the Federal Information Processing Standard
(FIPS) 180-4;
HMAC is also described in FIPS 198-1.
.Sh HISTORY
The
.Fn crypto_hmac_sha512 ,
.Fn crypto_hmac_sha512_init ,
.Fn crypto_hmac_sha512_update ,
and
.Fn crypto_hmac_sha512_final
functions first appeared in Monocypher 3.0.0.