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
Copyright International Business Machines 2004. All rights reserved.
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.
Copyright International Business Machines 2004. All rights reserved.
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
https://).
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.
Copyright International Business Machines 2004. All rights reserved.
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 http://www.stunnel.org/download/binaries.html. 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:
Copyright International Business Machines 2004. All rights reserved.
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;
Copyright International Business Machines 2004. All rights reserved.
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);
Copyright International Business Machines 2004. All rights reserved.
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.
www.SiteYouAreTesting.com)
Copyright International Business Machines 2004. All rights reserved.
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
http://pubiibfp.bouider.ibm.com/epubs/pdf/i265628o.pdf; 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;
Copyright International Business Machines 2004. All rights reserved.
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:
Copyright International Business Machines 2004. All rights reserved.
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.
server
If the
Copyright International Business Machines 2004. All rights reserved.
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
machine
number
of
stunnel
processes
per
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:
http://localhost:<port that Stunnel is listening on>/
If that does not work with Internet Explorer, then it won't work with VU.
Copyright International Business Machines 2004. All rights reserved.
Page 10 of 10