Skip to content

Commit ad4fac4

Browse files
author
blackshirt
committed
add docs
1 parent f3e7fc8 commit ad4fac4

File tree

3 files changed

+289
-23
lines changed

3 files changed

+289
-23
lines changed

‎.gitignore

+23-22
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,28 @@
1-
# These are some examples of commonly ignored file patterns.
2-
# You should customize this list as applicable to your project.
3-
# Learn more about .gitignore:
4-
# https://www.atlassian.com/git/tutorials/saving-changes/gitignore
1+
# Binaries for programs and plugins
2+
main
3+
tls13
4+
*.exe
5+
*.exe~
6+
*.so
7+
*.dylib
8+
*.dll
59

6-
# Node artifact files
7-
node_modules/
8-
dist/
9-
docs/
10-
_docs/
10+
# Ignore binary output folders
11+
bin/
1112

12-
# Generated by Windows
13-
Thumbs.db
13+
# Ignore common editor/system specific metadata
14+
.DS_Store
15+
.idea/
16+
.vscode/
17+
*.iml
1418

15-
# Applications
16-
*.app
17-
*.exe
18-
*.war
19+
# ENV
20+
.env
1921

20-
# Large media files
21-
*.mp4
22-
*.tiff
23-
*.avi
24-
*.flv
25-
*.mov
26-
*.wmv
22+
# vweb and database
23+
*.db
24+
*.js
2725

26+
# docs
27+
docs/
28+
_docs/

‎README.md

+263-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
# module curve25519
2+
3+
14
# curve25519
25
----------
36

