Cryptokit.transform

# Class type Cryptokit.transform

    class type transform = object .. end

A transform is an arbitrary mapping from sequences of characters to sequences of characters. Examples of transforms include ciphering, deciphering, compression, decompression, and encoding of binary data as text. Input data to a transform is provided by successive calls to the methods `put_substring`, `put_string`, `put_char` or `put_byte`. The result of transforming the input data is buffered internally, and can be obtained via the `get_string`, `get_substring`, `get_char` and `get_byte` methods.

    method put_substring : string -> int -> int -> unit

`put_substring str pos len` processes `len` characters of string `str`, starting at character number `pos`, through the transform.

    method put_string : string -> unit

`put_string str` processes all characters of string `str` through the transform.

    method put_char : char -> unit

`put_char c` processes character `c` through the transform.

    method put_byte : int -> unit

`put_byte b` processes the character having code `b` through the transform. `b` must be between `0` and `255` inclusive.

    method finish : unit

Call method `finish` to indicate that no further data will be processed through the transform. This causes the transform to flush its internal buffers and perform all appropriate finalization actions, e.g. add final padding. Raise `Error Wrong_data_length` if the total length of input data provided via the `put_*` methods is not an integral number of the input block size (see `Cryptokit.transform.input_block_size`). After calling `finish`, the transform can no longer accept additional data. Hence, do not call any of the `put_*` methods nor `flush` after calling `finish`.

    method flush : unit

`flush` causes the transform to flush its internal buffers and make all output processed up to this point available through the `get_*` methods. Raise `Error Wrong_data_length` if the total length of input data provided via the `put_*` methods is not an integral number of the input block size (see `Cryptokit.transform.input_block_size`). (For padded block ciphers, the input block size used here is that of the underlying block cipher, without the padding.) Unlike method `finish`, method `flush` does not add final padding and leaves the transform in a state where it can still accept more input.

    method available_output : int

Return the number of characters of output currently available. The output can be recovered with the `get_*` methods.

    method get_string : string

Return a character string containing all output characters available at this point. The internal output buffer is emptied; in other terms, all currently available output is consumed (and returned to the caller) by a call to `get_string`.

    method get_substring : string * int * int

Return a triple `(buf,pos,len)`, where `buf` is the internal output buffer for the transform, `pos` the position of the first character of available output, and `len` the number of characters of available output. The string `buf` will be modified later, so the caller must immediately copy characters `pos` to `pos+len-1` of `buf` to some other location. The internal output buffer is emptied; in other terms, all currently available output is consumed (and returned to the caller) by a call to `get_substring`.

    method get_char : char

Return the first character of output, and remove it from the internal output buffer. Raise `End_of_file` if no output is currently available.

    method get_byte : int

Return the code of the first character of output, and remove it from the internal output buffer. Raise `End_of_file` if no output is currently available.

    method input_block_size : int

Some transforms (e.g. unpadded block ciphers) process input data by blocks of several characters. This method returns the size of input blocks for the current transform. If `input_block_size > 1`, the user of the transform must ensure that the total length of input data provided between the creation of the cipher and the call to `finish` is an integral multiple of `input_block_size`. If `input_block_size = 1`, the transform can accept input data of arbitrary length.

    method output_block_size : int

Some transforms (e.g. block ciphers) always produce output data by blocks of several characters. This method returns the size of output blocks for the current transform. If `output_block_size > 1`, the total length of output data produced by the transform is always an integral multiple of `output_block_size`. If `output_block_size = 1`, the transform produces output data of arbitrary length.

    method wipe : unit

Erase all internal buffers and data structures of this transform, overwriting them with zeroes. A transform may contain sensitive data such as secret key-derived material, or parts of the input or output data. Calling `wipe` ensures that this sensitive data will not remain in memory longer than strictly necessary, thus making invasive attacks more difficult. It is thus prudent practice to call `wipe` on every transform that the program no longer needs. After calling `wipe`, the transform is no longer in a working state: do not call any other methods after calling `wipe`.