TLS Connection

Before sending the HTTP request built in the previous chapter, a secure communication channel has to be established, guaranteeing both that all data is passed encrypted and that the client (your application) and server (running the Web Service API) can be sure of communicating with each other and no one else.

📘

Please note, that only TLS secured communication over standard HTTPS TCP port 443 is accepted.

Both are achieved by establishing a TLS connection with the client and server exchanging certificates.
A certificate identifies a communication party uniquely.

Basically, this process works as follows:

1. TLS: The client requests access to www.ipg-online.com
2. TLS: The server presents its certificate to the client
3. TLS: The client verifies the server’s certificate (optional)
4. TLS: The server asks the client for a client certificate
5. TLS: The client sends its certificate to the server
6. TLS: The server verifies the client’s credentials
7. TLS: If successful, the server establishes TLS tunnel to www.ipg-online.com and all the data
   exchanged between parties is encrypted.
8. HTTP: Start HTTP and request the URL part: /ipgapi/services […]

Following this process, your application has to do two things: First, start the communication by sending its client certificate. Second, verify the received server certificate. How this is accomplished differs from platform to platform. However, in order to illustrate the basic concepts, the PHP and ASP scripts started in the previous chapter will be continued by extending them with the relevant statements necessary for setting up a TLS connection.

Building on the script started in the previous chapter, the parameters which are necessary for establishing an TLS connection with cURL are set in the following statements:

<?php
...
// telling cURL to verify the server certificate:
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 1);
// setting the path where cURL can find the certificate to verify the
// received server certificate against:
curl_setopt($ch, CURLOPT_CAINFO, "C:\certs\tlstrust.pem");
// setting the path where cURL can find the client certificate:
curl_setopt($ch, CURLOPT_SSLCERT, "C:\certs\WS101._.007.pem");
// setting the path where cURL can find the client certificate’s
// private key:
curl_setopt($ch, CURLOPT_SSLKEY, "C:\certs\WS101._.007.key");
// setting the key password:
curl_setopt($ch, CURLOPT_SSLKEYPASSWD, "ckp_1193927132");
...
?>

📘

Please note that this script is extended in the next chapter by the statements doing the actual HTTP request.

Building on the script started in the previous chapter, the statements which initialize the TLS parameters passed to the cURL command line tool are as follows:

<?php
...
// setting the path where cURL can find the certificate to verify the
// received server certificate against:
$serverCert = " --cacert C:\certs\tlstrust.pem";
// setting the path where cURL can find the client certificate:
$clientCert = " --cert C:\certs\WS101._.007.pem";
// setting the path where cURL can find the client certificate’s
// private key:
$clientKey = " --key C:\certs\WS101._.007.key";
// setting the key password:
$keyPW = " --pass ckp_1193927132";
...
?>

📘

Please note that this script is extended in the next chapter by the statements doing the actual HTTP request.

📘

For making the above TLS initialization process work, ASP requires both the client and the server certificate to be present in certificate stores.

In other words, before ASP can communicate via TLS, both certificates have to be installed first. The following steps which assume ASP running on Microsoft IIS 5.1 under Windows XP, will guide you through this set up process:

After installing both certificates one could assume that the environment allowing ASP to communicate via TLS is set up. However, there is still one thing which makes the communication fail: IIS – running your ASP – has a Windows user which does not have the necessary rights to access the client certificate private key. Although accessing the private key is not really necessary for establishing the TLS connection to the Gateway, the IIS user needs access rights for running the authentication process in ASP.

📘

For granting rights to a user, Microsoft provides the WinHttpCertCfg.exe tool you can download for free under:

http://www.microsoft.com/downloads/details.aspx?familyid=c42e27ac-3409-40e9-8667-c748e422833f&displaylang=en

After installing the tool, open a command prompt, switch to the directory where you have installed the tool, and type in the following line for granting access to the IIS user:

winhttpcertcfg -g -c LOCAL_MACHINE\\My -s WS101._.007 -a IWAM_MyMachine

LOCALMACHINE\My determines the key store where the personal certificates for the local machine account are stored. After installing the client certificate in the personal certificates store as described above, the client certificate can be found under this path, so there is no need to provide another path.

WS101._.007 is the name of the client certificate. You have to adapt this name to the name of your client certificate. Therefore, check the name displayed for the client certificate in the mmc console after installing it as described above. Finally, IWAM_MyMachine denotes the IIS user name.

📘

Please note that IIS 5.1 uses IWAM_MachineName by default.

That means if your machine has the name IISServerMachine, the IIS user will be called IWAM_IISServerMachine. Note that other IIS versions might use a different naming scheme.

If you do not know your machine name or IIS user name, check the IIS documentation and contact your administrator.

Now you are ready to use TLS in your ASP code. The code extending the ASP script started in the previous chapter is reduced to only one additional statement which tells WinHTTP which client certificate to send (and where to find it) when contacting the Gateway:

<%@ language="javascript"%>
<html>...<body>
<%
...
// setting the path where the client certificate to send can be found:
request.setClientCertificate("LOCAL_MACHINE\\My\\WS101._.007");
...
%>
</body></html>

📘

Please note that if you use VB Script, the code looks almost the same – however, do not forget to replace the doubled backslashes in the path with single ones (i.e. the path to the certificate would be "LOCALMACHINE\My\WS101..007" instead).

This script is extended in the next chapter by the statements doing the actual HTTP request.