EmailSentry Configuration

EmailSentry™ Configuration

Config File

We recommend splitting the Config File into two pieces: FixedConfigFile and LiveConfigFile (see Configuration File). In this documentation we refer to these two as just "Config File".

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

Control EmailSentry

The Config File 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 Config File 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 Config Files. 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 Config File 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 Config File 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 Config File.

As some of the settings for EmailSentry (above) have the same names as settings for //email/testTo:, the Config File 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 Config File and how is it updated?

The Config File has two parts: a Fixed Config File and an optional Live Config File. They are read every time Outlook starts. Both have the same XML format.

Fixed Config File

The Fixed Config File is stored on the user's PC and is loaded into Outlook every time Outlook starts. Because it is on the local PC, it is always available (even when the Internet is down) and loads almost instantly.

When a user configures EmailSentry (by clicking on the configure link and then clicking Send in Outlook), EmailSentry fetches a new Fixed Config File from our servers and stores it on the user's PC.

Most EmailSentry customers do not change their user’s Fixed Config Files very often, since it requires that each user does something (click a link and then click Send). See "Editing Config Files" below for how to make changes to your Fixed Config File.

For more control, you can store the Fixed Config File as a URL on your own servers. Send us the URL and we will have our servers redirect all configure requests from your users to that link. Be sure the URL is accessible from inside and outside your firewalls if users might have to configure EmailSentry from outside.

Live Config File

The Live Config File is stored on the Internet, your intranet, or some other network connection. Typically a URL, it is fetched every time Outlook starts. Settings in the Live Config File override settings in the Fixed Config File.

The Live Config File lets you tune EmailSentry without making your users click the (re)configure link: users just have to close and re-open Outlook to get Live Config File changes. If we are hosting your Live Config File, see "Editing Config Files" below for how to make changes to it.

Editing Config Files

Your Fixed Config File and your Live Config File (if we are hosting it) are editable with //EmailSentry/editConfigFiles.

Using the Two Config File Types

We recommend the Fixed Config File contain only one entry: <CONFIGURL>, the pointer to your Live Config File. This gives you the most flexibility in tuning EmailSentry over time. If you host the Live Config File on your own intranet, you can protect it, especially your AUTH (see below), so no one can steal one of your EmailSentry licenses.

You can use the Fixed Config File to give different options to different departments at your company. Legal may want tighter requirements for what constitutes a "safe" amount of encryption, while Sales may want to be able to send almost anything to almost anyone. The Fixed Config File on Legal's PCs would point to Live Config File with stricter settings than the Live Config File pointed to on Sale's PCs.

AUTH Parameter

This is the only required parameter in a Config File. Your AUTH code is unique to your license and it is how we control access to EmailSentry.

AUTH is a public/private key encrypted combination of your CompanyCode, CompanyPass, and one or more IP address masks. See Shared Company Information for info about CompanyCode and CompanyPass.

Your CompanyCode and CompanyPass are your Corporate Subscription permissions to the CheckTLS website. All EmailSentry licenses include a full Corporate Subscription to CheckTLS.

The IP address masks are used to limit use of EmailSentry and your Corporate Subscription to those specific IP addresses. For very security conscious organizations that only allow access to corporate assets from within their own controlled environment (i.e. network), this can be used to protect your EmailSentry license, and your access to any information, such as stored tests, as part of your Corporate Subscription.

It does preclude, obviously, any use of EmailSentry and the CheckTLS website, from anywhere but your network.

Every time EmailSentry checks a domain from an Outlook email it sends the email address, your Config File choices, and your AUTH code to our servers. We decode the AUTH with our private key and check that your CompanyCode and CompanyPass are still valid, and that the user's PC has a public IP address in one of the decoded IP address masks. If so, the test is run and results returned to EmailSentry. If not, we return an error to EmailSentry, which the popup then displays.

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.

Config File Format

Here is a sample Config File: <CONFIG> <CONFIGURL>https://CsOA.CheckTLS.com/CsOA/CUSTOMERCODE/LiveConfigFile.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/Email Transfer/EmailSentry Logo v2.3a - Soldier Only Heavier Lines - WEB ONLY [NoICC 96 [97 x 86].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.

path.path.path shows a one-time popup with the path to the Config File on the user's PC. The email is not sent.

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 Config File 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.

update.update.update checks for a new version of the Click-Once (not the MSI) version of EmailSentry and installs it. This can be used with an email: link on a webpage to allow your users to easily update EmailSentry. For example: Update LINK