EmailSentry V02 Configuration

EmailSentry™ V02 Configuration

This document describes configuration for EmailSentry V02, the Outlook Classic (Classic Outlook for Windows) version, also called a "COM Add-In". Configuration for EmailSentry V03, the Outlook (New Outlook for Windows) version are at EmailSentry V03 Configuration (which is also for MAC, browser, and mobile devices).

EmailSentry V02 is configured in a ConfigFile that specifies what feature/functionality is offered and how it is performed. The ConfigFile can also contain customized prompts for most EmailSentry features, for example changing "Delete This Email" to "Elimina Este Correo".

The ConfigFile controls two things: the EmailSentry Add-in itself, and the //email/testTo: ("TestReceiver") webservice that EmailSentry uses.

Control EmailSentry

The ConfigFile controls several EmailSentry settings:

CONFIGURL: URL of next config file to load. Used in FixedConfigFile to find the LiveConfigFile.xml (see below "Where is the ConfigFile and how is it updated?") (default is https://www.checktls.com/CsOA/YOURCSOACODE/LiveConfigFile.xml).
DISABLE: 0(default) or 1, 1 to completely disable EmailSentry.
SKIPDOMAIN: domains that you do not want to test like your own domains or other trusted email partners (default is empty). Multiple domains may be listed in multiple SKIPDOMAIN nodes or together in one SKIPDOMAIN node separated by semi-colons (";"), or a combination of both.
NOTFROM: Outlook accounts ("From:" addresses) on which you do not want EmailSentry. Used when Outlook has multiple accounts and don't want EmailSentry to popup when sending from one or more of them.
TIMEOUT: how long EmailSentry waits for CheckTLS servers to respond (default is 30 seconds).
MINSCORE: tells EmailSentry what TestReceiver ConfidenceFactor (i.e. the score) you consider “secure” (default is 90). See Confidence Factor℠ for details.
HIDEUID: 0(default) or 1. Each EmailSentry licensed user has a unique GUID containing their computer's USERNAME and COMPUTERNAME. HIDEUID=1 obfuscates the GUID with a one-way hash. HIDEUID=0 lets you see these NAMES on your EmailSentry reports.
AUTH: This is the only required entry in your ConfigFiles. It contains your license information. See below "AUTH Parameter".
MOREINFOURL: the target of the MoreInfo link on EmailSentry’s processing window. See MoreInfo Page (default is https://www.checktls.com/CsOA/YOURCSOACODE/MoreInfo.html).
POPUPURL: URL of an simple text file that displays in a popup on EmailSentry first use (first email sent after starting Outlook, typically not used, default is empty).
CHECKMULTI: See below "Parallel Processing"
CHECKPARALLEL: See below "Parallel Processing"
SENDBUTTON: 0 or 1(default), 0 to remove Send button.
WAITSEC: How many seconds to wait before allowing the user to "Send Anyway" (default 0). This makes it a little more difficult for a user to disregard a security warning.
TURNOFFSEC: How many seconds to wait before turning EmailSentry back on after it is turned off, default 10800 (3 hours), zero to never turn back on.
ENCRYPTOPTION: see below "Encrypt Options".
HIDEPOPUP: 0(default), 1, or 2. 0 shows the interactive processing popup, 1 only shows the popup after checking and only if one or more domains fail, 2 suppresses the popup completely (requires AUTOENCRYPT).
FAILSAFEES: 0 or 1(default), 1 to disable EmailSentry if it encounters any error (until next restart of Outlook). This prevents EmailSentry from "breaking" a user's email at the cost of removing all EmailSentry security checks.
AUTOENCRYPT: 0 or 1(default). 1 automatically selects the Encrypt option if any domains fail (user does not have to click, requires an EncryptOption).
FULLERRORS: 0(default) or 1. 1 shows several lines of detail on internal error messages (not useful for end users, we use it for support)
PROXYURL: URL of your proxy server if you require web requests to be sent via a proxy (default is empty, example "http://192.168.254.72:3128/", see WebProxy Class).

Translate EmailSentry

The ConfigFile allows you to enter translations for all the EmailSentry prompts and controls. Not all of these fields need to be translated. We suggest adding translations for the fields below down through T_NewConfigFileSaved and leaving the error messages alone because they are almost never seen.

T_Title: CheckTLS
T_Change: &Change This Email
T_Delete: &Delete This Email
T_Encrypt: &Encrypt This Email
T_Send: &Send This Email Anyway
T_TurnOff: &Turn off EmailSentry
T_CheckingRecipient: Checking Recipient Security
T_MoreInformation: More Information
T_Checking: Checking:
T_TheseDomainsFailed: These domains failed CheckTLS:
T_FAIL: FAIL (displayed for domains that fail)
T_NOTTESTED: NotTested (displayed for domains that cannot be tested)
T_TIMEOUT: TimeOut (displayed for domains that testing took too long)
T_OK: OK (displayed for domains that pass)
T_NewConfigFileSaved: New config file saved!
Please close and re-open Outlook.
T_EmailSentryErrorTO: ****** EMAIL SECURITY TESTING HAS BEEN DISABLED ******
(blank line)
It will re-enable in XX:XX hours. Restart Outlook to re-enable sooner.
(various error messages display here)
T_EmailSentryErrorNoTO: ****** EMAIL SECURITY TESTING HAS BEEN DISABLED ******
(blank line)
Restart Outlook to re-enable.
(various error messages display here)
T_WebServiceErrorTO: ****** EMAIL SECURITY CANNOT BE TESTED ******
(blank line)
due to the error below. If this continues, use the
TurnOff button to disable EmailSentry for XX:XX hours.
Restart Outlook to re-enable sooner.
(various error messages display here)
T_WebServiceErrorNoTO: ****** EMAIL SECURITY CANNOT BE TESTED ******
(blank line)
due to the error below. If this continues, use the
TurnOff button to disable EmailSentry.
Restart Outlook to re-enable.
(various error messages display here)
T_ConfigError: EmailSentry configuration failed (fix CODE/PASS and click Send to retry)
T_ConfigComplete: EmailSentry configuration complete!
Please restart Outlook to load new settings.

One other user customization available as a T_ parameter is a URL and not a string, for example:

T_LogoImageLocation: https:/www.checktls.com/EmailSentryLogo.png

Control //email/testTo: ("TestReceiver")

The ConfigFile also controls the //email/testTo: ("TestReceiver") test that is the foundation of EmailSentry. All of the options, and thus all the capabilities, of the //email/testTo: test can be specified in a ConfigFile.

As some of the settings for EmailSentry (above) have the same names as settings for //email/testTo:, the ConfigFile marks settings for //email/testTo: by prefixing them with "a_". Case is important, it must be a lowercase "a".

For example:

a_QUICK: 0 or 1(default)
sets the Quick option in TestReceiver. See //email/testTo: (“TestReceiver”) for details.
a_TIMEOUT: #
sets the TIMEOUT parameter for //email/testTo:. It tells how long to wait for an MX host to respond before calling it a failure.
Compare this to the EmailSentry TIMEOUT parameter (above) that tells EmailSentry how long to wait for the //email/testTo: test itself to respond.
a_SSLVERSION: STRING
sets the SSLVERSION parameter for //email/testTo:. It tells //email/testTo: what versions of TLS are acceptable to you (default empty, all versions allowed).
a_SOCKS: HOST:PORT
source the test from a SOCKS server in your own IP address space, thereby using your IP reputation not ours.

See the expandable More Options section in the Instruction/Info for //email/testTo: for information about the options available, and TestReceiver API for the parameter names to use (remember to prefix them with "a_" in EmailSentry config).

Where is the ConfigFile and how is it updated?

The ConfigFile is stored on our servers. It is fetched and parsed by EmailSentry every time Outlook starts. This has two ramifications: one, the user must be connected to the Internet when they start Outlook (note that Outlook is not useful if the user is not connected to the Internet); and two, any changes to the ConfigFile ony requires that the user restart Outlook to get the new changes.

The ConfigFile stored on our servers can link to a ConfigFile hosted behind a company firewall where only company users can fetch it. Both ConfigFiles use the same format and are fetched every time Outlook restarts. Companies using EmailSentry use this to hide certain ConfigFile settings from the public. This might include things like SKIPDOMAINS, which are those domains that the company has decided are safe and do not need to be checked everytime an email is sent.

Editing ConfigFiles

Your ConfigFile stored on our servers is editable with //EmailSentry/editConfigFile. If you do use a linked ConfigFile, you can have your IT infrastructure supply different linked ConfigFiles, with different configuration options, to different departments, for example putting tighter controls on engineers than sales persons.

Parallel Processing

EmailSentry finds everything it needs to know about the security of a recipient from just the recipient's domain (the stuff after the "@"). When processing multiple (To:, CC:, and BCC:) recipients, EmailSentry first finds all the unique domains. When an email has more than one unique domain, EmailSentry has three ways (modes) to test each domain: linear, multi, and parallel.

Linear Mode

Linear mode tests the domains one at a time. As each test finishes, the domain is listed in the textbox and the progress bar fills in across the window. This gives the user positive feedback that EmailSentry is working, and reminds them that Email Security is important.

Multi Mode

Multi mode sends all the domains to CheckTLS at once. CheckTLS servers can process many domains at the same time, so this is faster when doing more than about two domains. The progress bar shows an estimate of how far along the test process is, but this can only be an estimate since the testing is being done remotely. The results typically show up all at once in the textbox.

Parallel Mode

Parallel mode runs multiple copies of EmailSentry on the user's PC. EmailSentry is very efficient, and a typical PC or laptop can process hundreds of domains in parallel. With Parallel mode, the textbox and the progress bar more accurately show how far along the testing is.

Mode Configuration

These three modes are controlled by two configuration parameters: CHECKMULTI and CHECKPARALLEL. Both have three numbers: min, batch, and max. "min" is the lowest target (unique domain) count that will use that mode, "batch" is how many targets to test at once, "max" is the most targets that the mode can handle. A target count outside the min/max for either mode will be tested linearly. Linear testing is the fastest for just a couple targets, and the safest, albeit unworkable, for impossibly large target counts. Anyone sending to hundreds of targets should be verifying them with CheckTLS "Batch", not in EmailSentry.

Default Configuration

By default, EmailSentry is set to process up to 3 domains linearly. More than that are processed in multi mode, sending them all to CheckTLS to process at once. So the default settings are:
<CHECKMULTI>4,320,960</CHECKMULTI>
<CHECKPARALLEL>0,0,0</CHECKPARALLEL>

Encrypt Options

EmailSentry can flag a message that does not meet your security requirements so your mail system can do special processing with them. This special processing could be End-to-end Encryption, outsourced email like CounterMail or ProtonMail, or your own webmail.

Encrypt Options are: Subject, Recipient, and Sensitivity (V02.05). Setting ENCRYPTOPTION adds an Encrypt button to the EmailSentry popup. In V02.04 ENCRYPTOPTION was called SENDOPTION.

ENCRYPTOPTION:Subject

<ENCRYPTOPTION>subject:/reOLD/reNEW/</ENCRYPTOPTION> tells EmailSentry to change the message's Subject:. Any string in the message Subject matching reOLD will be replaced with reNEW. Since these "re"s are Regular Expressions, you can insert a string at the beginning with "subject:/^/[newstring]/", or at the end with "subject:/$/[newstring]/".

For example <ENCRYPTOPTION>subject:/^/ENCRYPT THIS ONE /</ENCRYPTOPTION> will add "ENCRYPT THIS ONE " as the first characters of the message's Subject:

Note that this is a "message level" option, so when it is invoked it pertains to all recipients.

ENCRYPTOPTION:Recipient

<ENCRYPTOPTION>recipient:/reOLD/reNEW/</ENCRYPTOPTION> tells EmailSentry to change ("rewrite") insecure recipient addresses.

This is used with email systems that can route emails through different processes depending on the recipient's domain name: secure recipients get standard handling but insecure recipients get special handling. For example: <ENCRYPTOPTION>recipient:/@(.*)/%$1@forcetls.com/</ENCRYPTOPTION> will change ("rewrite") all insecure addresses from "user@unsafe.com" to "user%unsafe.com@forcetls.com".

We can provide sendmail rules that intercept an @forcetls.com address, restore it back to what it was (e.g. "user@unsafe.com"), and direct the email to an alternate emailer. This alternate emailer could, for example be an outside service that encrypts email or that allows the email to be viewed safely from a website.

Note that since this option only changes the insecure recipients, ENCRYPTOPTION:Recipient can send the same email two different ways: the normal way to secure recipients, and with special processing as described above for insecure ones. Importantly, the single email will show the insecure email addresses in their rewritten (e.g. "user%unsafe.com@forcetls.com") form to all recipients, both secure and insecure, preventing replies to the email from going insecurely.

ENCRYPTOPTION:Sensitivity

<ENCRYPTOPTION>sensitivity:Confidential</ENCRYPTOPTION> tells EmailSentry to change the message's Sensitivity to Confidential. Confidential can be one of Normal, Personal, Private, or Confidential.

Note that this is a "message level" option, so when it is invoked it pertains to all recipients.

ConfigFile Format

The example below is a very full ConfigFile. Most of these are defaults and are not in a real ConfigFile; they are shown here for your information. See your specific ConfigFile for the few options that you do need. Here is the full ConfigFile: <CONFIG> <CONFIGURL>https://MyCompany.com/EmailSentry/SalesConfigFile.xml</CONFIGURL>  <DISABLE>0</DISABLE> <SKIPDOMAIN>Dwalin.com</SKIPDOMAIN> <SKIPDOMAIN>Balin.com;Kili.com;Fili.com;Dori.com</SKIPDOMAIN> <SKIPDOMAIN>Nori.com;Ori.com;Gloin.com;Bifur.com;Bofur.com</SKIPDOMAIN> <SKIPDOMAIN>Bombur.com</SKIPDOMAIN> <SKIPDOMAIN>Thorin.com</SKIPDOMAIN> <SKIPDOMAIN>/.*@(?i)seven.xxx/</SKIPDOMAIN> <NOTFROM>user@domain</NOTFROM> <TIMEOUT>30</TIMEOUT>  <MINSCORE>90</MINSCORE> <HIDEUID>0</HIDEUID> <AUTH> faE7jN/lju8pUohfmGEW8YWXY2IdSxziId2iAIvvG4KgVlkiBKnRb/EVKekFrRsBWnhUu/A8oz1K gOu728fIrZ4vZZvv0VjM8Sy3GzpOTIFavnOFMTM707MNE5x06vr2mwZV9NwCK+owrKDPlhjccVMw JIcQt/6SRu/Ew/YGawRCTz9AgGOZqc3tj2jGMecMIe+ZrW0YP3FEV2+Kgy+HfTCE2C+U2ey8WvvV z/gP7mrO+ZVGT0zlVz0iDhEEFZOkeGu7kamT6CH8rmkUkXVdomkxicUffiE90DTjSeqrVQkU00pU eI8HFOqYA+yK5xh/lDgvQxW3VSF6ZJickVCgKQ== </AUTH> <MOREINFOURL>https://CsOA.CheckTLS.com/CsOA/CUSTOMERCODE/MoreInfo.html</MOREINFOURL>  <POPUPURL>https://CsOA.CheckTLS.com/CsOA/CUSTOMERCODE/PopUp.txt</POPUPURL>  <CHECKMULTI>4,320,960</CHECKMULTI> <CHECKPARALLEL>0,0,0</CHECKPARALLEL> <SENDBUTTON>1</SENDBUTTON> <WAITSEC>0</WAITSEC> <TURNOFFSEC>10800</WAITSEC> <HIDEPOPUP>0</HIDEPOPUP> <FAILSAFEES>1</FAILSAFEES> <FULLERRORS>0</FULLERRORS> <STATLEVEL>2</STATLEVEL> <PROXYURL>http://192.168.254.72:3128</PROXYURL> <a_QUICK>on</a_QUICK> <a_TIMEOUT>11</a_TIMEOUT>    <T_Title>CheckTLS</T_Title> <T_Change>&Change This Email</T_Change> <T_Delete>&Delete This Email</T_Delete> <T_Encrypt>&Encrypt This Email</T_Encrypt> <T_Send>&Send This Email Anyway</T_Send> <T_TurnOff>&Turn Off EmailSentry</T_Send> <T_CheckingRecipient>Checking Recipient Security</T_CheckingRecipient> <T_LogoImageLocation>https://www.checktls.com/EmailSentry/EmailSentry/Logo.png</T_LogoImageLocation> <T_MoreInformation>More Information</T_MoreInformation> <T_Checking>Checking:</T_Checking> <T_TheseDomainsFailed>These domains failed CheckTLS:</T_TheseDomainsFailed> <T_NOTTESTED>NotTested</T_NOTTESTED> <T_TIMEOUT>TimeOut</T_TIMEOUT> <T_FAIL>FAIL</T_FAIL> <T_OK>OK</T_OK> <T_NewConfigFileSaved>New config file saved!
Please close and re-open Outlook.</T_NewConfigFileSaved> <T_EmailSentryErrorTO>****** EMAIL SECURITY TESTING HAS BEEN DISABLED ******

It will re-enable in XX:XX hours. Restart Outlook to re-enable sooner.
</T_EmailSentryErrorTO> <T_EmailSentryErrorNoTO>****** EMAIL SECURITY TESTING HAS BEEN DISABLED ******

Restart Outlook to re-enable.
</T_EmailSentryErrorNoTO> <T_WebServiceErrorTO>****** EMAIL SECURITY CANNOT BE TESTED ******

due to the error below. If this continues, use the
TurnOff button to disable EmailSentry for XX:XX hours.
Restart Outlook to re-enable sooner.
</T_WebServiceErrorTO> <T_WebServiceErrorNoTO>****** EMAIL SECURITY CANNOT BE TESTED ******

due to the error below. If this continues, use the
TurnOff button to disable EmailSentry.
Restart Outlook to re-enable.
</T_WebServiceErrorNoTO> <T_ConfigError>EmailSentry configuration failed (fix CODE/PASS and click Send to retry)</T_ConfigError> <T_ConfigComplete>EmailSentry configuration complete!
Please restart Outlook to load new settings.</T_ConfigComplete> <ENCRYPTOPTION>subject:/^/***ENCRYPT*** /</ENCRYPTOPTION> </CONFIG>

Debug 3-dot Commands

There are a few hidden commands that we use to diagnose problems. They are triggered by entering special strings in the Subject: of an email and clicking Send. The email can be a live email that will be sent, or a dummy email, i.e. with an invalid address.

debug.debug.debug turns on debugging messages. EmailSentry will display information about what it is doing in popups as it processes the email. The email is sent. This setting stays on until you exit Outlook and restart it.

fullerrors.fullerrors.fullerrors displays all the information it has about an error it encounters. Normally error messages are summarized. The email is sent. This setting stays on until you exit Outlook and restart it.

version.version.version shows a one-time popup with the version string of EmailSentry installed on the user's PC. The email is not sent.

config.config.config puts the ConfigFile contents and all internal config variables into the body of the email. You are returned to editing the email.

uid.uid.uid puts the user's unique UID (one-way hash of their USERNAME and COMPUTERNAME) into the subject of the email. You are returned to editing the email.

test.test.test runs the message in "test" mode: normal testing is done but the final pop-up is displayed even if no errors are found, and the user must choose Change, Delete, or Send anyway.