|
47 | 47 | \def\gap{\vspace{0.5ex}} |
48 | 48 | \makeindex |
49 | 49 | \begin{document} |
50 | | -\title{LibTomCrypt \\ Version 1.08} |
| 50 | +\title{LibTomCrypt \\ Version 1.09} |
51 | 51 | \author{Tom St Denis \\ |
52 | 52 | \\ |
53 | 53 | tomstdenis@gmail.com \\ |
@@ -520,6 +520,18 @@ \section{The Cipher Descriptors} |
520 | 520 | unsigned char *ct, |
521 | 521 | unsigned long blocks, unsigned char *IV, |
522 | 522 | int mode, symmetric_key *skey); |
| 523 | + int (*accel_lrw_encrypt)(const unsigned char *pt, |
| 524 | + unsigned char *ct, |
| 525 | + unsigned long blocks, |
| 526 | + unsigned char *IV, |
| 527 | + const unsigned char *tweak, |
| 528 | + symmetric_key *skey); |
| 529 | + int (*accel_lrw_decrypt)(const unsigned char *ct, |
| 530 | + unsigned char *pt, |
| 531 | + unsigned long blocks, |
| 532 | + unsigned char *IV, |
| 533 | + const unsigned char *tweak, |
| 534 | + symmetric_key *skey); |
523 | 535 | int (*accel_ccm_memory)( |
524 | 536 | const unsigned char *key, unsigned long keylen, |
525 | 537 | symmetric_key *uskey, |
@@ -938,6 +950,61 @@ \subsection{Examples} |
938 | 950 | \end{verbatim} |
939 | 951 | \end{small} |
940 | 952 |
|
| 953 | +\subsection{LRW Mode} |
| 954 | + |
| 955 | +LRW mode is a cipher mode which is meant for indexed encryption like used to handle storage media. It is meant to have efficient seeking and overcome the |
| 956 | +security problems of ECB mode while not increasing the storage requirements. It is used much like any other chaining mode except with two key differences. |
| 957 | + |
| 958 | +The key is specified as two strings the first key $K_1$ is the (normally AES) key and can be any length (typically 16, 24 or 32 octets long). The second key |
| 959 | +$K_2$ is the ``tweak'' key and is always 16 octets long. The tweak value is \textbf{NOT} a nonce or IV value it must be random and secret. |
| 960 | + |
| 961 | +To initialize LRW mode use: |
| 962 | + |
| 963 | +\index{lrw\_start()} |
| 964 | +\begin{verbatim} |
| 965 | +int lrw_start( int cipher, |
| 966 | + const unsigned char *IV, |
| 967 | + const unsigned char *key, int keylen, |
| 968 | + const unsigned char *tweak, |
| 969 | + int num_rounds, |
| 970 | + symmetric_LRW *lrw); |
| 971 | +\end{verbatim} |
| 972 | + |
| 973 | +This will initialize the LRW context with the given (16 octet) ``IV'', cipher $K_1$ ``key'' of length ``keylen'' octets and the (16 octet) $K_2$ ``tweak''. |
| 974 | +While LRW was specified to be used only with AES, LibTomCrypt will allow any 128--bit block cipher to be specified as indexed by ``cipher''. The |
| 975 | +number of rounds for the block cipher ``num\_rounds'' can be 0 to use the default number of rounds for the given cipher. |
| 976 | + |
| 977 | +To process data use the following functions: |
| 978 | + |
| 979 | +\index{lrw\_encrypt()} \index{lrw\_decrypt()} |
| 980 | +\begin{verbatim} |
| 981 | +int lrw_encrypt(const unsigned char *pt, unsigned char *ct, |
| 982 | + unsigned long len, symmetric_LRW *lrw); |
| 983 | +int lrw_decrypt(const unsigned char *ct, unsigned char *pt, |
| 984 | + unsigned long len, symmetric_LRW *lrw); |
| 985 | +\end{verbatim} |
| 986 | + |
| 987 | +These will encrypt (or decrypt) the plaintext to the ciphertext buffer (or vice versa). The length is specified by ``len'' in octets but must be a multiple |
| 988 | +of 16. |
| 989 | + |
| 990 | +To manipulate the IV use the following functions: |
| 991 | + |
| 992 | +\index{lrw\_getiv()} \index{lrw\_setiv()} |
| 993 | +\begin{verbatim} |
| 994 | +int lrw_getiv(unsigned char *IV, unsigned long *len, symmetric_LRW *lrw); |
| 995 | +int lrw_setiv(const unsigned char *IV, unsigned long len, symmetric_LRW *lrw); |
| 996 | +\end{verbatim} |
| 997 | + |
| 998 | +These will get or set the 16--octet IV. Note that setting the IV is the same as ``seeking'' and unlike other modes is not a free operation. It requires |
| 999 | +updating the entire tweak which is slower than sequential use. Avoid seeking excessively in performance constrained code. |
| 1000 | + |
| 1001 | +To terminate the LRW state use the following: |
| 1002 | + |
| 1003 | +\index{lrw\_done()} |
| 1004 | +\begin{verbatim} |
| 1005 | +int lrw_done(symmetric_LRW *lrw); |
| 1006 | +\end{verbatim} |
| 1007 | + |
941 | 1008 | \section{Encrypt and Authenticate Modes} |
942 | 1009 |
|
943 | 1010 | \subsection{EAX Mode} |
@@ -4306,6 +4373,32 @@ \section{Ciphers} |
4306 | 4373 | unsigned long blocks, unsigned char *IV, |
4307 | 4374 | int mode, symmetric_key *skey); |
4308 | 4375 |
|
| 4376 | + /** Accelerated LRW |
| 4377 | + @param pt Plaintext |
| 4378 | + @param ct Ciphertext |
| 4379 | + @param blocks The number of complete blocks to process |
| 4380 | + @param IV The initial value (input/output) |
| 4381 | + @param tweak The LRW tweak |
| 4382 | + @param skey The scheduled key context |
| 4383 | + @return CRYPT_OK if successful |
| 4384 | + */ |
| 4385 | + int (*accel_lrw_encrypt)(const unsigned char *pt, unsigned char *ct, |
| 4386 | + unsigned long blocks, unsigned char *IV, |
| 4387 | + const unsigned char *tweak, symmetric_key *skey); |
| 4388 | +
|
| 4389 | + /** Accelerated LRW |
| 4390 | + @param ct Ciphertext |
| 4391 | + @param pt Plaintext |
| 4392 | + @param blocks The number of complete blocks to process |
| 4393 | + @param IV The initial value (input/output) |
| 4394 | + @param tweak The LRW tweak |
| 4395 | + @param skey The scheduled key context |
| 4396 | + @return CRYPT_OK if successful |
| 4397 | + */ |
| 4398 | + int (*accel_lrw_decrypt)(const unsigned char *ct, unsigned char *pt, |
| 4399 | + unsigned long blocks, unsigned char *IV, |
| 4400 | + const unsigned char *tweak, symmetric_key *skey); |
| 4401 | +
|
4309 | 4402 | /** Accelerated CCM packet (one-shot) |
4310 | 4403 | @param key The secret key to use |
4311 | 4404 | @param keylen The length of the secret key (octets) |
@@ -4432,6 +4525,18 @@ \subsubsection{Accelerated CTR} |
4432 | 4525 |
|
4433 | 4526 | The accelerator will only be used to encrypt whole blocks. Partial blocks are always handled in software. |
4434 | 4527 |
|
| 4528 | +\subsubsection{Accelerated LRW} |
| 4529 | +These functions are meant for accelerated LRW. They process blocks of input in lengths of multiples of 16 octets. They must accept the ``IV'' and ``tweak'' |
| 4530 | +state variables and updated them prior to returning. Note that you may want to disable \textbf{LRW\_TABLES} in ``tomcrypt\_custom.h'' if you intend |
| 4531 | +to use accelerators for LRW. |
| 4532 | +
|
| 4533 | +While both encrypt and decrypt accelerators are not required it is suggested as it makes lrw\_setiv() more efficient. |
| 4534 | +
|
| 4535 | +Note that calling lrw\_done() will only invoke the cipher\_descriptor[].done() function on the ``symmetric\_key'' parameter of the LRW state. That means |
| 4536 | +if your device requires any (LRW specific) resources you should free them in your ciphers() done function. The simplest way to think of it is to write |
| 4537 | +the plugin solely to do LRW with the cipher. That way cipher\_descriptor[].setup() means to init LRW resources and cipher\_descriptor[].done() means to |
| 4538 | +free them. |
| 4539 | +
|
4435 | 4540 | \subsubsection{Accelerated CCM} |
4436 | 4541 | This function is meant for accelerated CCM encryption or decryption. It processes the entire packet in one call. You can optimize the work flow somewhat |
4437 | 4542 | by allowing the caller to call the setup() function first to schedule the key if your accelerator cannot do the key schedule on the fly (for instance). This |
@@ -5076,5 +5181,5 @@ \subsection{RSA Functions} |
5076 | 5181 | \end{document} |
5077 | 5182 |
|
5078 | 5183 | % $Source: /cvs/libtom/libtomcrypt/crypt.tex,v $ |
5079 | | -% $Revision: 1.59 $ |
5080 | | -% $Date: 2005/11/24 01:53:18 $ |
| 5184 | +% $Revision: 1.62 $ |
| 5185 | +% $Date: 2006/01/26 18:29:02 $ |
0 commit comments