spot-the-bug/stream-ciphers/monocypher-3.1.1/doc/man/man3/crypto_chacha20_encrypt.3monocypher

.\" 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) 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 2019 by 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 2, 2019
.Dt CRYPTO_CHACHA20_ENCRYPT 3MONOCYPHER
.Os
.Sh NAME
.Nm crypto_chacha20_encrypt ,
.Nm crypto_chacha20_init ,
.Nm crypto_chacha20_x_init ,
.Nm crypto_chacha20_stream ,
.Nm crypto_chacha20_set_ctr
.Nd deprecated Chacha20 and XChacha20 encryption functions
.Sh SYNOPSIS
.In monocypher.h
.Ft void
.Fo crypto_chacha20_init
.Fa "crypto_chacha_ctx *ctx"
.Fa "const uint8_t key[32]"
.Fa "const uint8_t nonce[8]"
.Fc
.Ft void
.Fo crypto_chacha20_x_init
.Fa "crypto_chacha_ctx *ctx"
.Fa "const uint8_t key[32]"
.Fa "const uint8_t nonce[24]"
.Fc
.Ft void
.Fo crypto_chacha20_encrypt
.Fa "crypto_chacha_ctx *ctx"
.Fa "uint8_t *cipher_text"
.Fa "const uint8_t *plain_text"
.Fa "size_t text_size"
.Fc
.Ft void
.Fo crypto_chacha20_stream
.Fa "crypto_chacha_ctx *ctx"
.Fa "uint8_t *stream"
.Fa "size_t stream_size"
.Fc
.Ft void
.Fo crypto_chacha20_set_ctr
.Fa "crypto_chacha_ctx *ctx"
.Fa "uint64_t ctr"
.Fc
.Sh DESCRIPTION
These functions provided an incremental interface for the Chacha20
cipher.
They are deprecated in favor of
.Xr crypto_chacha20 3monocypher ,
.Xr crypto_chacha20_ctr 3monocypher ,
.Xr crypto_xchacha20 3monocypher , and
.Xr crypto_xchacha20_ctr 3monocypher .
.Pp
For encryption, you can achieve an identical effect
as the deprecated functions by using
.Xr crypto_chacha20_ctr 3monocypher
or
.Xr crypto_xchacha20_ctr 3monocypher .
Care needs to be taken with regards to handling the counter value
when migrating old code to use the new functions.
The new functions
.Em always return next counter value .
This means that input ciphertexts or plaintexts
whose lengths are not exactly multiples of 64 bytes
advance the counter, even though there is theoretically some space left
in a Chacha20 block.
New applications should design their code so that either
the protocl is not reliant on the counter covering the entire text
(e.g. by cutting input into independent chunks) or
inputs are always such that their lengths are multiples of 64 bytes
(e.g. by buffering input until 64 bytes have been obtained).
.Pp
To obtain the raw Chacha20 stream previously provided by
.Fn crypto_chacha20_stream ,
pass
.Dv NULL
to 
.Xr crypto_chacha20
as plaintext.
.Sh RETURN VALUES
These functions return nothing.
.Sh SEE ALSO
.Xr crypto_chacha20 3monocypher ,
.Xr crypto_chacha20_ctr 3monocypher ,
.Xr crypto_xchacha20 3monocypher ,
.Xr crypto_xchacha20_ctr 3monocypher ,
.Xr crypto_lock 3monocypher ,
.Xr crypto_wipe 3monocypher ,
.Xr intro 3monocypher
.Sh HISTORY
The
.Fn crypto_chacha20_encrypt ,
.Fn crypto_chacha20_init ,
functions first appeared in Monocypher 0.1.
.Fn crypto_chacha20_stream
was added in Monocypher 0.2.
.Fn crypto_chacha20_x_init
and
.Fn crypto_chacha20_set_ctr
were added in Monocypher 1.0.
They were deprecated in Monocypher 3.0.0
and will be removed in Monocypher 4.0.0.