description.
The iocrypt_o class manages the input-output management of data to be encrypted or decrypted. The class object does not provide any new cipher features or functionality specific to encryption. It extends the multicrypt_o class (which handles all the work of encryption-decryption and uuencoding-decoding). It can be considered to be a marriage of the multicrypt and file objects. Although file encryption is its primary purpose, it also accomodates standard (console) input and output, or can encrypt [/decrypt] a line of text specified in the command line.

The object can be configured to process a line of input at a time, or a block of multi-line input. The former provides a facility for generating large amounts of encrypted strings, and is an important tool for providing keys to the Z Directory security subsystem. The output can be displayed in various ways, such as enveloping the resultant data with right and left border-text.

This extreme level of configurability allows the object to behave like a complete program, and the object is the basis for the zipher encryption program. This class is requires a large amount of pre-run configuration, and when all is ready, a single member function call, run(), performs the actual work. zipher supercedes the krypt program, whose source is publicly available.

There are a few options available:

• MCRYPT_FMT_XTRALINE - prints an extra newline ('\n') after the input. this is oriented towards interactive console output, where the user wants to clearly see the full ciphered data. This option may be quite useful in the case of dumping the result to the console - usually, the raw data will not be terminated with a new line.
• MCRYPT_FMT_SHOWSIZE - prints some info about the ciphered output after the data is dumped to the console. Again, this is oriented towards interactive console output.
• MCRYPT_PERLINE - this applies to text files only. If this flag is set, each line of text from the file will be individually encrypted. This allows for processing a large batch of small chunks of data, such as a password file, where there is a clear-text password per line. The output can be routed to the console or to another file.

Note that if the input is a file, and no output (either file or console), the output will default to a file with a ".e" extension. If the input is a fixed string, and no output is specified, the output will default to the console (stdout).

For AES encryption algorithm, the data block to encrypt will be padded to a multiple of 32, if it is not. This means that when the data is decrypted, and if the data was padded, it will not be exactly the same as the original - [up to 32] extra bytes will be appended. The alternative is to let the encryption fail; neither is an optimal solution (this is not done for text files doing line-by-line ciphering, eg, with MCRYPT_PERLINE flag set - only full-block ciphering applied to files or stdin).

member functions (primary)

iocrypt_o()
SIGNATURE: testdriver_o ()
SYNOPSIS: creates an empty testdriver object. the bulk of the work for this constructor is done in the base class.
 

iocrypt_o(iocrypt_o)
SIGNATURE: iocrypt_o (const iocrypt_o &that)
SYNOPSIS: creates a a new iocrypt_o object which is an exact image of the copied object "that".
 

destructor
SIGNATURE: ~iocrypt_o ()
SYNOPSIS: virtual destructor. The iocrypt instance is 'wiped out'.
 

operator = (iocrypt_o)
SIGNATURE: const iocrypt_o &operator = (const iocrypt_o &that)
SYNOPSIS:
copy the settings of iocrypt object 'that' into the current object. This funciton is provided mainly for orthodox completeness.
RETURNS: a reference to the current object.
 

set_direction()
SIGNATURE: void set_direction (Crypto_BufType x)
SYNOPSIS: defines the "direction" (encryption or decryption) to be set for the object when it is run.
PARAMETERS

x: an enumeration defining the type of operation to perform. its value should be iocrypt_o::WAY_ENCRYPT for encryption and iocrypt_o::WAY_DECRYPT for decryption.

TRAITS: This is a pre-action configuration function.
 

set_left()
SIGNATURE: int set_left (const string_o &s)
SYNOPSIS:
sets the left "border" text to print when emitting output. If the value of 's ' is blank (an empty string), its use will decommissioned.
RETURNS: 0
 

set_right()
SIGNATURE: int set_right (const string_o &s)
SYNOPSIS:
sets the right "border" text to print when emitting output. If the value of 's ' is blank (an empty string), its use will decommissioned.
RETURNS: 0
 

