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 calls to flush and 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.