This repository has been archived by the owner on Aug 2, 2018. It is now read-only.
-
-
Notifications
You must be signed in to change notification settings - Fork 1
/
README
438 lines (296 loc) · 13.1 KB
/
README
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
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
NeuG - a true random number generator implementation (for STM32F103)
Version 1.0.6
2017-10-11
Niibe Yutaka
Free Software Initiative of Japan
What's NeuG?
============
NeuG is a set of routines of random number generator (RNG) which is
based on physical noise. It supports STM32F103. It can be stand
alone USB RNG device (with main routine), too.
The name comes from Japanized English word "noidgy" (from English word
"noisy"), where many Japanese (including me) don't distinguish
pronunciations of "gee" and "zee". NeuG includes my important letters
of "g", "n", and "u", and the word "neu" (German spelling of "new").
My primary intention was to incorporate NeuG routines into Gnuk for
random number generation, but the stand alone version could be useful
too.
Gnuk was named after my son who loved the pacifier when he was baby.
NeuG was named after my daughter, but I don't say she is noisy.
Release notes
=============
This is the sixth minor release of NeuG, after 1.0.
Basic features (generating random numbers) are stable, but newly added
things like Fraucheky (USB Mass Storage Class) support and reGNUal
(firmware upgrad) support should be considered experimental.
Note that you need Chopstx (the thread library) as external source
code. If you get the source code by Git, Chopstx is a submodule of
NeuG.
You can test how the NeuG stand-alone device works on GNU/Linux,
without real hardware, by USBIP emulation (--target=GNU_LINUX).
Please note that this is only for testing. Use of its generated
randomness is not recommended, because of no entropy source.
FAQ
===
Q0: How NeuG device is good?
A0: I believe it's good enough if we compare to other hardware RNGs.
I evaluated it with rngtest of RNG-tools, NIST STS test suite and
Dieharder. See the directory neug/test-results/.
A0-dash: For better entropy device with embedded test, you could get
EntropyKey. See http://www.entropykey.co.uk/
A0-double-dash: STM32F2xx and STM32F4xx have built-in TRNG, it would
be better for you (although the quality of randomness
looks not that good).
Q1: How fast is NeuG device?
A1: It's about 80 kB/sec for conditioned output (by SHA-256), and
about 270 kB/sec for CRC-32 filtered output (kB = 1000 byte).
Q2: Should we check condition of noise sources?
A2: Yes, we should. Three continuous tests are implemented, following
(Draft of) NIST SP 800-90B. Those are Repetition Count Test,
Adaptive Proportion Test (for 64 samples), and another Adaptive
Proportion Test (for 4096 samples). When it detects an error (it
is really rare, but it could occur even for normal condition), the
generation of random bits restart again.
Q3: Conditioning with SHA-256 sounds over-kill. Why not simpler?
A3: It is because NIST SP 800-90B mandates something like that for
"full entropy source". If your usage is as an entropy source for
RNG-tools to feed entropy to your kernel, or use for computer
simulations, I think that CRC-32 filtered output would be good
enough.
Q4: Configuring by 'stty' doesn't work, what's up?
A4: Common problem on GNU/Linux is the "modemmanager" try to control
/dev/ttyACM0, which interferes. Please consider removing
modemmanager from your system or configure it to ignore NeuG
device. For detail, please see the FST-01 support pages on the
web.
Targets
=======
FST-01, Nitrokey-Start, Olimex STM32-H103, STM32 part of STM8S
Discovery Kit, STBee Mini, STBee, STM32 Primer 2, CQ STARM, ST Dongle
and STM32 Nucleo F103 are supported.
Build system and Host system
============================
Makefile is written for GNU make. You need Bash 4.x for configure.
If your bash is not installed as /bin/bash, you need to run configure
script prepending 'bash' before './configure'.
Some tools are written in Python. If your Python is not installed as
/usr/bin/python, please prepend 'python' for your command invocation.
Python 2.7 and PyUSB 0.4.3 is assumed. I also use Python 3.5 and
PyUSB 1.0.0.
Souce code
==========
NeuG source code is under src/ directory.
Note that SHA-256 hash function implementation, src/sha256.c, is based
on the original implementation by Dr. Brian Gladman. See:
http://brg.a2hosted.com//oldsite/cryptography_technology/sha/index.php
(was at:
http://gladman.plushost.co.uk/oldsite/cryptography_technology/sha/index.php)
License
=======
It is distributed under GNU General Public Licence version 3 or later
(GPLv3+). Please see src/COPYING.
External source code
====================
NeuG is distributed with external source code.
* chopstx/ -- Chopstx, the RT Thread Library
* [optional] fraucheky/ -- Fraucheky, the GPL container
Those are available at:
https://anonscm.debian.org/cgit/gnuk/chopstx/
USB vendor ID and product ID (USB device ID)
============================================
When you have a vender ID and assign a product ID for NeuG, edit the
file NEUG_USB_DEVICE_ID and add an entry for yours. In this case,
please contact Niibe, so that it is listed to the file in the official
release of the source code.
When you are modifing NeuG and installing the binary to device, you
should replace the vendor string to yours, so that users can see it's
not by original vendor, and it is modified version.
FSIJ allows you to use USB device ID of FSIJ (234b:0001) for devices
with standalone NeuG under one of following conditions:
* For everyone for experimental purpose:
- You must not distribute a binary with FSIJ's USB device ID, but
must use the binary by yourself only for your experiment. Note
that "Distributing binary" includes distributing a device which
holds the binary.
* For individuals:
- No additional conditions.
FSIJ could give companies or business entities "second source
manufacturer" license to use USB device ID of FSIJ for devices with
unmodified version of NeuG, provided they support Free Software and
respect users' freedom for computing. Please ask FSIJ for the
license.
Otherwise, companies which want to distribute NeuG devices, please use
your own USB vendor ID and product ID. Please replace vendor string
and possibly product string to yours, when you modify NeuG.
How to compile
==============
You need GNU toolchain and newlib for 'arm-none-eabi' target.
On Debian we can install the packages of gcc-arm-none-eabi,
gdb-arm-none-eabi and its friends. I'm using:
binutils-arm-none-eabi 2.28-5+9+b3
gcc-arm-none-eabi 15:5.4.1+svn241155-1
gdb-arm-none-eabi 7.12-6+9+b2
libnewlib-arm-none-eabi 2.4.0.20160527-2
Or else, see https://launchpad.net/gcc-arm-embedded for preparation of
GNU Toolchain for 'arm-none-eabi' target.
Change directory to `src':
$ cd neug-VERSION/src
Then, run `configure':
$ ./configure --vidpid=<VID:PID>
Here, you need to specify USB vendor ID and product ID. For FSIJ's,
it's: --vidpid=234b:0001 . Please read section 'USB vendor ID and
product ID' above.
Type:
$ make
Then, we will have "neug.elf" under the "build" directory.
How to install
==============
Olimex STM32-H103 board
-----------------------
If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
$ openocd -f interface/ftdi/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
Then, with another terminal, type following to write "neug.elf" to Flash ROM:
$ telnet localhost 4444
> reset halt
> flash write_image erase neug.elf
> reset
> exit
$
Flying Stone Tiny 01 and STM8S Discovery Kit
--------------------------------------------
If you are using Flying Stone Tiny 01, you need a SWD writer.
OpenOCD 0.6.1 or newer supports ST-Link/V2. With that we can do:
$ openocd -f interface/stlink-v2.cfg -f target/stm32f1x_stlink.cfg
Then, with another terminal, type following to write "neug.elf" to Flash ROM:
$ telnet localhost 4444
> reset halt
> flash write_image erase neug.elf
> reset
> exit
$
Note that OpenOCD (as of 0.7.0) doesn't support option bytes handling yet.
You can also use tool/stlinkv2.py in Gnuk.
Use of NeuG device
==================
It is USB CDC ACM device. On GNU/Linux, it can be /dev/ttyACM0 or like.
Before using /dev/ttyACM0, you need to configure its TTY discipline.
$ stty -F /dev/ttyACM0 -echo raw
Then, you can use output of /dev/ttyACM0.
When you want to get CRC-32 filtered output, you can configure:
$ stty -F /dev/ttyACM0 parenb parodd
for raw data after filter. For direct raw data of ADC samples,
configure:
$ stty -F /dev/ttyACM0 parenb -parodd
And you can get SHA-256 conditioned output by configuring:
$ stty -F /dev/ttyACM0 -parenb
If your device is configured with Fraucheky, you can invoke Fraucheky
from NeuG by setting the unusual sequence of configurations:
$ stty -F /dev/ttyACM0 ispeed 110 ospeed 110
$ stty -F /dev/ttyACM0 ispeed 115200 ospeed 115200
Structure of NeuG
=================
Here is a figure of the circuit.
Noise sources
/|<---+--- [ Analog input Vref ]
16 | |<-+-|--- [ Analog input Temperature Sensor ]
+---/-[ADC1] <==| | | |
| | |<-+ |
+-+ | \|<---+
| |<---+ |
+----| | MUX CTL >--+
| | |<---+
| +-+ | /|
| | 16 | |<------- [ Analog input 0 ] (pull up to Vdd)
| +---/-[ADC2] <==| |
| | |<------- [ Analog input 1 ] (pull up to Vdd)
| \|
| |
| MUX CTL >--+
|
+------------------+ <============ (*1)
|
/ 32
|
| Put 4 times to output 32-bit
V
[ CRC-32 filter ]
|
| Put 35 times to output 1120-bit
+---------------------------------+ <====== (*2)
|
/ 32
|
V
[ Entropy Buffer ]
|
+--------------+ |
| | |
| Conditioning | 1120 |
| Component |<------------/------------+
| |
+-----| Hash_df |
| | by |
| | SHA-256 |
| | | 128
| | |<--/--+
| +--------------+ |
| |
+---------------------------+
|
/ 256
|
v
Random Number Output <========== (*3)
Specifying by "stty", you can get (*3) with -parenb, (*2) with parenb
parodd, and (*1) with parenb -parodd.
STM32F103 has two built-in A/D converters. NeuG uses A/D converters'
outputs as entropy sources. It is considered noise of quantization
error, plus noise from power supply, etc.
We chose four analog input sources of: built-in voltage reference,
temperature sensor and two analog inputs which are pull-up to Vdd.
By a single sampling of two channels, we get 32-bit (not all 32-bit is
valid, as a A/D converter resolution is 12-bit only). We take four
sampling of combinations: (Vref, IN0), (Temp, IN1), (Vref, IN1), and
(Temp, IN0). Those 32-bit * 4 is fed into CRC32 filter.
We use STM32F103's CRC32 calculation unit as a kind of filter. We put
output of A/D converters into CRC32 calculation unit, four times, to
get 4-byte output.
Output of CRC32 filter is collected 35 times, and it becomes 1120-bit
(32 * 35). This is the noise source bits.
We put this 1120-bit and half of previous output (128-bit) to
conditioning component.
Conditioning Component is implemented by Hash_df function which is
composed by SHA-256. Since the noise source is not "white", signal is
whiten by this Conditioning Component.
My experience with STM32F103 and NeuG shows that noise source is
stable at least for a year.
Test results
============
See files under the directory test-results, for test result of
PractRand 0.92.
I collect 140 files of 125MB (>= 16GiB), and run the test suite of
PractRand 0.92. Collecting 140 files, it took two days and a half.
Git Repository
==============
NeuG is available in the Gnuk repository at:
https://anonscm.debian.org/cgit/gnuk/gnuk/
You can get it by:
$ git clone git://anonscm.debian.org/gnuk/gnuk/neug.git
I put Chopstx and Fraucheky as a submodules of Git. Please do this:
$ git submodule init
$ git submodule update
Information on the Web
======================
Please see the FST-01 support pages:
https://www.gniibe.org/category/fst-01.html
Please consider to join Gnuk-users mailing list:
https://lists.alioth.debian.org/mailman/listinfo/gnuk-users
The mailing list will be moved to lists.debian.org.
Your Contributions
==================
FSIJ welcomes your contributions. Please assign your copyright
to FSIJ (if possible).
Foot note
==========
If NeuG had a family name, it must be Kunisada.
--