diff --git a/nettle.texinfo b/nettle.texinfo index ec02237bf00fea7a86c291062591e176488ea34e..6ac9705c50c6f127fce676f6e12bfd82d098e36a 100644 --- a/nettle.texinfo +++ b/nettle.texinfo @@ -97,7 +97,7 @@ translation approved by the Free Software Foundation. @top Nettle This document describes the nettle low-level cryptographic library. You -can use the library directly from your C-programs, or (recommended) +can use the library directly from your C programs, or (recommended) write or use an object-oriented wrapper for your favorite language or application. @@ -139,7 +139,7 @@ In particular, Nettle doesn't do algorithm selection. It doesn't do memory allocation. It doesn't do any I/O. The idea is that one can build several application and context specific -interfaces on top of Nettle, and share the code, test-cases, benchmarks, +interfaces on top of Nettle, and share the code, test cases, benchmarks, documentation, etc. For this first version, the only application using Nettle is LSH, and it uses an object-oriented abstraction on top of the library. @@ -489,7 +489,7 @@ These are all the hash functions that Nettle implements. A @dfn{cipher} is a function that takes a message or @dfn{plaintext} and a secret @dfn{key} and transforms it to a @dfn{ciphertext}. Given only the ciphertext, but not the key, it should be hard to find the -clear-text. Given matching pairs of plaintext and ciphertext, it should +plaintext. Given matching pairs of plaintext and ciphertext, it should be hard to find the key. There are two main classes of ciphers: Block ciphers and stream ciphers. @@ -519,7 +519,7 @@ same as for a One Time Pad: @emph{never} ever use the same key twice. A common misconception is that encryption, by itself, implies authentication. Say that you and a friend share a secret key, and you -receive an encrypted message. You apply the key, and get a clear-text +receive an encrypted message. You apply the key, and get a plaintext message that makes sense to you. Can you then be sure that it really was your friend that wrote the message you're reading? The answer is no. For example, if you were using a block cipher in ECB mode, an attacker may @@ -977,17 +977,17 @@ ones without weak keys or other oddity. @comment node-name, next, previous, up @section Cipher Block Chaining -When using @acronym{CBC} mode, clear-text blocks are not encrypted +When using @acronym{CBC} mode, plaintext blocks are not encrypted independently of each other, like in Electronic Cook Book mode. Instead, when encrypting a block in @acronym{CBC} mode, the previous ciphertext -block is XOR:ed with the clear-text before it is fed to the block cipher. +block is XOR:ed with the plaintext before it is fed to the block cipher. When encrypting the first block, a random block called an @dfn{IV}, or Initialization Vector, is used as the ``previous ciphertext block''. The IV should be chosen randomly, but it need not be kept secret, and can even be transmitted in the clear together with the encrypted data. -In symbols, if @code{E_k} is the encryption function of a block-cipher, -and @code{IV} is the initialization vector, then @code{n} clear-text blocks +In symbols, if @code{E_k} is the encryption function of a block cipher, +and @code{IV} is the initialization vector, then @code{n} plaintext blocks @code{M_1},@dots{} @code{M_n} are transformed into @code{n} ciphertext blocks @code{C_1},@dots{} @code{C_n} as follows: @@ -1102,7 +1102,7 @@ such constructions have weaknesses. A better construction is For an underlying hash function @code{H}, with digest size @code{l} and internal block size @code{b}, @acronym{HMAC-H} is constructed as -follows: From a given key @code{k}, two distinct sub-keys @code{k_i} and +follows: From a given key @code{k}, two distinct subkeys @code{k_i} and @code{k_o} are constructed, both of length @code{b}. The @acronym{HMAC-H} of a message @code{m} is then computed as @code{H(k_o | H(k_i | m))}, where @code{|} denotes string concatenation. @@ -1123,7 +1123,7 @@ functions: @deftypefun void hmac_set_key (void *@var{outer}, void *@var{inner}, void *@var{state}, const struct nettle_hash *@var{H}, unsigned @var{length}, const uint8_t *@var{key}) Initializes the three context structs from the key. The @var{outer} and -@var{inner} contexts corresponds to the sub-keys @code{k_o} and +@var{inner} contexts corresponds to the subkeys @code{k_o} and @code{k_i}. @var{state} is used for hashing the message, and is initialized as a copy of the @var{inner} context. @end deftypefun @@ -1709,12 +1709,12 @@ Yarrow-256, which is similar, but uses @acronym{SHA256} and Yarrow was an almost finished project, the paper mentioned above is the closest thing to a specification for it, but some smaller details are left out. There is no official reference implementation or test cases. -This section includes an overview of Yarrow, but the details of +This section includes an overview of Yarrow, but for the details of Yarrow-256, as implemented by Nettle, you have to consult the source code. Maybe a complete specification can be written later. Yarrow can use many sources (at least two are needed for proper -reseeding), and two randomness "pools", referred to the "slow pool" and +reseeding), and two randomness "pools", referred to as the "slow pool" and the "fast pool". Input from the sources is fed alternatingly into the two pools. When one of the sources has contributed 100 bits of entropy to the fast pool, a "fast reseed" happens and the fast pool is mixed @@ -1810,7 +1810,7 @@ Initializes the context. @end deftypefun @deftypefun unsigned yarrow_key_event_estimate(struct yarrow_key_event_ctx *@var{ctx}, unsigned @var{key}, unsigned @var{time}) -@var{key} is the id of the key (ASCII value, hardware key-code, X +@var{key} is the id of the key (ASCII value, hardware key code, X keysym, @dots{} it doesn't matter), and @var{time} is the timestamp of the event. The time must be given in units matching the resolution by which you read the clock. If you read the clock with microsecond @@ -1865,7 +1865,7 @@ variable @code{des_check_key}, and the functions @code{des_cbc_cksum} @node Nettle soup, Installation, Reference, Top @comment node-name, next, previous, up @chapter Traditional Nettle Soup -For the serious nettle hacker, here is a recipe for nettle-soup. 4 servings +For the serious nettle hacker, here is a recipe for nettle soup. 4 servings @itemize @w{} @item