view release on metacpan or  search on metacpan

dropbear/libtomcrypt/doc/crypt.tex  view on Meta::CPAN

If you just want a random stream of bytes initialize the cipher with truly random \textit{key}.
After that you can get a stream of pseudo--random bytes via:
\begin{verbatim}
err = rc4_stream_keystream(&st, out_buffer, out_len);
\end{verbatim}

At the end you have to terminate the state:
\begin{verbatim}
err = rc4_stream_done(&st);
\end{verbatim}

\mysection{Sober128}

Supported key size: must be multiple of 4 bytes

You need to initialize Sober128 with a \textit{key} and a \textit{nonce} (must be multiple of 4 bytes).
\begin{verbatim}
sober128_state st;
err = sober128_stream_setup(&st, key, 16);
err = sober128_stream_setiv(&st, nonce, 12);
\end{verbatim}

For the actual encryption or decryption you to call:
\begin{verbatim}
err = sober128_stream_crypt(&st, in_buffer, in_len, out_buffer);
\end{verbatim}

If you just want a random stream of bytes initialize the cipher with a truly random \textit{key}
and a truly random \textit{nonce}. After that you can get a stream of pseudo--random bytes via:
\begin{verbatim}
err = sober128_stream_keystream(&st, out_buffer, out_len);
\end{verbatim}

At the end you have to terminate the state:
\begin{verbatim}
err = sober128_stream_done(&st);
\end{verbatim}

\chapter{Authenticated Encryption}

Authenticated Encryption - sometimes also called Authenticated Encryption with Associated Data (AEAD) - is a variant of encryption
that provides not only confidentiality (as other symmetric or stream ciphers) but also integrity.

The inputs of Authenticated Encryption are: \textit{key}, \textit{nonce} (sometimes called initialization vector), \textit{plaintext},
optional \textit{header} (sometimes called additional authenticated data - AAD). The outputs are: \textit{ciphertext} and \textit{tag}.

\mysection{EAX Mode}
LibTomCrypt provides support for a mode called EAX\footnote{See
M. Bellare, P. Rogaway, D. Wagner, A Conventional Authenticated-Encryption Mode.} in a manner similar to the way it was intended to be used
by the designers.  First, a short description of what EAX mode is before we explain how to use it.  EAX is a mode that requires a cipher,
CTR and OMAC support and provides encryption and
authentication\footnote{Note that since EAX only requires OMAC and CTR you may use \textit{encrypt only} cipher descriptors with this mode.}.
It is initialized with a random \textit{nonce} that can be shared publicly, a \textit{header} which can be fixed and public, and a random secret symmetric key.

The \textit{header} data is meant to be meta--data associated with a stream that isn't private (e.g., protocol messages).  It can
be added at anytime during an EAX stream, and is part of the authentication tag.  That is, changes in the meta-data can be detected by changes in the output tag.

The mode can then process plaintext producing ciphertext as well as compute a partial checksum.  The actual checksum
called a \textit{tag} is only emitted when the message is finished.  In the interim, the user can process any arbitrary
sized message block to send to the recipient as ciphertext.  This makes the EAX mode especially suited for streaming modes
of operation.

The mode is initialized with the following function.
\index{eax\_init()}
\begin{verbatim}
int eax_init(          eax_state *eax,
                             int  cipher,
             const unsigned char *key,
                   unsigned long  keylen,
             const unsigned char *nonce,
                   unsigned long  noncelen,
             const unsigned char *header,
                   unsigned long  headerlen);
\end{verbatim}

Where \textit{eax} is the EAX state.  The \textit{cipher} parameter is the index of the desired cipher in the descriptor table.
The \textit{key} parameter is the shared secret symmetric key of length \textit{keylen} octets.  The \textit{nonce} parameter is the
random public string of length \textit{noncelen} octets.  The \textit{header} parameter is the random (or fixed or \textbf{NULL}) header for the
message of length \textit{headerlen} octets.

When this function completes, the \textit{eax} state will be initialized such that you can now either have data decrypted or
encrypted in EAX mode.  Note: if \textit{headerlen} is zero you may pass \textit{header} as \textbf{NULL} to indicate there is no initial header data.

To encrypt or decrypt data in a streaming mode use the following.
\index{eax\_encrypt()} \index{eax\_decrypt()}
\begin{verbatim}
int eax_encrypt(          eax_state *eax,
                const unsigned char *pt,
                      unsigned char *ct,
                      unsigned long  length);

int eax_decrypt(          eax_state *eax,
                const unsigned char *ct,
                      unsigned char *pt,
                      unsigned long  length);
\end{verbatim}
The function \textit{eax\_encrypt} will encrypt the bytes in \textit{pt} of \textit{length} octets, and store the ciphertext in
\textit{ct}.  Note: \textit{ct} and \textit{pt} may be the same region in memory.   This function will also send the ciphertext
through the OMAC function.  The function \textit{eax\_decrypt} decrypts \textit{ct}, and stores it in \textit{pt}.  This also allows
\textit{pt} and \textit{ct} to be the same region in memory.

You cannot both encrypt or decrypt with the same \textit{eax} context.  For bi--directional communication you will need to initialize
two EAX contexts (preferably with different headers and nonces).

Note: both of these functions allow you to send the data in any granularity but the order is important.  While
the eax\_init() function allows you to add initial header data to the stream you can also add header data during the
EAX stream with the following.

\index{eax\_addheader()}
\begin{verbatim}
int eax_addheader(          eax_state *eax,
                  const unsigned char *header,
                        unsigned long  length);
\end{verbatim}
This will add the \textit{length} octet from \textit{header} to the given \textit{eax} header.  Once the message is finished, the
\textit{tag} (checksum) may be computed with the following function:

\index{eax\_done()}
\begin{verbatim}
int eax_done(    eax_state *eax,
             unsigned char *tag,
             unsigned long *taglen);
\end{verbatim}
This will terminate the EAX state \textit{eax}, and store up to \textit{taglen} bytes of the message tag in \textit{tag}.  The function
then stores how many bytes of the tag were written out back in to \textit{taglen}.

The EAX mode code can be tested to ensure it matches the test vectors by calling the following function:
\index{eax\_test()}
\begin{verbatim}
int eax_test(void);
\end{verbatim}
This requires that the AES (or Rijndael) block cipher be registered with the cipher\_descriptor table first.

\begin{verbatim}
#include <tomcrypt.h>
int main(void)
{
   int           err;
   eax_state     eax;
   unsigned char pt[64], ct[64], nonce[16], key[16], tag[16];
   unsigned long taglen;

   if (register_cipher(&rijndael_desc) == -1) {
      printf("Error registering Rijndael");

dropbear/libtomcrypt/doc/crypt.tex  view on Meta::CPAN

   }

   /* ... send a header describing the lengths ... */

   /* depending on the protocol and how nonce is
    * generated you may have to send it too... */
   send(socket, nonce, noncelen, 0);

   /* send the aad */
   send(socket, aad, aadlen, 0);

   /* send the ciphertext */
   send(socket, pt, ptlen, 0);

   /* send the tag */
   send(socket, tag, taglen, 0);

   return CRYPT_OK;
}

int main(void)
{
   ccm_state     ccm;
   unsigned char key[16], NONCE[12], pt[PACKET_SIZE];
   int           err, x;
   unsigned long ptlen;

   /* somehow fill key/NONCE with random values */

   /* register AES */
   register_cipher(&aes_desc);

   /* init the CCM state */
   if ((err =
        ccm_init(&ccm, find_cipher("aes"), key, 16, PACKET_SIZE, 16, size(NONCE))) != CRYPT_OK) {
      whine_and_pout(err);
   }

   /* handle us some packets */
   for (;;) {
       ptlen = make_packet_we_want_to_send(pt);

       /* use NONCE as counter (12 byte counter) */
       for (x = 11; x >= 0; x--) {
           if (++NONCE[x]) {
              break;
           }
       }

       if ((err = send_packet(pt, ptlen, NONCE, 12, NULL, 0, &ccm))
           != CRYPT_OK) {
           whine_and_pout(err);
       }
   }
   return EXIT_SUCCESS;
}
\end{verbatim}
\end{small}

\mysection{GCM Mode}
Galois counter mode is an IEEE proposal for authenticated encryption (also it is a planned NIST standard).  Like EAX and OCB mode, it can be used in a streaming capacity
however, unlike EAX it cannot accept \textit{additional authentication data} (meta--data) after plaintext has been processed.  This mode also only works with
block ciphers with a 16--byte block.

A GCM stream is meant to be processed in three modes, one after another.  First, the initialization vector (per session) data is processed.  This should be
unique to every session.  Next, the the optional additional authentication data is processed, and finally the plaintext (or ciphertext depending on the direction).

\subsection{Initialization}
To initialize the GCM context with a secret key call the following function.

\index{gcm\_init()}
\begin{verbatim}
int gcm_init(          gcm_state *gcm,
                             int  cipher,
             const unsigned char *key,
                             int  keylen);
\end{verbatim}
This initializes the GCM state \textit{gcm} for the given cipher indexed by \textit{cipher}, with a secret key \textit{key} of length \textit{keylen} octets.  The cipher
chosen must have a 16--byte block size (e.g., AES).

\subsection{Initialization Vector}
After the state has been initialized (or reset) the next step is to add the session (or packet) initialization vector.  It should be unique per packet encrypted.

\index{gcm\_add\_iv()}
\begin{verbatim}
int gcm_add_iv(          gcm_state *gcm,
               const unsigned char *IV,
                     unsigned long  IVlen);
\end{verbatim}
This adds the initialization vector octets from \textit{IV} of length \textit{IVlen} to the GCM state \textit{gcm}.  You can call this function as many times as required
to process the entire IV.

Note: the GCM protocols provides a \textit{shortcut} for 12--byte IVs where no pre-processing is to be done.  If you want to minimize per packet latency it is ideal
to only use 12--byte IVs.  You can just increment it like a counter for each packet.

\subsection{Additional Authentication Data}
After the entire IV has been processed, the additional authentication data can be processed.  Unlike the IV, a packet/session does not require additional
authentication data (AAD) for security.  The AAD is meant to be used as side--channel data you want to be authenticated with the packet.  Note:  once
you begin adding AAD to the GCM state you cannot return to adding IV data until the state has been reset.

\index{gcm\_add\_aad()}
\begin{verbatim}
int gcm_add_aad(          gcm_state *gcm,
                const unsigned char *adata,
                      unsigned long  adatalen);
\end{verbatim}
This adds the additional authentication data \textit{adata} of length \textit{adatalen} to the GCM state \textit{gcm}.

\subsection{Plaintext Processing}
After the AAD has been processed, the plaintext (or ciphertext depending on the direction) can be processed.

\index{gcm\_process()}
\begin{verbatim}
int gcm_process(    gcm_state *gcm,
                unsigned char *pt,
                unsigned long  ptlen,
                unsigned char *ct,
                          int  direction);
\end{verbatim}
This processes message data where \textit{pt} is the plaintext and \textit{ct} is the ciphertext.  The length of both are equal and stored in \textit{ptlen}.  Depending on
the mode \textit{pt} is the input and \textit{ct} is the output (or vice versa).  When \textit{direction} equals \textbf{GCM\_ENCRYPT} the plaintext is read,