80
80
\chapter{Introduction}
81
81
\section{What is the LibTomCrypt?}
82
LibTomCrypt is a portable ANSI C cryptographic library that supports symmetric ciphers, one-way hashes,
83
pseudo-random number generators, public key cryptography (via RSA,DH or ECC/DH) and a plethora of support
84
routines. It is designed to compile out of the box with the GNU C Compiler (GCC) version 2.95.3 (and higher)
85
and with MSVC version 6 in win32.
87
The library has been successfully tested on quite a few other platforms ranging from the ARM7TDMI in a
88
Gameboy Advanced to various PowerPC processors and even the MIPS processor in the PlayStation 2. Suffice it
89
to say the code is portable.
91
The library is designed so new ciphers/hashes/PRNGs can be added at runtime and the existing API (and helper API functions) will
92
be able to use the new designs automatically. There exist self-check functions for each cipher and hash to ensure that
93
they compile and execute to the published design specifications. The library also performs extensive parameter error checking
94
and will give verbose error messages when possible.
96
Essentially the library saves the time of having to implement the ciphers, hashes, prngs yourself. Typically implementing
97
useful cryptography is an error prone business which means anything that can save considerable time and effort is a good
82
LibTomCrypt is a portable ISO C cryptographic library that is meant to be a toolset for cryptographers who are
83
designing a cryptosystem. It supports symmetric ciphers, one-way hashes, pseudo-random number generators,
84
public key cryptography (via PKCS \#1 RSA, DH or ECCDH) and a plethora of support
87
The library was designed such that new ciphers/hashes/PRNGs can be added at runtime and the existing API
88
(and helper API functions) are able to use the new designs automatically. There exists self-check functions for each
89
block cipher and hash function to ensure that they compile and execute to the published design specifications. The library
90
also performs extensive parameter error checking to prevent any number of runtime exploits or errors.
100
92
\subsection{What the library IS for?}
102
The library typically serves as a basis for other protocols and message formats. For example, it should be possible to
103
take the RSA routines out of this library, apply the appropriate message padding and get PKCS compliant RSA routines.
104
Similarly SSL protocols could be formed on top of the low-level symmetric cipher functions. The goal of this package is
105
to provide these low level core functions in a robust and easy to use fashion.
107
The library also serves well as a toolkit for applications where they don't need to be OpenPGP, PKCS, etc. compliant.
108
Included are fully operational public key routines for encryption, decryption, signature generation and verification.
109
These routines are fully portable but are not conformant to any known set of standards\footnote{With the exception of
110
the RSA code which is based on the PKCS \#1 standards.}. They are all based on established
111
number theory and cryptography.
113
\subsection{What the library IS NOT for?}
115
The library is not designed to be in anyway an implementation of the SSL or OpenPGP standards. The library
116
is not designed to be compliant with any known form of API or programming hierarchy. It is not a port of any other
117
library and it is not platform specific (like the MS CSP). So if you're looking to drop in some buzzword
118
compliant crypto library this is not for you. The library has been written from scratch to provide basic functions as
119
well as non-standard higher level functions.
121
This is not to say that the library is a ``homebrew'' project. All of the symmetric ciphers and one-way hash functions
122
conform to published test vectors. The public key functions are derived from publicly available material and the majority
123
of the code has been reviewed by a growing community of developers.
125
\subsubsection{Why not?}
126
You may be asking why I didn't choose to go all out and support standards like P1363, PKCS and the whole lot. The reason
127
is quite simple too much money gets in the way. When I tried to access the P1363 draft documents and was denied (it
128
requires a password) I realized that they're just a business anyways. See what happens is a company will sit down and
129
invent a ``standard''. Then they try to sell it to as many people as they can. All of a sudden this ``standard'' is
130
everywhere. Then the standard is updated every so often to keep people dependent. Then you become RSA. If people are
131
supposed to support these standards they had better make them more accessible.
94
The library serves as a toolkit for developers who have to solve cryptographic problems. Out of the box LibTomCrypt
95
does not process SSL or OpenPGP messages, it doesn't read x.591 certificates or write PEM encoded data. It does, however,
96
provide all of the tools required to build such functionality. LibTomCrypt was designed to be a flexible library that
97
was not tied to any particular cryptographic problem.
133
99
\section{Why did I write it?}
134
100
You may be wondering, ``Tom, why did you write a crypto library. I already have one.''. Well the reason falls into
468
479
The number of rounds of most ciphers is not an option you can change. Only RC5 allows you to change the number of
469
480
rounds. By passing zero as the number of rounds all ciphers will use their default number of rounds. Generally the
470
ciphers are configured such that the default number of rounds provide adequate security for the given block size.
481
ciphers are configured such that the default number of rounds provide adequate security for the given block and key
472
484
\section{The Cipher Descriptors}
473
485
\index{Cipher Descriptor}
474
486
To facilitate automatic routines an array of cipher descriptors is provided in the array ``cipher\_descriptor''. An element
475
487
of this array has the following format:
478
491
struct _cipher_descriptor {
480
unsigned long min_key_length, max_key_length,
481
block_length, default_rounds;
482
int (*setup) (const unsigned char *key, int keylength,
483
int num_rounds, symmetric_key *skey);
484
void (*ecb_encrypt)(const unsigned char *pt, unsigned char *ct,
486
void (*ecb_decrypt)(const unsigned char *ct, unsigned char *pt,
489
int (*keysize) (int *desired_keysize);
498
int (*setup)(const unsigned char *key, int keylen, int num_rounds, symmetric_key *skey);
499
void (*ecb_encrypt)(const unsigned char *pt, unsigned char *ct, symmetric_key *skey);
500
void (*ecb_decrypt)(const unsigned char *ct, unsigned char *pt, symmetric_key *skey);
502
void (*done)(symmetric_key *skey);
503
int (*keysize)(int *keysize);
505
void (*accel_ecb_encrypt)(const unsigned char *pt,
507
unsigned long blocks, symmetric_key *skey);
508
void (*accel_ecb_decrypt)(const unsigned char *ct,
510
unsigned long blocks, symmetric_key *skey);
511
void (*accel_cbc_encrypt)(const unsigned char *pt,
513
unsigned long blocks, unsigned char *IV,
514
symmetric_key *skey);
515
void (*accel_cbc_decrypt)(const unsigned char *ct,
517
unsigned long blocks, unsigned char *IV,
518
symmetric_key *skey);
519
void (*accel_ctr_encrypt)(const unsigned char *pt,
521
unsigned long blocks, unsigned char *IV,
522
int mode, symmetric_key *skey);
523
void (*accel_ccm_memory)(
524
const unsigned char *key, unsigned long keylen,
525
const unsigned char *nonce, unsigned long noncelen,
526
const unsigned char *header, unsigned long headerlen,
527
unsigned char *pt, unsigned long ptlen,
529
unsigned char *tag, unsigned long *taglen,
493
Where ``name'' is the lower case ASCII version of the name. The fields ``min\_key\_length'', ``max\_key\_length'' and
494
``block\_length'' are all the number of bytes not bits. As a good rule of thumb it is assumed that the cipher supports
536
Where ``name'' is the lower case ASCII version of the name. The fields ``min\_key\_length'' and ``max\_key\_length''
537
are the minimum and maximum key sizes in bytes. The ``block\_length'' member is the block size of the cipher
538
in bytes. As a good rule of thumb it is assumed that the cipher supports
495
539
the min and max key lengths but not always everything in between. The ``default\_rounds'' field is the default number
496
540
of rounds that will be used.
1119
1191
Similarly this will OCB decrypt and compare the internally computed tag against the tag provided. ``res'' is set
1194
\subsection{CCM Mode}
1195
CCM is a NIST proposal for Encrypt+Authenticate that is centered around using AES (or any 16--byte cipher) as a primitive. Unlike EAX and OCB mode
1196
it is only meant for ``packet'' mode where the length of the input is known in advance. Since it is a packet mode function CCM only has one
1197
function that performs the protocol.
1199
\index{ccm\_memory()}
1201
int ccm_memory(int cipher,
1202
const unsigned char *key, unsigned long keylen,
1203
const unsigned char *nonce, unsigned long noncelen,
1204
const unsigned char *header, unsigned long headerlen,
1205
unsigned char *pt, unsigned long ptlen,
1207
unsigned char *tag, unsigned long *taglen,
1211
This performs the ``CCM'' operation on the data. The ``cipher'' variable indicates which cipher in the descriptor table to use. It must have a
1212
16--byte block size for CCM. The key is ``key'' with a length of ``keylen'' octets. The nonce or salt is ``nonce'' of
1213
length ``noncelen'' octets. The header is meta--data you want to send with the message but not have encrypted, it is stored in ``header''
1214
of length ``headerlen'' octets. The header can be zero octets long (if $headerlen = 0$ then you can pass ``header'' as \textbf{NULL}).
1216
The plaintext is stored in ``pt'' and the ciphertext in ``ct''. The length of both are expected to be equal and is passed in as ``ptlen''. It is
1217
allowable that $pt = ct$. The ``direction'' variable indicates whether encryption (direction $=$ \textbf{CCM\_ENCRYPT}) or
1218
decryption (direction $=$ \textbf{CCM\_DECRYPT}) is to be performed.
1220
As implemented this copy of CCM cannot handle a header or plaintext longer than $2^{32} - 1$ octets long.
1222
You can test the implementation of CCM with the following function.
1229
This will return \textbf{CRYPT\_OK} if the CCM routine passes known test vectors.
1231
\subsection{GCM Mode}
1232
Galois counter mode is an IEEE proposal for authenticated encryption. Like EAX and OCB it can be used in a streaming capacity however, unlike EAX it cannot
1233
accept ``additional authentication data'' (meta--data) after plaintext has been processed. This mode also only works with block ciphers with a sixteen
1236
A GCM stream is meant to be processed in three modes each one sequential serial. First the initial vector (per session) data is processed. This should be
1237
unique to every session. Next the the optional additional authentication data is processed and finally the plaintext.
1239
\subsubsection{Initialization}
1240
To initialize the GCM context with a secret key call the following function.
1244
int gcm_init(gcm_state *gcm, int cipher,
1245
const unsigned char *key, int keylen);
1247
This initializes the GCM state ``gcm'' for the given cipher indexed by ``cipher'' with a secret key ``key'' of length ``keylen'' octets. The cipher chosen
1248
must have a 16--byte block size (e.g. AES).
1250
\subsubsection{Initial Vector}
1251
After the state has been initialized (or reset) the next step is to add the session (or packet) initial vector. It should be unique per packet encrypted.
1253
\index{gcm\_add\_iv()}
1255
int gcm_add_iv(gcm_state *gcm,
1256
const unsigned char *IV, unsigned long IVlen);
1259
This adds the initial vector octets from ``IV'' of length ``IVlen'' to the GCM state ``gcm''. You can call this function as many times as required
1260
to process the entire IV.
1262
Note that the GCM protocols provides a ``shortcut'' for 12--byte IVs where no preprocessing is to be done. If you want to minimize per packet latency it's ideal
1263
to only use 12--byte IVs. You can just increment it like a counter for each packet and the CTR [privacy] will be ensured.
1265
\subsubsection{Additional Authentication Data}
1266
After the entire IV has been processed the additional authentication data can be processed. Unlike the IV a packet/session does not require additional
1267
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 that once
1268
you begin adding AAD to the GCM state you cannot return to adding IV data until the state is reset.
1270
\index{gcm\_add\_aad()}
1272
int gcm_add_aad(gcm_state *gcm,
1273
const unsigned char *adata, unsigned long adatalen);
1275
This adds the additional authentication data ``adata'' of length ``adatalen'' to the GCM state ``gcm''.
1277
\subsubsection{Plaintext Processing}
1278
After the AAD has been processed the plaintext (or ciphertext depending on the direction) can be processed.
1280
\index{gcm\_process()}
1282
int gcm_process(gcm_state *gcm,
1283
unsigned char *pt, unsigned long ptlen,
1287
This processes message data where ``pt'' is the plaintext and ``ct'' is the ciphertext. The length of both are equal and stored in ``ptlen''. Depending on the
1288
mode ``pt'' is the input and ``ct'' is the output (or vice versa). When ``direction'' equals \textbf{GCM\_ENCRYPT} the plaintext is read, encrypted and stored
1289
in the ciphertext buffer. When ``direction'' equals \textbf{GCM\_DECRYPT} the opposite occurs.
1291
\subsubsection{State Termination}
1292
To terminate a GCM state and retrieve the message authentication tag call the following function.
1296
int gcm_done(gcm_state *gcm,
1297
unsigned char *tag, unsigned long *taglen);
1299
This terminates the GCM state ``gcm'' and stores the tag in ``tag'' of length ``taglen'' octets.
1301
\subsubsection{State Reset}
1302
The call to gcm\_init() will perform considerable pre--computation (when \textbf{GCM\_TABLES} is defined) and if you're going to be dealing with a lot of packets
1303
it is very costly to have to call it repeatedly. To aid in this endeavour the reset function has been provided.
1305
\index{gcm\_reset()}
1307
int gcm_reset(gcm_state *gcm);
1310
This will reset the GCM state ``gcm'' to the state that gcm\_init() left it. The user would then call gcm\_add\_iv(), gcm\_add\_aad(), etc.
1312
\subsubsection{One--Shot Packet}
1313
To process a single packet under any given key the following helper function can be used.
1315
\index{gcm\_memory()}
1317
int gcm_memory( int cipher,
1318
const unsigned char *key, unsigned long keylen,
1319
const unsigned char *IV, unsigned long IVlen,
1320
const unsigned char *adata, unsigned long adatalen,
1321
unsigned char *pt, unsigned long ptlen,
1323
unsigned char *tag, unsigned long *taglen,
1327
This will initialize the GCM state with the given key, IV and AAD value then proceed to encrypt or decrypt the message text and store the final
1328
message tag. The definition of the variables is the same as it is for all the manual functions.
1330
If you are processing many packets under the same key you shouldn't use this function as it invokes the pre--computation with each call.
1332
\subsubsection{Example Usage}
1333
The following is an example usage of how to use GCM over multiple packets with a shared secret key.
1337
#include <tomcrypt.h>
1339
int send_packet(const unsigned char *pt, unsigned long ptlen,
1340
const unsigned char *iv, unsigned long ivlen,
1341
const unsigned char *aad, unsigned long aadlen,
1345
unsigned long taglen;
1346
unsigned char tag[16];
1348
/* reset the state */
1349
if ((err = gcm_reset(gcm)) != CRYPT_OK) {
1354
if ((err = gcm_add_iv(gcm, iv, ivlen)) != CRYPT_OK) {
1358
/* Add the AAD (note: aad can be NULL if aadlen == 0) */
1359
if ((err = gcm_add_aad(gcm, aad, aadlen)) != CRYPT_OK) {
1363
/* process the plaintext */
1364
if ((err = gcm_process(gcm, pt, ptlen, pt, GCM_ENCRYPT)) != CRYPT_OK) {
1368
/* Finish up and get the MAC tag */
1369
taglen = sizeof(tag);
1370
if ((err = gcm_done(gcm, tag, &taglen)) != CRYPT_OK) {
1374
/* ... send a header describing the lengths ... */
1376
/* depending on the protocol and how IV is generated you may have to send it too... */
1377
send(socket, iv, ivlen, 0);
1380
send(socket, aad, aadlen, 0);
1382
/* send the ciphertext */
1383
send(socket, pt, ptlen, 0);
1386
send(socket, tag, taglen, 0);
1394
unsigned char key[16], IV[12], pt[PACKET_SIZE];
1396
unsigned long ptlen;
1398
/* somehow fill key/IV with random values */
1401
register_cipher(&aes_desc);
1403
/* init the GCM state */
1404
if ((err = gcm_init(&gcm, find_cipher("aes"), key, 16)) != CRYPT_OK) {
1405
whine_and_pout(err);
1408
/* handle us some packets */
1410
ptlen = make_packet_we_want_to_send(pt);
1412
/* use IV as counter (12 byte counter) */
1413
for (x = 11; x >= 0; x--) {
1419
if ((err = send_packet(pt, ptlen, iv, 12, NULL, 0, &gcm)) != CRYPT_OK) {
1420
whine_and_pout(err);
1423
return EXIT_SUCCESS;
1122
1428
\chapter{One-Way Cryptographic Hash Functions}
1123
1429
\section{Core Functions}
2931
3319
will automatically free all of the heap allocated in the process (you don't have to call dsa\_free()).
2933
3321
\chapter{Standards Support}
2934
\section{DER Support}
2935
DER or ``Distinguished Encoding Rules'' is a subset of the ASN.1 encoding rules that is fully deterministic and
2936
ideal for cryptography. In particular ASN.1 specifies an INTEGER type for storing arbitrary sized integers. DER
2937
further limits the ASN.1 specifications to a deterministic encoding.
2939
\subsection{Storing INTEGER types}
3322
\section{ASN.1 Formats}
3323
LibTomCrypt supports a variety of ASN.1 data types encoded with the Distinguished Encoding Rules (DER) suitable for various cryptographic protocols. The data types
3324
are all provided with three basic functions with \textit{similar} prototypes. One function has been dedicated to calculate the length in octets of a given
3325
format and two functions have been dedicated to encoding and decoding the format.
3327
On top of the basic data types are the SEQUENCE and\footnote{Planned for LTC 1.06} SET data types which are collections of other ASN.1 types. They are provided
3328
in the same manner as the other data types except they use list of objects known as the \textbf{ltc\_asn1\_list} structure. It is defined as
3330
\index{ltc\_asn1\_list structure}
3340
The ``type'' field is one of the following ASN.1 field definitions. The ``data'' pointer is a void pointer to the data to be encoded (or the destination) and the
3341
``size'' field is specific to what you are encoding (e.g. number of bits in the BIT STRING data type). The ``used'' field is primarily for the CHOICE decoder
3342
and reflects if the particular member of a list was the decoded data type. To help build the lists in an orderly fashion the macro
3343
``LTC\_SET\_ASN1(list, index, Type, Data, Size)'' has been provided.
3345
It will assign to the ``index''th position in the ``list'' the tripplet (Type, Data, Size). An example usage would be:
3350
ltc_asn1_list sequence[3];
3351
unsigned long three=3;
3353
LTC_SET_ASN1(sequence, 0, LTC_ASN1_IA5_STRING, "hello", 5);
3354
LTC_SET_ASN1(sequence, 1, LTC_ASN1_SHORT_INTEGER, &three, 1);
3355
LTC_SET_ASN1(sequence, 2, LTC_ASN1_NULL, NULL, 0);
3359
The macro is relatively safe with respect to modifying variables, for instance the following code is equivalent.
3364
ltc_asn1_list sequence[3];
3365
unsigned long three=3;
3367
LTC_SET_ASN1(sequence, x++, LTC_ASN1_IA5_STRING, "hello", 5);
3368
LTC_SET_ASN1(sequence, x++, LTC_ASN1_SHORT_INTEGER, &three, 1);
3369
LTC_SET_ASN1(sequence, x++, LTC_ASN1_NULL, NULL, 0);
3373
\begin{figure}[here]
3376
\begin{tabular}{|l|l|}
3377
\hline \textbf{Definition} & \textbf{ASN.1 Type} \\
3378
\hline LTC\_ASN1\_EOL & End of a ASN.1 list structure. \\
3379
\hline LTC\_ASN1\_INTEGER & INTEGER (uses mp\_int) \\
3380
\hline LTC\_ASN1\_SHORT\_INTEGER & INTEGER (32--bit using unsigned long) \\
3381
\hline LTC\_ASN1\_BIT\_STRING & BIT STRING (one bit per char) \\
3382
\hline LTC\_ASN1\_OCTET\_STRING & OCTET STRING (one octet per char) \\
3383
\hline LTC\_ASN1\_NULL & NULL \\
3384
\hline LTC\_ASN1\_OBJECT\_IDENTIFIER & OBJECT IDENTIFIER (words are in unsigned long) \\
3385
\hline LTC\_ASN1\_IA5\_STRING & IA5 STRING (one octet per char) \\
3386
\hline LTC\_ASN1\_PRINTABLE\_STRING & PRINTABLE STIRNG (one octet per char) \\
3387
\hline LTC\_ASN1\_UTCTIME & UTCTIME (see ltc\_utctime structure) \\
3388
\hline LTC\_ASN1\_SEQUENCE & SEQUENCE OF \\
3389
\hline LTC\_ASN1\_CHOICE & CHOICE \\
3392
\caption{List of ASN.1 Supported Types}
3397
\subsection{SEQUENCE Type}
3398
The SEQUENCE data type is a collection of other ASN.1 data types encapsulated with a small header which is a useful way of sending multiple data types in one packet.
3400
\subsubsection{SEUQNECE Encoding}
3401
To encode a sequence a \textbf{ltc\_asn1\_list} array must be initialized with the members of the sequence and their respective pointers. The encoding is performed
3402
with the following function.
3404
\index{der\_encode\_sequence()}
3406
int der_encode_sequence(ltc_asn1_list *list, unsigned long inlen,
3407
unsigned char *out, unsigned long *outlen);
3409
This encodes a sequence of items pointed to by ``list'' where the list has ``inlen'' items in it. The SEQUENCE will be encoded to ``out'' and of length ``outlen''. The
3410
function will terminate when it reads all the items out of the list (upto ``inlen'') or it encounters an item in the list with a type of \textbf{LTC\_ASN1\_EOL}.
3412
The ``data'' pointer in the list would be the same pointer you would pass to the respective ASN.1 encoder (e.g. der\_encode\_bit\_string()) and it is simply passed on
3413
verbatim to the dependent encoder. The list can contain other SEQUENCE or SET types which enables you to have nested SEQUENCE and SET definitions. In these cases
3414
the ``data'' pointer is simply a pointer to another \textbf{ltc\_asn1\_list}.
3416
\subsubsection{SEQUENCE Decoding}
3418
\index{der\_decode\_sequence()}
3420
Decoding a SEQUENCE is similar to encoding. You set up an array of \textbf{ltc\_asn1\_list} where in this case the ``size'' member is the maximum size
3421
(in certain cases). For types such as IA5 STRING, BIT STRING, OCTET STRING (etc) the ``size'' field is updated after successful decoding to reflect how many
3422
units of the respective type has been loaded.
3425
int der_decode_sequence(const unsigned char *in, unsigned long inlen,
3426
ltc_asn1_list *list, unsigned long outlen);
3429
This will decode upto ``outlen'' items from the input buffer ``in'' of length ``inlen'' octets. The function will stop (gracefully) when it runs out of items to decode.
3430
It will fail (for among other reasons) when it runs out of input bytes to read, a data type is invalid or a heap failure occured.
3432
For the following types the ``size'' field will be updated to reflect the number of units read of the given type.
3436
\item OBJECT IDENTIFIER
3438
\item PRINTABLE STRING
3441
\subsubsection{SEQUENCE Length}
3443
The length of a SEQUENCE can be determined with the following function.
3445
\index{der\_length\_sequence()}
3447
int der_length_sequence(ltc_asn1_list *list, unsigned long inlen,
3448
unsigned long *outlen);
3451
This will get the encoding size for the given ``list'' of length ``inlen'' and store it in ``outlen''.
3453
\subsubsection{SEQUENCE Multiple Argument Lists}
3455
For small or simple sequences an encoding or decoding can be performed with one of the following two functions.
3457
\index{der\_encode\_sequence\_multi()}
3458
\index{der\_decode\_sequence\_multi()}
3461
int der_encode_sequence_multi(unsigned char *out, unsigned long *outlen, ...);
3462
int der_decode_sequence_multi(const unsigned char *in, unsigned long inlen, ...);
3465
These either encode or decode (respectively) a SEQUENCE data type where the items in the sequence are specified after the length parameter.
3467
The list of items are specified as a triple of the form ``(type, size, data)'' where ``type'' is an \textbf{int}, ``size'' is a \textbf{unsigned long}
3468
and ``data'' is \textbf{void} pointer. The list of items must be terminated with an item with the type \textbf{LTC\_ASN1\_EOL}.
3470
It's ideal that you cast the ``size'' values to unsigned long to ensure that the proper data type is passed to the function. Constants such as ``1'' without
3471
a cast or prototype are of type \textbf{int} by default. Appending \textit{UL} or prepending \textit{(unsigned long)} is enough to cast it to the correct type.
3473
\subsection{ASN.1 INTEGER}
3475
To encode or decode INTEGER data types use the following functions.
2940
3477
\index{der\_encode\_integer()}
2942
int der_encode_integer(mp_int *num, unsigned char *out, unsigned long *outlen);
2945
This will store the integer in ``num'' to the output buffer ``out'' of length ``outlen''. It only stores
2946
non--negative numbers. It stores the number of octets used back in ``outlen''.
2948
\subsection{Reading INTEGER types}
2949
3478
\index{der\_decode\_integer()}
2951
int der_decode_integer(const unsigned char *in, unsigned long *inlen, mp_int *num);
2953
This will decode the DER encoded INTEGER in ``in'' of length ``inlen'' and store the resulting integer
2954
in ``num''. It will store the bytes read in ``inlen'' which is handy if you have to parse multiple
2955
data items out of a binary packet.
2957
\subsection{INTEGER length}
2958
3479
\index{der\_length\_integer()}
3481
int der_encode_integer(mp_int *num, unsigned char *out, unsigned long *outlen);
3482
int der_decode_integer(const unsigned char *in, unsigned long inlen, mp_int *num);
2960
3483
int der_length_integer(mp_int *num, unsigned long *len);
2962
This will determine the length of the DER encoding of the integer ``num'' and store it in ``len''.
2964
\subsection{Multiple INTEGER types}
2965
To simplify the DER encoding/decoding there are two functions two handle multple types at once.
2967
\index{der\_put\_multi\_integer()}
2968
\index{der\_get\_multi\_integer()}
2970
int der_put_multi_integer(unsigned char *dst, unsigned long *outlen, mp_int *num, ...);
2971
int der_get_multi_integer(const unsigned char *src, unsigned long *inlen, mp_int *num, ...);
2974
These will handle multiple encodings/decodings at once. They work like their single operand counterparts
2975
except they handle a \textbf{NULL} terminated list of operands.
2978
#include <mycrypt.h>
2982
unsigned char buffer[1000];
2986
/* init a,b,c,d with some values ... */
2988
/* ok we want to store them now... */
2989
len = sizeof(buffer);
2990
if ((err = der_put_multi_integer(buffer, &len,
2991
&a, &b, &c, &d, NULL)) != CRYPT_OK) {
2994
printf("I stored %lu bytes in buf\n", len);
2996
/* ok say we want to get them back for fun */
2997
/* len set previously...otherwise set it to the size of the packet */
2998
if ((err = der_get_multi_integer(buffer, &len,
2999
&a, &b, &c, &d, NULL)) != CRYPT_OK) {
3002
printf("I read %lu bytes from buf\n", len);
3486
These will encode or decode a signed INTEGER data type using the ``mp\_int'' data type to store the large INTEGER. To encode smaller values without allocating
3487
an mp\_int to store the value the ``short'' INTEGER functions were made available.
3489
\index{der\_encode\_short\_integer()}
3490
\index{der\_decode\_short\_integer()}
3491
\index{der\_length\_short\_integer()}
3493
int der_encode_short_integer(unsigned long num,
3494
unsigned char *out, unsigned long *outlen);
3496
int der_decode_short_integer(const unsigned char *in, unsigned long inlen,
3497
unsigned long *num);
3499
int der_length_short_integer(unsigned long num, unsigned long *outlen);
3502
These will encode or decode an unsigned \textbf{unsigned long} type (only reads upto 32--bits). For values in the range $0 \dots 2^{32} - 1$ the integer
3503
and short integer functions can encode and decode each others outputs.
3505
\subsection{ASN.1 BIT STRING}
3507
\index{der\_encode\_bit\_string()}
3508
\index{der\_decode\_bit\_string()}
3509
\index{der\_length\_bit\_string()}
3511
int der_encode_bit_string(const unsigned char *in, unsigned long inlen,
3512
unsigned char *out, unsigned long *outlen);
3514
int der_decode_bit_string(const unsigned char *in, unsigned long inlen,
3515
unsigned char *out, unsigned long *outlen);
3517
int der_length_bit_string(unsigned long nbits, unsigned long *outlen);
3520
These will encode or decode a BIT STRING data type. The bits are passed in (or read out) using one \textbf{char} per bit. A non--zero value will be interpretted
3521
as a one bit and a zero value a zero bit.
3523
\subsection{ASN.1 OCTET STRING}
3525
\index{der\_encode\_octet\_string()}
3526
\index{der\_decode\_octet\_string()}
3527
\index{der\_length\_octet\_string()}
3529
int der_encode_octet_string(const unsigned char *in, unsigned long inlen,
3530
unsigned char *out, unsigned long *outlen);
3532
int der_decode_octet_string(const unsigned char *in, unsigned long inlen,
3533
unsigned char *out, unsigned long *outlen);
3535
int der_length_octet_string(unsigned long noctets, unsigned long *outlen);
3538
These will encode or decode an OCTET STRING data type. The octets are stored using one \textbf{char} each.
3540
\subsection{ASN.1 OBJECT IDENTIFIER}
3542
\index{der\_encode\_object\_identifier()}
3543
\index{der\_decode\_object\_identifier()}
3544
\index{der\_length\_object\_identifier()}
3546
int der_encode_object_identifier(unsigned long *words, unsigned long nwords,
3547
unsigned char *out, unsigned long *outlen);
3549
int der_decode_object_identifier(const unsigned char *in, unsigned long inlen,
3550
unsigned long *words, unsigned long *outlen);
3552
int der_length_object_identifier(unsigned long *words, unsigned long nwords,
3553
unsigned long *outlen);
3556
These will encode or decode an OBJECT IDENTIFIER object. The words of the OID are stored in individual \textbf{unsigned long} elements and must be in the range
3557
$0 \ldots 2^{32} - 1$.
3559
\subsection{ASN.1 IA5 STRING}
3561
\index{der\_encode\_ia5\_string()}
3562
\index{der\_decode\_ia5\_string()}
3563
\index{der\_length\_ia5\_string()}
3565
int der_encode_ia5_string(const unsigned char *in, unsigned long inlen,
3566
unsigned char *out, unsigned long *outlen);
3568
int der_decode_ia5_string(const unsigned char *in, unsigned long inlen,
3569
unsigned char *out, unsigned long *outlen);
3571
int der_length_ia5_string(const unsigned char *octets, unsigned long noctets,
3572
unsigned long *outlen);
3575
These will encode or decode an IA5 STRING. The characters are read or stored in individual \textbf{char} elements. This functions performs internal character
3576
to numerical conversions based on the conventions of the compiler being used. For instance, on an x86\_32 machine 'A' == 65 but the same may not be true on
3577
say a SPARC machine. Internally these functions have a table of literal characters and their numerical ASCII values. This provides a stable conversion provided
3578
that the build platform honours the runtime platforms character conventions.
3580
If you're worried try building the test suite and running it. It has hard coded test vectors to ensure it is operating properly.
3582
\subsection{ASN.1 PRINTABLE STRING}
3584
\index{der\_encode\_printable\_string()}
3585
\index{der\_decode\_printable\_string()}
3586
\index{der\_length\_printable\_string()}
3588
int der_encode_printable_string(const unsigned char *in, unsigned long inlen,
3589
unsigned char *out, unsigned long *outlen);
3591
int der_decode_printable_string(const unsigned char *in, unsigned long inlen,
3592
unsigned char *out, unsigned long *outlen);
3594
int der_length_printable_string(const unsigned char *octets, unsigned long noctets,
3595
unsigned long *outlen);
3598
These will encode or decode an PRINTABLE STRING. The characters are read or stored in individual \textbf{char} elements. This functions performs internal character
3599
to numerical conversions based on the conventions of the compiler being used. For instance, on an x86\_32 machine 'A' == 65 but the same may not be true on
3600
say a SPARC machine. Internally these functions have a table of literal characters and their numerical ASCII values. This provides a stable conversion provided
3601
that the build platform honours the runtime platforms character conventions.
3603
If you're worried try building the test suite and running it. It has hard coded test vectors to ensure it is operating properly.
3605
\subsection{ASN.1 UTCTIME}
3607
The UTCTIME type is to store a date and time in ASN.1 format. It uses the following structure to organize the time.
3611
unsigned YY, /* year 00--99 */
3612
MM, /* month 01--12 */
3613
DD, /* day 01--31 */
3614
hh, /* hour 00--23 */
3615
mm, /* minute 00--59 */
3616
ss, /* second 00--59 */
3617
off_dir, /* timezone offset direction 0 == +, 1 == - */
3618
off_hh, /* timezone offset hours */
3619
off_mm; /* timezone offset minutes */
3623
The time can be offset plus or minus a set amount of hours (off\_hh) and minutes (off\_mm). When ``off\_dir'' is zero the time will be added otherwise it
3626
For instance, the array $\lbrace 5, 6, 20, 22, 4, 00, 0, 5, 0 \rbrace$ represents the current time of 2005, June 20th, 22:04:00 with a time offset of +05h00.
3628
\index{der\_encode\_utctime()}
3629
\index{der\_decode\_utctime()}
3630
\index{der\_length\_utctime()}
3632
int der_encode_utctime(ltc_utctime *utctime,
3633
unsigned char *out, unsigned long *outlen);
3635
int der_decode_utctime(const unsigned char *in, unsigned long *inlen,
3638
int der_length_utctime(ltc_utctime *utctime, unsigned long *outlen);
3641
The encoder will store time in one of the two ASN.1 formats, either ``YYMMDDhhmmssZ'' or ``YYMMDDhhmmss$\pm$hhmm'' and perform minimal error checking on the
3642
input. The decoder will read all valid ASN.1 formats and perform range checking on the values (not complete but rational) useful for catching packet errors.
3644
It is suggested that decoded data be further scrutinized (e.g. days of month in particular).
3646
\subsection{ASN.1 CHOICE}
3648
The CHOICE ASN.1 type represents a union of ASN.1 types all of which are stored in a ``ltc\_asn1\_list''. There is no encoder for the CHOICE type, only a
3649
decoder. The decoder will scan through the provided list attempting to use the appropriate decoder on the input packet. The list can contain any ASN.1 data
3650
type\footnote{Except it cannot have LTC\_ASN1\_INTEGER and LTC\_ASN1\_SHORT\_INTEGER simultaneously.} except for other CHOICE types.
3652
There is no encoder for the CHOICE type as the actual DER encoding is the encoding of the chosen type.
3654
\index{der\_decode\_choice()}
3656
int der_decode_choice(const unsigned char *in, unsigned long *inlen,
3657
ltc_asn1_list *list, unsigned long outlen);
3660
This will decode the input in the ``in'' field of length ``inlen''. It uses the provided ASN.1 list specified in the ``list'' field which has ``outlen'' elements.
3661
The ``inlen'' field will be updated with the length of the decoded data type as well as the respective entry in the ``list'' field will have the ``used'' flag
3662
set to non--zero to reflect it was the data type decoded.
3005
3664
\section{Password Based Cryptography}
3006
3665
\subsection{PKCS \#5}
3007
3667
In order to securely handle user passwords for the purposes of creating session keys and chaining IVs the PKCS \#5 was drafted. PKCS \#5
3008
3668
is made up of two algorithms, Algorithm One and Algorithm Two. Algorithm One is the older fairly limited algorithm which has been implemented
3009
3669
for completeness. Algorithm Two is a bit more modern and more flexible to work with.
3441
4089
will increase by approximately 500 bytes. If this is defined but TWOFISH\_SMALL is not the cipher will still work but
3442
4090
it will not speed up the encryption or decryption functions.
3444
\subsubsection{SMALL\_CODE}
4092
\subsection{GCM\_TABLES}
4093
When defined GCM will use a 64KB table (per GCM state) which will greatly speed up the per--packet latency.
4094
It also increases the initialization time and isn't suitable when you are going to use a key a few times only.
4096
\subsection{SMALL\_CODE}
3445
4097
When this is defined some of the code such as the Rijndael and SAFER+ ciphers are replaced with smaller code variants.
3446
4098
These variants are slower but can save quite a bit of code space.
4100
\subsection{LTC\_FAST}
4101
This mode (autodetected with x86\_32,x86\_64 platforms with GCC or MSVC) configures various routines such as ctr\_encrypt() or
4102
cbc\_encrypt() that it can safely XOR multiple octets in one step by using a larger data type. This has the benefit of
4103
cutting down the overhead of the respective functions.
4105
This mode does have one downside. It can cause unaligned reads from memory if you are not careful with the functions. This is why
4106
it has been enabled by default only for the x86 class of processors where unaligned accesses are allowed. Technically LTC\_FAST
4107
is not ``portable'' since unaligned accesses are not covered by the ISO C specifications.
4109
In practice however, you can use it on pretty much any platform (even MIPS) with care.
4111
By design the ``fast'' mode functions won't get unaligned on their own. For instance, if you call ctr\_encrypt() right after calling
4112
ctr\_start() and all the inputs you gave are aligned than ctr\_encrypt() will perform aligned memory operations only. However, if you
4113
call ctr\_encrypt() with an odd amount of plaintext then call it again the CTR pad (the IV) will be partially used. This will
4114
cause the ctr routine to first use up the remaining pad bytes. Then if there are enough plaintext bytes left it will use
4115
whole word XOR operations. These operations will be unaligned.
4117
The simplest precaution is to make sure you process all data in power of two blocks and handle ``remainder'' at the end. e.g. If you are
4118
CTR'ing a long stream process it in blocks of (say) four kilobytes and handle any remaining incomplete blocks at the end of the stream.
4120
If you do plan on using the ``LTC\_FAST'' mode you have to also define a ``LTC\_FAST\_TYPE'' macro which resolves to an optimal sized
4121
data type you can perform integer operations with. Ideally it should be four or eight bytes since it must properly divide the size
4122
of your block cipher (e.g. 16 bytes for AES). This means sadly if you're on a platform with 57--bit words (or something) you can't
4123
use this mode. So sad.
4125
\subsection{LTC\_PTHREAD}
4126
When this is activated all of the descriptor table functions will use pthread locking to ensure thread safe updates to the tables. Note that
4127
it doesn't prevent a thread that is passively using a table from being messed up by another thread that updates the table.
4129
Generally the rule of thumb is to setup the tables once at startup and then leave them be. This added build flag simply makes updating
3448
4132
\section{MPI Tweaks}
3449
4133
\subsection{RSA Only Tweak}
3450
4134
If you plan on only using RSA with moduli in the range of 1024 to 2560 bits you can enable a series of tweaks
3451
4135
to reduce the library size. Follow these steps
3453
4137
\begin{enumerate}
3454
\item Undefine MDSA, MECC and MDH from mycrypt\_custom.h
4138
\item Undefine MDSA, MECC and MDH from tomcrypt\_custom.h
3455
4139
\item Undefine LTM\_ALL from tommath\_superclass.h
3456
4140
\item Define SC\_RSA\_1 from tommath\_superclass.h
3457
4141
\item Rebuild the library.
3458
4142
\end{enumerate}
4144
\chapter{Optimizations}
4145
\section{Introduction}
4146
The entire API was designed with plug and play in mind at the low level. That is you can swap out any cipher, hash or PRNG and dependent API will not require
4147
updating. This has the nice benefit that I can add ciphers not have to re--write large portions of the API. For the most part LibTomCrypt has also been written
4148
to be highly portable and easy to build out of the box on pretty much any platform. As such there are no assembler inlines throughout the code, I make no assumptions
4149
about the platform, etc...
4151
That works well for most cases but there are times where time is of the essence. This API also allows optimized routines to be dropped in--place of the existing
4152
portable routines. For instance, hand optimized assembler versions of AES could be provided and any existing function that uses the cipher could automatically use
4153
the optimized code without re--writing. This also paves the way for hardware drivers that can access hardware accelerated cryptographic devices.
4155
At the heart of this flexibility is the ``descriptor'' system. A descriptor is essentially just a C ``struct'' which describes the algorithm and provides pointers
4156
to functions that do the work. For a given class of operation (e.g. cipher, hash, prng) the functions have identical prototypes which makes development simple. In most
4157
dependent routines all a developer has to do is register\_XXX() the descriptor and they're set.
4160
The ciphers in LibTomCrypt are accessed through the ltc\_cipher\_descriptor structure.
4164
struct ltc_cipher_descriptor {
4165
/** name of cipher */
4169
/** min keysize (octets) */
4171
/** max keysize (octets) */
4173
/** block size (octets) */
4175
/** default number of rounds */
4177
/** Setup the cipher
4178
@param key The input symmetric key
4179
@param keylen The length of the input key (octets)
4180
@param num_rounds The requested number of rounds (0==default)
4181
@param skey [out] The destination of the scheduled key
4182
@return CRYPT_OK if successful
4184
int (*setup)(const unsigned char *key, int keylen,
4185
int num_rounds, symmetric_key *skey);
4187
@param pt The plaintext
4188
@param ct [out] The ciphertext
4189
@param skey The scheduled key
4191
void (*ecb_encrypt)(const unsigned char *pt,
4192
unsigned char *ct, symmetric_key *skey);
4194
@param ct The ciphertext
4195
@param pt [out] The plaintext
4196
@param skey The scheduled key
4198
void (*ecb_decrypt)(const unsigned char *ct,
4199
unsigned char *pt, symmetric_key *skey);
4200
/** Test the block cipher
4201
@return CRYPT_OK if successful, CRYPT_NOP if self-testing has been disabled
4204
/** Determine a key size
4205
@param keysize [in/out] The size of the key desired and the suggested size
4206
@return CRYPT_OK if successful
4208
int (*keysize)(int *keysize);
4210
/** Accelerators **/
4211
/** Accelerated ECB encryption
4213
@param ct Ciphertext
4214
@param blocks The number of complete blocks to process
4215
@param skey The scheduled key context
4217
void (*accel_ecb_encrypt)(const unsigned char *pt,
4218
unsigned char *ct, unsigned long blocks,
4219
symmetric_key *skey);
4221
/** Accelerated ECB decryption
4223
@param ct Ciphertext
4224
@param blocks The number of complete blocks to process
4225
@param skey The scheduled key context
4227
void (*accel_ecb_decrypt)(const unsigned char *ct,
4228
unsigned char *pt, unsigned long blocks,
4229
symmetric_key *skey);
4231
/** Accelerated CBC encryption
4233
@param ct Ciphertext
4234
@param blocks The number of complete blocks to process
4235
@param IV The initial value (input/output)
4236
@param skey The scheduled key context
4238
void (*accel_cbc_encrypt)(const unsigned char *pt,
4239
unsigned char *ct, unsigned long blocks,
4240
unsigned char *IV, symmetric_key *skey);
4242
/** Accelerated CBC decryption
4244
@param ct Ciphertext
4245
@param blocks The number of complete blocks to process
4246
@param IV The initial value (input/output)
4247
@param skey The scheduled key context
4249
void (*accel_cbc_decrypt)(const unsigned char *ct,
4250
unsigned char *pt, unsigned long blocks,
4251
unsigned char *IV, symmetric_key *skey);
4253
/** Accelerated CTR encryption
4255
@param ct Ciphertext
4256
@param blocks The number of complete blocks to process
4257
@param IV The initial value (input/output)
4258
@param mode little or big endian counter (mode=0 or mode=1)
4259
@param skey The scheduled key context
4261
void (*accel_ctr_encrypt)(const unsigned char *pt,
4262
unsigned char *ct, unsigned long blocks,
4263
unsigned char *IV, int mode, symmetric_key *skey);
4265
/** Accelerated CCM packet (one-shot)
4266
@param key The secret key to use
4267
@param keylen The length of the secret key (octets)
4268
@param nonce The session nonce [use once]
4269
@param noncelen The length of the nonce
4270
@param header The header for the session
4271
@param headerlen The length of the header (octets)
4272
@param pt [out] The plaintext
4273
@param ptlen The length of the plaintext (octets)
4274
@param ct [out] The ciphertext
4275
@param tag [out] The destination tag
4276
@param taglen [in/out] The max size and resulting size of the authentication tag
4277
@param direction Encrypt or Decrypt direction (0 or 1)
4278
@return CRYPT_OK if successful
4280
void (*accel_ccm_memory)(
4281
const unsigned char *key, unsigned long keylen,
4282
const unsigned char *nonce, unsigned long noncelen,
4283
const unsigned char *header, unsigned long headerlen,
4284
unsigned char *pt, unsigned long ptlen,
4286
unsigned char *tag, unsigned long *taglen,
4289
/** Accelerated GCM packet (one shot)
4290
@param key The secret key
4291
@param keylen The length of the secret key
4292
@param IV The initial vector
4293
@param IVlen The length of the initial vector
4294
@param adata The additional authentication data (header)
4295
@param adatalen The length of the adata
4296
@param pt The plaintext
4297
@param ptlen The length of the plaintext (ciphertext length is the same)
4298
@param ct The ciphertext
4299
@param tag [out] The MAC tag
4300
@param taglen [in/out] The MAC tag length
4301
@param direction Encrypt or Decrypt mode (GCM_ENCRYPT or GCM_DECRYPT)
4303
void (*accel_gcm_memory)(
4304
const unsigned char *key, unsigned long keylen,
4305
const unsigned char *IV, unsigned long IVlen,
4306
const unsigned char *adata, unsigned long adatalen,
4307
unsigned char *pt, unsigned long ptlen,
4309
unsigned char *tag, unsigned long *taglen,
4317
The ``name'' parameter specifies the name of the cipher. This is what a developer would pass to find\_cipher() to find the cipher in the descriptor
4320
\subsection{Internal ID}
4321
This is a single byte Internal ID you can use to distingish ciphers from each other.
4323
\subsection{Key Lengths}
4324
The minimum key length is ``min\_key\_length'' and is measured in octets. Similarly the maximum key length is ``max\_key\_length''. They can be equal
4325
and both must valid key sizes for the cipher. Values in between are not assumed to be valid though they may be.
4327
\subsection{Block Length}
4328
The size of the ciphers plaintext or ciphertext is ``block\_length'' and is measured in octets.
4331
Some ciphers allow different number of rounds to be used. Usually you just use the default. The default round count is ``default\_rounds''.
4334
To initialize a cipher (for ECB mode) the function setup() was provided. It accepts an array of key octets ``key'' of length ``keylen'' octets. The user
4335
can specify the number of rounds they want through ``num\_rounds'' where $num\_rounds = 0$ means use the default. The destination of a scheduled key is stored
4338
Inside the ``symmetric\_key'' union there is a ``void *data'' which you can use to allocate data if you need a data structure that doesn't fit with the existing
4339
ones provided. Just make sure in your ``done()'' function that you free the allocated memory.
4341
\subsection{Single block ECB}
4342
To process a single block in ECB mode the ecb\_encrypt() and ecb\_decrypt() functions were provided. The plaintext and ciphertext buffers are allowed to overlap so you
4343
must make sure you do not overwrite the output before you are finished with the input.
4345
\subsection{Testing}
4346
The test() function is used to self--test the ``device''. It takes no arguments and returns \textbf{CRYPT\_OK} if all is working properly.
4348
\subsection{Key Sizing}
4349
Occasionally a function will want to find a suitable key size to use since the input is oddly sized. The keysize() function is for this case. It accepts a
4350
pointer to an integer which represents the desired size. The function then has to match it to the exact or a lower key size that is valid for the cipher. For
4351
example, if the input is $25$ and $24$ is valid then it stores $24$ back in the pointed to integer. It must not round up and must return an error if the keysize
4352
cannot be mapped to a valid key size for the cipher.
4354
\subsection{Acceleration}
4355
The next set of functions cover the accelerated functionality of the cipher descriptor. Any combination of these functions may be set to \textbf{NULL} to indicate
4356
it is not supported. In those cases the software fallbacks are used (using the single ECB block routines).
4358
\subsubsection{Accelerated ECB}
4359
These two functions are meant for cases where a user wants to encrypt (in ECB mode no less) an array of blocks. These functions are accessed
4360
through the accel\_ecb\_encrypt and accel\_ecb\_decrypt pointers. The ``blocks'' count is the number of complete blocks to process.
4362
\subsubsection{Accelerated CBC}
4363
These two functions are meant for accelerated CBC encryption. These functions are accessed through the accel\_cbc\_encrypt and accel\_cbc\_decrypt pointers.
4364
The ``blocks'' value is the number of complete blocks to process. The ``IV'' is the CBC initial vector. It is an input upon calling this function and must be
4365
updated by the function before returning.
4367
\subsubsection{Accelerated CTR}
4368
This function is meant for accelerated CTR encryption. It is accessible through the accel\_ctr\_encrypt pointer.
4369
The ``blocks'' value is the number of complete blocks to process. The ``IV'' is the CTR counter vector. It is an input upon calling this function and must be
4370
updated by the function before returning. The ``mode'' value indicates whether the counter is big (mode = CTR\_COUNTER\_BIG\_ENDIAN) or
4371
little (mode = CTR\_COUNTER\_LITTLE\_ENDIAN) endian.
4373
This function (and the way it's called) differs from the other two since ctr\_encrypt() allows any size input plaintext. The accelerator will only be
4374
called if the following conditions are met.
4377
\item The accelerator is present
4378
\item The CTR pad is empty
4379
\item The remaining length of the input to process is greater than or equal to the block size.
4382
The ``CTR pad'' is empty when a multiple (including zero) blocks of text have been processed. That is, if you pass in seven bytes to AES--CTR mode you would have to
4383
pass in a minimum of nine extra bytes before the accelerator could be called. The CTR accelerator must increment the counter (and store it back into the
4384
buffer provided) before encrypting it to create the pad.
4386
The accelerator will only be used to encrypt whole blocks. Partial blocks are always handled in software.
4388
\subsubsection{Accelerated CCM}
4389
This function is meant for accelerated CCM encryption or decryption. It processes the entire packet in one call. Note that the setup() function will not
4390
be called prior to this. This function must handle scheduling the key provided on its own.
4392
\subsubsection{Accelerated GCM}
4393
This function is meant for accelerated GCM encryption or decryption. It processes the entire packet in one call. Note that the setup() function will not
4394
be called prior to this. This function must handle scheduling the key provided on its own.
4396
\section{One--Way Hashes}
4397
The hash functions are accessed through the ltc\_hash\_descriptor structure.
4401
struct ltc_hash_descriptor {
4406
/** Size of digest in octets */
4407
unsigned long hashsize;
4408
/** Input block size in octets */
4409
unsigned long blocksize;
4411
unsigned long OID[16];
4412
/** Length of DER encoding */
4413
unsigned long OIDlen;
4414
/** Init a hash state
4415
@param hash The hash to initialize
4416
@return CRYPT_OK if successful
4418
int (*init)(hash_state *hash);
4419
/** Process a block of data
4420
@param hash The hash state
4421
@param in The data to hash
4422
@param inlen The length of the data (octets)
4423
@return CRYPT_OK if successful
4425
int (*process)(hash_state *hash, const unsigned char *in, unsigned long inlen);
4426
/** Produce the digest and store it
4427
@param hash The hash state
4428
@param out [out] The destination of the digest
4429
@return CRYPT_OK if successful
4431
int (*done)(hash_state *hash, unsigned char *out);
4433
@return CRYPT_OK if successful, CRYPT_NOP if self-tests have been disabled
4441
This is the name the hash is known by and what find\_hash() will look for.
4443
\subsection{Internal ID}
4444
This is the internal ID byte used to distinguish the hash from other hashes.
4446
\subsection{Digest Size}
4447
The ``hashsize'' variable indicates the length of the output in octets.
4449
\subsection{Block Size}
4450
The `blocksize'' variable indicates the length of input (in octets) that the hash processes in a given
4453
\subsection{OID Identifier}
4454
This is the universal ASN.1 Object Identifier for the hash.
4456
\subsection{Initialization}
4457
The init function initializes the hash and prepares it to process message bytes.
4459
\subsection{Process}
4460
This processes message bytes. The algorithm must accept any length of input that the hash would allow. The input is not
4461
guaranteed to be a multiple of the block size in length.
4464
The done function terminates the hash and returns the message digest.
4466
\subsection{Acceleration}
4467
A compatible accelerator must allow processing data in any granularity which may require internal padding on the driver side.
4469
\section{Pseudo--Random Number Generators}
4470
The pseudo--random number generators are accessible through the ltc\_prng\_descriptor structure.
4474
struct ltc_prng_descriptor {
4475
/** Name of the PRNG */
4477
/** size in bytes of exported state */
4479
/** Start a PRNG state
4480
@param prng [out] The state to initialize
4481
@return CRYPT_OK if successful
4483
int (*start)(prng_state *prng);
4484
/** Add entropy to the PRNG
4485
@param in The entropy
4486
@param inlen Length of the entropy (octets)\
4487
@param prng The PRNG state
4488
@return CRYPT_OK if successful
4490
int (*add_entropy)(const unsigned char *in, unsigned long inlen, prng_state *prng);
4491
/** Ready a PRNG state to read from
4492
@param prng The PRNG state to ready
4493
@return CRYPT_OK if successful
4495
int (*ready)(prng_state *prng);
4496
/** Read from the PRNG
4497
@param out [out] Where to store the data
4498
@param outlen Length of data desired (octets)
4499
@param prng The PRNG state to read from
4500
@return Number of octets read
4502
unsigned long (*read)(unsigned char *out, unsigned long outlen, prng_state *prng);
4503
/** Terminate a PRNG state
4504
@param prng The PRNG state to terminate
4505
@return CRYPT_OK if successful
4507
int (*done)(prng_state *prng);
4508
/** Export a PRNG state
4509
@param out [out] The destination for the state
4510
@param outlen [in/out] The max size and resulting size of the PRNG state
4511
@param prng The PRNG to export
4512
@return CRYPT_OK if successful
4514
int (*pexport)(unsigned char *out, unsigned long *outlen, prng_state *prng);
4515
/** Import a PRNG state
4516
@param in The data to import
4517
@param inlen The length of the data to import (octets)
4518
@param prng The PRNG to initialize/import
4519
@return CRYPT_OK if successful
4521
int (*pimport)(const unsigned char *in, unsigned long inlen, prng_state *prng);
4522
/** Self-test the PRNG
4523
@return CRYPT_OK if successful, CRYPT_NOP if self-testing has been disabled
4531
The name by which find\_prng() will find the PRNG.
4533
\subsection{Export Size}
4534
When an PRNG state is to be exported for future use you specify the space required in this variable.
4537
Initialize the PRNG and make it ready to accept entropy.
4539
\subsection{Entropy Addition}
4540
Add entropy to the PRNG state. The exact behaviour of this function depends on the particulars of the PRNG.
4543
This function makes the PRNG ready to read from by processing the entropy added. The behaviour of this function depends
4544
on the specific PRNG used.
4547
Read from the PRNG and return the number of bytes read. This function does not have to fill the buffer but it is best
4548
if it does as many protocols do not retry reads and will fail on the first try.
4551
Terminate a PRNG state. The behaviour of this function depends on the particular PRNG used.
4553
\subsection{Exporting and Importing}
4554
An exported PRNG state is data that the PRNG can later import to resume activity. They're not meant to resume ``the same session''
4555
but should at least maintain the same level of state entropy.
3462
4557
\input{crypt.ind}
4561
% $Source: /cvs/libtom/libtomcrypt/crypt.tex,v $
4563
% $Date: 2005/06/27 13:08:28 $
added
removed
libtomcrypt/crypt.tex
