# Module Cryptokit

    module Cryptokit: sig .. end

The Cryptokit 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-512. SHA-3, RIPEMD-160, MD5, and MACs based on AES and DES.
- Random number generation.
- Encodings and compression: base 64, hexadecimal, Zlib compression.

To use this library, link with `ocamlc unix.cma nums.cma cryptokit.cma` or `ocamlopt unix.cmxa nums.cmxa cryptokit.cmxa`.

## General-purpose abstract interfaces

    class type transform = object .. end

A transform is an arbitrary mapping from sequences of characters to sequences of characters.

    val transform_string : transform -> string -> string

`transform_string t s` runs the string `s` through the transform `t` and returns the transformed string. The transform `t` is wiped before returning, hence can no longer be used for further transformations.

    val transform_channel : transform ->
           ?len:int -> Stdlib.in_channel -> Stdlib.out_channel -> unit

`transform_channel t ic oc` reads characters from input channel `ic`, runs them through the transform `t`, and writes the transformed data to the output channel `oc`. If the optional `len` argument is provided, exactly `len` characters are read from `ic` and transformed; `End_of_file` is raised if `ic` does not contain at least `len` characters. If `len` is not provided, `ic` is read all the way to end of file. The transform `t` is wiped before returning, hence can no longer be used for further transformations.

    val compose : transform -> transform -> transform

Compose two transforms, feeding the output of the first transform to the input of the second transform.

    class type hash = object .. end

A hash is a function that maps arbitrarily-long character sequences to small, fixed-size strings.

    val hash_string : hash -> string -> string

`hash_string h s` runs the string `s` through the hash function `h` and returns the hash value of `s`. The hash `h` is wiped before returning, hence can no longer be used for further hash computations.

    val hash_channel : hash -> ?len:int -> Stdlib.in_channel -> string

`hash_channel h ic` reads characters from the input channel `ic`, computes their hash value and returns it. If the optional `len` argument is provided, exactly `len` characters are read from `ic` and hashed; `End_of_file` is raised if `ic` does not contain at least `len` characters. If `len` is not provided, `ic` is read all the way to end of file. The hash `h` is wiped before returning, hence can no longer be used for further hash computations.

## Utilities: random numbers and padding schemes

    module Random: sig .. end

The `Random` module provides random and pseudo-random number generators suitable for generating cryptographic keys, nonces, or challenges.

    module Padding: sig .. end

The `Padding` module defines a generic interface for padding input data to an integral number of blocks, as well as two popular padding schemes.

## Cryptographic primitives (simplified interface)

    module Cipher: sig .. end

The `Cipher` module implements the AES, DES, Triple-DES, ARCfour and Blowfish symmetric ciphers.

    module Hash: sig .. end

The `Hash` module implements unkeyed cryptographic hashes (SHA-1, SHA-256, SHA-512, SHA-3, RIPEMD-160 and MD5), also known as message digest functions.

    module MAC: sig .. end

The `MAC` module implements message authentication codes, also known as keyed hash functions.

    module RSA: sig .. end

The `RSA` module implements RSA public-key cryptography.

    module DH: sig .. end

The `DH` module implements Diffie-Hellman key agreement.

## Advanced, compositional interface to block ciphers and stream ciphers

    module Block: sig .. end

The `Block` module provides classes that implements popular block ciphers, chaining modes, and wrapping of a block cipher as a general transform or as a hash function.

    module Stream: sig .. end

The `Stream` module provides classes that implement the ARCfour stream cipher, and the wrapping of a stream cipher as a general transform.

## Encoding and compression of data

    module Base64: sig .. end

The `Base64` module supports the encoding and decoding of binary data in base 64 format, using only alphanumeric characters that can safely be transmitted over e-mail or in URLs.

    module Hexa: sig .. end

The `Hexa` module supports the encoding and decoding of binary data as hexadecimal strings.

    module Zlib: sig .. end

The `Zlib` module supports the compression and decompression of data, using the `zlib` library.

## Error reporting

    type error =

`|` | `Wrong_key_size` | `(*` | The key is too long or too short for the given cipher. | `*)`
`|` | `Wrong_IV_size` | `(*` | The initialization vector does not have the same size as the block size. | `*)`
`|` | `Wrong_data_length` | `(*` | The total length of the input data for a transform is not an integral multiple of the input block size. | `*)`
`|` | `Bad_padding` | `(*` | Incorrect padding bytes were found after decryption. | `*)`
`|` | `Output_buffer_overflow` | `(*` | The output buffer for a transform exceeds the maximal length of a Caml string. | `*)`
`|` | `Incompatible_block_size` | `(*` | A combination of two block ciphers was attempted whereby the ciphers have different block sizes, while they must have the same. | `*)`
`|` | `Number_too_long` | `(*` | Denotes an internal error in RSA key generation or encryption. | `*)`
`|` | `Seed_too_short` | `(*` | The seed given to a pseudo random number generator is too short. | `*)`
`|` | `Message_too_long` | `(*` | The message passed to RSA encryption or decryption is greater than the modulus of the RSA key | `*)`
`|` | `Bad_encoding` | `(*` | Illegal characters were found in an encoding of binary data such as base 64 or hexadecimal. | `*)`
`|` | `Compression_error of `string * string`` | `(*` | Error during compression or decompression. | `*)`
`|` | `No_entropy_source` | `(*` | No entropy source (OS, `/dev/random` or EGD) was found for `Cryptokit.Random.secure_rng`. | `*)`
`|` | `Entropy_source_closed` | `(*` | End of file on a device or EGD entropy source. | `*)`
`|` | `Compression_not_supported` | `(*` | The data compression functions are not available. | `*)`

Error codes for this library.

    exception Error of error

Exception raised by functions in this library to report error conditions.

## Miscellaneous utilities

    val wipe_bytes : bytes -> unit

`wipe_bytes s` overwrites `s` with zeroes. Can be used to reduce the memory lifetime of sensitive data.

    val wipe_string : string -> unit

`wipe_string s` overwrites `s` with zeroes. Can be used to reduce the memory lifetime of sensitive data.

    val xor_bytes : bytes -> int -> bytes -> int -> int -> unit

`xor_string src spos dst dpos len` performs the xor (exclusive or) of characters `spos, ..., spos + len - 1` of `src` with characters `dpos, ..., dpos + len - 1` of `dst`, storing the result in `dst` starting at position `dpos`.

    val xor_string : string -> int -> bytes -> int -> int -> unit

Same as `xor_bytes`, but the source is a string instead of a byte array.

    val mod_power : string -> string -> string -> string

`mod_power a b c` computes `a^b mod c`, where the strings `a`, `b`, `c` and the result are viewed as arbitrary-precision integers in big-endian format. Requires `a < c`.

    val mod_mult : string -> string -> string -> string

`mod_mult a b c` computes `a*b mod c`, where the strings `a`, `b`, `c` and the result are viewed as arbitrary-precision integers in big-endian format.