.\" 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 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_LOCK_INIT 3MONOCYPHER
.Os
.Sh NAME
.Nm crypto_lock_init ,
.Nm crypto_lock_auth_ad ,
.Nm crypto_lock_auth_message ,
.Nm crypto_lock_update ,
.Nm crypto_lock_final ,
.Nm crypto_unlock_init ,
.Nm crypto_unlock_auth_ad ,
.Nm crypto_unlock_auth_message ,
.Nm crypto_unlock_update ,
.Nm crypto_unlock_final
.Nd incremental authenticated encryption with additional data
.Sh SYNOPSIS
.In monocypher.h
.Ft void
.Fo crypto_lock_init
.Fa "crypto_lock_ctx *ctx"
.Fa "const uint8_t key[32]"
.Fa "const uint8_t nonce[24]"
.Fc
.Ft void
.Fo crypto_lock_auth_ad
.Fa "crypto_lock_ctx *ctx"
.Fa "const uint8_t *ad"
.Fa "size_t ad_size"
.Fc
.Ft void
.Fo crypto_lock_auth_message
.Fa "crypto_lock_ctx *ctx"
.Fa "const uint8_t *plain_text"
.Fa "size_t text_size"
.Fc
.Ft void
.Fo crypto_lock_update
.Fa "crypto_lock_ctx *ctx"
.Fa "uint8_t *cipher_text"
.Fa "const uint8_t *plain_text"
.Fa "size_t text_size"
.Fc
.Ft void
.Fo crypto_lock_final
.Fa "crypto_lock_ctx *ctx"
.Fa "uint8_t mac[16]"
.Fc
.Ft void
.Fo crypto_unlock_init
.Fa "crypto_unlock_ctx *ctx"
.Fa "const uint8_t key[32]"
.Fa "const uint8_t nonce[24]"
.Fc
.Ft void
.Fo crypto_unlock_auth_ad
.Fa "crypto_unlock_ctx *ctx"
.Fa "const uint8_t *ad"
.Fa "size_t ad_size"
.Fc
.Ft void
.Fo crypto_unlock_auth_message
.Fa "crypto_unlock_ctx *ctx"
.Fa "const uint8_t *plain_text"
.Fa "size_t text_size"
.Fc
.Ft void
.Fo crypto_unlock_update
.Fa "crypto_unlock_ctx *ctx"
.Fa "uint8_t *plain_text"
.Fa "const uint8_t *cipher_text"
.Fa "size_t text_size"
.Fc
.Ft int
.Fo crypto_unlock_final
.Fa "crypto_unlock_ctx *ctx"
.Fa "const uint8_t mac[16]"
.Fc
.Sh DESCRIPTION
These functions were variants of
.Xr crypto_lock 3monocypher ,
.Xr crypto_unlock 3monocypher ,
.Xr crypto_lock_aead 3monocypher
and
.Xr crypto_unlock_aead 3monocypher .
They are deprecated in favor of
those simpler functions.
.Pp
Change your protocol so that it does not rely on the removed functions,
namely by splitting the data into chunks that you can individually use
.Xr crypto_lock 3monocypher
and
.Xr crypto_unlock 3monocypher
on.
.Pp
For files in particular,
you may alternatively (and suboptimally)
attempt to use
.Fn mmap
(on *NIX)
or
.Fn MapViewOfFile
(on Windows)
and pass the files as mapped memory into
.Xr crypto_lock 3monocypher
and
.Xr crypto_unlock 3monocypher
instead.
.El
.Sh RETURN VALUES
.Fn crypto_lock_init ,
.Fn crypto_unlock_init ,
.Fn crypto_lock_auth_ad ,
.Fn crypto_unlock_auth_ad ,
.Fn crypto_lock_auth_message ,
.Fn crypto_unlock_auth_message ,
.Fn crypto_lock_update ,
.Fn crypto_unlock_update ,
and
.Fn crypto_lock_final
return nothing.
.Pp
.Fn crypto_unlock_final
returns 0 on success or -1 if the message was corrupted.
Corruption can be caused by transmission errors, programmer error, or an
attacker's interference.
.Em Always check the return value .
.Sh SEE ALSO
.Xr crypto_key_exchange 3monocypher ,
.Xr crypto_lock 3monocypher ,
.Xr crypto_lock_aead 3monocypher ,
.Xr crypto_unlock 3monocypher ,
.Xr crypto_unlock_aead 3monocypher ,
.Xr crypto_wipe 3monocypher ,
.Xr intro 3monocypher
.Sh HISTORY
The
.Fn crypto_lock_init ,
.Fn crypto_lock_auth_ad ,
.Fn crypto_lock_auth_message ,
.Fn crypto_lock_update ,
.Fn crypto_lock_final ,
.Fn crypto_unlock_init ,
.Fn crypto_unlock_auth_ad ,
.Fn crypto_unlock_auth_message ,
.Fn crypto_unlock_update ,
and
.Fn crypto_unlock_final
functions first appeared in Monocypher 1.1.0.
.Fn crypto_lock_aead_auth
and
.Fn crypto_unlock_aead_auth
were renamed to
.Fn crypto_lock_auth_ad
and
.Fn crypto_unlock_auth_ad
respectively in Monocypher 2.0.0.
They were deprecated in Monocypher 3.0.0
and will be removed in Monocypher 4.0.0.
