1\defmodule{ucrypto}
2
3This module implements different versions of some random number generators
4proposed or used in the world of cryptology.
5% \richard{Implanter MD5, \ldots}
6%  It implements a generator
7% based on the Rijndael cipher, upon which is based AES,
8% the Advanced Encryption Standard \cite{rDAE02a}.
9% For more details, see
10% \url{http://www.esat.kuleuven.ac.be/~rijmen/rijndael/}.
11
12% Les RNG propos\'es au workshop de NIST en 2004:
13% \texttt{Hash, HMAC, KHF, cipherOFB, cipherCTR,
14% Dual\_EC, MS}. (2004) \url{http://csrc.nist.gov/CryptoToolkit/tkrng.html}
15\newcommand{\aes}{\textrm{AES}}
16\newcommand{\shaun}{\mbox{\textrm{SHA-1}}}
17\newcommand{\calh}{{H}}
18\newcommand{\cale}{{E}}
19
20
21%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
22\bigskip
23\hrule
24\code\hide
25/*  ucrypto.h  for ANSI C  */
26#ifndef UCRYPTO_H
27#define UCRYPTO_H
28\endhide
29#include "unif01.h"
30
31
32typedef enum {
33   ucrypto_OFB,                 /* Output Feedback mode */
34   ucrypto_CTR,                 /* Counter mode */
35   ucrypto_KTR                  /* Key counter mode */
36   } ucrypto_Mode;
37\endcode
38 \tab  Block modes of operation \cite{rDWO01a} for this module. Given an algorithm
39  (for example, encryption or hashing) used as a generator of random numbers, then
40  the output feedback mode (\texttt{OFB}) uses the result of the last application
41  of the algorithm as input block for the current application. The counter
42   mode (\texttt{CTR}) applies the algorithm on a counter used as input and
43  incremented by 1 at each application.  The key counter mode (\texttt{KTR})
44  applies the algorithm on the seed with a different key at each application of
45  the algorithm; the key is incremented by 1 before each application.
46%  It is assumed that the plain text blocks to encrypt are all 0, except for the
47%  first one (\emph{the seed}) which is used for initialization.
48 \endtab
49\code
50
51
52unif01_Gen * ucrypto_CreateAES (unsigned char *Key, int klen,
53                                unsigned char *Seed, ucrypto_Mode mode,
54                                int r, int s);
55\endcode
56\tab Uses the \textit{Advanced Encryption standard} (\aes) as a source of
57\index{Generator!AES}\index{Generator!Rijndael}%
58  random numbers \cite{rDAE02a,rNIS01a,rHEL03a,rBAR06a}, based on the optimized
59  C code for the Rijndael cipher written by V. Rijmen,
60  A. Bossel\ae rs and P. Barreto \cite{rRIJ00a}. \texttt{klen} is the number of
61  bits in the cipher \texttt{Key}, which must be given as an array of $16, 24$
62  or $32$ bytes for a key of 128, 192 or 256 bits, respectively. \texttt{Seed}
63  is the initial state, which must be an array of 16 bytes making in all 128 bits.
64  At each encryption step $j$, the AES encryption algorithm is applied on the
65  input block to obtain a new block of 128 bits (16 bytes). Of these,
66  the first $r$ bytes are dropped and the next $s$ bytes are used to build 32-bit
67  random numbers. Each call to the generator returns a 32-bit random number.
68  For example, if $r=2$ and $s=8$, then the 16 ($8r$) most significant bits of
69  the block are dropped and the next 64 ($8s$) bits are used to make two 32-bit
70  random numbers which will be returned by the next two calls to the
71  generator. Restrictions: \texttt{klen} $\in \{ 128, 192, 256\}$,
72  $0 \le r \le 15$, $1 \le s \le 16$, and  $r + s \le 16$.
73
74  Let $C = \cale(K,T)$ denote the \aes\ encryption operation with key $K$ on
75  plain text $T$ resulting in encrypted text $C$.
76\begin{itemize}
77
78\item  For the \texttt{OFB} mode, each new block of 128 bits $C_j$ is
79  obtained by $C_j = \cale(K,C_{j-1})$, where $C_0 =$ \texttt{Seed}.
80
81\item The \texttt{CTR} mode uses a 128-bit counter $i$ whose initial value is
82  equal to \texttt{Seed}, and which is incremented
83  by 1 at each encryption step $j$. Each new block of 128 bits
84  $C_j$ is obtained by $C_j = \cale(K,i)$.
85
86\item The \texttt{KTR} mode uses a counter $i$ as the key which is
87  incremented by 1 at each encryption step $j$ as $i \leftarrow i + 1$.
88  Each new block of 128 bits $C_j$ is obtained by
89  $C_j = \cale(i, \texttt{Seed})$, where the initial value of $i$ is
90 \texttt{Key} viewed as an integer.
91\end{itemize}
92 \endtab
93\code
94
95
96unif01_Gen * ucrypto_CreateSHA1 (unsigned char *Seed, int len,
97                                 ucrypto_Mode mode, int r, int s);
98\endcode
99 \tab Uses the \textit{Secure Hash Algorithm}
100  \shaun\ as a source of random numbers \cite{rNIS02a,rBAR06a}.
101\index{Generator!SHA1}%
102 \texttt{Seed} is an array of size \texttt{len} used to initialize the
103  generator. At each hashing step $j$, the \shaun\ algorithm is applied on the
104  input block to obtain a hashed string of 160 bits (20 bytes). Of these,
105  the first $r$ bytes are dropped and the next $s$ bytes are used to build 32-bit
106  random numbers. Each call to the generator returns a 32-bit random number.
107  For example, if $r=2$ and $s=8$, then the 16 ($8r$) most significant bits of
108  the 160-bit string are dropped and the next 64 ($8s$) bits are used to make
109  two 32-bit random numbers which will be returned by the next two
110  calls to the generator. Restrictions: \texttt{len} $\le 55$,
111  $0 \le r \le 19$, $1 \le s \le 20$, and  $r + s \le 20$.
112
113 Let $C = \calh(T)$ denote the \shaun\  operation applied on the original text $T$
114 hashed to the 160-bit string $C$. (When $T$ is too short, it is padded
115 automatically by the \shaun\  algorithm to have the required block length of
116 512 bits.)
117\begin{itemize}
118\item  For the \texttt{OFB} mode, each new block of 160 $C_j$ is
119  obtained by $C_j = \calh(C_{j-1})$, where $C_0 = \calh(\mbox{\texttt{Seed}})$.
120
121\item The \texttt{CTR} mode uses a 440-bit counter $i$ whose initial value is
122  equal to \texttt{Seed}, and which is incremented by 1 at each hashing step $j$.
123  Each new block of 160 bits $C_j$ is obtained by
124  $C_j = \calh(i)$.
125\end{itemize}
126 \endtab
127\code
128
129
130unif01_Gen * ucrypto_CreateISAAC (int flag, unsigned int A[256]);
131\endcode
132  \tab
133   This is the generator \texttt{ISAAC}
134\index{Generator!ISAAC}%
135   (Indirection, Shift, Accumulate, Add, and Count),
136   proposed and implemented by Bob Jenkins Jr. in \cite{rJEN96a}.
137   The version used here is the one recommended for cryptography,
138   with  \texttt{RANDSIZL = 8}.
139   If \texttt{flag = 0}, the array  \texttt{A} is not used and the initial state
140   is obtained from a complicated initialization procedure used in Jenkins'
141   implementation.
142  \richard{In his test program in file \texttt{rand.c}, Jenkins outputs the ISAAC
143   random numbers as \texttt{randrsl[0], randrsl[1], randrsl[2]}, \ldots
144   In TestU01, they are outputted in the order  { \tt randrsl[255], randrsl[254],
145   randrsl[253]}, \ldots, because it is simpler.}
146   If \texttt{flag = 1}, the array \texttt{A} is used and transformed by
147   Jenkins' initialization procedure to obtain the initial state.
148   If \texttt{flag = 2}, the array  \texttt{A} is used as the starting
149   state.  Restriction: \texttt{flag} $\in \{0, 1, 2\}$.
150 \endtab
151
152
153%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
154\guisec{Clean-up functions}
155\code
156
157void ucrypto_DeleteAES (unif01_Gen * gen);
158void ucrypto_DeleteSHA1 (unif01_Gen * gen);
159void ucrypto_DeleteISAAC (unif01_Gen * gen);
160\endcode
161  \tab Frees the dynamic memory used by the generators of this module,
162  and allocated by the corresponding \texttt{Create} function.
163 \endtab
164\code\hide
165#endif
166\endhide\endcode
167