Sometimes a script needs variables such as database passwords which you may not wish to have visible in IIF files.  CopiaFacts allows the system administrator to enter password-protected variables in the configurator program (CFHWL), which can then be used in IIF scripts.

Eight variables are available, named SECRET1 through SECRET8.  When these variables are expanded in infobox commands, the expansions are excluded from the CopiaFacts engine trace files (nodename.TRx) and from the trace messages generated by CF8SUPPORT.DLL and CF8DATABASE.DLL. Their use in an infobox also requires the infobox to be 'authenticated' (see below) by the system administrator.

Secret variables may also be expanded on an $email_sign_keyfile command and other 'keyfile' commands.

Encrypted variables are only expanded when used in an authenticated infobox or on certain other 'keyfile' commands.  Tracing is suppressed when processing expanded variables, but Copia does not guarantee that expanded variables cannot be seen while being passed to other utilities or by someone with suitable expertise and with access to the machine.

The authentication process ensures that an unauthorized person cannot access the value of a secret variable from a script.  Without this control, the variable could be assigned to another unsecured variable with an assignment that would appear in the trace file, or could even be included in an e-mail message generated from the system, for example:

$type FSFILE

$email_text "The secret password is `SECRET3"  ; will NOT be expanded!

To authenticate an IIF file, the system administrator should add an authentication command as the first command in an infobox:

$authenticate

$type decision

...

$set_var DLL_SELECT @GMDLL

$set_var DLL_PARM "GMW_LoadAPI('@SYSDIR', '@GOLDDIR', '@COMMDIR', '@SECRET1', '@SECRET2')"

$set_var DLL_CALL GMAPI

$if @DLL_RETURN < 1

  $set_var TRACE_LINE "GMW_LoadAPI failed with @DLL_RETURN"

  $next_box S191

$else

...

When the infobox file starting with an $authenticate command is saved from COPIAEDIT, the program will prompt for the password saved in CFHWL. A security digest of the file will then be added as the parameter on this command.  For example the first line might be changed to:

$authenticate E0CA61A65F5CC162182207CF3E5BF18BAF4FC95A

The COPIAFACTS program will then only expand SECRETx variables in scripts if the digest matches the content of the file, proving that it has not been subsequently modified.

If you wish to encapsulate your script files into an Infobox Collection, you can use a file extension of .IBCA instead of .IBC to signal that the whole collection is to be authenticated. The COLLECT program will then prompt for the password to authenticate the collection file.  If an individual authenticated infobox is included in a collection, the whole collection must be authenticated, and a password will then be requested even if the file extension is not .IBCA.

The system administrator is responsible for ensuring that an authenticated infobox does not use secret variables in a way that could expose their content outside the script.

If you need more than eight secured values, you could store several passwords in a single variable, delimited by a special character, and extract the item you need using $set_var substring operations.  You should then clear the values of the temporary variables before transferring control out of the infobox.  Tracing of variable assignments is suppressed in an authenticated infobox.