Client Certificate Plugin
Imports client certificates on the agent and uses them in web requests if requested by server.
Added as a webtest plugin, called Client Certificate. The certificate has to be available as a P12 or PFX file, and the path to this file can be set in 3 diffrent ways
Using the "Certificate Path" property
Using a parameter in the script and set the parameter name in the "Certificate Path Parameter" property (as the example above)
Using a parameter in the loadtest and copy this parameter into the webtest using the loadtest plugins "LoadTest Context Copy" or "Set Test Context Parameter" plugins. With the latter, diffrent client certificates can then be used randomly, in sequence or unique for each virtual user or test iteration. The parameter name used in the loadtest must be set as the "Certificate Path Parameter" property value. Read more about those plugins on page Parameter plugins
The password for loading the P12 or PFX file can be specified in any of the above options as well, using the property "Certificate Password" or "Certificate Password Parameter" accordingly.
Setting the property for Path or Password will not override the use of parameters, if a parameter is specified, exists in the context and has a value other than null and is not an empty or whitespace only string, the parameter value overrides the property value.
Automatic deployment of certificate files
Please read the page on Deployment Items if you want automatic deployment of certificate files to all agents (as in the example above).
Operation
If the "Log Debug info" property is set to True (default is False) additional information will be logged in the test results log for the webtest run. If it is set to False, only warnings and errors will be logged in the testresults. Logging is done at the beginning of the test iteration.
The client certificate is loaded from file at the beginning of each iteration, and used to identify the correct certificate in the users certificate store. It is automatically imported to the certificate store if the corresponding "Import trusted/untrusted certificate" properties are set to True, and only if it does not exist in the local users certificate store already. The certificate needs to be in the users cert store since the actual SSL handshaking is performed by the operating system and the kernel, rather than the .NET machine that runs the webtest code. Certificates added by this plugin will have the Custom Name/Alias field set to "VSTT" so they can be easely identified and removed if needed (for cleanup).
Certificates are stored in the users personal certificate store, and can be viewed (and removed) using "certmgr.msc" on windows. When running on an agent in a test rig, the user account running the agent process certificate store will be used (see the service config of the agent).
Above as example run with "Log Debug info" set to True.
The path being used is logged (i.e. the value being used from either a parameter or property)
The certificate is loaded from file in all cases, this is order to get the thumbprint of the client certificate in order to uniquely identify the certificate in the cert store.
Certificate trust chain and expire date is validated. If the certificate CA or intermediate CA certificates are not installed or not trusted, the client certificate is not trusted either. If the do not trust before or do not trust after dates invalidate the certificate, it is not trusted either. The certificate will still be used and sent to the server, but a warning message is logged if this is the case (also if debug logging is false) since the server might not accept the certificate
Private key is necessary in order to use client certificates. If the private key is missing, and error is logged (also when debug logging is false)
Certificate is either already installed in the user cert store, or it will be installed at this Point if the property "Install trusted certificate" is set to True in the properties for the plugin. Any errors that occur during install will be logged at this Point (also if debug logging is false). If the certificate is not trusted, and the property "Install untrusted certificate" is not set to True (default is False), the certificate will not be installed.
If Everything worked out without errors, the certificate will from this Point on be added to all requests. It will only be used if the server requests or requires a client certificate, and the servers list of accaptable CA's (Issuers) matches the Issuer of the client certificate. If the client certificate does not match the Issuers requested, it will not be sent to the server and no error or warning will be logged, since this is handled by the operating system. The error logged in the webtest will be the standard SSL error that a secure Connection could not be established.
For each web request in the web test, a context parameter called "Client Certificate" will be set, with the actually used certificate subject as the value
Debugging
If a client certificate is required by the server, but for some reason the certificate provided with the plugin does not work, one can debug the SSL handshake to get more information. In order to do this, a sniffer tool like WireShark can be used.
The most common reason to a failed attempt is that the client certificate is no longer valid or not trusted. Therefor the plugin will check for this condition and warn about it in the test results log.
In the above example, Everything seems okey (except for the warnings that the certificate is not trusted, and has expired), yet no SSL Connection could be established.
Example of a failed attempt in WireShark
In the example above we recorded the SSL handshake with Wireshark and display the recording with a filter on "ssl" packets only.
Packet 4: Client Hello is where the client presents itself to the server. In this case an SNI hostname is sent as well (the hostname in the URL used in the web request)
Packet 6: Alert from server that it does not recognize the hostname provided by the client in the previous Client Hello. This is a warning only, the server does not seem to have the intended host configured.
Packet 8: Certificate is being received from the server
Packet 9: Certificate Request and Server Hello Done, here is where the server requests that the client provides a client certificate. This packet can be investigated in WireShark by looking at the Certificate Request -> Certificate Types and Distinguished Names list of CA's (Issuers) that the server accepts client certificates of.
Packet 11: Certificate is the actual client certificate being sent to the server. This packet can also be investigated to see and verify that the intended client certificate is actually sent (by checking the Subject of the certificate for instance)
Packet 13: Here is the response from the server after it received the certificate we sent. In this case it is rejected by the server because it is expired, since the Alert has level Fatal (cannot continue) and the Description field is set to Certificate Expired