set_custom_format()
SIGNATURE: int set_custom_format (const string_o &s, int *pi = NULL)
SYNOPSIS:
This lets the application set up his own output string format, such as "[%7I] .. [%12R]\n", which would print the input string, 7 wide in brackets, then the output string, 12 wide in brackets. "I" means input, R means Result ("O" for Output looks too much like zero).
This function is currently unavailable
RETURNS: 1 {meaning: not available}
TRAITS: NOT YET IMPLEMENTED! (incomplete)
 

set_inputtype()
SIGNATURE: void set_inputtype (Crypto_BufType x)
SYNOPSIS: defines from what type of source the input data comes from.
PARAMETERS

x: an enumeration defining the type of input. values:
iocrypt_o::DATA_SPECIFIC - cipher a specific block of text (such as passed in via command-line).
iocrypt_o::DATA_FILE - the data to cipher comes from a file.
iocrypt_o::DATA_STDIO - the data to cipher comes from standard input (eg, console input).
iocrypt_o::DATA_UNDEFINED - object initial state

 

set_outputtype()
SIGNATURE: void set_outputtype (Crypto_BufType x)
SYNOPSIS: defines what type of target the output data should go to.
PARAMETERS

x: an enumeration defining the type of input. values:
iocrypt_o::DATA_FILE - the data to cipher goes to a file.
iocrypt_o::DATA_STDIO - the data to cipher goes to standard output (eg, the console).
iocrypt_o::DATA_UNDEFINED - object' initial state for the output

 

set_sourcefile()
SIGNATURE: int set_sourcefile (const string_o &sfile, boolean is_text = TRUE, int *pi = NULL)
SYNOPSIS:
set the data to cipher to a file. The file name is given by 's'. The contents of the file can be binary or text type data. This sets the input type to DATA_FILE.
PARAMETERS

• sfile: the name of the file to derive the input from. 'sfile' can be just the file name, in which case the current directory will be searched, or a path and file name.
• is_text: a flag denoting if the file is a text file. If this value is TRUE, the application can specify the MCRYPT_PERLINE option. This would allow individual lines of the file to be encrypted separately. If you are not sure if the file is a text file or not, simply leave this flag at the default value (FALSE).
• pi: [optional] output error indicator variable. Values:
  0: source file successfully set
  zErr_Param_NotSet: 'sfile' is a blank (empty) string

 

set_targetfile()
SIGNATURE: int set_targetfile (const string_o &s, int *pi = NULL)
SYNOPSIS: set the output to be a file. The file name (including path) is given by 's'. This sets the output type to DATA_FILE.
 

set_data()
SIGNATURE: int set_data (const string_o &sdat, int *pi = NULL)
SYNOPSIS: Defines the data to encrypt-decrypt. This sets the input type to "DATA_SPECIFIC" and single-multi mode to "Q_SINGLTON".
PARAMETERS

sdat: the text to encrypt-decrypt.

 

set_extension()
SIGNATURE: static int set_extension (const string_o &sext, int *pi = NULL)
SYNOPSIS:
sets the file name extension. This is for encryption of files only. If not doing encryption, or if not creating an output file, this operation is ignored. The file name extension is appended to the entire file (if possible - some OSs may not allow this) as a ".[ext]". Thus, if the file name is "foo.txt", and the extension is "encr", the encrypted file will be named "foo.txt.encr".
PARAMETERS

• sext: a string containing the extension to assign to encrypted files. No leading dots ('.') should be in the string. Actually, it must not contain any dots or any illegal (eg non-alphabetic) characters anywhere in it.
• pi: [optional] output error indicator variable. Values:
  0: successfully set
  zErr_Param_BadFormat: illegal character(s) in the string
  zErr_NotSupported: assigning a file extension not permitted [by the OS] in this context

TRAITS:
this is a static function. Thus, all iocrypt_o instances will use the provided extension for encrypted files after this function is [successfully] invoked.
The default extension is ".e". So unless this member function is explicitly called with some other value, the encrypted image "foo.txt" will be named "foo.txt.e".
 

set_flags()
SIGNATURE: int set_flags (int fv)
SYNOPSIS: sets on the object's internal flag variables corresponding to the values defined in input parameter 'fv'.
PARAMETERS

