dropbear: libtomcrypt/crypt.tex comparison

comparison libtomcrypt/crypt.tex @ 1437:871b18fd7065 fuzz

merge from main (libtommath/libtomcrypt/curve25510-donna updates)

author	Matt Johnston <matt@ucc.asn.au>
date	Sat, 24 Jun 2017 22:51:45 +0800
parents	f849a5ca2efc
children

comparison

equal deleted inserted replaced

-:41dca1e5ea34
+:871b18fd7065
 The project is hereby released as public domain.
 \mysection{Patent Disclosure}
 The author (Tom St Denis) is not a patent lawyer so this section is not to be treated as legal advice.  To the best
-of the authors knowledge the only patent related issues within the library are the RC5 and RC6 symmetric block ciphers.
+of the author's knowledge the only patent related issues within the library are the RC5 and RC6 symmetric block ciphers.
 They can be removed from a build by simply commenting out the two appropriate lines in \textit{tomcrypt\_custom.h}.  The rest
 of the ciphers and hashes are patent free or under patents that have since expired.
 The RC2 and RC4 symmetric ciphers are not under patents but are under trademark regulations.  This means you can use
 the ciphers you just can't advertise that you are doing so.
 \hline RC6-32/20/b & rc6\_desc & 16 & 8 $\ldots$ 128 & 20 \\
 \hline SAFER+ & saferp\_desc &16 & 16, 24, 32 & 8, 12, 16 \\
 \hline AES & aes\_desc & 16 & 16, 24, 32 & 10, 12, 14 \\
 & aes\_enc\_desc & 16 & 16, 24, 32 & 10, 12, 14 \\
 \hline Twofish & twofish\_desc & 16 & 16, 24, 32 & 16 \\
-\hline DES & des\_desc & 8 & 7 & 16 \\
+\hline DES & des\_desc & 8 & 8 & 16 \\
-\hline 3DES (EDE mode) & des3\_desc & 8 & 21 & 16 \\
+\hline 3DES (EDE mode) & des3\_desc & 8 & 24 & 16 \\
 \hline CAST5 (CAST-128) & cast5\_desc & 8 & 5 $\ldots$ 16 & 12, 16 \\
 \hline Noekeon & noekeon\_desc & 16 & 16 & 16 \\
 \hline Skipjack & skipjack\_desc & 8 & 10 & 32 \\
 \hline Anubis & anubis\_desc & 16 & 16 $\ldots$ 40 & 12 $\ldots$ 18 \\
 \hline Khazad & khazad\_desc & 8 & 16 & 8 \\
 length as the block size\footnote{In other words the size of a block of plaintext for the cipher, e.g. 8 for DES, 16 for AES, etc.}
 of the cipher you choose.  It is important that the IV  be random for each unique message you want to encrypt.  The
 parameters \textit{key}, \textit{keylen} and \textit{num\_rounds} are the same as in the XXX\_setup() function call.  The final parameter
 is a pointer to the structure you want to hold the information for the mode of operation.
+The routines return {\bf CRYPT\_OK} if the cipher initialized correctly, otherwise, they return an error code.
+\subsubsection{CTR Mode}
 In the case of CTR mode there is an additional parameter \textit{ctr\_mode} which specifies the mode that the counter is to be used in.
 If \textbf{CTR\_COUNTER\_ LITTLE\_ENDIAN} was specified then the counter will be treated as a little endian value.  Otherwise, if
 \textbf{CTR\_COUNTER\_BIG\_ENDIAN} was specified the counter will be treated as a big endian value.  As of v1.15 the RFC 3686 style of
 increment then encrypt is also supported.  By OR'ing \textbf{LTC\_CTR\_RFC3686} with the CTR \textit{mode} value, ctr\_start() will increment
 the counter before encrypting it for the first time.
-The routines return {\bf CRYPT\_OK} if the cipher initialized correctly, otherwise, they return an error code.
+As of V1.17, the library supports variable length counters for CTR mode.  The (optional) counter length is specified by OR'ing the octet
+length of the counter against the \textit{ctr\_mode} parameter.  The default, zero, indicates that a full block length counter will be used.  This also
+ensures backwards compatibility with software that uses older versions of the library.
+\begin{small}
+\begin{verbatim}
+symmetric_CTR ctr;
+int           err;
+unsigned char IV[16], key[16];
+/* use a 32-bit little endian counter */
+if ((err = ctr_start(find_cipher("aes"),
+IV, key, 16, 0,
+CTR_COUNTER_LITTLE_ENDIAN | 4,
+&ctr)) != CRYPT_OK) {
+handle_error(err);
+}
+\end{verbatim}
+\end{small}
+Changing the counter size has little (really no) effect on the performance of the CTR chaining mode.  It is provided for compatibility
+with other software (and hardware) which have smaller fixed sized counters.
 \subsection{Encryption and Decryption}
 To actually encrypt or decrypt the following routines are provided:
 \index{ecb\_encrypt()} \index{ecb\_decrypt()} \index{cfb\_encrypt()} \index{cfb\_decrypt()}
 \index{cbc\_encrypt()} \index{cbc\_decrypt()} \index{ofb\_encrypt()} \index{ofb\_decrypt()} \index{ctr\_encrypt()} \index{ctr\_decrypt()}
 \index{lrw\_done()}
 \begin{verbatim}
 int lrw_done(symmetric_LRW *lrw);
 \end{verbatim}
