diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 40 |
1 files changed, 26 insertions, 14 deletions
@@ -6,7 +6,7 @@ The Cryptokit library for OCaml provides a variety of cryptographic primitives t * Symmetric-key ciphers: AES, Chacha20, DES, Triple-DES, Blowfish, ARCfour, in ECB, CBC, CFB, OFB and counter modes. * Public-key cryptography: RSA encryption and signature, Diffie-Hellman key agreement. -* Hash functions and MACs: SHA-3, SHA-1, SHA-2, RIPEMD-160, MD5, and MACs based on AES and DES. +* Hash functions and MACs: SHA-3, SHA-2, BLAKE2b, RIPEMD-160, and MACs based on AES and DES. (SHA-1 and MD5, despite being broken, are also provided for historical value.) * Random number generation. * Encodings and compression: base 64, hexadecimal, Zlib compression. @@ -17,28 +17,38 @@ This library is distributed under the conditions of the GNU Library General Publ ## Requirements * OCaml 4.02 or more recent. -* The findlib/ocamlfind tool. -* The OASIS tool. +* The Dune build system, version 2.0 or more recent. * The Zarith library, version 1.4 or more recent. * 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 indicate in the Makefile that you do not have it. If you are running Linux or BSD or MacOS, 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](http://egd.sourceforge.net/) entropy gathering daemon. Without `/dev/random` nor EGD, this library cannot generate cryptographically-strong random data nor RSA keys. The remainder of the library still works, though. -## Installation +## Build, test and install +* To configure, run `./configure`. There are options to disable or enable some features (run `./configure --help` for a list), but the default configuration is fine most of the time. + +* To build, run `dune build`. + +* To execute a test, run `dune exec test/<name>.exe` where `<name>` can be `test`, + `prngtest` or `speedtest`, supplying additional command line arguments if needed. + The main test file `test/test.ml` is also included into the `runtest` alias, so it + can be executed simply by `dune test`. + +* To install, run `dune install`. + +## Using the library + +The package name is `cryptokit`. With Dune, use `(library cryptokit)`. With ocamlfind, do ``` -./configure --enable-tests -make -make test -make install + ocamlfind ocamlopt -package cryptokit ... # for compilation + ocamlfind ocamlopt -package cryptokit -linkpkg ... # for linking ``` ## Documentation -See the extensive documentation comments in file src/cryptokit.mli. - -Compilation options: `ocamlfind ocamlopt -package cryptokit`... +See the extensive documentation comments in file `src/cryptokit.mli`. -Linking options: `ocamlfind ocamlopt -linkpkg -package cryptokit`... +To build HTML documentation, run `dune build @doc`. The resulting index file is +located at `_build/default/_doc/_html/cryptokit/Cryptokit/index.html`. ## Warnings and disclaimers @@ -68,6 +78,8 @@ SHA-2 is implemented from scratch based on FIPS publication 180-2. It passes th SHA-3 is based on the "readable" implementation of Keccak written by Markku-Juhani O. Saarinen <mjos@iki.fi>. +BLAKE2b is implemented from scratch based on RFC 7693. The test vectors are taken from https://github.com/BLAKE2/BLAKE2/tree/master/testvectors; others were obtained with the b2sum program. + 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. @@ -76,10 +88,10 @@ RSA encryption and decryption was implemented from scratch, using the Zarith OCa RSA key generation uses GMP's `nextprime` function for probabilistic primality testing. -The hardware RNG uses the RDRAND instruction of recent x86 processors, if supported. It is not available on other platforms. +The hardware RNG uses the RDRAND instruction of recent x86 processors, if supported. It is not available on other platforms. A check is included to reject the broken RDRAND on AMD Ryzen 3000 processors (https://arstechnica.com/gadgets/2019/10/how-a-months-old-amd-microcode-bug-destroyed-my-weekend/). The seeded PRNG is just the Chacha20 stream cipher encrypting the all-zeroes message. The seed is used as the Chacha20 key. An alternate seeded PRNG is provided, based on AES encryption of a 128-bit counter. Both PRNGs pass the Dieharder statistical tests. Still, better use the system RNG or the hardware RNG if high-quality random numbers are needed. ## Performance -If you configure with the options `--enable-tests --enable-bench`, then do `make test`, a simple benchmark is performed and shows the speed of various operations from this library. +If you run `dune exec test/speedtest.exe`, a simple benchmark is performed and shows the speed of various operations from this library. |