Lines Matching refs:That
123 The library was designed such that new ciphers/hashes/PRNGs can be added at run-time and the existing API
125 block cipher and hash function to ensure that they compile and execute to the published design specifications. The library
132 provide all of the tools required to build such functionality. LibTomCrypt was designed to be a flexible library that
139 \item I am too lazy to figure out someone else's API. I'd rather invent my own simpler API and use that.
143 The idea is that I am not striving to replace OpenSSL or Crypto++ or Cryptlib or etc. I'm trying to write my
148 on an x86 with zero problems. The consistent API also means that if you learn how to use Blowfish with the library you
150 that can be used to make a program automatically pick between ciphers, hashes and PRNGs at run-time. That means your
155 without having to use configure scripts. This means that the library will work with platforms where development
161 with \textit{cycles per byte} timings that are comparable (and often favourable) to other libraries such as OpenSSL and
172 that for the PRNG needs within the library (\textit{e.g. making a RSA key}). All the developer has to do
173 is write a descriptor and the few support routines required for the device. After that the rest of the
180 mode routines for every single cipher. That means every time you add or remove a cipher from the library
182 are not directly tied to the ciphers. That is a new cipher can be added to the library by simply providing
183 the key setup, ECB decrypt and encrypt and test vector routines. After that all five chaining mode routines
195 of the ciphers and hashes are patent free or under patents that have since expired.
198 the ciphers you just can't advertise that you are doing so.
227 that return {\bf int} will return {\bf CRYPT\_OK} if the function was successful, or one of the many error codes
228 if it failed. Certain functions that return int will return $-1$ to indicate an error. These functions will be explicitly
255 that is not an issue.
319 Certain functions such as (for example) \textit{rsa\_export()} give an output that is variable length. To prevent buffer overflows you
353 \textit{x} so that the calling application will know how many bytes were used.
356 support this so please check the source before you rely on it doing that.
358 \mysection{Functions that need a PRNG}
391 \mysection{Functions that use Arrays of Octets}
392 Most functions require inputs that are arrays of the data type \textit{unsigned char}. Whether it is a symmetric key, IV
393 for a chaining mode or public key packet it is assumed that regardless of the actual size of \textit{unsigned char} only the
403 LibTomCrypt provides several block ciphers with an ECB block mode interface. It is important to first note that you
412 functions which are (given that XXX is the name of the cipher) the following:
425 that you should only used this scheduled key with the intended cipher. For example, if you call \textit{blowfish\_setup()} do not
444 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
496 An example snippet that encodes a block with Blowfish in ECB mode.
555 ciphers are configured such that the default number of rounds provide adequate security for the given block and key
590 in bytes. As a good rule of thumb it is assumed that the cipher supports
592 of rounds that will be used.
647 The \textit{encrypt only} descriptors are useful for applications that only use the encryption function of the cipher. Algorithms such
652 Note that for \textit{DES} and \textit{3DES} they use 8 and 24 byte keys but only 7 and 21 [respectively] bytes of the keys are in
657 Note that \textit{Twofish} has additional configuration options (Figure \ref{fig:twofishopts}) that take place at build time. These options are found in
659 to not pre-compute the Twofish \textit{$g(X)$} function as a set of four $8 \times 32$ s-boxes. This means that a scheduled
762 This snippet is a small program that registers Rijndael.
786 It is important that the initial vector be unique and preferably random for each message encrypted under the same key.
807 Note that in this library the output feedback width is equal to the size of the block cipher. That is this mode is used
828 \item Allows the encryption of block sizes that are not equal to the size of the block cipher.
830 The CTR, CFB and OFB routines provided allow you to encrypt block sizes that differ from the ciphers block size. They
849 you want is XXX there is a structure called \textit{symmetric\_XXX} that will contain the information required to
850 use that mode. They have identical setup routines (except CTR and ECB mode):
878 of the cipher you choose. It is important that the IV be random for each unique message you want to encrypt. The
883 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.
909 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}
1072 of 16. The LRW code uses a fast tweak update such that consecutive blocks are encrypted faster than if random seeking where used.
1086 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
1098 The F8 Chaining mode (see RFC 3711 for instance) is yet another chaining mode for block ciphers. It behaves much like CTR mode in that it XORs a keystream
1099 against the plaintext to encrypt. F8 mode comes with the additional twist that the counter value is secret, encrypted by a \textit{salt key}. We
1161 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,
1163 authentication\footnote{Note that since EAX only requires OMAC and CTR you may use \textit{encrypt only} cipher descriptors with this mode.}.
1164 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.
1166 The \textit{header} data is meant to be meta--data associated with a stream that isn't private (e.g., protocol messages). It can
1167 be added at anytime during an EAX stream, and is part of the authentication tag. That is, changes in the meta-data can be detected by changes in the output tag.
1192 When this function completes, the \textit{eax} state will be initialized such that you can now either have data decrypted or
1243 This requires that the AES (or Rijndael) block cipher be registered with the cipher\_descriptor table first.
1333 . OCB is an encryption protocol that simultaneously provides authentication. It is slightly faster to use than EAX mode
1346 and the random \textit{nonce}. Note that \textit{nonce} must be a random (public) string the same length as the block ciphers
1364 They assume that \textit{pt} and \textit{ct} are the same size as the block cipher's block size. Note that you cannot call
1382 This will terminate an encrypt stream \textit{ocb}. If you have trailing bytes of plaintext that will not complete a block
1386 Note that \textit{ptlen} must be less than or equal to the block size of block cipher chosen. Also note that if you have
1439 CCM is a NIST proposal for encrypt + authenticate that
1441 function that performs the protocol.
1469 allowable that $pt = ct$. The \textit{direction} variable indicates whether encryption (direction $=$ \textbf{CCM\_ENCRYPT}) or
1625 This will reset the GCM state \textit{gcm} to the state that gcm\_init() left it. The user would then call gcm\_add\_iv(), gcm\_add\_aad(), etc.
1766 this means that:
1783 This function will finish up the hash and store the result in the \textit{out} array. You must ensure that \textit{out} is long
1793 example snippet that hashes a message with md5 is given below.
1855 You can use the table to indirectly call a hash function that is chosen at run-time. For example:
1901 length. This provides a simple size you can set your automatic arrays to that will not get overrun.
2015 applicable block ciphers (such as AES) can be turned into hash functions that other LTC functions can use. In
2068 It is highly recommended that you \textbf{not} use the MD4 or MD5 hashes for the purposes of digital signatures or authentication codes.
2072 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
2078 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
2082 The HMAC support works much like the normal hash functions except that the initialization routine requires you to pass a key
2083 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
2093 to use to authenticate the message. The \textit{key} parameter is the pointer to the array of chars that make up the key. The \textit{keylen} parameter is the
2246 Which will terminate the OMAC and output the \textit{tag} (MAC) to \textit{out}. Note that unlike the HMAC and other code
2248 specification states that the output may be truncated. So if you pass in $outlen = 5$ and use AES as your cipher than
2338 protocol is another MAC algorithm that relies solely on a symmetric-key block cipher. It uses essentially the same
2383 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
2423 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
2441 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
2580 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
2703 so that you can later resume the PRNG call the following.
2713 the export is meant to be used as a \textit{seed file}. That is, when the program starts up there will not likely
2714 be that much entropy available. To import a state to seed a PRNG call the following function.
2727 Note that importing a state will not \textit{resume} the PRNG from where it left off. That is, if you export
2740 import function and go on your way. It is ideal that (as soon as possible) after start up you export a
2741 fresh state. This helps in the case that the program aborts or the machine is powered down without
2744 Note that even if you have a state to import it is important to add new entropy to the state. However,
2764 Below is a simple snippet to read 10 bytes from Yarrow. It is important to note that this snippet is {\bf NOT} secure since
2796 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
2874 Fortuna is slightly less flexible than Yarrow in the sense that it only works with the AES block cipher
2875 and SHA--256 hash function. Technically, Fortuna will work with any block cipher that accepts a 256--bit
2876 key, and any hash that produces at least a 256--bit output. However, to make the implementation simpler
2879 Fortuna is more secure than Yarrow in the sense that attackers who learn parts of the entropy being
2880 added to the PRNG learn far less about the state than that of Yarrow. Without getting into to many
2883 recover from that problem until new entropy is added to the pool and put to use through the ready() function.
2887 RC4 is an old stream cipher that can also double duty as a PRNG in a pinch. You key RC4 by
2895 the fact that faster alternatives exist.
2908 that is a multiple of four bytes.
2958 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
2960 PRNG. Computers are deterministic that try hard not to stray from pre--determined paths. This makes gathering entropy needed to seed a PRNG
2963 There is one small function that may help on certain platforms:
2975 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
2987 the callback in \textit{rng\_get\_bytes()}. It is highly recommended that you use this function to setup your PRNGs unless you have a
3026 requires to be started, that is you need not call the start, add\_entropy, or ready functions. For example, consider
3062 PKCS \#1 v1.5 padding is so simple that both signature and encryption padding are performed by the same function. Note: the
3063 signature padding does \textbf{not} include the ASN.1 padding required. That is performed by the rsa\_sign\_hash\_ex() function
3130 tag that can be applied to the encoding. This is useful to identify which system encoded the message. If no variance is desired then
3142 Note that when the message is padded it still has not been RSA encrypted. You must pass the output of this function to
3161 This function decodes an OAEP encoded message and outputs the original message that was passed to the OAEP encoder. \textit{msg} is the
3174 PSS encoding is the second half of the PKCS \#1 standard which is padding to be applied to messages that are signed.
3198 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().
3225 RSA is a public key algorithm that is based on the inability to find the \textit{e-th} root modulo a composite of unknown
3231 $\mbox{lcm}(p - 1, q - 1)$. The public key consists of the composite $N$ and some integer $e$ such that
3235 A person who wants to encrypt with your public key simply forms an integer (the plaintext) $M$ such that
3241 Currently RSA is a difficult system to cryptanalyze provided that both primes are large and not close to each other.
3243 the plaintext to be encrypted than it is possible that $M^3 < N$ in which case finding the cube-root would be trivial.
3268 least 128 bytes, and no more than 512 bytes in size (\textit{that is from 1024 to 4096 bits}).
3282 To do raw work with the RSA function, that is without padding, use the following function:
3596 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
3602 The library provides a set of core ECC functions as well that are designed to be the Elliptic Curve analogy of all of the
3603 Diffie-Hellman routines in the previous chapter. Elliptic curves (of certain forms) have the benefit that they are harder
3605 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
3616 They are all curves over the integers modulo a prime. The curves have the basic equation that is:
3621 The variable $b$ is chosen such that the number of points is nearly maximal. In fact the order of the base points $\beta$
3622 provided are very close to $p$ that is $\vert \vert \phi(\beta) \vert \vert \approx \vert \vert p \vert \vert$. The curves
3629 As of v1.12 of LibTomCrypt, support for Fixed Point ECC point multiplication has been added. It is a generic optimization that is
3643 all subsequent point multiplications with that point will use the faster algorithm.
3706 /** The prime that defines the field (encoded in hex) */
3737 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
3872 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
3887 to use some form of challenge response in that case (e.g. compute a MAC of a known string).
3938 The ECC \textit{key} must be the public (or private) ECC key corresponding to the key that performed the signature.
3944 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
3959 now so that others can interoperate with this library.
3965 -- check that g^q mod p == 1
3966 -- and that 1 < g < p - 1
3972 -- check that y^q mod p == 1
3973 -- and that 1 < y < p - 1
3979 -- check that g^q mod p == 1
3980 -- and that 1 < g < p - 1
3986 -- check that y^q mod p == 1
3987 -- and that 1 < y < p - 1
4054 Tests one and two ensure that
4055 function. Tests three and four ensure that the generator $g$ is not set to a trivial value which would make signature
4056 forgery easier. Test five ensures that $q$ divides the order of multiplicative sub-group of $\Z/p\Z$. Test six
4057 ensures that the generator actually generates a prime order group. Tests seven and eight ensure that the public key
4058 is within range and belongs to a group of prime order. Note that test eight does not prove that $g$ generated $y$ only
4059 that $y$ belongs to a multiplicative sub-group of order $q$.
4091 To verify a hash created with that function use the following function:
4145 To export a DSA key so that it can be transported use the following function:
4334 It is ideal that you cast the \textit{size} values to unsigned long to ensure that the proper data type is passed to the function. Constants such as \textit{1} without
4355 on the size parameters. This forces the compiler to pass the numbers as the required \textbf{unsigned long} type that the function expects.
4360 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
4366 SETs use the same array structure of ltc\_asn1\_list that the SEQUENCE functions use. They are encoded with the following function:
4396 It handles the fact that
4403 used to store objects deterministically based solely on their encoding. It uses the same array structure of ltc\_asn1\_list that the SEQUENCE functions
4548 that the build platform honours the run--time platforms character conventions.
4572 that the build platform honours the run-time platforms character conventions.
4597 intend to use the ISO C functions for working with wide--char arrays, you should make sure that wchar\_t has been defined previously.
4639 It is suggested that decoded data be further scrutinized (e.g. days of month in particular).
4731 that of an IA5 STRING. The sibbling will now be the \textit{LoginToken} SEQUENCE. The sibbling has a child node which points to the \textit{passwdHash} OCTET STRING.
4746 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
4860 put any character (that is not in the above sequence) in between any character of the encoders output. You may not however,
4888 $\left ( { 1 \over 4 } \right )^{8} = 2^{-16}$. In practice the probability of error is in fact much lower than that.
4896 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
4908 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
4909 it returns an error that the value in \textit{result} is undefined. To make
4926 would be impossible. The requirement that one be setup correctly is vitally important, and to address this point the library
4927 does provide two RNG sources that will address the largest amount of end users as possible. The \textit{sprng} PRNG provides an easy to
4931 entropy. This manual is not designed to be a text on cryptography. I would just like to highlight that when you design
4946 A neat bonus to the registry system is that you can add external algorithms that are not part of the library without
4948 write the few functions required plus a descriptor. After registering your PRNG, all of the library functions that
4964 Note that $n$ is not the bit-length but the magnitude. For example, for a 1024-bit key $n = 2^{1024}$. The work required
5020 The rest of the code uses state variables you must pass it such as hash\_state, hmac\_state, etc. This means that if each
5031 each new release that will make the library even more flexible. Each of the classes of functions can be disabled during
5038 configured. Note that LibTomCrypt can be built with no internal math descriptors. This means that one must be provided at either
5039 build, or run time for the application. LibTomCrypt comes with three math descriptors that provide a standard interface to math
5137 that GCC expects for global archives.
5148 Note that \textbf{EXTRALIBS} is not required if you are only making and installing the static library but none of the test programs.
5158 That will build LibTomCrypt (including the TomsFastMath descriptor), and install it in the default locations indicated previously. You can enable
5169 Note that even if you include the built--in descriptors you must link against the source library as well.
5175 This will compile \textit{myprogram} and link it against the LibTomCrypt library as well as TomsFastMath (which must have been previously installed). Note that
5176 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
5182 that you \textbf{must} specify the \textbf{EXTRALIBS} variable at install time.
5198 stderr and raising a SIGABRT signal. This is provided so all platforms that use LibTomCrypt can have an error that functions
5226 The rng\_get\_bytes() function can call a function that requires the clock() function. These macros let you override
5230 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
5235 When this functions is defined the functions that store key material on the stack will clean up afterwards.
5236 Assumes that you have no memory paging with the stack.
5244 which can be auto-detected. This macro ensures that they are never enabled.
5248 cbc\_encrypt() that it can safely XOR multiple octets in one step by using a larger data type. This has the benefit of
5290 Twofish is a 128-bit symmetric block cipher that is provided within the library. The cipher itself is flexible enough
5315 When this is activated all of the descriptor table functions will use pthread locking to ensure thread safe updates to the tables. Note that
5316 it doesn't prevent a thread that is passively using a table from being messed up by another thread that updates the table.
5327 The library comes with three math descriptors that allow you to interface the public key cryptography API to freely available math
5331 In the test demos that use the libraries the additional flags \textbf{USE\_GMP}, \textbf{USE\_LTM}, and \textbf{USE\_TFM} can be defined
5342 That will build and install the library with all descriptors (and link against all), but only use TomsFastMath in the timing demo.
5346 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
5347 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
5351 That works well for most cases but there are times where performance is of the essence. This API allows optimized routines to be dropped in--place of the existing
5352 portable routines. For instance, hand optimized assembler versions of AES could be provided. Any existing function that uses the cipher could automatically use
5353 the optimized code without re--writing. This also paves the way for hardware drivers that can access hardware accelerated cryptographic devices.
5356 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
5655 Inside the \textit{symmetric\_key} union there is a \textit{void *data} which you can use to allocate data if you need a data structure that does not fit with the existing
5656 ones provided. Just make sure in your \textit{done()} function that you free the allocated memory.
5664 \textbf{CRYPT\_NOP} to indicate that no testing was performed.
5668 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
5700 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
5708 state variables and updated them prior to returning. Note that you may want to disable \textbf{LRW\_TABLES} in \textit{tomcrypt\_custom.h} if you intend
5713 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
5715 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
5740 This function is meant for accelerated GCM encryption or decryption. It processes the entire packet in one call. Note that the setup() function will not
5835 The \textit{blocksize} variable indicates the length of input (in octets) that the hash processes in a given
5845 This processes message bytes. The algorithm must accept any length of input that the hash would allow. The input is not
5961 An exported PRNG state is data that the PRNG can later import to resume activity. They're not meant to resume \textit{the same session}
6030 /** Get the number of digits that represent the number
6405 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
6406 than an \textit{unsigned long} that is also acceptable as the \textit{bits\_per\_digit} parameter will specify this.
6414 that (x,y,z) => (x/z^2, y/z^3, 1) when interpreted as affine */
6476 to the \textit{out} buffer. The output must be zero padded (leading bytes) so that the length of the output matches the length of the modulus (in bytes). For example,