@@ -14,4 +17,263 @@ the Elliptic Curve Diffie-Hellman (ECDH) key agreement key design scheme.
1417
## Installation
1518
```bash
1619
v install https://github.com/blackshirt/curve25519
17-
```
20+
```
21+
22+
## Contents
23+
- [Constants](#Constants)
24+
- [x25519](#x25519)
25+
- [Curve](#Curve)
26+
- [new_key_exchanger](#new_key_exchanger)
27+
- [KeyExchanger](#KeyExchanger)
28+
- [PublicKey](#PublicKey)
29+
- [equal](#equal)
30+
- [bytes](#bytes)
31+
- [PrivateKey](#PrivateKey)
32+
- [bytes](#bytes)
33+
- [equal](#equal)
34+
- [public_key](#public_key)
35+
- [new_x25519_key_exchanger](#new_x25519_key_exchanger)
36+
- [Ecdh25519](#Ecdh25519)
37+
- [curve_id](#curve_id)
38+
- [private_key_size](#private_key_size)
39+
- [public_key_size](#public_key_size)
40+
- [private_key_from_key](#private_key_from_key)
41+
- [generate_private_key](#generate_private_key)
42+
- [public_key](#public_key)
43+
- [shared_secret](#shared_secret)
44+
- [verify](#verify)
45+
46+
## Constants
47+
```v
48+
const (
49+
// scalar_size is the size of the scalar to the x25519
50+
scalar_size = 32
51+
52+
// point_size is the size of the point input to the x25519
53+
point_size = 32
54+
55+
// zero_point is point with 32 bytes of zero (null) bytes
56+
zero_point = []u8{len: 32, cap: 32, init: u8(0x00)}
57+
58+
// base_point is the canonical Curve25519 generator, encoded as a byte with value 9,
59+
// followed by 31 zero bytes
60+
base_point = [u8(9), 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
61+
0, 0, 0, 0, 0, 0, 0, 0]
62+
)
63+
```
64+
65+
66+
[[Return to contents]](#Contents)
67+
68+
```v
69+
const (
70+
key_size = 32
71+
private_key_size = key_size
72+
public_key_size = key_size
73+
)
74+
```
75+
76+
This const for Curve25519 based curve
77+
78+
[[Return to contents]](#Contents)
79+
80+
## x25519
81+
```v
82+
fn x25519(scalar []u8, point []u8) ![]u8
83+
```
84+
85+
x25519 returns the result of the scalar multiplication (scalar * point), according to RFC 7748, Section 5. scalar, point and the return value are
86+
slices of 32 bytes.
87+
The functions take a scalar and a u-coordinate as inputs and produce a u-coordinate as output.
88+
Although the functions work internally with integers, the inputs and outputs are 32-byte strings (for X25519) scalar can be generated at random, for example with `crypto.rand` and point should
89+
be either base_point or the output of another `x25519` call.
90+
91+
[[Return to contents]](#Contents)
92+
93+
## Curve
94+
```v
95+
enum Curve {
96+
secp256r1 = 0x0017
97+
secp384r1 = 0x0018
98+
secp521r1 = 0x0019
99+
x25519 = 0x001D
100+
x448 = 0x001E
101+
ffdhe2048 = 0x0100
102+
ffdhe3072 = 0x0101
103+
ffdhe4096 = 0x0102
104+
ffdhe6144 = 0x0103
105+
ffdhe8192 = 0x0104
106+
}
107+
```
108+
109+
Basically, Curve is a TLS 1.3 NamedGroup.
110+
its defined here for simplicity.
111+
vfmt off
112+
113+
[[Return to contents]](#Contents)
114+
115+
## new_key_exchanger
116+
```v
117+
fn new_key_exchanger(c Curve) !KeyExchanger
118+
```
119+
120+
new_key_exchanger creates new KeyExchanger for curve c, for this time, only curve25519 is supported
121+
122+
[[Return to contents]](#Contents)
123+
124+
## KeyExchanger
125+
```v
126+
interface KeyExchanger {
127+
// curve_id tell the curve id
128+
curve_id() Curve
129+
// private_key_size should return underlying PrivateKey bytes size.
130+
private_key_size() int
131+
// public_key_size should return underlying PublicKey bytes size.
132+
public_key_size() int
133+
// generate_private_key generates random PrivateKey using entropy from secure crypto random generator.
134+
generate_private_key() !PrivateKey
135+
// private_key_from_key generates PrivateKey from some given key.
136+
private_key_from_key(key []u8) !PrivateKey
137+
// public_key returns public key corresponding to PrivateKey.
138+
public_key(PrivateKey) !PublicKey
139+
// shared_secret computes shared secret between alice PrivateKey and bob's PublicKey.
140+
shared_secret(local PrivateKey, remote PublicKey) ![]u8
141+
}
142+
```
143+
144+
Key Exchange Protocol
145+
146+
[[Return to contents]](#Contents)
147+
148+
## PublicKey
149+
## equal
150+
```v
151+
fn (pk PublicKey) equal(x PublicKey) bool
152+
```
153+
154+
equal tell if two PublicKey is equal, its check if has the same curve and its also check
155+
if underlying pubkey bytes has exactly the same length and contents.
156+
157+
[[Return to contents]](#Contents)
158+
159+
## bytes
160+
```v
161+
fn (pk PublicKey) bytes() ![]u8
162+
```
163+
164+
bytes returns bytes content of PublicKey.
165+
166+
[[Return to contents]](#Contents)
167+
168+
## PrivateKey
169+
## bytes
170+
```v
171+
fn (pv PrivateKey) bytes() ![]u8
172+
```
173+
174+
bytes return PrivateKey as a bytes array
175+
176+
[[Return to contents]](#Contents)
177+
178+
## equal
179+
```v
180+
fn (pv PrivateKey) equal(oth PrivateKey) bool
181+
```
182+
183+
equal whether two PrivateKey has equally identical (its not check pubkey part)
184+
185+
[[Return to contents]](#Contents)
186+
187+
## public_key
188+
```v
189+
fn (mut prv PrivateKey) public_key() !PublicKey
190+
```
191+
192+
public_key is accessor for `privatekey.pubk` public key part, its does check if matching public key part or initializes PublicKey if not. Initialization is does under `sync.do_with_param`
193+
to make sure its that a function is executed only once.
194+
195+
[[Return to contents]](#Contents)
196+
197+
## new_x25519_key_exchanger
198+
```v
199+
fn new_x25519_key_exchanger() KeyExchanger
200+
```
201+
202+
new_x25519_key_exchanger creates new Curve25519 based ECDH key exchange protocol
203+
204+
[[Return to contents]](#Contents)
205+
206+
## Ecdh25519
207+
## curve_id
208+
```v
209+
fn (ec Ecdh25519) curve_id() Curve
210+
```
211+
212+
return underlying curve id
213+
214+
[[Return to contents]](#Contents)
215+
216+
## private_key_size
217+
```v
218+
fn (ec Ecdh25519) private_key_size() int
219+
```
220+
221+
private_key_size returns private key size, in bytes
222+
223+
[[Return to contents]](#Contents)
224+
225+
## public_key_size
226+
```v
227+
fn (ec Ecdh25519) public_key_size() int
228+
```
229+
230+
public_key_size returns public key size, in bytes
231+
232+
[[Return to contents]](#Contents)
233+
234+
## private_key_from_key
235+
```v
236+
fn (ec Ecdh25519) private_key_from_key(key []u8) !PrivateKey
237+
```
238+
239+
private_key_from_key generates PrivateKey from seeded key.
240+
241+
[[Return to contents]](#Contents)
242+
243+
## generate_private_key
244+
```v
245+
fn (ec Ecdh25519) generate_private_key() !PrivateKey
246+
```
247+
248+
generate_private_key generates PrivateKey with random entropy using `crypto.rand`
249+
250+
[[Return to contents]](#Contents)
251+
252+
## public_key
253+
```v
254+
fn (ec Ecdh25519) public_key(pv PrivateKey) !PublicKey
255+
```
256+
257+
public_key gets PublicKey part of PrivateKey
258+
259+
[[Return to contents]](#Contents)
260+
261+
## shared_secret
262+
```v
263+
fn (ec Ecdh25519) shared_secret(local PrivateKey, remote PublicKey) ![]u8
264+
```
265+
266+
shared_secret computes shared keys between two parties, alice private keys and others public keys.
267+
Its commonly used as elliptic curve diffie-hellman (ECDH) key exchange protocol
268+
269+
[[Return to contents]](#Contents)
270+
271+
## verify
272+
```v
273+
fn verify(ec KeyExchanger, privkey PrivateKey, pubkey PublicKey) bool
274+
```
275+
276+
given PrivateKey privkey, verify do check whether given PublicKey pubkey is really keypair for privkey. Its check by calculating public key part of
277+
given PrivateKey.
278+
279+
[[Return to contents]](#Contents)

‎ecdh.v

+3
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,9 @@ pub fn (pv PrivateKey) equal(oth PrivateKey) bool {
125125
&& subtle.constant_time_compare(pv.privkey, oth.privkey) == 1
126126
}
127127

128+
// public_key is accessor for `privatekey.pubk` public key part, its does check if matching
129+
// public key part or initializes PublicKey if not. Initialization is does under `sync.do_with_param`
130+
// to make sure its that a function is executed only once.
128131
pub fn (mut prv PrivateKey) public_key() !PublicKey {
129132
prv.pubk_once.do_with_param(fn (mut o PrivateKey) {
130133
// internal pubkey of privatekey does not initialized to some values.

0 commit comments

Comments
 (0)