aboutsummaryrefslogtreecommitdiff
path: root/vendor/doc/html/crypto_key_exchange_public_key.html
blob: dd5a314f8a432702a1d5b2006efee95804263b89 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8"/>
  <style>
    table.head, table.foot { width: 100%; }
    td.head-rtitle, td.foot-os { text-align: right; }
    td.head-vol { text-align: center; }
    div.Pp { margin: 1ex 0ex; }
  </style>
  <link rel="stylesheet" href="style.css" type="text/css" media="all"/>
  <title>CRYPTO_KEY_EXCHANGE(3MONOCYPHER)</title>
</head>
<body>
<table class="head">
  <tr>
    <td class="head-ltitle">CRYPTO_KEY_EXCHANGE(3MONOCYPHER)</td>
    <td class="head-vol">3MONOCYPHER</td>
    <td class="head-rtitle">CRYPTO_KEY_EXCHANGE(3MONOCYPHER)</td>
  </tr>
</table>
<div class="manual-text">
<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1>
<b class="Nm" title="Nm">crypto_key_exchange</b>,
  <b class="Nm" title="Nm">crypto_key_exchange_public_key</b> &#x2014;
  <span class="Nd" title="Nd">Elliptic Curve Diffie-Hellman key exchange</span>
<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<b class="In" title="In">#include
  &lt;<a class="In" title="In">monocypher.h</a>&gt;</b>
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_key_exchange</b>(<var class="Fa" title="Fa">uint8_t
  shared_key[32]</var>, <var class="Fa" title="Fa">const uint8_t
  your_secret_key[32]</var>, <var class="Fa" title="Fa">const uint8_t
  their_public_key[32]</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_key_exchange_public_key</b>(<var class="Fa" title="Fa">uint8_t
  your_public_key[32]</var>, <var class="Fa" title="Fa">const uint8_t
  your_secret_key[32]</var>);
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<b class="Fn" title="Fn">crypto_key_exchange</b>() computes a shared key with
  your secret key and their public key.
<div class="Pp"></div>
<b class="Fn" title="Fn">crypto_key_exchange_public_key</b>() deterministically
  computes the public key from a random secret key.
<div class="Pp"></div>
The arguments are:
<dl class="Bl-tag">
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">shared_key</var></dt>
  <dd class="It-tag">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
      <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>
      family of functions.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">your_secret_key</var></dt>
  <dd class="It-tag">A 32-byte random number, known only to you. See
      <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for
      advice about generating random bytes (use the operating system's random
      number generator).</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">their_public_key</var></dt>
  <dd class="It-tag">The public key of the other party.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">your_public_key</var></dt>
  <dd class="It-tag">Your public key, generated from
      <var class="Fa" title="Fa">your_secret_key</var> with
      <b class="Fn" title="Fn">crypto_key_exchange_public_key</b>().</dd>
</dl>
<div class="Pp"></div>
<var class="Fa" title="Fa">shared_key</var> and
  <var class="Fa" title="Fa">your_secret_key</var> may overlap if the secret is
  no longer required.
<div class="Pp"></div>
Some poorly designed protocols require to test for &#x201C;contributory&#x201D;
  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.
<div class="Pp"></div>
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
  <a class="Xr" title="Xr" href="crypto_from_eddsa_private.html">crypto_from_eddsa_private(3monocypher)</a>
  and
  <a class="Xr" title="Xr" href="crypto_from_eddsa_public.html">crypto_from_eddsa_public(3monocypher)</a>.
<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN
  VALUES</a></h1>
<b class="Fn" title="Fn">crypto_key_exchange</b>() and
  <b class="Fn" title="Fn">crypto_key_exchange_public_key</b>() return nothing.
<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1>
The following examples assume the existence of
  <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer
  with cryptographically secure random bytes. If
  <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system,
  see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for
  advice about how to generate cryptographically secure random bytes.
<div class="Pp"></div>
Generate a public key from a randomly generated secret key:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
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);
</pre>
</div>
<div class="Pp"></div>
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.)
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
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);
</pre>
</div>
<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE
  ALSO</a></h1>
<a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>,
  <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a>
<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1>
These functions implement X25519, described in RFC 7748.
  <b class="Fn" title="Fn">crypto_key_exchange</b>() uses HChacha20 as well.
<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
The <b class="Fn" title="Fn">crypto_key_exchange</b>() function first appeared
  in Monocypher 0.2. The
  <b class="Fn" title="Fn">crypto_key_exchange_public_key</b>() macro alias
  first appeared in Monocypher 1.1.0.
<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY
  CONSIDERATIONS</a></h1>
If either of the long term secret keys leaks, it may compromise
  <i class="Em" title="Em">all past messages</i>. This can be avoided by using
  protocols that provide forward secrecy, such as the X3DH key agreement
  protocol.
<h1 class="Sh" title="Sh" id="IMPLEMENTATION_DETAILS"><a class="selflink" href="#IMPLEMENTATION_DETAILS">IMPLEMENTATION
  DETAILS</a></h1>
<b class="Fn" title="Fn">crypto_key_exchange_public_key</b>() is an alias to
  <a class="Xr" title="Xr" href="crypto_x25519_public_key.html">crypto_x25519_public_key(3monocypher)</a>.</div>
<table class="foot">
  <tr>
    <td class="foot-date">March 31, 2020</td>
    <td class="foot-os">Linux 4.15.0-106-generic</td>
  </tr>
</table>
</body>
</html>