211 lines
6.0 KiB
Plaintext
211 lines
6.0 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 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.
|