EmailSentry™ Features, Configuration, and Customization

There are three customization and tuning options for EmailSentry™:

  • Install Page
  • MoreInfo Page
  • Config File

Install Page

We provide simple installation instructions with every EmailSentry™ license that your users can use to get started.

Like the MoreInfo page below, most companies will want to host their own installation instructions, using our simple instructions as a starting point.

MoreInfo Page

The "MoreInfo" page is the link on EmailSentry popup window called "More Info".

The MoreInfo Page is your page. It should look like your other web pages, with your corporate look-and-feel. It should have content specific to your company and your use of EmailSentry.

We provide a skeletal MoreInfo Page at the MoreInfo link we provided when we setup your subscription.

MoreInfo is where companies instruct their users how to use EmailSentry, and more importantly, what to do if EmailSentry stops an insecure address. This ranges from telling your users

"If you are certain that there is no 'protected information' in the email you may use the 'Send Anyway' menu choice to send the message"


to

"When you click the 'Send Anyway' button the email will be held in our secure email portal and your recipient will have to login to our website to view their message. Please phone them and let them know if this is the first time you have emailed them."


or even

"When EmailSentry stops and lists one or more domains that are insecure, you may not send any email to this address and you must find another way to send the information."

Your MoreInfo page should:

  • Inform your users that you are using an Outlook Add-in for email security
  • Describe what EmailSentry does: checks every recipient for adequate encryption
  • Instruct users how to use EmailSentry:
    • what to do when it stops with a "failed TLS" message
    • how you have configured the "Send Anyway" choice (one of):
      • you cannot send to any failed address
      • email is held and the recipient must login to our website to see it
      • email will be PGP encrypted and to contact you to get the key
      • etc.
  • Have instructions for how to get support for EmailSentry

It can include content from any of these links, or the links themselves:

The page should be hosted on your own website or intranet so you can easily control access to it and the content on it. CheckTLS can host this page for you if you do not want to host it yourself. We cannot host complex pages with lots of images, style sheets, javascript, or subdirectories. We can host plain html and a few support files.

For smaller IT departments without the ability to make their own webpages, CheckTLS can make text changes to the skeletal MoreInfo page that we provide, and even do some simple customizations with a logo or something.

No matter where your MoreInfo Page is hosted, it will likely include your EmailSentry password, so it should be protected on a private area of your website or on your private intranet. If someone steals your password and starts using some of your licenses, we can reset it, but this will then require all your users to reconfigure EmailSentry (click the configure link on your MoreInfo Page and then click Send in Outlook). So, while having your password stolen will not cost you any money, it will cost you time and effort to reconfigure everyone’s PC. Take some care to protect your password and the webpages that include it in plain text.

When we host your MoreInfo Page, it is a private link that no one knows but you, so it is protected as long as you and your employees do not share it.

We can protect your license by limiting access to a range of IP addresses. If all your users are inside your corporate network, this is an almost foolproof protection for your license. But if any of your users do email from outside your environment, for example from a laptop they take home and to cafes, then this will not help. See AUTH below for more information.

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:

