.\" 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) 2017, 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 31, 2020
.Dt CRYPTO_SIGN_INIT_FIRST_PASS 3MONOCYPHER
.Os
.Sh NAME
.Nm crypto_sign_init_first_pass ,
.Nm crypto_sign_update ,
.Nm crypto_sign_final ,
.Nm crypto_sign_init_second_pass ,
.Nm crypto_check_init ,
.Nm crypto_check_update ,
.Nm crypto_check_final
.Nd incremental public key signatures
.Sh SYNOPSIS
.In monocypher.h
.Ft void
.Fo crypto_sign_init_first_pass
.Fa "crypto_sign_ctx *ctx"
.Fa "const uint8_t secret_key[32]"
.Fa "const uint8_t public_key[32]"
.Fc
.Ft void
.Fo crypto_sign_update
.Fa "crypto_sign_ctx *ctx"
.Fa "const uint8_t *message"
.Fa "size_t message_size"
.Fc
.Ft void
.Fo crypto_sign_final
.Fa "crypto_sign_ctx *ctx"
.Fa "uint8_t signature[64]"
.Fc
.Ft void
.Fo crypto_sign_init_second_pass
.Fa "crypto_sign_ctx *ctx"
.Fc
.Ft void
.Fo crypto_check_init
.Fa "crypto_check_ctx *ctx"
.Fa "const uint8_t signature[64]"
.Fa "const uint8_t public_key[32]"
.Fc
.Ft void
.Fo crypto_check_update
.Fa "crypto_check_ctx *ctx"
.Fa "const uint8_t *message"
.Fa "size_t message_size"
.Fc
.Ft int
.Fo crypto_check_final
.Fa "crypto_check_ctx *ctx"
.Fc
.Sh DESCRIPTION
These functions are variants of
.Xr crypto_sign 3monocypher
and
.Xr crypto_check 3monocypher .
Prefer those simpler functions if possible.
.Pp
The arguments are the same as those described in
.Xr crypto_sign 3monocypher .
.Pp
This incremental interface can be used to sign or verify messages too
large to fit in a single buffer.
The arguments are the same as the direct interface described in
.Xr crypto_sign 3monocypher .
.Pp
The direct and incremental interface produce and accept the same
signatures.
.Pp
Signing is done in two passes.
This requires five steps:
.Bl -bullet
.It
Initialisation of the first pass with
.Fn crypto_sign_init_first_pass .
The public key is optional, and will be recomputed if not provided.
This recomputation doubles the execution time for short messages.
.It
The first pass proper, with
.Fn crypto_sign_update .
.Sy Under no circumstances must you forget the first pass :
Forgetting to call
.Fn crypto_sign_update
will appear to work in that it produces valid signatures,
but also
loses all security because attackers may now recover the secret key.
.It
Initialisation of the second pass with
.Fn crypto_sign_init_second_pass .
.It
The second pass proper, with
.Fn crypto_sign_update .
The same update function is used for both passes.
.It
Signature generation with
.Fn crypto_sign_final .
This also wipes the context.
.El
.Pp
Verification requires three steps:
.Bl -bullet
.It
Initialisation with
.Fn crypto_check_init .
.It
Update with
.Fn crypto_check_update .
.It
Signature verification with
.Fn crypto_check_final .
.El
.Sh RETURN VALUES
.Fn crypto_sign_init_first_pass ,
.Fn crypto_sign_init_second_pass ,
.Fn crypto_sign_update ,
.Fn crypto_sign_final ,
.Fn crypto_check_init
and
.Fn crypto_check_update
return nothing.
.Pp
.Fn crypto_check_final
returns 0 for legitimate messages and -1 for forgeries.
.Sh EXAMPLES
Sign a message:
.Bd -literal -offset indent
uint8_t       sk       [ 32]; /* Secret key            */
const uint8_t pk       [ 32]; /* Public key (optional) */
const uint8_t message  [500]; /* Message to sign       */
uint8_t       signature[ 64]; /* Output signature      */
crypto_sign_ctx ctx;
crypto_sign_init_first_pass((crypto_sign_ctx_abstract*)&ctx, sk, pk);
/* Wipe the secret key if no longer needed */
crypto_wipe(sk, 32);
for (size_t i = 0; i < 500; i += 100) {
    crypto_sign_update((crypto_sign_ctx_abstract*)&ctx, message + i, 100);
}
crypto_sign_init_second_pass((crypto_sign_ctx_abstract*)&ctx);
for (size_t i = 0; i < 500; i += 100) {
    crypto_sign_update((crypto_sign_ctx_abstract*)&ctx, message + i, 100);
}
crypto_sign_final((crypto_sign_ctx_abstract*)&ctx, signature);
.Ed
.Pp
Check the above:
.Bd -literal -offset indent
const uint8_t pk       [ 32]; /* Public key         */
const uint8_t message  [500]; /* Message to sign    */
const uint8_t signature[ 64]; /* Signature to check */
crypto_check_ctx ctx;
crypto_check_init((crypto_sign_ctx_abstract*)&ctx, signature, pk);
for (size_t i = 0; i < 500; i += 100) {
    crypto_check_update((crypto_sign_ctx_abstract*)&ctx, message + i, 100);
}
if (crypto_check_final((crypto_sign_ctx_abstract*)&ctx)) {
    /* Message is corrupted, abort processing */
} else {
    /* Message is genuine */
}
.Ed
.Pp
This interface can be used to mitigate attacks that leverage power
analysis and fault injection (glitching) \(en both of which require
physical access and appropriate equipment \(en by injecting additional
randomness (at least 32 bytes) and padding (to the hash function's block
size, which is 128 bytes for all hash functions supported by
Monocypher), of which 32 bytes are already inserted into the buffer by
.Fn crypto_sign_init_first_pass .
Access to a cryptographically secure pseudo-random generator is a
requirement for effective side channel mitigation.
Signing a message with increased power-related side channel mitigations:
.Bd -literal -offset indent
const uint8_t message  [   500]; /* Message to sign         */
uint8_t       sk       [    32]; /* Secret key              */
const uint8_t pk       [    32]; /* Public key (optional)   */
uint8_t       signature[    64]; /* Output signature        */
uint8_t       buf      [128-32] = {0}; /* Mitigation buffer */
crypto_sign_ctx ctx;
crypto_sign_ctx_abstract *actx = (crypto_sign_ctx_abstract *)&ctx;

arc4random_buf(buf, 32);
/* The rest of buf MUST be zeroes. */

crypto_sign_init_first_pass(actx, sk, pk);
crypto_sign_update         (actx, buf, sizeof(buf));
crypto_sign_update         (actx, message, 500);

crypto_sign_init_second_pass(actx);
crypto_sign_update          (actx, message, 500);
crypto_sign_final           (actx, signature);

crypto_wipe(buf, 32);
/* Wipe the secret key if no longer needed */
crypto_wipe(sk,  32);
.Ed
.Sh SEE ALSO
.Xr crypto_blake2b 3monocypher ,
.Xr crypto_key_exchange 3monocypher ,
.Xr crypto_lock 3monocypher ,
.Xr crypto_sign 3monocypher ,
.Xr crypto_wipe 3monocypher ,
.Xr intro 3monocypher
.Sh STANDARDS
These functions implement PureEdDSA with Curve25519 and Blake2b, as
described in RFC 8032.
This is the same as Ed25519, with Blake2b instead of SHA-512.
.Pp
The example for side channel mitigation follows the methodology outlined
in I-D.draft-mattsson-cfrg-det-sigs-with-noise-02.
.Sh HISTORY
The
.Fn crypto_sign_init_first_pass ,
.Fn crypto_sign_update ,
.Fn crypto_sign_final ,
.Fn crypto_sign_init_second_pass ,
.Fn crypto_check_init ,
.Fn crypto_check_update ,
and
.Fn crypto_check_final
functions first appeared in Monocypher 1.1.0.
.Pp
.Sy A critical security vulnerability
that caused all-zero signatures to be accepted was introduced in
Monocypher 0.3;
it was fixed in Monocypher 1.1.1 and 2.0.4.
.Sh SECURITY CONSIDERATIONS
Messages are not verified until the call to
.Fn crypto_check_final .
Messages may be stored before they are verified, but they cannot be
.Em trusted .
Processing untrusted messages increases the attack surface of the
system.
Doing so securely is hard.
Do not process messages before calling
.Fn crypto_check_final .
.Pp
When signing messages, the security considerations documented in
.Xr crypto_sign 3monocypher
also apply.
In particular, if power-related side channels are part of your threat
model,
note that there may still be other power-related side channels (such as
if the CPU leaks information when an operation overflows a register)
that must be considered.
.Sh IMPLEMENTATION DETAILS
EdDSA signatures require two passes that cannot be performed in
parallel.
There are ways around this limitation, but they all lower security in
some way.
For this reason, Monocypher does not support them.
