You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
parameters \textit{key}, \textit{keylen} and \textit{num\_rounds} are the same as in the XXX\_setup() function call. The final parameter
880
880
is a pointer to the structure you want to hold the information for the mode of operation.
881
881
882
+
The routines return {\bf CRYPT\_OK} if the cipher initialized correctly, otherwise, they return an error code.
882
883
884
+
\subsubsection{CTR Mode}
883
885
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.
884
886
If \textbf{CTR\_COUNTER\_ LITTLE\_ENDIAN} was specified then the counter will be treated as a little endian value. Otherwise, if
885
887
\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
886
888
increment then encrypt is also supported. By OR'ing \textbf{LTC\_CTR\_RFC3686} with the CTR \textit{mode} value, ctr\_start() will increment
887
889
the counter before encrypting it for the first time.
888
890
889
-
The routines return {\bf CRYPT\_OK} if the cipher initialized correctly, otherwise, they return an error code.
891
+
As of V1.17, the library supports variable length counters for CTR mode. The (optional) counter length is specified by OR'ing the octet
892
+
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
893
+
ensures backwards compatibility with software that uses older versions of the library.
894
+
895
+
\begin{small}
896
+
\begin{verbatim}
897
+
symmetric_CTR ctr;
898
+
int err;
899
+
unsigned char IV[16], key[16];
900
+
901
+
/* use a 32-bit little endian counter */
902
+
if ((err = ctr_start(find_cipher("aes"),
903
+
IV, key, 16, 0,
904
+
CTR_COUNTER_LITTLE_ENDIAN | 4,
905
+
&ctr)) != CRYPT_OK) {
906
+
handle_error(err);
907
+
}
908
+
\end{verbatim}
909
+
\end{small}
910
+
911
+
Changing the counter size has little (really no) effect on the performance of the CTR chaining mode. It is provided for compatibility
912
+
with other software (and hardware) which have smaller fixed sized counters.
890
913
891
914
\subsection{Encryption and Decryption}
892
915
To actually encrypt or decrypt the following routines are provided:
@@ -1093,6 +1116,55 @@ \subsection{LRW Mode}
1093
1116
int lrw_done(symmetric_LRW *lrw);
1094
1117
\end{verbatim}
1095
1118
1119
+
\subsection{XTS Mode}
1120
+
As of v1.17, LibTomCrypt supports XTS mode with code donated by Elliptic Semiconductor Inc.\footnote{www.ellipticsemi.com}.
1121
+
XTS is a chaining mode for 128--bit block ciphers, recommended by IEEE (P1619)
1122
+
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
1123
+
length) to perform the encryption process. Each encryption invocation includes a sector number or unique identifier specified as a 128--bit string.
1124
+
1125
+
To initialize XTS mode use the following function call:
1126
+
1127
+
\index{xts\_start()}
1128
+
\begin{verbatim}
1129
+
int xts_start( int cipher,
1130
+
const unsigned char *key1,
1131
+
const unsigned char *key2,
1132
+
unsigned long keylen,
1133
+
int num_rounds,
1134
+
symmetric_xts *xts)
1135
+
\end{verbatim}
1136
+
This will start the XTS mode with the two keys pointed to by \textit{key1} and \textit{key2} of length \textit{keylen} octets each.
1137
+
1138
+
To encrypt or decrypt a sector use the following calls:
1139
+
1140
+
\index{xts\_encrypt()} \index{xts\_decrypt()}
1141
+
\begin{verbatim}
1142
+
int xts_encrypt(
1143
+
const unsigned char *pt, unsigned long ptlen,
1144
+
unsigned char *ct,
1145
+
const unsigned char *tweak,
1146
+
symmetric_xts *xts);
1147
+
1148
+
int xts_decrypt(
1149
+
const unsigned char *ct, unsigned long ptlen,
1150
+
unsigned char *pt,
1151
+
const unsigned char *tweak,
1152
+
symmetric_xts *xts);
1153
+
\end{verbatim}
1154
+
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
1155
+
\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
1156
+
functions support ciphertext stealing (blocks that are not multiples of 16 bytes).
1157
+
1158
+
The P1619 specification states the tweak for sector number shall be represented as a 128--bit little endian string.
1159
+
1160
+
To terminate the XTS state call the following function:
1161
+
1162
+
\index{xts\_done()}
1163
+
\begin{verbatim}
1164
+
void xts_done(symmetric_xts *xts);
1165
+
\end{verbatim}
1166
+
1167
+
1096
1168
\subsection{F8 Mode}
1097
1169
\index{F8 Mode}
1098
1170
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
\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
2102
-
number of octets to process. Like the hash process routines you can send the data in arbitrarily sized chunks. When you
2173
+
\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
2174
+
number of octets to process. Like the hash process routines, you can send the data in arbitrarily sized chunks. When you
2103
2175
are finished with the HMAC process you must call the following function to get the HMAC code:
2104
2176
\index{hmac\_done()}
2105
2177
\begin{verbatim}
@@ -2511,6 +2583,13 @@ \subsection{Example}
2511
2583
This will initialize the XCBC--MAC state \textit{xcbc}, with the key specified in \textit{key} of length \textit{keylen} octets. The cipher indicated
2512
2584
by the \textit{cipher} index can be either a 64 or 128--bit block cipher. This will return \textbf{CRYPT\_OK} on success.
2513
2585
2586
+
\index{LTC\_XCBC\_PURE}
2587
+
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
2588
+
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
2589
+
$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\cdot16 = 56$ octets.
2590
+
The three keys are interpretted as if they were concatenated in the \textit{key} buffer.
2591
+
2592
+
2514
2593
To process data through XCBC--MAC use the following function:
0 commit comments