Chapter 6: SSL Security Setup

Home Prev	InControl 4.00.02 SDK Guide	Next

Whenever using the API on a platform that is not Microsoft Windows™ or if not using .NET™, security between the API and the InControl server must be secured using SSL.

To set up SSL communication, the following steps need to be performed on the Windows computer that is running the InControl server:

Configure the InControl server:
1. Open the InControl server management interface and set the HTTPMode to be SSL.
2. As shown in the example screenshot below, set the Certificate Path to be the certificate's public key (.cer) file.
3. Restart the InControl server.

Install the certificate with the private key to the machine key store:
1. Open a Windows console and enter the command:
```
 > mmc
```
  This will open up the interface of the Windows mmc utility.
2. Select the menu option: File > Add/Remove Snap-in...
3. Double click Certificates to start a wizard.
4. Choose Computer account in the wizard and press Next.
5. Choose Local computer and press Finish to close the wizard.
6. Right-click Personal in the mmc navigation tree and choose All Tasks > Import...
7. A wizard will open which allows the relevant .pfx file for the certificate to be imported.

Register the port to use with the certificate
1. Still in mmc, double click the imported certificate and this will open a new dialog to display the certificate's properties.
2. Select the Details tab and find the Thumbprint value.
3. Copy and paste the thumbprint value into a text editor, close the dialog and close mmc.
4. Remove the spaces from the thumbprint in the text editor. For example, an original thumbprint would like this:
```
 93 05 7a 88 15 c6 4f ce 82 2f fa 91 16 52 28 78 bc 53 64 17
```
  After editing, this thumbprint becomes: 93057a8815c64fce822ffa9116522878bc536417
5. Choose an arbitrary and unique CLSID. This is an 128-bit number, expressed in hexadecimal. An example CLSID that could be used for this purpose is:
```
 d1f6aa3a-a814-4373-a316-4f43d00ecb1e
```
6. Issue the following Windows netsh console command with the thumbprint and CLSID inserted in the relevant position to register port number 443:
```
 > netsh http add sslcert ipport=0.0.0.0:443
		certhash=<thumbprint_without_spaces>
		appid={<CLSID>}
```
  Note that the CLSID must be contained in curly brackets. Here is the same command with inserted values:
```
 > netsh http add sslcert ipport=0.0.0.0:443
		certhash=93057a8815c64fce822ffa9116522878bc536417
		appid={d1f6aa3a-a814-4373-a316-4f43d00ecb1e}
```

SSL communication between the API and the InControl server is now possible based on the imported certificate for security.

SSL Client Setup Code Example

Below is a code example that illustrates how to set up a WCF client that uses HTTPS.

// Define the address for the connection
	
EndpointAddress epa =
   new EndpointAddress("https://icserver.example.com:443/InControl");
	
//Create the bindings
	
var bindings = new BindingElementCollection();

var rsbe = new ReliableSessionBindingElement();
bindings.Add(item: rsbe);

var htbe = new HttpsTransportBindingElement();
htbe.AuthenticationScheme = AuthenticationSchemes.Basic;
bindings.Add(item: htbe);

Binding reliableSessionOverHttps =
   new CustomBinding(bindingElementsInTopDownChannelStackOrder: bindings);
	
// Create the client
		
ChannelFactory<IRemoteServer> cf =
   new ChannelFactory<IRemoteServer>(binding: reliableSessionOverHttps,
   remoteAddress: epa);
	
// Specify the client credentials
		
cf.Credentials.UserName.UserName = "MyUsername";
cf.Credentials.UserName.Password = "MyPassword";

// Retrieve the server object
		
IRemoteServer server = cf.CreateChannel();
	
// Increase the timeout if required for deployment
		
((IContextChannel)server).OperationTimeout = new TimeSpan(0, 3, 0);