For Distribution to IBM Customers Only

Testing Client Certificates with Rational Robot's VU Language

Document Version: 0.4 (DRAFT)

Document Date: March 9, 2004

For Distribution to IBM Customers Only By: Robert Wu, Jeff Robbins, and Brian Massey

Abstract...... 1

Background...... 1

Technique Overview...... 3

Files & Scripts...... 3

Stunnel Files...... 3

startstunnel.c...... 3

StartStun.s and StopStun.s VU Language Test Scripts...... 4

Steps to use the solution...... 7

Other Things to Consider:...... 9

Abstract

Many web applications require each browser client to have a unique digitally-signed certificate (often referred to as a "personal digital certificate" or a "client digital certificate"). Multiple virtual testers (each of which is an executing instance of a VU language script recorded by Rational Robot) can each present a unique client certificate or a client certificate per agent machine to a web application through the technique described in this document.

Background

A Digital Certificate is an attachment to an electronic message used for security purposes. The most common use of a digital certificate is to verify that a user sending a message is who he claims to be, and to provide the receiver with the means to encode a reply.

Page 1 of 10

For Distribution to IBM Customers Only

When a client connects to a secure server, the server responds with an encrypted message and a certificate. The certificate is an attachment to an electronic message used for security purposes that verifies that a user sending a message is who they claim. The certificate also provides the client with the means to encode a reply. This certificate provided by the server is digitally signed by a 'Certificate Authority' (CA) - which is a trusted third party certificate provider such as Verisign.

This is in short how it works.

1) On the client side, the browser requests a secure page (usually at a URL starting with

2) The web server responds - sending a digital certificate that verifies the server
identity.

a) The client browser verifies the certificate.

b) The browser ensures the certificate was issued by a trusted party

c) The browser checks to determine if the certificate is still valid

3) The browser uses the public key within the certificate to encrypt a random symmetric
encryption key and sends it to the server with the encrypted URL required as well as
other encrypted http data.

4) The web server decrypts the symmetric encryption key using its private key and uses
the symmetric key to decrypt the URL and http data.

5) The web server sends back the requested html document and http data encrypted
with the symmetric key.

6) The browser decrypts the http data and html document using the symmetric key and
displays the information.

It is also possible for a client to present a certificate, called a client certificate or peer certificate, to a server. Most secure web sites don't require client certificates - especially not consumer-oriented sites (ex. Amazon.com). Of course, some businesses requiring extra security configure their servers to require that the client present a specific certificate, which is installed on the client before it first connects with the server. Client certificates are the same as server certificates; client certificates differ from server certificates only in that they originate on the client and not the server.

Page 2 of 10

For Distribution to IBM Customers Only

Technique Overview

The technique for emulating the use of client side certificates with IBM Rational Performance Tester uses open source software called Stunnel, as well extending VU scripts via external C libraries. You will start the OPENSSL-based processes named stunnel on the machines where the virtual tester processes execute (specifically, the test agents and/or the local computer). Then, the executing virtual testers send all http requests to the stunnel processes instead of the actual web server. The stunnel processes encode the http requests and send them to the web server. When the web server responds to the http requests, the responses are returned to the stunnel processes, which perform the necessary decoding and send the decoded responses to the executing virtual testers.

Performance Tester supports server side certificates (Secure Socket Layer or SSL) automatically for you. There is no need to use the technique described in this document for configurations that use server side certificates without also using client certificates.

Files & Scripts

This section describes the key files needed to implement this technique. Note that this document was developed specifically with Windows users in mind (both local and agent machines). For UNIX agents, shared libraries instead of DLLs would need to be used. UNIX agent users should keep this difference in mind as they read this document.

Stunnel Files

The version of STunnel being referenced in this document is 4.05. The Stunnel files can be downloaded from The files required are openssl.exe, Stunnel-<version number>.exe, libssl.dll and Iibeay32.dll. Per the installation instructions you need to copy the libssl.dll and libeay.dll to the Windows\system directory of the machine(s) where the stunnel process will execute.

In addition, you will need to create a dll to import into Rational Test Manager. This DLL is created from a C source file that will need to be compiled with a Windows C compiler or the GNU gcc compiler. Please see Step 1 within the Steps to use the solution section of this document for compilation instructions.

startstunnel.c

The following source code comprises startstunnel.c, which will be compiled into startstunnel.dll:

Page 3 of 10

For Distribution to IBM Customers Only

#include <windows.h> #include <winsock.h> void killprocess(int pid){ DWORD dwExitCode;

