Documentation about ARCTWO.

Rev: src/nettle/nettle.texinfo:1.26

diff --git a/nettle.texinfo b/nettle.texinfo
index ed31484858079aeeaa3fd0d94a7ccf5eb57ab128..e6c00c2251141861137118171e3887e689cc7498 100644 (file)
--- a/nettle.texinfo
+++ b/nettle.texinfo
@@ -23,7 +23,7 @@
 Draft manual for the Nettle library. This manual corresponds to version
 @value{UPDATED-FOR}.
 
-Copyright 2001 @value{AUTHOR}
+Copyright 2001, 2004 @value{AUTHOR}
 
 Permission is granted to make and distribute verbatim
 copies of this manual provided the copyright notice and
@@ -172,6 +172,11 @@ by Rafael Sevilla. Released under the LGPL.
 The implementation of the ARCFOUR (also known as RC4) cipher is written
 by Niels Möller. Released under the LGPL.
 
+@item ARCTWO
+The implementation of the ARCTWO (also known as RC2) cipher is written
+by Nikos Mavroyanopoulos and modified by Werner Koch and Simon
+Josefsson. Released under the LGPL.
+
 @item BLOWFISH
 The implementation of the BLOWFISH cipher is written by Werner Koch,
 copyright owned by the Free Software Foundation. Also hacked by Ray
@@ -358,7 +363,7 @@ To start over, you can call @code{md5_init} at any time.
 
 @subsection @acronym{MD2}
 
-MD2 is another hash function of Ronald Rivests', described in
+MD2 is another hash function of Ronald Rivest's, described in
 @cite{RFC 1319}. It outputs message digests of 128 bits, or 16 octets.
 Nettle defines MD2 in @file{<nettle/md2.h>}.
 
@@ -699,6 +704,67 @@ them one after another. The result is the same as if you had called
 @code{arcfour_crypt} only once with all the data.
 @end deftypefun
 
+@subsection ARCTWO
+ARCTWO (also known as the trade marked name RC2) is a block cipher
+specified in RFC 2268. Nettle also include a variation of the ARCTWO
+set key operation that lack one step, to be compatible with the
+reverse engineered RRC2 cipher description, as described in a Usenet
+post to @code{sci.crypt} by Peter Gutmann.
+
+ARCTWO uses a block size of 64 bits, and variable key-size ranging
+from 1 to 128 octets. Besides the key, ARCTWO also has a second
+parameter to key setup, the number of effective key bits, @code{ekb}.
+This parameter can be used to artificially reduce the key size. In
+practice, @code{ekb} is usually set equal to the input key size.
+Nettle defines ARCTWO in @file{<nettle/arctwo.h>}.
+
+We do not recommend the use of ARCTWO; the Nettle implementation is
+provided primarily for interoperability with existing applications and
+standards.
+
+@deftp {Context struct} {struct arctwo_ctx}
+@end deftp
+
+@defvr Constant ARCTWO_BLOCK_SIZE
+The AES block-size, 8
+@end defvr
+
+@defvr Constant ARCTWO_MIN_KEY_SIZE
+@end defvr
+
+@defvr Constant ARCTWO_MAX_KEY_SIZE
+@end defvr
+
+@defvr Constant ARCTWO_KEY_SIZE
+Default ARCTWO key size, 8
+@end defvr
+
+@deftypefun void arctwo_set_key_ekb (struct arctwo_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{key}, unsigned @var{ekb})
+@deftypefunx void arctwo_set_key (struct arctwo_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{key})
+@deftypefunx void arctwo_set_key_gutmann (struct arctwo_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{key})
+Initialize the cipher. The same function is used for both encryption
+and decryption. The first function is the most general one, which lets
+you provide both the variable size key, and the desired effective key
+size (in bits). The maximum value for @var{ekb} is 1024, and for
+convenience, @code{ekb = 0} has the same effect as @code{ekb = 1024}.
+
+@code{arctwo_set_key(ctx, length, key)} is equivalent to
+@code{arctwo_set_key_ekb(ctx, length, key, 8*length)}, and
+@code{arctwo_set_key_gutmann(ctx, length, key)} is equivalent to
+@code{arctwo_set_key_ekb(ctx, length, key, 1024)}
+@end deftypefun
+
+@deftypefun void arctwo_encrypt (struct arctwo_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{dst}, uint8_t *@var{src})
+Encryption function. @var{length} must be an integral multiple of the
+block size. If it is more than one block, the data is processed in ECB
+mode. @code{src} and @code{dst} may be equal, but they must not
+overlap in any other way.
+@end deftypefun
+
+@deftypefun void arctwo_decrypt (struct arctwo_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{dst}, uint8_t *@var{src})
+Analogous to @code{arctwo_encrypt}
+@end deftypefun
+
 @subsection CAST128
 
 CAST-128 is a block cipher, specified in @cite{RFC 2144}. It uses a 64
@@ -1015,8 +1081,13 @@ struct, which is of size @code{context_size}.
 @deftypevrx {Constant Struct} {struct nettle_cipher} nettle_twofish192
 @deftypevrx {Constant Struct} {struct nettle_cipher} nettle_twofish256
 
+@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_arctwo40;
+@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_arctwo64;
+@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_arctwo128;
+@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_arctwo_gutmann128;
+
 Nettle includes such structs for all the @emph{regular} ciphers, i.e.
-ones without weak keys or other oddity.
+ones without weak keys or other oddities.
 @end deftypevr
 
 @node Cipher Block Chaining, Keyed hash functions, Cipher functions, Reference
@@ -2241,4 +2312,5 @@ End:
 @c  LocalWords:  NIST Alice's GMP bignum Diffie Adi Shamir Adleman Euclid's ASN
 @c  LocalWords:  PKCS callbacks Young's urtica dioica autoconf automake SSH tad
 @c  LocalWords:  unguessability reseeding reseed alternatingly keysym subkeys
-@c  LocalWords:  DSA gmp FIPS DSS libdes OpenSSL
+@c  LocalWords:  DSA gmp FIPS DSS libdes OpenSSL ARCTWO Josefsson Nikos Andreas
+@c  LocalWords:  Mavroyanopoulos Sigfridsson Comstedt interoperability