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. Values of SECRET variables are limited to 256 characters.
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 CF9SUPPORT.DLL and CF9DATABASE.DLL. Their use in an infobox also requires the infobox to be 'authenticated' (see below) by the system administrator.
 | Important: if you set up a vault for encrypted variables, you must remember its password. Copia cannot decrypt or recover the contents of your SECRETn variables without the password. If you lose/forget your password, you can send your FAXCOUNT.HWL file to Copia Support, who will be able to delete from it the password and all the variables. You can then re-enter the values without losing your other configuration data. |
Secret variables may also be expanded on an $email_sign_keyfile command and other 'keyfile' commands. When these occur in an FS file, the $authenticate mechanism is not used.
| Encrypted variables are only expanded when used in an authenticated infobox or on 'keyfile' commands and special password variables which are specifically documented. 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 in the file 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.
When an infobox file includes another file by using the $include command, and the included file also has an $include FROM command naming the calling file, the files are processed together to calculate the security digest. If the included file is subsequently changed, the principal file must be re-authenticated in COPIAEDIT. COPIAEDIT can also authenticate multiple callers after opening the included file.
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. |
Note that SECRET8, if assigned, is used as a password for updating image options in the FFVIEWER Image Options Editor.
If you need more than seven other 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.
