Instructions/Info
How to run it

See Development and Testing below for how to run Embed interactively.

Embed is a pseudo web service that loads content into one of your web pages. In production it is not run by a person from their browser. It is accessible here to help IT professionals create correct web pages (web service call) and do testing.

Embed has three parts:

Requestor
A web page on your site where your users fill in data they want you to test for them.
Embed
Our pseudo web service that your Requestor page calls and that returns your user back to your Response page.
Response
A web page on your site where you display our results to your users.

When your user submits the form on your Requestor page, their browser calls Embed. Embed runs the test you specify and directs the user's browser to your Response page.

Requestor

The Requestor is a web page on your site. You completely control the content and look and feel of this page. The page must have this HTML form:

<form method="post" action="https://www.checktls.com/perl/beta/Embed.pl">
  <input name="RETURN_URL" type="hidden" value="http://www.checktls.com/beta/embed_response.html" />
  <input name="CHECKTLS_URL" type="hidden" value="http://www.checktls.com/perl/beta/TestReceiver.pl" />
  <input name="XF" type="hidden" value="eMailAddress:ConfidenceFactor" />
  <input name="a_EMAIL" type="text" value="test@checktls.com" />
  <input name="a_LEVEL" type="hidden" value="-2" />
  <button name="ACTION" type="submit" value="CheckTLS">CheckTLS</button>
</form>

Without your look and feel, the above form looks like:

Most of the fields (in this example all but one) are hidden. You use them to specify the test on our site you want to run, some of the parameters for that test, and what parts of the test results you want us to send back to you.

The lines or values on the form are:

form
This entire line has to be exactly like this.
RETURN_URL
The URL of your Response page, which is how we direct the user back to you.
CHECKTLS_URL
The URL of our test you want to run for the user. The test you specify with this input and with the a_XXXXXX parameters below must return XML. See the documentation for the test you want to use for information on how to output XML.
XF
The XML nodes whose data you want to extract from the test output. Separate multiple fields with a colon (":"). As per the example here, these are exact XML node names (spelling and capitalization are important).
a_XXXXXX
Inputs that begin with "a_" are parameters for the test you want to run. Each "a_" input is one of the Input Fields from the interactive test on our site. Contact us for the specific names and values.
ACTION
This entire line has to be exactly like this.

Response

The web page on your site where you display our results to your users. Your Response page must have this JavaScript, and something like the HTML below it:

<script type="text/javascript">
var checktls = {}, t, re = /[?&]?([^=]+)=([^&]*)/g;
while (t = re.exec(document.location.search.split('+').join(' '))) {
        checktls[decodeURIComponent(t[1])] = decodeURIComponent(t[2]);
}
</script>
<p>
Address <script>document.write(checktls.eMailAddress);</script>:
<script>document.write(checktls.ConfidenceFactor<100?"Nope! This recipient does not use TLS":"Yes! This recipient uses TLS");</script>
(score:<script>document.write(checktls.ConfidenceFactor);</script>)
</p>

Without your look and feel, the above output looks like:

Address test@checktls.com: Yes! This recipient uses TLS (score:100)

When your user submits the form on your Requestor page, their browser calls Embed. Embed runs the CHECKTLS_URL using the a_XXXXXX parameters, parses the output, which must be XML, and picks out the nodes you specify in XF. Then it instructs the user's browser to "submit" the selected data back to your Response page where the JavaScript makes it available to you.

What it does

The user sees an input box on a page (Requestor) of your web site and a CheckTLS button. When the enter something and click the button, they get back another page (Response) on your web site with their answer.

Behind the scenes, when the user submits the form on your Requestor page, their browser calls our Embed pseudo web service. Embed runs the test you specified in CHECKTLS_URL using the a_XXXXXX parameters. It parses the output and picks out the nodes you specified in XF. Finally it instructs the user's browser to "submit" the selected nodes back to your Response page where the JavaScript makes the data available to you.

What it shows

When working correctly, Embed doesn't show anything. Your user goes seamlessly from inputting information on your web site to getting results on your web site.

Development and Testing

Requestor Testing

To test your Requestor page, change the ACTION on the <button> line from "CheckTLS" to "DEBUG". This will run Embed interactively from our website, showing the fields and values we received from your Requestor page. See below.

Response Testing

To test your Response page, run Embed interactively from our website. When run interactively you have four fields:

Return URL
The RETURN_URL field from the form: the URL of your Response page, which is how we direct the user back to you.
CheckTLS URL
The CHECKTLS_URL field from the form: the URL of our test you want to run for the user.
XML Nodes
The XF field from the form: the XML nodes whose data you want to extract from the test output. Separate multiple fields with a colon (":"). As per the example here, these are exact XML node names (spelling and capitalization are important).
ARGS
The "a_" fields from the form. Enter one "a_" field per line with an equal sign and the value, for example:
a_EMAIL=test@checktls.com
a_LEVEL=-2
Show <form>
Displays the HTML <form> you need to incorporate into your Requestor page.
Return Result
Runs Embed and directs you to your Response page.

About the JavaScript

The JavaScript for your Response page reads the XF field names and values from Embed and makes them available as checktls.[fieldname]. You do have to access these from JavaScript as in the example above.

Input Fields
Embed parameter entry