Using PolarSSL in Microsoft Visual Studio 2010

1. Introduction

This tutorial will show how to get started with the PolarSSL cryptography library in a Windows environment, using Microsoft Visual Studio 2010 Express Edition. We will be using the sample client application (from this tutorial). This simple application sends a http request to read an html page from a server. We will be using PolarSSL to enable encrypting our communication with the server with SSL.

In this step-by-step tutorial we will show you how to setup Visual Studio for PolarSSL and the sample application. Only assumption is that you have already installed Visual Studio Express Edition for C++ (or the Professional Edition).

To keep things simple, the sample application is a command line program, written in C. PolarSSL can be integrated just as easily in any C/C++ application, with or without a (graphical) user interface.

2. Download PolarSSL

The first thing we need to do is get the PolarSSL source code. Download 'polarssl-<version>-gpl.tgz' from: here. To unpack this file you can use a tool like 7-zip.

The default installation of Visual Studio should have created folder: My Documents\Visual Studio 2010\Projects. Extract the contents of the .tgz file to this location. Make sure to extract the second occurrence of the polarssl- folder. Otherwise the paths given later on in this tutorial won't match.

3. Open the visual studio solution

You should now have a folder: My Documents\Visual Studio 2010\Projects\polarssl-<version>\visualc\VS2010.

In this folder you will find the file 'PolarSSL.sln'. This is a Visual Studio 'solution' file, which holds all the components PolarSSL consist of and the rules to build the PolarSSL library.

Double click the .sln file to open Visual Studio.

4. Build

When Visual Studio opens it shows all the components of the PolarSSL source code. We are only interested in the 'PolarSSL' project (shown in bold to indicate that it is the default project) which builds the PolarSSL library file. Later on we will link to this library file from our sample application.

Now we can build the library. Since we won't be debugging PolarSSL we will build the 'Release' version. Select the 'release' configuration in the icon bar. Then press F7 to start the building process.

Not all components may have been built successfully. This does not matter as long as the PolarSSL project was built !
Check this by looking in folder: My Documents\Visual Studio 2010\Projects\polarssl-\visualc\VS2010\Release. The file 'PolarSSL.lib' should be present.

5. Set up a new project

Now we are ready to setup the sample project. Close the current solution by clicking on 'Close solution' in the file menu.

Create a new project by selecting the menu command: File / New / Project (or use the 'New' icon).

Visual Studio will then ask what kind of project you would like to create. Choose 'Empty project'. Type the name of the project, for instance 'polar_client_demo'. Check that the 'My Documents\Visual Studio 2010\Projects' folder has been selected as the location (the same base path as used for PolarSSL). Leave the 'create directory for solution' flag enabled. After clicking the OK button you will end up with a new, empty, project.

6. Copy sample application

To create an application we must add a source file. In the solution explorer, right click on 'Source files' and select Add / New item.

Visual Studio will ask what kind of item you would like to create. Select 'C++ file'. Enter a name for the file, for example 'client.c'. Click on 'Add'.

7. Compile and test

Before building the new project we need to add one project setting. In the solution explorer, right click on the project name, in this case 'polar_client_demo' and select 'Properties'.

In the properties dialog select Linker / Input. Select 'Additional dependencies', click on the down arrow and 'edit'.

Type 'wsock32.lib' in the dialog and click on OK twice. This library needs to be added to the project since line 4 of the source code includes the 'winsock' header file. Visual Studio needs to know where to find the executable code for this file.

You can now build the sample application. Press the F7 key. If all goes well Visual Studio will show 'Build: 1 succeeded' in the output screen.

Start the application by pressing the F5 key. Note that line 16 of the source code states that the application should load the home page of a well-known search engine.

The application shows a command screen, stating that a connection has been made to the server and shows the server's response. Press enter to close the application.

Now let's assume that we want to connect to the server using https. Change line 15 to:

#define SERVER_PORT 443

Build (F7) and run (F5) the application again. Not surprisingly the application will show an error. We first need to set up an SSL connection. And that is where PolarSSL comes in !

8. SSL Explanation

The SSL/TLS part of PolarSSL provides the means to setup and communicate over a secure communication channel using SSL/TLS.
Its basic provisions are:
• Initialize an SSL/TLS context.
• Perform an SSL/TLS handshake.
• Send/receive data.
• Notify a peer that a connection is being closed.

Many aspects of such a channel are set through parameters and callback functions:
• The endpoint role: client or server.
• The authentication mode: whether certificate verification should take place.
• The host-to-host communication channel: send and receive functions.
• The random number generator (RNG) function.
• The ciphers to use for encryption/decryption.
• A certificate verification function.
• Session control: session get and set functions.
• X.509 parameters for certificate-handling and key exchange.

PolarSSL can be used to create an SSL/TLS server and client by providing a framework to setup and communicate through an SSL/TLS communication channel. The SSL/TLS part relies directly on the certificate parsing, symmetric and asymmetric encryption and hashing modules of the library.

9. Modify application to use SSL

How to add PolarSSL to the sample application is described in this tutorial.
For now replace the code in the client.c file by copy and pasting this code over the existing code.

Under Linker / General / Additional Library Directories add : '....\polarssl-1.1.3\visualc\VS2010\Release'. Again without the quotes. You may need to replace the version number with the one you installed. If you unpacked and compiled PolarSSL in a different location you can enter the full path to the location of the PolarSSL.lib file.

Under C/C++ / General / Additional Include Directories add: '....\polarssl-1.1.3\include'. Use the same renaming as for the library directory mentioned above.
Click on OK.

10. Compile and test

You can now build the modified sample application. Press the F7 key. If all goes well Visual Studio will show 'Build: 1 succeeded' in the output screen.

Start the application by pressing the F5 key. The application shows a command screen, stating that a connection has been made to the server and shows the server's response. But this time we are communicating over a secure SSL connection !

11. Conclusion

This tutorial showed how to set up a Visual Studio project that uses the PolarSSL cryptography library.

This sample application is very simple. In a larger project you might want to wrap the code to call PolarSSL in functions like: InitializeSSL, OpenSSLConnection, ExecuteSSLRequest, ReadSSLResponse and CloseSSL. Or use a C++ class where the initialize and close functions can be placed in the constructor and destructor.

You also might want to copy the PolarSSL.lib files to the Debug/Release folders of your project to ease the rollout of your application.