186 lines
6.4 KiB
Plaintext
186 lines
6.4 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-2018 Michael Savage
|
||
|
|
.\" Copyright (c) 2017, 2019-2020 Fabio Scotoni
|
||
|
|
.\" Copyright (c) 2020 Richard Walmsley
|
||
|
|
.\" 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-2020 by Loup Vaillant, Michael Savage, Fabio Scotoni and
|
||
|
|
.\" Richard Walmsley
|
||
|
|
.\"
|
||
|
|
.\" 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 31, 2020
|
||
|
|
.Dt CRYPTO_KEY_EXCHANGE 3MONOCYPHER
|
||
|
|
.Os
|
||
|
|
.Sh NAME
|
||
|
|
.Nm crypto_key_exchange ,
|
||
|
|
.Nm crypto_key_exchange_public_key
|
||
|
|
.Nd Elliptic Curve Diffie-Hellman key exchange
|
||
|
|
.Sh SYNOPSIS
|
||
|
|
.In monocypher.h
|
||
|
|
.Ft void
|
||
|
|
.Fo crypto_key_exchange
|
||
|
|
.Fa "uint8_t shared_key[32]"
|
||
|
|
.Fa "const uint8_t your_secret_key[32]"
|
||
|
|
.Fa "const uint8_t their_public_key[32]"
|
||
|
|
.Fc
|
||
|
|
.Ft void
|
||
|
|
.Fo crypto_key_exchange_public_key
|
||
|
|
.Fa "uint8_t your_public_key[32]"
|
||
|
|
.Fa "const uint8_t your_secret_key[32]"
|
||
|
|
.Fc
|
||
|
|
.Sh DESCRIPTION
|
||
|
|
.Fn crypto_key_exchange
|
||
|
|
computes a shared key with your secret key and their public key.
|
||
|
|
.Pp
|
||
|
|
.Fn crypto_key_exchange_public_key
|
||
|
|
deterministically computes the public key from a random secret key.
|
||
|
|
.Pp
|
||
|
|
The arguments are:
|
||
|
|
.Bl -tag -width Ds
|
||
|
|
.It Fa shared_key
|
||
|
|
The shared secret, known only to those who know a relevant secret key
|
||
|
|
(yours or theirs).
|
||
|
|
It is cryptographically random, and suitable for use with the
|
||
|
|
.Xr crypto_lock 3monocypher
|
||
|
|
family of functions.
|
||
|
|
.It Fa your_secret_key
|
||
|
|
A 32-byte random number, known only to you.
|
||
|
|
See
|
||
|
|
.Xr intro 3monocypher
|
||
|
|
for advice about generating random bytes (use the operating system's
|
||
|
|
random number generator).
|
||
|
|
.It Fa their_public_key
|
||
|
|
The public key of the other party.
|
||
|
|
.It Fa your_public_key
|
||
|
|
Your public key, generated from
|
||
|
|
.Fa your_secret_key
|
||
|
|
with
|
||
|
|
.Fn crypto_key_exchange_public_key .
|
||
|
|
.El
|
||
|
|
.Pp
|
||
|
|
.Fa shared_key
|
||
|
|
and
|
||
|
|
.Fa your_secret_key
|
||
|
|
may overlap if the secret is no longer required.
|
||
|
|
.Pp
|
||
|
|
Some poorly designed protocols require to test for
|
||
|
|
.Dq contributory
|
||
|
|
behaviour, which ensures that no untrusted party forces the shared
|
||
|
|
secret to a known constant.
|
||
|
|
Protocols should instead be designed in such a way that no such check
|
||
|
|
is necessary, namely by authenticating the other party or exchanging
|
||
|
|
keys over a trusted channel.
|
||
|
|
.Pp
|
||
|
|
Do not use the same secret key for both key exchanges and signatures.
|
||
|
|
The public keys are different, and revealing both may leak information.
|
||
|
|
If there really is no room to store or derive two different secret keys,
|
||
|
|
consider generating a key pair for signatures and then converting it
|
||
|
|
with
|
||
|
|
.Xr crypto_from_eddsa_private 3monocypher
|
||
|
|
and
|
||
|
|
.Xr crypto_from_eddsa_public 3monocypher .
|
||
|
|
.Sh RETURN VALUES
|
||
|
|
.Fn crypto_key_exchange
|
||
|
|
and
|
||
|
|
.Fn crypto_key_exchange_public_key
|
||
|
|
return nothing.
|
||
|
|
.Sh EXAMPLES
|
||
|
|
The following examples assume the existence of
|
||
|
|
.Fn arc4random_buf ,
|
||
|
|
which fills the given buffer with cryptographically secure random bytes.
|
||
|
|
If
|
||
|
|
.Fn arc4random_buf
|
||
|
|
does not exist on your system, see
|
||
|
|
.Xr intro 3monocypher
|
||
|
|
for advice about how to generate cryptographically secure random bytes.
|
||
|
|
.Pp
|
||
|
|
Generate a public key from a randomly generated secret key:
|
||
|
|
.Bd -literal -offset indent
|
||
|
|
uint8_t sk[32]; /* Random secret key */
|
||
|
|
uint8_t pk[32]; /* Public key */
|
||
|
|
arc4random_buf(sk, 32);
|
||
|
|
crypto_key_exchange_public_key(pk, sk);
|
||
|
|
/* Wipe secrets if they are no longer needed */
|
||
|
|
crypto_wipe(sk, 32);
|
||
|
|
.Ed
|
||
|
|
.Pp
|
||
|
|
Generate a shared, symmetric key with your secret key and their public
|
||
|
|
key.
|
||
|
|
(The other party will generate the same shared key with your public
|
||
|
|
key and their secret key.)
|
||
|
|
.Bd -literal -offset indent
|
||
|
|
const uint8_t their_pk [32]; /* Their public key */
|
||
|
|
uint8_t your_sk [32]; /* Your secret key */
|
||
|
|
uint8_t shared_key[32]; /* Shared session key */
|
||
|
|
crypto_key_exchange(shared_key, your_sk, their_pk);
|
||
|
|
/* Wipe secrets if they are no longer needed */
|
||
|
|
crypto_wipe(your_sk, 32);
|
||
|
|
.Ed
|
||
|
|
.Sh SEE ALSO
|
||
|
|
.Xr crypto_lock 3monocypher ,
|
||
|
|
.Xr intro 3monocypher
|
||
|
|
.Sh STANDARDS
|
||
|
|
These functions implement X25519, described in RFC 7748.
|
||
|
|
.Fn crypto_key_exchange
|
||
|
|
uses HChacha20 as well.
|
||
|
|
.Sh HISTORY
|
||
|
|
The
|
||
|
|
.Fn crypto_key_exchange
|
||
|
|
function first appeared in Monocypher 0.2.
|
||
|
|
The
|
||
|
|
.Fn crypto_key_exchange_public_key
|
||
|
|
macro alias first appeared in Monocypher 1.1.0.
|
||
|
|
.Sh SECURITY CONSIDERATIONS
|
||
|
|
If either of the long term secret keys leaks, it may compromise
|
||
|
|
.Em all past messages .
|
||
|
|
This can be avoided by using protocols that provide forward secrecy,
|
||
|
|
such as the X3DH key agreement protocol.
|
||
|
|
.Sh IMPLEMENTATION DETAILS
|
||
|
|
.Fn crypto_key_exchange_public_key
|
||
|
|
is an alias to
|
||
|
|
.Xr crypto_x25519_public_key 3monocypher .
|