fv: a bitmap of flag values. Only valid flag bit numbers are checked:
MCRYPT_FMT_XTRALINE - if set, a final newline character ("\n") is printed after the ciphered output.
MCRYPT_FMT_SHOWSIZE - prints the number of bytes after the ciphered data is printed, in the syntax "([n] bytes)", where [n] is the number of characters in the output block.
MCRYPT_PERLINE - if set, this will allow for a indivisual lines of text to be ciphered separately. This flag applies only to when the data source is file.

 

clear_flags()
SIGNATURE: int clear_flags (int fv)
SYNOPSIS: clears the object's internal flag object of the bit values represented by 'fv'.
 

set_flag()
SIGNATURE: int set_flag (int idx, int *pi = NULL)
SYNOPSIS:
Sets a single flag given by the value in 'idx'. Only valid flags applicable to this object may be set: MCRYPT_FMT_XTRALINE, MCRYPT_FMT_SHOWSIZE, and MCRYPT_PERLINE.
 

clear_flag()
SIGNATURE: int clear_flag (int idx, int *pi = NULL)
SYNOPSIS:
Clears a single flag given by the value in 'idx'. Only the following flags, applicable to this object, may be affected: MCRYPT_FMT_XTRALINE, MCRYPT_FMT_SHOWSIZE.
 

add_crypto()
SIGNATURE: int add_crypto (const string_o &nam, paramstring_o &rps, int *pi = NULL)
SYNOPSIS:
this member function adds a new encryption algorithm. Only a single cipher algorithm can be provided at a time (do not concatenate names with '+'). This function can be called repeatedly to add multiple ciphers. The ciphers will be invoked on the data in the order in which they are provided by repeated invocation of this function.
PARAMETERS

• nam: a short code name for the cipher to be added to the object. The list of legal values are provided elsewhere on this page.
• rps: a list of secondary parameters, supplied as a parameter string. For all ciphers except RSA this should be an empty string. For RSA (cipher name: "rsa"), the only valid text this can be is "private_key=[value]", where "[value]" represents the ciphers' private key string.
• pi: [optional] output error indicator variable. Possible values:
  0: success
  zErr_Param_BadVal: invalid encryptor name
  zErr_TooMany: cipher algorithm provided earlier. A limitation of this object is that a cipher can be used at most 1 time.
  zErr_Param_OuttaBounds: this should never happen and indiates an internal panic error.
  zErr_InvalidSize: illegal key length (this is currently targeted for AES)
  5: invalid keyword provided to parameter 'rps'.

RETURNS:
0: cipher added successfully
-1: error occurred (see return code in output parameter 'pi')
 

run()
SIGNATURE: int run (int *pi)
SYNOPSIS: runs the cipher process. All object settings must have been set prior to calling this function.
PARAMETERS

pi: [mandatory] output error indicator variable. Values:
0: success
1: direction (encrypt-decrypt) undefined. use set_direction() to set this.
2: single/multi mode undefined. Use setmode_multi() or setmode_solo().
3: input type is undefined. use set_inputtype().
4: input type is "specific data" but single/multi is "multi" (which doesn't make sense). This should never happen.
zErr_Item_NotFound: the file to process was not found.
zErr_Resource_Corrupted: could not get standard input (panic)
zErr_Read_Failed: error trying to get line from file
zErr_Internal: cipher process failed
zErr_Illegal_CaseValue: "single/multi" internal variable corrupted (panic)
zErr_Param_NotSet: illegal input type (or not set)
zErr_Incompatible: user wants to process individual lines, but the file was not specified as type text

 

reset()
SIGNATURE: int reset ()
SYNOPSIS: resets the object to default at-construction state. All configuration settings are reset.
 

dump_output()
SIGNATURE: int dump_output (const string_o &, const string_o &, size_t, int *)
SYNOPSIS: this function is not made to be explicitly called, but rather to be overwridden in subclasses
TRAITS: a virtual function
 

limitations.
As with multicrypt_o, the number of cipher algorithms is limited to whatever is currently implemented. At the time of this writing (2013), the available ciphers are: