Communicating with FAST ESP from a .NET application through SSL

For a custom application we’re building, we decided to use SSL to communicate between our .NET application and the FAST query server. Setting up SSL to enable secure communication between a .NET application and a FAST query server is fairly simple but the FAST documentation doesn’t exactly explain it a straightforward manner. These were the steps I took to enable and use SSL.

The first step is to request a new certificate.You can use the openssl executable found in c:\esp\bin to request the new certificate. Open up a command prompt and change the working directory to c:\esp\bin. Enter the following command:

openssl req –new –out client.pem –days 365 –config c:\esp\etc\openssl.cnf

The above command creates a new certificate and should be fairly easy to understand. The request file will be saved as client.pem and the certificate generated (later) will be valid for 365 days. The configuration file specified by the –config parameter is the file that specifies the fields that you will be prompted for as identification to be included in the certificate request. When you run the command, you will be asked to enter and verify a passphrase. You will then be asked for the fields specified in the config file (note that you can just leave the ‘extra’ attributes being asked for blank). The command also outputs the private key to a file called privkey.pem. The exact output of the command is below:

C:\Users\btubalinal>openssl req -new -out client.pem -days 365 -config c:\esp\etc\
Loading 'screen' into random state - done
Generating a 1024 bit RSA private key
writing new private key to 'privkey.pem'
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (eg, YOUR name) []:
Email Address []:
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

The next step is to create a PKCS12 file from the .pem file. Again, you can use the openssl executable to create this:

openssl pkcs12 -export -out client.p12 -in client.pem -inkey privkey.pem

This exports out the PKCS12 file to a file called client.p12. It uses the client.pem file (which is the certificate) and the privkey.pem file (which is the private key) and merges them into the client.p12 file. The client.p12 file needs to be imported into your personal certificate store on whatever machine you’ll use to access the FAST query server. So copy the p12 file to your machine and double click the file to start the certificate import wizard. The wizard will ask you for the password/pass phrase you gave when creating the original client.pem certificate. The rest of the wizard is straightforward.

The last file we need to generate is a .cer file. This file is what is required to be used by your .NET application to issue the queries to the query server. Here is the command to create the .cer file:

openssl x509 -in client.pem -out client.cer -outform DER

This command basically converts the client.pem certificate (which is in PEM format) to a certificate that is in DER format and saves it to the client.cer file. Copy this cer file to a location on your machine where your app has access to.

The following is a code snippet that shows how the .cer file is used:

   1: using System;
   2: using Com.FastSearch.Esp.Search;
   3: using Com.FastSearch.Esp.Search.View;
   4: using Com.FastSearch.Esp.Search.Result;
   5: using Com.FastSearch.Esp.Search.Query;
   6: using Com.FastSearch.Esp.Search.Http;
   7: using System.Collections.Specialized;
   9: namespace FASTSampleSSL
  10: {
  11:     class Program
  12:     {
  13:         static void Main(string[] args)
  14:         {
  15:             string fastserver = "";
  16:             string certfilepath = @"c:\client.cer";
  18:             NameValueCollection searchFactoryConfiguration = new NameValueCollection();
  19:             searchFactoryConfiguration.Add("Com.FastSearch.Esp.Search.Http.QRServers", fastserver);
  21:             ISearchFactory searchFactory = SearchFactory.NewInstance(searchFactoryConfiguration);
  23:             string fastserverurl = "https://" + fastserver;
  24:             HttpSearchEngine searchEngine = searchFactory.GetSearchEngine(new Uri(fastserverurl));
  25:             ISearchView view = searchEngine.GetView("mypublishedview", fastserverurl, false, false, certfilepath);
  27:             IQuery query = new Query("string(\"sharepoint\", mode=simpleall)");
  28:             IQueryResult result = view.Search(query);
  30:             //PROCESS THE RESULTS
  31:         }
  32:     }
  33: }

Most of the code should be easy enough to understand. The cert file is used in the call to get the view from the instance of the HttpSearchEngine. The FAST ESP API will take care of reading that certificate file and using it to communicate securely to the FAST query server.