(* OASIS_START *)
(* DO NOT EDIT (digest: e0e395579ad4c8ec0401e3ef76bfc6ab) *)
This is the README file for the cryptokit distribution.

Cryptographic primitives

This library provides a variety of cryptographic primitives that can be used
to implement cryptographic protocols in security-sensitive applications. The
primitives provided include:

- Symmetric-key ciphers: AES, DES, Triple-DES, ARCfour,   in ECB, CBC, CFB
and OFB modes. - Public-key cryptography: RSA encryption, Diffie-Hellman key
agreement. - Hash functions and MACs: SHA-1, SHA-256, SHA-3, RIPEMD160, MD5, 
 and MACs based on AES and DES. - Random number generation. - Encodings and
compression: base 64, hexadecimal, Zlib compression.

Additional ciphers and hashes can easily be used in conjunction with the
library. In particular, basic mechanisms such as chaining modes, output
buffering, and padding are provided by generic classes that can easily be
composed with user-provided ciphers. More generally, the library promotes a
"Lego"-like style of constructing and composing transformations over
character streams.

See the files INSTALL.txt for building and installation instructions. 


(* OASIS_STOP *)

EXTRA REQUIREMENTS:

  - The Zlib C library, version 1.1.3 or up is recommended.
    If it is not installed on your system (look for libz.a or libz.so),
    get it from http://www.gzip.org/, or call configure with the flag
    "--disable-zlib".
    If you are running Linux or BSD, chances are that your distribution
    provides precompiled binaries for this library.

  - If the operating system does not provide the /dev/random device
    (for random number generation), consider installing the EGD
    entropy gathering daemon http://egd.sourceforge.net/
    Without /dev/random nor EGD, this library cannot generate random data
    and RSA keys.  The remainder of the library still works, though.

WARNINGS AND DISCLAIMERS:

  Disclaimer 1: the author is not an expert in cryptography.
  While reasonable care has been taken to select good, widely-used
  implementations of the ciphers and hashes, and follow recommended
  practices found in reputable applied cryptography textbooks,
  you are advised to review thoroughly the implementation of this module
  before using it in a security-critical application.

  Disclaimer 2: some knowledge of cryptography is needed to use
  effectively this library.  A recommended reading is the
  Handbook of Applied Cryptography http://www.cacr.math.uwaterloo.ca/hac/
  Building secure applications out of cryptographic primitives also
  requires a general background in computer security.

  Disclaimer 3: in some countries, the use, distribution, import
  and/or export of cryptographic applications is restricted by law.
  The precise restrictions may depend on the strenght of the cryptography
  used (e.g. key size), but also on its purpose (e.g. confidentiality
  vs. authentication).  It is up to the users of this library to
  comply with regulations applicable in their country.


DESIGN NOTES AND REFERENCES:

  The library is organized around the concept of "transforms".  A transform
  is an object that accepts strings, sub-strings, characters and bytes
  as input, transforms them, and buffers the output.  While it is possible
  to enter all input, then fetch the output, lower memory requirements
  can be achieved by purging the output periodically during data input.

  The AES implementation is the public-domain optimized reference
  implementation by Daemen, Rijmen and Barreto.

  The DES implementation is based on Outerbridge's popular "d3des"
  implementation.  This is not the fastest DES implementation available,
  but one of the cleanest.  Outerbridge's code is marked as public domain.

  The Blowfish implementation is that of Paul Kocher with some
  performance improvements.  It is under the LGPL.  It passes the
  test vectors listed at http://www.schneier.com/code/vectors.txt

  ARCfour (``alleged RC4'') is implemented from scratch, based on the
  algorithm described in Schneier's _Applied_Cryptography_

  SHA-1 is also implemented from scratch, based on the algorithm
  described in the _Handbook_of_Applied_Cryptography_.   It passes the
  FIPS test vectors.

  SHA-256 is implemented from scratch based on FIPS publication 180-2.
  It passes the FIPS test vectors.

  SHA-3 is based on the "readable implementation" written and released by
  Markku-Juhani O. Saarinen.  It passes the provisional test vectors
  listed at http://www.di-mgt.com.au/sha_testvectors.html

  RIPEMD-160 is based on the reference implementation by A.Bosselaers.
  It passes the test vectors listed at
     http://www.esat.kuleuven.ac.be/~bosselae/ripemd160.html

  MD5 uses the public-domain implementation by Colin Plumb that is also
  used in the OCaml runtime system for module Digest.

  RSA encryption and decryption was implemented from scratch, using
  OCaml's bignum library for arbitrary-precision arithmetic.  Modular
  exponentiation uses the trivial Russian peasant algorithm, because the
  bignum library does not support Montgomery modular multiplication.
  The Chinese remainder theorem is exploited when possible, though.
  Like all ciphers in this library, the RSA implementation is *not*
  protected against timing attacks.

  RSA key generation follows the algorithms used in PGP 2.6.3.
  Probabilistic primality testing is achieved by Fermat tests using the
  first 8 prime numbers.  While not as good on paper as a Miller-Rabin
  probabilistic primality test, this seems good enough for PGP, so it
  should be good enough for us.

  The seeded PRNG is a combination of AES encryption in CBC mode and a lagged
  Fibonacci generator with long period.  It appears to pass the Diehard
  statistical tests.  Still, better to use the system RNG if high-quality
  random numbers are needed.


PERFORMANCE:

Some performance figures measured on a Pentium 4 2Ghz:

  AES 128: raw encryption  39 Mbyte/s; with CBC and buffering  15 Mbytes/s
  AES 192: raw encryption  34 Mbyte/s; with CBC and buffering  14 Mbytes/s
  AES 256: raw encryption  29 Mbyte/s; with CBC and buffering  13 Mbytes/s
      DES: raw encryption  19 Mbyte/s; with CBC and buffering   8 Mbytes/s
     3DES: raw encryption 6.5 Mbyte/s; with CBC and buffering 4.5 Mbytes/s
     ARC4: raw encryption  57 Mbyte/s; with buffering          47 Mbytes/s
     SHA1: 31 Mbyte/s
   SHA256: 21 Mbyte/s
RIPEMD160: 21 Mbyte/s
      MD5: 53 Mbyte/s
  AES MAC: 20 Mbyte/s
 RSA 1024: key generation 120 ms
           public-key operation (public exponent 65537) 0.70 ms
           private-key operation 29 ms
           private-key operation with CRT 9 ms