SKIPDOMAINS
domains that you do not want to test like your own domains or other trusted email partners (default is empty).
TIMEOUT
how long EmailSentry waits for CheckTLS servers to respond (default is 30 seconds).
CONFIGURL
URL of LiveConfigFile.xml (see below "Where is the Config File and how is it updated?") (default is https://www.checktls.com/CsOA/YOURCSOACODE/LiveConfigFile.xml).
MOREINFOURL
the target of the MoreInfo link on EmailSentry’s processing window. See above, this should be hosted on your site and have your support info (default is https://www.checktls.com/CsOA/YOURCSOACODE/MoreInfo.html).
POPUPURL
URL of an simple text file that displays in a popup when the user starts EmailSentry (typically not used, default is empty).
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").
MINSCORE
tells EmailSentry what TestReceiver ConfidenceFactor (i.e. the score) you consider “secure” (default is 90). See //email/testTo: (“TestReceiver”) for details.
FULLERRORS
0 or 1, 0 (default) shows human readable error messages, 1 shows several lines of detail on internal error messages (not useful for end users, we use it for support)
AUTH
See below "AUTH Parameter".
CHECKMULTI
See below "Parallel Processing"
CHECKPARALLEL
See below "Parallel Processing"
DISABLE
(V02.02 and above) 0 or 1, 1 to disable EmailSentry.
ENCRYPTOPTION
(V02.04 and above) see below "Encrypt Options".
SENDBUTTON
(V02.05 and above) 0 or 1, 0 to remove Send button.

Translate EmailSentry (version V01.23 and higher)

The Config File allows you to enter translations for all the EmailSentry prompts and controls:

T_Title
CheckTLS
T_Change
&Change This Email
T_Delete
&Delete This Email
T_Send
&Send This Email Anyway
T_CheckingRecipient
Checking Recipient Security
T_MoreInformation
More Information
T_Checking
Checking:
T_TheseDomainsFailed
These domains failed CheckTLS:
T_FAIL
FAIL
T_OK
OK
T_NewConfigFileSaved
New config file saved!
Please close and re-open Outlook.

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
sets the Quick option in TestReceiver (default 1) . See //email/testTo: (“TestReceiver”) for details.
a_SOCKS
HOST:PORT
source the test from a SOCKS server in your own IP address space, thereby using your IP reputation not ours.
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_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_MXCOUNT
# or %
sets the MXCOUNT parameter for //email/testTo:. Can be a number or a percentage indicating how many MX hosts to check (default 1, the one most likely to be used).
See the expandable More Options section in the Instruction/Info for //email/testTo: for information about these and other possible parameters (remember to prefix them with "a_") and their function.

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.

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). If we are hosting your Fixed Config File, you can send us changes and we will install them within two business days (usually within a few hours).

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.

Editing Config Files

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

Using the Two Config File Types

Because the Fixed Config File is local to the user's PC, it is always available and always works. We designed EmailSentry so that important and infrequently changed settings go in the Fixed Config File. That way EmailSentry works even if the Live Config File cannot be fetched.

The Live Config File is more flexible, albeit with some risk. Obviously, if the Live Config File cannot be fetched, its settings are ignored. Also there is the chance that if fetching the Live Config File takes too long, Microsoft will deem EmailSentry unresponsive and disable it. With EmailSentry Version 1.22 and above, this chance is greatly reduced. We provide instructions for how to re-enable a disabled Add-in at https://www.checktls.com/EmailSentry/troubleshooting.html.

For any Config Files you host, your server must return a valid XML file with content-type=text/xml. We can send you a copy of your file from our server as your starting point.

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 CustomerCode, CustomerPass, and one or more IP address masks. See Shared Customer Information for info about CustomerCode and CustomerPass.

Your CustomerCode and CustomerPass 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 CustomerCode and CustomerPass 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.

Sensitivity Flag

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

Subject Flag

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

Recipient Flag

<ENCRYPTOPTION>recipient:/reOLD/reNEW/</ENCRYPTOPTION> tells EmailSentry to change just insecure recipient addresses. Note that since this option only changes the insecure recipients, Recipient Flag can send the email two different ways: the normal way to secure recipients, and with special processing as mentioned above for insecure ones.

For example
<ENCRYPTOPTION>recipient:/@(.*)/%$1@forcetls.com/</ENCRYPTOPTION>
will change all insecure addresses from "user@unsafe.com" to "user%unsafe.com@forcetls.com".

We can provide sendmail rules that intercept an @forcetls.com address, rewrite it back to what it was, and direct the email to an alternate emailer, for example to send the email to an outside service that encrypts it or that allows the user to access it safely from a website.

Config File Format

Here is a sample Config File:

<?xml version="1.0" encoding="utf-8" ?>
<CONFIG>
  <RECONFIGUREURL>https://www.checktls.com/GetCsOAConfig?</RECONFIGUREURL> <!-- loaded on config email to code@CsOA.CheckTLS.com (replaces this file entirely so need AUTH node in it) -->
  <CONFIGURL>https://www.checktls.com/CsOA/YourCode/LiveConfigFile.xml</CONFIGURL> <!-- loaded every Add-In startup, is additive to RECONFIGUREURL settings -->
  <POSTBASE>https://csoa.checktls.com/Embed?CHECKTLS_URL=/TestReceiver&ACTION=ShowResult&XF=ConfidenceFactor:ConfidenceQFactor&a_LEVEL=XML_SCORE&a_QUICK=on</POSTBASE>
  <POSTBASEMULTI>https://csoa.checktls.com/Embed?CHECKTLS_URL=/MultiTestReceiver&ACTION=ShowResult&a_LEVEL=XML_SCORE&a_QUICK=on</POSTBASEMULTI>
  <AUTH>
    uI3AJISFC0KD76N/sa/kd8F7hxFs6Z8V2Bou/LHuX8TqCOM1VdG74FhDl8ew1B/QamlDPd+H5Uyu
    Cuxhaya8fo15rQQ9XVxxXOD1UAwWbs6YEvNXoKB4ajjDXMyLeIUdUSy5fMkkbsiyyJnyZUoQzFci
    vEkWnEg6wFt2Zd0HWOCNDV1OayC+e7cS/BwamXu5X1EpC8n7Znk2MDDq94AbDoI7TaUW3y8F2ZCo
    7/yVnGOvFy8Zt0nNC5MyNvPlLtAmbXoVXMsX1HoUDjQaQFglmzqdJg0Nr+SGk3USTcmvwXQl4+Zf
    o87UeQVWHfaa8iEl8s76T7xPKU3TMyPdbIEEXA==
  </AUTH>
  <FULLERRORS>0</FULLERRORS>
  <QUICK>on</QUICK>
  <MINSCORE>90</MINSCORE>
  <TIMEOUT>30</TIMEOUT> <!-- CsOA HttpWebRequest -->
  <a_TIMEOUT>11</a_TIMEOUT> <!-- TestReceiver TO -->
  <SKIPDOMAIN></SKIPDOMAIN>
  <CHECKMULTI>-1,-1</CHECKMULTI>
  <CHECKPARALLEL>2,15</CHECKPARALLEL>
  <MOREINFOURL>https://www.checktls.com/CsOA/YourCode/MoreInfo.html</MOREINFOURL> <!-- link displayed on popup -->
  <POPUPURL>https://www.checktls.com/CsOA/YourCode/PopUp.txt</POPUPURL> <!-- messagebox that displays after any config file load -->
  <T_Title>CheckTLS</T_Title>
  <T_Change>&Change This Email</T_Change>
  <T_Delete>&Delete This Email</T_Delete>
  <T_Send>&Send This Email Anyway</T_Send>
  <T_CheckingRecipient>Checking Recipient Security</T_CheckingRecipient>
  <T_MoreInformation>More Information</T_MoreInformation>
  <T_Checking>Checking:</T_Checking>
  <T_TheseDomainsFailed>These domains failed CheckTLS:</T_TheseDomainsFailed>
  <T_FAIL>FAIL</T_FAIL>
  <T_OK>OK</T_OK>
  <T_NewConfigFileSaved>New config file saved!
Please close and re-open Outlook.</T_NewConfigFileSaved>

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.