From 94f1b407d1fbffb891162ad70cb22a8c8fcbd4cc Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Tue, 29 Apr 2014 15:15:54 +0200 Subject: [PATCH 01/28] start updating documentation --- crypt.tex | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/crypt.tex b/crypt.tex index 8ac054c..6f2ff0a 100644 --- a/crypt.tex +++ b/crypt.tex @@ -2141,7 +2141,7 @@ It is highly recommended that you \textbf{not} use the MD4 or MD5 hashes for the These hashes are provided for completeness and they still can be used for the purposes of password hashing or one-way accumulators (e.g. Yarrow). -The other hashes such as the SHA-1, SHA-2 (that includes SHA-512, SHA-384 and SHA-256) and TIGER-192 are still considered secure +The other hashes such as the SHA-1, SHA-2 (that includes SHA-512, SHA-384, SHA-256 and SHA-224) and TIGER-192 are still considered secure for all purposes you would normally use a hash for. \chapter{Message Authentication Codes} @@ -5594,14 +5594,14 @@ if you handle signals on your own. When set to 3, it will resolve to a empty ma to 4, it will return CRYPT\_INVALID\_ARG to the caller. \subsubsection{Endianness} -There are five macros related to endianess issues. For little endian platforms define, \textbf{ENDIAN\_LITTLE}. For big endian +There are five macros related to endianness issues. For little endian platforms define, \textbf{ENDIAN\_LITTLE}. For big endian platforms define \textbf{ENDIAN\_BIG}. Similarly when the default word size of an \textit{unsigned long} is 32-bits define \textbf{ENDIAN\_32BITWORD} or define \textbf{ENDIAN\_64BITWORD} when its 64-bits. If you do not define any of them the library will automatically use \textbf{ENDIAN\_NEUTRAL} which will work on all platforms. Currently LibTomCrypt will detect x86-32, x86-64, MIPS R5900, SPARC and SPARC64 running GCC as well as x86-32 running MSVC. -\mysection{The Configure Script} +\mysection{Customisation} There are also options you can specify from the \textit{tomcrypt\_custom.h} header file. \subsection{X memory routines} @@ -5636,7 +5636,7 @@ When this has been defined the library will not use faster word oriented operati which can be auto-detected. This macro ensures that they are never enabled. \subsection{LTC\_FAST} -This mode (auto-detected with x86\_32,x86\_64 platforms with GCC or MSVC) configures various routines such as ctr\_encrypt() or +This mode (auto-detected with x86\_32, x86\_64 platforms with GCC or CLANG) configures various routines such as ctr\_encrypt() or cbc\_encrypt() that it can safely XOR multiple octets in one step by using a larger data type. This has the benefit of cutting down the overhead of the respective functions. @@ -5656,8 +5656,8 @@ The simplest precaution is to make sure you process all data in power of two blo 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. \index{LTC\_FAST\_TYPE} -If you do plan on using the \textit{LTC\_FAST} mode you have to also define a \textit{LTC\_FAST\_TYPE} macro which resolves to an optimal sized -data type you can perform integer operations with. Ideally it should be four or eight bytes since it must properly divide the size +If you do plan on using the \textit{LTC\_FAST} mode, a \textit{LTC\_FAST\_TYPE} type which resolves to an optimal sized +data type you can perform integer operations with is required. For the auto-detected platforms this type will be defined automatically. Ideally it should be four or eight bytes since it must properly divide the size 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 use this mode. So sad. From 4d35336e38ec856c2566e5dcdf70d924c70aa12f Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Thu, 17 Jul 2014 11:30:44 +0200 Subject: [PATCH 02/28] more documentation --- crypt.tex | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/crypt.tex b/crypt.tex index 6f2ff0a..6444470 100644 --- a/crypt.tex +++ b/crypt.tex @@ -601,7 +601,7 @@ As of this release the current cipher\_descriptors elements are the following: \vfil \index{Cipher descriptor table} \index{blowfish\_desc} \index{xtea\_desc} \index{rc2\_desc} \index{rc5\_desc} \index{rc6\_desc} \index{saferp\_desc} \index{aes\_desc} \index{twofish\_desc} -\index{des\_desc} \index{des3\_desc} \index{noekeon\_desc} \index{skipjack\_desc} \index{anubis\_desc} \index{khazad\_desc} \index{kseed\_desc} \index{kasumi\_desc} +\index{des\_desc} \index{des3\_desc} \index{noekeon\_desc} \index{skipjack\_desc} \index{anubis\_desc} \index{khazad\_desc} \index{kseed\_desc} \index{kasumi\_desc} \index{camellia\_desc} \index{aes\_enc\_desc} \begin{figure}[hpbt] \begin{small} \begin{center} @@ -625,6 +625,7 @@ As of this release the current cipher\_descriptors elements are the following: \hline Khazad & khazad\_desc & 8 & 16 & 8 \\ \hline SEED & kseed\_desc & 16 & 16 & 16 \\ \hline KASUMI & kasumi\_desc & 8 & 16 & 8 \\ + \hline Camellia & camellia\_desc & 16 & 16, 24, 32 & 18, 24 \\ \hline \end{tabular} \end{center} @@ -653,6 +654,8 @@ Note that for \textit{DES} and \textit{3DES} they use 8 and 24 byte keys but onl fact used for the purposes of encryption. My suggestion is just to use random 8/24 byte keys instead of trying to make a 8/24 byte string from the real 7/21 byte key. +For \textit{3DES} exists a two-key mode, that can be initialized by calling the setup function with a \textit{keylen} of 16. This results in the re-usage of key \textit{K1} as key \textit{K3}. This mode has been specified as \textit{Keying Option 2} in FIPS 46-3. + \item Note that \textit{Twofish} has additional configuration options (Figure \ref{fig:twofishopts}) that take place at build time. These options are found in the file \textit{tomcrypt\_cfg.h}. The first option is \textit{TWOFISH\_SMALL} which when defined will force the Twofish code From f44c972b10405db13c82e956a81b6de9e77b122a Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Thu, 17 Jul 2014 11:38:47 +0200 Subject: [PATCH 03/28] update changes document [skip ci] --- changes | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/changes b/changes index 85a9c69..055c918 100644 --- a/changes +++ b/changes @@ -1,3 +1,25 @@ +June 25th, 2014 +v1.18 -- Added Camellia block cipher + -- Thanks to Karel Miko for cotributing a bunchload of patches and additions, namely + OCBv3, DSA and ECC key generation FIPS-186-4 compliance, BASE64-URL encoding, + a bugfix in Camellia, + -- Larry Bugbee contributed the necessary stuff to easier include libtomcrypt + in a foreign language like python, as shown in his pyTomCrypt + -- Nikos Mavrogiannopoulos contributed RSA blinding and export of RSA and DSA keys + in OpenSSL/GnuTLS compatible format + -- Patrick Pelletier contributed a smart volley of patches + -- RyanC contributed HKDF including documentation (yippie) + -- Added 2-key Triple-DES mode, thanks to Paul Howarth + -- Brought back Diffie-Hellman + -- Enabled timing resistant calculations of ECC and RSA operations per default + -- Fixed several build issues on FreeBSD, NetBSD, Linux x32 ABI, x86_64 Windows ... + -- Documentation (crypt.pdf) is now built deterministically, thanks to Michael Stapelberg + -- Removed all compiler warnings + -- Improved/extended several tests + -- Bugfix multi2 + -- Bugfix Noekeon + -- Bugfix XTEA + May 12th, 2007 v1.17 -- Cryptography Research Inc. contributed another small volley of patches, one to fix __WCHAR_DEFINED__ for BSD platforms, another to silence MSVC warnings. From f73a342b17aec947bc69fa3dbbffcdf4845c2f97 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Thu, 17 Jul 2014 19:00:03 +0200 Subject: [PATCH 04/28] oops, it's not yet released [skip ci] --- changes | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes b/changes index 055c918..ddbfd93 100644 --- a/changes +++ b/changes @@ -1,4 +1,4 @@ -June 25th, 2014 +XXX, 2014 v1.18 -- Added Camellia block cipher -- Thanks to Karel Miko for cotributing a bunchload of patches and additions, namely OCBv3, DSA and ECC key generation FIPS-186-4 compliance, BASE64-URL encoding, From 82ea2ee3daa9c555d28a5faea3d2601cdbc04439 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Mon, 25 Aug 2014 19:53:01 +0200 Subject: [PATCH 05/28] update changes document --- changes | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/changes b/changes index ddbfd93..4c8ef58 100644 --- a/changes +++ b/changes @@ -10,6 +10,11 @@ v1.18 -- Added Camellia block cipher -- Patrick Pelletier contributed a smart volley of patches -- RyanC contributed HKDF including documentation (yippie) -- Added 2-key Triple-DES mode, thanks to Paul Howarth + -- Christopher Braun contributed some patches and additions to ASN.1/DER + -- Applied some patches from the OLPC project regarding PKCS#1 and preventing the + the hash algorithms from overflowing + -- Fixed the Bleichbacher Signature attack in PKCS#1 v1.5 EMSA, thanks to Alex Dent + -- Add PKCS#1 testvectors from RSA -- Brought back Diffie-Hellman -- Enabled timing resistant calculations of ECC and RSA operations per default -- Fixed several build issues on FreeBSD, NetBSD, Linux x32 ABI, x86_64 Windows ... From e212f04f0fccff0bcdb8b404ad97eab638014ded Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Thu, 28 Aug 2014 14:42:19 +0200 Subject: [PATCH 06/28] trim trailing spaces --- crypt.tex | 2262 ++++++++++++++++++++++++++--------------------------- 1 file changed, 1131 insertions(+), 1131 deletions(-) diff --git a/crypt.tex b/crypt.tex index 6444470..6f62f5c 100644 --- a/crypt.tex +++ b/crypt.tex @@ -116,21 +116,21 @@ Canada \mainmatter \chapter{Introduction} \mysection{What is the LibTomCrypt?} -LibTomCrypt is a portable ISO C cryptographic library meant to be a tool set for cryptographers who are -designing cryptosystems. It supports symmetric ciphers, one-way hashes, pseudo-random number generators, -public key cryptography (via PKCS \#1 RSA, DH or ECCDH), and a plethora of support routines. +LibTomCrypt is a portable ISO C cryptographic library meant to be a tool set for cryptographers who are +designing cryptosystems. It supports symmetric ciphers, one-way hashes, pseudo-random number generators, +public key cryptography (via PKCS \#1 RSA, DH or ECCDH), and a plethora of support routines. -The library was designed such that new ciphers/hashes/PRNGs can be added at run-time and the existing API -(and helper API functions) are able to use the new designs automatically. There exists self-check functions for each -block cipher and hash function to ensure that they compile and execute to the published design specifications. The library +The library was designed such that new ciphers/hashes/PRNGs can be added at run-time and the existing API +(and helper API functions) are able to use the new designs automatically. There exists self-check functions for each +block cipher and hash function to ensure that they compile and execute to the published design specifications. The library also performs extensive parameter error checking to prevent any number of run-time exploits or errors. \subsection{What the library IS for?} The library serves as a toolkit for developers who have to solve cryptographic problems. Out of the box LibTomCrypt does not process SSL or OpenPGP messages, it doesn't read X.509 certificates, or write PEM encoded data. It does, however, -provide all of the tools required to build such functionality. LibTomCrypt was designed to be a flexible library that -was not tied to any particular cryptographic problem. +provide all of the tools required to build such functionality. LibTomCrypt was designed to be a flexible library that +was not tied to any particular cryptographic problem. \mysection{Why did I write it?} You may be wondering, \textit{Tom, why did you write a crypto library. I already have one.} Well the reason falls into @@ -140,14 +140,14 @@ two categories: \item It was (still is) good coding practice. \end{enumerate} -The idea is that I am not striving to replace OpenSSL or Crypto++ or Cryptlib or etc. I'm trying to write my +The idea is that I am not striving to replace OpenSSL or Crypto++ or Cryptlib or etc. I'm trying to write my {\bf own} crypto library and hopefully along the way others will appreciate the work. With this library all core functions (ciphers, hashes, prngs, and bignum) have the same prototype definition. They all load and store data in a format independent of the platform. This means if you encrypt with Blowfish on a PPC it should decrypt -on an x86 with zero problems. The consistent API also means that if you learn how to use Blowfish with the library you -know how to use Safer+, RC6, or Serpent as well. With all of the core functions there are central descriptor tables -that can be used to make a program automatically pick between ciphers, hashes and PRNGs at run-time. That means your +on an x86 with zero problems. The consistent API also means that if you learn how to use Blowfish with the library you +know how to use Safer+, RC6, or Serpent as well. With all of the core functions there are central descriptor tables +that can be used to make a program automatically pick between ciphers, hashes and PRNGs at run-time. That means your application can support all ciphers/hashes/prngs/bignum without changing the source code. Not only did I strive to make a consistent and simple API to work with but I also attempted to make the library @@ -163,23 +163,23 @@ Crypto++. \subsection{Modular} The LibTomCrypt package has also been written to be very modular. The block ciphers, one--way hashes, -pseudo--random number generators (PRNG), and bignum math routines are all used within the API through \textit{descriptor} tables which +pseudo--random number generators (PRNG), and bignum math routines are all used within the API through \textit{descriptor} tables which are essentially structures with pointers to functions. While you can still call particular functions directly (\textit{e.g. sha256\_process()}) this descriptor interface allows the developer to customize their usage of the library. For example, consider a hardware platform with a specialized RNG device. Obviously one would like to tap that for the PRNG needs within the library (\textit{e.g. making a RSA key}). All the developer has to do -is write a descriptor and the few support routines required for the device. After that the rest of the -API can make use of it without change. Similarly imagine a few years down the road when AES2 -(\textit{or whatever they call it}) has been invented. It can be added to the library and used within applications +is write a descriptor and the few support routines required for the device. After that the rest of the +API can make use of it without change. Similarly imagine a few years down the road when AES2 +(\textit{or whatever they call it}) has been invented. It can be added to the library and used within applications with zero modifications to the end applications provided they are written properly. -This flexibility within the library means it can be used with any combination of primitive algorithms and +This flexibility within the library means it can be used with any combination of primitive algorithms and unlike libraries like OpenSSL is not tied to direct routines. For instance, in OpenSSL there are CBC block mode routines for every single cipher. That means every time you add or remove a cipher from the library you have to update the associated support code as well. In LibTomCrypt the associated code (\textit{chaining modes in this case}) -are not directly tied to the ciphers. That is a new cipher can be added to the library by simply providing +are not directly tied to the ciphers. That is a new cipher can be added to the library by simply providing the key setup, ECB decrypt and encrypt and test vector routines. After that all five chaining mode routines can make use of the cipher right away. @@ -190,12 +190,12 @@ 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 author's 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. +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. \mysection{Thanks} I would like to give thanks to the following people (in no particular order) for helping me develop this project from @@ -224,7 +224,7 @@ time to time. \index{CRYPT\_ERROR} \index{CRYPT\_OK} In general the API is very simple to memorize and use. Most of the functions return either {\bf void} or {\bf int}. Functions -that return {\bf int} will return {\bf CRYPT\_OK} if the function was successful, or one of the many error codes +that return {\bf int} will return {\bf CRYPT\_OK} if the function was successful, or one of the many error codes if it failed. Certain functions that return int will return $-1$ to indicate an error. These functions will be explicitly commented upon. When a function does return a CRYPT error code it can be translated into a string with @@ -239,7 +239,7 @@ An example of handling an error is: void somefunc(void) { int err; - + /* call a cryptographic function */ if ((err = some_crypto_function(...)) != CRYPT_OK) { printf("A crypto error occurred, %s\n", error_to_string(err)); @@ -294,7 +294,7 @@ There are a few helper macros to make the coding process a bit easier. The firs \end{figure} There are 32 and 64-bit cyclic rotations as well: -\index{ROL} \index{ROR} \index{ROL64} \index{ROR64} \index{ROLc} \index{RORc} \index{ROL64c} \index{ROR64c} +\index{ROL} \index{ROR} \index{ROL64} \index{ROR64} \index{ROLc} \index{RORc} \index{ROL64c} \index{ROR64c} \begin{figure}[hpbt] \begin{small} \begin{center} @@ -330,15 +330,15 @@ int main(void) { /* ... Make up the RSA key somehow ... */ - /* lets export the key, set x to the size of the + /* lets export the key, set x to the size of the * output buffer */ x = sizeof(buffer); if ((err = rsa_export(buffer, &x, PK_PUBLIC, &key)) != CRYPT_OK) { printf("Export error: %s\n", error_to_string(err)); return -1; } - - /* if rsa_export() was successful then x will have + + /* if rsa_export() was successful then x will have * the size of the output */ printf("RSA exported key takes %d bytes\n", x); @@ -349,7 +349,7 @@ int main(void) { \end{verbatim} \end{small} In the above example if the size of the RSA public key was more than 1024 bytes this function would return an error code -indicating a buffer overflow would have occurred. If the function succeeds, it stores the length of the output back into +indicating a buffer overflow would have occurred. If the function succeeds, it stores the length of the output back into \textit{x} so that the calling application will know how many bytes were used. As of v1.13, most functions will update your length on failure to indicate the size required by the function. Not all functions @@ -357,7 +357,7 @@ support this so please check the source before you rely on it doing that. \mysection{Functions that need a PRNG} \index{Pseudo Random Number Generator} \index{PRNG} -Certain functions such as \textit{rsa\_make\_key()} require a Pseudo Random Number Generator (PRNG). These functions do not setup +Certain functions such as \textit{rsa\_make\_key()} require a Pseudo Random Number Generator (PRNG). These functions do not setup the PRNG themselves so it is the responsibility of the calling function to initialize the PRNG before calling them. Certain PRNG algorithms do not require a \textit{prng\_state} argument (sprng for example). The \textit{prng\_state} argument @@ -372,10 +372,10 @@ int main(void) { int err; /* register the system RNG */ - register_prng(&sprng_desc) + register_prng(&sprng_desc) /* make a 1024-bit RSA key with the system RNG */ - if ((err = rsa_make_key(NULL, find_prng("sprng"), 1024/8, 65537, &key)) + if ((err = rsa_make_key(NULL, find_prng("sprng"), 1024/8, 65537, &key)) != CRYPT_OK) { printf("make_key error: %s\n", error_to_string(err)); return -1; @@ -391,8 +391,8 @@ int main(void) { \mysection{Functions that use Arrays of Octets} Most functions require inputs that are arrays of the data type \textit{unsigned char}. Whether it is a symmetric key, IV for a chaining mode or public key packet it is assumed that regardless of the actual size of \textit{unsigned char} only the -lower eight bits contain data. For example, if you want to pass a 256 bit key to a symmetric ciphers setup routine, you -must pass in (a pointer to) an array of 32 \textit{unsigned char} variables. Certain routines (such as SAFER+) take +lower eight bits contain data. For example, if you want to pass a 256 bit key to a symmetric ciphers setup routine, you +must pass in (a pointer to) an array of 32 \textit{unsigned char} variables. Certain routines (such as SAFER+) take special care to work properly on platforms where an \textit{unsigned char} is not eight bits. For the purposes of this library, the term \textit{byte} will refer to an octet or eight bit word. Typically an array of @@ -400,20 +400,20 @@ type \textit{byte} will be synonymous with an array of type \textit{unsigned cha \chapter{Symmetric Block Ciphers} \mysection{Core Functions} -LibTomCrypt provides several block ciphers with an ECB block mode interface. It is important to first note that you +LibTomCrypt provides several block ciphers with an ECB block mode interface. It is important to first note that you should never use the ECB modes directly to encrypt data. Instead you should use the ECB functions to make a chaining mode, or use one of the provided chaining modes. All of the ciphers are written as ECB interfaces since it allows the rest of the API to grow in a modular fashion. \subsection{Key Scheduling} -All ciphers store their scheduled keys in a single data type called \textit{symmetric\_key}. This allows all ciphers to +All ciphers store their scheduled keys in a single data type called \textit{symmetric\_key}. This allows all ciphers to have the same prototype and store their keys as naturally as possible. This also removes the need for dynamic memory -allocation, and allows you to allocate a fixed sized buffer for storing scheduled keys. All ciphers must provide six visible +allocation, and allows you to allocate a fixed sized buffer for storing scheduled keys. All ciphers must provide six visible functions which are (given that XXX is the name of the cipher) the following: \index{Cipher Setup} \begin{verbatim} -int XXX_setup(const unsigned char *key, - int keylen, +int XXX_setup(const unsigned char *key, + int keylen, int rounds, symmetric_key *skey); \end{verbatim} @@ -422,8 +422,8 @@ The XXX\_setup() routine will setup the cipher to be used with a given number of The number of rounds can be set to zero to use the default, which is generally a good idea. If the function returns successfully the variable \textit{skey} will have a scheduled key stored in it. It's important to note -that you should only used this scheduled key with the intended cipher. For example, if you call \textit{blowfish\_setup()} do not -pass the scheduled key onto \textit{rc5\_ecb\_encrypt()}. All built--in setup functions do not allocate memory off the heap so +that you should only used this scheduled key with the intended cipher. For example, if you call \textit{blowfish\_setup()} do not +pass the scheduled key onto \textit{rc5\_ecb\_encrypt()}. All built--in setup functions do not allocate memory off the heap so when you are done with a key you can simply discard it (e.g. they can be on the stack). However, to maintain proper coding practices you should always call the respective XXX\_done() function. This allows for quicker porting to applications with externally supplied plugins. @@ -432,28 +432,28 @@ externally supplied plugins. To encrypt or decrypt a block in ECB mode there are these two functions per cipher: \index{Cipher Encrypt} \index{Cipher Decrypt} \begin{verbatim} -int XXX_ecb_encrypt(const unsigned char *pt, +int XXX_ecb_encrypt(const unsigned char *pt, unsigned char *ct, symmetric_key *skey); -int XXX_ecb_decrypt(const unsigned char *ct, +int XXX_ecb_decrypt(const unsigned char *ct, unsigned char *pt, symmetric_key *skey); \end{verbatim} These two functions will encrypt or decrypt (respectively) a single block of text\footnote{The size of which depends on -which cipher you are using.}, storing the result in the \textit{ct} buffer (\textit{pt} resp.). It is possible that the input and output buffer are -the same buffer. For the encrypt function \textit{pt}\footnote{pt stands for plaintext.} is the input and +which cipher you are using.}, storing the result in the \textit{ct} buffer (\textit{pt} resp.). It is possible that the input and output buffer are +the same buffer. For the encrypt function \textit{pt}\footnote{pt stands for plaintext.} is the input and \textit{ct}\footnote{ct stands for ciphertext.} is the output. For the decryption function it's the opposite. They both -return \textbf{CRYPT\_OK} on success. To test a particular cipher against test vectors\footnote{As published in their design papers.} +return \textbf{CRYPT\_OK} on success. To test a particular cipher against test vectors\footnote{As published in their design papers.} call the following self-test function. - + \subsection{Self--Testing} \index{Cipher Testing} \begin{verbatim} int XXX_test(void); \end{verbatim} -This function will return {\bf CRYPT\_OK} if the cipher matches the test vectors from the design publication it is -based upon. +This function will return {\bf CRYPT\_OK} if the cipher matches the test vectors from the design publication it is +based upon. \subsection{Key Sizing} For each cipher there is a function which will help find a desired key size. It is specified as follows: @@ -500,7 +500,7 @@ An example snippet that encodes a block with Blowfish in ECB mode. \begin{verbatim} #include int main(void) -{ +{ unsigned char pt[8], ct[8], key[8]; symmetric_key skey; int err; @@ -520,17 +520,17 @@ int main(void) /* encrypt the block */ blowfish_ecb_encrypt(pt, /* encrypt this 8-byte array */ - ct, /* store encrypted data here */ + ct, /* store encrypted data here */ &skey); /* our previously scheduled key */ - - /* now ct holds the encrypted version of pt */ + + /* now ct holds the encrypted version of pt */ /* decrypt the block */ blowfish_ecb_decrypt(ct, /* decrypt this 8-byte array */ pt, /* store decrypted data here */ &skey); /* our previously scheduled key */ - /* now we have decrypted ct to the original plaintext in pt */ + /* now we have decrypted ct to the original plaintext in pt */ /* Terminate the cipher context */ blowfish_done(&skey); @@ -552,7 +552,7 @@ only 53 bits of entropy. The number of rounds of most ciphers is not an option you can change. Only RC5 allows you to change the number of rounds. By passing zero as the number of rounds all ciphers will use their default number of rounds. Generally the -ciphers are configured such that the default number of rounds provide adequate security for the given block and key +ciphers are configured such that the default number of rounds provide adequate security for the given block and key size. \mysection{The Cipher Descriptors} @@ -570,13 +570,13 @@ struct _cipher_descriptor { unsigned char ID; /** min keysize (octets) */ - int min_key_length, + int min_key_length, /** max keysize (octets) */ - max_key_length, + max_key_length, /** block size (octets) */ - block_length, + block_length, /** default number of rounds */ default_rounds; @@ -585,7 +585,7 @@ struct _cipher_descriptor { \end{verbatim} \end{small} -Where \textit{name} is the lower case ASCII version of the name. The fields \textit{min\_key\_length} and \textit{max\_key\_length} +Where \textit{name} is the lower case ASCII version of the name. The fields \textit{min\_key\_length} and \textit{max\_key\_length} are the minimum and maximum key sizes in bytes. The \textit{block\_length} member is the block size of the cipher in bytes. As a good rule of thumb it is assumed that the cipher supports the min and max key lengths but not always everything in between. The \textit{default\_rounds} field is the default number @@ -637,12 +637,12 @@ As of this release the current cipher\_descriptors elements are the following: \begin{small} \begin{enumerate} \item -For AES, (also known as Rijndael) there are four descriptors which complicate issues a little. The descriptors -rijndael\_desc and rijndael\_enc\_desc provide the cipher named \textit{rijndael}. The descriptors aes\_desc and +For AES, (also known as Rijndael) there are four descriptors which complicate issues a little. The descriptors +rijndael\_desc and rijndael\_enc\_desc provide the cipher named \textit{rijndael}. The descriptors aes\_desc and aes\_enc\_desc provide the cipher name \textit{aes}. Functionally both \textit{rijndael} and \textit{aes} are the same cipher. The -only difference is when you call find\_cipher() you have to pass the correct name. The cipher descriptors with \textit{enc} +only difference is when you call find\_cipher() you have to pass the correct name. The cipher descriptors with \textit{enc} in the middle (e.g. rijndael\_enc\_desc) are related to an implementation of Rijndael with only the encryption routine -and tables. The decryption and self--test function pointers of both \textit{encrypt only} descriptors are set to \textbf{NULL} and +and tables. The decryption and self--test function pointers of both \textit{encrypt only} descriptors are set to \textbf{NULL} and should not be called. The \textit{encrypt only} descriptors are useful for applications that only use the encryption function of the cipher. Algorithms such @@ -709,9 +709,9 @@ int main(void) return -1; } - /* generic call to function (assuming the key + /* generic call to function (assuming the key * in key[] was already setup) */ - if ((err = + if ((err = cipher_descriptor[find_cipher("blowfish")]. setup(key, 8, 0, &skey)) != CRYPT_OK) { printf("Error setting up Blowfish: %s\n", error_to_string(err)); @@ -736,14 +736,14 @@ than once it will just return the index of the first copy. To remove a cipher c \begin{verbatim} int unregister_cipher(const struct _cipher_descriptor *cipher); \end{verbatim} -Which returns {\bf CRYPT\_OK} if it removes the cipher, otherwise it returns {\bf CRYPT\_ERROR}. +Which returns {\bf CRYPT\_OK} if it removes the cipher, otherwise it returns {\bf CRYPT\_ERROR}. \begin{small} \begin{verbatim} #include int main(void) { int err; - + /* register the cipher */ if (register_cipher(&rijndael_desc) == -1) { printf("Error registering Rijndael\n"); @@ -762,7 +762,7 @@ int main(void) } \end{verbatim} \end{small} -This snippet is a small program that registers Rijndael. +This snippet is a small program that registers Rijndael. \mysection{Symmetric Modes of Operations} \subsection{Background} @@ -830,8 +830,8 @@ My personal preference is for the CTR mode since it has several key benefits: \item Allows random access to the plaintext. \item Allows the encryption of block sizes that are not equal to the size of the block cipher. \end{enumerate} -The CTR, CFB and OFB routines provided allow you to encrypt block sizes that differ from the ciphers block size. They -accomplish this by buffering the data required to complete a block. This allows you to encrypt or decrypt any size +The CTR, CFB and OFB routines provided allow you to encrypt block sizes that differ from the ciphers block size. They +accomplish this by buffering the data required to complete a block. This allows you to encrypt or decrypt any size block of memory with either of the three modes. The ECB and CBC modes process blocks of the same size as the cipher at a time. Therefore, they are less flexible than the @@ -841,52 +841,52 @@ other modes. \index{Ciphertext stealing} Ciphertext stealing is a method of dealing with messages in CBC mode which are not a multiple of the block length. This is accomplished by encrypting the last ciphertext block in ECB mode, and XOR'ing the output against the last partial block of plaintext. LibTomCrypt does not -support this mode directly but it is fairly easy to emulate with a call to the cipher's ecb\_encrypt() callback function. +support this mode directly but it is fairly easy to emulate with a call to the cipher's ecb\_encrypt() callback function. -The more sane way to deal with partial blocks is to pad them with zeroes, and then use CBC normally. +The more sane way to deal with partial blocks is to pad them with zeroes, and then use CBC normally. \subsection{Initialization} \index{CBC Mode} \index{CTR Mode} \index{OFB Mode} \index{CFB Mode} -The library provides simple support routines for handling CBC, CTR, CFB, OFB and ECB encoded messages. Assuming the mode +The library provides simple support routines for handling CBC, CTR, CFB, OFB and ECB encoded messages. Assuming the mode you want is XXX there is a structure called \textit{symmetric\_XXX} that will contain the information required to use that mode. They have identical setup routines (except CTR and ECB mode): \index{ecb\_start()} \index{cfb\_start()} \index{cbc\_start()} \index{ofb\_start()} \index{ctr\_start()} \begin{verbatim} -int XXX_start( int cipher, - const unsigned char *IV, - const unsigned char *key, - int keylen, - int num_rounds, +int XXX_start( int cipher, + const unsigned char *IV, + const unsigned char *key, + int keylen, + int num_rounds, symmetric_XXX *XXX); int ctr_start( int cipher, const unsigned char *IV, - const unsigned char *key, + const unsigned char *key, int keylen, - int num_rounds, + int num_rounds, int ctr_mode, symmetric_CTR *ctr); -int ecb_start( int cipher, - const unsigned char *key, - int keylen, - int num_rounds, +int ecb_start( int cipher, + const unsigned char *key, + int keylen, + int num_rounds, symmetric_ECB *ecb); \end{verbatim} -In each case, \textit{cipher} is the index into the cipher\_descriptor array of the cipher you want to use. The \textit{IV} value is -the initialization vector to be used with the cipher. You must fill the IV yourself and it is assumed they are the same -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 +In each case, \textit{cipher} is the index into the cipher\_descriptor array of the cipher you want to use. The \textit{IV} value is +the initialization vector to be used with the cipher. You must fill the IV yourself and it is assumed they are the same +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. +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 +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. @@ -904,7 +904,7 @@ 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_COUNTER_LITTLE_ENDIAN | 4, &ctr)) != CRYPT_OK) { handle_error(err); } @@ -916,20 +916,20 @@ 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{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()} \begin{verbatim} -int XXX_encrypt(const unsigned char *pt, - unsigned char *ct, - unsigned long len, +int XXX_encrypt(const unsigned char *pt, + unsigned char *ct, + unsigned long len, symmetric_YYY *YYY); -int XXX_decrypt(const unsigned char *ct, - unsigned char *pt, - unsigned long len, +int XXX_decrypt(const unsigned char *ct, + unsigned char *pt, + unsigned long len, symmetric_YYY *YYY); \end{verbatim} -Where \textit{XXX} is one of $\lbrace ecb, cbc, ctr, cfb, ofb \rbrace$. +Where \textit{XXX} is one of $\lbrace ecb, cbc, ctr, cfb, ofb \rbrace$. In all cases, \textit{len} is the size of the buffer (as number of octets) to encrypt or decrypt. The CTR, OFB and CFB modes are order sensitive but not chunk sensitive. That is you can encrypt \textit{ABCDEF} in three calls like \textit{AB}, \textit{CD}, \textit{EF} or two like \textit{ABCDE} and \textit{F} @@ -946,22 +946,22 @@ To change or read the IV of a previously initialized chaining mode use the follo \index{cbc\_setiv()} \index{cbc\_getiv()} \index{ofb\_setiv()} \index{ofb\_getiv()} \index{cfb\_setiv()} \index{cfb\_getiv()} \index{ctr\_setiv()} \index{ctr\_getiv()} \begin{verbatim} -int XXX_getiv(unsigned char *IV, - unsigned long *len, +int XXX_getiv(unsigned char *IV, + unsigned long *len, symmetric_XXX *XXX); -int XXX_setiv(const unsigned char *IV, - unsigned long len, +int XXX_setiv(const unsigned char *IV, + unsigned long len, symmetric_XXX *XXX); \end{verbatim} -The XXX\_getiv() functions will read the IV out of the chaining mode and store it into \textit{IV} along with the length of the IV +The XXX\_getiv() functions will read the IV out of the chaining mode and store it into \textit{IV} along with the length of the IV stored in \textit{len}. The XXX\_setiv will initialize the chaining mode state as if the original IV were the new IV specified. The length of the IV passed in must be the size of the ciphers block size. -The XXX\_setiv() functions are handy if you wish to change the IV without re--keying the cipher. +The XXX\_setiv() functions are handy if you wish to change the IV without re--keying the cipher. -What the \textit{setiv} function will do depends on the mode being changed. In CBC mode, the new IV replaces the existing IV as if it +What the \textit{setiv} function will do depends on the mode being changed. In CBC mode, the new IV replaces the existing IV as if it were the last ciphertext block. In CFB mode, the IV is encrypted as if it were the prior encrypted pad. In CTR mode, the IV is encrypted without first incrementing it (regardless of the LTC\_RFC\_3686 flag presence). In F8 mode, the IV is encrypted and becomes the new pad. It does not change the salted IV, and is only meant to allow seeking within a session. In LRW, it changes the tweak, forcing a computation of the tweak pad, allowing for @@ -1056,11 +1056,11 @@ int main(void) \end{small} \subsection{LRW Mode} -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 +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 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. -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 -$K_2$ is the \textit{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. +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 +$K_2$ is the \textit{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. To initialize LRW mode use: @@ -1068,14 +1068,14 @@ To initialize LRW mode use: \begin{verbatim} int lrw_start( int cipher, const unsigned char *IV, - const unsigned char *key, + const unsigned char *key, int keylen, const unsigned char *tweak, - int num_rounds, + int num_rounds, symmetric_LRW *lrw); \end{verbatim} -This will initialize the LRW context with the given (16 octet) \textit{IV}, cipher $K_1$ \textit{key} of length \textit{keylen} octets and the (16 octet) $K_2$ \textit{tweak}. +This will initialize the LRW context with the given (16 octet) \textit{IV}, cipher $K_1$ \textit{key} of length \textit{keylen} octets and the (16 octet) $K_2$ \textit{tweak}. While LRW was specified to be used only with AES, LibTomCrypt will allow any 128--bit block cipher to be specified as indexed by \textit{cipher}. The number of rounds for the block cipher \textit{num\_rounds} can be 0 to use the default number of rounds for the given cipher. @@ -1083,30 +1083,30 @@ To process data use the following functions: \index{lrw\_encrypt()} \index{lrw\_decrypt()} \begin{verbatim} -int lrw_encrypt(const unsigned char *pt, - unsigned char *ct, - unsigned long len, +int lrw_encrypt(const unsigned char *pt, + unsigned char *ct, + unsigned long len, symmetric_LRW *lrw); -int lrw_decrypt(const unsigned char *ct, - unsigned char *pt, - unsigned long len, +int lrw_decrypt(const unsigned char *ct, + unsigned char *pt, + unsigned long len, symmetric_LRW *lrw); \end{verbatim} These will encrypt (or decrypt) the plaintext to the ciphertext buffer (or vice versa). The length is specified by \textit{len} in octets but must be a multiple -of 16. The LRW code uses a fast tweak update such that consecutive blocks are encrypted faster than if random seeking where used. +of 16. The LRW code uses a fast tweak update such that consecutive blocks are encrypted faster than if random seeking where used. To manipulate the IV use the following functions: -\index{lrw\_getiv()} \index{lrw\_setiv()} +\index{lrw\_getiv()} \index{lrw\_setiv()} \begin{verbatim} -int lrw_getiv(unsigned char *IV, - unsigned long *len, +int lrw_getiv(unsigned char *IV, + unsigned long *len, symmetric_LRW *lrw); -int lrw_setiv(const unsigned char *IV, - unsigned long len, +int lrw_setiv(const unsigned char *IV, + unsigned long len, symmetric_LRW *lrw); \end{verbatim} These will get or set the 16--octet IV. Note that setting the IV is the same as \textit{seeking} and unlike other modes is not a free operation. It requires @@ -1120,23 +1120,23 @@ 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. +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, + const unsigned char *key1, + const unsigned char *key2, unsigned long keylen, - int num_rounds, + 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. +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: @@ -1154,11 +1154,11 @@ int xts_decrypt( 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 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. +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: @@ -1176,44 +1176,44 @@ initialize F8 mode with the following function call: \index{f8\_start()} \begin{verbatim} -int f8_start( int cipher, - const unsigned char *IV, - const unsigned char *key, - int keylen, - const unsigned char *salt_key, +int f8_start( int cipher, + const unsigned char *IV, + const unsigned char *key, + int keylen, + const unsigned char *salt_key, int skeylen, - int num_rounds, + int num_rounds, symmetric_F8 *f8); \end{verbatim} -This will start the F8 mode state using \textit{key} as the secret key, \textit{IV} as the counter. It uses the \textit{salt\_key} as IV encryption key -(\textit{m} in the RFC 3711). The salt\_key can be shorter than the secret key but it should not be longer. +This will start the F8 mode state using \textit{key} as the secret key, \textit{IV} as the counter. It uses the \textit{salt\_key} as IV encryption key +(\textit{m} in the RFC 3711). The salt\_key can be shorter than the secret key but it should not be longer. To encrypt or decrypt data we use the following two functions: \index{f8\_encrypt()} \index{f8\_decrypt()} \begin{verbatim} -int f8_encrypt(const unsigned char *pt, - unsigned char *ct, - unsigned long len, +int f8_encrypt(const unsigned char *pt, + unsigned char *ct, + unsigned long len, symmetric_F8 *f8); -int f8_decrypt(const unsigned char *ct, - unsigned char *pt, - unsigned long len, +int f8_decrypt(const unsigned char *ct, + unsigned char *pt, + unsigned long len, symmetric_F8 *f8); \end{verbatim} -These will encrypt or decrypt a variable length array of bytes using the F8 mode state specified. The length is specified in bytes and does not have to be a multiple +These will encrypt or decrypt a variable length array of bytes using the F8 mode state specified. The length is specified in bytes and does not have to be a multiple of the ciphers block size. To change or retrieve the current counter IV value use the following functions: \index{f8\_getiv()} \index{f8\_setiv()} \begin{verbatim} -int f8_getiv(unsigned char *IV, - unsigned long *len, +int f8_getiv(unsigned char *IV, + unsigned long *len, symmetric_F8 *f8); -int f8_setiv(const unsigned char *IV, - unsigned long len, +int f8_setiv(const unsigned char *IV, + unsigned long len, symmetric_F8 *f8); \end{verbatim} These work with the current IV value only and not the encrypted IV value specified during the call to f8\_start(). The purpose of these two functions is to be @@ -1231,11 +1231,11 @@ int f8_done(symmetric_F8 *f8); \mysection{Encrypt and Authenticate Modes} \subsection{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.}. +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 @@ -1249,44 +1249,44 @@ 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, +int eax_init( eax_state *eax, + int cipher, + const unsigned char *key, unsigned long keylen, - const unsigned char *nonce, + const unsigned char *nonce, unsigned long noncelen, - const unsigned char *header, + 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 +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 +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, +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, +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. +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). +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 @@ -1294,17 +1294,17 @@ EAX stream with the following. \index{eax\_addheader()} \begin{verbatim} -int eax_addheader( eax_state *eax, - const unsigned char *header, +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 +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, +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 @@ -1365,12 +1365,12 @@ int main(void) return EXIT_FAILURE; } - /* now we have the authentication tag in "tag" and + /* now we have the authentication tag in "tag" and * it's taglen bytes long */ } \end{verbatim} - -You can also perform an entire EAX state on a block of memory in a single function call with the + +You can also perform an entire EAX state on a block of memory in a single function call with the following functions. @@ -1397,23 +1397,23 @@ int eax_decrypt_verify_memory( \end{verbatim} Both essentially just call eax\_init() followed by eax\_encrypt() (or eax\_decrypt() respectively) and eax\_done(). The parameters -have the same meaning as with those respective functions. +have the same meaning as with those respective functions. The only difference is eax\_decrypt\_verify\_memory() does not emit a tag. Instead you pass it a tag as input and it compares it against the tag it computed while decrypting the message. If the tags match then it stores a $1$ in \textit{res}, otherwise it stores a $0$. \subsection{OCB Mode} -LibTomCrypt provides support for a mode called OCB\footnote{See +LibTomCrypt provides support for a mode called OCB\footnote{See P. Rogaway, M. Bellare, J. Black, T. Krovetz, \textit{OCB: A Block Cipher Mode of Operation for Efficient Authenticated Encryption}.} . OCB is an encryption protocol that simultaneously provides authentication. It is slightly faster to use than EAX mode but is less flexible. Let's review how to initialize an OCB context. \index{ocb\_init()} \begin{verbatim} -int ocb_init( ocb_state *ocb, - int cipher, - const unsigned char *key, - unsigned long keylen, +int ocb_init( ocb_state *ocb, + int cipher, + const unsigned char *key, + unsigned long keylen, const unsigned char *nonce); \end{verbatim} @@ -1426,17 +1426,17 @@ To encrypt or decrypt data use the following. \index{ocb\_encrypt()} \index{ocb\_decrypt()} \begin{verbatim} -int ocb_encrypt( ocb_state *ocb, - const unsigned char *pt, +int ocb_encrypt( ocb_state *ocb, + const unsigned char *pt, unsigned char *ct); -int ocb_decrypt( ocb_state *ocb, - const unsigned char *ct, +int ocb_decrypt( ocb_state *ocb, + const unsigned char *ct, unsigned char *pt); \end{verbatim} -This will encrypt (or decrypt for the latter) a fixed length of data from \textit{pt} to \textit{ct} (vice versa for the latter). -They assume that \textit{pt} and \textit{ct} are the same size as the block cipher's block size. Note that you cannot call +This will encrypt (or decrypt for the latter) a fixed length of data from \textit{pt} to \textit{ct} (vice versa for the latter). +They assume that \textit{pt} and \textit{ct} are the same size as the block cipher's block size. Note that you cannot call both functions given a single \textit{ocb} state. For bi-directional communication you will have to initialize two \textit{ocb} states (with different nonces). Also \textit{pt} and \textit{ct} may point to the same location in memory. @@ -1446,34 +1446,34 @@ When you are finished encrypting the message you call the following function to \index{ocb\_done\_encrypt()} \begin{verbatim} -int ocb_done_encrypt( ocb_state *ocb, - const unsigned char *pt, +int ocb_done_encrypt( ocb_state *ocb, + const unsigned char *pt, unsigned long ptlen, - unsigned char *ct, - unsigned char *tag, + unsigned char *ct, + unsigned char *tag, unsigned long *taglen); \end{verbatim} -This will terminate an encrypt stream \textit{ocb}. If you have trailing bytes of plaintext that will not complete a block +This will terminate an encrypt stream \textit{ocb}. If you have trailing bytes of plaintext that will not complete a block you can pass them here. This will also encrypt the \textit{ptlen} bytes in \textit{pt} and store them in \textit{ct}. It will also store up to \textit{taglen} bytes of the tag into \textit{tag}. -Note that \textit{ptlen} must be less than or equal to the block size of block cipher chosen. Also note that if you have -an input message equal to the length of the block size then you pass the data here (not to ocb\_encrypt()) only. +Note that \textit{ptlen} must be less than or equal to the block size of block cipher chosen. Also note that if you have +an input message equal to the length of the block size then you pass the data here (not to ocb\_encrypt()) only. To terminate a decrypt stream and compared the tag you call the following. \index{ocb\_done\_decrypt()} \begin{verbatim} -int ocb_done_decrypt( ocb_state *ocb, - const unsigned char *ct, +int ocb_done_decrypt( ocb_state *ocb, + const unsigned char *ct, unsigned long ctlen, - unsigned char *pt, - const unsigned char *tag, - unsigned long taglen, + unsigned char *pt, + const unsigned char *tag, + unsigned long taglen, int *res); \end{verbatim} -Similarly to the previous function you can pass trailing message bytes into this function. This will compute the +Similarly to the previous function you can pass trailing message bytes into this function. This will compute the tag of the message (internally) and then compare it against the \textit{taglen} bytes of \textit{tag} provided. By default \textit{res} is set to zero. If all \textit{taglen} bytes of \textit{tag} can be verified then \textit{res} is set to one (authenticated message). @@ -1486,33 +1486,33 @@ To make life simpler the following two functions are provided for memory bound O int ocb_encrypt_authenticate_memory( int cipher, const unsigned char *key, unsigned long keylen, - const unsigned char *nonce, + const unsigned char *nonce, const unsigned char *pt, unsigned long ptlen, unsigned char *ct, unsigned char *tag, unsigned long *taglen); \end{verbatim} This will OCB encrypt the message \textit{pt} of length \textit{ptlen}, and store the ciphertext in \textit{ct}. The length \textit{ptlen} -can be any arbitrary length. +can be any arbitrary length. \index{ocb\_decrypt\_verify\_memory()} \begin{verbatim} int ocb_decrypt_verify_memory( int cipher, const unsigned char *key, unsigned long keylen, - const unsigned char *nonce, + const unsigned char *nonce, const unsigned char *ct, unsigned long ctlen, unsigned char *pt, const unsigned char *tag, unsigned long taglen, int *res); \end{verbatim} -Similarly, this will OCB decrypt, and compare the internally computed tag against the tag provided. \textit{res} is set +Similarly, this will OCB decrypt, and compare the internally computed tag against the tag provided. \textit{res} is set appropriately. \subsection{CCM Mode} 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, -it is only meant for \textit{packet} mode where the length of the input is known in advance. Since it is a packet mode function, CCM only has one +it is only meant for \textit{packet} mode where the length of the input is known in advance. Since it is a packet mode function, CCM only has one function that performs the protocol. \index{ccm\_memory()} @@ -1529,22 +1529,22 @@ int ccm_memory( int direction); \end{verbatim} -This performs the \textit{CCM} operation on the data. The \textit{cipher} variable indicates which cipher in the descriptor table to use. It must have a -16--byte block size for CCM. +This performs the \textit{CCM} operation on the data. The \textit{cipher} variable indicates which cipher in the descriptor table to use. It must have a +16--byte block size for CCM. The key can be specified in one of two fashions. First, it can be passed as an array of octets in \textit{key} of length \textit{keylen}. Alternatively, it can be passed in as a previously scheduled key in \textit{uskey}. The latter fashion saves time when the same key is used for multiple packets. If -\textit{uskey} is not \textbf{NULL}, then \textit{key} may be \textbf{NULL} (and vice-versa). +\textit{uskey} is not \textbf{NULL}, then \textit{key} may be \textbf{NULL} (and vice-versa). -The nonce or salt is \textit{nonce} of length \textit{noncelen} octets. The header is meta--data you want to send with the message but not have -encrypted, it is stored in \textit{header} of length \textit{headerlen} octets. The header can be zero octets long (if $headerlen = 0$ then -you can pass \textit{header} as \textbf{NULL}). +The nonce or salt is \textit{nonce} of length \textit{noncelen} octets. The header is meta--data you want to send with the message but not have +encrypted, it is stored in \textit{header} of length \textit{headerlen} octets. The header can be zero octets long (if $headerlen = 0$ then +you can pass \textit{header} as \textbf{NULL}). The plaintext is stored in \textit{pt}, and the ciphertext in \textit{ct}. The length of both are expected to be equal and is passed in as \textit{ptlen}. It is -allowable that $pt = ct$. The \textit{direction} variable indicates whether encryption (direction $=$ \textbf{CCM\_ENCRYPT}) or +allowable that $pt = ct$. The \textit{direction} variable indicates whether encryption (direction $=$ \textbf{CCM\_ENCRYPT}) or decryption (direction $=$ \textbf{CCM\_DECRYPT}) is to be performed. -As implemented, this version of CCM cannot handle header or plaintext data longer than $2^{32} - 1$ octets long. +As implemented, this version of CCM cannot handle header or plaintext data longer than $2^{32} - 1$ octets long. You can test the implementation of CCM with the following function. @@ -1564,7 +1564,7 @@ The following is a sample of how to call CCM. #include int main(void) { - unsigned char key[16], nonce[12], pt[32], ct[32], + unsigned char key[16], nonce[12], pt[32], ct[32], tag[16], tagcp[16]; unsigned long taglen; int err; @@ -1573,10 +1573,10 @@ int main(void) register_cipher(&aes_desc); /* somehow fill key, nonce, pt */ - + /* encrypt it */ taglen = sizeof(tag); - if ((err = + if ((err = ccm_memory(find_cipher("aes"), key, 16, /* 128-bit key */ NULL, /* not prescheduled */ @@ -1593,7 +1593,7 @@ int main(void) /* decrypt it */ taglen = sizeof(tagcp); - if ((err = + if ((err = ccm_memory(find_cipher("aes"), key, 16, /* 128-bit key */ NULL, /* not prescheduled */ @@ -1614,37 +1614,37 @@ int main(void) \end{small} \subsection{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 +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 initial 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). +A GCM stream is meant to be processed in three modes, one after another. First, the initial 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). \subsubsection{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 gcm_init( gcm_state *gcm, int cipher, - const unsigned char *key, + 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). +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). \subsubsection{Initial Vector} 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. \index{gcm\_add\_iv()} \begin{verbatim} -int gcm_add_iv( gcm_state *gcm, - const unsigned char *IV, +int gcm_add_iv( gcm_state *gcm, + const unsigned char *IV, unsigned long IVlen); \end{verbatim} This adds the initial 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. +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. @@ -1656,25 +1656,25 @@ you begin adding AAD to the GCM state you cannot return to adding IV data until \index{gcm\_add\_aad()} \begin{verbatim} -int gcm_add_aad( gcm_state *gcm, - const unsigned char *adata, +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}. \subsubsection{Plaintext Processing} -After the AAD has been processed, the plaintext (or ciphertext depending on the direction) can be processed. +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 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, +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, encrypted and stored in the ciphertext buffer. When \textit{direction} equals \textbf{GCM\_DECRYPT} the opposite occurs. \subsubsection{State Termination} @@ -1682,8 +1682,8 @@ To terminate a GCM state and retrieve the message authentication tag call the fo \index{gcm\_done()} \begin{verbatim} -int gcm_done( gcm_state *gcm, - unsigned char *tag, +int gcm_done( gcm_state *gcm, + unsigned char *tag, unsigned long *taglen); \end{verbatim} This terminates the GCM state \textit{gcm} and stores the tag in \textit{tag} of length \textit{taglen} octets. @@ -1704,14 +1704,14 @@ To process a single packet under any given key the following helper function can \index{gcm\_memory()} \begin{verbatim} -int gcm_memory( +int gcm_memory( int cipher, - const unsigned char *key, + const unsigned char *key, unsigned long keylen, const unsigned char *IV, unsigned long IVlen, const unsigned char *adata, unsigned long adatalen, unsigned char *pt, unsigned long ptlen, - unsigned char *ct, + unsigned char *ct, unsigned char *tag, unsigned long *taglen, int direction); \end{verbatim} @@ -1741,7 +1741,7 @@ int send_packet(const unsigned char *pt, unsigned long ptlen, if ((err = gcm_reset(gcm)) != CRYPT_OK) { return err; } - + /* Add the IV */ if ((err = gcm_add_iv(gcm, iv, ivlen)) != CRYPT_OK) { return err; @@ -1753,7 +1753,7 @@ int send_packet(const unsigned char *pt, unsigned long ptlen, } /* process the plaintext */ - if ((err = + if ((err = gcm_process(gcm, pt, ptlen, pt, GCM_ENCRYPT)) != CRYPT_OK) { return err; } @@ -1766,7 +1766,7 @@ int send_packet(const unsigned char *pt, unsigned long ptlen, /* ... send a header describing the lengths ... */ - /* depending on the protocol and how IV is + /* depending on the protocol and how IV is * generated you may have to send it too... */ send(socket, iv, ivlen, 0); @@ -1787,15 +1787,15 @@ int main(void) gcm_state gcm; unsigned char key[16], IV[12], pt[PACKET_SIZE]; int err, x; - unsigned long ptlen; - + unsigned long ptlen; + /* somehow fill key/IV with random values */ - + /* register AES */ register_cipher(&aes_desc); /* init the GCM state */ - if ((err = + if ((err = gcm_init(&gcm, find_cipher("aes"), key, 16)) != CRYPT_OK) { whine_and_pout(err); } @@ -1811,7 +1811,7 @@ int main(void) } } - if ((err = send_packet(pt, ptlen, iv, 12, NULL, 0, &gcm)) + if ((err = send_packet(pt, ptlen, iv, 12, NULL, 0, &gcm)) != CRYPT_OK) { whine_and_pout(err); } @@ -1823,7 +1823,7 @@ int main(void) \chapter{One-Way Cryptographic Hash Functions} \mysection{Core Functions} -Like the ciphers, there are hash core functions and a universal data type to hold the hash state called \textit{hash\_state}. To initialize hash +Like the ciphers, there are hash core functions and a universal data type to hold the hash state called \textit{hash\_state}. To initialize hash XXX (where XXX is the name) call: \index{Hash Functions} \begin{verbatim} @@ -1832,12 +1832,12 @@ void XXX_init(hash_state *md); This simply sets up the hash to the default state governed by the specifications of the hash. To add data to the message being hashed call: \begin{verbatim} -int XXX_process( hash_state *md, - const unsigned char *in, +int XXX_process( hash_state *md, + const unsigned char *in, unsigned long inlen); \end{verbatim} -Essentially all hash messages are virtually infinitely\footnote{Most hashes are limited to $2^{64}$ bits or 2,305,843,009,213,693,952 bytes.} long message which -are buffered. The data can be passed in any sized chunks as long as the order of the bytes are the same the message digest (hash output) will be the same. For example, +Essentially all hash messages are virtually infinitely\footnote{Most hashes are limited to $2^{64}$ bits or 2,305,843,009,213,693,952 bytes.} long message which +are buffered. The data can be passed in any sized chunks as long as the order of the bytes are the same the message digest (hash output) will be the same. For example, this means that: \begin{verbatim} md5_process(&md, "hello ", 6); @@ -1851,7 +1851,7 @@ md5_process(&md, "hello world", 11); To finally get the message digest (the hash) call: \begin{verbatim} -int XXX_done( hash_state *md, +int XXX_done( hash_state *md, unsigned char *out); \end{verbatim} @@ -1900,8 +1900,8 @@ struct _hash_descriptor { void (*init) (hash_state *hash); - int (*process)( hash_state *hash, - const unsigned char *in, + int (*process)( hash_state *hash, + const unsigned char *in, unsigned long inlen); int (*done) (hash_state *hash, unsigned char *out); @@ -1913,9 +1913,9 @@ struct _hash_descriptor { \index{find\_hash()} The \textit{name} member is the name of the hash function (all lowercase). The \textit{hashsize} member is the size of the digest output in bytes, while \textit{blocksize} is the size of blocks the hash expects to the compression function. Technically, this detail is not important -for high level developers but is useful to know for performance reasons. +for high level developers but is useful to know for performance reasons. -The \textit{init} member initializes the hash, \textit{process} passes data through the hash, \textit{done} terminates the hash and retrieves the +The \textit{init} member initializes the hash, \textit{process} passes data through the hash, \textit{done} terminates the hash and retrieves the digest. The \textit{test} member tests the hash against the specified test vectors. There is a function to search the array as well called \textit{int find\_hash(char *name)}. It returns -1 if the hash is not found, otherwise, the @@ -1978,42 +1978,42 @@ length. This provides a simple size you can set your automatic arrays to that w There are three helper functions to make working with hashes easier. The first is a function to hash a buffer, and produce the digest in a single function call. -\index{hash\_memory()} +\index{hash\_memory()} \begin{verbatim} -int hash_memory( int hash, - const unsigned char *in, - unsigned long inlen, - unsigned char *out, +int hash_memory( int hash, + const unsigned char *in, + unsigned long inlen, + unsigned char *out, unsigned long *outlen); \end{verbatim} This will hash the data pointed to by \textit{in} of length \textit{inlen}. The hash used is indexed by the \textit{hash} parameter. The message -digest is stored in \textit{out}, and the \textit{outlen} parameter is updated to hold the message digest size. +digest is stored in \textit{out}, and the \textit{outlen} parameter is updated to hold the message digest size. -The next helper function allows for the hashing of a file based on a file name. +The next helper function allows for the hashing of a file based on a file name. \index{hash\_file()} \begin{verbatim} -int hash_file( int hash, - const char *fname, - unsigned char *out, +int hash_file( int hash, + const char *fname, + unsigned char *out, unsigned long *outlen); \end{verbatim} -This will hash the file named by \textit{fname} using the hash indexed by \textit{hash}. The file named in this function call must be readable by the +This will hash the file named by \textit{fname} using the hash indexed by \textit{hash}. The file named in this function call must be readable by the user owning the process performing the request. This function can be omitted by the \textbf{LTC\_NO\_FILE} define, which forces it to return \textbf{CRYPT\_NOP} -when it is called. The message digest is stored in \textit{out}, and the \textit{outlen} parameter is updated to hold the message digest size. +when it is called. The message digest is stored in \textit{out}, and the \textit{outlen} parameter is updated to hold the message digest size. \index{hash\_filehandle()} \begin{verbatim} -int hash_filehandle( int hash, - FILE *in, - unsigned char *out, +int hash_filehandle( int hash, + FILE *in, + unsigned char *out, unsigned long *outlen); \end{verbatim} This will hash the file identified by the handle \textit{in} using the hash indexed by \textit{hash}. This will begin hashing from the current file pointer position, and will not rewind the file pointer when finished. This function can be omitted by the \textbf{LTC\_NO\_FILE} define, which forces it to return \textbf{CRYPT\_NOP} -when it is called. The message digest is stored in \textit{out}, and the \textit{outlen} parameter is updated to hold the message digest size. +when it is called. The message digest is stored in \textit{out}, and the \textit{outlen} parameter is updated to hold the message digest size. To perform the above hash with md5 the following code could be used: \begin{small} @@ -2036,7 +2036,7 @@ int main(void) /* call the hash */ len = sizeof(out); - if ((err = + if ((err = hash_memory(idx, "hello world", 11, out, &len)) != CRYPT_OK) { printf("Error hashing data: %s\n", error_to_string(err)); return -1; @@ -2087,7 +2087,7 @@ The following hashes are provided as of this release within the LibTomCrypt libr \mysection{Cipher Hash Construction} \index{Cipher Hash Construction} An addition to the suite of hash functions is the \textit{Cipher Hash Construction} or \textit{CHC} mode. In this mode -applicable block ciphers (such as AES) can be turned into hash functions that other LTC functions can use. In +applicable block ciphers (such as AES) can be turned into hash functions that other LTC functions can use. In particular this allows a cryptosystem to be designed using very few moving parts. In order to use the CHC system the developer will have to take a few extra steps. First the \textit{chc\_desc} hash @@ -2100,12 +2100,12 @@ via the chc\_register() function. int chc_register(int cipher); \end{verbatim} -A cipher has to be registered with CHC (and also in the cipher descriptor tables with -register\_cipher()). The chc\_register() function will bind a cipher to the CHC system. Only one cipher can +A cipher has to be registered with CHC (and also in the cipher descriptor tables with +register\_cipher()). The chc\_register() function will bind a cipher to the CHC system. Only one cipher can be bound to the CHC hash at a time. There are additional requirements for the system to work. \begin{enumerate} - \item The cipher must have a block size greater than 64--bits. + \item The cipher must have a block size greater than 64--bits. \item The cipher must allow an input key the size of the block size. \end{enumerate} @@ -2115,7 +2115,7 @@ Example of using CHC with the AES block cipher. #include int main(void) { - int err; + int err; /* register cipher and hash */ if (register_cipher(&aes_enc_desc) == -1) { @@ -2129,18 +2129,18 @@ int main(void) /* start chc with AES */ if ((err = chc_register(find_cipher("aes"))) != CRYPT_OK) { - printf("Error binding AES to CHC: %s\n", + printf("Error binding AES to CHC: %s\n", error_to_string(err)); } - /* now you can use chc_hash in any LTC function + /* now you can use chc_hash in any LTC function * [aside from pkcs...] */ } \end{verbatim} \mysection{Notice} -It is highly recommended that you \textbf{not} use the MD4 or MD5 hashes for the purposes of digital signatures or authentication codes. +It is highly recommended that you \textbf{not} use the MD4 or MD5 hashes for the purposes of digital signatures or authentication codes. These hashes are provided for completeness and they still can be used for the purposes of password hashing or one-way accumulators (e.g. Yarrow). @@ -2152,16 +2152,16 @@ for all purposes you would normally use a hash for. Thanks to Dobes Vandermeer, the library now includes support for hash based message authentication codes, or HMAC for short. An HMAC of a message is a keyed authentication code that only the owner of a private symmetric key will be able to verify. The purpose is to allow an owner of a private symmetric key to produce an HMAC on a message then later verify if it is correct. Any impostor or -eavesdropper will not be able to verify the authenticity of a message. +eavesdropper will not be able to verify the authenticity of a message. -The HMAC support works much like the normal hash functions except that the initialization routine requires you to pass a key +The HMAC support works much like the normal hash functions except that the initialization routine requires you to pass a key and its length. The key is much like a key you would pass to a cipher. That is, it is simply an array of octets stored in unsigned characters. The initialization routine is: \index{hmac\_init()} \begin{verbatim} -int hmac_init( hmac_state *hmac, - int hash, - const unsigned char *key, +int hmac_init( hmac_state *hmac, + int hash, + const unsigned char *key, unsigned long keylen); \end{verbatim} The \textit{hmac} parameter is the state for the HMAC code. The \textit{hash} parameter is the index into the descriptor table of the hash you want @@ -2169,20 +2169,20 @@ to use to authenticate the message. The \textit{key} parameter is the pointer t length (in octets) of the key you want to use to authenticate the message. To send octets of a message through the HMAC system you must use the following function: \index{hmac\_process()} \begin{verbatim} -int hmac_process( hmac_state *hmac, - const unsigned char *in, +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{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, +int hmac_done( hmac_state *hmac, + unsigned char *out, unsigned long *outlen); \end{verbatim} -The \textit{hmac} parameter is the HMAC state you are working with. The \textit{out} parameter is the array of octets where the HMAC code should be stored. +The \textit{hmac} parameter is the HMAC state you are working with. The \textit{out} parameter is the array of octets where the HMAC code should be stored. You must set \textit{outlen} to the size of the destination buffer before calling this function. It is updated with the length of the HMAC code produced (depending on which hash was picked). If \textit{outlen} is less than the size of the message digest (and ultimately the HMAC code) then the HMAC code is truncated as per FIPS-198 specifications (e.g. take the first \textit{outlen} bytes). @@ -2194,25 +2194,25 @@ calling the three step process yourself. \index{hmac\_memory()} \begin{verbatim} int hmac_memory( - int hash, + int hash, const unsigned char *key, unsigned long keylen, - const unsigned char *in, unsigned long inlen, + const unsigned char *in, unsigned long inlen, unsigned char *out, unsigned long *outlen); \end{verbatim} -This will produce an HMAC code for the array of octets in \textit{in} of length \textit{inlen}. The index into the hash descriptor -table must be provided in \textit{hash}. It uses the key from \textit{key} with a key length of \textit{keylen}. +This will produce an HMAC code for the array of octets in \textit{in} of length \textit{inlen}. The index into the hash descriptor +table must be provided in \textit{hash}. It uses the key from \textit{key} with a key length of \textit{keylen}. The result is stored in the array of octets \textit{out} and the length in \textit{outlen}. The value of \textit{outlen} must be set to the size of the destination buffer before calling this function. Similarly for files there is the following function: \index{hmac\_file()} \begin{verbatim} int hmac_file( - int hash, - const char *fname, - const unsigned char *key, unsigned long keylen, + int hash, + const char *fname, + const unsigned char *key, unsigned long keylen, unsigned char *out, unsigned long *outlen); \end{verbatim} -\textit{hash} is the index into the hash descriptor table of the hash you want to use. \textit{fname} is the filename to process. -\textit{key} is the array of octets to use as the key of length \textit{keylen}. \textit{out} is the array of octets where the +\textit{hash} is the index into the hash descriptor table of the hash you want to use. \textit{fname} is the filename to process. +\textit{key} is the array of octets to use as the key of length \textit{keylen}. \textit{out} is the array of octets where the result should be stored. To test if the HMAC code is working there is the following function: @@ -2220,7 +2220,7 @@ To test if the HMAC code is working there is the following function: \begin{verbatim} int hmac_test(void); \end{verbatim} -Which returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code. Some example code for using the +Which returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code. Some example code for using the HMAC system is given below. \begin{small} @@ -2263,7 +2263,7 @@ int main(void) return -1; } printf("The hmac is %lu bytes long\n", dstlen); - + /* return */ return 0; } @@ -2272,17 +2272,17 @@ int main(void) \mysection{OMAC Support} \index{OMAC} \index{CMAC} -OMAC\footnote{\url{http://crypt.cis.ibaraki.ac.jp/omac/omac.html}}, which stands for \textit{One-Key CBC MAC} is an +OMAC\footnote{\url{http://crypt.cis.ibaraki.ac.jp/omac/omac.html}}, which stands for \textit{One-Key CBC MAC} is an algorithm which produces a Message Authentication Code (MAC) using only a block cipher such as AES. Note: OMAC has been standardized as -CMAC within NIST, for the purposes of this library OMAC and CMAC are synonymous. From an API standpoint, the OMAC routines work much like the -HMAC routines. Instead, in this case a cipher is used instead of a hash. +CMAC within NIST, for the purposes of this library OMAC and CMAC are synonymous. From an API standpoint, the OMAC routines work much like the +HMAC routines. Instead, in this case a cipher is used instead of a hash. To start an OMAC state you call \index{omac\_init()} \begin{verbatim} -int omac_init( omac_state *omac, - int cipher, - const unsigned char *key, +int omac_init( omac_state *omac, + int cipher, + const unsigned char *key, unsigned long keylen); \end{verbatim} The \textit{omac} parameter is the state for the OMAC algorithm. The \textit{cipher} parameter is the index into the cipher\_descriptor table @@ -2292,11 +2292,11 @@ wish to use. The \textit{key} and \textit{keylen} parameters are the keys used To send data through the algorithm call \index{omac\_process()} \begin{verbatim} -int omac_process( omac_state *state, - const unsigned char *in, +int omac_process( omac_state *state, + const unsigned char *in, unsigned long inlen); \end{verbatim} -This will send \textit{inlen} bytes from \textit{in} through the active OMAC state \textit{state}. Returns \textbf{CRYPT\_OK} if the +This will send \textit{inlen} bytes from \textit{in} through the active OMAC state \textit{state}. Returns \textbf{CRYPT\_OK} if the function succeeds. The function is not sensitive to the granularity of the data. For example, \begin{verbatim} @@ -2314,23 +2314,23 @@ When you are done processing the message you can call the following to compute t \index{omac\_done()} \begin{verbatim} -int omac_done( omac_state *state, - unsigned char *out, +int omac_done( omac_state *state, + unsigned char *out, unsigned long *outlen); \end{verbatim} -Which will terminate the OMAC and output the \textit{tag} (MAC) to \textit{out}. Note that unlike the HMAC and other code -\textit{outlen} can be smaller than the default MAC size (for instance AES would make a 16-byte tag). Part of the OMAC +Which will terminate the OMAC and output the \textit{tag} (MAC) to \textit{out}. Note that unlike the HMAC and other code +\textit{outlen} can be smaller than the default MAC size (for instance AES would make a 16-byte tag). Part of the OMAC specification states that the output may be truncated. So if you pass in $outlen = 5$ and use AES as your cipher than the output MAC code will only be five bytes long. If \textit{outlen} is larger than the default size it is set to the default size to show how many bytes were actually used. -Similar to the HMAC code the file and memory functions are also provided. To OMAC a buffer of memory in one shot use the +Similar to the HMAC code the file and memory functions are also provided. To OMAC a buffer of memory in one shot use the following function. \index{omac\_memory()} \begin{verbatim} -int omac_memory( - int cipher, +int omac_memory( + int cipher, const unsigned char *key, unsigned long keylen, const unsigned char *in, unsigned long inlen, unsigned char *out, unsigned long *outlen); @@ -2343,14 +2343,14 @@ To OMAC a file use \index{omac\_file()} \begin{verbatim} int omac_file( - int cipher, + int cipher, const unsigned char *key, unsigned long keylen, - const char *filename, + const char *filename, unsigned char *out, unsigned long *outlen); \end{verbatim} Which will OMAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes -and the cipher specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with +and the cipher specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with the same rules as omac\_done. To test if the OMAC code is working there is the following function: @@ -2358,7 +2358,7 @@ To test if the OMAC code is working there is the following function: \begin{verbatim} int omac_test(void); \end{verbatim} -Which returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code. Some example code for using the +Which returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code. Some example code for using the OMAC system is given below. \begin{small} @@ -2401,7 +2401,7 @@ int main(void) return -1; } printf("The omac is %lu bytes long\n", dstlen); - + /* return */ return 0; } @@ -2409,17 +2409,17 @@ int main(void) \end{small} \mysection{PMAC Support} -The PMAC\footnote{J.Black, P.Rogaway, \textit{A Block--Cipher Mode of Operation for Parallelizable Message Authentication}} +The PMAC\footnote{J.Black, P.Rogaway, \textit{A Block--Cipher Mode of Operation for Parallelizable Message Authentication}} protocol is another MAC algorithm that relies solely on a symmetric-key block cipher. It uses essentially the same -API as the provided OMAC code. +API as the provided OMAC code. A PMAC state is initialized with the following. \index{pmac\_init()} \begin{verbatim} -int pmac_init( pmac_state *pmac, - int cipher, - const unsigned char *key, +int pmac_init( pmac_state *pmac, + int cipher, + const unsigned char *key, unsigned long keylen); \end{verbatim} Which initializes the \textit{pmac} state with the given \textit{cipher} and \textit{key} of length \textit{keylen} bytes. The chosen cipher @@ -2429,8 +2429,8 @@ To MAC data simply send it through the process function. \index{pmac\_process()} \begin{verbatim} -int pmac_process( pmac_state *state, - const unsigned char *in, +int pmac_process( pmac_state *state, + const unsigned char *in, unsigned long inlen); \end{verbatim} This will process \textit{inlen} bytes of \textit{in} in the given \textit{state}. The function is not sensitive to the granularity of the @@ -2451,20 +2451,20 @@ When a complete message has been processed the following function can be called \index{pmac\_done()} \begin{verbatim} -int pmac_done( pmac_state *state, - unsigned char *out, +int pmac_done( pmac_state *state, + unsigned char *out, unsigned long *outlen); \end{verbatim} This will store up to \textit{outlen} bytes of the tag for the given \textit{state} into \textit{out}. Note that if \textit{outlen} is larger than the size of the tag it is set to the amount of bytes stored in \textit{out}. -Similar to the OMAC code the file and memory functions are also provided. To PMAC a buffer of memory in one shot use the +Similar to the OMAC code the file and memory functions are also provided. To PMAC a buffer of memory in one shot use the following function. \index{pmac\_memory()} \begin{verbatim} int pmac_memory( - int cipher, + int cipher, const unsigned char *key, unsigned long keylen, const unsigned char *in, unsigned long inlen, unsigned char *out, unsigned long *outlen); @@ -2477,14 +2477,14 @@ To PMAC a file use \index{pmac\_file()} \begin{verbatim} int pmac_file( - int cipher, + int cipher, const unsigned char *key, unsigned long keylen, - const char *filename, + const char *filename, unsigned char *out, unsigned long *outlen); \end{verbatim} -Which will PMAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes, -and the cipher specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with +Which will PMAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes, +and the cipher specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with the same rules as pmac\_done(). To test if the PMAC code is working there is the following function: @@ -2495,22 +2495,22 @@ int pmac_test(void); Which returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code. \mysection{Pelican MAC} -Pelican MAC is a new (experimental) MAC by the AES team that uses four rounds of AES as a \textit{mixing function}. It achieves a very high +Pelican MAC is a new (experimental) MAC by the AES team that uses four rounds of AES as a \textit{mixing function}. It achieves a very high rate of processing and is potentially very secure. It requires AES to be enabled to function. You do not have to register\_cipher() AES first though as it calls AES directly. \index{pelican\_init()} \begin{verbatim} -int pelican_init( pelican_state *pelmac, - const unsigned char *key, +int pelican_init( pelican_state *pelmac, + const unsigned char *key, unsigned long keylen); \end{verbatim} This will initialize the Pelican state with the given AES key. Once this has been done you can begin processing data. \index{pelican\_process()} \begin{verbatim} -int pelican_process( pelican_state *pelmac, - const unsigned char *in, +int pelican_process( pelican_state *pelmac, + const unsigned char *in, unsigned long inlen); \end{verbatim} This will process \textit{inlen} bytes of \textit{in} through the Pelican MAC. It's best that you pass in multiples of 16 bytes as it makes the @@ -2540,17 +2540,17 @@ int main(void) key, /* user key */ 32 /* key length in octets */ )) != CRYPT_OK) { - printf("Error initializing Pelican: %s", + printf("Error initializing Pelican: %s", error_to_string(err)); return EXIT_FAILURE; } /* MAC some data */ if ((err = pelican_process(&pelstate, /* the state */ - "hello world", /* data to mac */ + "hello world", /* data to mac */ 11 /* length of data */ )) != CRYPT_OK) { - printf("Error processing Pelican: %s", + printf("Error processing Pelican: %s", error_to_string(err)); return EXIT_FAILURE; } @@ -2559,7 +2559,7 @@ int main(void) if ((err = pelican_done(&pelstate,/* the state */ tag /* where to store the tag */ )) != CRYPT_OK) { - printf("Error terminating Pelican: %s", + printf("Error terminating Pelican: %s", error_to_string(err)); return EXIT_FAILURE; } @@ -2577,9 +2577,9 @@ initialized with the following function: \index{xcbc\_init()} \begin{verbatim} -int xcbc_init( xcbc_state *xcbc, - int cipher, - const unsigned char *key, +int xcbc_init( xcbc_state *xcbc, + int cipher, + const unsigned char *key, unsigned long keylen); \end{verbatim} @@ -2588,7 +2588,7 @@ by the \textit{cipher} index can be either a 64 or 128--bit block cipher. This \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 +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. @@ -2597,8 +2597,8 @@ To process data through XCBC--MAC use the following function: \index{xcbc\_process()} \begin{verbatim} -int xcbc_process( xcbc_state *state, - const unsigned char *in, +int xcbc_process( xcbc_state *state, + const unsigned char *in, unsigned long inlen); \end{verbatim} @@ -2609,8 +2609,8 @@ To compute the MAC tag value use the following function: \index{xcbc\_done()} \begin{verbatim} -int xcbc_done( xcbc_state *state, - unsigned char *out, +int xcbc_done( xcbc_state *state, + unsigned char *out, unsigned long *outlen); \end{verbatim} @@ -2622,7 +2622,7 @@ Helper functions are provided to make parsing memory buffers and files easier. \index{xcbc\_memory()} \begin{verbatim} int xcbc_memory( - int cipher, + int cipher, const unsigned char *key, unsigned long keylen, const unsigned char *in, unsigned long inlen, unsigned char *out, unsigned long *outlen); @@ -2634,13 +2634,13 @@ To xcbc a file use \index{xcbc\_file()} \begin{verbatim} int xcbc_file( - int cipher, + int cipher, const unsigned char *key, unsigned long keylen, - const char *filename, + const char *filename, unsigned char *out, unsigned long *outlen); \end{verbatim} -Which will XCBC--MAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes, and the cipher +Which will XCBC--MAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes, and the cipher specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with the same rules as xcbc\_done(). @@ -2651,17 +2651,17 @@ To test XCBC--MAC for RFC 3566 compliance use the following function: int xcbc_test(void); \end{verbatim} -This will return \textbf{CRYPT\_OK} on success. This requires the AES or Rijndael descriptor be previously registered, otherwise, it will return -\textbf{CRYPT\_NOP}. +This will return \textbf{CRYPT\_OK} on success. This requires the AES or Rijndael descriptor be previously registered, otherwise, it will return +\textbf{CRYPT\_NOP}. \mysection{F9--MAC} The F9--MAC is yet another CBC--MAC variant proposed for the 3GPP standard. Originally specified to be used with the KASUMI block cipher, it can also be used -with other ciphers. For LibTomCrypt, the F9--MAC code can use any cipher. +with other ciphers. For LibTomCrypt, the F9--MAC code can use any cipher. \subsection{Usage Notice} F9--MAC differs slightly from the other MAC functions in that it requires the caller to perform the final message padding. The padding quite simply is a direction -bit followed by a 1 bit and enough zeros to make the message a multiple of the cipher block size. If the message is byte aligned, the padding takes on the form of -a single 0x40 or 0xC0 byte followed by enough 0x00 bytes to make the message proper multiple. +bit followed by a 1 bit and enough zeros to make the message a multiple of the cipher block size. If the message is byte aligned, the padding takes on the form of +a single 0x40 or 0xC0 byte followed by enough 0x00 bytes to make the message proper multiple. If the user simply wants a MAC function (hint: use OMAC) padding with a single 0x40 byte should be sufficient for security purposes and still be reasonably compatible with F9--MAC. @@ -2670,9 +2670,9 @@ with F9--MAC. A F9--MAC state is initialized with the following function: \index{f9\_init()} \begin{verbatim} -int f9_init( f9_state *f9, - int cipher, - const unsigned char *key, +int f9_init( f9_state *f9, + int cipher, + const unsigned char *key, unsigned long keylen); \end{verbatim} @@ -2682,8 +2682,8 @@ by the \textit{cipher} index can be either a 64 or 128--bit block cipher. This To process data through F9--MAC use the following function: \index{f9\_process()} \begin{verbatim} -int f9_process( f9_state *state, - const unsigned char *in, +int f9_process( f9_state *state, + const unsigned char *in, unsigned long inlen); \end{verbatim} @@ -2694,13 +2694,13 @@ To compute the MAC tag value use the following function: \index{f9\_done()} \begin{verbatim} -int f9_done( f9_state *state, - unsigned char *out, +int f9_done( f9_state *state, + unsigned char *out, unsigned long *outlen); \end{verbatim} This will retrieve the F9--MAC tag from the state pointed to by \textit{state}, and store it in the array pointed to by \textit{out}. The \textit{outlen} parameter -specifies the maximum size of the destination buffer, and is updated to hold the final size of the tag when the function returns. This will return +specifies the maximum size of the destination buffer, and is updated to hold the final size of the tag when the function returns. This will return \textbf{CRYPT\_OK} on success. Helper functions are provided to make parsing memory buffers and files easier. The following functions are provided: @@ -2708,7 +2708,7 @@ Helper functions are provided to make parsing memory buffers and files easier. \index{f9\_memory()} \begin{verbatim} int f9_memory( - int cipher, + int cipher, const unsigned char *key, unsigned long keylen, const unsigned char *in, unsigned long inlen, unsigned char *out, unsigned long *outlen); @@ -2720,13 +2720,13 @@ To F9--MAC a file use \index{f9\_file()} \begin{verbatim} int f9_file( - int cipher, + int cipher, const unsigned char *key, unsigned long keylen, - const char *filename, + const char *filename, unsigned char *out, unsigned long *outlen); \end{verbatim} -Which will F9--MAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes, and the cipher +Which will F9--MAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes, and the cipher specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with the same rules as f9\_done(). @@ -2737,8 +2737,8 @@ To test f9--MAC for RFC 3566 compliance use the following function: int f9_test(void); \end{verbatim} -This will return \textbf{CRYPT\_OK} on success. This requires the AES or Rijndael descriptor be previously registered, otherwise, it will return -\textbf{CRYPT\_NOP}. +This will return \textbf{CRYPT\_OK} on success. This requires the AES or Rijndael descriptor be previously registered, otherwise, it will return +\textbf{CRYPT\_NOP}. \chapter{Pseudo-Random Number Generators} \mysection{Core Functions} @@ -2750,12 +2750,12 @@ key generation. There is a universal structure called \textit{prng\_state}. To int XXX_start(prng_state *prng); \end{verbatim} -This will setup the PRNG for future use and not seed it. In order for the PRNG to be cryptographically useful you must give it +This will setup the PRNG for future use and not seed it. In order for the PRNG to be cryptographically useful you must give it entropy. Ideally you'd have some OS level source to tap like in UNIX. To add entropy to the PRNG call: \index{PRNG add\_entropy} \begin{verbatim} -int XXX_add_entropy(const unsigned char *in, - unsigned long inlen, +int XXX_add_entropy(const unsigned char *in, + unsigned long inlen, prng_state *prng); \end{verbatim} Which returns {\bf CRYPT\_OK} if the entropy was accepted. Once you think you have enough entropy you call another @@ -2768,7 +2768,7 @@ int XXX_ready(prng_state *prng); Which returns {\bf CRYPT\_OK} if it is ready. Finally to actually read bytes call: \index{PRNG read} \begin{verbatim} -unsigned long XXX_read(unsigned char *out, +unsigned long XXX_read(unsigned char *out, unsigned long outlen, prng_state *prng); \end{verbatim} @@ -2786,19 +2786,19 @@ so that you can later resume the PRNG call the following. \index{PRNG export} \begin{verbatim} -int XXX_export(unsigned char *out, - unsigned long *outlen, +int XXX_export(unsigned char *out, + unsigned long *outlen, prng_state *prng); \end{verbatim} -This will write a \textit{PRNG state} to the buffer \textit{out} of length \textit{outlen} bytes. The idea of +This will write a \textit{PRNG state} to the buffer \textit{out} of length \textit{outlen} bytes. The idea of the export is meant to be used as a \textit{seed file}. That is, when the program starts up there will not likely be that much entropy available. To import a state to seed a PRNG call the following function. \index{PRNG import} \begin{verbatim} -int XXX_import(const unsigned char *in, - unsigned long inlen, +int XXX_import(const unsigned char *in, + unsigned long inlen, prng_state *prng); \end{verbatim} @@ -2807,7 +2807,7 @@ This will call the start and add\_entropy functions of the given PRNG. It will by the corresponding export function. Note that importing a state will not \textit{resume} the PRNG from where it left off. That is, if you export -a state, emit (say) 8 bytes and then import the previously exported state the next 8 bytes will not +a state, emit (say) 8 bytes and then import the previously exported state the next 8 bytes will not specifically equal the 8 bytes you generated previously. When a program is first executed the normal course of operation is: @@ -2818,13 +2818,13 @@ When a program is first executed the normal course of operation is: \end{enumerate} When your program is finished you simply call the export function and save the state to a medium (disk, -flash memory, etc). The next time your application starts up you can detect the state, feed it to the +flash memory, etc). The next time your application starts up you can detect the state, feed it to the import function and go on your way. It is ideal that (as soon as possible) after start up you export a fresh state. This helps in the case that the program aborts or the machine is powered down without -being given a chance to exit properly. +being given a chance to exit properly. Note that even if you have a state to import it is important to add new entropy to the state. However, -there is less pressure to do so. +there is less pressure to do so. To test a PRNG for operational conformity call the following functions. @@ -2839,11 +2839,11 @@ This will return \textbf{CRYPT\_OK} if PRNG is operating properly. It is possible to be adding entropy and reading from a PRNG at the same time. For example, if you first seed the PRNG and call ready() you can now read from it. You can also keep adding new entropy to it. The new entropy will not be used -in the PRNG until ready() is called again. This allows the PRNG to be used and re-seeded at the same time. No real error +in the PRNG until ready() is called again. This allows the PRNG to be used and re-seeded at the same time. No real error checking is guaranteed to see if the entropy is sufficient, or if the PRNG is even in a ready state before reading. \subsection{Example} -Below is a simple snippet to read 10 bytes from Yarrow. It is important to note that this snippet is {\bf NOT} secure since +Below is a simple snippet to read 10 bytes from Yarrow. It is important to note that this snippet is {\bf NOT} secure since the entropy added is not random. \begin{verbatim} @@ -2853,13 +2853,13 @@ int main(void) prng_state prng; unsigned char buf[10]; int err; - + /* start it */ if ((err = yarrow_start(&prng)) != CRYPT_OK) { printf("Start error: %s\n", error_to_string(err)); } /* add entropy */ - if ((err = yarrow_add_entropy("hello world", 11, &prng)) + if ((err = yarrow_add_entropy("hello world", 11, &prng)) != CRYPT_OK) { printf("Add_entropy error: %s\n", error_to_string(err)); } @@ -2867,7 +2867,7 @@ int main(void) if ((err = yarrow_ready(&prng)) != CRYPT_OK) { printf("Ready error: %s\n", error_to_string(err)); } - printf("Read %lu bytes from yarrow\n", + printf("Read %lu bytes from yarrow\n", yarrow_read(buf, sizeof(buf), &prng)); return 0; } @@ -2875,7 +2875,7 @@ int main(void) \mysection{PRNG Descriptors} \index{PRNG Descriptor} -PRNGs have descriptors that allow plugin driven functions to be created using PRNGs. The plugin descriptors are stored in the structure \textit{prng\_descriptor}. The +PRNGs have descriptors that allow plugin driven functions to be created using PRNGs. The plugin descriptors are stored in the structure \textit{prng\_descriptor}. The format of an element is: \begin{verbatim} struct _prng_descriptor { @@ -2884,12 +2884,12 @@ struct _prng_descriptor { int (*start) (prng_state *); - int (*add_entropy)(const unsigned char *, unsigned long, + int (*add_entropy)(const unsigned char *, unsigned long, prng_state *); int (*ready) (prng_state *); - unsigned long (*read)(unsigned char *, unsigned long len, + unsigned long (*read)(unsigned char *, unsigned long len, prng_state *); void (*done)(prng_state *); @@ -2910,7 +2910,7 @@ int find_prng(const char *name); This will search the PRNG descriptor table for the PRNG named \textit{name}. It will return -1 if the PRNG is not found, otherwise, it returns the index into the descriptor table. -Just like the ciphers and hashes, you must register your prng before you can use it. The two functions provided work exactly as those for the cipher registry functions. +Just like the ciphers and hashes, you must register your prng before you can use it. The two functions provided work exactly as those for the cipher registry functions. They are the following: \index{register\_prng()} \index{unregister\_prng()} \begin{verbatim} @@ -2940,8 +2940,8 @@ will return \textbf{CRYPT\_OK} if the PRNG was found and removed. Otherwise, it \end{figure} \subsubsection{Yarrow} -Yarrow is fast PRNG meant to collect an unspecified amount of entropy from sources -(keyboard, mouse, interrupts, etc), and produce an unbounded string of random bytes. +Yarrow is fast PRNG meant to collect an unspecified amount of entropy from sources +(keyboard, mouse, interrupts, etc), and produce an unbounded string of random bytes. \textit{Note:} This PRNG is still secure for most tasks but is no longer recommended. Users should use Fortuna instead. @@ -2951,38 +2951,38 @@ should use Fortuna instead. Fortuna is a fast attack tolerant and more thoroughly designed PRNG suitable for long term usage. It is faster than the default implementation of Yarrow\footnote{Yarrow has been implemented to work with most cipher and hash combos based on which you have chosen to build into the library.} while -providing more security. +providing more security. -Fortuna is slightly less flexible than Yarrow in the sense that it only works with the AES block cipher +Fortuna is slightly less flexible than Yarrow in the sense that it only works with the AES block cipher and SHA--256 hash function. Technically, Fortuna will work with any block cipher that accepts a 256--bit key, and any hash that produces at least a 256--bit output. However, to make the implementation simpler it has been fixed to those choices. -Fortuna is more secure than Yarrow in the sense that attackers who learn parts of the entropy being +Fortuna is more secure than Yarrow in the sense that attackers who learn parts of the entropy being added to the PRNG learn far less about the state than that of Yarrow. Without getting into to many details Fortuna has the ability to recover from state determination attacks where the attacker starts -to learn information from the PRNGs output about the internal state. Yarrow on the other hand, cannot +to learn information from the PRNGs output about the internal state. Yarrow on the other hand, cannot recover from that problem until new entropy is added to the pool and put to use through the ready() function. \subsubsection{RC4} RC4 is an old stream cipher that can also double duty as a PRNG in a pinch. You key RC4 by calling add\_entropy(), and setup the key by calling ready(). You can only add up to 256 bytes via -add\_entropy(). +add\_entropy(). -When you read from RC4, the output is XOR'ed against your buffer you provide. In this manner, you can use rc4\_read() -as an encrypt (and decrypt) function. +When you read from RC4, the output is XOR'ed against your buffer you provide. In this manner, you can use rc4\_read() +as an encrypt (and decrypt) function. -You really should not use RC4. This is not because RC4 is weak, (though biases are known to exist) but simply due to +You really should not use RC4. This is not because RC4 is weak, (though biases are known to exist) but simply due to the fact that faster alternatives exist. \subsubsection{SOBER-128} -SOBER--128 is a stream cipher designed by the QUALCOMM Australia team. Like RC4, you key it by -calling add\_entropy(). There is no need to call ready() for this PRNG as it does not do anything. +SOBER--128 is a stream cipher designed by the QUALCOMM Australia team. Like RC4, you key it by +calling add\_entropy(). There is no need to call ready() for this PRNG as it does not do anything. -Note: this cipher has several oddities about how it operates. The first call to add\_entropy() sets the cipher's key. -Every other time call to the add\_entropy() function sets the cipher's IV variable. The IV mechanism allows you to +Note: this cipher has several oddities about how it operates. The first call to add\_entropy() sets the cipher's key. +Every other time call to the add\_entropy() function sets the cipher's IV variable. The IV mechanism allows you to encrypt several messages with the same key, and not re--use the same key material. Unlike Yarrow and Fortuna, all of the entropy (and hence security) of this algorithm rests in the data @@ -2992,9 +2992,9 @@ that is a multiple of four bytes. Like RC4, the output of SOBER--128 is XOR'ed against the buffer you provide it. In this manner, you can use sober128\_read() as an encrypt (and decrypt) function. -Since SOBER-128 has a fixed keying scheme, and is very fast (faster than RC4) the ideal usage of SOBER-128 is to +Since SOBER-128 has a fixed keying scheme, and is very fast (faster than RC4) the ideal usage of SOBER-128 is to key it from the output of Fortuna (or Yarrow), and use it to encrypt messages. It is also ideal for -simulations which need a high quality (and fast) stream of bytes. +simulations which need a high quality (and fast) stream of bytes. \subsubsection{Example Usage} \begin{small} @@ -3030,39 +3030,39 @@ int main(void) exit(-1); } return 0; -} +} \end{verbatim} \end{small} -To decrypt you have to do the exact same steps. +To decrypt you have to do the exact same steps. \mysection{The Secure RNG} \index{Secure RNG} An RNG is related to a PRNG in many ways, except that it does not expand a smaller seed to get the data. They generate their random bits -by performing some computation on fresh input bits. Possibly the hardest thing to get correctly in a cryptosystem is the -PRNG. Computers are deterministic that try hard not to stray from pre--determined paths. This makes gathering entropy needed to seed a PRNG -a hard task. +by performing some computation on fresh input bits. Possibly the hardest thing to get correctly in a cryptosystem is the +PRNG. Computers are deterministic that try hard not to stray from pre--determined paths. This makes gathering entropy needed to seed a PRNG +a hard task. There is one small function that may help on certain platforms: \index{rng\_get\_bytes()} \begin{verbatim} unsigned long rng_get_bytes( - unsigned char *buf, - unsigned long len, + unsigned char *buf, + unsigned long len, void (*callback)(void)); \end{verbatim} -Which will try one of three methods of getting random data. The first is to open the popular \textit{/dev/random} device which -on most *NIX platforms provides cryptographic random bits\footnote{This device is available in Windows through the Cygwin compiler suite. It emulates \textit{/dev/random} via the Microsoft CSP.}. -The second method is to try the Microsoft Cryptographic Service Provider, and read the RNG. The third method is an ANSI C -clock drift method that is also somewhat popular but gives bits of lower entropy. The \textit{callback} parameter is a pointer to a function that returns void. It is -used when the slower ANSI C RNG must be used so the calling application can still work. This is useful since the ANSI C RNG has a throughput of roughly three -bytes a second. The callback pointer may be set to {\bf NULL} to avoid using it if you do not want to. The function returns the number of bytes actually read from +Which will try one of three methods of getting random data. The first is to open the popular \textit{/dev/random} device which +on most *NIX platforms provides cryptographic random bits\footnote{This device is available in Windows through the Cygwin compiler suite. It emulates \textit{/dev/random} via the Microsoft CSP.}. +The second method is to try the Microsoft Cryptographic Service Provider, and read the RNG. The third method is an ANSI C +clock drift method that is also somewhat popular but gives bits of lower entropy. The \textit{callback} parameter is a pointer to a function that returns void. It is +used when the slower ANSI C RNG must be used so the calling application can still work. This is useful since the ANSI C RNG has a throughput of roughly three +bytes a second. The callback pointer may be set to {\bf NULL} to avoid using it if you do not want to. The function returns the number of bytes actually read from any RNG source. There is a function to help setup a PRNG as well: \index{rng\_make\_prng()} \begin{verbatim} -int rng_make_prng( int bits, - int wprng, - prng_state *prng, +int rng_make_prng( int bits, + int wprng, + prng_state *prng, void (*callback)(void)); \end{verbatim} This will try to initialize the prng with a state of at least \textit{bits} of entropy. The \textit{callback} parameter works much like @@ -3085,14 +3085,14 @@ int main(void) } /* setup the PRNG */ - if ((err = rng_make_prng(128, find_prng("yarrow"), &prng, NULL)) + if ((err = rng_make_prng(128, find_prng("yarrow"), &prng, NULL)) != CRYPT_OK) { printf("Error setting up PRNG, %s\n", error_to_string(err)); return -1; } /* make a 192-bit ECC key */ - if ((err = ecc_make_key(&prng, find_prng("yarrow"), 24, &mykey)) + if ((err = ecc_make_key(&prng, find_prng("yarrow"), 24, &mykey)) != CRYPT_OK) { printf("Error making key: %s\n", error_to_string(err)); return -1; @@ -3104,7 +3104,7 @@ int main(void) \subsection{The Secure PRNG Interface} It is possible to access the secure RNG through the PRNG interface, and in turn use it within dependent functions such -as the PK API. This simplifies the cryptosystem on platforms where the secure RNG is fast. The secure PRNG never +as the PK API. This simplifies the cryptosystem on platforms where the secure RNG is fast. The secure PRNG never requires to be started, that is you need not call the start, add\_entropy, or ready functions. For example, consider the previous example using this PRNG. @@ -3123,7 +3123,7 @@ int main(void) } /* make a 192-bit ECC key */ - if ((err = ecc_make_key(NULL, find_prng("sprng"), 24, &mykey)) + if ((err = ecc_make_key(NULL, find_prng("sprng"), 24, &mykey)) != CRYPT_OK) { printf("Error making key: %s\n", error_to_string(err)); return -1; @@ -3138,31 +3138,31 @@ int main(void) \mysection{Introduction} RSA wrote the PKCS \#1 specifications which detail RSA Public Key Cryptography. In the specifications are padding algorithms for encryption and signatures. The standard includes the \textit{v1.5} and \textit{v2.1} algorithms. -To simplify matters a little the v2.1 encryption and signature padding algorithms are called OAEP and PSS respectively. +To simplify matters a little the v2.1 encryption and signature padding algorithms are called OAEP and PSS respectively. \mysection{PKCS \#1 Padding} PKCS \#1 v1.5 padding is so simple that both signature and encryption padding are performed by the same function. Note: the signature padding does \textbf{not} include the ASN.1 padding required. That is performed by the rsa\_sign\_hash\_ex() function -documented later on in this chapter. +documented later on in this chapter. \subsection{PKCS \#1 v1.5 Encoding} The following function performs PKCS \#1 v1.5 padding: \index{pkcs\_1\_v1\_5\_encode()} \begin{verbatim} int pkcs_1_v1_5_encode( - const unsigned char *msg, + const unsigned char *msg, unsigned long msglen, int block_type, unsigned long modulus_bitlen, - prng_state *prng, + prng_state *prng, int prng_idx, - unsigned char *out, + unsigned char *out, unsigned long *outlen); \end{verbatim} This will encode the message pointed to by \textit{msg} of length \textit{msglen} octets. The \textit{block\_type} parameter must be set to -\textbf{LTC\_PKCS\_1\_EME} to perform encryption padding. It must be set to \textbf{LTC\_PKCS\_1\_EMSA} to perform signature padding. The \textit{modulus\_bitlen} -parameter indicates the length of the modulus in bits. The padded data is stored in \textit{out} with a length of \textit{outlen} octets. The output will not be +\textbf{LTC\_PKCS\_1\_EME} to perform encryption padding. It must be set to \textbf{LTC\_PKCS\_1\_EMSA} to perform signature padding. The \textit{modulus\_bitlen} +parameter indicates the length of the modulus in bits. The padded data is stored in \textit{out} with a length of \textit{outlen} octets. The output will not be longer than the modulus which helps allocate the correct output buffer size. Only encryption padding requires a PRNG. When performing signature padding the \textit{prng\_idx} parameter may be left to zero as it is not checked for validity. @@ -3172,11 +3172,11 @@ The following function performs PKCS \#1 v1.5 de--padding: \index{pkcs\_1\_v1\_5\_decode()} \begin{verbatim} int pkcs_1_v1_5_decode( - const unsigned char *msg, + const unsigned char *msg, unsigned long msglen, int block_type, unsigned long modulus_bitlen, - unsigned char *out, + unsigned char *out, unsigned long *outlen, int *is_valid); \end{verbatim} @@ -3196,86 +3196,86 @@ The following function performs PKCS \#1 v2.1 encryption padding: \index{pkcs\_1\_oaep\_encode()} \begin{alltt} int pkcs_1_oaep_encode( - const unsigned char *msg, + const unsigned char *msg, unsigned long msglen, - const unsigned char *lparam, + const unsigned char *lparam, unsigned long lparamlen, - unsigned long modulus_bitlen, + unsigned long modulus_bitlen, prng_state *prng, int prng_idx, int hash_idx, - unsigned char *out, + unsigned char *out, unsigned long *outlen); \end{alltt} This accepts \textit{msg} as input of length \textit{msglen} which will be OAEP padded. The \textit{lparam} variable is an additional system specific tag that can be applied to the encoding. This is useful to identify which system encoded the message. If no variance is desired then -\textit{lparam} can be set to \textbf{NULL}. +\textit{lparam} can be set to \textbf{NULL}. OAEP encoding requires the length of the modulus in bits in order to calculate the size of the output. This is passed as the parameter -\textit{modulus\_bitlen}. \textit{hash\_idx} is the index into the hash descriptor table of the hash desired. PKCS \#1 allows any hash to be +\textit{modulus\_bitlen}. \textit{hash\_idx} is the index into the hash descriptor table of the hash desired. PKCS \#1 allows any hash to be used but both the encoder and decoder must use the same hash in order for this to succeed. The size of hash output affects the maximum - sized input message. \textit{prng\_idx} and \textit{prng} are the random number generator arguments required to randomize the padding process. + sized input message. \textit{prng\_idx} and \textit{prng} are the random number generator arguments required to randomize the padding process. The padded message is stored in \textit{out} along with the length in \textit{outlen}. -If $h$ is the length of the hash and $m$ the length of the modulus (both in octets) then the maximum payload for \textit{msg} is -$m - 2h - 2$. For example, with a $1024$--bit RSA key and SHA--1 as the hash the maximum payload is $86$ bytes. +If $h$ is the length of the hash and $m$ the length of the modulus (both in octets) then the maximum payload for \textit{msg} is +$m - 2h - 2$. For example, with a $1024$--bit RSA key and SHA--1 as the hash the maximum payload is $86$ bytes. -Note that when the message is padded it still has not been RSA encrypted. You must pass the output of this function to -rsa\_exptmod() to encrypt it. +Note that when the message is padded it still has not been RSA encrypted. You must pass the output of this function to +rsa\_exptmod() to encrypt it. \subsection{OAEP Decoding} \index{pkcs\_1\_oaep\_decode()} \begin{alltt} int pkcs_1_oaep_decode( - const unsigned char *msg, + const unsigned char *msg, unsigned long msglen, - const unsigned char *lparam, + const unsigned char *lparam, unsigned long lparamlen, - unsigned long modulus_bitlen, + unsigned long modulus_bitlen, int hash_idx, - unsigned char *out, + unsigned char *out, unsigned long *outlen, int *res); \end{alltt} -This function decodes an OAEP encoded message and outputs the original message that was passed to the OAEP encoder. \textit{msg} is the +This function decodes an OAEP encoded message and outputs the original message that was passed to the OAEP encoder. \textit{msg} is the output of pkcs\_1\_oaep\_encode() of length \textit{msglen}. \textit{lparam} is the same system variable passed to the OAEP encoder. If it does not match what was used during encoding this function will not decode the packet. \textit{modulus\_bitlen} is the size of the RSA modulus in bits and must match what was used during encoding. Similarly the \textit{hash\_idx} index into the hash descriptor table must match what was used during encoding. -If the function succeeds it decodes the OAEP encoded message into \textit{out} of length \textit{outlen} and stores a +If the function succeeds it decodes the OAEP encoded message into \textit{out} of length \textit{outlen} and stores a $1$ in \textit{res}. If the packet is invalid it stores $0$ in \textit{res} and if the function fails for another reason -it returns an error code. +it returns an error code. \mysection{PKCS \#1 Digital Signatures} \subsection{PSS Encoding} -PSS encoding is the second half of the PKCS \#1 standard which is padding to be applied to messages that are signed. +PSS encoding is the second half of the PKCS \#1 standard which is padding to be applied to messages that are signed. \index{pkcs\_1\_pss\_encode()} \begin{alltt} int pkcs_1_pss_encode( - const unsigned char *msghash, + const unsigned char *msghash, unsigned long msghashlen, - unsigned long saltlen, - prng_state *prng, - int prng_idx, + unsigned long saltlen, + prng_state *prng, + int prng_idx, int hash_idx, unsigned long modulus_bitlen, - unsigned char *out, + unsigned char *out, unsigned long *outlen); \end{alltt} -This function assumes the message to be PSS encoded has previously been hashed. The input hash \textit{msghash} is of length -\textit{msghashlen}. PSS allows a variable length random salt (it can be zero length) to be introduced in the signature process. +This function assumes the message to be PSS encoded has previously been hashed. The input hash \textit{msghash} is of length +\textit{msghashlen}. PSS allows a variable length random salt (it can be zero length) to be introduced in the signature process. \textit{hash\_idx} is the index into the hash descriptor table of the hash to use. \textit{prng\_idx} and \textit{prng} are the random number generator information required for the salt. Similar to OAEP encoding \textit{modulus\_bitlen} is the size of the RSA modulus (in bits). It limits the size of the salt. If $m$ is the length -of the modulus $h$ the length of the hash output (in octets) then there can be $m - h - 2$ bytes of salt. +of the modulus $h$ the length of the hash output (in octets) then there can be $m - h - 2$ bytes of salt. This function does not actually sign the data it merely pads the hash of a message so that it can be processed by rsa\_exptmod(). @@ -3286,17 +3286,17 @@ To decode a PSS encoded signature block you have to use the following. \index{pkcs\_1\_pss\_decode()} \begin{alltt} int pkcs_1_pss_decode( - const unsigned char *msghash, + const unsigned char *msghash, unsigned long msghashlen, - const unsigned char *sig, + const unsigned char *sig, unsigned long siglen, unsigned long saltlen, int hash_idx, - unsigned long modulus_bitlen, + unsigned long modulus_bitlen, int *res); \end{alltt} This will decode the PSS encoded message in \textit{sig} of length \textit{siglen} and compare it to values in \textit{msghash} of length -\textit{msghashlen}. If the block is a valid PSS block and the decoded hash equals the hash supplied \textit{res} is set to non--zero. Otherwise, +\textit{msghashlen}. If the block is a valid PSS block and the decoded hash equals the hash supplied \textit{res} is set to non--zero. Otherwise, it is set to zero. The rest of the parameters are as in the PSS encode call. It's important to use the same \textit{saltlen} and hash for both encoding and decoding as otherwise the procedure will not work. @@ -3304,75 +3304,75 @@ It's important to use the same \textit{saltlen} and hash for both encoding and d \mysection{RSA Key Operations} \subsection{Background} -RSA is a public key algorithm that is based on the inability to find the \textit{e-th} root modulo a composite of unknown +RSA is a public key algorithm that is based on the inability to find the \textit{e-th} root modulo a composite of unknown factorization. Normally the difficulty of breaking RSA is associated with the integer factoring problem but they are not strictly equivalent. The system begins with with two primes $p$ and $q$ and their product $N = pq$. The order or \textit{Euler totient} of the -multiplicative sub-group formed modulo $N$ is given as $\phi(N) = (p - 1)(q - 1)$ which can be reduced to -$\mbox{lcm}(p - 1, q - 1)$. The public key consists of the composite $N$ and some integer $e$ such that -$\mbox{gcd}(e, \phi(N)) = 1$. The private key consists of the composite $N$ and the inverse of $e$ modulo $\phi(N)$ +multiplicative sub-group formed modulo $N$ is given as $\phi(N) = (p - 1)(q - 1)$ which can be reduced to +$\mbox{lcm}(p - 1, q - 1)$. The public key consists of the composite $N$ and some integer $e$ such that +$\mbox{gcd}(e, \phi(N)) = 1$. The private key consists of the composite $N$ and the inverse of $e$ modulo $\phi(N)$ often simply denoted as $de \equiv 1\mbox{ }(\mbox{mod }\phi(N))$. -A person who wants to encrypt with your public key simply forms an integer (the plaintext) $M$ such that +A person who wants to encrypt with your public key simply forms an integer (the plaintext) $M$ such that $1 < M < N-2$ and computes the ciphertext $C = M^e\mbox{ }(\mbox{mod }N)$. Since finding the inverse exponent $d$ given only $N$ and $e$ appears to be intractable only the owner of the private key can decrypt the ciphertext and compute -$C^d \equiv \left (M^e \right)^d \equiv M^1 \equiv M\mbox{ }(\mbox{mod }N)$. Similarly the owner of the private key -can sign a message by \textit{decrypting} it. Others can verify it by \textit{encrypting} it. +$C^d \equiv \left (M^e \right)^d \equiv M^1 \equiv M\mbox{ }(\mbox{mod }N)$. Similarly the owner of the private key +can sign a message by \textit{decrypting} it. Others can verify it by \textit{encrypting} it. -Currently RSA is a difficult system to cryptanalyze provided that both primes are large and not close to each other. +Currently RSA is a difficult system to cryptanalyze provided that both primes are large and not close to each other. Ideally $e$ should be larger than $100$ to prevent direct analysis. For example, if $e$ is three and you do not pad -the plaintext to be encrypted than it is possible that $M^3 < N$ in which case finding the cube-root would be trivial. -The most often suggested value for $e$ is $65537$ since it is large enough to make such attacks impossible and also well +the plaintext to be encrypted than it is possible that $M^3 < N$ in which case finding the cube-root would be trivial. +The most often suggested value for $e$ is $65537$ since it is large enough to make such attacks impossible and also well designed for fast exponentiation (requires 16 squarings and one multiplication). -It is important to pad the input to RSA since it has particular mathematical structure. For instance +It is important to pad the input to RSA since it has particular mathematical structure. For instance $M_1^dM_2^d = (M_1M_2)^d$ which can be used to forge a signature. Suppose $M_3 = M_1M_2$ is a message you want to have a forged signature for. Simply get the signatures for $M_1$ and $M_2$ on their own and multiply the result -together. Similar tricks can be used to deduce plaintexts from ciphertexts. It is important not only to sign -the hash of documents only but also to pad the inputs with data to remove such structure. +together. Similar tricks can be used to deduce plaintexts from ciphertexts. It is important not only to sign +the hash of documents only but also to pad the inputs with data to remove such structure. \subsection{RSA Key Generation} For RSA routines a single \textit{rsa\_key} structure is used. To make a new RSA key call: \index{rsa\_make\_key()} \begin{verbatim} -int rsa_make_key(prng_state *prng, - int wprng, - int size, - long e, +int rsa_make_key(prng_state *prng, + int wprng, + int size, + long e, rsa_key *key); \end{verbatim} Where \textit{wprng} is the index into the PRNG descriptor array. The \textit{size} parameter is the size in bytes of the RSA modulus desired. -The \textit{e} parameter is the encryption exponent desired, typical values are 3, 17, 257 and 65537. Stick with 65537 since it is big enough to prevent -trivial math attacks, and not super slow. The \textit{key} parameter is where the constructed key is placed. All keys must be at +The \textit{e} parameter is the encryption exponent desired, typical values are 3, 17, 257 and 65537. Stick with 65537 since it is big enough to prevent +trivial math attacks, and not super slow. The \textit{key} parameter is where the constructed key is placed. All keys must be at least 128 bytes, and no more than 512 bytes in size (\textit{that is from 1024 to 4096 bits}). \index{rsa\_free()} -Note: the \textit{rsa\_make\_key()} function allocates memory at run--time when you make the key. Make sure to call -\textit{rsa\_free()} (see below) when you are finished with the key. If \textit{rsa\_make\_key()} fails it will automatically +Note: the \textit{rsa\_make\_key()} function allocates memory at run--time when you make the key. Make sure to call +\textit{rsa\_free()} (see below) when you are finished with the key. If \textit{rsa\_make\_key()} fails it will automatically free the memory allocated. \index{PK\_PRIVATE} \index{PK\_PUBLIC} -There are two types of RSA keys. The types are {\bf PK\_PRIVATE} and {\bf PK\_PUBLIC}. The first type is a private -RSA key which includes the CRT parameters\footnote{As of v0.99 the PK\_PRIVATE\_OPTIMIZED type has been deprecated, and has been replaced by the -PK\_PRIVATE type.} in the form of a RSAPrivateKey (PKCS \#1 compliant). The second type, is a public RSA key which only includes the modulus and public exponent. +There are two types of RSA keys. The types are {\bf PK\_PRIVATE} and {\bf PK\_PUBLIC}. The first type is a private +RSA key which includes the CRT parameters\footnote{As of v0.99 the PK\_PRIVATE\_OPTIMIZED type has been deprecated, and has been replaced by the +PK\_PRIVATE type.} in the form of a RSAPrivateKey (PKCS \#1 compliant). The second type, is a public RSA key which only includes the modulus and public exponent. It takes the form of a RSAPublicKey (PKCS \#1 compliant). \subsection{RSA Exponentiation} To do raw work with the RSA function, that is without padding, use the following function: \index{rsa\_exptmod()} \begin{verbatim} -int rsa_exptmod(const unsigned char *in, +int rsa_exptmod(const unsigned char *in, unsigned long inlen, - unsigned char *out, - unsigned long *outlen, - int which, + unsigned char *out, + unsigned long *outlen, + int which, rsa_key *key); \end{verbatim} This will load the bignum from \textit{in} as a big endian integer in the format PKCS \#1 specifies, raises it to either \textit{e} or \textit{d} and stores the result -in \textit{out} and the size of the result in \textit{outlen}. \textit{which} is set to {\bf PK\_PUBLIC} to use \textit{e} +in \textit{out} and the size of the result in \textit{outlen}. \textit{which} is set to {\bf PK\_PUBLIC} to use \textit{e} (i.e. for encryption/verifying) and set to {\bf PK\_PRIVATE} to use \textit{d} as the exponent (i.e. for decrypting/signing). Note: the output of this function is zero--padded as per PKCS \#1 specification. This allows this routine to work with PKCS \#1 padding functions properly. @@ -3384,15 +3384,15 @@ To facilitate encrypting short keys the following functions have been provided. \index{rsa\_encrypt\_key()} \begin{verbatim} int rsa_encrypt_key( - const unsigned char *in, + const unsigned char *in, unsigned long inlen, - unsigned char *out, + unsigned char *out, unsigned long *outlen, - const unsigned char *lparam, + const unsigned char *lparam, unsigned long lparamlen, - prng_state *prng, - int prng_idx, - int hash_idx, + prng_state *prng, + int prng_idx, + int hash_idx, rsa_key *key); \end{verbatim} This function will OAEP pad \textit{in} of length \textit{inlen} bytes, RSA encrypt it, and store the ciphertext @@ -3406,16 +3406,16 @@ encryption function: \index{rsa\_encrypt\_key\_ex()} \begin{verbatim} int rsa_encrypt_key_ex( - const unsigned char *in, + const unsigned char *in, unsigned long inlen, - unsigned char *out, + unsigned char *out, unsigned long *outlen, - const unsigned char *lparam, + const unsigned char *lparam, unsigned long lparamlen, - prng_state *prng, - int prng_idx, - int hash_idx, - int padding, + prng_state *prng, + int prng_idx, + int hash_idx, + int padding, rsa_key *key); \end{verbatim} @@ -3429,13 +3429,13 @@ When performing v1.5 encryption, the hash and lparam parameters are totally igno \index{rsa\_decrypt\_key()} \begin{verbatim} int rsa_decrypt_key( - const unsigned char *in, + const unsigned char *in, unsigned long inlen, - unsigned char *out, - unsigned long *outlen, - const unsigned char *lparam, + unsigned char *out, + unsigned long *outlen, + const unsigned char *lparam, unsigned long lparamlen, - int hash_idx, + int hash_idx, int *stat, rsa_key *key); \end{verbatim} @@ -3452,19 +3452,19 @@ decryption function: \index{rsa\_decrypt\_key\_ex()} \begin{verbatim} int rsa_decrypt_key_ex( - const unsigned char *in, + const unsigned char *in, unsigned long inlen, - unsigned char *out, + unsigned char *out, unsigned long *outlen, - const unsigned char *lparam, + const unsigned char *lparam, unsigned long lparamlen, - int hash_idx, + int hash_idx, int padding, int *stat, rsa_key *key); \end{verbatim} -Similar to the extended encryption, the new parameter \textit{padding} indicates which version of the PKCS \#1 standard to use. +Similar to the extended encryption, the new parameter \textit{padding} indicates which version of the PKCS \#1 standard to use. It must be set to \textbf{LTC\_PKCS\_1\_V1\_5} to perform v1.5 decryption, or set to \textbf{LTC\_PKCS\_1\_OAEP} to perform v2.1 decryption. When performing v1.5 decryption, the hash and lparam parameters are totally ignored and can be set to \textbf{NULL} or zero (respectively). @@ -3476,24 +3476,24 @@ process the following functions have been provided. \index{rsa\_sign\_hash()} \begin{verbatim} -int rsa_sign_hash(const unsigned char *in, - unsigned long inlen, - unsigned char *out, - unsigned long *outlen, - prng_state *prng, +int rsa_sign_hash(const unsigned char *in, + unsigned long inlen, + unsigned char *out, + unsigned long *outlen, + prng_state *prng, int prng_idx, - int hash_idx, + int hash_idx, unsigned long saltlen, rsa_key *key); \end{verbatim} -This will PSS encode the message digest pointed to by \textit{in} of length \textit{inlen} octets. Next, the PSS encoded hash will be RSA -\textit{signed} and the output stored in the buffer pointed to by \textit{out} of length \textit{outlen} octets. +This will PSS encode the message digest pointed to by \textit{in} of length \textit{inlen} octets. Next, the PSS encoded hash will be RSA +\textit{signed} and the output stored in the buffer pointed to by \textit{out} of length \textit{outlen} octets. The \textit{hash\_idx} parameter indicates which hash will be used to create the PSS encoding. It should be the same as the hash used to hash the message being signed. The \textit{saltlen} parameter indicates the length of the desired salt, and should typically be small. A good default value is between 8 and 16 octets. Strictly, it must be small than $modulus\_len - hLen - 2$ where \textit{modulus\_len} is the size of -the RSA modulus (in octets), and \textit{hLen} is the length of the message digest produced by the chosen hash. +the RSA modulus (in octets), and \textit{hLen} is the length of the message digest produced by the chosen hash. \subsection{Extended Signatures} @@ -3502,21 +3502,21 @@ As of v1.15, the library supports both v1.5 and v2.1 signatures. The extended s \index{rsa\_sign\_hash\_ex()} \begin{verbatim} int rsa_sign_hash_ex( - const unsigned char *in, + const unsigned char *in, unsigned long inlen, - unsigned char *out, + unsigned char *out, unsigned long *outlen, int padding, - prng_state *prng, + prng_state *prng, int prng_idx, - int hash_idx, + int hash_idx, unsigned long saltlen, rsa_key *key); \end{verbatim} -This will PKCS encode the message digest pointed to by \textit{in} of length \textit{inlen} octets. Next, the PKCS encoded hash will be RSA +This will PKCS encode the message digest pointed to by \textit{in} of length \textit{inlen} octets. Next, the PKCS encoded hash will be RSA \textit{signed} and the output stored in the buffer pointed to by \textit{out} of length \textit{outlen} octets. The \textit{padding} parameter -must be set to \textbf{LTC\_PKCS\_1\_V1\_5} to produce a v1.5 signature, otherwise, it must be set to \textbf{LTC\_PKCS\_1\_PSS} to produce a +must be set to \textbf{LTC\_PKCS\_1\_V1\_5} to produce a v1.5 signature, otherwise, it must be set to \textbf{LTC\_PKCS\_1\_PSS} to produce a v2.1 signature. When performing a v1.5 signature the \textit{prng}, \textit{prng\_idx}, and \textit{hash\_idx} parameters are not checked and can be left to any @@ -3525,11 +3525,11 @@ values such as $\lbrace$\textbf{NULL}, 0, 0$\rbrace$. \mysection{RSA Signature Verification} \index{rsa\_verify\_hash()} \begin{verbatim} -int rsa_verify_hash(const unsigned char *sig, +int rsa_verify_hash(const unsigned char *sig, unsigned long siglen, - const unsigned char *msghash, + const unsigned char *msghash, unsigned long msghashlen, - int hash_idx, + int hash_idx, unsigned long saltlen, int *stat, rsa_key *key); @@ -3538,7 +3538,7 @@ int rsa_verify_hash(const unsigned char *sig, This will RSA \textit{verify} the signature pointed to by \textit{sig} of length \textit{siglen} octets. Next, the RSA decoded data is PSS decoded and the extracted hash is compared against the message digest pointed to by \textit{msghash} of length \textit{msghashlen} octets. -If the RSA decoded data is not a valid PSS message, or if the PSS decoded hash does not match the \textit{msghash} +If the RSA decoded data is not a valid PSS message, or if the PSS decoded hash does not match the \textit{msghash} value, \textit{res} is set to $0$. Otherwise, if the function succeeds, and signature is valid \textit{res} is set to $1$. \subsection{Extended Verification} @@ -3548,24 +3548,24 @@ As of v1.15, the library supports both v1.5 and v2.1 signature verification. Th \index{rsa\_verify\_hash\_ex()} \begin{verbatim} int rsa_verify_hash_ex( - const unsigned char *sig, + const unsigned char *sig, unsigned long siglen, - const unsigned char *hash, + const unsigned char *hash, unsigned long hashlen, int padding, - int hash_idx, + int hash_idx, unsigned long saltlen, - int *stat, + int *stat, rsa_key *key); \end{verbatim} This will RSA \textit{verify} the signature pointed to by \textit{sig} of length \textit{siglen} octets. Next, the RSA decoded data is PKCS decoded and the extracted hash is compared against the message digest pointed to by \textit{msghash} of length \textit{msghashlen} octets. -If the RSA decoded data is not a valid PSS message, or if the PKCS decoded hash does not match the \textit{msghash} +If the RSA decoded data is not a valid PSS message, or if the PKCS decoded hash does not match the \textit{msghash} value, \textit{res} is set to $0$. Otherwise, if the function succeeds, and signature is valid \textit{res} is set to $1$. -The \textit{padding} parameter must be set to \textbf{LTC\_PKCS\_1\_V1\_5} to perform a v1.5 verification. Otherwise, it must be set to +The \textit{padding} parameter must be set to \textbf{LTC\_PKCS\_1\_V1\_5} to perform a v1.5 verification. Otherwise, it must be set to \textbf{LTC\_PKCS\_1\_PSS} to perform a v2.1 verification. When performing a v1.5 verification the \textit{hash\_idx} parameter is ignored. \mysection{RSA Encryption Example} @@ -3633,7 +3633,7 @@ int main(void) 7, /* lparam is 7 bytes long */ hash_idx, /* hash idx */ &res, /* validity of data */ - &key) /* our RSA key */ + &key) /* our RSA key */ ) != CRYPT_OK) { printf("rsa_decrypt_key %s", error_to_string(err)); return EXIT_FAILURE; @@ -3645,7 +3645,7 @@ int main(void) \mysection{RSA Key Format} -The RSA key format adopted for exporting and importing keys is the PKCS \#1 format defined by the ASN.1 constructs known as +The RSA key format adopted for exporting and importing keys is the PKCS \#1 format defined by the ASN.1 constructs known as RSAPublicKey and RSAPrivateKey. Additionally, the OpenSSL key format is supported by the import function only. \subsection{RSA Key Export} @@ -3653,12 +3653,12 @@ To export a RSA key use the following function. \index{rsa\_export()} \begin{verbatim} -int rsa_export(unsigned char *out, - unsigned long *outlen, - int type, +int rsa_export(unsigned char *out, + unsigned long *outlen, + int type, rsa_key *key); \end{verbatim} -This will export the RSA key in either a RSAPublicKey or RSAPrivateKey (PKCS \#1 types) depending on the value of \textit{type}. When it is +This will export the RSA key in either a RSAPublicKey or RSAPrivateKey (PKCS \#1 types) depending on the value of \textit{type}. When it is set to \textbf{PK\_PRIVATE} the export format will be RSAPrivateKey and otherwise it will be RSAPublicKey. \subsection{RSA Key Import} @@ -3666,8 +3666,8 @@ To import a RSA key use the following function. \index{rsa\_import()} \begin{verbatim} -int rsa_import(const unsigned char *in, - unsigned long inlen, +int rsa_import(const unsigned char *in, + unsigned long inlen, rsa_key *key); \end{verbatim} @@ -3676,7 +3676,7 @@ function can import both RSAPublicKey and RSAPrivateKey formats. As of v1.06 this function can also import OpenSSL DER formatted public RSA keys. They are essentially encapsulated RSAPublicKeys. LibTomCrypt will import the key, strip off the additional data (it's the preferred hash) and fill in the rsa\_key structure as if it were a native RSAPublicKey. Note that -there is no function provided to export in this format. +there is no function provided to export in this format. \chapter{Diffie-Hellman Key Exchange} @@ -3684,73 +3684,73 @@ there is no function provided to export in this format. \section{Background} Diffie-Hellman was the original public key system proposed. The system is based upon the group structure -of finite fields. For Diffie-Hellman a prime $p$ is chosen and a ``base'' $b$ such that $b^x\mbox{ }(\mbox{mod }p)$ +of finite fields. For Diffie-Hellman a prime $p$ is chosen and a ``base'' $b$ such that $b^x\mbox{ }(\mbox{mod }p)$ generates a large sub-group of prime order (for unique values of $x$). A secret key is an exponent $x$ and a public key is the value of $y \equiv g^x\mbox{ }(\mbox{mod }p)$. The term ``discrete logarithm'' denotes the action of finding $x$ given only $y$, $g$ and $p$. The key exchange part of -Diffie-Hellman arises from the fact that two users A and B with keys $(A_x, A_y)$ and $(B_x, B_y)$ can exchange +Diffie-Hellman arises from the fact that two users A and B with keys $(A_x, A_y)$ and $(B_x, B_y)$ can exchange a shared key $K \equiv B_y^{A_x} \equiv A_y^{B_x} \equiv g^{A_xB_x}\mbox{ }(\mbox{mod }p)$. -From this public encryption and signatures can be developed. The trivial way to encrypt (for example) using a public key -$y$ is to perform the key exchange offline. The sender invents a key $k$ and its public copy +From this public encryption and signatures can be developed. The trivial way to encrypt (for example) using a public key +$y$ is to perform the key exchange offline. The sender invents a key $k$ and its public copy $k' \equiv g^k\mbox{ }(\mbox{mod }p)$ and uses $K \equiv k'^{A_x}\mbox{ }(\mbox{mod }p)$ as a key to encrypt -the message with. Typically $K$ would be sent to a one-way hash and the message digested used as a key in a +the message with. Typically $K$ would be sent to a one-way hash and the message digested used as a key in a symmetric cipher. It is important that the order of the sub-group that $g$ generates not only be large but also prime. There are discrete logarithm algorithms that take $\sqrt r$ time given the order $r$. The discrete logarithm can be computed -modulo each prime factor of $r$ and the results combined using the Chinese Remainder Theorem. In the cases where +modulo each prime factor of $r$ and the results combined using the Chinese Remainder Theorem. In the cases where $r$ is ``B-Smooth'' (e.g. all small factors or powers of small prime factors) the solution is trivial to find. To thwart such attacks the primes and bases in the library have been designed and fixed. Given a prime $p$ the order of - the sub-group generated is a large prime namely ${p - 1} \over 2$. Such primes are known as ``strong primes'' and the + the sub-group generated is a large prime namely ${p - 1} \over 2$. Such primes are known as ``strong primes'' and the smaller prime (e.g. the order of the base) are known as Sophie-Germaine primes. \section{Core Functions} -This library also provides core Diffie-Hellman functions so you can negotiate keys over insecure mediums. The routines +This library also provides core Diffie-Hellman functions so you can negotiate keys over insecure mediums. The routines provided are relatively easy to use and only take two function calls to negotiate a shared key. There is a structure called ``dh\_key'' which stores the Diffie-Hellman key in a format these routines can use. The first routine is to make a Diffie-Hellman private key pair: \index{dh\_make\_key()} \begin{verbatim} -int dh_make_key(prng_state *prng, int wprng, +int dh_make_key(prng_state *prng, int wprng, int keysize, dh_key *key); \end{verbatim} -The ``keysize'' is the size of the modulus you want in bytes. Currently support sizes are 96 to 512 bytes which correspond -to key sizes of 768 to 4096 bits. The smaller the key the faster it is to use however it will be less secure. When -specifying a size not explicitly supported by the library it will round {\em up} to the next key size. If the size is -above 512 it will return an error. So if you pass ``keysize == 32'' it will use a 768 bit key but if you pass -``keysize == 20000'' it will return an error. The primes and generators used are built-into the library and were designed +The ``keysize'' is the size of the modulus you want in bytes. Currently support sizes are 96 to 512 bytes which correspond +to key sizes of 768 to 4096 bits. The smaller the key the faster it is to use however it will be less secure. When +specifying a size not explicitly supported by the library it will round {\em up} to the next key size. If the size is +above 512 it will return an error. So if you pass ``keysize == 32'' it will use a 768 bit key but if you pass +``keysize == 20000'' it will return an error. The primes and generators used are built-into the library and were designed to meet very specific goals. The primes are strong primes which means that if $p$ is the prime then $p-1$ is equal to $2r$ where $r$ is a large prime. The bases are chosen to generate a group of order $r$ to prevent leaking a bit of the key. This means the bases generate a very large prime order group which is good to make cryptanalysis hard. The next two routines are for exporting/importing Diffie-Hellman keys in a binary format. This is useful for transport -over communication mediums. +over communication mediums. \index{dh\_export()} \index{dh\_import()} \begin{verbatim} -int dh_export(unsigned char *out, unsigned long *outlen, +int dh_export(unsigned char *out, unsigned long *outlen, int type, dh_key *key); int dh_import(const unsigned char *in, unsigned long inlen, dh_key *key); \end{verbatim} -These two functions work just like the ``rsa\_export()'' and ``rsa\_import()'' functions except these work with -Diffie-Hellman keys. Its important to note you do not have to free the ram for a ``dh\_key'' if an import fails. You can free a +These two functions work just like the ``rsa\_export()'' and ``rsa\_import()'' functions except these work with +Diffie-Hellman keys. Its important to note you do not have to free the ram for a ``dh\_key'' if an import fails. You can free a ``dh\_key'' using: \begin{verbatim} void dh_free(dh_key *key); \end{verbatim} -After you have exported a copy of your public key (using {\bf PK\_PUBLIC} as ``type'') you can now create a shared secret +After you have exported a copy of your public key (using {\bf PK\_PUBLIC} as ``type'') you can now create a shared secret with the other user using: \index{dh\_shared\_secret()} \begin{verbatim} -int dh_shared_secret(dh_key *private_key, - dh_key *public_key, +int dh_shared_secret(dh_key *private_key, + dh_key *public_key, unsigned char *out, unsigned long *outlen); \end{verbatim} @@ -3765,12 +3765,12 @@ int dh_get_size(dh_key *key); This returns the size in bytes of the modulus chosen for that key. \subsection{Remarks on Usage} -Its important that you hash the shared key before trying to use it as a key for a symmetric cipher or something. An +Its important that you hash the shared key before trying to use it as a key for a symmetric cipher or something. An example program that communicates over sockets, using MD5 and 1024-bit DH keys is\footnote{This function is a small example. It is suggested that proper packaging be used. For example, if the public key sent is truncated these routines will not detect that.}: \newpage \begin{small} \begin{verbatim} -int establish_secure_socket(int sock, int mode, unsigned char *key, +int establish_secure_socket(int sock, int mode, unsigned char *key, prng_state *prng, int wprng) { unsigned char buf[4096], buf2[4096]; @@ -3783,7 +3783,7 @@ int establish_secure_socket(int sock, int mode, unsigned char *key, return err; } - /* export our key as public */ + /* export our key as public */ x = sizeof(buf); if ((err = dh_export(buf, &x, PK_PUBLIC, &mykey)) != CRYPT_OK) { res = err; @@ -3795,7 +3795,7 @@ int establish_secure_socket(int sock, int mode, unsigned char *key, if (send(sock, buf, x, 0) != x) { res = CRYPT_ERROR; goto done2; - } + } /* get their key */ if ((inlen = recv(sock, buf2, sizeof(buf2), 0)) <= 0) { @@ -3815,7 +3815,7 @@ int establish_secure_socket(int sock, int mode, unsigned char *key, } } - if ((err = dh_import(buf2, inlen, &theirkey)) != CRYPT_OK) { + if ((err = dh_import(buf2, inlen, &theirkey)) != CRYPT_OK) { res = err; goto done2; } @@ -3826,7 +3826,7 @@ int establish_secure_socket(int sock, int mode, unsigned char *key, res = err; goto done; } - + /* hash it */ len = 16; /* default is MD5 so "key" must be at least 16 bytes long */ if ((err = hash_memory(find_hash("md5"), buf, x, key, &len)) != CRYPT_OK) { @@ -3859,7 +3859,7 @@ available: int dh_test(void); \end{verbatim} -This function returns {\bf CRYPT\_OK} if the bases and primes in the library are correct. There is one last helper +This function returns {\bf CRYPT\_OK} if the bases and primes in the library are correct. There is one last helper function: \index{dh\_sizes()} \begin{verbatim} @@ -3869,20 +3869,20 @@ Which stores the smallest and largest key sizes support into the two variables. \section{DH Packet} Similar to the RSA related functions there are functions to encrypt or decrypt symmetric keys using the DH public key -algorithms. +algorithms. \index{dh\_encrypt\_key()} \index{dh\_decrypt\_key()} \begin{verbatim} int dh_encrypt_key(const unsigned char *in, unsigned long inlen, - unsigned char *out, unsigned long *len, - prng_state *prng, int wprng, int hash, + unsigned char *out, unsigned long *len, + prng_state *prng, int wprng, int hash, dh_key *key); int dh_decrypt_key(const unsigned char *in, unsigned long inlen, - unsigned char *out, unsigned long *outlen, + unsigned char *out, unsigned long *outlen, dh_key *key); \end{verbatim} Where ``in'' is an input symmetric key of no more than 32 bytes. Essentially these routines created a random public key -and find the hash of the shared secret. The message digest is than XOR'ed against the symmetric key. All of the +and find the hash of the shared secret. The message digest is than XOR'ed against the symmetric key. All of the required data is placed in ``out'' by ``dh\_encrypt\_key()''. The hash must produce a message digest at least as large as the symmetric key you are trying to share. @@ -3894,18 +3894,18 @@ int dh_sign_hash(const unsigned char *in, unsigned long inlen, prng_state *prng, int wprng, dh_key *key); int dh_verify_hash(const unsigned char *sig, unsigned long siglen, - const unsigned char *hash, unsigned long hashlen, + const unsigned char *hash, unsigned long hashlen, int *stat, dh_key *key); \end{verbatim} -The ``dh\_sign\_hash'' function signs the message hash in ``in'' of length ``inlen'' and forms a DH packet in ``out''. +The ``dh\_sign\_hash'' function signs the message hash in ``in'' of length ``inlen'' and forms a DH packet in ``out''. The ``dh\_verify\_hash'' function verifies the DH signature in ``sig'' against the hash in ``hash''. It sets ``stat'' to non-zero if the signature passes or zero if it fails. \chapter{Elliptic Curve Cryptography} \mysection{Background} -The library provides a set of core ECC functions as well that are designed to be the Elliptic Curve analogy of all of the +The library provides a set of core ECC functions as well that are designed to be the Elliptic Curve analogy of all of the Diffie-Hellman routines in the previous chapter. Elliptic curves (of certain forms) have the benefit that they are harder to attack (no sub-exponential attacks exist unlike normal DH crypto) in fact the fastest attack requires the square root of the order of the base point in time. That means if you use a base point of order $2^{192}$ (which would represent a @@ -3916,7 +3916,7 @@ The curves in this library are taken from the following website: http://csrc.nist.gov/cryptval/dss.htm \end{verbatim} -As of v1.15 three new curves from the SECG standards are also included they are the secp112r1, secp128r1, and secp160r1 curves. These curves were added to +As of v1.15 three new curves from the SECG standards are also included they are the secp112r1, secp128r1, and secp160r1 curves. These curves were added to support smaller devices which do not need as large keys for security. They are all curves over the integers modulo a prime. The curves have the basic equation that is: @@ -3924,19 +3924,19 @@ They are all curves over the integers modulo a prime. The curves have the basic y^2 = x^3 - 3x + b\mbox{ }(\mbox{mod }p) \end{equation} -The variable $b$ is chosen such that the number of points is nearly maximal. In fact the order of the base points $\beta$ +The variable $b$ is chosen such that the number of points is nearly maximal. In fact the order of the base points $\beta$ provided are very close to $p$ that is $\vert \vert \phi(\beta) \vert \vert \approx \vert \vert p \vert \vert$. The curves range in order from $\approx 2^{112}$ points to $\approx 2^{521}$. According to the source document any key size greater -than or equal to 256-bits is sufficient for long term security. +than or equal to 256-bits is sufficient for long term security. \mysection{Fixed Point Optimizations} \index{Fixed Point ECC} \index{MECC\_FP} As of v1.12 of LibTomCrypt, support for Fixed Point ECC point multiplication has been added. It is a generic optimization that is -supported by any conforming math plugin. It is enabled by defining \textbf{MECC\_FP} during the build, such as +supported by any conforming math plugin. It is enabled by defining \textbf{MECC\_FP} during the build, such as \begin{verbatim} -CFLAGS="-DTFM_DESC -DMECC_FP" make +CFLAGS="-DTFM_DESC -DMECC_FP" make \end{verbatim} which will build LTC using the TFM math library and enabling this new feature. The feature is not enabled by default as it is \textbf{NOT} thread @@ -3945,11 +3945,11 @@ safe (by default). It supports the LTC locking macros (such as by enabling LTC\ \index{FP\_ENTRIES} The optimization works by using a Fixed Point multiplier on any base point you use twice or more in a short period of time. It has a limited size cache (of FP\_ENTRIES entries) which it uses to hold recent bases passed to ltc\_ecc\_mulmod(). Any base detected to be used twice is sent through the -pre--computation phase, and then the fixed point algorithm can be used. For example, if you use a NIST base point twice in a row, the 2$^{nd}$ and +pre--computation phase, and then the fixed point algorithm can be used. For example, if you use a NIST base point twice in a row, the 2$^{nd}$ and all subsequent point multiplications with that point will use the faster algorithm. \index{FP\_LUT} -The optimization uses a window on the multiplicand of FP\_LUT bits (default: 8, min: 2, max: 12), and this controls the memory/time trade-off. The larger the +The optimization uses a window on the multiplicand of FP\_LUT bits (default: 8, min: 2, max: 12), and this controls the memory/time trade-off. The larger the value the faster the algorithm will be but the more memory it will take. The memory usage is $3 \cdot 2^{FP\_LUT}$ integers which by default with TFM amounts to about 400kB of memory. Tuning TFM (by changing FP\_SIZE) can decrease the usage by a fair amount. Memory is only used by a cache entry if it is active. Both FP\_ENTRIES and FP\_LUT are definable on the command line if you wish to override them. For instance, @@ -3958,7 +3958,7 @@ if it is active. Both FP\_ENTRIES and FP\_LUT are definable on the command line CFLAGS="-DTFM_DESC -DMECC_FP -DFP_ENTRIES=8 -DFP_LUT=6" make \end{verbatim} -\begin{flushleft} +\begin{flushleft} \index{FP\_SIZE} \index{TFM} \index{tfm.h} would define a window of 6 bits and limit the cache to 8 entries. Generally, it is better to first tune TFM by adjusting FP\_SIZE (from tfm.h). It defaults to 4096 bits (512 bytes) which is way more than what is required by ECC. At most, you need 1152 bits to accommodate ECC--521. If you're only using (say) @@ -3973,16 +3973,16 @@ In the case of LibTomCrypt, it is meant \textbf{solely} for NIST and SECG $GF(p) \begin{small} \begin{verbatim} ECCPublicKey ::= SEQUENCE { - flags BIT STRING(0), -- public/private flag (always zero), - keySize INTEGER, -- Curve size (in bits) divided by eight + flags BIT STRING(0), -- public/private flag (always zero), + keySize INTEGER, -- Curve size (in bits) divided by eight -- and rounded down, e.g. 521 => 65 pubkey.x INTEGER, -- The X co-ordinate of the public key point pubkey.y INTEGER, -- The Y co-ordinate of the public key point } ECCPrivateKey ::= SEQUENCE { - flags BIT STRING(1), -- public/private flag (always one), - keySize INTEGER, -- Curve size (in bits) divided by eight + flags BIT STRING(1), -- public/private flag (always one), + keySize INTEGER, -- Curve size (in bits) divided by eight -- and rounded down, e.g. 521 => 65 pubkey.x INTEGER, -- The X co-ordinate of the public key point pubkey.y INTEGER, -- The Y co-ordinate of the public key point @@ -3991,13 +3991,13 @@ ECCPrivateKey ::= SEQUENCE { \end{verbatim} \end{small} -The first flags bit denotes whether the key is public (zero) or private (one). +The first flags bit denotes whether the key is public (zero) or private (one). \vfil \mysection{ECC Curve Parameters} The library uses the following structure to describe an elliptic curve. This is used internally, as well as by the new -extended ECC functions which allow the user to specify their own curves. +extended ECC functions which allow the user to specify their own curves. \index{ltc\_ecc\_set\_type} \begin{verbatim} @@ -4007,7 +4007,7 @@ typedef struct { int size; /** name of curve */ - char *name; + char *name; /** The prime that defines the field (encoded in hex) */ char *prime; @@ -4017,10 +4017,10 @@ typedef struct { /** The order of the curve (hex) */ char *order; - + /** The x co-ordinate of the base point on the curve (hex) */ char *Gx; - + /** The y co-ordinate of the base point on the curve (hex) */ char *Gy; } ltc_ecc_set_type; @@ -4033,14 +4033,14 @@ The curve must be of the form $y^2 = x^3 - 3x + b$, and all of the integer param There is a key structure called \textit{ecc\_key} used by the ECC functions. There is a function to make a key: \index{ecc\_make\_key()} \begin{verbatim} -int ecc_make_key(prng_state *prng, - int wprng, - int keysize, +int ecc_make_key(prng_state *prng, + int wprng, + int keysize, ecc_key *key); \end{verbatim} The \textit{keysize} is the size of the modulus in bytes desired. Currently directly supported values are 12, 16, 20, 24, 28, 32, 48, and 65 bytes which -correspond to key sizes of 112, 128, 160, 192, 224, 256, 384, and 521 bits respectively. If you pass a key size that is between any key size it will round +correspond to key sizes of 112, 128, 160, 192, 224, 256, 384, and 521 bits respectively. If you pass a key size that is between any key size it will round the keysize up to the next available one. The function will free any internally allocated resources if there is an error. @@ -4051,9 +4051,9 @@ As of v1.16, the library supports an extended key generation routine which allow \index{ecc\_make\_key\_ex()} \begin{verbatim} int ecc_make_key_ex( - prng_state *prng, - int wprng, - ecc_key *key, + prng_state *prng, + int wprng, + ecc_key *key, const ltc_ecc_set_type *dp); \end{verbatim} @@ -4071,19 +4071,19 @@ void ecc_free(ecc_key *key); To export an ECC key using the LibTomCrypt format call the following function: \index{ecc\_export()} \begin{verbatim} -int ecc_export(unsigned char *out, - unsigned long *outlen, - int type, +int ecc_export(unsigned char *out, + unsigned long *outlen, + int type, ecc_key *key); \end{verbatim} -This will export the key with the given \textit{type} (\textbf{PK\_PUBLIC} or \textbf{PK\_PRIVATE}), and store it to \textit{out}. +This will export the key with the given \textit{type} (\textbf{PK\_PUBLIC} or \textbf{PK\_PRIVATE}), and store it to \textit{out}. \subsection{ECC Key Import} The following function imports a LibTomCrypt format ECC key: \index{ecc\_import()} \begin{verbatim} -int ecc_import(const unsigned char *in, - unsigned long inlen, +int ecc_import(const unsigned char *in, + unsigned long inlen, ecc_key *key); \end{verbatim} This will import the ECC key from \textit{in}, and store it in the ecc\_key structure pointed to by \textit{key}. If the operation fails it will free @@ -4094,9 +4094,9 @@ any allocated memory automatically. The following function imports a LibTomCrypt format ECC key using a specified set of curve parameters: \index{ecc\_import\_ex()} \begin{verbatim} -int ecc_import_ex(const unsigned char *in, - unsigned long inlen, - ecc_key *key, +int ecc_import_ex(const unsigned char *in, + unsigned long inlen, + ecc_key *key, const ltc_ecc_set_type *dp); \end{verbatim} This will import the key from the array pointed to by \textit{in} of length \textit{inlen} octets. The key is stored in @@ -4108,8 +4108,8 @@ The following function exports an ECC public key in the ANSI X9.63 format: \index{ecc\_ansi\_x963\_export()} \begin{verbatim} -int ecc_ansi_x963_export( ecc_key *key, - unsigned char *out, +int ecc_ansi_x963_export( ecc_key *key, + unsigned char *out, unsigned long *outlen); \end{verbatim} The ECC key pointed to by \textit{key} is exported in public fashion to the array pointed to by \textit{out}. The ANSI X9.63 format used is from @@ -4120,11 +4120,11 @@ The following function imports an ANSI X9.63 section 4.3.6 format public ECC key \index{ecc\_ansi\_x963\_import()} \begin{verbatim} -int ecc_ansi_x963_import(const unsigned char *in, - unsigned long inlen, +int ecc_ansi_x963_import(const unsigned char *in, + unsigned long inlen, ecc_key *key); \end{verbatim} -This will import the key stored in the array pointed to by \textit{in} of length \textit{inlen} octets. The imported key is stored in the ECC key pointed to by +This will import the key stored in the array pointed to by \textit{in} of length \textit{inlen} octets. The imported key is stored in the ECC key pointed to by \textit{key}. The function will free any allocated memory upon error. \subsection{Extended ANSI X9.63 Import} @@ -4132,25 +4132,25 @@ The following function allows the importing of an ANSI x9.63 section 4.3.6 forma \index{ecc\_ansi\_x963\_import\_ex()} \begin{verbatim} -int ecc_ansi_x963_import_ex(const unsigned char *in, - unsigned long inlen, - ecc_key *key, +int ecc_ansi_x963_import_ex(const unsigned char *in, + unsigned long inlen, + ecc_key *key, ltc_ecc_set_type *dp); \end{verbatim} -This will import the key stored in the array pointed to by \textit{in} of length \textit{inlen} octets using the domain parameters pointed to by \textit{dp}. +This will import the key stored in the array pointed to by \textit{in} of length \textit{inlen} octets using the domain parameters pointed to by \textit{dp}. The imported key is stored in the ECC key pointed to by \textit{key}. The function will free any allocated memory upon error. \subsection{ECC Shared Secret} To construct a Diffie-Hellman shared secret with a private and public ECC key, use the following function: \index{ecc\_shared\_secret()} \begin{verbatim} -int ecc_shared_secret( ecc_key *private_key, - ecc_key *public_key, - unsigned char *out, +int ecc_shared_secret( ecc_key *private_key, + ecc_key *public_key, + unsigned char *out, unsigned long *outlen); \end{verbatim} -The \textit{private\_key} is typically the local private key, and \textit{public\_key} is the key the remote party has shared. -Note: this function stores only the $x$ co-ordinate of the shared elliptic point as described in ANSI X9.63 ECC--DH. +The \textit{private\_key} is typically the local private key, and \textit{public\_key} is the key the remote party has shared. +Note: this function stores only the $x$ co-ordinate of the shared elliptic point as described in ANSI X9.63 ECC--DH. \mysection{ECC Diffie-Hellman Encryption} ECC--DH Encryption is performed by producing a random key, hashing it, and XOR'ing the digest against the plaintext. It is not strictly ANSI X9.63 compliant @@ -4162,29 +4162,29 @@ encrypts a short string (no longer than the message digest) using this technique \begin{verbatim} int ecc_encrypt_key(const unsigned char *in, unsigned long inlen, - unsigned char *out, - unsigned long *outlen, - prng_state *prng, - int wprng, - int hash, + unsigned char *out, + unsigned long *outlen, + prng_state *prng, + int wprng, + int hash, ecc_key *key); \end{verbatim} -As the name implies this function encrypts a (symmetric) key, and is not intended for encrypting long messages directly. It will encrypt the +As the name implies this function encrypts a (symmetric) key, and is not intended for encrypting long messages directly. It will encrypt the plaintext in the array pointed to by \textit{in} of length \textit{inlen} octets. It uses the public ECC key pointed to by \textit{key}, and hash algorithm indexed by \textit{hash} to construct a shared secret which may be XOR'ed against the plaintext. The ciphertext is stored in the output buffer pointed to by \textit{out} of length \textit{outlen} octets. -The data is encrypted to the public ECC \textit{key} such that only the holder of the private key can decrypt the payload. To have multiple +The data is encrypted to the public ECC \textit{key} such that only the holder of the private key can decrypt the payload. To have multiple recipients multiple call to this function for each public ECC key is required. \subsection{ECC-DH Decryption} \index{ecc\_decrypt\_key()} \begin{verbatim} -int ecc_decrypt_key(const unsigned char *in, +int ecc_decrypt_key(const unsigned char *in, unsigned long inlen, - unsigned char *out, - unsigned long *outlen, + unsigned char *out, + unsigned long *outlen, ecc_key *key); \end{verbatim} @@ -4199,7 +4199,7 @@ The packet format for the encrypted keys is the following ASN.1 SEQUENCE: ECCEncrypt ::= SEQUENCE { hashID OBJECT IDENTIFIER, -- OID of hash used pubkey OCTET STRING , -- Encapsulated ECCPublicKey - skey OCTET STRING -- xor of plaintext and + skey OCTET STRING -- xor of plaintext and --"hash of shared secret" } \end{verbatim} @@ -4207,58 +4207,58 @@ ECCEncrypt ::= SEQUENCE { \mysection{EC DSA Signatures} There are also functions to sign and verify messages. They use the ANSI X9.62 EC-DSA algorithm to generate and verify signatures in the -ANSI X9.62 format. +ANSI X9.62 format. \subsection{EC-DSA Signature Generation} To sign a message digest (hash) use the following function: \index{ecc\_sign\_hash()} \begin{verbatim} -int ecc_sign_hash(const unsigned char *in, +int ecc_sign_hash(const unsigned char *in, unsigned long inlen, - unsigned char *out, + unsigned char *out, unsigned long *outlen, - prng_state *prng, - int wprng, + prng_state *prng, + int wprng, ecc_key *key); \end{verbatim} This function will EC--DSA sign the message digest stored in the array pointed to by \textit{in} of length \textit{inlen} octets. The signature -will be stored in the array pointed to by \textit{out} of length \textit{outlen} octets. The function requires a properly seeded PRNG, and +will be stored in the array pointed to by \textit{out} of length \textit{outlen} octets. The function requires a properly seeded PRNG, and the ECC \textit{key} provided must be a private key. \subsection{EC-DSA Signature Verification} \index{ecc\_verify\_hash()} \begin{verbatim} -int ecc_verify_hash(const unsigned char *sig, +int ecc_verify_hash(const unsigned char *sig, unsigned long siglen, - const unsigned char *hash, - unsigned long hashlen, - int *stat, + const unsigned char *hash, + unsigned long hashlen, + int *stat, ecc_key *key); \end{verbatim} -This function will verify the EC-DSA signature in the array pointed to by \textit{sig} of length \textit{siglen} octets, against the message digest -pointed to by the array \textit{hash} of length \textit{hashlen}. It will store a non--zero value in \textit{stat} if the signature is valid. Note: -the function will not return an error if the signature is invalid. It will return an error, if the actual signature payload is an invalid format. +This function will verify the EC-DSA signature in the array pointed to by \textit{sig} of length \textit{siglen} octets, against the message digest +pointed to by the array \textit{hash} of length \textit{hashlen}. It will store a non--zero value in \textit{stat} if the signature is valid. Note: +the function will not return an error if the signature is invalid. It will return an error, if the actual signature payload is an invalid format. The ECC \textit{key} must be the public (or private) ECC key corresponding to the key that performed the signature. \subsection{Signature Format} The signature code is an implementation of X9.62 EC--DSA, and the output is compliant for GF(p) curves. \mysection{ECC Keysizes} -With ECC if you try to sign a hash that is bigger than your ECC key you can run into problems. The math will still work, and in effect the signature will still -work. With ECC keys the strength of the signature is limited by the size of the hash, or the size of they key, whichever is smaller. For example, if you sign with -SHA256 and an ECC-192 key, you in effect have 96--bits of security. +With ECC if you try to sign a hash that is bigger than your ECC key you can run into problems. The math will still work, and in effect the signature will still +work. With ECC keys the strength of the signature is limited by the size of the hash, or the size of they key, whichever is smaller. For example, if you sign with +SHA256 and an ECC-192 key, you in effect have 96--bits of security. The library will not warn you if you make this mistake, so it is important to check yourself before using the signatures. \chapter{Digital Signature Algorithm} \mysection{Introduction} -The Digital Signature Algorithm (or DSA) is a variant of the ElGamal Signature scheme which has been modified to -reduce the bandwidth of the signatures. For example, to have \textit{80-bits of security} with ElGamal, you need a group with an order of at least 1024--bits. -With DSA, you need a group of order at least 160--bits. By comparison, the ElGamal signature would require at least 256 bytes of storage, whereas the DSA signature -would require only at least 40 bytes. +The Digital Signature Algorithm (or DSA) is a variant of the ElGamal Signature scheme which has been modified to +reduce the bandwidth of the signatures. For example, to have \textit{80-bits of security} with ElGamal, you need a group with an order of at least 1024--bits. +With DSA, you need a group of order at least 160--bits. By comparison, the ElGamal signature would require at least 256 bytes of storage, whereas the DSA signature +would require only at least 40 bytes. \mysection{Key Format} Since no useful public standard for DSA key storage was presented to me during the course of this development I made my own ASN.1 SEQUENCE which I document @@ -4270,11 +4270,11 @@ DSAPublicKey ::= SEQUENCE { g INTEGER , -- base generator -- check that g^q mod p == 1 -- and that 1 < g < p - 1 - p INTEGER , -- prime modulus - q INTEGER , -- order of sub-group + p INTEGER , -- prime modulus + q INTEGER , -- order of sub-group -- (must be prime) - y INTEGER , -- public key, specifically, - -- g^x mod p, + y INTEGER , -- public key, specifically, + -- g^x mod p, -- check that y^q mod p == 1 -- and that 1 < y < p - 1 } @@ -4284,32 +4284,32 @@ DSAPrivateKey ::= SEQUENCE { g INTEGER , -- base generator -- check that g^q mod p == 1 -- and that 1 < g < p - 1 - p INTEGER , -- prime modulus - q INTEGER , -- order of sub-group + p INTEGER , -- prime modulus + q INTEGER , -- order of sub-group -- (must be prime) - y INTEGER , -- public key, specifically, - -- g^x mod p, + y INTEGER , -- public key, specifically, + -- g^x mod p, -- check that y^q mod p == 1 -- and that 1 < y < p - 1 x INTEGER -- private key } \end{verbatim} -The leading BIT STRING has a single bit in it which is zero for public keys and one for private keys. This makes the structure uniquely decodable, +The leading BIT STRING has a single bit in it which is zero for public keys and one for private keys. This makes the structure uniquely decodable, and easy to work with. \mysection{Key Generation} To make a DSA key you must call the following function \begin{verbatim} -int dsa_make_key(prng_state *prng, - int wprng, - int group_size, - int modulus_size, +int dsa_make_key(prng_state *prng, + int wprng, + int group_size, + int modulus_size, dsa_key *key); \end{verbatim} -The variable \textit{prng} is an active PRNG state and \textit{wprng} the index to the descriptor. \textit{group\_size} and +The variable \textit{prng} is an active PRNG state and \textit{wprng} the index to the descriptor. \textit{group\_size} and \textit{modulus\_size} control the difficulty of forging a signature. Both parameters are in bytes. The larger the -\textit{group\_size} the more difficult a forgery becomes upto a limit. The value of $group\_size$ is limited by +\textit{group\_size} the more difficult a forgery becomes upto a limit. The value of $group\_size$ is limited by $15 < group\_size < 1024$ and $modulus\_size - group\_size < 512$. Suggested values for the pairs are as follows. \begin{figure}[here] @@ -4336,11 +4336,11 @@ void dsa_free(dsa_key *key); Each DSA key is composed of the following variables. \begin{enumerate} - \item $q$ a small prime of magnitude $256^{group\_size}$. + \item $q$ a small prime of magnitude $256^{group\_size}$. \item $p = qr + 1$ a large prime of magnitude $256^{modulus\_size}$ where $r$ is a random even integer. - \item $g = h^r \mbox{ (mod }p\mbox{)}$ a generator of order $q$ modulo $p$. $h$ can be any non-trivial random + \item $g = h^r \mbox{ (mod }p\mbox{)}$ a generator of order $q$ modulo $p$. $h$ can be any non-trivial random value. For this library they start at $h = 2$ and step until $g$ is not $1$. - \item $x$ a random secret (the secret key) in the range $1 < x < q$ + \item $x$ a random secret (the secret key) in the range $1 < x < q$ \item $y = g^x \mbox{ (mod }p\mbox{)}$ the public key. \end{enumerate} @@ -4357,12 +4357,12 @@ A DSA key is considered valid if it passes all of the following tests. \item $y^q \equiv 1 \mbox{ (mod }p\mbox{)}$. \end{enumerate} -Tests one and two ensure that the values will at least form a field which is required for the signatures to +Tests one and two ensure that the values will at least form a field which is required for the signatures to function. Tests three and four ensure that the generator $g$ is not set to a trivial value which would make signature forgery easier. Test five ensures that $q$ divides the order of multiplicative sub-group of $\Z/p\Z$. Test six ensures that the generator actually generates a prime order group. Tests seven and eight ensure that the public key is within range and belongs to a group of prime order. Note that test eight does not prove that $g$ generated $y$ only -that $y$ belongs to a multiplicative sub-group of order $q$. +that $y$ belongs to a multiplicative sub-group of order $q$. The following function will perform these tests. @@ -4380,12 +4380,12 @@ To generate a DSA signature call the following function: \index{dsa\_sign\_hash()} \begin{verbatim} -int dsa_sign_hash(const unsigned char *in, +int dsa_sign_hash(const unsigned char *in, unsigned long inlen, - unsigned char *out, + unsigned char *out, unsigned long *outlen, - prng_state *prng, - int wprng, + prng_state *prng, + int wprng, dsa_key *key); \end{verbatim} @@ -4396,17 +4396,17 @@ is stored and the function returns an error code. The DSA \textit{key} must be \subsection{Signature Verification} To verify a hash created with that function use the following function: -\index{dsa\_verify\_hash()} +\index{dsa\_verify\_hash()} \begin{verbatim} -int dsa_verify_hash(const unsigned char *sig, +int dsa_verify_hash(const unsigned char *sig, unsigned long siglen, - const unsigned char *hash, - unsigned long inlen, - int *stat, + const unsigned char *hash, + unsigned long inlen, + int *stat, dsa_key *key); \end{verbatim} -Which will verify the data in \textit{hash} of length \textit{inlen} against the signature stored in \textit{sig} of length \textit{siglen}. -It will set \textit{stat} to $1$ if the signature is valid, otherwise it sets \textit{stat} to $0$. +Which will verify the data in \textit{hash} of length \textit{inlen} against the signature stored in \textit{sig} of length \textit{siglen}. +It will set \textit{stat} to $1$ if the signature is valid, otherwise it sets \textit{stat} to $0$. \mysection{DSA Encrypt and Decrypt} As of version 1.07, the DSA keys can be used to encrypt and decrypt small payloads. It works similar to the ECC encryption where @@ -4418,31 +4418,31 @@ This function will encrypt a small payload with a recipients public DSA key. \index{dsa\_encrypt\_key()} \begin{verbatim} -int dsa_encrypt_key(const unsigned char *in, +int dsa_encrypt_key(const unsigned char *in, unsigned long inlen, - unsigned char *out, - unsigned long *outlen, - prng_state *prng, - int wprng, - int hash, + unsigned char *out, + unsigned long *outlen, + prng_state *prng, + int wprng, + int hash, dsa_key *key); \end{verbatim} This will encrypt the payload in \textit{in} of length \textit{inlen} and store the ciphertext in the output buffer \textit{out}. The -length of the ciphertext \textit{outlen} must be originally set to the length of the output buffer. The DSA \textit{key} can be +length of the ciphertext \textit{outlen} must be originally set to the length of the output buffer. The DSA \textit{key} can be a public key. \subsection{DSA Decryption} \index{dsa\_decrypt\_key()} -\begin{verbatim} -int dsa_decrypt_key(const unsigned char *in, +\begin{verbatim} +int dsa_decrypt_key(const unsigned char *in, unsigned long inlen, - unsigned char *out, - unsigned long *outlen, + unsigned char *out, + unsigned long *outlen, dsa_key *key); \end{verbatim} -This will decrypt the ciphertext \textit{in} of length \textit{inlen}, and store the original payload in \textit{out} of length \textit{outlen}. +This will decrypt the ciphertext \textit{in} of length \textit{inlen}, and store the original payload in \textit{out} of length \textit{outlen}. The DSA \textit{key} must be a private key. \mysection{DSA Key Import and Export} @@ -4451,9 +4451,9 @@ The DSA \textit{key} must be a private key. To export a DSA key so that it can be transported use the following function: \index{dsa\_export()} \begin{verbatim} -int dsa_export(unsigned char *out, - unsigned long *outlen, - int type, +int dsa_export(unsigned char *out, + unsigned long *outlen, + int type, dsa_key *key); \end{verbatim} This will export the DSA \textit{key} to the buffer \textit{out} and set the length in \textit{outlen} (which must have been previously @@ -4465,21 +4465,21 @@ To import an exported DSA key use the following function : \index{dsa\_import()} \begin{verbatim} -int dsa_import(const unsigned char *in, - unsigned long inlen, +int dsa_import(const unsigned char *in, + unsigned long inlen, dsa_key *key); \end{verbatim} This will import the DSA key from the buffer \textit{in} of length \textit{inlen} to the \textit{key}. If the process fails the function -will automatically free all of the heap allocated in the process (you don't have to call dsa\_free()). +will automatically free all of the heap allocated in the process (you don't have to call dsa\_free()). \chapter{Standards Support} \mysection{ASN.1 Formats} LibTomCrypt supports a variety of ASN.1 data types encoded with the Distinguished Encoding Rules (DER) suitable for various cryptographic protocols. The data types 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 -format, and two functions have been dedicated to encoding and decoding the format. +format, and two functions have been dedicated to encoding and decoding the format. -On top of the basic data types are the SEQUENCE and SET data types which are collections of other ASN.1 types. They are provided +On top of the basic data types are the SEQUENCE and SET data types which are collections of other ASN.1 types. They are provided 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 the following: \index{ltc\_asn1\_list structure} @@ -4489,13 +4489,13 @@ typedef struct { void *data; unsigned long size; int used; - struct ltc_asn1_list_ *prev, *next, + struct ltc_asn1_list_ *prev, *next, *child, *parent; } ltc_asn1_list; \end{verbatim} \index{LTC\_SET\_ASN1 macro} -The \textit{type} field is one of the following ASN.1 field definitions. The \textit{data} pointer is a void pointer to the data to be encoded (or the destination) and the +The \textit{type} field is one of the following ASN.1 field definitions. The \textit{data} pointer is a void pointer to the data to be encoded (or the destination) and the \textit{size} field is specific to what you are encoding (e.g. number of bits in the BIT STRING data type). The \textit{used} field is primarily for the CHOICE decoder 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 \textit{LTC\_SET\_ASN1(list, index, Type, Data, Size)} has been provided. @@ -4565,9 +4565,9 @@ with the following function. \index{der\_encode\_sequence()} \begin{verbatim} -int der_encode_sequence(ltc_asn1_list *list, +int der_encode_sequence(ltc_asn1_list *list, unsigned long inlen, - unsigned char *out, + unsigned char *out, unsigned long *outlen); \end{verbatim} This encodes a sequence of items pointed to by \textit{list} where the list has \textit{inlen} items in it. The SEQUENCE will be encoded to \textit{out} and of length \textit{outlen}. The @@ -4581,14 +4581,14 @@ the \textit{data} pointer is simply a pointer to another \textbf{ltc\_asn1\_list \index{der\_decode\_sequence()} -Decoding a SEQUENCE is similar to encoding. You set up an array of \textbf{ltc\_asn1\_list} where in this case the \textit{size} member is the maximum size +Decoding a SEQUENCE is similar to encoding. You set up an array of \textbf{ltc\_asn1\_list} where in this case the \textit{size} member is the maximum size (in certain cases). For types such as IA5 STRING, BIT STRING, OCTET STRING (etc) the \textit{size} field is updated after successful decoding to reflect how many -units of the respective type has been loaded. +units of the respective type has been loaded. \begin{verbatim} int der_decode_sequence(const unsigned char *in, unsigned long inlen, - ltc_asn1_list *list, + ltc_asn1_list *list, unsigned long outlen); \end{verbatim} @@ -4610,12 +4610,12 @@ The length of a SEQUENCE can be determined with the following function. \index{der\_length\_sequence()} \begin{verbatim} -int der_length_sequence(ltc_asn1_list *list, +int der_length_sequence(ltc_asn1_list *list, unsigned long inlen, unsigned long *outlen); \end{verbatim} -This will get the encoding size for the given \textit{list} of length \textit{inlen} and store it in \textit{outlen}. +This will get the encoding size for the given \textit{list} of length \textit{inlen} and store it in \textit{outlen}. \subsubsection{SEQUENCE Multiple Argument Lists} @@ -4625,10 +4625,10 @@ For small or simple sequences an encoding or decoding can be performed with one \index{der\_decode\_sequence\_multi()} \begin{verbatim} -int der_encode_sequence_multi(unsigned char *out, +int der_encode_sequence_multi(unsigned char *out, unsigned long *outlen, ...); -int der_decode_sequence_multi(const unsigned char *in, +int der_decode_sequence_multi(const unsigned char *in, unsigned long inlen, ...); \end{verbatim} @@ -4647,7 +4647,7 @@ unsigned long buflen; int err; buflen = sizeof(buf); - if ((err = + if ((err = der_encode_sequence_multi(buf, &buflen, LTC_ASN1_IA5_STRING, 5UL, "Hello", LTC_ASN1_IA5_STRING, 7UL, " World!", @@ -4664,7 +4664,7 @@ on the size parameters. This forces the compiler to pass the numbers as the req \index{SET} \index{SET OF} SET and SET OF are related to the SEQUENCE type in that they can be pretty much be decoded with the same code. However, they are different, and they should -be carefully noted. The SET type is an unordered array of ASN.1 types sorted by the TAG (type identifier), whereas the SET OF type is an ordered array of +be carefully noted. The SET type is an unordered array of ASN.1 types sorted by the TAG (type identifier), whereas the SET OF type is an ordered array of a \textbf{single} ASN.1 object sorted in ascending order by the DER their respective encodings. \subsubsection{SET Encoding} @@ -4673,14 +4673,14 @@ SETs use the same array structure of ltc\_asn1\_list that the SEQUENCE functions \index{der\_encode\_set()} \begin{verbatim} -int der_encode_set(ltc_asn1_list *list, +int der_encode_set(ltc_asn1_list *list, unsigned long inlen, - unsigned char *out, + unsigned char *out, unsigned long *outlen); -\end{verbatim} +\end{verbatim} -This will encode the list of ASN.1 objects in \textit{list} of length \textit{inlen} objects, and store the output in \textit{out} of length \textit{outlen} bytes. -The function will make a copy of the list provided, and sort it by the TAG. Objects with identical TAGs are additionally sorted on their original placement in the +This will encode the list of ASN.1 objects in \textit{list} of length \textit{inlen} objects, and store the output in \textit{out} of length \textit{outlen} bytes. +The function will make a copy of the list provided, and sort it by the TAG. Objects with identical TAGs are additionally sorted on their original placement in the array (to make the process deterministic). This function will \textbf{NOT} recognize \textit{DEFAULT} objects, and it is the responsibility of the caller to remove them as required. @@ -4691,39 +4691,39 @@ The SET type can be decoded with the following function. \index{der\_decode\_set()} \begin{verbatim} -int der_decode_set(const unsigned char *in, +int der_decode_set(const unsigned char *in, unsigned long inlen, - ltc_asn1_list *list, + ltc_asn1_list *list, unsigned long outlen); \end{verbatim} This will decode the SET specified by \textit{list} of length \textit{outlen} objects from the input buffer \textit{in} of length \textit{inlen} octets. -It handles the fact that SETs are not strictly ordered and will make multiple passes (as required) through the list to decode all the objects. +It handles the fact that SETs are not strictly ordered and will make multiple passes (as required) through the list to decode all the objects. \subsubsection{SET Length} The length of a SET can be determined by calling der\_length\_sequence() since they have the same encoding length. \subsubsection{SET OF Encoding} -A \textit{SET OF} object is an array of identical objects (e.g. OCTET STRING) sorted in ascending order by the DER encoding of the object. They are +A \textit{SET OF} object is an array of identical objects (e.g. OCTET STRING) sorted in ascending order by the DER encoding of the object. They are used to store objects deterministically based solely on their encoding. It uses the same array structure of ltc\_asn1\_list that the SEQUENCE functions use. They are encoded with the following function. \index{der\_encode\_setof()} \begin{verbatim} -int der_encode_setof(ltc_asn1_list *list, +int der_encode_setof(ltc_asn1_list *list, unsigned long inlen, - unsigned char *out, + unsigned char *out, unsigned long *outlen); \end{verbatim} This will encode a \textit{SET OF} containing the \textit{list} of \textit{inlen} ASN.1 objects and store the encoding in the output buffer \textit{out} of length \textit{outlen}. The routine will first encode the SET OF in an unordered fashion (in a temporary buffer) then sort using the XQSORT macro and copy back to the output buffer. This -means you need at least enough memory to keep an additional copy of the output on the heap. +means you need at least enough memory to keep an additional copy of the output on the heap. \subsubsection{SET OF Decoding} -Since the decoding of a \textit{SET OF} object is unambiguous it can be decoded with der\_decode\_sequence(). +Since the decoding of a \textit{SET OF} object is unambiguous it can be decoded with der\_decode\_sequence(). \subsubsection{SET OF Length} Like the SET type the der\_length\_sequence() function can be used to determine the length of a \textit{SET OF} object. @@ -4734,15 +4734,15 @@ To encode or decode INTEGER data types use the following functions. \index{der\_encode\_integer()}\index{der\_decode\_integer()}\index{der\_length\_integer()} \begin{verbatim} -int der_encode_integer( void *num, - unsigned char *out, +int der_encode_integer( void *num, + unsigned char *out, unsigned long *outlen); -int der_decode_integer(const unsigned char *in, - unsigned long inlen, +int der_decode_integer(const unsigned char *in, + unsigned long inlen, void *num); -int der_length_integer( void *num, +int der_length_integer( void *num, unsigned long *len); \end{verbatim} @@ -4751,36 +4751,36 @@ a bignum to store the value, the \textit{short} INTEGER functions were made avai \index{der\_encode\_short\_integer()}\index{der\_decode\_short\_integer()}\index{der\_length\_short\_integer()} \begin{verbatim} -int der_encode_short_integer(unsigned long num, - unsigned char *out, +int der_encode_short_integer(unsigned long num, + unsigned char *out, unsigned long *outlen); -int der_decode_short_integer(const unsigned char *in, - unsigned long inlen, +int der_decode_short_integer(const unsigned char *in, + unsigned long inlen, unsigned long *num); -int der_length_short_integer(unsigned long num, +int der_length_short_integer(unsigned long num, unsigned long *outlen); \end{verbatim} -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 -and short integer functions can encode and decode each others outputs. +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 +and short integer functions can encode and decode each others outputs. \subsection{ASN.1 BIT STRING} \index{der\_encode\_bit\_string()}\index{der\_decode\_bit\_string()}\index{der\_length\_bit\_string()} \begin{verbatim} -int der_encode_bit_string(const unsigned char *in, +int der_encode_bit_string(const unsigned char *in, unsigned long inlen, - unsigned char *out, + unsigned char *out, unsigned long *outlen); -int der_decode_bit_string(const unsigned char *in, +int der_decode_bit_string(const unsigned char *in, unsigned long inlen, - unsigned char *out, + unsigned char *out, unsigned long *outlen); -int der_length_bit_string(unsigned long nbits, +int der_length_bit_string(unsigned long nbits, unsigned long *outlen); \end{verbatim} @@ -4791,65 +4791,65 @@ as a one bit, and a zero value a zero bit. \index{der\_encode\_octet\_string()}\index{der\_decode\_octet\_string()}\index{der\_length\_octet\_string()} \begin{verbatim} -int der_encode_octet_string(const unsigned char *in, +int der_encode_octet_string(const unsigned char *in, unsigned long inlen, - unsigned char *out, + unsigned char *out, unsigned long *outlen); -int der_decode_octet_string(const unsigned char *in, +int der_decode_octet_string(const unsigned char *in, unsigned long inlen, - unsigned char *out, + unsigned char *out, unsigned long *outlen); -int der_length_octet_string(unsigned long noctets, +int der_length_octet_string(unsigned long noctets, unsigned long *outlen); \end{verbatim} -These will encode or decode an OCTET STRING data type. The octets are stored using one \textbf{unsigned char} each. +These will encode or decode an OCTET STRING data type. The octets are stored using one \textbf{unsigned char} each. \subsection{ASN.1 OBJECT IDENTIFIER} \index{der\_encode\_object\_identifier()}\index{der\_decode\_object\_identifier()}\index{der\_length\_object\_identifier()} \begin{verbatim} -int der_encode_object_identifier(unsigned long *words, +int der_encode_object_identifier(unsigned long *words, unsigned long nwords, - unsigned char *out, + unsigned char *out, unsigned long *outlen); int der_decode_object_identifier(const unsigned char *in, unsigned long inlen, - unsigned long *words, + unsigned long *words, unsigned long *outlen); -int der_length_object_identifier(unsigned long *words, - unsigned long nwords, +int der_length_object_identifier(unsigned long *words, + unsigned long nwords, unsigned long *outlen); \end{verbatim} 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 -$0 \ldots 2^{32} - 1$. +$0 \ldots 2^{32} - 1$. \subsection{ASN.1 IA5 STRING} \index{der\_encode\_ia5\_string()}\index{der\_decode\_ia5\_string()}\index{der\_length\_ia5\_string()} \begin{verbatim} -int der_encode_ia5_string(const unsigned char *in, +int der_encode_ia5_string(const unsigned char *in, unsigned long inlen, - unsigned char *out, + unsigned char *out, unsigned long *outlen); -int der_decode_ia5_string(const unsigned char *in, +int der_decode_ia5_string(const unsigned char *in, unsigned long inlen, - unsigned char *out, + unsigned char *out, unsigned long *outlen); -int der_length_ia5_string(const unsigned char *octets, - unsigned long noctets, +int der_length_ia5_string(const unsigned char *octets, + unsigned long noctets, unsigned long *outlen); \end{verbatim} These will encode or decode an IA5 STRING. The characters are read or stored in individual \textbf{char} elements. These functions performs internal character -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 +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 say a SPARC machine. Internally, these functions have a table of literal characters and their numerical ASCII values. This provides a stable conversion provided that the build platform honours the run--time platforms character conventions. @@ -4857,23 +4857,23 @@ that the build platform honours the run--time platforms character conventions. \index{der\_encode\_printable\_string()}\index{der\_decode\_printable\_string()}\index{der\_length\_printable\_string()} \begin{verbatim} -int der_encode_printable_string(const unsigned char *in, +int der_encode_printable_string(const unsigned char *in, unsigned long inlen, - unsigned char *out, + unsigned char *out, unsigned long *outlen); -int der_decode_printable_string(const unsigned char *in, +int der_decode_printable_string(const unsigned char *in, unsigned long inlen, - unsigned char *out, + unsigned char *out, unsigned long *outlen); -int der_length_printable_string(const unsigned char *octets, - unsigned long noctets, +int der_length_printable_string(const unsigned char *octets, + unsigned long noctets, unsigned long *outlen); \end{verbatim} These will encode or decode an PRINTABLE STRING. The characters are read or stored in individual \textbf{char} elements. These functions performs internal character -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 +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 say a SPARC machine. Internally, these functions have a table of literal characters and their numerical ASCII values. This provides a stable conversion provided that the build platform honours the run-time platforms character conventions. @@ -4881,25 +4881,25 @@ that the build platform honours the run-time platforms character conventions. \index{der\_encode\_utf8\_string()}\index{der\_decode\_utf8\_string()}\index{der\_length\_utf8\_string()} \begin{verbatim} -int der_encode_utf8_string(const wchar_t *in, +int der_encode_utf8_string(const wchar_t *in, unsigned long inlen, - unsigned char *out, + unsigned char *out, unsigned long *outlen); -int der_decode_utf8_string(const unsigned char *in, +int der_decode_utf8_string(const unsigned char *in, unsigned long inlen, - wchar_t *out, + wchar_t *out, unsigned long *outlen); -int der_length_utf8_string(const wchar_t *octets, - unsigned long noctets, +int der_length_utf8_string(const wchar_t *octets, + unsigned long noctets, unsigned long *outlen); \end{verbatim} These will encode or decode an UTF8 STRING. The characters are read or stored in individual \textbf{wchar\_t} elements. These function performs no internal -mapping and treat the characters as literals. +mapping and treat the characters as literals. -These functions use the \textbf{wchar\_t} type which is not universally available. In those cases, the library will typedef it to \textbf{unsigned long}. If you +These functions use the \textbf{wchar\_t} type which is not universally available. In those cases, the library will typedef it to \textbf{unsigned long}. If you intend to use the ISO C functions for working with wide--char arrays, you should make sure that wchar\_t has been defined previously. \subsection{ASN.1 UTCTIME} @@ -4921,47 +4921,47 @@ typedef struct { } ltc_utctime; \end{verbatim} -The time can be offset plus or minus a set amount of hours (off\_hh) and minutes (off\_mm). When \textit{off\_dir} is zero, the time will be added otherwise it -will be subtracted. For instance, the array $\lbrace 5, 6, 20, 22, 4, 00, 0, 5, 0 \rbrace$ represents the current time of -\textit{2005, June 20th, 22:04:00} with a time offset of +05h00. +The time can be offset plus or minus a set amount of hours (off\_hh) and minutes (off\_mm). When \textit{off\_dir} is zero, the time will be added otherwise it +will be subtracted. For instance, the array $\lbrace 5, 6, 20, 22, 4, 00, 0, 5, 0 \rbrace$ represents the current time of +\textit{2005, June 20th, 22:04:00} with a time offset of +05h00. \index{der\_encode\_utctime()}\index{der\_decode\_utctime()}\index{der\_length\_utctime()} \begin{verbatim} -int der_encode_utctime( ltc_utctime *utctime, - unsigned char *out, +int der_encode_utctime( ltc_utctime *utctime, + unsigned char *out, unsigned long *outlen); -int der_decode_utctime(const unsigned char *in, +int der_decode_utctime(const unsigned char *in, unsigned long *inlen, ltc_utctime *out); -int der_length_utctime( ltc_utctime *utctime, +int der_length_utctime( ltc_utctime *utctime, unsigned long *outlen); \end{verbatim} -The encoder will store time in one of the two ASN.1 formats, either \textit{YYMMDDhhmmssZ} or \textit{YYMMDDhhmmss$\pm$hhmm}, and perform minimal error checking on the +The encoder will store time in one of the two ASN.1 formats, either \textit{YYMMDDhhmmssZ} or \textit{YYMMDDhhmmss$\pm$hhmm}, and perform minimal error checking on the 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. It is suggested that decoded data be further scrutinized (e.g. days of month in particular). \subsection{ASN.1 CHOICE} -The CHOICE ASN.1 type represents a union of ASN.1 types all of which are stored in a \textit{ltc\_asn1\_list}. There is no encoder for the CHOICE type, only a +The CHOICE ASN.1 type represents a union of ASN.1 types all of which are stored in a \textit{ltc\_asn1\_list}. There is no encoder for the CHOICE type, only a 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 -type\footnote{Except it cannot have LTC\_ASN1\_INTEGER and LTC\_ASN1\_SHORT\_INTEGER simultaneously.} except for other CHOICE types. +type\footnote{Except it cannot have LTC\_ASN1\_INTEGER and LTC\_ASN1\_SHORT\_INTEGER simultaneously.} except for other CHOICE types. -There is no encoder for the CHOICE type as the actual DER encoding is the encoding of the chosen type. +There is no encoder for the CHOICE type as the actual DER encoding is the encoding of the chosen type. \index{der\_decode\_choice()} \begin{verbatim} -int der_decode_choice(const unsigned char *in, +int der_decode_choice(const unsigned char *in, unsigned long *inlen, - ltc_asn1_list *list, + ltc_asn1_list *list, unsigned long outlen); \end{verbatim} -This will decode the input in the \textit{in} field of length \textit{inlen}. It uses the provided ASN.1 list specified in the \textit{list} field which has -\textit{outlen} elements. The \textit{inlen} field will be updated with the length of the decoded data type, as well as the respective entry in the \textit{list} field +This will decode the input in the \textit{in} field of length \textit{inlen}. It uses the provided ASN.1 list specified in the \textit{list} field which has +\textit{outlen} elements. The \textit{inlen} field will be updated with the length of the decoded data type, as well as the respective entry in the \textit{list} field will have the \textit{used} flag set to non--zero to reflect it was the data type decoded. \subsection{ASN.1 Flexi Decoder} @@ -4969,17 +4969,17 @@ The ASN.1 \textit{flexi} decoder allows the developer to decode arbitrary ASN.1 the structure of the data. Where der\_decode \_sequence() requires the developer to specify the data types to decode in advance the flexi decoder is entirely free form. -The flexi decoder uses the same \textit{ltc\_asn1\_list} but instead of being stored in an array it uses the linked list pointers \textit{prev}, \textit{next}, \textit{parent} +The flexi decoder uses the same \textit{ltc\_asn1\_list} but instead of being stored in an array it uses the linked list pointers \textit{prev}, \textit{next}, \textit{parent} and \textit{child}. The list works as a \textit{doubly-linked list} structure where decoded items at the same level are siblings (using next and prev) and items encoded in a SEQUENCE are stored as a child element. -When a SEQUENCE or SET has been encountered a SEQUENCE (or SET resp.) item will be added as a sibling (e.g. list.type == LTC\_ASN1\_SEQUENCE) and the child +When a SEQUENCE or SET has been encountered a SEQUENCE (or SET resp.) item will be added as a sibling (e.g. list.type == LTC\_ASN1\_SEQUENCE) and the child pointer points to a new list of items contained within the object. \index{der\_decode\_sequence\_flexi()} \begin{verbatim} -int der_decode_sequence_flexi(const unsigned char *in, - unsigned long *inlen, +int der_decode_sequence_flexi(const unsigned char *in, + unsigned long *inlen, ltc_asn1_list **out); \end{verbatim} @@ -4987,12 +4987,12 @@ This will decode items in the \textit{in} buffer of max input length \textit{inl all required memory for the decoding. It stores the number of octets read back into \textit{inlen}. The function will terminate when either it hits an invalid ASN.1 tag, or it reads \textit{inlen} octets. An early termination is a soft error, and returns -normally. The decoded list \textit{out} will point to the very first element of the list (e.g. both parent and prev pointers will be \textbf{NULL}). +normally. The decoded list \textit{out} will point to the very first element of the list (e.g. both parent and prev pointers will be \textbf{NULL}). -An invalid decoding will terminate the process, and free the allocated memory automatically. +An invalid decoding will terminate the process, and free the allocated memory automatically. \textbf{Note:} the list decoded by this function is \textbf{NOT} in the correct form for der\_encode\_sequence() to use directly. You will first -have to convert the list by first storing all of the siblings in an array then storing all the children as sub-lists of a sequence using the \textit{.data} +have to convert the list by first storing all of the siblings in an array then storing all the children as sub-lists of a sequence using the \textit{.data} pointer. Currently no function in LibTomCrypt provides this ability. \subsubsection{Sample Decoding} @@ -5049,7 +5049,7 @@ The \textit{LastOn} member of the SEQUENCE is a sibbling of the LoginToken node, list = list->parent->next; \end{verbatim} \end{small} -At this point, we are pointing to the last node of the list. Lists are terminated in all directions by a \textbf{NULL} pointer. All nodes are doubly linked so that you +At this point, we are pointing to the last node of the list. Lists are terminated in all directions by a \textbf{NULL} pointer. All nodes are doubly linked so that you can walk up and down the nodes without keeping pointers lying around. @@ -5077,22 +5077,22 @@ The OpenSSL project implemented an extension to Algorithm One that allows for ar \subsection{Algorithm One} Algorithm One accepts as input a password, an 8--byte salt, and an iteration counter. The iteration counter is meant to act as delay for -people trying to brute force guess the password. The higher the iteration counter the longer the delay. This algorithm also requires a hash -algorithm and produces an output no longer than the output of the hash. +people trying to brute force guess the password. The higher the iteration counter the longer the delay. This algorithm also requires a hash +algorithm and produces an output no longer than the output of the hash. \index{pkcs\_5\_alg1()} \begin{alltt} -int pkcs_5_alg1(const unsigned char *password, - unsigned long password_len, - const unsigned char *salt, - int iteration_count, +int pkcs_5_alg1(const unsigned char *password, + unsigned long password_len, + const unsigned char *salt, + int iteration_count, int hash_idx, unsigned char *out, unsigned long *outlen) \end{alltt} -Where \textit{password} is the user's password. Since the algorithm allows binary passwords you must also specify the length in \textit{password\_len}. +Where \textit{password} is the user's password. Since the algorithm allows binary passwords you must also specify the length in \textit{password\_len}. The \textit{salt} is a fixed size 8--byte array which should be random for each user and session. The \textit{iteration\_count} is the delay desired -on the password. The \textit{hash\_idx} is the index of the hash you wish to use in the descriptor table. +on the password. The \textit{hash\_idx} is the index of the hash you wish to use in the descriptor table. The output of length up to \textit{outlen} is stored in \textit{out}. If \textit{outlen} is initially larger than the size of the hash functions output it is set to the number of bytes stored. If it is smaller than not all of the hash output is stored in \textit{out}. @@ -5110,28 +5110,28 @@ int pkcs_5_alg1_openssl(const unsigned char *password, As above, but we generate as many bytes as requested in outlen per the OpenSSL extension to Algorithm One. If you are trying to be compatible with OpenSSL's EVP\_BytesToKey() or the "openssl enc" command line (or variants such as perl's Crypt::CBC), then use this function with MD5 as your hash (ick!) and iteration\_count=1 (double-ick!!). \subsection{Algorithm Two} -Algorithm Two is the recommended algorithm for this task. It allows variable length salts, and can produce outputs larger than the +Algorithm Two is the recommended algorithm for this task. It allows variable length salts, and can produce outputs larger than the hash functions output. As such, it can easily be used to derive session keys for ciphers and MACs as well initial vectors as required from a single password and invocation of this algorithm. \index{pkcs\_5\_alg2()} \begin{alltt} int pkcs_5_alg2(const unsigned char *password, - unsigned long password_len, + unsigned long password_len, const unsigned char *salt, unsigned long salt_len, - int iteration_count, + int iteration_count, int hash_idx, unsigned char *out, unsigned long *outlen) \end{alltt} -Where \textit{password} is the users password. Since the algorithm allows binary passwords you must also specify the length in \textit{password\_len}. +Where \textit{password} is the users password. Since the algorithm allows binary passwords you must also specify the length in \textit{password\_len}. The \textit{salt} is an array of size \textit{salt\_len}. It should be random for each user and session. The \textit{iteration\_count} is the delay desired -on the password. The \textit{hash\_idx} is the index of the hash you wish to use in the descriptor table. The output of length up to +on the password. The \textit{hash\_idx} is the index of the hash you wish to use in the descriptor table. The output of length up to \textit{outlen} is stored in \textit{out}. \begin{verbatim} -/* demo to show how to make session state material +/* demo to show how to make session state material * from a password */ #include int main(void) @@ -5148,9 +5148,9 @@ int main(void) /* create the material (100 iterations in algorithm) */ outlen = sizeof(outbuf); - if ((err = pkcs_5_alg2(password, password_len, salt, - salt_len, 100, hash_idx, outbuf, - &outlen)) + if ((err = pkcs_5_alg2(password, password_len, salt, + salt_len, 100, hash_idx, outbuf, + &outlen)) != CRYPT_OK) { /* error handle */ } @@ -5248,7 +5248,7 @@ ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/ \end{verbatim} Those characters are supported in the 7-bit ASCII map, which means they can be used for transport over common e-mail, usenet and HTTP mediums. The format of an encoded stream is just a literal sequence of ASCII characters -where a group of four represent 24-bits of input. The first four chars of the encoders output is the length of the +where a group of four represent 24-bits of input. The first four chars of the encoders output is the length of the original input. After the first four characters is the rest of the message. Often, it is desirable to line wrap the output to fit nicely in an e-mail or usenet posting. The decoder allows you to @@ -5256,30 +5256,30 @@ put any character (that is not in the above sequence) in between any character o break up the first four characters. To encode a binary string in base64 call: -\index{base64\_encode()} \index{base64\_decode()} +\index{base64\_encode()} \index{base64\_decode()} \begin{verbatim} -int base64_encode(const unsigned char *in, - unsigned long len, - unsigned char *out, +int base64_encode(const unsigned char *in, + unsigned long len, + unsigned char *out, unsigned long *outlen); \end{verbatim} Where \textit{in} is the binary string and \textit{out} is where the ASCII output is placed. You must set the value of \textit{outlen} prior -to calling this function and it sets the length of the base64 output in \textit{outlen} when it is done. To decode a base64 +to calling this function and it sets the length of the base64 output in \textit{outlen} when it is done. To decode a base64 string call: \begin{verbatim} -int base64_decode(const unsigned char *in, - unsigned long len, - unsigned char *out, +int base64_decode(const unsigned char *in, + unsigned long len, + unsigned char *out, unsigned long *outlen); \end{verbatim} \mysection{Primality Testing} \index{Primality Testing} The library includes primality testing and random prime functions as well. The primality tester will perform the test in -two phases. First it will perform trial division by the first few primes. Second it will perform eight rounds of the +two phases. First it will perform trial division by the first few primes. Second it will perform eight rounds of the Rabin-Miller primality testing algorithm. If the candidate passes both phases it is declared prime otherwise it is declared composite. No prime number will fail the two phases but composites can. Each round of the Rabin-Miller algorithm reduces -the probability of a pseudo-prime by $1 \over 4$ therefore after sixteen rounds the probability is no more than +the probability of a pseudo-prime by $1 \over 4$ therefore after sixteen rounds the probability is no more than $\left ( { 1 \over 4 } \right )^{8} = 2^{-16}$. In practice the probability of error is in fact much lower than that. When making random primes the trial division step is in fact an optimized implementation of \textit{Implementation of Fast RSA Key Generation on Smart Cards}\footnote{Chenghuai Lu, Andre L. M. dos Santos and Francisco R. Pimentel}. @@ -5288,29 +5288,29 @@ is rejected and ultimately incremented to test the next number the residues are math operations. As a result the routine can scan ahead to the next number required for testing with very little work involved. -In the event that a composite did make it through it would most likely cause the the algorithm trying to use it to fail. For -instance, in RSA two primes $p$ and $q$ are required. The order of the multiplicative sub-group (modulo $pq$) is given +In the event that a composite did make it through it would most likely cause the the algorithm trying to use it to fail. For +instance, in RSA two primes $p$ and $q$ are required. The order of the multiplicative sub-group (modulo $pq$) is given as $\phi(pq)$ or $(p - 1)(q - 1)$. The decryption exponent $d$ is found as $de \equiv 1\mbox{ }(\mbox{mod } \phi(pq))$. If either $p$ or $q$ is composite the value of $d$ will be incorrect and the user -will not be able to sign or decrypt messages at all. Suppose $p$ was prime and $q$ was composite this is just a variation of -the multi-prime RSA. Suppose $q = rs$ for two primes $r$ and $s$ then $\phi(pq) = (p - 1)(r - 1)(s - 1)$ which clearly is +will not be able to sign or decrypt messages at all. Suppose $p$ was prime and $q$ was composite this is just a variation of +the multi-prime RSA. Suppose $q = rs$ for two primes $r$ and $s$ then $\phi(pq) = (p - 1)(r - 1)(s - 1)$ which clearly is not equal to $(p - 1)(rs - 1)$. -These are not technically part of the LibTomMath library but this is the best place to document them. +These are not technically part of the LibTomMath library but this is the best place to document them. To test if a \textit{mp\_int} is prime call: \begin{verbatim} int is_prime(mp_int *N, int *result); \end{verbatim} -This puts a one in \textit{result} if the number is probably prime, otherwise it places a zero in it. It is assumed that if -it returns an error that the value in \textit{result} is undefined. To make +This puts a one in \textit{result} if the number is probably prime, otherwise it places a zero in it. It is assumed that if +it returns an error that the value in \textit{result} is undefined. To make a random prime call: \begin{verbatim} -int rand_prime( mp_int *N, - unsigned long len, - prng_state *prng, +int rand_prime( mp_int *N, + unsigned long len, + prng_state *prng, int wprng); \end{verbatim} Where \textit{len} is the size of the prime in bytes ($2 \le len \le 256$). You can set \textit{len} to the negative size you want -to get a prime of the form $p \equiv 3\mbox{ }(\mbox{mod } 4)$. So if you want a 1024-bit prime of this sort pass +to get a prime of the form $p \equiv 3\mbox{ }(\mbox{mod } 4)$. So if you want a 1024-bit prime of this sort pass \textit{len = -128} to the function. Upon success it will return {\bf CRYPT\_OK} and \textit{N} will contain an integer which is very likely prime. @@ -5319,28 +5319,28 @@ is very likely prime. \mysection{Secure Pseudo Random Number Generators} Probably the single most vulnerable point of any cryptosystem is the PRNG. Without one, generating and protecting secrets would be impossible. The requirement that one be setup correctly is vitally important, and to address this point the library -does provide two RNG sources that will address the largest amount of end users as possible. The \textit{sprng} PRNG provides an easy to -access source of entropy for any application on a UNIX (and the like) or Windows computer. +does provide two RNG sources that will address the largest amount of end users as possible. The \textit{sprng} PRNG provides an easy to +access source of entropy for any application on a UNIX (and the like) or Windows computer. However, when the end user is not on one of these platforms, the application developer must address the issue of finding entropy. This manual is not designed to be a text on cryptography. I would just like to highlight that when you design -a cryptosystem make sure the first problem you solve is getting a fresh source of entropy. +a cryptosystem make sure the first problem you solve is getting a fresh source of entropy. \mysection{Preventing Trivial Errors} Two simple ways to prevent trivial errors is to prevent overflows, and to check the return values. All of the functions which output variable length strings will require you to pass the length of the destination. If the size of your output buffer is smaller than the output it will report an error. Therefore, make sure the size you pass is correct! -Also, virtually all of the functions return an error code or {\bf CRYPT\_OK}. You should detect all errors, as simple +Also, virtually all of the functions return an error code or {\bf CRYPT\_OK}. You should detect all errors, as simple typos can cause algorithms to fail to work as desired. \mysection{Registering Your Algorithms} -To avoid linking and other run--time errors it is important to register the ciphers, hashes and PRNGs you intend to use +To avoid linking and other run--time errors it is important to register the ciphers, hashes and PRNGs you intend to use before you try to use them. This includes any function which would use an algorithm indirectly through a descriptor table. -A neat bonus to the registry system is that you can add external algorithms that are not part of the library without -having to hack the library. For example, suppose you have a hardware specific PRNG on your system. You could easily -write the few functions required plus a descriptor. After registering your PRNG, all of the library functions that +A neat bonus to the registry system is that you can add external algorithms that are not part of the library without +having to hack the library. For example, suppose you have a hardware specific PRNG on your system. You could easily +write the few functions required plus a descriptor. After registering your PRNG, all of the library functions that need a PRNG can instantly take advantage of it. The same applies for ciphers, hashes, and bignum math routines. \mysection{Key Sizes} @@ -5353,10 +5353,10 @@ is not a hard thing to do. As a good rule of thumb do not use a key smaller tha The following chart gives the work factor for solving a DH/RSA public key using the NFS. The work factor for a key of order $n$ is estimated to be \begin{equation} -e^{1.923 \cdot ln(n)^{1 \over 3} \cdot ln(ln(n))^{2 \over 3}} +e^{1.923 \cdot ln(n)^{1 \over 3} \cdot ln(ln(n))^{2 \over 3}} \end{equation} -Note that $n$ is not the bit-length but the magnitude. For example, for a 1024-bit key $n = 2^{1024}$. The work required +Note that $n$ is not the bit-length but the magnitude. For example, for a 1024-bit key $n = 2^{1024}$. The work required is: \begin{figure}[here] \begin{center} @@ -5370,7 +5370,7 @@ is: \hline 2560 & 128.47 \\ \hline 3072 & 138.73 \\ \hline 4096 & 156.49 \\ - \hline + \hline \end{tabular} \end{center} \caption{RSA/DH Key Strength} @@ -5403,7 +5403,7 @@ Using the above tables the following suggestions for key sizes seems appropriate \hline Near term & 1024 & 160 \\ \hline Short term & 1536 & 192 \\ \hline Long Term & 2560 & 384 \\ - \hline + \hline \end{tabular} \end{center} @@ -5414,7 +5414,7 @@ code before threads are initiated. The rest of the code uses state variables you must pass it such as hash\_state, hmac\_state, etc. This means that if each thread has its own state variables then they will not affect each other, and are fully thread safe. This is fairly simple with symmetric ciphers -and hashes. +and hashes. \index{LTC\_PTHREAD} The only sticky issue is a shared PRNG which can be alleviated with the careful use of mutex devices. Defining LTC\_PTHREAD for instance, enables @@ -5431,17 +5431,17 @@ LibTomCrypt no longer provides a math API on its own and relies on third party l The build process now consists of installing a math library first, and then building and installing LibTomCrypt with a math library configured. Note that LibTomCrypt can be built with no internal math descriptors. This means that one must be provided at either -build, or run time for the application. LibTomCrypt comes with three math descriptors that provide a standard interface to math +build, or run time for the application. LibTomCrypt comes with three math descriptors that provide a standard interface to math libraries. \mysection{Makefile variables} -All GNU driven makefiles (including the makefile for ICC) use a set of common variables to control the build and install process. Most of the +All GNU driven makefiles (including the makefile for ICC) use a set of common variables to control the build and install process. Most of the settings can be overwritten from the command line which makes custom installation a breeze. \index{MAKE}\index{CC}\index{AR} \subsection{MAKE, CC and AR} -The MAKE, CC and AR flags can all be overwritten. They default to \textit{make}, \textit{\$CC} and \textit{\$AR} respectively. +The MAKE, CC and AR flags can all be overwritten. They default to \textit{make}, \textit{\$CC} and \textit{\$AR} respectively. Changing MAKE allows you to change what program will be invoked to handle sub--directories. For example, this \begin{verbatim} @@ -5451,7 +5451,7 @@ MAKE=gmake gmake install \begin{flushleft} will build and install the libraries with the \textit{gmake} tool. Similarly, \end{flushleft} \begin{verbatim} -CC=arm-gcc AR=arm-ar make +CC=arm-gcc AR=arm-ar make \end{verbatim} \begin{flushleft} will build the library using \textit{arm--gcc} as the compiler and \textit{arm--ar} as the archiver. \end{flushleft} @@ -5465,7 +5465,7 @@ CFLAGS on the command line. E.g. to add debugging CFLAGS="-g3" make IGNORE_SPEED=1 \end{verbatim} -This will turn off optimizations and add \textit{-g3} to the CFLAGS which enables debugging. +This will turn off optimizations and add \textit{-g3} to the CFLAGS which enables debugging. \subsection{LIBNAME and LIBNAME\_S} \index{LIBNAME} \index{LIBNAME\_S} @@ -5473,13 +5473,13 @@ This will turn off optimizations and add \textit{-g3} to the CFLAGS which enable shared. The \textbf{LIBNAME\_S} variable is the static name while doing shared builds. Ideally they should have the same prefix but don't have to. \index{LIBTEST} \index{LIBTEST\_S} -Similarly \textbf{LIBTEST} and \textbf{LIBTEST\_S} are the names for the profiling and testing library. The default is \textit{libtomcrypt\_prof.a} for +Similarly \textbf{LIBTEST} and \textbf{LIBTEST\_S} are the names for the profiling and testing library. The default is \textit{libtomcrypt\_prof.a} for static and \textit{libtomcrypt\_prof.la} for shared. \subsection{Installation Directories} \index{DESTDIR} \index{LIBPATH} \index{INCPATH} \index{DATADIR} \textbf{DESTDIR} is the prefix for the installation directories. It defaults to an empty string. \textbf{LIBPATH} is the prefix for the library -directory which defaults to \textit{/usr/lib}. \textbf{INCPATH} is the prefix for the header file directory which defaults to \textit{/usr/include}. +directory which defaults to \textit{/usr/lib}. \textbf{INCPATH} is the prefix for the header file directory which defaults to \textit{/usr/include}. \textbf{DATADIR} is the prefix for the data (documentation) directory which defaults to \textit{/usr/share/doc/libtomcrypt/pdf}. All four can be used to create custom install locations depending on the nature of the OS and file system in use. @@ -5537,50 +5537,50 @@ CFLAGS="-DTFM_DESC -DUSE_TFM" EXTRALIBS=-ltfm make install \ \end{verbatim} This will install the library using the TomsFastMath library and link the \textit{libtfm.a} library out of the default library search path. The two -defines are explained below. You can specify multiple archives (say if you want to support two math libraries, or add on additional code) to +defines are explained below. You can specify multiple archives (say if you want to support two math libraries, or add on additional code) to the \textbf{EXTRALIBS} variable by separating them by a space. -Note that \textbf{EXTRALIBS} is not required if you are only making and installing the static library but none of the test programs. +Note that \textbf{EXTRALIBS} is not required if you are only making and installing the static library but none of the test programs. \mysection{Building a Static Library} -Building a static library is fairly trivial as it only requires one invocation of the GNU make command. +Building a static library is fairly trivial as it only requires one invocation of the GNU make command. \begin{verbatim} CFLAGS="-DTFM_DESC" make install \end{verbatim} -That will build LibTomCrypt (including the TomsFastMath descriptor), and install it in the default locations indicated previously. You can enable -the built--in LibTomMath descriptor as well (or in place of the TomsFastMath descriptor). Similarly, you can build the library with no built--in -math descriptors. +That will build LibTomCrypt (including the TomsFastMath descriptor), and install it in the default locations indicated previously. You can enable +the built--in LibTomMath descriptor as well (or in place of the TomsFastMath descriptor). Similarly, you can build the library with no built--in +math descriptors. \begin{verbatim} make install \end{verbatim} -In this case, no math descriptors are present in the library and they will have to be made available at build or run time before you can use any of the -public key functions. +In this case, no math descriptors are present in the library and they will have to be made available at build or run time before you can use any of the +public key functions. -Note that even if you include the built--in descriptors you must link against the source library as well. +Note that even if you include the built--in descriptors you must link against the source library as well. \begin{verbatim} gcc -DTFM_DESC myprogram.c -ltomcrypt -ltfm -o myprogram \end{verbatim} -This will compile \textit{myprogram} and link it against the LibTomCrypt library as well as TomsFastMath (which must have been previously installed). Note that -we define \textbf{TFM\_DESC} for compilation. This is so that the TFM descriptor symbol will be defined for the client application to make use of without +This will compile \textit{myprogram} and link it against the LibTomCrypt library as well as TomsFastMath (which must have been previously installed). Note that +we define \textbf{TFM\_DESC} for compilation. This is so that the TFM descriptor symbol will be defined for the client application to make use of without giving warnings. \mysection{Building a Shared Library} LibTomCrypt can also be built as a shared library through the \textit{makefile.shared} make script. It is similar to use as the static script except -that you \textbf{must} specify the \textbf{EXTRALIBS} variable at install time. +that you \textbf{must} specify the \textbf{EXTRALIBS} variable at install time. \begin{verbatim} CFLAGS="-DTFM_DESC" EXTRALIBS=-ltfm make -f makefile.shared install \end{verbatim} -This will build and install the library and link the shared object against the TomsFastMath library (which must be installed as a shared object as well). The +This will build and install the library and link the shared object against the TomsFastMath library (which must be installed as a shared object as well). The shared build process requires libtool to be installed. \mysection{Header Configuration} @@ -5589,12 +5589,12 @@ stored in \textit{tomcrypt\_custom.h} which allow the enabling and disabling of \subsubsection{ARGTYPE} This lets you control how the LTC\_ARGCHK macro will behave. The macro is used to check pointers inside the functions against -NULL. There are four settings for ARGTYPE. When set to 0, it will have the default behaviour of printing a message to +NULL. There are four settings for ARGTYPE. When set to 0, it will have the default behaviour of printing a message to stderr and raising a SIGABRT signal. This is provided so all platforms that use LibTomCrypt can have an error that functions similarly. When set to 1, it will simply pass on to the assert() macro. When set to 2, the macro will display the error to stderr then return execution to the caller. This could lead to a segmentation fault (e.g. when a pointer is \textbf{NULL}) but is useful if you handle signals on your own. When set to 3, it will resolve to a empty macro and no error checking will be performed. Finally, when set -to 4, it will return CRYPT\_INVALID\_ARG to the caller. +to 4, it will return CRYPT\_INVALID\_ARG to the caller. \subsubsection{Endianness} There are five macros related to endianness issues. For little endian platforms define, \textbf{ENDIAN\_LITTLE}. For big endian @@ -5602,16 +5602,16 @@ platforms define \textbf{ENDIAN\_BIG}. Similarly when the default word size of or define \textbf{ENDIAN\_64BITWORD} when its 64-bits. If you do not define any of them the library will automatically use \textbf{ENDIAN\_NEUTRAL} which will work on all platforms. -Currently LibTomCrypt will detect x86-32, x86-64, MIPS R5900, SPARC and SPARC64 running GCC as well as x86-32 running MSVC. +Currently LibTomCrypt will detect x86-32, x86-64, MIPS R5900, SPARC and SPARC64 running GCC as well as x86-32 running MSVC. \mysection{Customisation} There are also options you can specify from the \textit{tomcrypt\_custom.h} header file. \subsection{X memory routines} \index{XMALLOC}\index{XCALLOC}\index{XREALLOC}\index{XFREE} -At the top of tomcrypt\_custom.h are a series of macros denoted as XMALLOC, XCALLOC, XREALLOC, XFREE, and so on. They resolve to -the name of the respective functions from the standard C library by default. This lets you substitute in your own memory routines. -If you substitute in your own functions they must behave like the standard C library functions in terms of what they expect as input and +At the top of tomcrypt\_custom.h are a series of macros denoted as XMALLOC, XCALLOC, XREALLOC, XFREE, and so on. They resolve to +the name of the respective functions from the standard C library by default. This lets you substitute in your own memory routines. +If you substitute in your own functions they must behave like the standard C library functions in terms of what they expect as input and output. These macros are handy for working with platforms which do not have a standard C library. For instance, the OLPC\footnote{See http://dev.laptop.org/git?p=bios-crypto;a=summary} @@ -5622,12 +5622,12 @@ The rng\_get\_bytes() function can call a function that requires the clock() fun the default clock() used with a replacement. By default the standard C library clock() function is used. \subsection{LTC\_NO\_FILE} -During the build if LTC\_NO\_FILE is defined then any function in the library that uses file I/O will not call the file I/O +During the build if LTC\_NO\_FILE is defined then any function in the library that uses file I/O will not call the file I/O functions and instead simply return CRYPT\_NOP. This should help resolve any linker errors stemming from a lack of file I/O on embedded platforms. \subsection{LTC\_CLEAN\_STACK} -When this functions is defined the functions that store key material on the stack will clean up afterwards. +When this functions is defined the functions that store key material on the stack will clean up afterwards. Assumes that you have no memory paging with the stack. \subsection{LTC\_TEST} @@ -5639,9 +5639,9 @@ When this has been defined the library will not use faster word oriented operati which can be auto-detected. This macro ensures that they are never enabled. \subsection{LTC\_FAST} -This mode (auto-detected with x86\_32, x86\_64 platforms with GCC or CLANG) configures various routines such as ctr\_encrypt() or -cbc\_encrypt() that it can safely XOR multiple octets in one step by using a larger data type. This has the benefit of -cutting down the overhead of the respective functions. +This mode (auto-detected with x86\_32, x86\_64 platforms with GCC or CLANG) configures various routines such as ctr\_encrypt() or +cbc\_encrypt() that it can safely XOR multiple octets in one step by using a larger data type. This has the benefit of +cutting down the overhead of the respective functions. This mode does have one downside. It can cause unaligned reads from memory if you are not careful with the functions. This is why it has been enabled by default only for the x86 class of processors where unaligned accesses are allowed. Technically LTC\_FAST @@ -5650,43 +5650,43 @@ is not \textit{portable} since unaligned accesses are not covered by the ISO C s In practice however, you can use it on pretty much any platform (even MIPS) with care. By design the \textit{fast} mode functions won't get unaligned on their own. For instance, if you call ctr\_encrypt() right after calling -ctr\_start() and all the inputs you gave are aligned than ctr\_encrypt() will perform aligned memory operations only. However, if you +ctr\_start() and all the inputs you gave are aligned than ctr\_encrypt() will perform aligned memory operations only. However, if you call ctr\_encrypt() with an odd amount of plaintext then call it again the CTR pad (the IV) will be partially used. This will -cause the ctr routine to first use up the remaining pad bytes. Then if there are enough plaintext bytes left it will use +cause the ctr routine to first use up the remaining pad bytes. Then if there are enough plaintext bytes left it will use whole word XOR operations. These operations will be unaligned. -The simplest precaution is to make sure you process all data in power of two blocks and handle \textit{remainder} at the end. e.g. If you are -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. +The simplest precaution is to make sure you process all data in power of two blocks and handle \textit{remainder} at the end. e.g. If you are +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. \index{LTC\_FAST\_TYPE} If you do plan on using the \textit{LTC\_FAST} mode, a \textit{LTC\_FAST\_TYPE} type which resolves to an optimal sized -data type you can perform integer operations with is required. For the auto-detected platforms this type will be defined automatically. Ideally it should be four or eight bytes since it must properly divide the size -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 +data type you can perform integer operations with is required. For the auto-detected platforms this type will be defined automatically. Ideally it should be four or eight bytes since it must properly divide the size +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 use this mode. So sad. \subsection{LTC\_NO\_ASM} When this has been defined the library will not use any inline assembler. Only a few platforms support assembler inlines but various versions of ICC and GCC -cannot handle all of the assembler functions. +cannot handle all of the assembler functions. \subsection{Symmetric Ciphers, One-way Hashes, PRNGS and Public Key Functions} -There are a plethora of macros for the ciphers, hashes, PRNGs and public key functions which are fairly -self-explanatory. When they are defined the functionality is included otherwise it is not. There are some -dependency issues which are noted in the file. For instance, Yarrow requires CTR chaining mode, a block +There are a plethora of macros for the ciphers, hashes, PRNGs and public key functions which are fairly +self-explanatory. When they are defined the functionality is included otherwise it is not. There are some +dependency issues which are noted in the file. For instance, Yarrow requires CTR chaining mode, a block cipher and a hash function. Also see technical note number five for more details. \subsection{LTC\_EASY} -When defined the library is configured to build fewer algorithms and modes. Mostly it sticks to NIST and ANSI approved algorithms. See -the header file \textit{tomcrypt\_custom.h} for more details. It is meant to provide literally an easy method of trimming the library +When defined the library is configured to build fewer algorithms and modes. Mostly it sticks to NIST and ANSI approved algorithms. See +the header file \textit{tomcrypt\_custom.h} for more details. It is meant to provide literally an easy method of trimming the library build to the most minimum of useful functionality. \subsection{TWOFISH\_SMALL and TWOFISH\_TABLES} Twofish is a 128-bit symmetric block cipher that is provided within the library. The cipher itself is flexible enough -to allow some trade-offs in the implementation. When TWOFISH\_SMALL is defined the scheduled symmetric key for Twofish -requires only 200 bytes of memory. This is achieved by not pre-computing the substitution boxes. Having this -defined will also greatly slow down the cipher. When this macro is not defined Twofish will pre-compute the -tables at a cost of 4KB of memory. The cipher will be much faster as a result. +to allow some trade-offs in the implementation. When TWOFISH\_SMALL is defined the scheduled symmetric key for Twofish +requires only 200 bytes of memory. This is achieved by not pre-computing the substitution boxes. Having this +defined will also greatly slow down the cipher. When this macro is not defined Twofish will pre-compute the +tables at a cost of 4KB of memory. The cipher will be much faster as a result. When TWOFISH\_TABLES is defined the cipher will use pre-computed (and fixed in code) tables required to work. This is useful when TWOFISH\_SMALL is defined as the table values are computed on the fly. When this is defined the code size @@ -5694,8 +5694,8 @@ will increase by approximately 500 bytes. If this is defined but TWOFISH\_SMALL it will not speed up the encryption or decryption functions. \subsection{GCM\_TABLES} -When defined GCM will use a 64KB table (per GCM state) which will greatly speed up the per--packet latency. -It also increases the initialization time and is not suitable when you are going to use a key a few times only. +When defined GCM will use a 64KB table (per GCM state) which will greatly speed up the per--packet latency. +It also increases the initialization time and is not suitable when you are going to use a key a few times only. \subsection{GCM\_TABLES\_SSE2} \index{SSE2} @@ -5707,7 +5707,7 @@ When this is defined some of the code such as the Rijndael and SAFER+ ciphers ar These variants are slower but can save quite a bit of code space. \subsection{LTC\_PTHREAD} -When this is activated all of the descriptor table functions will use pthread locking to ensure thread safe updates to the tables. Note that +When this is activated all of the descriptor table functions will use pthread locking to ensure thread safe updates to the tables. Note that it doesn't prevent a thread that is passively using a table from being messed up by another thread that updates the table. 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 @@ -5734,11 +5734,11 @@ EXTRALIBS="-lgmp -ltommath -ltfm" make -f makefile.shared install timing \end{verbatim} \end{small} -That will build and install the library with all descriptors (and link against all), but only use TomsFastMath in the timing demo. +That will build and install the library with all descriptors (and link against all), but only use TomsFastMath in the timing demo. \chapter{Optimizations} \mysection{Introduction} -The entire API was designed with plug and play in mind at the low level. That is you can swap out any cipher, hash, PRNG or bignum library and the dependent API will not +The entire API was designed with plug and play in mind at the low level. That is you can swap out any cipher, hash, PRNG or bignum library and the dependent API will not require updating. This has the nice benefit that one can add ciphers (etc.) not have to re--write portions of the API. For the most part, LibTomCrypt has also been written 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 about the platform, etc... @@ -5748,7 +5748,7 @@ portable routines. For instance, hand optimized assembler versions of AES could the optimized code without re--writing. This also paves the way for hardware drivers that can access hardware accelerated cryptographic devices. At the heart of this flexibility is the \textit{descriptor} system. A descriptor is essentially just a C \textit{struct} which describes the algorithm and provides pointers -to functions that do the required work. For a given class of operation (e.g. cipher, hash, prng, bignum) the functions of a descriptor have identical prototypes which makes +to functions that do the required work. For a given class of operation (e.g. cipher, hash, prng, bignum) the functions of a descriptor have identical prototypes which makes development simple. In most dependent routines all an end developer has to do is register\_XXX() the descriptor and they are set. \mysection{Ciphers} @@ -5765,27 +5765,27 @@ struct ltc_cipher_descriptor { unsigned char ID; /** min keysize (octets) */ - int min_key_length, + int min_key_length, /** max keysize (octets) */ - max_key_length, + max_key_length, /** block size (octets) */ - block_length, + block_length, /** default number of rounds */ default_rounds; - /** Setup the cipher + /** Setup the cipher @param key The input symmetric key @param keylen The length of the input key (octets) @param num_rounds The requested number of rounds (0==default) @param skey [out] The destination of the scheduled key @return CRYPT_OK if successful */ - int (*setup)(const unsigned char *key, - int keylen, - int num_rounds, + int (*setup)(const unsigned char *key, + int keylen, + int num_rounds, symmetric_key *skey); /** Encrypt a block @@ -5794,8 +5794,8 @@ struct ltc_cipher_descriptor { @param skey The scheduled key @return CRYPT_OK if successful */ - int (*ecb_encrypt)(const unsigned char *pt, - unsigned char *ct, + int (*ecb_encrypt)(const unsigned char *pt, + unsigned char *ct, symmetric_key *skey); /** Decrypt a block @@ -5804,54 +5804,54 @@ struct ltc_cipher_descriptor { @param skey The scheduled key @return CRYPT_OK if successful */ - int (*ecb_decrypt)(const unsigned char *ct, - unsigned char *pt, + int (*ecb_decrypt)(const unsigned char *ct, + unsigned char *pt, symmetric_key *skey); /** Test the block cipher - @return CRYPT_OK if successful, + @return CRYPT_OK if successful, CRYPT_NOP if self-testing has been disabled */ int (*test)(void); - /** Terminate the context + /** Terminate the context @param skey The scheduled key */ - void (*done)(symmetric_key *skey); + void (*done)(symmetric_key *skey); /** Determine a key size - @param keysize [in/out] The size of the key desired + @param keysize [in/out] The size of the key desired The suggested size @return CRYPT_OK if successful */ int (*keysize)(int *keysize); /** Accelerators **/ - /** Accelerated ECB encryption + /** Accelerated ECB encryption @param pt Plaintext @param ct Ciphertext @param blocks The number of complete blocks to process @param skey The scheduled key context @return CRYPT_OK if successful */ - int (*accel_ecb_encrypt)(const unsigned char *pt, - unsigned char *ct, - unsigned long blocks, + int (*accel_ecb_encrypt)(const unsigned char *pt, + unsigned char *ct, + unsigned long blocks, symmetric_key *skey); - /** Accelerated ECB decryption + /** Accelerated ECB decryption @param pt Plaintext @param ct Ciphertext @param blocks The number of complete blocks to process @param skey The scheduled key context @return CRYPT_OK if successful */ - int (*accel_ecb_decrypt)(const unsigned char *ct, - unsigned char *pt, - unsigned long blocks, + int (*accel_ecb_decrypt)(const unsigned char *ct, + unsigned char *pt, + unsigned long blocks, symmetric_key *skey); - /** Accelerated CBC encryption + /** Accelerated CBC encryption @param pt Plaintext @param ct Ciphertext @param blocks The number of complete blocks to process @@ -5859,13 +5859,13 @@ struct ltc_cipher_descriptor { @param skey The scheduled key context @return CRYPT_OK if successful */ - int (*accel_cbc_encrypt)(const unsigned char *pt, - unsigned char *ct, - unsigned long blocks, - unsigned char *IV, + int (*accel_cbc_encrypt)(const unsigned char *pt, + unsigned char *ct, + unsigned long blocks, + unsigned char *IV, symmetric_key *skey); - /** Accelerated CBC decryption + /** Accelerated CBC decryption @param pt Plaintext @param ct Ciphertext @param blocks The number of complete blocks to process @@ -5873,13 +5873,13 @@ struct ltc_cipher_descriptor { @param skey The scheduled key context @return CRYPT_OK if successful */ - int (*accel_cbc_decrypt)(const unsigned char *ct, - unsigned char *pt, - unsigned long blocks, - unsigned char *IV, + int (*accel_cbc_decrypt)(const unsigned char *ct, + unsigned char *pt, + unsigned long blocks, + unsigned char *IV, symmetric_key *skey); - /** Accelerated CTR encryption + /** Accelerated CTR encryption @param pt Plaintext @param ct Ciphertext @param blocks The number of complete blocks to process @@ -5888,14 +5888,14 @@ struct ltc_cipher_descriptor { @param skey The scheduled key context @return CRYPT_OK if successful */ - int (*accel_ctr_encrypt)(const unsigned char *pt, - unsigned char *ct, - unsigned long blocks, - unsigned char *IV, - int mode, + int (*accel_ctr_encrypt)(const unsigned char *pt, + unsigned char *ct, + unsigned long blocks, + unsigned char *IV, + int mode, symmetric_key *skey); - /** Accelerated LRW + /** Accelerated LRW @param pt Plaintext @param ct Ciphertext @param blocks The number of complete blocks to process @@ -5904,14 +5904,14 @@ struct ltc_cipher_descriptor { @param skey The scheduled key context @return CRYPT_OK if successful */ - int (*accel_lrw_encrypt)(const unsigned char *pt, - unsigned char *ct, - unsigned long blocks, - unsigned char *IV, - const unsigned char *tweak, + int (*accel_lrw_encrypt)(const unsigned char *pt, + unsigned char *ct, + unsigned long blocks, + unsigned char *IV, + const unsigned char *tweak, symmetric_key *skey); - /** Accelerated LRW + /** Accelerated LRW @param ct Ciphertext @param pt Plaintext @param blocks The number of complete blocks to process @@ -5920,11 +5920,11 @@ struct ltc_cipher_descriptor { @param skey The scheduled key context @return CRYPT_OK if successful */ - int (*accel_lrw_decrypt)(const unsigned char *ct, - unsigned char *pt, - unsigned long blocks, - unsigned char *IV, - const unsigned char *tweak, + int (*accel_lrw_decrypt)(const unsigned char *ct, + unsigned char *pt, + unsigned long blocks, + unsigned char *IV, + const unsigned char *tweak, symmetric_key *skey); /** Accelerated CCM packet (one-shot) @@ -5939,7 +5939,7 @@ struct ltc_cipher_descriptor { @param ptlen The length of the plaintext (octets) @param ct [out] The ciphertext @param tag [out] The destination tag - @param taglen [in/out] The max size and resulting size + @param taglen [in/out] The max size and resulting size of the authentication tag @param direction Encrypt or Decrypt direction (0 or 1) @return CRYPT_OK if successful @@ -5957,7 +5957,7 @@ struct ltc_cipher_descriptor { /** Accelerated GCM packet (one shot) @param key The secret key @param keylen The length of the secret key - @param IV The initial vector + @param IV The initial vector @param IVlen The length of the initial vector @param adata The additional authentication data (header) @param adatalen The length of the adata @@ -5974,14 +5974,14 @@ struct ltc_cipher_descriptor { const unsigned char *IV, unsigned long IVlen, const unsigned char *adata, unsigned long adatalen, unsigned char *pt, unsigned long ptlen, - unsigned char *ct, + unsigned char *ct, unsigned char *tag, unsigned long *taglen, int direction); - /** Accelerated one shot OMAC + /** Accelerated one shot OMAC @param key The secret key - @param keylen The key length (octets) - @param in The message + @param keylen The key length (octets) + @param in The message @param inlen Length of message (octets) @param out [out] Destination for tag @param outlen [in/out] Initial and final size of out @@ -5992,10 +5992,10 @@ struct ltc_cipher_descriptor { const unsigned char *in, unsigned long inlen, unsigned char *out, unsigned long *outlen); - /** Accelerated one shot XCBC + /** Accelerated one shot XCBC @param key The secret key - @param keylen The key length (octets) - @param in The message + @param keylen The key length (octets) + @param in The message @param inlen Length of message (octets) @param out [out] Destination for tag @param outlen [in/out] Initial and final size of out @@ -6006,10 +6006,10 @@ struct ltc_cipher_descriptor { const unsigned char *in, unsigned long inlen, unsigned char *out, unsigned long *outlen); - /** Accelerated one shot F9 + /** Accelerated one shot F9 @param key The secret key - @param keylen The key length (octets) - @param in The message + @param keylen The key length (octets) + @param in The message @param inlen Length of message (octets) @param out [out] Destination for tag @param outlen [in/out] Initial and final size of out @@ -6051,7 +6051,7 @@ Inside the \textit{symmetric\_key} union there is a \textit{void *data} which yo ones provided. Just make sure in your \textit{done()} function that you free the allocated memory. \subsection{Single block ECB} -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 +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 must make sure you do not overwrite the output before you are finished with the input. \subsection{Testing} @@ -6059,7 +6059,7 @@ The test() function is used to self--test the \textit{device}. It takes no argu \textbf{CRYPT\_NOP} to indicate that no testing was performed. \subsection{Key Sizing} -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 +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 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 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 cannot be mapped to a valid key size for the cipher. @@ -6072,15 +6072,15 @@ it is not supported. In those cases the software defaults are used (using the s 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 through the accel\_ecb\_encrypt and accel\_ecb\_decrypt pointers. The \textit{blocks} count is the number of complete blocks to process. -\subsubsection{Accelerated CBC} +\subsubsection{Accelerated CBC} These two functions are meant for accelerated CBC encryption. These functions are accessed through the accel\_cbc\_encrypt and accel\_cbc\_decrypt pointers. The \textit{blocks} value is the number of complete blocks to process. The \textit{IV} is the CBC initial vector. It is an input upon calling this function and must be -updated by the function before returning. +updated by the function before returning. \subsubsection{Accelerated CTR} This function is meant for accelerated CTR encryption. It is accessible through the accel\_ctr\_encrypt pointer. The \textit{blocks} value is the number of complete blocks to process. The \textit{IV} is the CTR counter vector. It is an input upon calling this function and must be -updated by the function before returning. The \textit{mode} value indicates whether the counter is big (mode = CTR\_COUNTER\_BIG\_ENDIAN) or +updated by the function before returning. The \textit{mode} value indicates whether the counter is big (mode = CTR\_COUNTER\_BIG\_ENDIAN) or little (mode = CTR\_COUNTER\_LITTLE\_ENDIAN) endian. 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 @@ -6092,9 +6092,9 @@ called if the following conditions are met. \item The remaining length of the input to process is greater than or equal to the block size. \end{enumerate} -The \textit{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 -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 -buffer provided) before encrypting it to create the pad. +The \textit{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 +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 +buffer provided) before encrypting it to create the pad. The accelerator will only be used to encrypt whole blocks. Partial blocks are always handled in software. @@ -6105,14 +6105,14 @@ to use accelerators for LRW. While both encrypt and decrypt accelerators are not required it is suggested as it makes lrw\_setiv() more efficient. -Note that calling lrw\_done() will only invoke the cipher\_descriptor[].done() function on the \textit{symmetric\_key} parameter of the LRW state. That means +Note that calling lrw\_done() will only invoke the cipher\_descriptor[].done() function on the \textit{symmetric\_key} parameter of the LRW state. That means 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 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 free them. \subsubsection{Accelerated CCM} 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 -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 +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 function MUST support both key passing methods. \begin{center} @@ -6137,11 +6137,11 @@ be called prior to this. This function must handle scheduling the key provided \subsubsection{Accelerated OMAC} \index{omac\_memory()} -This function is meant to perform an optimized OMAC1 (CMAC) message authentication code computation when the user calls omac\_memory(). +This function is meant to perform an optimized OMAC1 (CMAC) message authentication code computation when the user calls omac\_memory(). \subsubsection{Accelerated XCBC-MAC} \index{xcbc\_memory()} -This function is meant to perform an optimized XCBC-MAC message authentication code computation when the user calls xcbc\_memory(). +This function is meant to perform an optimized XCBC-MAC message authentication code computation when the user calls xcbc\_memory(). \subsubsection{Accelerated F9} \index{f9\_memory()} @@ -6179,14 +6179,14 @@ struct ltc_hash_descriptor { */ int (*init)(hash_state *hash); - /** Process a block of data + /** Process a block of data @param hash The hash state @param in The data to hash @param inlen The length of the data (octets) @return CRYPT_OK if successful */ - int (*process)( hash_state *hash, - const unsigned char *in, + int (*process)( hash_state *hash, + const unsigned char *in, unsigned long inlen); /** Produce the digest and store it @@ -6194,24 +6194,24 @@ struct ltc_hash_descriptor { @param out [out] The destination of the digest @return CRYPT_OK if successful */ - int (*done)( hash_state *hash, + int (*done)( hash_state *hash, unsigned char *out); /** Self-test - @return CRYPT_OK if successful, + @return CRYPT_OK if successful, CRYPT_NOP if self-tests have been disabled */ int (*test)(void); - /* accelerated hmac callback: if you need to-do - multiple packets just use the generic hmac_memory - and provide a hash callback + /* accelerated hmac callback: if you need to-do + multiple packets just use the generic hmac_memory + and provide a hash callback */ - int (*hmac_block)(const unsigned char *key, + int (*hmac_block)(const unsigned char *key, unsigned long keylen, - const unsigned char *in, - unsigned long inlen, - unsigned char *out, + const unsigned char *in, + unsigned long inlen, + unsigned char *out, unsigned long *outlen); }; \end{verbatim} @@ -6274,8 +6274,8 @@ struct ltc_prng_descriptor { @param prng The PRNG state @return CRYPT_OK if successful */ - int (*add_entropy)(const unsigned char *in, - unsigned long inlen, + int (*add_entropy)(const unsigned char *in, + unsigned long inlen, prng_state *prng); /** Ready a PRNG state to read from @@ -6290,8 +6290,8 @@ struct ltc_prng_descriptor { @param prng The PRNG state to read from @return Number of octets read */ - unsigned long (*read)(unsigned char *out, - unsigned long outlen, + unsigned long (*read)(unsigned char *out, + unsigned long outlen, prng_state *prng); /** Terminate a PRNG state @@ -6300,14 +6300,14 @@ struct ltc_prng_descriptor { */ int (*done)(prng_state *prng); - /** Export a PRNG state + /** Export a PRNG state @param out [out] The destination for the state @param outlen [in/out] The max size and resulting size @param prng The PRNG to export @return CRYPT_OK if successful */ - int (*pexport)(unsigned char *out, - unsigned long *outlen, + int (*pexport)(unsigned char *out, + unsigned long *outlen, prng_state *prng); /** Import a PRNG state @@ -6316,12 +6316,12 @@ struct ltc_prng_descriptor { @param prng The PRNG to initialize/import @return CRYPT_OK if successful */ - int (*pimport)(const unsigned char *in, - unsigned long inlen, + int (*pimport)(const unsigned char *in, + unsigned long inlen, prng_state *prng); /** Self-test the PRNG - @return CRYPT_OK if successful, + @return CRYPT_OK if successful, CRYPT_NOP if self-testing has been disabled */ int (*test)(void); @@ -6346,7 +6346,7 @@ This function makes the PRNG ready to read from by processing the entropy added. on the specific PRNG used. \subsection{Read} -Read from the PRNG and return the number of bytes read. This function does not have to fill the buffer but it is best +Read from the PRNG and return the number of bytes read. This function does not have to fill the buffer but it is best if it does as many protocols do not retry reads and will fail on the first try. \subsection{Done} @@ -6377,15 +6377,15 @@ typedef struct { @return CRYPT_OK on success */ int (*init)(void **a); - - /** init copy + + /** init copy @param dst The number to initialize and write to @param src The number to copy from @return CRYPT_OK on success */ int (*init_copy)(void **dst, void *src); - /** deinit + /** deinit @param a The number to free @return CRYPT_OK on success */ @@ -6393,29 +6393,29 @@ typedef struct { /* ---- data movement ---- */ - /** copy + /** copy @param src The number to copy from - @param dst The number to write to + @param dst The number to write to @return CRYPT_OK on success */ int (*copy)(void *src, void *dst); /* ---- trivial low level functions ---- */ - /** set small constant + /** set small constant @param a Number to write to - @param n Source upto bits_per_digit (meant for small constants) + @param n Source upto bits_per_digit (meant for small constants) @return CRYPT_OK on success */ int (*set_int)(void *a, unsigned long n); - /** get small constant + /** get small constant @param a Small number to read @return The lower bits_per_digit of the integer (unsigned) */ unsigned long (*get_int)(void *a); - /** get digit n + /** get digit n @param a The number to read from @param n The number of the digit to fetch @return The bits_per_digit sized n'th digit of a @@ -6431,17 +6431,17 @@ typedef struct { /** compare two integers @param a The left side integer @param b The right side integer - @return LTC_MP_LT if a < b, - LTC_MP_GT if a > b and + @return LTC_MP_LT if a < b, + LTC_MP_GT if a > b and LTC_MP_EQ otherwise. (signed comparison) */ int (*compare)(void *a, void *b); - /** compare against int + /** compare against int @param a The left side integer @param b The right side integer (upto bits_per_digit) - @return LTC_MP_LT if a < b, - LTC_MP_GT if a > b and + @return LTC_MP_LT if a < b, + LTC_MP_GT if a > b and LTC_MP_EQ otherwise. (signed comparison) */ int (*compare_d)(void *a, unsigned long n); @@ -6452,7 +6452,7 @@ typedef struct { */ int (*count_bits)(void * a); - /** Count the number of LSB bits which are zero + /** Count the number of LSB bits which are zero @param a The integer to count @return The number of contiguous zero LSB bits */ @@ -6466,8 +6466,8 @@ typedef struct { int (*twoexpt)(void *a , int n); /* ---- radix conversions ---- */ - - /** read ascii string + + /** read ascii string @param a The integer to store into @param str The string to read @param radix The radix the integer has been represented in (2-64) @@ -6483,13 +6483,13 @@ typedef struct { */ int (*write_radix)(void *a, char *str, int radix); - /** get size as unsigned char string + /** get size as unsigned char string @param a The integer to get the size @return The length of the integer in octets */ unsigned long (*unsigned_size)(void *a); - /** store an integer as an array of octets + /** store an integer as an array of octets @param src The integer to store @param dst The buffer to store the integer in @return CRYPT_OK on success @@ -6498,17 +6498,17 @@ typedef struct { /** read an array of octets and store as integer @param dst The integer to load - @param src The array of octets - @param len The number of octets + @param src The array of octets + @param len The number of octets @return CRYPT_OK on success */ - int (*unsigned_read)( void *dst, - unsigned char *src, + int (*unsigned_read)( void *dst, + unsigned char *src, unsigned long len); /* ---- basic math ---- */ - /** add two integers + /** add two integers @param a The first source integer @param b The second source integer @param c The destination of "a + b" @@ -6516,16 +6516,16 @@ typedef struct { */ int (*add)(void *a, void *b, void *c); - /** add two integers + /** add two integers @param a The first source integer - @param b The second source integer + @param b The second source integer (single digit of upto bits_per_digit in length) @param c The destination of "a + b" @return CRYPT_OK on success */ int (*addi)(void *a, unsigned long b, void *c); - /** subtract two integers + /** subtract two integers @param a The first source integer @param b The second source integer @param c The destination of "a - b" @@ -6533,27 +6533,27 @@ typedef struct { */ int (*sub)(void *a, void *b, void *c); - /** subtract two integers + /** subtract two integers @param a The first source integer - @param b The second source integer + @param b The second source integer (single digit of upto bits_per_digit in length) @param c The destination of "a - b" @return CRYPT_OK on success */ int (*subi)(void *a, unsigned long b, void *c); - /** multiply two integers + /** multiply two integers @param a The first source integer - @param b The second source integer + @param b The second source integer (single digit of upto bits_per_digit in length) @param c The destination of "a * b" @return CRYPT_OK on success */ int (*mul)(void *a, void *b, void *c); - /** multiply two integers + /** multiply two integers @param a The first source integer - @param b The second source integer + @param b The second source integer (single digit of upto bits_per_digit in length) @param c The destination of "a * b" @return CRYPT_OK on success @@ -6576,9 +6576,9 @@ typedef struct { */ int (*div)(void *a, void *b, void *c, void *d); - /** divide by two + /** divide by two @param a The integer to divide (shift right) - @param b The destination + @param b The destination @return CRYPT_OK on success */ int (*div_2)(void *a, void *b); @@ -6591,7 +6591,7 @@ typedef struct { */ int (*modi)(void *a, unsigned long b, unsigned long *c); - /** gcd + /** gcd @param a The first integer @param b The second integer @param c The destination for (a, b) @@ -6599,7 +6599,7 @@ typedef struct { */ int (*gcd)(void *a, void *b, void *c); - /** lcm + /** lcm @param a The first integer @param b The second integer @param c The destination for [a, b] @@ -6609,7 +6609,7 @@ typedef struct { /** Modular multiplication @param a The first source - @param b The second source + @param b The second source @param c The modulus @param d The destination (a*b mod c) @return CRYPT_OK on success @@ -6626,7 +6626,7 @@ typedef struct { /** Modular inversion @param a The value to invert - @param b The modulus + @param b The modulus @param c The destination (1/a mod b) @return CRYPT_OK on success */ @@ -6635,13 +6635,13 @@ typedef struct { /* ---- reduction ---- */ /** setup Montgomery - @param a The modulus - @param b The destination for the reduction digit + @param a The modulus + @param b The destination for the reduction digit @return CRYPT_OK on success */ int (*montgomery_setup)(void *a, void **b); - /** get normalization value + /** get normalization value @param a The destination for the normalization value @param b The modulus @return CRYPT_OK on success @@ -6659,7 +6659,7 @@ typedef struct { /** clean up (frees memory) @param a The value "b" from montgomery_setup() @return CRYPT_OK on success - */ + */ void (*montgomery_deinit)(void *a); /* ---- exponentiation ---- */ @@ -6685,19 +6685,19 @@ typedef struct { /** ECC GF(p) point multiplication (from the NIST curves) @param k The integer to multiply the point by @param G The point to multiply - @param R The destination for kG + @param R The destination for kG @param modulus The modulus for the field - @param map Boolean indicated whether to map back to affine or not + @param map Boolean indicated whether to map back to affine or not (can be ignored if you work in affine only) @return CRYPT_OK on success */ - int (*ecc_ptmul)( void *k, - ecc_point *G, - ecc_point *R, - void *modulus, + int (*ecc_ptmul)( void *k, + ecc_point *G, + ecc_point *R, + void *modulus, int map); - /** ECC GF(p) point addition + /** ECC GF(p) point addition @param P The first point @param Q The second point @param R The destination of P + Q @@ -6705,32 +6705,32 @@ typedef struct { @param mp The "b" value from montgomery_setup() @return CRYPT_OK on success */ - int (*ecc_ptadd)(ecc_point *P, - ecc_point *Q, - ecc_point *R, - void *modulus, + int (*ecc_ptadd)(ecc_point *P, + ecc_point *Q, + ecc_point *R, + void *modulus, void *mp); - /** ECC GF(p) point double + /** ECC GF(p) point double @param P The first point @param R The destination of 2P @param modulus The modulus @param mp The "b" value from montgomery_setup() @return CRYPT_OK on success */ - int (*ecc_ptdbl)(ecc_point *P, - ecc_point *R, - void *modulus, + int (*ecc_ptdbl)(ecc_point *P, + ecc_point *R, + void *modulus, void *mp); - /** ECC mapping from projective to affine, + /** ECC mapping from projective to affine, currently uses (x,y,z) => (x/z^2, y/z^3, 1) @param P The point to map @param modulus The modulus @param mp The "b" value from montgomery_setup() @return CRYPT_OK on success - @remark The mapping can be different but keep in mind a - ecc_point only has three integers (x,y,z) so if + @remark The mapping can be different but keep in mind a + ecc_point only has three integers (x,y,z) so if you use a different mapping you have to make it fit. */ int (*ecc_map)(ecc_point *P, void *modulus, void *mp); @@ -6741,9 +6741,9 @@ typedef struct { @param B Second point to multiply @param kB What to multiple B by @param C [out] Destination point (can overlap with A or B) - @param modulus Modulus for curve + @param modulus Modulus for curve @return CRYPT_OK on success - */ + */ int (*ecc_mul2add)(ecc_point *A, void *kA, ecc_point *B, void *kB, ecc_point *C, @@ -6752,29 +6752,29 @@ typedef struct { /* ---- (optional) rsa optimized math (for internal CRT) ---- */ - /** RSA Key Generation + /** RSA Key Generation @param prng An active PRNG state @param wprng The index of the PRNG desired @param size The size of the key in octets - @param e The "e" value (public key). + @param e The "e" value (public key). e==65537 is a good choice @param key [out] Destination of a newly created private key pair @return CRYPT_OK if successful, upon error all allocated ram is freed */ - int (*rsa_keygen)(prng_state *prng, - int wprng, - int size, - long e, + int (*rsa_keygen)(prng_state *prng, + int wprng, + int size, + long e, rsa_key *key); /** RSA exponentiation @param in The octet array representing the base @param inlen The length of the input @param out The destination (to be stored in an octet array format) - @param outlen The length of the output buffer and the resulting size + @param outlen The length of the output buffer and the resulting size (zero padded to the size of the modulus) @param which PK_PUBLIC for public RSA and PK_PRIVATE for private RSA - @param key The RSA key to use + @param key The RSA key to use @return CRYPT_OK on success */ int (*rsa_me)(const unsigned char *in, unsigned long inlen, @@ -6789,23 +6789,23 @@ Most of the functions are fairly straightforward and do not need documentation. \subsection{Conventions} All \textit{bignums} are accessed through an opaque \textit{void *} data type. You must internally cast the pointer if you need to access members of your bignum structure. During -the init calls a \textit{void **} will be passed where you allocate your structure and set the pointer then initialize the number to zero. During the deinit calls you must +the init calls a \textit{void **} will be passed where you allocate your structure and set the pointer then initialize the number to zero. During the deinit calls you must free the bignum as well as the structure you allocated to place it in. -All functions except the Montgomery reductions work from left to right with the arguments. For example, mul(a, b, c) computes $c \leftarrow ab$. +All functions except the Montgomery reductions work from left to right with the arguments. For example, mul(a, b, c) computes $c \leftarrow ab$. All functions (except where noted otherwise) return \textbf{CRYPT\_OK} to signify a successful operation. All error codes must be valid LibTomCrypt error codes. The digit routines (including functions with the \textit{i} suffix) use a \textit{unsigned long} to represent the digit. If your internal digit is larger than this you must then partition your digits. Normally this does not matter as \textit{unsigned long} will be the same size as your register size. Note that if your digit is smaller -than an \textit{unsigned long} that is also acceptable as the \textit{bits\_per\_digit} parameter will specify this. +than an \textit{unsigned long} that is also acceptable as the \textit{bits\_per\_digit} parameter will specify this. \subsection{ECC Functions} -The ECC system in LibTomCrypt is based off of the NIST recommended curves over $GF(p)$ and is used to implement EC-DSA and EC-DH. The ECC functions work with +The ECC system in LibTomCrypt is based off of the NIST recommended curves over $GF(p)$ and is used to implement EC-DSA and EC-DH. The ECC functions work with the \textbf{ecc\_point} structure and assume the points are stored in Jacobian projective format. \begin{verbatim} -/** A point on a ECC curve, stored in Jacobian format such +/** A point on a ECC curve, stored in Jacobian format such that (x,y,z) => (x/z^2, y/z^3, 1) when interpreted as affine */ typedef struct { /** The x co-ordinate */ @@ -6822,21 +6822,21 @@ over how the ECC math will be implemented. Out of the box you only have three p could point to anything you want. The only further exception is the export functions which expects the values to be in affine format. \subsubsection{Point Multiply} -This will multiply the point $G$ by the scalar $k$ and store the result in the point $R$. The value should be mapped to affine only if $map$ is set to one. +This will multiply the point $G$ by the scalar $k$ and store the result in the point $R$. The value should be mapped to affine only if $map$ is set to one. \subsubsection{Point Addition} This will add the point $P$ to the point $Q$ and store it in the point $R$. The $mp$ parameter is the \textit{b} value from the montgomery\_setup() call. The input points -may be in either affine (with $z = 1$) or projective format and the output point is always projective. +may be in either affine (with $z = 1$) or projective format and the output point is always projective. \subsubsection{Point Mapping} -This will map the point $P$ back from projective to affine. The output point $P$ must be of the form $(x, y, 1)$. +This will map the point $P$ back from projective to affine. The output point $P$ must be of the form $(x, y, 1)$. \subsubsection{Shamir's Trick} \index{Shamir's Trick} \index{ltc\_ecc\_mul2add()} To accelerate EC--DSA verification the library provides a built--in function called ltc\_ecc\_mul2add(). This performs two point multiplications and an addition in roughly the time of one point multiplication. It is called from ecc\_verify\_hash() if an accelerator is not present. The acclerator function must allow the points to -overlap (e.g., $A \leftarrow k_1A + k_2B$) and must return the final point in affine format. +overlap (e.g., $A \leftarrow k_1A + k_2B$) and must return the final point in affine format. \subsection{RSA Functions} @@ -6849,19 +6849,19 @@ typedef struct Rsa_key { /** Type of key, PK_PRIVATE or PK_PUBLIC */ int type; /** The public exponent */ - void *e; + void *e; /** The private exponent */ - void *d; + void *d; /** The modulus */ - void *N; + void *N; /** The p factor of N */ - void *p; + void *p; /** The q factor of N */ - void *q; + void *q; /** The 1/q mod p CRT param */ - void *qP; + void *qP; /** The d mod (p - 1) CRT param */ - void *dP; + void *dP; /** The d mod (q - 1) CRT param */ void *dQ; } rsa_key; From df8814dfefd7cd053eccc30b272a6b8446e2869d Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Sat, 30 Aug 2014 15:21:40 +0200 Subject: [PATCH 07/28] some minor corrections/improvements --- crypt.tex | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/crypt.tex b/crypt.tex index 6f62f5c..04547c3 100644 --- a/crypt.tex +++ b/crypt.tex @@ -3566,7 +3566,8 @@ If the RSA decoded data is not a valid PSS message, or if the PKCS decoded hash value, \textit{res} is set to $0$. Otherwise, if the function succeeds, and signature is valid \textit{res} is set to $1$. The \textit{padding} parameter must be set to \textbf{LTC\_PKCS\_1\_V1\_5} to perform a v1.5 verification. Otherwise, it must be set to -\textbf{LTC\_PKCS\_1\_PSS} to perform a v2.1 verification. When performing a v1.5 verification the \textit{hash\_idx} parameter is ignored. +\textbf{LTC\_PKCS\_1\_PSS} to perform a v2.1 verification. When performing a v1.5 verification the \textit{hash\_idx} and \textit{saltlen} parameters are ignored. + \mysection{RSA Encryption Example} \begin{small} @@ -4563,7 +4564,7 @@ The SEQUENCE data type is a collection of other ASN.1 data types encapsulated wi 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 with the following function. -\index{der\_encode\_sequence()} +\index{der\_encode\_sequence()}\index{LTC\_ASN1\_EOL} \begin{verbatim} int der_encode_sequence(ltc_asn1_list *list, unsigned long inlen, @@ -4617,7 +4618,7 @@ int der_length_sequence(ltc_asn1_list *list, This will get the encoding size for the given \textit{list} of length \textit{inlen} and store it in \textit{outlen}. -\subsubsection{SEQUENCE Multiple Argument Lists} +\subsubsection{SEQUENCE Multiple Argument Lists}\index{LTC\_ASN1\_EOL} For small or simple sequences an encoding or decoding can be performed with one of the following two functions. @@ -4966,7 +4967,7 @@ will have the \textit{used} flag set to non--zero to reflect it was the data typ \subsection{ASN.1 Flexi Decoder} The ASN.1 \textit{flexi} decoder allows the developer to decode arbitrary ASN.1 DER packets (provided they use data types LibTomCrypt supports) without first knowing -the structure of the data. Where der\_decode \_sequence() requires the developer to specify the data types to decode in advance the flexi decoder is entirely +the structure of the data. Where der\_decode\_sequence() requires the developer to specify the data types to decode in advance the flexi decoder is entirely free form. The flexi decoder uses the same \textit{ltc\_asn1\_list} but instead of being stored in an array it uses the linked list pointers \textit{prev}, \textit{next}, \textit{parent} From 331f76c0ec007f8566cc7299b865d4ea4667609c Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Sat, 30 Aug 2014 17:18:58 +0200 Subject: [PATCH 08/28] add documentation of the newly added ASN.1 types --- crypt.tex | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 54 insertions(+), 1 deletion(-) diff --git a/crypt.tex b/crypt.tex index 04547c3..04abf6e 100644 --- a/crypt.tex +++ b/crypt.tex @@ -4550,6 +4550,9 @@ LTC_SET_ASN1(sequence, x++, LTC_ASN1_NULL, NULL, 0); \hline LTC\_ASN1\_SET & SET \\ \hline LTC\_ASN1\_SETOF & SET OF \\ \hline LTC\_ASN1\_CHOICE & CHOICE \\ +\hline LTC\_ASN1\_RAW\_BIT\_STRING & BIT STRING (one octet per char) \\ +\hline LTC\_ASN1\_TELETEX\_STRING & TELETEX STRING (one octet per char) \\ +\hline LTC\_ASN1\_CONSTRUCTED & A constructed type that is not SEQUENCE or SET \\ \hline \end{tabular} \caption{List of ASN.1 Supported Types} @@ -4788,6 +4791,30 @@ int der_length_bit_string(unsigned long nbits, 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 interpreted as a one bit, and a zero value a zero bit. +\subsection{ASN.1 RAW BIT STRING} + +\index{der\_encode\_raw\_bit\_string()}\index{der\_decode\_raw\_bit\_string()} +\begin{verbatim} +int der_encode_raw_bit_string(const unsigned char *in, + unsigned long inlen, + unsigned char *out, + unsigned long *outlen); + +int der_decode_raw_bit_string(const unsigned char *in, + unsigned long inlen, + unsigned char *out, + unsigned long *outlen); +\end{verbatim} + +These will encode or decode a BIT STRING data type. +The bits are passed in (or read out) using one \textbf{unsigned char} per 8 bit. + +This function differs from the normal BIT STRING, as it can be used to directly +process raw binary data and store it to resp. read it from an ASN.1 BIT STRING +data type. + +The length function is the same as for the normal BIT STRING \textit{der\_length\_bit\_string()}. + \subsection{ASN.1 OCTET STRING} \index{der\_encode\_octet\_string()}\index{der\_decode\_octet\_string()}\index{der\_length\_octet\_string()} @@ -4854,6 +4881,26 @@ to numerical conversions based on the conventions of the compiler being used. F say a SPARC machine. Internally, these functions have a table of literal characters and their numerical ASCII values. This provides a stable conversion provided that the build platform honours the run--time platforms character conventions. +\subsection{ASN.1 TELETEX STRING} + +\index{der\_decode\_teletex\_string()}\index{der\_length\_teletex\_string()} +\begin{verbatim} +int der_decode_teletex_string(const unsigned char *in, + unsigned long inlen, + unsigned char *out, + unsigned long *outlen); + +int der_length_teletex_string(const unsigned char *octets, + unsigned long noctets, + unsigned long *outlen); +\end{verbatim} + +These will decode a TELETEX STRING. +The characters are read in individual \textbf{char} elements. +The internal structure is similar to that of the IA5 STRING implementation, to +be able to provide a stable conversion independent of the build-- and run--time +platform. + \subsection{ASN.1 PRINTABLE STRING} \index{der\_encode\_printable\_string()}\index{der\_decode\_printable\_string()}\index{der\_length\_printable\_string()} @@ -4977,7 +5024,7 @@ encoded in a SEQUENCE are stored as a child element. When a SEQUENCE or SET has been encountered a SEQUENCE (or SET resp.) item will be added as a sibling (e.g. list.type == LTC\_ASN1\_SEQUENCE) and the child pointer points to a new list of items contained within the object. -\index{der\_decode\_sequence\_flexi()} +\index{der\_decode\_sequence\_flexi()}\index{LTC\_ASN1\_CONSTRUCTED} \begin{verbatim} int der_decode_sequence_flexi(const unsigned char *in, unsigned long *inlen, @@ -4996,6 +5043,12 @@ An invalid decoding will terminate the process, and free the allocated memory au have to convert the list by first storing all of the siblings in an array then storing all the children as sub-lists of a sequence using the \textit{.data} pointer. Currently no function in LibTomCrypt provides this ability. +\textbf{Note 2:} the flexi decoder will also decode arbitrary constructed types +other than SEQUENCE and SET. The \textit{type} field will be set to +\textbf{LTC\_ASN1\_CONSTRUCTED} and the plain type that was indicated in the ASN.1 +encoding is stored in the \textit{used} field. Further decoding is done in the +same way as if it were a SEQUENCE or SET. + \subsubsection{Sample Decoding} Suppose we decode the following structure: \begin{small} From d010f195878793bd5cfc7c60409adb399d6dfa24 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Sat, 30 Aug 2014 17:19:20 +0200 Subject: [PATCH 09/28] add documentation of the new RSA API functions --- crypt.tex | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/crypt.tex b/crypt.tex index 04abf6e..4b1d9e6 100644 --- a/crypt.tex +++ b/crypt.tex @@ -3377,6 +3377,14 @@ in \textit{out} and the size of the result in \textit{outlen}. \textit{which} is Note: the output of this function is zero--padded as per PKCS \#1 specification. This allows this routine to work with PKCS \#1 padding functions properly. +\subsection{RSA Key Size} +To fetch the key size of an RSA key, use the following function: +\index{rsa\_get\_size()} +\begin{verbatim} +int rsa_get_size(rsa_key *key); +\end{verbatim} +This can be used to determine the modulus size of an RSA key. + \mysection{RSA Key Encryption} Normally RSA is used to encrypt short symmetric keys which are then used in block ciphers to encrypt a message. To facilitate encrypting short keys the following functions have been provided. @@ -3541,6 +3549,22 @@ and the extracted hash is compared against the message digest pointed to by \tex If the RSA decoded data is not a valid PSS message, or if the PSS decoded hash does not match the \textit{msghash} value, \textit{res} is set to $0$. Otherwise, if the function succeeds, and signature is valid \textit{res} is set to $1$. +\subsection{RSA Signature Salt Length} + +The v2.1 signature algorithm requires a salt length to be able to properly +encode resp. decode. To fetch the maximum possible salt length this function +is provided: + +\index{rsa\_sign\_saltlen\_get\_max()} +\begin{verbatim} +int rsa_sign_saltlen_get_max(int hash_idx, rsa_key *key); +\end{verbatim} + +As stated in the PKCS#1 RFC3447 "Typical salt lengths in octets are hLen +(the length of the output of the hash function Hash) and 0". +This function is provided to be able to use other lengths as well and to make +sure at runtime that the RSA key can handle the desired salt length. + \subsection{Extended Verification} As of v1.15, the library supports both v1.5 and v2.1 signature verification. The extended signature verification function has the following prototype: From 1367c1d685c6bb853a4f9e7e4476bd4c42af3b61 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Sun, 31 Aug 2014 17:02:07 +0200 Subject: [PATCH 10/28] fix build error --- crypt.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crypt.tex b/crypt.tex index 4b1d9e6..a805ac7 100644 --- a/crypt.tex +++ b/crypt.tex @@ -3560,7 +3560,7 @@ is provided: int rsa_sign_saltlen_get_max(int hash_idx, rsa_key *key); \end{verbatim} -As stated in the PKCS#1 RFC3447 "Typical salt lengths in octets are hLen +As stated in the PKCS\#1 RFC3447 "Typical salt lengths in octets are hLen (the length of the output of the hash function Hash) and 0". This function is provided to be able to use other lengths as well and to make sure at runtime that the RSA key can handle the desired salt length. From a5d95448e1c3196fe2c402d2cee41b611d71c54d Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Sun, 31 Aug 2014 17:57:59 +0200 Subject: [PATCH 11/28] use ulong32 resp. ulong64 in the tables of the Macros section This closes #16 --- crypt.tex | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/crypt.tex b/crypt.tex index a805ac7..c38f404 100644 --- a/crypt.tex +++ b/crypt.tex @@ -277,15 +277,15 @@ There are a few helper macros to make the coding process a bit easier. The firs \begin{small} \begin{center} \begin{tabular}{|c|c|c|} - \hline STORE32L(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $x \to y[0 \ldots 3]$ \\ - \hline STORE64L(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $x \to y[0 \ldots 7]$ \\ - \hline LOAD32L(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $y[0 \ldots 3] \to x$ \\ - \hline LOAD64L(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $y[0 \ldots 7] \to x$ \\ - \hline STORE32H(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $x \to y[3 \ldots 0]$ \\ - \hline STORE64H(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $x \to y[7 \ldots 0]$ \\ - \hline LOAD32H(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $y[3 \ldots 0] \to x$ \\ - \hline LOAD64H(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $y[7 \ldots 0] \to x$ \\ - \hline BSWAP(x) & {\bf unsigned long} x & Swap bytes \\ + \hline STORE32L(x, y) & {\bf ulong32} x, {\bf unsigned char} *y & $x \to y[0 \ldots 3]$ \\ + \hline STORE64L(x, y) & {\bf ulong64} x, {\bf unsigned char} *y & $x \to y[0 \ldots 7]$ \\ + \hline LOAD32L(x, y) & {\bf ulong32} x, {\bf unsigned char} *y & $y[0 \ldots 3] \to x$ \\ + \hline LOAD64L(x, y) & {\bf ulong64} x, {\bf unsigned char} *y & $y[0 \ldots 7] \to x$ \\ + \hline STORE32H(x, y) & {\bf ulong32} x, {\bf unsigned char} *y & $x \to y[3 \ldots 0]$ \\ + \hline STORE64H(x, y) & {\bf ulong64} x, {\bf unsigned char} *y & $x \to y[7 \ldots 0]$ \\ + \hline LOAD32H(x, y) & {\bf ulong32} x, {\bf unsigned char} *y & $y[3 \ldots 0] \to x$ \\ + \hline LOAD64H(x, y) & {\bf ulong64} x, {\bf unsigned char} *y & $y[7 \ldots 0] \to x$ \\ + \hline BSWAP(x) & {\bf ulong32} x & Swap bytes \\ \hline \end{tabular} \caption{Load And Store Macros} @@ -299,15 +299,15 @@ There are 32 and 64-bit cyclic rotations as well: \begin{small} \begin{center} \begin{tabular}{|c|c|c|} - \hline ROL(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x << y, 0 \le y \le 31$ \\ - \hline ROLc(x, y) & {\bf unsigned long} x, {\bf const unsigned long} y & $x << y, 0 \le y \le 31$ \\ - \hline ROR(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x >> y, 0 \le y \le 31$ \\ - \hline RORc(x, y) & {\bf unsigned long} x, {\bf const unsigned long} y & $x >> y, 0 \le y \le 31$ \\ + \hline ROL(x, y) & {\bf ulong32} x, {\bf ulong32} y & $x << y, 0 \le y \le 31$ \\ + \hline ROLc(x, y) & {\bf ulong32} x, {\bf const ulong32} y & $x << y, 0 \le y \le 31$ \\ + \hline ROR(x, y) & {\bf ulong32} x, {\bf ulong32} y & $x >> y, 0 \le y \le 31$ \\ + \hline RORc(x, y) & {\bf ulong32} x, {\bf const ulong32} y & $x >> y, 0 \le y \le 31$ \\ \hline && \\ - \hline ROL64(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x << y, 0 \le y \le 63$ \\ - \hline ROL64c(x, y) & {\bf unsigned long} x, {\bf const unsigned long} y & $x << y, 0 \le y \le 63$ \\ - \hline ROR64(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x >> y, 0 \le y \le 63$ \\ - \hline ROR64c(x, y) & {\bf unsigned long} x, {\bf const unsigned long} y & $x >> y, 0 \le y \le 63$ \\ + \hline ROL64(x, y) & {\bf ulong64} x, {\bf ulong64} y & $x << y, 0 \le y \le 63$ \\ + \hline ROL64c(x, y) & {\bf ulong64} x, {\bf const ulong64} y & $x << y, 0 \le y \le 63$ \\ + \hline ROR64(x, y) & {\bf ulong64} x, {\bf ulong64} y & $x >> y, 0 \le y \le 63$ \\ + \hline ROR64c(x, y) & {\bf ulong64} x, {\bf const ulong64} y & $x >> y, 0 \le y \le 63$ \\ \hline \end{tabular} \caption{Rotate Macros} From 3c8743e1025e4a937bed4e51af4dad2de6d31f1d Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Wed, 27 Aug 2014 14:39:03 +0200 Subject: [PATCH 12/28] add SHA512/t documentation --- crypt.tex | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/crypt.tex b/crypt.tex index c38f404..85e5743 100644 --- a/crypt.tex +++ b/crypt.tex @@ -2067,8 +2067,10 @@ The following hashes are provided as of this release within the LibTomCrypt libr \hline SHA-512 & sha512\_desc & 64 \\ \hline SHA-384 & sha384\_desc & 48 \\ \hline RIPEMD-320 & rmd160\_desc & 40 \\ + \hline SHA-512/256 & sha512\_256\_desc & 32 \\ \hline SHA-256 & sha256\_desc & 32 \\ \hline RIPEMD-256 & rmd160\_desc & 32 \\ + \hline SHA-512/224 & sha512\_224\_desc & 28 \\ \hline SHA-224 & sha224\_desc & 28 \\ \hline TIGER-192 & tiger\_desc & 24 \\ \hline SHA-1 & sha1\_desc & 20 \\ @@ -2144,7 +2146,7 @@ It is highly recommended that you \textbf{not} use the MD4 or MD5 hashes for the These hashes are provided for completeness and they still can be used for the purposes of password hashing or one-way accumulators (e.g. Yarrow). -The other hashes such as the SHA-1, SHA-2 (that includes SHA-512, SHA-384, SHA-256 and SHA-224) and TIGER-192 are still considered secure +The other hashes such as the SHA-1, SHA-2 (that includes SHA-512, SHA-512/384, SHA-384, SHA-512/256, SHA-256 and SHA-224) and TIGER-192 are still considered secure for all purposes you would normally use a hash for. \chapter{Message Authentication Codes} From d2047f4b61cc143807b3e1c5394be305f64b8dae Mon Sep 17 00:00:00 2001 From: Larry Bugbee Date: Sat, 30 Aug 2014 23:50:42 -0700 Subject: [PATCH 13/28] added sec 11.3, dynamic lang support --- crypt.tex | 125 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) diff --git a/crypt.tex b/crypt.tex index 85e5743..c80921e 100644 --- a/crypt.tex +++ b/crypt.tex @@ -5394,6 +5394,131 @@ to get a prime of the form $p \equiv 3\mbox{ }(\mbox{mod } 4)$. So if you want \textit{len = -128} to the function. Upon success it will return {\bf CRYPT\_OK} and \textit{N} will contain an integer which is very likely prime. +\mysection{Dynamic Language Support} +\index{Dynamic Language Support} +Various LibTomCrypt functions require that their callers define a struct +(or a union) and provide a pointer to it, or allocate sufficient memory and +provide its pointer. Programs written in C or C++ can obtain the necessary +information by simply including the appropriate header files, but dynamic +languages like Python don't understand C header files, and without assistance, +have no way to know how much memory to allocate. A similar story can be told +for certain LTC constant values. + +LTC's Dynamic Language Support provides functions that return the size of +a named struct or union, the value of a named constant, a list of all sizes +supported, and a list of all named constants supported. Two additional +functions can initialize LTM and TFM. + +To get the size of a named struct or union: +\begin{verbatim} +int crypt_get_size(const char *namein, + int *sizeout); +\end{verbatim} +$namein$ is spelled exactly as found in the C header files with "_struct" +or "_union" appended to the name. This function will return -1 if $namein$ +is not found. + +To get the value of a named constant: +\begin{verbatim} +int crypt_get_constant(const char *namein, + int *valueout); +\end{verbatim} +$namein$ is spelled exactly as found in the C header files. Again, -1 is +returned if $namein$ is not found. + +To get the names of all the supported structs, unions and constants: +\begin{verbatim} +int crypt_list_all_sizes(char *names_list, + int *names_list_size); + +int crypt_list_all_constants(char *names_list, + int *names_list_size); +\end{verbatim} +You may want to call these functions twice, first to get the amount +of memory to be allocated for the $names_list$, and a final time to +actually populate $names_list$. If $names_list$ is NULL, +$names_list_size$ will be the minimum size needed to receive the +complete $names_list$. If $names_list$ is NOT NULL, $names_list$ must +be a pointer to sufficient memory into which the $names_list$ will be +written. Also, the value in $names_list_size$ sets the upper bound of +the number of characters to be written. A -1 return value signifies +insufficient space. + +The format of the $names_list$ string is a series of $name,value$ pairs +where each name and value is separated by a comma, the pairs are separated +by newlines, and the list is null terminated. + +Calling either of these functions will initialize the respective +math library. +\begin{verbatim} +void init_LTM(void); +void init_TFM(void); +\end{verbatim} + +Here is a Python program demonstrating how to call various LTC dynamic +language support functions. +\begin{verbatim} +from ctypes import * + +# load the OSX shared/dynamic library +LIB = CDLL('libtomcrypt.dylib') + +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# print info about this library + +little = c_int() # assume False is big +word32 = c_int() # assume False is 64-bit + +LIB.crypt_get_constant('ENDIAN_LITTLE', byref(little)) +LIB.crypt_get_constant('ENDIAN_32BITWORD', byref(word32)) + +print('this lib was compiled for a %s endian %d-bit processor' + % ('little' if little else 'big', 32 if word32 else 64)) + +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# print the size of the struct named "sha256_state" + +struct_size = c_int() + +# don't forget to add the '_struct' or '_union' suffix +LIB.crypt_get_size('sha256_state_struct', byref(struct_size)) + +print('allocate %d bytes for sha256_state' % struct_size.value) + +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# print a list of all supported named constants + +list_size = c_int() + +# call with NULL to calc the min size needed for the list +LIB.crypt_list_all_constants(None, byref(list_size)) + +# allocate required space +names_list = c_buffer(list_size.value) + +# call again providing a pointer to where to write the list +LIB.crypt_list_all_constants(names_list, byref(list_size)) + +print(names_list.value) + +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# print a list of all supported named structs and unions + +list_size = c_int() + +# call with NULL to calc the min size needed for the list +LIB.crypt_list_all_sizes(None, byref(list_size)) + +# allocate required space +names_list = c_buffer(list_size.value) + +# call again providing a pointer to where to write the list +LIB.crypt_list_all_sizes(names_list, byref(list_size)) + +print(names_list.value) +\end{verbatim} + + \chapter{Programming Guidelines} \mysection{Secure Pseudo Random Number Generators} From 2a98d0a11fa528332cad669ae041c30878b7d8e3 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Mon, 29 Sep 2014 23:42:40 +0200 Subject: [PATCH 14/28] adapt dynamic language documentation to modified API and functionality --- crypt.tex | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/crypt.tex b/crypt.tex index c80921e..781b06c 100644 --- a/crypt.tex +++ b/crypt.tex @@ -5411,12 +5411,11 @@ functions can initialize LTM and TFM. To get the size of a named struct or union: \begin{verbatim} -int crypt_get_size(const char *namein, - int *sizeout); +int crypt_get_size( const char *namein, + unsigned int *sizeout); \end{verbatim} -$namein$ is spelled exactly as found in the C header files with "_struct" -or "_union" appended to the name. This function will return -1 if $namein$ -is not found. +$namein$ is spelled exactly as found in the C header files. This function will +return -1 if $namein$ is not found. To get the value of a named constant: \begin{verbatim} @@ -5428,11 +5427,11 @@ returned if $namein$ is not found. To get the names of all the supported structs, unions and constants: \begin{verbatim} -int crypt_list_all_sizes(char *names_list, - int *names_list_size); +int crypt_list_all_sizes( char *names_list, + unsigned int *names_list_size); -int crypt_list_all_constants(char *names_list, - int *names_list_size); +int crypt_list_all_constants( char *names_list, + unsigned int *names_list_size); \end{verbatim} You may want to call these functions twice, first to get the amount of memory to be allocated for the $names_list$, and a final time to From 3233e51a230d93299e29fb6f79c9d7b76048d1b5 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Thu, 9 Oct 2014 21:39:22 +0200 Subject: [PATCH 15/28] update documentation regarding RSA key import/export --- crypt.tex | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/crypt.tex b/crypt.tex index 781b06c..94a2038 100644 --- a/crypt.tex +++ b/crypt.tex @@ -3673,7 +3673,7 @@ int main(void) \mysection{RSA Key Format} The RSA key format adopted for exporting and importing keys is the PKCS \#1 format defined by the ASN.1 constructs known as -RSAPublicKey and RSAPrivateKey. Additionally, the OpenSSL key format is supported by the import function only. +RSAPublicKey and RSAPrivateKey. Additionally, the OpenSSL key format is supported as well. \subsection{RSA Key Export} To export a RSA key use the following function. @@ -3685,8 +3685,17 @@ int rsa_export(unsigned char *out, int type, rsa_key *key); \end{verbatim} -This will export the RSA key in either a RSAPublicKey or RSAPrivateKey (PKCS \#1 types) depending on the value of \textit{type}. When it is -set to \textbf{PK\_PRIVATE} the export format will be RSAPrivateKey and otherwise it will be RSAPublicKey. + +This will export the RSA key depending on the value of \textit{type}. + +The RSAPublicKey (PKCS \#1 type) format will be used for the public key, +indicated by \textbf{PK\_PUBLIC}. +The RSAPrivateKey (PKCS \#1 type) format will be used for the private key, +indicated by \textbf{PK\_PRIVATE}. + +As of v1.18 this function can also export OpenSSL-compatible formatted public RSA keys. +By OR'ing \textbf{PK\_STD} and \textbf{PK\_PUBLIC} the public key will be exported +in the SubjectPublicKeyInfo (X.509 type) format. \subsection{RSA Key Import} To import a RSA key use the following function. @@ -3702,8 +3711,7 @@ This will import the key stored in \textit{inlen} and import it to \textit{key}. function can import both RSAPublicKey and RSAPrivateKey formats. As of v1.06 this function can also import OpenSSL DER formatted public RSA keys. They are essentially encapsulated RSAPublicKeys. LibTomCrypt will -import the key, strip off the additional data (it's the preferred hash) and fill in the rsa\_key structure as if it were a native RSAPublicKey. Note that -there is no function provided to export in this format. +import the key, strip off the additional data and fill in the rsa\_key structure. \chapter{Diffie-Hellman Key Exchange} From 627aef962c2d1f9c4defd16f06c173591db41761 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Thu, 9 Oct 2014 22:39:39 +0200 Subject: [PATCH 16/28] add documentation of ASN.1 context-specific decoding --- crypt.tex | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/crypt.tex b/crypt.tex index 94a2038..99d6f07 100644 --- a/crypt.tex +++ b/crypt.tex @@ -5058,7 +5058,9 @@ encoded in a SEQUENCE are stored as a child element. When a SEQUENCE or SET has been encountered a SEQUENCE (or SET resp.) item will be added as a sibling (e.g. list.type == LTC\_ASN1\_SEQUENCE) and the child pointer points to a new list of items contained within the object. -\index{der\_decode\_sequence\_flexi()}\index{LTC\_ASN1\_CONSTRUCTED} +\index{der\_decode\_sequence\_flexi()} +\index{LTC\_ASN1\_CONSTRUCTED} +\index{LTC\_ASN1\_CONTEXT\_SPECIFIC} \begin{verbatim} int der_decode_sequence_flexi(const unsigned char *in, unsigned long *inlen, @@ -5073,16 +5075,23 @@ normally. The decoded list \textit{out} will point to the very first element of An invalid decoding will terminate the process, and free the allocated memory automatically. +As of v1.18 the flexi decoder will also decode arbitrary constructed types +other than SEQUENCE and SET. The \textit{type} field will be set to +\textbf{LTC\_ASN1\_CONSTRUCTED} and the plain identifier that was indicated in the ASN.1 +encoding is stored in the \textit{used} field. Further decoding is done in the +same way as if it were a SEQUENCE or SET. + +Also as of v1.18 the flexi decoder is capable to handle +\textit{context-specific} encodings. The \textit{type} field will be set to +\textbf{LTC\_ASN1\_CONTEXT\_SPECIFIC} and the plain identifier that was indicated +in the ASN.1 encoding is stored in the \textit{used} field. Encapsulated data +in the \textit{context-specific} encoding is copied to newly allocated memory +and is accessible through the \textit{data} field. + \textbf{Note:} the list decoded by this function is \textbf{NOT} in the correct form for der\_encode\_sequence() to use directly. You will first have to convert the list by first storing all of the siblings in an array then storing all the children as sub-lists of a sequence using the \textit{.data} pointer. Currently no function in LibTomCrypt provides this ability. -\textbf{Note 2:} the flexi decoder will also decode arbitrary constructed types -other than SEQUENCE and SET. The \textit{type} field will be set to -\textbf{LTC\_ASN1\_CONSTRUCTED} and the plain type that was indicated in the ASN.1 -encoding is stored in the \textit{used} field. Further decoding is done in the -same way as if it were a SEQUENCE or SET. - \subsubsection{Sample Decoding} Suppose we decode the following structure: \begin{small} From 6a47cb5931c407293bad4746cb166263ba92e34c Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Thu, 9 Oct 2014 22:43:30 +0200 Subject: [PATCH 17/28] describe behavior of the flexi decoder on unknown identifiers --- crypt.tex | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/crypt.tex b/crypt.tex index 99d6f07..958f52a 100644 --- a/crypt.tex +++ b/crypt.tex @@ -5075,6 +5075,13 @@ normally. The decoded list \textit{out} will point to the very first element of An invalid decoding will terminate the process, and free the allocated memory automatically. +The flexi decoder calls itself when decoding a constructed type. This leads to +a 'child process' that will terminate when it decodes an unkown/invalid +identifier and leaves an allocated but uninitialized child element. +However the parent processing will continue with a "soft-error". +This can be detected by checking for \textit{child} elements with +type \textbf{LTC\_ASN1\_EOL} after decoding. + As of v1.18 the flexi decoder will also decode arbitrary constructed types other than SEQUENCE and SET. The \textit{type} field will be set to \textbf{LTC\_ASN1\_CONSTRUCTED} and the plain identifier that was indicated in the ASN.1 From 17b961e554dd8a588bf70e585c341dae908e42b2 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Thu, 9 Oct 2014 23:09:10 +0200 Subject: [PATCH 18/28] update changes document include changes proposed by @buggywhip fix typos [skip ci] --- changes | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/changes b/changes index 4c8ef58..85e0d8c 100644 --- a/changes +++ b/changes @@ -1,17 +1,20 @@ XXX, 2014 -v1.18 -- Added Camellia block cipher +v1.18.0 + -- Added Camellia block cipher -- Thanks to Karel Miko for cotributing a bunchload of patches and additions, namely OCBv3, DSA and ECC key generation FIPS-186-4 compliance, BASE64-URL encoding, a bugfix in Camellia, - -- Larry Bugbee contributed the necessary stuff to easier include libtomcrypt - in a foreign language like python, as shown in his pyTomCrypt + -- Larry Bugbee contributed the necessary stuff to more easily call libtomcrypt + from a dynamic language like Python, as shown in his pyTomCrypt -- Nikos Mavrogiannopoulos contributed RSA blinding and export of RSA and DSA keys in OpenSSL/GnuTLS compatible format -- Patrick Pelletier contributed a smart volley of patches -- RyanC contributed HKDF including documentation (yippie) -- Added 2-key Triple-DES mode, thanks to Paul Howarth - -- Christopher Braun contributed some patches and additions to ASN.1/DER - -- Applied some patches from the OLPC project regarding PKCS#1 and preventing the + -- Christopher Brown contributed some patches and additions to ASN.1/DER + -- Pascal Brand of STMicroelectronics contributed patches regarding the + XTS mode and RSA private key operations with keys without CRT parameters + -- Applied some patches from the OLPC project regarding PKCS#1 and preventing the hash algorithms from overflowing -- Fixed the Bleichbacher Signature attack in PKCS#1 v1.5 EMSA, thanks to Alex Dent -- Add PKCS#1 testvectors from RSA @@ -21,6 +24,7 @@ v1.18 -- Added Camellia block cipher -- Documentation (crypt.pdf) is now built deterministically, thanks to Michael Stapelberg -- Removed all compiler warnings -- Improved/extended several tests + -- Add SHA512/256 and SHA512/224 -- Bugfix multi2 -- Bugfix Noekeon -- Bugfix XTEA From 699f52418ef47137fc9ea5da608fbddc6bbc73a3 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Fri, 10 Oct 2014 16:43:53 +0200 Subject: [PATCH 19/28] don't use SHA1 @buggywhip is right [skip ci] --- crypt.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crypt.tex b/crypt.tex index 958f52a..ce740a1 100644 --- a/crypt.tex +++ b/crypt.tex @@ -2146,7 +2146,7 @@ It is highly recommended that you \textbf{not} use the MD4 or MD5 hashes for the These hashes are provided for completeness and they still can be used for the purposes of password hashing or one-way accumulators (e.g. Yarrow). -The other hashes such as the SHA-1, SHA-2 (that includes SHA-512, SHA-512/384, SHA-384, SHA-512/256, SHA-256 and SHA-224) and TIGER-192 are still considered secure +The other hashes such as the SHA-2 (that includes SHA-512, SHA-512/384, SHA-384, SHA-512/256, SHA-256 and SHA-224) and TIGER-192 are still considered secure for all purposes you would normally use a hash for. \chapter{Message Authentication Codes} From 1cf965cfccfb72eff78c1846557bb8c8aaedfb99 Mon Sep 17 00:00:00 2001 From: Pascal Brand Date: Mon, 3 Nov 2014 10:25:40 +0100 Subject: [PATCH 20/28] Add doc for CCM Authentication full set of functions Change-Id: I2830ea3c04fd0410cc12137be41e6c511c4a47fe --- crypt.tex | 241 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 172 insertions(+), 69 deletions(-) diff --git a/crypt.tex b/crypt.tex index ce740a1..88d0874 100644 --- a/crypt.tex +++ b/crypt.tex @@ -1511,9 +1511,91 @@ Similarly, this will OCB decrypt, and compare the internally computed tag agains appropriately. \subsection{CCM Mode} -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, -it is only meant for \textit{packet} mode where the length of the input is known in advance. Since it is a packet mode function, CCM only has one -function that performs the protocol. +CCM is a NIST proposal for encrypt + authenticate that is centered around using AES (or any 16--byte cipher) as a primitive. + +\subsubsection{Initialization} +To initialize the CCM context with a secret key call the following function. + +\index{ccm\_init()} +\begin{verbatim} +int ccm_init( ccm_state *ccm, + int cipher, + const unsigned char *key, + int keylen, + int ptlen, + int taglen, + int aadlen); +\end{verbatim} +This initializes the CCM state \textit{ccm} 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). +Unlike EAX and OCB mode, CCM is only meant for \textit{packet} mode where the length of the input is known in advance. This is why the length of the stream +to authenticate is given as \textit{ptlen}. +With CCM, a header is meta--data you want to send with the message but not have encrypted. The header len is given in the init +as \textit{aadlen}. + +\subsubsection{Nonce Vector} +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. + +\index{ccm\_add\_nonce()} +\begin{verbatim} +int ccm_add_nonce( ccm_state *ccm, + const unsigned char *nonce, + unsigned long noncelen); +\end{verbatim} + +This adds the nonce or salt is \textit{nonce} of length \textit{noncelen} octets to the CCM state \textit{ccm}. Note that this function must be called +once and only once. + +\subsubsection{Additional Authentication Data} +The header is meta--data you want to send with the message but not have encrypted, it is stored in \textit{adata} of length \textit{adatalen} octets. + +\index{ccm\_add\_aad()} +\begin{verbatim} +int ccm_add_aad( ccm_state *ccm, + const unsigned char *adata, + unsigned long adatalen); +\end{verbatim} +This adds the additional authentication data \textit{adata} of length \textit{adatalen} to the CCM state \textit{ccm}. + +\subsubsection{Plaintext Processing} +After the AAD has been processed, the plaintext (or ciphertext depending on the direction) can be processed. + +\index{ccm\_process()} +\begin{verbatim} +int ccm_process(ccm_state *ccm, + 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{CCM\_ENCRYPT} the plaintext is read, +encrypted and stored in the ciphertext buffer. When \textit{direction} equals \textbf{CCM\_DECRYPT} the opposite occurs. + +\subsubsection{State Termination} +To terminate a CCM state and retrieve the message authentication tag call the following function. + +\index{ccm\_done()} +\begin{verbatim} +int ccm_done( ccm_state *ccm, + unsigned char *tag, + unsigned long *taglen); +\end{verbatim} +This terminates the CCM state \textit{ccm} and stores the tag in \textit{tag} of length \textit{taglen} octets. + +\subsubsection{State Reset} +The call to ccm\_init() will perform considerable pre--computation and if you're going to be dealing with a lot of packets +it is very costly to have to call it repeatedly. To aid in this endeavour, the reset function has been provided. + +\index{ccm\_reset()} +\begin{verbatim} +int ccm_reset(ccm_state *ccm); +\end{verbatim} + +This will reset the CCM state \textit{ccm} to the state that ccm\_init() left it. The user would then call ccm\_add\_nonce(), ccm\_add\_aad(), etc. + +\subsubsection{One--Shot Packet} +To process a single packet under any given key the following helper function can be used. \index{ccm\_memory()} \begin{verbatim} @@ -1529,86 +1611,107 @@ int ccm_memory( int direction); \end{verbatim} -This performs the \textit{CCM} operation on the data. The \textit{cipher} variable indicates which cipher in the descriptor table to use. It must have a -16--byte block size for CCM. +This will initialize the CCM state with the given key, nonce and AAD value then proceed to encrypt or decrypt the message text and store the final +message tag. The definition of the variables is the same as it is for all the manual functions. -The key can be specified in one of two fashions. First, it can be passed as an array of octets in \textit{key} of length \textit{keylen}. Alternatively, -it can be passed in as a previously scheduled key in \textit{uskey}. The latter fashion saves time when the same key is used for multiple packets. If -\textit{uskey} is not \textbf{NULL}, then \textit{key} may be \textbf{NULL} (and vice-versa). +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. -The nonce or salt is \textit{nonce} of length \textit{noncelen} octets. The header is meta--data you want to send with the message but not have -encrypted, it is stored in \textit{header} of length \textit{headerlen} octets. The header can be zero octets long (if $headerlen = 0$ then -you can pass \textit{header} as \textbf{NULL}). - -The plaintext is stored in \textit{pt}, and the ciphertext in \textit{ct}. The length of both are expected to be equal and is passed in as \textit{ptlen}. It is -allowable that $pt = ct$. The \textit{direction} variable indicates whether encryption (direction $=$ \textbf{CCM\_ENCRYPT}) or -decryption (direction $=$ \textbf{CCM\_DECRYPT}) is to be performed. - -As implemented, this version of CCM cannot handle header or plaintext data longer than $2^{32} - 1$ octets long. - -You can test the implementation of CCM with the following function. - -\index{ccm\_test()} -\begin{verbatim} -int ccm_test(void); -\end{verbatim} - -This will return \textbf{CRYPT\_OK} if the CCM routine passes known test vectors. It requires AES or Rijndael to be registered previously, otherwise it will -return \textbf{CRYPT\_NOP}. - -\subsubsection{CCM Example} -The following is a sample of how to call CCM. +\subsubsection{Example Usage} +The following is an example usage of how to use CCM over multiple packets with a shared secret key. \begin{small} \begin{verbatim} #include + +int send_packet(const unsigned char *pt, unsigned long ptlen, + const unsigned char *nonce, unsigned long noncelen, + const unsigned char *aad, unsigned long aadlen, + ccm_state *ccm) +{ + int err; + unsigned long taglen; + unsigned char tag[16]; + + /* reset the state */ + if ((err = ccm_reset(ccm)) != CRYPT_OK) { + return err; + } + + /* Add the nonce */ + if ((err = ccm_add_nonce(ccm, nonce, noncelen)) != CRYPT_OK) { + return err; + } + + /* Add the AAD (note: aad can be NULL if aadlen == 0) */ + if ((err = ccm_add_aad(ccm, aad, aadlen)) != CRYPT_OK) { + return err; + } + + /* process the plaintext */ + if ((err = + ccm_process(ccm, pt, ptlen, pt, CCM_ENCRYPT)) != CRYPT_OK) { + return err; + } + + /* Finish up and get the MAC tag */ + taglen = sizeof(tag); + if ((err = ccm_done(ccm, tag, &taglen)) != CRYPT_OK) { + return err; + } + + /* ... 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) { - unsigned char key[16], nonce[12], pt[32], ct[32], - tag[16], tagcp[16]; - unsigned long taglen; - int err; + ccm_state ccm; + unsigned char key[16], NONCE[12], pt[PACKET_SIZE]; + int err, x; + unsigned long ptlen; - /* register cipher */ + /* somehow fill key/NONCE with random values */ + + /* register AES */ register_cipher(&aes_desc); - /* somehow fill key, nonce, pt */ - - /* encrypt it */ - taglen = sizeof(tag); + /* init the CCM state */ if ((err = - ccm_memory(find_cipher("aes"), - key, 16, /* 128-bit key */ - NULL, /* not prescheduled */ - nonce, 12, /* 96-bit nonce */ - NULL, 0, /* no header */ - pt, 32, /* [in] 32-byte plaintext */ - ct, /* [out] ciphertext */ - tag, &taglen, - CCM_ENCRYPT)) != CRYPT_OK) { - printf("ccm_memory error %s\n", error_to_string(err)); - return -1; - } - /* ct[0..31] and tag[0..15] now hold the output */ - - /* decrypt it */ - taglen = sizeof(tagcp); - if ((err = - ccm_memory(find_cipher("aes"), - key, 16, /* 128-bit key */ - NULL, /* not prescheduled */ - nonce, 12, /* 96-bit nonce */ - NULL, 0, /* no header */ - pt, 32, /* [out] 32-byte plaintext */ - ct, /* [in] ciphertext */ - tagcp, &taglen, - CCM_DECRYPT)) != CRYPT_OK) { - printf("ccm_memory error %s\n", error_to_string(err)); - return -1; + ccm_init(&ccm, find_cipher("aes"), key, 16, PACKET_SIZE, 16, size(NONCE))) != CRYPT_OK) { + whine_and_pout(err); } - /* now pt[0..31] should hold the original plaintext, - tagcp[0..15] and tag[0..15] should have the same contents */ + /* 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} From 84606ab8de526be869eb0bf69fa0599117d60120 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Mon, 3 Nov 2014 23:13:07 +0100 Subject: [PATCH 21/28] minor spelling corrections --- crypt.tex | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/crypt.tex b/crypt.tex index 88d0874..daf63b0 100644 --- a/crypt.tex +++ b/crypt.tex @@ -1543,11 +1543,11 @@ int ccm_add_nonce( ccm_state *ccm, unsigned long noncelen); \end{verbatim} -This adds the nonce or salt is \textit{nonce} of length \textit{noncelen} octets to the CCM state \textit{ccm}. Note that this function must be called +This adds the nonce (a.k.a. salt) \textit{nonce} of length \textit{noncelen} octets to the CCM state \textit{ccm}. Note that this function must be called once and only once. \subsubsection{Additional Authentication Data} -The header is meta--data you want to send with the message but not have encrypted, it is stored in \textit{adata} of length \textit{adatalen} octets. +The header is meta--data you want to send with the message but not have encrypted, it must be stored in \textit{adata} of length \textit{adatalen} octets. \index{ccm\_add\_aad()} \begin{verbatim} @@ -1585,7 +1585,7 @@ This terminates the CCM state \textit{ccm} and stores the tag in \textit{tag} of \subsubsection{State Reset} The call to ccm\_init() will perform considerable pre--computation and if you're going to be dealing with a lot of packets -it is very costly to have to call it repeatedly. To aid in this endeavour, the reset function has been provided. +it is very costly to have to call it repeatedly. To aid in this endeavour, the reset function is provided. \index{ccm\_reset()} \begin{verbatim} From deeea5a1ec3fb7f74715a88b0f6f33915870489c Mon Sep 17 00:00:00 2001 From: Michael Stapelberg Date: Sun, 28 Jun 2015 20:35:13 +0200 Subject: [PATCH 22/28] fix crypt.tex with newer LaTeX: s/here/h/g See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=790321 for context --- crypt.tex | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/crypt.tex b/crypt.tex index daf63b0..c908579 100644 --- a/crypt.tex +++ b/crypt.tex @@ -2162,7 +2162,7 @@ int unregister_hash(const struct _hash_descriptor *hash); The following hashes are provided as of this release within the LibTomCrypt library: \index{Hash descriptor table} -\begin{figure}[here] +\begin{figure}[h] \begin{center} \begin{tabular}{|c|c|c|} \hline \textbf{Name} & \textbf{Descriptor Name} & \textbf{Size of Message Digest (bytes)} \\ @@ -3028,7 +3028,7 @@ descriptor twice, and will return the index of the current placement in the tabl will return \textbf{CRYPT\_OK} if the PRNG was found and removed. Otherwise, it returns \textbf{CRYPT\_ERROR}. \subsection{PRNGs Provided} -\begin{figure}[here] +\begin{figure}[h] \begin{center} \begin{small} \begin{tabular}{|c|c|l|} @@ -4450,7 +4450,7 @@ The variable \textit{prng} is an active PRNG state and \textit{wprng} the index \textit{group\_size} the more difficult a forgery becomes upto a limit. The value of $group\_size$ is limited by $15 < group\_size < 1024$ and $modulus\_size - group\_size < 512$. Suggested values for the pairs are as follows. -\begin{figure}[here] +\begin{figure}[h] \begin{center} \begin{tabular}{|c|c|c|} \hline \textbf{Bits of Security} & \textbf{group\_size} & \textbf{modulus\_size} \\ @@ -4666,7 +4666,7 @@ LTC_SET_ASN1(sequence, x++, LTC_ASN1_NULL, NULL, 0); \end{verbatim} \end{small} -\begin{figure}[here] +\begin{figure}[h] \begin{center} \begin{small} \begin{tabular}{|l|l|} @@ -5689,7 +5689,7 @@ e^{1.923 \cdot ln(n)^{1 \over 3} \cdot ln(ln(n))^{2 \over 3}} Note that $n$ is not the bit-length but the magnitude. For example, for a 1024-bit key $n = 2^{1024}$. The work required is: -\begin{figure}[here] +\begin{figure}[h] \begin{center} \begin{tabular}{|c|c|} \hline RSA/DH Key Size (bits) & Work Factor ($log_2$) \\ @@ -5709,7 +5709,7 @@ is: The work factor for ECC keys is much higher since the best attack is still fully exponential. Given a key of magnitude $n$ it requires $\sqrt n$ work. The following table summarizes the work required: -\begin{figure}[here] +\begin{figure}[h] \begin{center} \begin{tabular}{|c|c|} \hline ECC Key Size (bits) & Work Factor ($log_2$) \\ From 434280587a9bd56b30f0ca15583fa0a59aeeaec4 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Tue, 28 Feb 2017 13:26:12 +0100 Subject: [PATCH 23/28] also apply the verbosity settings to the doc generation --- makefile | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/makefile b/makefile index 9fb0113..702b02e 100644 --- a/makefile +++ b/makefile @@ -12,8 +12,10 @@ PLATFORM := $(shell uname | sed -e 's/_.*//') ifeq ($V,1) silent= +silent_stdout= else silent=@ +silent_stdout= > /dev/null endif %.o: %.c @@ -360,7 +362,7 @@ clean: #build the doxy files (requires Doxygen, tetex and patience) doxy: - doxygen + doxygen $(silent_stdout) cd doc/doxygen/latex ; ${MAKE} ; mv -f refman.pdf ../../. echo The huge doxygen PDF should be available as doc/refman.pdf @@ -380,11 +382,11 @@ docs: crypt.tex mv crypt-deterministic.tex crypt.tex touch --reference=crypt.bak crypt.tex echo "hello" > crypt.ind - latex crypt > /dev/null - latex crypt > /dev/null - makeindex crypt.idx > /dev/null + latex crypt $(silent_stdout) + latex crypt $(silent_stdout) + makeindex crypt.idx $(silent_stdout) perl fixupind.pl - pdflatex crypt > /dev/null + pdflatex crypt $(silent_stdout) sed -b -i 's,^/ID \[.*\]$$,/ID [<0> <0>],g' crypt.pdf mv -ivf crypt.pdf doc/crypt.pdf mv crypt.bak crypt.tex @@ -392,12 +394,12 @@ docs: crypt.tex docdvi: crypt.tex echo hello > crypt.ind - latex crypt > /dev/null - latex crypt > /dev/null + latex crypt $(silent_stdout) + latex crypt $(silent_stdout) makeindex crypt.idx perl fixupind.pl - latex crypt > /dev/null - latex crypt > /dev/null + latex crypt $(silent_stdout) + latex crypt $(silent_stdout) #zipup the project (take that!) no_oops: clean From 6c1d614a92c5e1ddb451cb9be3f8901ec5f52266 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Tue, 28 Feb 2017 13:27:02 +0100 Subject: [PATCH 24/28] update Doxyfile to a more recent version of doxygen --- Doxyfile | 2477 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 1817 insertions(+), 660 deletions(-) diff --git a/Doxyfile b/Doxyfile index f07c339..5a33f5c 100644 --- a/Doxyfile +++ b/Doxyfile @@ -1,1155 +1,2312 @@ -# Doxyfile 1.3.9.1 +# Doxyfile 1.8.7 # This file describes the settings to be used by the documentation system -# doxygen (www.doxygen.org) for a project +# doxygen (www.doxygen.org) for a project. # -# All text after a hash (#) is considered a comment and will be ignored +# All text after a double hash (##) is considered a comment and is placed in +# front of the TAG it is preceding. +# +# All text after a single hash (#) is considered a comment and will be ignored. # The format is: -# TAG = value [value, ...] -# For lists items can also be appended using: -# TAG += value [value, ...] -# Values that contain spaces should be placed between quotes (" ") +# TAG = value [value, ...] +# For lists, items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (\" \"). #--------------------------------------------------------------------------- # Project related configuration options #--------------------------------------------------------------------------- -# The PROJECT_NAME tag is a single word (or a sequence of words surrounded -# by quotes) that should identify the project. +# This tag specifies the encoding used for all characters in the config file +# that follow. The default is UTF-8 which is also the encoding used for all text +# before the first occurrence of this tag. Doxygen uses libiconv (or the iconv +# built into libc) for the transcoding. See http://www.gnu.org/software/libiconv +# for the list of possible encodings. +# The default value is: UTF-8. + +DOXYFILE_ENCODING = UTF-8 + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by +# double-quotes, unless you are using Doxywizard) that should identify the +# project for which the documentation is generated. This name is used in the +# title of most generated pages and in a few other places. +# The default value is: My Project. PROJECT_NAME = LibTomCrypt -# The PROJECT_NUMBER tag can be used to enter a project or revision number. -# This could be handy for archiving the generated documentation or -# if some version control system is used. +# The PROJECT_NUMBER tag can be used to enter a project or revision number. This +# could be handy for archiving the generated documentation or if some version +# control system is used. PROJECT_NUMBER = 1.17 -# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) -# base path where the generated documentation will be put. -# If a relative path is entered, it will be relative to the location -# where doxygen was started. If left blank the current directory will be used. +# Using the PROJECT_BRIEF tag one can provide an optional one line description +# for a project that appears at the top of each page and should give viewer a +# quick idea about the purpose of the project. Keep the description short. + +PROJECT_BRIEF = + +# With the PROJECT_LOGO tag one can specify an logo or icon that is included in +# the documentation. The maximum height of the logo should not exceed 55 pixels +# and the maximum width should not exceed 200 pixels. Doxygen will copy the logo +# to the output directory. + +PROJECT_LOGO = + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path +# into which the generated documentation will be written. If a relative path is +# entered, it will be relative to the location where doxygen was started. If +# left blank the current directory will be used. OUTPUT_DIRECTORY = doc/doxygen -# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create -# 4096 sub-directories (in 2 levels) under the output directory of each output -# format and will distribute the generated files over these directories. -# Enabling this option can be useful when feeding doxygen a huge amount of source -# files, where putting all generated files in the same directory would otherwise -# cause performance problems for the file system. +# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 4096 sub- +# directories (in 2 levels) under the output directory of each output format and +# will distribute the generated files over these directories. Enabling this +# option can be useful when feeding doxygen a huge amount of source files, where +# putting all generated files in the same directory would otherwise causes +# performance problems for the file system. +# The default value is: NO. CREATE_SUBDIRS = NO -# The OUTPUT_LANGUAGE tag is used to specify the language in which all -# documentation generated by doxygen is written. Doxygen will use this -# information to generate all constant output in the proper language. -# The default language is English, other supported languages are: -# Brazilian, Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, -# Dutch, Finnish, French, German, Greek, Hungarian, Italian, Japanese, -# Japanese-en (Japanese with English messages), Korean, Korean-en, Norwegian, -# Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovene, Spanish, -# Swedish, and Ukrainian. +# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII +# characters to appear in the names of generated files. If set to NO, non-ASCII +# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode +# U+3044. +# The default value is: NO. + +ALLOW_UNICODE_NAMES = NO + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese, +# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States), +# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian, +# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages), +# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian, +# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian, +# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish, +# Ukrainian and Vietnamese. +# The default value is: English. OUTPUT_LANGUAGE = English -# This tag can be used to specify the encoding used in the generated output. -# The encoding is not always determined by the language that is chosen, -# but also whether or not the output is meant for Windows or non-Windows users. -# In case there is a difference, setting the USE_WINDOWS_ENCODING tag to YES -# forces the Windows encoding (this is the default for the Windows binary), -# whereas setting the tag to NO uses a Unix-style encoding (the default for -# all platforms other than Windows). - -USE_WINDOWS_ENCODING = NO - -# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will -# include brief member descriptions after the members that are listed in -# the file and class documentation (similar to JavaDoc). -# Set to NO to disable this. +# If the BRIEF_MEMBER_DESC tag is set to YES doxygen will include brief member +# descriptions after the members that are listed in the file and class +# documentation (similar to Javadoc). Set to NO to disable this. +# The default value is: YES. BRIEF_MEMBER_DESC = YES -# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend -# the brief description of a member or function before the detailed description. -# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# If the REPEAT_BRIEF tag is set to YES doxygen will prepend the brief +# description of a member or function before the detailed description +# +# Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the # brief descriptions will be completely suppressed. +# The default value is: YES. REPEAT_BRIEF = YES -# This tag implements a quasi-intelligent brief description abbreviator -# that is used to form the text in various listings. Each string -# in this list, if found as the leading text of the brief description, will be -# stripped from the text and the result after processing the whole list, is used -# as the annotated text. Otherwise, the brief description is used as-is. If left -# blank, the following values are used ("$name" is automatically replaced with the -# name of the entity): "The $name class" "The $name widget" "The $name file" -# "is" "provides" "specifies" "contains" "represents" "a" "an" "the" +# This tag implements a quasi-intelligent brief description abbreviator that is +# used to form the text in various listings. Each string in this list, if found +# as the leading text of the brief description, will be stripped from the text +# and the result, after processing the whole list, is used as the annotated +# text. Otherwise, the brief description is used as-is. If left blank, the +# following values are used ($name is automatically replaced with the name of +# the entity):The $name class, The $name widget, The $name file, is, provides, +# specifies, contains, represents, a, an and the. -ABBREVIATE_BRIEF = +ABBREVIATE_BRIEF = -# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then -# Doxygen will generate a detailed section even if there is only a brief +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# doxygen will generate a detailed section even if there is only a brief # description. +# The default value is: NO. ALWAYS_DETAILED_SEC = NO -# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all inherited -# members of a class in the documentation of that class as if those members were -# ordinary class members. Constructors, destructors and assignment operators of -# the base classes will not be shown. +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. +# The default value is: NO. INLINE_INHERITED_MEMB = NO -# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full -# path before files name in the file list and in the header files. If set -# to NO the shortest path that makes the file name unique will be used. +# If the FULL_PATH_NAMES tag is set to YES doxygen will prepend the full path +# before files name in the file list and in the header files. If set to NO the +# shortest path that makes the file name unique will be used +# The default value is: YES. FULL_PATH_NAMES = YES -# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag -# can be used to strip a user-defined part of the path. Stripping is -# only done if one of the specified strings matches the left-hand part of -# the path. The tag can be used to show relative paths in the file list. -# If left blank the directory from which doxygen is run is used as the -# path to strip. +# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. +# Stripping is only done if one of the specified strings matches the left-hand +# part of the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the path to +# strip. +# +# Note that you can specify absolute paths here, but also relative paths, which +# will be relative from the directory where doxygen is started. +# This tag requires that the tag FULL_PATH_NAMES is set to YES. STRIP_FROM_PATH = src -# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of -# the path mentioned in the documentation of a class, which tells -# the reader which header file to include in order to use a class. -# If left blank only the name of the header file containing the class -# definition is used. Otherwise one should specify the include paths that -# are normally passed to the compiler using the -I flag. +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the +# path mentioned in the documentation of a class, which tells the reader which +# header file to include in order to use a class. If left blank only the name of +# the header file containing the class definition is used. Otherwise one should +# specify the list of include paths that are normally passed to the compiler +# using the -I flag. STRIP_FROM_INC_PATH = src/headers -# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter -# (but less readable) file names. This can be useful is your file systems -# doesn't support long names like on DOS, Mac, or CD-ROM. +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but +# less readable) file names. This can be useful is your file systems doesn't +# support long names like on DOS, Mac, or CD-ROM. +# The default value is: NO. SHORT_NAMES = NO -# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen -# will interpret the first line (until the first dot) of a JavaDoc-style -# comment as the brief description. If set to NO, the JavaDoc -# comments will behave just like the Qt-style comments (thus requiring an -# explicit @brief command for a brief description. +# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the +# first line (until the first dot) of a Javadoc-style comment as the brief +# description. If set to NO, the Javadoc-style will behave just like regular Qt- +# style comments (thus requiring an explicit @brief command for a brief +# description.) +# The default value is: NO. JAVADOC_AUTOBRIEF = YES -# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen -# treat a multi-line C++ special comment block (i.e. a block of //! or /// -# comments) as a brief description. This used to be the default behaviour. -# The new default is to treat a multi-line C++ comment block as a detailed -# description. Set this tag to YES if you prefer the old behaviour instead. +# If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first +# line (until the first dot) of a Qt-style comment as the brief description. If +# set to NO, the Qt-style will behave just like regular Qt-style comments (thus +# requiring an explicit \brief command for a brief description.) +# The default value is: NO. + +QT_AUTOBRIEF = NO + +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a +# multi-line C++ special comment block (i.e. a block of //! or /// comments) as +# a brief description. This used to be the default behavior. The new default is +# to treat a multi-line C++ comment block as a detailed description. Set this +# tag to YES if you prefer the old behavior instead. +# +# Note that setting this tag to YES also means that rational rose comments are +# not recognized any more. +# The default value is: NO. MULTILINE_CPP_IS_BRIEF = NO -# If the DETAILS_AT_TOP tag is set to YES then Doxygen -# will output the detailed description near the top, like JavaDoc. -# If set to NO, the detailed description appears after the member -# documentation. - -DETAILS_AT_TOP = YES - -# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented -# member inherits the documentation from any documented member that it -# re-implements. +# If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the +# documentation from any documented member that it re-implements. +# The default value is: YES. INHERIT_DOCS = YES -# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC -# tag is set to YES, then doxygen will reuse the documentation of the first -# member in the group (if any) for the other members of the group. By default -# all members of a group must be documented explicitly. +# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce a +# new page for each member. If set to NO, the documentation of a member will be +# part of the file/class/namespace that contains it. +# The default value is: NO. -DISTRIBUTE_GROUP_DOC = NO +SEPARATE_MEMBER_PAGES = NO -# The TAB_SIZE tag can be used to set the number of spaces in a tab. -# Doxygen uses this value to replace tabs by spaces in code fragments. +# The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen +# uses this value to replace tabs by spaces in code fragments. +# Minimum value: 1, maximum value: 16, default value: 4. TAB_SIZE = 4 -# This tag can be used to specify a number of aliases that acts -# as commands in the documentation. An alias has the form "name=value". -# For example adding "sideeffect=\par Side Effects:\n" will allow you to -# put the command \sideeffect (or @sideeffect) in the documentation, which -# will result in a user-defined paragraph with heading "Side Effects:". -# You can put \n's in the value part of an alias to insert newlines. +# This tag can be used to specify a number of aliases that act as commands in +# the documentation. An alias has the form: +# name=value +# For example adding +# "sideeffect=@par Side Effects:\n" +# will allow you to put the command \sideeffect (or @sideeffect) in the +# documentation, which will result in a user-defined paragraph with heading +# "Side Effects:". You can put \n's in the value part of an alias to insert +# newlines. -ALIASES = +ALIASES = -# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources -# only. Doxygen will then generate output that is more tailored for C. -# For instance, some of the names that are used will be different. The list -# of all members will be omitted, etc. +# This tag can be used to specify a number of word-keyword mappings (TCL only). +# A mapping has the form "name=value". For example adding "class=itcl::class" +# will allow you to use the command class in the itcl::class meaning. + +TCL_SUBST = + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources +# only. Doxygen will then generate output that is more tailored for C. For +# instance, some of the names that are used will be different. The list of all +# members will be omitted, etc. +# The default value is: NO. OPTIMIZE_OUTPUT_FOR_C = YES -# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java sources -# only. Doxygen will then generate output that is more tailored for Java. -# For instance, namespaces will be presented as packages, qualified scopes -# will look different, etc. +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or +# Python sources only. Doxygen will then generate output that is more tailored +# for that language. For instance, namespaces will be presented as packages, +# qualified scopes will look different, etc. +# The default value is: NO. OPTIMIZE_OUTPUT_JAVA = NO -# Set the SUBGROUPING tag to YES (the default) to allow class member groups of -# the same type (for instance a group of public functions) to be put as a -# subgroup of that type (e.g. under the Public Functions section). Set it to -# NO to prevent subgrouping. Alternatively, this can be done per class using -# the \nosubgrouping command. +# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran +# sources. Doxygen will then generate output that is tailored for Fortran. +# The default value is: NO. + +OPTIMIZE_FOR_FORTRAN = NO + +# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL +# sources. Doxygen will then generate output that is tailored for VHDL. +# The default value is: NO. + +OPTIMIZE_OUTPUT_VHDL = NO + +# Doxygen selects the parser to use depending on the extension of the files it +# parses. With this tag you can assign which parser to use for a given +# extension. Doxygen has a built-in mapping, but you can override or extend it +# using this tag. The format is ext=language, where ext is a file extension, and +# language is one of the parsers supported by doxygen: IDL, Java, Javascript, +# C#, C, C++, D, PHP, Objective-C, Python, Fortran (fixed format Fortran: +# FortranFixed, free formatted Fortran: FortranFree, unknown formatted Fortran: +# Fortran. In the later case the parser tries to guess whether the code is fixed +# or free formatted code, this is the default for Fortran type files), VHDL. For +# instance to make doxygen treat .inc files as Fortran files (default is PHP), +# and .f files as C (default is Fortran), use: inc=Fortran f=C. +# +# Note For files without extension you can use no_extension as a placeholder. +# +# Note that for custom extensions you also need to set FILE_PATTERNS otherwise +# the files are not read by doxygen. + +EXTENSION_MAPPING = + +# If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments +# according to the Markdown format, which allows for more readable +# documentation. See http://daringfireball.net/projects/markdown/ for details. +# The output of markdown processing is further processed by doxygen, so you can +# mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in +# case of backward compatibilities issues. +# The default value is: YES. + +MARKDOWN_SUPPORT = YES + +# When enabled doxygen tries to link words that correspond to documented +# classes, or namespaces to their corresponding documentation. Such a link can +# be prevented in individual cases by by putting a % sign in front of the word +# or globally by setting AUTOLINK_SUPPORT to NO. +# The default value is: YES. + +AUTOLINK_SUPPORT = YES + +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want +# to include (a tag file for) the STL sources as input, then you should set this +# tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); +# versus func(std::string) {}). This also make the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate. +# The default value is: NO. + +BUILTIN_STL_SUPPORT = NO + +# If you use Microsoft's C++/CLI language, you should set this option to YES to +# enable parsing support. +# The default value is: NO. + +CPP_CLI_SUPPORT = NO + +# Set the SIP_SUPPORT tag to YES if your project consists of sip (see: +# http://www.riverbankcomputing.co.uk/software/sip/intro) sources only. Doxygen +# will parse them like normal C++ but will assume all classes use public instead +# of private inheritance when no explicit protection keyword is present. +# The default value is: NO. + +SIP_SUPPORT = NO + +# For Microsoft's IDL there are propget and propput attributes to indicate +# getter and setter methods for a property. Setting this option to YES will make +# doxygen to replace the get and set methods by a property in the documentation. +# This will only work if the methods are indeed getting or setting a simple +# type. If this is not the case, or you want to show the methods anyway, you +# should set this option to NO. +# The default value is: YES. + +IDL_PROPERTY_SUPPORT = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES, then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. +# The default value is: NO. + +DISTRIBUTE_GROUP_DOC = NO + +# Set the SUBGROUPING tag to YES to allow class member groups of the same type +# (for instance a group of public functions) to be put as a subgroup of that +# type (e.g. under the Public Functions section). Set it to NO to prevent +# subgrouping. Alternatively, this can be done per class using the +# \nosubgrouping command. +# The default value is: YES. SUBGROUPING = YES +# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions +# are shown inside the group in which they are included (e.g. using \ingroup) +# instead of on a separate page (for HTML and Man pages) or section (for LaTeX +# and RTF). +# +# Note that this feature does not work in combination with +# SEPARATE_MEMBER_PAGES. +# The default value is: NO. + +INLINE_GROUPED_CLASSES = NO + +# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions +# with only public data fields or simple typedef fields will be shown inline in +# the documentation of the scope in which they are defined (i.e. file, +# namespace, or group documentation), provided this scope is documented. If set +# to NO, structs, classes, and unions are shown on a separate page (for HTML and +# Man pages) or section (for LaTeX and RTF). +# The default value is: NO. + +INLINE_SIMPLE_STRUCTS = NO + +# When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or +# enum is documented as struct, union, or enum with the name of the typedef. So +# typedef struct TypeS {} TypeT, will appear in the documentation as a struct +# with name TypeT. When disabled the typedef will appear as a member of a file, +# namespace, or class. And the struct will be named TypeS. This can typically be +# useful for C code in case the coding convention dictates that all compound +# types are typedef'ed and only the typedef is referenced, never the tag name. +# The default value is: NO. + +TYPEDEF_HIDES_STRUCT = NO + +# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This +# cache is used to resolve symbols given their name and scope. Since this can be +# an expensive process and often the same symbol appears multiple times in the +# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small +# doxygen will become slower. If the cache is too large, memory is wasted. The +# cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range +# is 0..9, the default is 0, corresponding to a cache size of 2^16=65536 +# symbols. At the end of a run doxygen will report the cache usage and suggest +# the optimal cache size from a speed point of view. +# Minimum value: 0, maximum value: 9, default value: 0. + +LOOKUP_CACHE_SIZE = 0 + #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- -# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in -# documentation are documented, even if no documentation was available. -# Private class members and static file members will be hidden unless -# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES +# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in +# documentation are documented, even if no documentation was available. Private +# class members and static file members will be hidden unless the +# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES. +# Note: This will also disable the warnings about undocumented members that are +# normally produced when WARNINGS is set to YES. +# The default value is: NO. EXTRACT_ALL = YES -# If the EXTRACT_PRIVATE tag is set to YES all private members of a class -# will be included in the documentation. +# If the EXTRACT_PRIVATE tag is set to YES all private members of a class will +# be included in the documentation. +# The default value is: NO. EXTRACT_PRIVATE = YES -# If the EXTRACT_STATIC tag is set to YES all static members of a file -# will be included in the documentation. +# If the EXTRACT_PACKAGE tag is set to YES all members with package or internal +# scope will be included in the documentation. +# The default value is: NO. + +EXTRACT_PACKAGE = NO + +# If the EXTRACT_STATIC tag is set to YES all static members of a file will be +# included in the documentation. +# The default value is: NO. EXTRACT_STATIC = YES -# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) -# defined locally in source files will be included in the documentation. -# If set to NO only classes defined in header files are included. +# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) defined +# locally in source files will be included in the documentation. If set to NO +# only classes defined in header files are included. Does not have any effect +# for Java sources. +# The default value is: YES. EXTRACT_LOCAL_CLASSES = YES -# This flag is only useful for Objective-C code. When set to YES local -# methods, which are defined in the implementation section but not in -# the interface are included in the documentation. -# If set to NO (the default) only methods in the interface are included. +# This flag is only useful for Objective-C code. When set to YES local methods, +# which are defined in the implementation section but not in the interface are +# included in the documentation. If set to NO only methods in the interface are +# included. +# The default value is: NO. EXTRACT_LOCAL_METHODS = YES -# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all -# undocumented members of documented classes, files or namespaces. -# If set to NO (the default) these members will be included in the -# various overviews, but no documentation section is generated. -# This option has no effect if EXTRACT_ALL is enabled. +# If this flag is set to YES, the members of anonymous namespaces will be +# extracted and appear in the documentation as a namespace called +# 'anonymous_namespace{file}', where file will be replaced with the base name of +# the file that contains the anonymous namespace. By default anonymous namespace +# are hidden. +# The default value is: NO. + +EXTRACT_ANON_NSPACES = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all +# undocumented members inside documented classes or files. If set to NO these +# members will be included in the various overviews, but no documentation +# section is generated. This option has no effect if EXTRACT_ALL is enabled. +# The default value is: NO. HIDE_UNDOC_MEMBERS = NO -# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all -# undocumented classes that are normally visible in the class hierarchy. -# If set to NO (the default) these classes will be included in the various -# overviews. This option has no effect if EXTRACT_ALL is enabled. +# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. If set +# to NO these classes will be included in the various overviews. This option has +# no effect if EXTRACT_ALL is enabled. +# The default value is: NO. HIDE_UNDOC_CLASSES = NO -# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all -# friend (class|struct|union) declarations. -# If set to NO (the default) these declarations will be included in the -# documentation. +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend +# (class|struct|union) declarations. If set to NO these declarations will be +# included in the documentation. +# The default value is: NO. HIDE_FRIEND_COMPOUNDS = NO -# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any -# documentation blocks found inside the body of a function. -# If set to NO (the default) these blocks will be appended to the -# function's detailed documentation block. +# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any +# documentation blocks found inside the body of a function. If set to NO these +# blocks will be appended to the function's detailed documentation block. +# The default value is: NO. HIDE_IN_BODY_DOCS = NO -# The INTERNAL_DOCS tag determines if documentation -# that is typed after a \internal command is included. If the tag is set -# to NO (the default) then the documentation will be excluded. -# Set it to YES to include the internal documentation. +# The INTERNAL_DOCS tag determines if documentation that is typed after a +# \internal command is included. If the tag is set to NO then the documentation +# will be excluded. Set it to YES to include the internal documentation. +# The default value is: NO. INTERNAL_DOCS = NO -# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate -# file names in lower-case letters. If set to YES upper-case letters are also -# allowed. This is useful if you have classes or files whose names only differ -# in case and if your file system supports case sensitive file names. Windows +# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file +# names in lower-case letters. If set to YES upper-case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows # and Mac users are advised to set this option to NO. +# The default value is: system dependent. CASE_SENSE_NAMES = YES -# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen -# will show members with their full class and namespace scopes in the -# documentation. If set to YES the scope will be hidden. +# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with +# their full class and namespace scopes in the documentation. If set to YES the +# scope will be hidden. +# The default value is: NO. HIDE_SCOPE_NAMES = NO -# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen -# will put a list of the files that are included by a file in the documentation -# of that file. +# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of +# the files that are included by a file in the documentation of that file. +# The default value is: YES. SHOW_INCLUDE_FILES = YES -# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] -# is inserted in the documentation for inline members. +# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each +# grouped member an include statement to the documentation, telling the reader +# which file to include in order to use the member. +# The default value is: NO. + +SHOW_GROUPED_MEMB_INC = NO + +# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include +# files with double quotes in the documentation rather than with sharp brackets. +# The default value is: NO. + +FORCE_LOCAL_INCLUDES = NO + +# If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the +# documentation for inline members. +# The default value is: YES. INLINE_INFO = YES -# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen -# will sort the (detailed) documentation of file and class members -# alphabetically by member name. If set to NO the members will appear in -# declaration order. +# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the +# (detailed) documentation of file and class members alphabetically by member +# name. If set to NO the members will appear in declaration order. +# The default value is: YES. SORT_MEMBER_DOCS = YES -# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the -# brief documentation of file, namespace and class members alphabetically -# by member name. If set to NO (the default) the members will appear in -# declaration order. +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief +# descriptions of file, namespace and class members alphabetically by member +# name. If set to NO the members will appear in declaration order. Note that +# this will also influence the order of the classes in the class list. +# The default value is: NO. SORT_BRIEF_DOCS = NO -# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be -# sorted by fully-qualified names, including namespaces. If set to -# NO (the default), the class list will be sorted only by class name, -# not including the namespace part. +# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the +# (brief and detailed) documentation of class members so that constructors and +# destructors are listed first. If set to NO the constructors will appear in the +# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS. +# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief +# member documentation. +# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting +# detailed member documentation. +# The default value is: NO. + +SORT_MEMBERS_CTORS_1ST = NO + +# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy +# of group names into alphabetical order. If set to NO the group names will +# appear in their defined order. +# The default value is: NO. + +SORT_GROUP_NAMES = NO + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by +# fully-qualified names, including namespaces. If set to NO, the class list will +# be sorted only by class name, not including the namespace part. # Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. -# Note: This option applies only to the class list, not to the -# alphabetical list. +# Note: This option applies only to the class list, not to the alphabetical +# list. +# The default value is: NO. SORT_BY_SCOPE_NAME = YES -# The GENERATE_TODOLIST tag can be used to enable (YES) or -# disable (NO) the todo list. This list is created by putting \todo -# commands in the documentation. +# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper +# type resolution of all parameters of a function it will reject a match between +# the prototype and the implementation of a member function even if there is +# only one candidate or it is obvious which candidate to choose by doing a +# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still +# accept a match between prototype and implementation in such cases. +# The default value is: NO. + +STRICT_PROTO_MATCHING = NO + +# The GENERATE_TODOLIST tag can be used to enable ( YES) or disable ( NO) the +# todo list. This list is created by putting \todo commands in the +# documentation. +# The default value is: YES. GENERATE_TODOLIST = YES -# The GENERATE_TESTLIST tag can be used to enable (YES) or -# disable (NO) the test list. This list is created by putting \test -# commands in the documentation. +# The GENERATE_TESTLIST tag can be used to enable ( YES) or disable ( NO) the +# test list. This list is created by putting \test commands in the +# documentation. +# The default value is: YES. GENERATE_TESTLIST = YES -# The GENERATE_BUGLIST tag can be used to enable (YES) or -# disable (NO) the bug list. This list is created by putting \bug -# commands in the documentation. +# The GENERATE_BUGLIST tag can be used to enable ( YES) or disable ( NO) the bug +# list. This list is created by putting \bug commands in the documentation. +# The default value is: YES. GENERATE_BUGLIST = YES -# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or -# disable (NO) the deprecated list. This list is created by putting -# \deprecated commands in the documentation. +# The GENERATE_DEPRECATEDLIST tag can be used to enable ( YES) or disable ( NO) +# the deprecated list. This list is created by putting \deprecated commands in +# the documentation. +# The default value is: YES. GENERATE_DEPRECATEDLIST= YES -# The ENABLED_SECTIONS tag can be used to enable conditional -# documentation sections, marked by \if sectionname ... \endif. +# The ENABLED_SECTIONS tag can be used to enable conditional documentation +# sections, marked by \if ... \endif and \cond +# ... \endcond blocks. -ENABLED_SECTIONS = +ENABLED_SECTIONS = -# The MAX_INITIALIZER_LINES tag determines the maximum number of lines -# the initial value of a variable or define consists of for it to appear in -# the documentation. If the initializer consists of more lines than specified -# here it will be hidden. Use a value of 0 to hide initializers completely. -# The appearance of the initializer of individual variables and defines in the -# documentation can be controlled using \showinitializer or \hideinitializer -# command in the documentation regardless of this setting. +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the +# initial value of a variable or macro / define can have for it to appear in the +# documentation. If the initializer consists of more lines than specified here +# it will be hidden. Use a value of 0 to hide initializers completely. The +# appearance of the value of individual variables and macros / defines can be +# controlled using \showinitializer or \hideinitializer command in the +# documentation regardless of this setting. +# Minimum value: 0, maximum value: 10000, default value: 30. MAX_INITIALIZER_LINES = 30 -# Set the SHOW_USED_FILES tag to NO to disable the list of files generated -# at the bottom of the documentation of classes and structs. If set to YES the -# list will mention the files that were used to generate the documentation. +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated at +# the bottom of the documentation of classes and structs. If set to YES the list +# will mention the files that were used to generate the documentation. +# The default value is: YES. SHOW_USED_FILES = YES +# Set the SHOW_FILES tag to NO to disable the generation of the Files page. This +# will remove the Files entry from the Quick Index and from the Folder Tree View +# (if specified). +# The default value is: YES. + +SHOW_FILES = YES + +# Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces +# page. This will remove the Namespaces entry from the Quick Index and from the +# Folder Tree View (if specified). +# The default value is: YES. + +SHOW_NAMESPACES = YES + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from +# the version control system). Doxygen will invoke the program by executing (via +# popen()) the command command input-file, where command is the value of the +# FILE_VERSION_FILTER tag, and input-file is the name of an input file provided +# by doxygen. Whatever the program writes to standard output is used as the file +# version. For an example see the documentation. + +FILE_VERSION_FILTER = + +# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed +# by doxygen. The layout file controls the global structure of the generated +# output files in an output format independent way. To create the layout file +# that represents doxygen's defaults, run doxygen with the -l option. You can +# optionally specify a file name after the option, if omitted DoxygenLayout.xml +# will be used as the name of the layout file. +# +# Note that if you run doxygen from a directory containing a file called +# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE +# tag is left empty. + +LAYOUT_FILE = + +# The CITE_BIB_FILES tag can be used to specify one or more bib files containing +# the reference definitions. This must be a list of .bib files. The .bib +# extension is automatically appended if omitted. This requires the bibtex tool +# to be installed. See also http://en.wikipedia.org/wiki/BibTeX for more info. +# For LaTeX the style of the bibliography can be controlled using +# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the +# search path. Do not use file names with spaces, bibtex cannot handle them. See +# also \cite for info how to create references. + +CITE_BIB_FILES = + #--------------------------------------------------------------------------- -# configuration options related to warning and progress messages +# Configuration options related to warning and progress messages #--------------------------------------------------------------------------- -# The QUIET tag can be used to turn on/off the messages that are generated -# by doxygen. Possible values are YES and NO. If left blank NO is used. +# The QUIET tag can be used to turn on/off the messages that are generated to +# standard output by doxygen. If QUIET is set to YES this implies that the +# messages are off. +# The default value is: NO. QUIET = NO -# The WARNINGS tag can be used to turn on/off the warning messages that are -# generated by doxygen. Possible values are YES and NO. If left blank -# NO is used. +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated to standard error ( stderr) by doxygen. If WARNINGS is set to YES +# this implies that the warnings are on. +# +# Tip: Turn warnings on while writing the documentation. +# The default value is: YES. WARNINGS = YES -# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings -# for undocumented members. If EXTRACT_ALL is set to YES then this flag will -# automatically be disabled. +# If the WARN_IF_UNDOCUMENTED tag is set to YES, then doxygen will generate +# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag +# will automatically be disabled. +# The default value is: YES. WARN_IF_UNDOCUMENTED = YES -# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for -# potential errors in the documentation, such as not documenting some -# parameters in a documented function, or documenting parameters that -# don't exist or using markup commands wrongly. +# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some parameters +# in a documented function, or documenting parameters that don't exist or using +# markup commands wrongly. +# The default value is: YES. WARN_IF_DOC_ERROR = YES -# The WARN_FORMAT tag determines the format of the warning messages that -# doxygen can produce. The string should contain the $file, $line, and $text -# tags, which will be replaced by the file and line number from which the -# warning originated and the warning text. +# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that +# are documented, but have no documentation for their parameters or return +# value. If set to NO doxygen will only warn about wrong or incomplete parameter +# documentation, but not about the absence of documentation. +# The default value is: NO. + +WARN_NO_PARAMDOC = NO + +# The WARN_FORMAT tag determines the format of the warning messages that doxygen +# can produce. The string should contain the $file, $line, and $text tags, which +# will be replaced by the file and line number from which the warning originated +# and the warning text. Optionally the format may contain $version, which will +# be replaced by the version of the file (if it could be obtained via +# FILE_VERSION_FILTER) +# The default value is: $file:$line: $text. WARN_FORMAT = "$file:$line: $text" -# The WARN_LOGFILE tag can be used to specify a file to which warning -# and error messages should be written. If left blank the output is written -# to stderr. +# The WARN_LOGFILE tag can be used to specify a file to which warning and error +# messages should be written. If left blank the output is written to standard +# error (stderr). -WARN_LOGFILE = +WARN_LOGFILE = #--------------------------------------------------------------------------- -# configuration options related to the input files +# Configuration options related to the input files #--------------------------------------------------------------------------- -# The INPUT tag can be used to specify the files and/or directories that contain -# documented source files. You may enter file names like "myfile.cpp" or -# directories like "/usr/src/myproject". Separate the files or directories -# with spaces. +# The INPUT tag is used to specify the files and/or directories that contain +# documented source files. You may enter file names like myfile.cpp or +# directories like /usr/src/myproject. Separate the files or directories with +# spaces. +# Note: If this tag is empty the current directory is searched. INPUT = src -# If the value of the INPUT tag contains directories, you can use the -# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank the following patterns are tested: -# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp -# *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm +# This tag can be used to specify the character encoding of the source files +# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses +# libiconv (or the iconv built into libc) for the transcoding. See the libiconv +# documentation (see: http://www.gnu.org/software/libiconv) for the list of +# possible encodings. +# The default value is: UTF-8. -FILE_PATTERNS = +INPUT_ENCODING = UTF-8 -# The RECURSIVE tag can be used to turn specify whether or not subdirectories -# should be searched for input files as well. Possible values are YES and NO. -# If left blank NO is used. +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and +# *.h) to filter out the source-files in the directories. If left blank the +# following patterns are tested:*.c, *.cc, *.cxx, *.cpp, *.c++, *.java, *.ii, +# *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp, +# *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, *.m, *.markdown, +# *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf, +# *.qsf, *.as and *.js. + +FILE_PATTERNS = + +# The RECURSIVE tag can be used to specify whether or not subdirectories should +# be searched for input files as well. +# The default value is: NO. RECURSIVE = YES -# The EXCLUDE tag can be used to specify files and/or directories that should -# excluded from the INPUT source files. This way you can easily exclude a +# The EXCLUDE tag can be used to specify files and/or directories that should be +# excluded from the INPUT source files. This way you can easily exclude a # subdirectory from a directory tree whose root is specified with the INPUT tag. +# +# Note that relative paths are relative to the directory from which doxygen is +# run. -EXCLUDE = +EXCLUDE = -# The EXCLUDE_SYMLINKS tag can be used select whether or not files or directories -# that are symbolic links (a Unix filesystem feature) are excluded from the input. +# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or +# directories that are symbolic links (a Unix file system feature) are excluded +# from the input. +# The default value is: NO. EXCLUDE_SYMLINKS = NO -# If the value of the INPUT tag contains directories, you can use the -# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude # certain files from those directories. +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories for example use the pattern */test/* -EXCLUDE_PATTERNS = +EXCLUDE_PATTERNS = -# The EXAMPLE_PATH tag can be used to specify one or more files or -# directories that contain example code fragments that are included (see -# the \include command). +# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names +# (namespaces, classes, functions, etc.) that should be excluded from the +# output. The symbol name can be a fully qualified name, a word, or if the +# wildcard * is used, a substring. Examples: ANamespace, AClass, +# AClass::ANamespace, ANamespace::*Test +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories use the pattern */test/* -EXAMPLE_PATH = +EXCLUDE_SYMBOLS = -# If the value of the EXAMPLE_PATH tag contains directories, you can use the -# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank all files are included. +# The EXAMPLE_PATH tag can be used to specify one or more files or directories +# that contain example code fragments that are included (see the \include +# command). -EXAMPLE_PATTERNS = +EXAMPLE_PATH = -# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be -# searched for input files to be used with the \include or \dontinclude -# commands irrespective of the value of the RECURSIVE tag. -# Possible values are YES and NO. If left blank NO is used. +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and +# *.h) to filter out the source-files in the directories. If left blank all +# files are included. + +EXAMPLE_PATTERNS = + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude commands +# irrespective of the value of the RECURSIVE tag. +# The default value is: NO. EXAMPLE_RECURSIVE = NO -# The IMAGE_PATH tag can be used to specify one or more files or -# directories that contain image that are included in the documentation (see -# the \image command). +# The IMAGE_PATH tag can be used to specify one or more files or directories +# that contain images that are to be included in the documentation (see the +# \image command). -IMAGE_PATH = +IMAGE_PATH = -# The INPUT_FILTER tag can be used to specify a program that doxygen should -# invoke to filter for each input file. Doxygen will invoke the filter program -# by executing (via popen()) the command , where -# is the value of the INPUT_FILTER tag, and is the name of an -# input file. Doxygen will then use the output that the filter program writes -# to standard output. If FILTER_PATTERNS is specified, this tag will be -# ignored. +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command: +# +# +# +# where is the value of the INPUT_FILTER tag, and is the +# name of an input file. Doxygen will then use the output that the filter +# program writes to standard output. If FILTER_PATTERNS is specified, this tag +# will be ignored. +# +# Note that the filter must not add or remove lines; it is applied before the +# code is scanned, but not when the output code is generated. If lines are added +# or removed, the anchors will not be placed correctly. -INPUT_FILTER = +INPUT_FILTER = -# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern -# basis. Doxygen will compare the file name with each pattern and apply the -# filter if there is a match. The filters are a list of the form: -# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further -# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER -# is applied to all files. +# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern +# basis. Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. The filters are a list of the form: pattern=filter +# (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how +# filters are used. If the FILTER_PATTERNS tag is empty or if none of the +# patterns match the file name, INPUT_FILTER is applied. -FILTER_PATTERNS = +FILTER_PATTERNS = -# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using -# INPUT_FILTER) will be used to filter the input files when producing source -# files to browse (i.e. when SOURCE_BROWSER is set to YES). +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER ) will also be used to filter the input files that are used for +# producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES). +# The default value is: NO. FILTER_SOURCE_FILES = NO +# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file +# pattern. A pattern will override the setting for FILTER_PATTERN (if any) and +# it is also possible to disable source filtering for a specific pattern using +# *.ext= (so without naming a filter). +# This tag requires that the tag FILTER_SOURCE_FILES is set to YES. + +FILTER_SOURCE_PATTERNS = + +# If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that +# is part of the input, its contents will be placed on the main page +# (index.html). This can be useful if you have a project on for instance GitHub +# and want to reuse the introduction page also for the doxygen output. + +USE_MDFILE_AS_MAINPAGE = + #--------------------------------------------------------------------------- -# configuration options related to source browsing +# Configuration options related to source browsing #--------------------------------------------------------------------------- -# If the SOURCE_BROWSER tag is set to YES then a list of source files will -# be generated. Documented entities will be cross-referenced with these sources. -# Note: To get rid of all source code in the generated output, make sure also -# VERBATIM_HEADERS is set to NO. +# If the SOURCE_BROWSER tag is set to YES then a list of source files will be +# generated. Documented entities will be cross-referenced with these sources. +# +# Note: To get rid of all source code in the generated output, make sure that +# also VERBATIM_HEADERS is set to NO. +# The default value is: NO. SOURCE_BROWSER = YES -# Setting the INLINE_SOURCES tag to YES will include the body -# of functions and classes directly in the documentation. +# Setting the INLINE_SOURCES tag to YES will include the body of functions, +# classes and enums directly into the documentation. +# The default value is: NO. INLINE_SOURCES = YES -# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct -# doxygen to hide any special comment blocks from generated source code -# fragments. Normal C and C++ comments will always remain visible. +# Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any +# special comment blocks from generated source code fragments. Normal C, C++ and +# Fortran comments will always remain visible. +# The default value is: YES. STRIP_CODE_COMMENTS = NO -# If the REFERENCED_BY_RELATION tag is set to YES (the default) -# then for each documented function all documented -# functions referencing it will be listed. +# If the REFERENCED_BY_RELATION tag is set to YES then for each documented +# function all documented functions referencing it will be listed. +# The default value is: NO. REFERENCED_BY_RELATION = YES -# If the REFERENCES_RELATION tag is set to YES (the default) -# then for each documented function all documented entities -# called/used by that function will be listed. +# If the REFERENCES_RELATION tag is set to YES then for each documented function +# all documented entities called/used by that function will be listed. +# The default value is: NO. REFERENCES_RELATION = YES -# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen -# will generate a verbatim copy of the header file for each class for -# which an include is specified. Set to NO to disable this. +# If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set +# to YES, then the hyperlinks from functions in REFERENCES_RELATION and +# REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will +# link to the documentation. +# The default value is: YES. + +REFERENCES_LINK_SOURCE = YES + +# If SOURCE_TOOLTIPS is enabled (the default) then hovering a hyperlink in the +# source code will show a tooltip with additional information such as prototype, +# brief description and links to the definition and documentation. Since this +# will make the HTML file larger and loading of large files a bit slower, you +# can opt to disable this feature. +# The default value is: YES. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + +SOURCE_TOOLTIPS = YES + +# If the USE_HTAGS tag is set to YES then the references to source code will +# point to the HTML generated by the htags(1) tool instead of doxygen built-in +# source browser. The htags tool is part of GNU's global source tagging system +# (see http://www.gnu.org/software/global/global.html). You will need version +# 4.8.6 or higher. +# +# To use it do the following: +# - Install the latest version of global +# - Enable SOURCE_BROWSER and USE_HTAGS in the config file +# - Make sure the INPUT points to the root of the source tree +# - Run doxygen as normal +# +# Doxygen will invoke htags (and that will in turn invoke gtags), so these +# tools must be available from the command line (i.e. in the search path). +# +# The result: instead of the source browser generated by doxygen, the links to +# source code will now point to the output of htags. +# The default value is: NO. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + +USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a +# verbatim copy of the header file for each class for which an include is +# specified. Set to NO to disable this. +# See also: Section \class. +# The default value is: YES. VERBATIM_HEADERS = YES #--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index +# Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- -# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index -# of all compounds will be generated. Enable this if the project -# contains a lot of classes, structs, unions or interfaces. +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index of all +# compounds will be generated. Enable this if the project contains a lot of +# classes, structs, unions or interfaces. +# The default value is: YES. ALPHABETICAL_INDEX = YES -# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then -# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns -# in which this list will be split (can be a number in the range [1..20]) +# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in +# which the alphabetical index list will be split. +# Minimum value: 1, maximum value: 20, default value: 5. +# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. COLS_IN_ALPHA_INDEX = 5 -# In case all classes in a project start with a common prefix, all -# classes will be put under the same header in the alphabetical index. -# The IGNORE_PREFIX tag can be used to specify one or more prefixes that -# should be ignored while generating the index headers. +# In case all classes in a project start with a common prefix, all classes will +# be put under the same header in the alphabetical index. The IGNORE_PREFIX tag +# can be used to specify a prefix (or a list of prefixes) that should be ignored +# while generating the index headers. +# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. -IGNORE_PREFIX = +IGNORE_PREFIX = #--------------------------------------------------------------------------- -# configuration options related to the HTML output +# Configuration options related to the HTML output #--------------------------------------------------------------------------- -# If the GENERATE_HTML tag is set to YES (the default) Doxygen will -# generate HTML output. +# If the GENERATE_HTML tag is set to YES doxygen will generate HTML output +# The default value is: YES. GENERATE_HTML = YES -# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `html' will be used as the default path. +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: html. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_OUTPUT = html -# The HTML_FILE_EXTENSION tag can be used to specify the file extension for -# each generated HTML page (for example: .htm,.php,.asp). If it is left blank -# doxygen will generate files with .html extension. +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each +# generated HTML page (for example: .htm, .php, .asp). +# The default value is: .html. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_FILE_EXTENSION = .html -# The HTML_HEADER tag can be used to specify a personal HTML header for -# each generated HTML page. If it is left blank doxygen will generate a +# The HTML_HEADER tag can be used to specify a user-defined HTML header file for +# each generated HTML page. If the tag is left blank doxygen will generate a # standard header. +# +# To get valid HTML the header file that includes any scripts and style sheets +# that doxygen needs, which is dependent on the configuration options used (e.g. +# the setting GENERATE_TREEVIEW). It is highly recommended to start with a +# default header using +# doxygen -w html new_header.html new_footer.html new_stylesheet.css +# YourConfigFile +# and then modify the file new_header.html. See also section "Doxygen usage" +# for information on how to generate the default header that doxygen normally +# uses. +# Note: The header is subject to change so you typically have to regenerate the +# default header when upgrading to a newer version of doxygen. For a description +# of the possible markers and block names see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_HEADER = doc/header.html -# The HTML_FOOTER tag can be used to specify a personal HTML footer for -# each generated HTML page. If it is left blank doxygen will generate a -# standard footer. +# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each +# generated HTML page. If the tag is left blank doxygen will generate a standard +# footer. See HTML_HEADER for more information on how to generate a default +# footer and what special commands can be used inside the footer. See also +# section "Doxygen usage" for information on how to generate the default footer +# that doxygen normally uses. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_FOOTER = doc/footer.html -# The HTML_STYLESHEET tag can be used to specify a user-defined cascading -# style sheet that is used by each HTML page. It can be used to -# fine-tune the look of the HTML output. If the tag is left blank doxygen -# will generate a default style sheet. Note that doxygen will try to copy -# the style sheet file to the HTML output directory, so don't put your own -# stylesheet in the HTML output directory as well, or it will be erased! +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style +# sheet that is used by each HTML page. It can be used to fine-tune the look of +# the HTML output. If left blank doxygen will generate a default style sheet. +# See also section "Doxygen usage" for information on how to generate the style +# sheet that doxygen normally uses. +# Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as +# it is more robust and this tag (HTML_STYLESHEET) will in the future become +# obsolete. +# This tag requires that the tag GENERATE_HTML is set to YES. -HTML_STYLESHEET = +HTML_STYLESHEET = -# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, -# files or namespaces will be aligned in HTML using tables. If set to -# NO a bullet list will be used. +# The HTML_EXTRA_STYLESHEET tag can be used to specify an additional user- +# defined cascading style sheet that is included after the standard style sheets +# created by doxygen. Using this option one can overrule certain style aspects. +# This is preferred over using HTML_STYLESHEET since it does not replace the +# standard style sheet and is therefor more robust against future updates. +# Doxygen will copy the style sheet file to the output directory. For an example +# see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. -HTML_ALIGN_MEMBERS = YES +HTML_EXTRA_STYLESHEET = -# If the GENERATE_HTMLHELP tag is set to YES, additional index files -# will be generated that can be used as input for tools like the -# Microsoft HTML help workshop to generate a compressed HTML help file (.chm) -# of the generated HTML documentation. +# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the HTML output directory. Note +# that these files will be copied to the base HTML output directory. Use the +# $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these +# files. In the HTML_STYLESHEET file, use the file name only. Also note that the +# files will be copied as-is; there are no commands or markers available. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_FILES = + +# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen +# will adjust the colors in the stylesheet and background images according to +# this color. Hue is specified as an angle on a colorwheel, see +# http://en.wikipedia.org/wiki/Hue for more information. For instance the value +# 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 +# purple, and 360 is red again. +# Minimum value: 0, maximum value: 359, default value: 220. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_HUE = 220 + +# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors +# in the HTML output. For a value of 0 the output will use grayscales only. A +# value of 255 will produce the most vivid colors. +# Minimum value: 0, maximum value: 255, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_SAT = 100 + +# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the +# luminance component of the colors in the HTML output. Values below 100 +# gradually make the output lighter, whereas values above 100 make the output +# darker. The value divided by 100 is the actual gamma applied, so 80 represents +# a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not +# change the gamma. +# Minimum value: 40, maximum value: 240, default value: 80. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_GAMMA = 80 + +# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML +# page will contain the date and time when the page was generated. Setting this +# to NO can help when comparing the output of multiple runs. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_TIMESTAMP = YES + +# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML +# documentation will contain sections that can be hidden and shown after the +# page has loaded. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_DYNAMIC_SECTIONS = NO + +# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries +# shown in the various tree structured indices initially; the user can expand +# and collapse entries dynamically later on. Doxygen will expand the tree to +# such a level that at most the specified number of entries are visible (unless +# a fully collapsed tree already exceeds this amount). So setting the number of +# entries 1 will produce a full collapsed tree by default. 0 is a special value +# representing an infinite number of entries and will result in a full expanded +# tree by default. +# Minimum value: 0, maximum value: 9999, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_INDEX_NUM_ENTRIES = 100 + +# If the GENERATE_DOCSET tag is set to YES, additional index files will be +# generated that can be used as input for Apple's Xcode 3 integrated development +# environment (see: http://developer.apple.com/tools/xcode/), introduced with +# OSX 10.5 (Leopard). To create a documentation set, doxygen will generate a +# Makefile in the HTML output directory. Running make will produce the docset in +# that directory and running make install will install the docset in +# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at +# startup. See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html +# for more information. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_DOCSET = NO + +# This tag determines the name of the docset feed. A documentation feed provides +# an umbrella under which multiple documentation sets from a single provider +# (such as a company or product suite) can be grouped. +# The default value is: Doxygen generated docs. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_FEEDNAME = "Doxygen generated docs" + +# This tag specifies a string that should uniquely identify the documentation +# set bundle. This should be a reverse domain-name style string, e.g. +# com.mycompany.MyDocSet. Doxygen will append .docset to the name. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_BUNDLE_ID = org.doxygen.Project + +# The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify +# the documentation publisher. This should be a reverse domain-name style +# string, e.g. com.mycompany.MyDocSet.documentation. +# The default value is: org.doxygen.Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_PUBLISHER_ID = org.doxygen.Publisher + +# The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher. +# The default value is: Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_PUBLISHER_NAME = Publisher + +# If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three +# additional HTML index files: index.hhp, index.hhc, and index.hhk. The +# index.hhp is a project file that can be read by Microsoft's HTML Help Workshop +# (see: http://www.microsoft.com/en-us/download/details.aspx?id=21138) on +# Windows. +# +# The HTML Help Workshop contains a compiler that can convert all HTML output +# generated by doxygen into a single compiled HTML file (.chm). Compiled HTML +# files are now used as the Windows 98 help format, and will replace the old +# Windows help format (.hlp) on all Windows platforms in the future. Compressed +# HTML files also contain an index, a table of contents, and you can search for +# words in the documentation. The HTML workshop also contains a viewer for +# compressed HTML files. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_HTMLHELP = NO -# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can -# be used to specify the file name of the resulting .chm file. You -# can add a path in front of the file if the result should not be +# The CHM_FILE tag can be used to specify the file name of the resulting .chm +# file. You can add a path in front of the file if the result should not be # written to the html output directory. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. -CHM_FILE = +CHM_FILE = -# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can -# be used to specify the location (absolute path including file name) of -# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run -# the HTML help compiler on the generated index.hhp. +# The HHC_LOCATION tag can be used to specify the location (absolute path +# including file name) of the HTML help compiler ( hhc.exe). If non-empty +# doxygen will try to run the HTML help compiler on the generated index.hhp. +# The file has to be specified with full path. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. -HHC_LOCATION = +HHC_LOCATION = -# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag -# controls if a separate .chi index file is generated (YES) or that -# it should be included in the master .chm file (NO). +# The GENERATE_CHI flag controls if a separate .chi index file is generated ( +# YES) or that it should be included in the master .chm file ( NO). +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. GENERATE_CHI = NO -# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag -# controls whether a binary table of contents is generated (YES) or a -# normal table of contents (NO) in the .chm file. +# The CHM_INDEX_ENCODING is used to encode HtmlHelp index ( hhk), content ( hhc) +# and project file content. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +CHM_INDEX_ENCODING = + +# The BINARY_TOC flag controls whether a binary table of contents is generated ( +# YES) or a normal table of contents ( NO) in the .chm file. Furthermore it +# enables the Previous and Next buttons. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. BINARY_TOC = NO -# The TOC_EXPAND flag can be set to YES to add extra items for group members -# to the contents of the HTML help documentation and to the tree view. +# The TOC_EXPAND flag can be set to YES to add extra items for group members to +# the table of contents of the HTML help documentation and to the tree view. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. TOC_EXPAND = NO -# The DISABLE_INDEX tag can be used to turn on/off the condensed index at -# top of each HTML page. The value NO (the default) enables the index and -# the value YES disables it. +# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and +# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that +# can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help +# (.qch) of the generated HTML documentation. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_QHP = NO + +# If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify +# the file name of the resulting .qch file. The path specified is relative to +# the HTML output folder. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QCH_FILE = + +# The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help +# Project output. For more information please see Qt Help Project / Namespace +# (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace). +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_NAMESPACE = org.doxygen.Project + +# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt +# Help Project output. For more information please see Qt Help Project / Virtual +# Folders (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#virtual- +# folders). +# The default value is: doc. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_VIRTUAL_FOLDER = doc + +# If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom +# filter to add. For more information please see Qt Help Project / Custom +# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- +# filters). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_CUST_FILTER_NAME = + +# The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the +# custom filter to add. For more information please see Qt Help Project / Custom +# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- +# filters). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_CUST_FILTER_ATTRS = + +# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this +# project's filter section matches. Qt Help Project / Filter Attributes (see: +# http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_SECT_FILTER_ATTRS = + +# The QHG_LOCATION tag can be used to specify the location of Qt's +# qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the +# generated .qhp file. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHG_LOCATION = + +# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be +# generated, together with the HTML files, they form an Eclipse help plugin. To +# install this plugin and make it available under the help contents menu in +# Eclipse, the contents of the directory containing the HTML and XML files needs +# to be copied into the plugins directory of eclipse. The name of the directory +# within the plugins directory should be the same as the ECLIPSE_DOC_ID value. +# After copying Eclipse needs to be restarted before the help appears. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_ECLIPSEHELP = NO + +# A unique identifier for the Eclipse help plugin. When installing the plugin +# the directory name containing the HTML and XML files should also have this +# name. Each documentation set should have its own identifier. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES. + +ECLIPSE_DOC_ID = org.doxygen.Project + +# If you want full control over the layout of the generated HTML pages it might +# be necessary to disable the index and replace it with your own. The +# DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top +# of each HTML page. A value of NO enables the index and the value YES disables +# it. Since the tabs in the index contain the same information as the navigation +# tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. DISABLE_INDEX = NO -# This tag can be used to set the number of enum values (range [1..20]) -# that doxygen will group on one line in the generated HTML documentation. - -ENUM_VALUES_PER_LINE = 1 - -# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be -# generated containing a tree-like index structure (just like the one that -# is generated for HTML Help). For this to work a browser that supports -# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+, -# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are -# probably better off using the HTML help feature. +# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index +# structure should be generated to display hierarchical information. If the tag +# value is set to YES, a side panel will be generated containing a tree-like +# index structure (just like the one that is generated for HTML Help). For this +# to work a browser that supports JavaScript, DHTML, CSS and frames is required +# (i.e. any modern browser). Windows users are probably better off using the +# HTML help feature. Via custom stylesheets (see HTML_EXTRA_STYLESHEET) one can +# further fine-tune the look of the index. As an example, the default style +# sheet generated by doxygen has an example that shows how to put an image at +# the root of the tree instead of the PROJECT_NAME. Since the tree basically has +# the same information as the tab index, you could consider setting +# DISABLE_INDEX to YES when enabling this option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_TREEVIEW = YES -# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be -# used to set the initial width (in pixels) of the frame in which the tree -# is shown. +# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that +# doxygen will group on one line in the generated HTML documentation. +# +# Note that a value of 0 will completely suppress the enum values from appearing +# in the overview section. +# Minimum value: 0, maximum value: 20, default value: 4. +# This tag requires that the tag GENERATE_HTML is set to YES. + +ENUM_VALUES_PER_LINE = 1 + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used +# to set the initial width (in pixels) of the frame in which the tree is shown. +# Minimum value: 0, maximum value: 1500, default value: 250. +# This tag requires that the tag GENERATE_HTML is set to YES. TREEVIEW_WIDTH = 250 +# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open links to +# external symbols imported via tag files in a separate window. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +EXT_LINKS_IN_WINDOW = NO + +# Use this tag to change the font size of LaTeX formulas included as images in +# the HTML documentation. When you change the font size after a successful +# doxygen run you need to manually remove any form_*.png images from the HTML +# output directory to force them to be regenerated. +# Minimum value: 8, maximum value: 50, default value: 10. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FORMULA_FONTSIZE = 10 + +# Use the FORMULA_TRANPARENT tag to determine whether or not the images +# generated for formulas are transparent PNGs. Transparent PNGs are not +# supported properly for IE 6.0, but are supported on all modern browsers. +# +# Note that when changing this option you need to delete any form_*.png files in +# the HTML output directory before the changes have effect. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FORMULA_TRANSPARENT = YES + +# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see +# http://www.mathjax.org) which uses client side Javascript for the rendering +# instead of using prerendered bitmaps. Use this if you do not have LaTeX +# installed or if you want to formulas look prettier in the HTML output. When +# enabled you may also need to install MathJax separately and configure the path +# to it using the MATHJAX_RELPATH option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +USE_MATHJAX = NO + +# When MathJax is enabled you can set the default output format to be used for +# the MathJax output. See the MathJax site (see: +# http://docs.mathjax.org/en/latest/output.html) for more details. +# Possible values are: HTML-CSS (which is slower, but has the best +# compatibility), NativeMML (i.e. MathML) and SVG. +# The default value is: HTML-CSS. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_FORMAT = HTML-CSS + +# When MathJax is enabled you need to specify the location relative to the HTML +# output directory using the MATHJAX_RELPATH option. The destination directory +# should contain the MathJax.js script. For instance, if the mathjax directory +# is located at the same level as the HTML output directory, then +# MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax +# Content Delivery Network so you can quickly see the result without installing +# MathJax. However, it is strongly recommended to install a local copy of +# MathJax from http://www.mathjax.org before deployment. +# The default value is: http://cdn.mathjax.org/mathjax/latest. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest + +# The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax +# extension names that should be enabled during MathJax rendering. For example +# MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_EXTENSIONS = + +# The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces +# of code that will be used on startup of the MathJax code. See the MathJax site +# (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an +# example see the documentation. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_CODEFILE = + +# When the SEARCHENGINE tag is enabled doxygen will generate a search box for +# the HTML output. The underlying search engine uses javascript and DHTML and +# should work on any modern browser. Note that when using HTML help +# (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET) +# there is already a search function so this one should typically be disabled. +# For large projects the javascript based search engine can be slow, then +# enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to +# search using the keyboard; to jump to the search box use + S +# (what the is depends on the OS and browser, but it is typically +# , /