.\" 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 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-2019 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 December 12, 2019
.Dt CRYPTO_WIPE 3MONOCYPHER
.Os
.Sh NAME
.Nm crypto_wipe
.Nd wipe data from memory
.Sh SYNOPSIS
.In monocypher.h
.Ft void
.Fo crypto_wipe
.Fa "void *secret"
.Fa "size_t secret_size"
.Fc
.Sh DESCRIPTION
.Fn crypto_wipe
securely erases sensitive data in memory.
.Pp
Sensitive data (such as cryptographic keys or secret plaintexts) should
be erased from memory as early as possible to minimise the window in
which it can be leaked.
Standard functions like memset and bzero are not safe to use as the
compiler may decide they have no effect and optimise them out.
.Pp
The arguments are:
.Bl -tag -width Ds
.It Fa secret
The buffer to erase.
.It Fa secret_size
The number of bytes to erase from the buffer.
This is normally the size of the entire buffer.
.El
.Pp
Monocypher will wipe its context structs when finalizing an operation
such as signing or decrypting.
When using direct interfaces like
.Xr crypto_aead_lock 3monocypher ,
these context structs are invisible to you.
However, they are exposed in incremental interfaces like
.Xr crypto_blake2b_init 3monocypher .
The original key buffer does not get automatically wiped.
When using incremental interfaces, you may want to wipe the original key
buffers immediately after calling the respective init function.
.Pp
Using
.Fn crypto_wipe
alone may not be enough for security.
It is recommended to lock down relevant memory regions as well.
Refer to
.Xr intro 3monocypher
for instructions on how to lock down memory on common operating systems.
.Sh RETURN VALUES
This function returns nothing.
.Sh SEE ALSO
.Xr intro 3monocypher
.Sh HISTORY
The
.Fn crypto_wipe
function first appeared in Monocypher 1.1.0.
.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.
