web_set_certificate_ex

Sets the certificate and key file attributes.

C Language

int web_set_certificate_ex( char *option_list, LAST );

Example: web_set_certificate_ex

Authentication Functions

Java Language

int object.set_certificate_ex( String [] option_list );

Example: web.set_certificate_ex

Authentication Functions

Java Syntax

Argument	Description
object	An expression evaluating to an object of type WebApi. Usually web for Java. See also Function and Constant Prefixes.
option_list	The supported options are described below.
LAST	A marker that indicates the end of the argument list.

option_list can either be made up of one or more options without the CertIndex option, or the CertIndex option by itself.

The supported options are:

CertFilePath	The path and file name of the certificate (Sockets replay only). Set the value to NULL to clear the certificate. Because the certificate cannot be cleared for a working TLS session, you might need to call web_set_sockets_option first in order to stop and reset the session. For details, see Example: web_set_certificate_ex.
CertFormat	The format of the certificate: PEM or ASN1 (Sockets replay only).
SendCertChain	If the certificate should be sent to the server with or without an existing chain. Setting SendCertChain to 1 sends the chain; not specifying a value, or specifying the default value 0, does not send the chain.
KeyFilePath	The path and filename of the certificate's key file (Sockets replay only).
KeyFormat	The format of the key file: PEM or ASN1 (Sockets replay only).
Password	The password required by the certificate (Sockets replay only).
StringToSign	A PKCS7–compatible digital signature is generated from the StringToSign text, and stored in the SignedStringParam parameter. This option is meaningless if SignedStringParam is not used. (Sockets replay only).
SignedStringParam	The name of the parameter to store the digital signature created from the StringToSign argument. This option is meaningless if StringToSign is not used. (Sockets replay only).
CertIndex	The WinInet certificate index. It specifies a one–based index of the security certificate within the IE certificate database. The index is the same on WinInet and Sockets replay. Existing scripts might reference the wrong index due to changes in the implementation. To set the index, open “Internet options -> Content -> Certificates” and count to the correct certificate starting from 1. Alternatively, record and regenerate the script.
CertThumbprint	The thumbprint of the certificate. (For C language only) Tip: The certificate thumbprint can be obtained from the certificate’s details.

Return Values

This function returns LR_PASS (0) on success, and LR_FAIL (1) on failure.

Parameterization

The following argument(s) can be parameterized using standard parameterization: List of Options

General Information

web_set_certificate_ex sets the certificate and key file attributes, such as its location, type, and password. This information is used for HTTPS requests that require a certificate. All of the parameters are null–terminated character strings. The keywords are not case–sensitive; but the values attributed to the keywords are case–sensitive. Spaces are not allowed at the beginning or end of a keyword value.

In most cases, this function is generated automatically. VuGen records the relevant certificate files and sends them to the machine under test during replay. In instances where this function was not generated automatically, you can manually add it by following these steps:

To use this function, you must add it to the Vuser's file list. Select Group Information > More > Files tab in the Controller. Alternatively, you can copy the certificate file to all machines running the script.

To determine the certificate and key information, extract it from the machine on which the script was recorded. To extract a certificate and key file:

In Internet Explorer:

Choose Tools > Internet Options. Select the Content tab and click Certificates.
Select a certificate from the list and click Export.
Click Next several times until you are prompted for a password.
Enter a password and click Next.
Enter a file name and click Next.
Click Finish.

For other browsers, consult the browser help for the equivalent procedure.

The resulting certificate file is in PKCS12 format. To convert the file to PEM format, use the openssl_lt.exe utility located in the bin directory. To run the utility, open a command window, set the working directory to the bin directory and do the following sequence:

	<Path to LoadRunner Professional root folder>\bin>openssl_lt
	OpenSSL> pkcs12 -in <input file> -out <output file>
	Enter Import Password:
	MAC verified OK
	Enter PEM pass phrase:
	Verifying - Enter PEM pass phrase:
	OpenSSL>exit

Copy the output file with the .pem extension to the replay machine(s). This file serves as both the certificate file and key file.

Insert a web_set_certificate_ex function into the script, specifying the name of the output file.

When installing a certificate with private key in Internet Explorer, if you choose strong private key protection, you can set the security level of this certificate. The default is medium. The socket mode cannot handle the high security level with the CertIndex parameter. If you do not use CertIndex, the security level can be high but then you must provide the certificate password.

To locate a certificate, you can use any one of CertFilePath, CertIndex or CertThumbprint. However, use only one of these options at a time because the API processes only one of them, in the following order of precedence: CertFilePath, CertThumbprint, CertIndex. For example, in the following case, CertIndex will be ignored.

web_set_certificate_ex("CertIndex=8", "CertThumbprint=cd610c0b387c6eb670e2c564abb44ead2a3186d9", LAST);

Note that when recording a new script with an unexportable certificate, the new script will generate web_set_certificate_ex with the certThumbprint.

The Wininet mode only handles the low security level.