127 lines
4.3 KiB
Plaintext
127 lines
4.3 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) 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_VERIFY16 3MONOCYPHER
|
||
|
|
.Os
|
||
|
|
.Sh NAME
|
||
|
|
.Nm crypto_verify16 ,
|
||
|
|
.Nm crypto_verify32 ,
|
||
|
|
.Nm crypto_verify64
|
||
|
|
.Nd timing-safe data comparison
|
||
|
|
.Sh SYNOPSIS
|
||
|
|
.In monocypher.h
|
||
|
|
.Ft int
|
||
|
|
.Fo crypto_verify16
|
||
|
|
.Fa "const uint8_t a[16]"
|
||
|
|
.Fa "const uint8_t b[16]"
|
||
|
|
.Fc
|
||
|
|
.Ft int
|
||
|
|
.Fo crypto_verify32
|
||
|
|
.Fa "const uint8_t a[32]"
|
||
|
|
.Fa "const uint8_t b[32]"
|
||
|
|
.Fc
|
||
|
|
.Ft int
|
||
|
|
.Fo crypto_verify64
|
||
|
|
.Fa "const uint8_t a[64]"
|
||
|
|
.Fa "const uint8_t b[64]"
|
||
|
|
.Fc
|
||
|
|
.Sh DESCRIPTION
|
||
|
|
Cryptographic operations often require comparison of secrets or values
|
||
|
|
derived from secrets.
|
||
|
|
Standard comparison functions like
|
||
|
|
.Fn memcmp
|
||
|
|
tend to exit when they find the first difference, leaking information
|
||
|
|
through timing differences.
|
||
|
|
.Pp
|
||
|
|
As an example, say a message authentication code (MAC) is sent over the
|
||
|
|
network along with a message, but the correct MAC is secret.
|
||
|
|
If the attacker attempts a forgery, one does not want to reveal
|
||
|
|
.Dq your MAC is wrong, Em and it took 384 microseconds to tell .
|
||
|
|
If the next attempt takes 462 microseconds instead, it tells the
|
||
|
|
attacker they just guessed a byte correctly.
|
||
|
|
That way, an attacker can derive the correct MAC byte by byte,
|
||
|
|
and successfully forge a message.
|
||
|
|
This has lead to practical attacks in the past.
|
||
|
|
.Pp
|
||
|
|
To avoid such catastrophic failure,
|
||
|
|
.Fn crypto_verify16 ,
|
||
|
|
.Fn crypto_verify32
|
||
|
|
and
|
||
|
|
.Fn crypto_verify64
|
||
|
|
provide comparison functions whose timing is independent from
|
||
|
|
the content of their input.
|
||
|
|
They compare the first
|
||
|
|
16, 32, or 64 bytes of the two byte arrays
|
||
|
|
.Fa a
|
||
|
|
and
|
||
|
|
.Fa b .
|
||
|
|
.Pp
|
||
|
|
When in doubt, prefer these functions over
|
||
|
|
.Fn memcmp .
|
||
|
|
.Sh RETURN VALUES
|
||
|
|
These functions return 0 if the two memory chunks are the same, -1
|
||
|
|
otherwise.
|
||
|
|
.Sh SEE ALSO
|
||
|
|
.Xr intro 3monocypher
|
||
|
|
.Sh HISTORY
|
||
|
|
The
|
||
|
|
.Fn crypto_verify16 ,
|
||
|
|
.Fn crypto_verify32 ,
|
||
|
|
.Fn crypto_verify64
|
||
|
|
functions first appeared in Monocypher 1.1.0.
|
||
|
|
They replaced the
|
||
|
|
.Fn crypto_memcmp
|
||
|
|
and
|
||
|
|
.Fn crypto_zerocmp
|
||
|
|
functions that were present until Monocypher 1.0.1.
|