A <I>transform</I> 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.
put_substring b pos len processes len characters of byte sequence b, starting at character number pos, through the transform.
put_string str processes all characters of string str through the transform.
put_byte b processes the character having code b through the transform. b must be between 0 and 255 inclusive.
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.
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.
Return the number of characters of output currently available. The output can be recovered with the get_* methods.
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.
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 byte array 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.
Return the first character of output, and remove it from the internal output buffer. Raise End_of_file if no output is currently available.
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.
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.
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.
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.