annotate notes/tech0001.txt @ 211:f01f0400314d libtomcrypt

disapproval of revision 6a39eb8b36778460fca83b8149df2a8b6d3327fd
author Matt Johnston <matt@ucc.asn.au>
date Wed, 06 Jul 2005 13:23:45 +0000
parents d7da3b1e1540
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1 Tech Note 0001
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2 How to Gather Entropy on Embedded Systems
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3 Tom St Denis
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5 Introduction
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6 ------------
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
7
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
8 This tech note explains a relatively simple way to gather entropy for a PRNG (Yarrow in this case) in embedded systems
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
9 where there are few sources of entropy or physical sources.
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
10
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
11 When trying to setup a secure random number generator a fresh source of random data (entropy) is required to ensure the
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
12 deterministic state of the PRNG is not known or predetermined with respect to an attacker.
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
13
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
14 At the very least the system requires one timer and one source of un-timed interrupts. by "un-timed" I mean interrupts
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
15 that do not occur at regular intervals [e.g. joypad/keypad input, network packets, etc...].
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
16
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
17 First we shall begin by taking an overview of how the Yarrow PRNG works within libtomcrypt. At the heart of all
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
18 PRNGs is the "prng_state" data type. This is a union of structures that hold the PRNG state for the various prngs. The
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
19 first thing we require is a state...
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
20
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
21 prng_state myPrng;
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
22
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
23 Next we must initialize the state once to get the ball rolling
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
24
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
25 if (yarrow_start(&myPrng) != CRYPT_OK) {
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
26 // error should never happen!
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
27 }
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
28
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
29 At this point the PRNG is ready to accept fresh entropy which is added with
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
30
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
31 int yarrow_add_entropy(const unsigned char *buf, unsigned long len, prng_state *prng)
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
32
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
33 This function is **NOT** thread safe which will come under consideration later. To add entropy to our PRNG we must
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
34 call this function with fresh data as its sampled. Lets say we have a timer counter called "uTimer" which is a 32-bit
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
35 long and say a 32-bit joyPad state called "uPad". An example interrupt handler would look like
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
36
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
37 void joypad_interrupt(...) {
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
38 unsigned char buf[8];
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
39
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
40 STORE32L(uTimer, buf);
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
41 STORE32L(uPad, buf+4)
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
42 if (yarrow_add_entropy(buf, 8, &myPrng) != CRYPT_OK) {
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
43 // this should never occur either unless you didn't call yarrow_start
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
44 }
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
45
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
46 // handle interrupt
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
47 }
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
48
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
49 In this snippet the timer count and state of the joypad are added together into the entropy pool. The timer is important
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
50 because with respect to the joypad it is a good source of entropy (on its own its not). For example, the probability of
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
51 the user pushing the up arrow is fairly high, but at a specific time is not.
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
52
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
53 This method doesn't gather alot of entropy and has to be used to for quite a while. One way to speed it up is to tap
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
54 multiple sources. If you have a network adapter and other sources of events (keyboard, mouse, etc...) trapping their
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
55 data is ideal as well. Its important to gather the timer along with the event data.
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
56
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
57 As mentioned the "yarrow_add_entropy()" function is not thread safe. If your system allows interrupt handlers to be
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
58 interrupted themselves then you could have trouble. One simple way is to detect when an interrupt is in progress and
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
59 simply not add entropy during the call (jump over the yarrow_add_entropy() call)
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
60
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
61 Once you feel that there has been enough entropy added to the pool then within a single thread you can call
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
62
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
63 int yarrow_ready(prng_state *prng)
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
64
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
65 Now the PRNG is ready to read via the
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
66
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
67 unsigned long yarrow_read(unsigned char *buf, unsigned long len, prng_state *prng)
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
68
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
69 It is a very good idea that once you call the yarrow_ready() function that you stop harvesting entropy in your interrupt
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
70 functions. This will free up alot of CPU time. Also one more final note. The yarrow_read() function is not thread
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
71 safe either. This means if you have multiple threads or processes that read from it you will have to add your own semaphores
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
72 around calls to it.
d7da3b1e1540 put back the 0.95 makefile which was inadvertently merged over
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
73