GetExitCodeProcess(pid,SdwExitCode); TerminateProcess(pid,(UINT)dwExitCode); CloseHandle(pid); } int startstunnel(char *arg){

STARTUPINFO si; PROCESS_INFORMATION pi; ZeroMemory(&si, sizeof(si)); ZeroMemory(&pi, sizeof(pi)); si.cb = sizeof(si);

CreateProcess (NULL, arg, NULL, NULL, FALSE, 0, NULL, NULL, &si, &pi);

return pi.hProcess; } char* gethost () {

WORD wVersionRequested; WSADATA wsaData; char HOSTNAME[40 96] WSADATA p;

WSAStartup ( (2«8) | 2, &p) ; gethostname (HOSTNAME, 4096); WSACleanup( ); return HOSTNAME;

The function killprocess is used in a VU script to kill a Stunnel Process, startstunnel is used to start a STunnei process and gethost is used to obtain the host name of the executing machine. Gethost is necessary if you are executing a suite using agent machines..

StartStun.s and StopStun.s VU Language Test Scripts

The following VU language test scripts are needed in order to stop and start the stunnel process on each machine hosting virtual tester processes. First we have a script initialize some persistent variable with the local host and local port information. In this configuration, we are starting a STunnei process per agent machine. If a STunnei process was needed to be started per Virtual User this script could be integrated into the StartStun.s VU script below. This script is called STunlnit.s:

#include <VU.h>

external_C string func gethost()

string hostname;

Page 4 of 10

For Distribution to IBM Customers Only

persistent string localhost; persistent string localport; {

hostname=gethost ();

localhost = hostname+"<full dns name> ";

//e.g. machine.us.ibm.com

localport = "3885"; //any port above 1024

Next we have a VU script to copy the necessary files from a server machine to a local machine and start the Stunnel process. The script is named StartStun.s:

#include <VU.h>

external_C func startstunnel(arg)

string arg;

{}

string command;

persistent pid;

persistent string localhost;

persistent string localport;

{

// In this instance the STunnel configuration file and

// executable are kept on a server machine. The first

// step is to copy the files locally.

system ("mkdir c:\\temp\\stunnel4_05");

system ("xcopy \W\server\share\stunnel4_05\ " +

"c:\\temp\\stunnel4_05 /S"); //set up command for starting STunnel Process

command = "c:\\temp\\stunnel4_05\\stunnel-4.05.exe "+

"c:\\temp\\stunnel4_05\\stunnel.conf"; //Start the process

pid = startstunnel(command);

delay(3000);

Page 5 of 10

For Distribution to IBM Customers Only

There is also a VU script to kill the STunnel process. This script is called StopStun.s:

external_C func killprocess(p)

int p;

{}

persistent pid;

{

delay(5000) ;

killprocess(pid) ;

Lastly, there is the STunnel Configuration file. This is the command line arguments used by the stunnel executable. This parameters used in this setup are stored in a file called stunel.conf. Additional parameters can be set as needed. Consult the FAQ on the Stunnel web site for additional information. Note that the pern files are stored on the file server and copied over to the temp directory in StartStun.s.

CAfile=c:\temp\STunnnel4_05\root.pern

cert=c:\temp\STunnel4_05\server.pern

client=yes

debug=7

output=stunnel.log

[HTTP]

accept=3885

connect=<server under test>:443 // (e.g.

Page 6 of 10

For Distribution to IBM Customers Only

Steps to use the solution

1.Compile and link the startstunnel.c to create startstunnel.dll. Complete
compilation instructions can be found in the VU Language Reference (as of this
writing, the most current version of the VU Language Reference is at
page 70 of this link contains the
compilation information). Simplified complication instructions are as follows:

Compile: cl/c startstunnel.c

Link:link startstunnel.obj /dll /exportSstartstunnel /export:killprocess

Unix agent users should see the VU Language Reference for UNIX share library compilation instructions.

2. Copy the resulting startstunnel.dll file to the following folder on the local machine:
~ProjectNameTestDatastore\DefaultTestScriptDatastore\TMS_Scripts\externC

3. If any agent machines are being used copy the startstunnel.dll file to the following
folder on the agent machine (created when the agent is started):

C:\temp\rtagent_O\externC

4. In TestManager, select Tools->Options->VU Compilation and select
startstunnel.dll as an external C library to use.

5. Use openssl to create the server.pem file from p12 client digitally-signed certificate
file (named cert.p12 in this example) with the following command:

openssl pkcs12 -in cert.p12 -out server.pem -passin passPASSWORD -clcerts -nodes

F:\Customers\ABC\EBank\openssbopenssl pkcs12 -in ..\export_cer.pfx -out server, pem -passin pass:11 -clcerts -nodes MAC verified OK

6. If a root CA exists, extract the root key root.pem from cert.p12 as follows:
openssl pkcs12 -in cert.p12 -out root.pem -passin passPASSWORD -cacerts -nokeys

7. Create a configuration file (stunnel.conf above) to be used to start the STunnel
process.

8. Place all necessary files on the server so that the StartStun.s can copy them to the
local temp directory once a suite is started. This includes server.pem, root.pem,
Stunnel.conf and stunnel-4.05.exe.

9. Modify all http_request commands so that they point to the local stunnel process,
instead of the actual server under test. These required edits could potentially be

automated via perl or a similar mechanism.

persistent string localhost; persistent string localport;

Page 7 of 10

For Distribution to IBM Customers Only

/* Original command:

host_name_ca_raleigh_corp_co_nc_l = http_request ["stunl005"] "host_name.ca.raleigh.corp.co.nc:4 43", (HTTP_CONN_DIRECT | HTTP_CONN_SECURE_12 8), */

/*Modified command: */

host_name_ca_raleigh_corp_co_nc_l = http_request ["stunl005"] localhost+":"+localport, HTTP_CONN_DIRECT,

/* delete HTTP_CONN_SECURE_128 10. Build the suite Create suite

In the suite, the sequence of scripts should be as follows:

Stunlnit.s

StartStun.s

test script(s)

StopStun.s

In this ordering of test scripts, each virtual tester will start its own Stunnel process. Note that one Stunnel process could potentially serve multiple virtual testers, in order to reduce required memory. In order to accomplish this goal, one might create a user group with a single virtual tester that only runs Starttun.s. Other virtual testers could be delayed (via a construct such as a sync point) from executing http commands before the first virtual tester initializes the shared Stunnel process. Note, however, that a single Stunnel process supports only a single client certificate; all virtual testers that share a single Stunnel process will share the same client certificate.

The following is a sample of a suite that started a Stunnel process per agent machine, as opposed to starting one per virtual tester, in order to reduce memory consumption by Stunnel processes:

Page 8 of 10

For Distribution to IBM Customers Only

Within this suite, the Initialization User group is run with a fixed number of users corresponding to the number of agent machines used. Thus, the Stunnel process is initiated and started on the agent machines. The StunnelTest User group initializes the global variables and waits for the agents to start (via the sync point). Then all users execute the appropriate scenario and the Stunnel process is stopped on the agent machines. The Finished sync point is used to ensure the processes are not killed before all users are done.

11. Run the Suite

When you run the suite, the Stunnel server is started with a command prompt window, and communications between TestManager and the Stunnel process(es) can be viewed dynamically during the test run (the "-D 7" option used in startstunnel.c enables full logging).

Other Things to Consider:

1. In the scripts, always use the domain host name for the stunnel host. Host
names such as "Localhost" or "RobotHost" that are not domain-matched will cause
cookie problems during the playback.

2. Pros and cons of having multiple virtual testers share a single stunnel
instance:

• Pro: a reduction of the number of Stunnel processes and RAM required.

• Con: One Stunnel instance can support only one client certificate. If the server

Page 9 of 10

For Distribution to IBM Customers Only

allows each client to use the same client certificate, one Stunnel instance could theoretically support an unlimited number of VTs. But if the server configuration requires a unique certificate for each user, then you'd need a unique Stunnel instance for each user.

3. The recommended number of stunnel processes per machine is
machine-dependant. You need to keep on eye on the machine's resources to
ensure that stunnel processes are not consuming all available RAM. Note that
running the stunnel processes on the same machines as the VT's adds additional
overhead to the test agent, but provides the easiest configuration. One may run the
stunnel processes on a machine other that the agent; however, the VU scripts must
reflect the host name of this separate stunnel host.

4. In this document 7788 is the TCP/IP port that the Stunnel process listens to for
incoming connection attempts. If using multiple Stunnel processes on a single
agent, each Stunnel process must use a different port. The VU language read-only
variable _uid could be used as an offset from some base port number if all VTs need
to use a unique certificate (and therefore a separate Stunnel process). Any port(s)
above 1024 may be used by Stunnel, as long as no other processes or services have
locked that port.

5. In regards to the number of virtual testers a single stunnel process can
support, there is no hard data on this topic. Most likely one would see performance
go down as more VTs try to use the same Stunnel process. There has been little
"load testing" of the Stunnel process itself. One implementation of the technique
described in this document involved a single STunnei process supporting 100 VT's
with no performance degradation on the agent machine. In other words, the Stunnel
instance could likely have supported more than 100 virtual testers. Machine, script
size and various other factors will come into play in any given implementation.

6. Stunnel 4 is different than Stunnel 3. V3 uses command line options to specify
ports to listen on and forward to. V4 uses a configuration file.

7. Start with a baby steps - pull up Internet Explorer, and use this URL, with the
appropriate port number in place:

that Stunnel is listening on>/

If that does not work with Internet Explorer, then it won't work with VU.

Page 10 of 10