4747\def\gap {\vspace {0.5ex}}
4848\makeindex
4949\begin {document }
50- \title {LibTomCrypt \\ Version 0.97b }
50+ \title {LibTomCrypt \\ Version 0.98 }
5151\author {Tom St Denis \\
5252\\
5353tomstdenis@iahu.ca \\
@@ -1687,37 +1687,101 @@ \section{PMAC Support}
16871687Which returns {\bf CRYPT\_ OK} if the code passes otherwise it returns an error code.
16881688
16891689
1690+
1691+
1692+
16901693\chapter {Pseudo-Random Number Generators }
16911694\section {Core Functions }
1692-
16931695The library provides an array of core functions for Pseudo-Random Number Generators (PRNGs) as well. A cryptographic PRNG is
16941696used to expand a shorter bit string into a longer bit string. PRNGs are used wherever random data is required such as Public Key (PK)
16951697key generation. There is a universal structure called `` prng\_ state''
1698+ \index {PRNG start}
16961699\begin {verbatim }
16971700int XXX_start(prng_state *prng);
16981701\end {verbatim }
16991702
17001703This will setup the PRNG for future use and not seed it. In order
17011704for the PRNG to be cryptographically useful you must give it entropy. Ideally you'd have some OS level source to tap
17021705like in UNIX (see section 5.3). To add entropy to the PRNG call:
1706+ \index {PRNG add\_ entropy}
17031707\begin {verbatim }
17041708int XXX_add_entropy(const unsigned char *in, unsigned long len,
17051709 prng_state *prng);
17061710\end {verbatim }
17071711
17081712Which returns {\bf CRYPTO\_ OK} if the entropy was accepted. Once you think you have enough entropy you call another
17091713function to put the entropy into action.
1714+ \index {PRNG ready}
17101715\begin {verbatim }
17111716int XXX_ready(prng_state *prng);
17121717\end {verbatim }
17131718
17141719Which returns {\bf CRYPTO\_ OK} if it is ready. Finally to actually read bytes call:
1720+ \index {PRNG read}
17151721\begin {verbatim }
17161722unsigned long XXX_read(unsigned char *out, unsigned long len,
17171723 prng_state *prng);
17181724\end {verbatim }
17191725
1720- Which returns the number of bytes read from the PRNG.
1726+ Which returns the number of bytes read from the PRNG. When you are finished with a PRNG state you call
1727+ the following.
1728+
1729+ \index {PRNG done}
1730+ \begin {verbatim }
1731+ void XXX_done(prng_state *prng);
1732+ \end {verbatim }
1733+
1734+ This will terminate a PRNG state and free any memory (if any) allocated. To export a PRNG state
1735+ so that you can later resume the PRNG call the following.
1736+
1737+ \index {PRNG export}
1738+ \begin {verbatim }
1739+ int XXX_export(unsigned char *out, unsigned long *outlen,
1740+ prng_state *prng);
1741+ \end {verbatim }
1742+
1743+ This will write a `` PRNG state'' `` out'' `` outlen''
1744+ the export is meant to be used as a `` seed file''
1745+ be that much entropy available. To import a state to seed a PRNG call the following function.
1746+
1747+ \index {PRNG import}
1748+ \begin {verbatim }
1749+ int XXX_import(const unsigned char *in, unsigned long inlen,
1750+ prng_state *prng);
1751+ \end {verbatim }
1752+
1753+ This will call the start and add\_ entropy functions of the given PRNG. It will use the state in
1754+ `` in'' `` inlen''
1755+ by the corresponding export function.
1756+
1757+ Note that importing a state will not `` resume''
1758+ a state, emit (say) 8 bytes and then import the previously exported state the next 8 bytes will not
1759+ specifically equal the 8 bytes you generated previously.
1760+
1761+ When a program is first executed the normal course of operation is
1762+
1763+ \begin {enumerate }
1764+ \item Gather entropy from your sources for a given period of time or number of events.
1765+ \item Start, use your entropy via add\_ entropy and ready the PRNG yourself.
1766+ \end {enumerate }
1767+
1768+ When your program is finished you simply call the export function and save the state to a medium (disk,
1769+ flash memory, etc). The next time your application starts up you can detect the state, feed it to the
1770+ import function and go on your way. It is ideal that (as soon as possible) after startup you export a
1771+ fresh state. This helps in the case that the program aborts or the machine is powered down without
1772+ being given a chance to exit properly.
1773+
1774+ Note that even if you have a state to import it is important to add new entropy to the state. However,
1775+ there is less pressure to do so.
1776+
1777+ To test a PRNG for operational conformity call the following functions.
1778+
1779+ \index {PRNG test}
1780+ \begin {verbatim }
1781+ int XXX_test(void);
1782+ \end {verbatim }
1783+
1784+ This will return \textbf {CRYPT\_ OK } if PRNG is operating properly.
17211785
17221786\subsection {Remarks }
17231787
@@ -1728,8 +1792,8 @@ \subsection{Remarks}
17281792
17291793\subsection {Example }
17301794
1731- Below is a simple snippet to read 10 bytes from yarrow. Its important to note that this snippet is { \bf NOT} secure since
1732- the entropy added is not random.
1795+ Below is a simple snippet to read 10 bytes from yarrow. Its important to note that this snippet is
1796+ { \bf NOT} secure since the entropy added is not random.
17331797
17341798\begin {verbatim }
17351799#include <mycrypt.h>
@@ -1762,10 +1826,15 @@ \section{PRNG Descriptors}
17621826\begin {verbatim }
17631827struct _prng_descriptor {
17641828 char *name;
1829+ int export_size; /* size in bytes of exported state */
17651830 int (*start) (prng_state *);
17661831 int (*add_entropy)(const unsigned char *, unsigned long, prng_state *);
17671832 int (*ready) (prng_state *);
17681833 unsigned long (*read)(unsigned char *, unsigned long len, prng_state *);
1834+ void (*done)(prng_state *);
1835+ int (*export)(unsigned char *, unsigned long *, prng_state *);
1836+ int (*import)(const unsigned char *, unsigned long, prng_state *);
1837+ int (*test)(void);
17691838};
17701839\end {verbatim }
17711840
@@ -1779,16 +1848,82 @@ \section{PRNG Descriptors}
17791848int unregister_prng(const struct _prng_descriptor *prng);
17801849\end {verbatim }
17811850
1782- \subsubsection {PRNGs Provided }
1783- Currently Yarrow (yarrow\_ desc), RC4 (rc4\_ desc) and the secure RNG (sprng\_ desc) are provided as PRNGs within the
1784- library.
1851+ \subsection {PRNGs Provided }
1852+ \begin {figure }[here]
1853+ \begin {center }
1854+ \begin {small }
1855+ \begin {tabular }{|c|c|l|}
1856+ \hline \textbf {Name } & \textbf {Descriptor } & \textbf {Usage } \\
1857+ \hline Yarrow & yarrow\_ desc & Fast short-term PRNG \\
1858+ \hline Fortuna & fortuna\_ desc & Fast long-term PRNG (recommended) \\
1859+ \hline RC4 & rc4\_ desc & Stream Cipher \\
1860+ \hline SOBER-128 & sober128\_ desc & Stream Cipher (also very fast PRNG) \\
1861+ \hline
1862+ \end {tabular }
1863+ \end {small }
1864+ \end {center }
1865+ \caption {List of Provided PRNGs}
1866+ \end {figure }
1867+
1868+ \subsubsection {Yarrow }
1869+ Yarrow is fast PRNG meant to collect an unspecified amount of entropy from sources
1870+ (keyboard, mouse, interrupts, etc) and produce an unbounded string of random bytes.
1871+
1872+ \textit {Note: } This PRNG is still secure for most taskings but is no longer recommended. Users
1873+ should use Fortuna instead.
1874+
1875+ \subsubsection {Fortuna }
1876+
1877+ Fortuna is a fast attack tolerant and more thoroughly designed PRNG suitable for long term
1878+ usage. It is faster than the default implementation of Yarrow\footnote {Yarrow has been implemented
1879+ to work with most cipher and hash combos based on which you have chosen to build into the library.} while
1880+ providing more security.
1881+
1882+ Fortuna is slightly less flexible than Yarrow in the sense that it only works with the AES block cipher
1883+ and SHA--256 hash function. Technically Fortuna will work with any block cipher that accepts a 256--bit
1884+ key and any hash that produces at least a 256--bit output. However, to make the implementation simpler
1885+ it has been fixed to those choices.
1886+
1887+ Fortuna is more secure than Yarrow in the sense that attackers who learn parts of the entropy being
1888+ added to the PRNG learn far less about the state than that of Yarrow. Without getting into to many
1889+ details Fortuna has the ability to recover from state determination attacks where the attacker starts
1890+ to learn information from the PRNGs output about the internal state. Yarrow on the other hand cannot
1891+ recover from that problem until new entropy is added to the pool and put to use through the ready() function.
1892+
1893+ \subsubsection {RC4 }
1894+
1895+ RC4 is an old stream cipher that can also double duty as a PRNG in a pinch. You `` key''
1896+ calling add\_ entropy() and setup the key by calling ready(). You can only add upto 256 bytes via
1897+ add\_ entropy().
1898+
1899+ When you read from RC4 the output of the RC4 algorithm is XOR'd against your buffer you provide. In this
1900+ manner you can use rc4\_ read() as an encrypt (and decrypt) function.
1901+
1902+ You really shouldn't use RC4 anymore. This isn't because RC4 is weak (though biases are known to exist) just
1903+ simply that faster alternatives exist.
1904+
1905+ \subsubsection {SOBER-128 }
1906+
1907+ SOBER-128 is a stream cipher designed by the QUALCOMM Australia team. Like RC4 you `` key''
1908+ calling add\_ entropy(). There is no need to call ready() for this PRNG as it does not do anything.
1909+
1910+ Note that this cipher has several oddities about how it operates. The first time you call
1911+ add\_ entropy() that sets the cipher's key. Every other time you call the same function it sets
1912+ the cipher's IV variable. The IV mechanism allows you to encrypt several messages with the same
1913+ key and not re--use the same key material.
1914+
1915+ Unlike Yarrow and Fortuna all of the entropy (and hence security) of this algorithm rests in the data
1916+ you pass it on the first call to add\_ entropy(). All buffers sent to add\_ entropy() must have a length
1917+ that is a multiple of four bytes.
1918+
1919+ Like RC4 the output of SOBER--128 is XOR'ed against the buffer you provide it. In this manner you can use
1920+ sober128\_ read() as an encrypt (and decrypt) function.
17851921
1786- RC4 is provided with a PRNG interface because it is a stream cipher and not well suited for the symmetric block cipher
1787- interface. You provide the key for RC4 via the rc4\_ add\_ entropy() function. By calling rc4\_ ready() the key will be used
1788- to setup the RC4 state for encryption or decryption. The rc4\_ read() function has been modified from RC4 since it will
1789- XOR the output of the RC4 keystream generator against the input buffer you provide. The following snippet will demonstrate
1790- how to encrypt a buffer with RC4:
1922+ Since SOBER-128 has a fixed keying scheme and is very fast (faster than RC4) the ideal usage of SOBER-128 is to
1923+ key it from the output of Fortuna (or Yarrow) and use it to encrypt messages. It is also ideal for
1924+ simulations which need a high quality (and fast) stream of bytes.
17911925
1926+ \subsubsection {Example Usage }
17921927\begin {small }
17931928\begin {verbatim }
17941929#include <mycrypt.h>
0 commit comments