[crypticl-cvs] CVS crypticl/doc

[tskogan]

Update of /project/crypticl/cvsroot/crypticl/doc
In directory clnet:/tmp/cvs-serv23254

Modified Files:
	crypticl.pdf crypticl.lyx 
Log Message:
Adding section on random numbers.


Binary files /project/crypticl/cvsroot/crypticl/doc/crypticl.pdf	2007/02/17 00:54:50	1.3 and /project/crypticl/cvsroot/crypticl/doc/crypticl.pdf	2007/02/17 16:08:42	1.4 differ
--- /project/crypticl/cvsroot/crypticl/doc/crypticl.lyx	2007/02/17 00:46:36	1.2
+++ /project/crypticl/cvsroot/crypticl/doc/crypticl.lyx	2007/02/17 16:08:42	1.3
@@ -279,7 +279,7 @@
 \end_layout
 
 \begin_layout LyX-Code
-crypticl(31): (with-open-file (s "rsa.lisp") 
+crypticl(15): (with-open-file (s "rsa.lisp") 
 \end_layout
 
 \begin_layout LyX-Code
@@ -291,6 +291,79 @@
 \end_layout
 
 \begin_layout Section
+Random numbers
+\end_layout
+
+\begin_layout Standard
+Handling random numbers correctly is vital for almost all crypto primitives.
+ I recommend studying chapter 10 in 
+\begin_inset LatexCommand \cite{key-1}
+
+\end_inset
+
+ before using the random number api of Crypticl (or any crypto library for
+ that matter).
+ Two important factors are a cryptographically secure pseudorandom number
+ generator and a source of high entropy bits for seeding the generator.
+ Crypticl uses 256-bits AES in counter mode as the number generator (based
+ on the Fortuna design from 
+\begin_inset LatexCommand \cite{key-1}
+
+\end_inset
+
+).
+ The function 
+\family typewriter
+random-secure-octets
+\family default
+ returns an octet vector with random bits:
+\end_layout
+
+\begin_layout LyX-Code
+crypticl(16): (random-secure-octets 16)
+\end_layout
+
+\begin_layout LyX-Code
+#(146 37 34 245 50 193 238 169 54 139 ...)
+\end_layout
+
+\begin_layout Standard
+Before using any primitives involving keys or other random data you must
+ seed the pseudorandom number generator with high entropy bits.
+ On Linux the generator in Crypticl will seed itself using 
+\family typewriter
+/dev/random
+\family default
+, but on Windows you must seed the generator yourself with 256 bits of entropy
+ using the api call 
+\family typewriter
+reseed-secure-prng:
+\end_layout
+
+\begin_layout LyX-Code
+crypticl(17): (reseed-secure-prng seed)
+\end_layout
+
+\begin_layout LyX-Code
+#<SecurePRNG-AES @ #x209099f2>
+\end_layout
+
+\begin_layout Standard
+The seed must be an octet vector or a bignum.
+ Furthermore you may need to reseed the generator depending on how you use
+ it (see 
+\begin_inset LatexCommand \cite{key-1}
+
+\end_inset
+
+).
+ Note: The handling of entropy and reseeding is weak and brittle in the
+ current (0.2) version of Crypticl and it is very easy to compromise security
+ if you make a mistake.
+ So be extremely careful.
+\end_layout
+
+\begin_layout Section
 Symmetric key encryption
 \end_layout
 
@@ -810,5 +883,14 @@
 (8431410348096402792 8431410348096402792)
 \end_layout
 
+\begin_layout Bibliography
+
+\bibitem {key-1}
+Ferguson, Niels and Schneier, Bruce.
+ 2003.
+ Practical Cryptography.
+ Wiley.
+\end_layout
+
 \end_body
 \end_document