.\" 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) 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 2020 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 March 24, 2020
.Dt CRYPTO_X25519_DIRTY_FAST 3monocypher
.Os
.Sh NAME
.Nm crypto_x25519_dirty_fast ,
.Nm crypto_x25519_dirty_small
.Nd generation of Curve25519 points with a low-order component
.Sh SYNOPSIS
.In monocypher.h
.Ft void
.Fo crypto_x25519_dirty_fast
.Fa "uint8_t pk[32]"
.Fa "const uint8_t sk[32]"
.Fc
.Ft void
.Fo crypto_x25519_dirty_small
.Fa "uint8_t pk[32]"
.Fa "const uint8_t sk[32]"
.Fc
.Sh DESCRIPTION
These functions are used in public key generation for
.Xr crypto_curve_to_hidden 3monocypher .
.Sy This is a highly advanced feature ;
unless you are reading this because you were referred here from
.Xr crypto_curve_to_hidden 3monocypher ,
.Sy you likely have no reason to be using these functions
and are probably looking for
.Xr crypto_key_exchange 3monocypher
or
.Xr crypto_x25519 3monocypher
instead.
Expect elliptic curve jargon on this page.
.Pp
Both functions generate a Curve25519 public key
.Fa pk
from the given secret key
.Fa sk ;
the public keys are on the
.Em whole
curve, rather than just the main prime-order subgroup.
Both do the same with different code size and memory characteristics:
.Fn crypto_x25519_dirty_fast
uses multiple large temporary variables and uses functions that are
normally used internally for
.Xr crypto_sign 3monocypher ;
accordingly, it uses both more memory (for the temporary variables) and
more code size (unless the signing code is already compiled in
elsewhere).
.Fn crypto_x25519_dirty_small
yields the same result, but does so using less code and memory at a
large performance penalty compared to
.Fn crypto_x25519_dirty_fast .
.Pp
The resulting public keys are to be used with
.Xr crypto_x25519 3monocypher
or
.Xr crypto_key_exchange 3monocypher ,
which clear the cofactor.
.Sh RETURN VALUES
These functions have no return value.
They cannot fail.
.Sh SEE ALSO
.Xr crypto_curve_to_hidden 3monocypher ,
.Xr crypto_key_exchange_public_key 3monocypher ,
.Xr crypto_x25519_public_key 3monocypher ,
.Xr intro 3monocypher
.Sh HISTORY
The
.Fn crypto_x25519_dirty_fast
and
.Fn crypto_x25519_dirty_small
functions first appeared in Monocypher 3.1.0.
.Sh IMPLEMENTATION DETAILS
The slow variant is approximately an entire two times slower than the
fast variant.
When considering that, on average, two calls to this function will be
required for obtaining a valid key pair for
.Xr crypto_curve_to_hidden 3monocypher ,
this adds up to an
.Em average
effective slowdown for key pair generation of a factor of four.