+\subsection{XTS Mode}
+As of v1.17, LibTomCrypt supports XTS mode with code donated by Elliptic Semiconductor Inc.\footnote{www.ellipticsemi.com}.
+XTS is a chaining mode for 128--bit block ciphers, recommended by IEEE (P1619)
+for disk encryption.  It is meant to be an encryption mode with random access to the message data without compromising privacy.  It requires two private keys (of equal
+length) to perform the encryption process.  Each encryption invocation includes a sector number or unique identifier specified as a 128--bit string.
+To initialize XTS mode use the following function call:
+\index{xts\_start()}
+\begin{verbatim}
+int xts_start(                int  cipher,
+const unsigned char *key1,
+const unsigned char *key2,
+unsigned long  keylen,
+int  num_rounds,
+symmetric_xts *xts)
+\end{verbatim}
+This will start the XTS mode with the two keys pointed to by \textit{key1} and \textit{key2} of length \textit{keylen} octets each.
+To encrypt or decrypt a sector use the following calls:
+\index{xts\_encrypt()} \index{xts\_decrypt()}
+\begin{verbatim}
+int xts_encrypt(
+const unsigned char *pt, unsigned long ptlen,
+unsigned char *ct,
+const unsigned char *tweak,
+symmetric_xts *xts);
+int xts_decrypt(
+const unsigned char *ct, unsigned long ptlen,
+unsigned char *pt,
+const unsigned char *tweak,
+symmetric_xts *xts);
+\end{verbatim}
+The first will encrypt the plaintext pointed to by \textit{pt} of length \textit{ptlen} octets, and store the ciphertext in the array pointed to by
+\textit{ct}.  It uses the 128--bit tweak pointed to by \textit{tweak} to encrypt the block.  The decrypt function performs the opposite operation.  Both
+functions support ciphertext stealing (blocks that are not multiples of 16 bytes).
+The P1619 specification states the tweak for sector number shall be represented as a 128--bit little endian string.
+To terminate the XTS state call the following function:
+\index{xts\_done()}
+\begin{verbatim}
+void xts_done(symmetric_xts *xts);
+\end{verbatim}
 \subsection{F8 Mode}
 \index{F8 Mode}
 The F8 Chaining mode (see RFC 3711 for instance) is yet another chaining mode for block ciphers.  It behaves much like CTR mode in that it XORs a keystream
 against the plaintext to encrypt.  F8 mode comes with the additional twist that the counter value is secret, encrypted by a \textit{salt key}.  We
 \begin{verbatim}
 int hmac_process(         hmac_state *hmac,
 const unsigned char *in,
 unsigned long  inlen);
 \end{verbatim}
-\textit{hmac} is the HMAC state you are working with. \textit{buf} is the array of octets to send into the HMAC process.  \textit{len} is the
+\textit{hmac} is the HMAC state you are working with. \textit{in} is the array of octets to send into the HMAC process.  \textit{inlen} is the
-number of octets to process.  Like the hash process routines you can send the data in arbitrarily sized chunks. When you
+number of octets to process.  Like the hash process routines, you can send the data in arbitrarily sized chunks. When you
 are finished with the HMAC process you must call the following function to get the HMAC code:
 \index{hmac\_done()}
 \begin{verbatim}
 int hmac_done(   hmac_state *hmac,
 unsigned char *out,
 unsigned long  keylen);
 \end{verbatim}
 This will initialize the XCBC--MAC state \textit{xcbc}, with the key specified in \textit{key} of length \textit{keylen} octets.  The cipher indicated
 by the \textit{cipher} index can be either a 64 or 128--bit block cipher.  This will return \textbf{CRYPT\_OK} on success.
+\index{LTC\_XCBC\_PURE}
+It is possible to use XCBC in a three key mode by OR'ing the value \textbf{LTC\_XCBC\_PURE} against the \textit{keylen} parameter.  In this mode, the key is
+interpretted as three keys.  If the cipher has a block size of $n$ octets, the first key is then $keylen - 2n$ octets and is the encryption key.  The next
+$2n$ octets are the $K_1$ and $K_2$ padding keys (used on the last block).  For example, to use AES--192 \textit{keylen} should be $24 + 2 \cdot 16 = 56$ octets.
+The three keys are interpretted as if they were concatenated in the \textit{key} buffer.
 To process data through XCBC--MAC use the following function:
 \index{xcbc\_process()}
 \begin{verbatim}
 \input{crypt.ind}
 \end{document}
 % $Source: /cvs/libtom/libtomcrypt/crypt.tex,v $
-% $Revision: 1.123 $
+% $Revision: 1.128 $
-% $Date: 2006/12/16 19:08:17 $
+% $Date: 2007/03/10 23:59:54 $

Mercurial > dropbear

comparison libtomcrypt/crypt.tex @ 1437:871b18fd7065 fuzz