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.

Controll 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 hos 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/CsCheckTLS_OA/YOURCODE/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.
DEBUG
0 or 1, 1 shows debug information in popups as EmailSentry™ runs (not useful for end users as it shows a LOT of popups) (default 0)
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".

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.
T_ConfigureTheAddIn
Please configure the CheckTLS Add-In
by sending an email to
YOURCODE@CsOA.CheckTLS.com

Controll //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_SSLVERSION
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.
See the expandable section titled FULL Version in the Instruction/Info for //email/testTo: for information about the 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/CsCheckTLS_OA/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.

Config File Format

Here is a sample Config File:

<?xml version="1.0" encoding="utf-8" ?>
<CONFIG>
  <DEBUG>0</DEBUG>
  <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/CsCheckTLS_OA.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>
  <!-- deprecated <MAXTHREADS>100</MAXTHREADS> -->
  <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>
  <T_ConfigureTheAddIn>Please configure the CheckTLS Add-In
by sending an email to
YOURCODE@CsOA.CheckTLS.com</T_ConfigureTheAddIn>
</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.