Using .NET APIs

Stormshield Data Connector .NET APIs can be integrated into your applications in order to allow them to interact with Stormshield Data Security. In this section, the examples of code are given in C#.

Setting up a Visual Studio project

  1. Create a C#.NET project, targeting .NET Framework 4.5.2. The .NET Framework 4.5.2 Developer Pack must have been installed beforehand.

  2. The .NET Framework 4.5.2 Developer Pack is only needed for compiling the application using Stormshield Data Connector. Running an application that uses Stormshield Data Connector does not require it.
  3. Add the following reference to your project: Stormshield.DataSecurity.Connector.

This assembly is found in the Stormshield Data Security installation folder: by default it is C:\Program Files\Arkoon\Security BOX\Connector.

After that, the Stormshield.DataSecurity.Connector namespace can be used to benefit from its functionalities.

Some other namespaces (found in the Stormshield.DataSecurity.Connector assembly) can also be useful to handle some Stormshield Data Security particular objects. These namespaces can be found in the given examples throughout this document.

In some cases, an interoperability DLL will need to be added as a reference to your project. These assemblies can be found in the Stormshield Data Security installation folder.

On a 64-bit operating system, the .NET executable file has to be compiled for the 64-bit platform:

  1. Go to the properties of the Visual Studio project, under the section "Build".
  2. Select "Platform target = x64" or unselect "Prefer 32-bit" if you wish to remain in "Platform target Any CPU".

Using .NET APIs

Stormshield Data Connector .NET APIs are used in the same way as all cmdlets provided by the PowerShell module. The Stormshield.DataSecurity.Connector namespace contains all the objects useful to interact with Stormshield Data Security.

The Stormshield.DataSecurity.Connector.API class is the entry point to use the APIs. This is an object that implements the IDisposable interface. Once created, you can use the Execute method to call an API.

A .NET API is called up in the same way a PowerShell cmdlet command is called up. Two overloads of the Execute method are available.

object[] Execute(string)

This overload is used to simply call a PowerShell cmdlet that involves strings only (no .NET objects). The entire cmdlet (with arguments) must be passed in the string parameter.

object[] Execute(string, KeyValuePair<string, object>[])

This overload is used to call a PowerShell cmdlet that needs one or more .NET objects to be passed as arguments. The name of the cmdlet must be passed as the first parameter. The cmdlet arguments must be passed as a KeyValuePair array (refer to the use case below).

The returned object[] functions as follows:

  • It is equal to "null" if the API does not return anything;
  • It is equal to a table that may contain one or several objects if the API returns one or several results;
  • The elements of the table can never be "null".

Examples

First overload of the Execute method

In this example, we attempt to retrieve the currently connected user.

using Stormshield.DataSecurity.Connector;
using (API api = new API())
{
  object[] objects = api.Execute("Get-SDSUser");
}

If the returned array is not empty and the first item is not "null", the user has been successfully retrieved. The first item can then be cast to a User class, from the Stormshield.DataSecurity.Connector.Kernel namespace.

using Stormshield.DataSecurity.Connector.Kernel;
User user = objects[0] as User;

If the PowerShell cmdlet returns several objects, they are all available in the objects array.

When needed, it is the responsibility of the caller to make sure that the objects array is not empty and items are not "null".

Second overload of the Execute method

This example shows how the KeyValuePair table is used to encrypt several files:

string[] filePaths = new string[] { "file-path-1", "file-path-2", ... };
objects[] certificates; // retrieved from a call to Get-SDSCertificate API
KeyValuePair<string, object>[] parameters = new KeyValuePair<string, object>[]
{
  new KeyValuePair<string, object>("-Path", filePaths),
  new KeyValuePair<string, object>("-Coworkers", certificates)
};
objects = api.Execute("Protect-SDSFile", parameters);

Each parameter has to be added to the KeyValuePair table of objects, with the key being the name of the cmdlet's parameter.

Running shipped code samples

Some sample projects are provided with a Visual Studio 2013 Solution.

Prerequisites:

The .NET Framework 4.5.2 Developer Pack is only needed for compiling the application using Stormshield Data Connector. Running an application that uses Stormshield Data Connector does not require it.

Each project included in this solution demonstrates the use of a particular API.

.NET API usage scenarios

NOTE
In the following examples, the error scenarios are not managed.

Handling user connection

Connecting a user

The Connect-SDUser API allows connecting a user to Stormshield Data Security.

using Stormshield.DataSecurity.Connector;
using Stormshield.DataSecurity.Connector.Kernel;
using (API api = new API())
{
  object[] objects = api.Execute("Connect-SDSUser <id> <password>");
  User connectedUser = objects[0] as User;
  Console.WriteLine("User '{0}' connected", connectedUser.Id);
}				

Checking the connection status

Get-SDSUser API makes it possible to find out the status of the current Stormshield Data Security session (connected or locked):

using Stormshield.DataSecurity.Connector;
using Stormshield.DataSecurity.Connector.Kernel;
using (API api = new API())
{
  object[] objects = api.Execute("Get-SDSUser");
  User connectedUser = objects[0] as User;
  if (connectedUser.Locked)
    Console.WriteLine("User is locked");
}			

Locking a session

The Lock-SDSUser API allows locking a current Stormshield Data Security session:

using Stormshield.DataSecurity.Connector;
using (API api = new API())
{
  // first ensure that a user is connected
  api.Execute("Lock-SDSUser");
}

Unlocking a session

The Unlock-SDSUser API allows unlocking a current Stormshield Data Security session:

using Stormshield.DataSecurity.Connector;
using Stormshield.DataSecurity.Connector.Kernel;
using (API api = new API())
{
  // first ensure that a user is connected and locked
  object[] objects = api.Execute("Unlock-SDSUser <password>");
  User connectedUser = objects[0] as User;
  Console.WriteLine("User '{0}' unlocked", connectedUser.Id);
}

Logging off a user

The Disconnect-SDUser API allows disconnecting the current user:

using Stormshield.DataSecurity.Connector;
using (API api = new API())
{
  api.Execute("Disconnect-SDSUser");
  // if no exception thrown, then the operation succeeded
}

Interacting with the trusted address book

A Stormshield Data Security user must be connected in order to perform the operations described below (see Handling user connection). An exception is raised if no user is connected.

Retrieving certificates

The Get-SDSCertificate API allows retrieving one or several certificates found in the directory.

using Stormshield.DataSecurity.Connector;
using Stormshield.DataSecurity.Connector.Common;
using (API api = new API())
{
  // first ensure that a user is connected
  object[] objects = api.Execute("Get-SDSCertificate -EmailAddress alicesmith@mycompany.com");
  X509Certificate certificate = objects[0] as X509Certificate;
}

NOTE
The retrieval of certificates by e-mail addresses relies only on the E-mail address field available in the certificate's General tab. E-mail addresses contained in the details of the certificate will not be used.

It is possible to retrieve several certificates at once, by using the PowerShell list syntax:

using Stormshield.DataSecurity.Connector;
using (API api = new API())
{
  // first ensure that a user is connected
  object[] objects = api.Execute("Get-SDSCertificate -EmailAddress alicesmith@mycompany.com,jodiefisher@mycompany.com,robertmiller@mycompany.com");
  X509Certificate aliceSmithCertificate = objects[0] as X509Certificate;
  X509Certificate jodieFisherCertificate = objects[1] as X509Certificate;
  X509Certificate robertMillerCertificate = objects[2] as X509Certificate;
}

If the UpdateStatus option was not selected during the command, the certificates will be retrieved without the status data. In order to get updates for this field, you will need to make an explicit request. The command will then take a longer time to send back certificates.

Exporting the contents of the address book

The contents of the trusted address book can be backed up in a file so that it can be restored later.

The Export-SDSAddressBook API allows exporting part of the contents of a user's address book.

The following example shows how to export in a P7B file certificates, their parent-child relationship as well as contacts and groups:

using Stormshield.DataSecurity.Connector;
using (API api = new API())
{
  // first ensure that a user is connected
  string p7bPath = @"path\to\file.p7b";
  object[] objects = api.Execute(string.Format("Export-SDSAddressBook -Path '{0}' -ExportAncestry -ExportContactsAndGroups", p7bPath));
  System.IO.FileInfo p7bFileInfo = objects[0] as System.IO.FileInfo;
}

The whole address book including the customization of certificates can be exported using the Backup-SDSAddressBook API.

The following example allows backing up the whole address book in a P7Z file:

using Stormshield.DataSecurity.Connector;
using (API api = new API())
{
  // first ensure that a user is connected 
  string p7zPath = @"path\to\file.p7z";
  oject[] objects = api.Execute(string.Format("Backup-SDSAddressBook -Path '{0}'", p7zPath));
  System.IO.FileInfo p7zFileInfo = objects[0] as System.IO.FileInfo;
}

The .p7z file allows backing up customized certificate data. However, this format is not compatible with versions of Stormshield Data Security older than version 9.1.

Importing the contents of the address book

The contents of the address book can be imported using the following code. The example shown here uses a P7Z file, but any format that is compatible with the Suite's address book will work.

using Stormshield.DataSecurity.Connector;
using (API api = new API())
{
  // first ensure that a user is connected 
  string p7zPath = @"path\to\file.p7z";
  api.Execute(string.Format("Import-SDSAddressBook -Path '{0}'", p7zPath));
}

Interacting with Stormshield Data File

Getting information about files

The Get-SDSFile API can be used to retrieve some information about a file, encrypted or not.

using Stormshield.DataSecurity.Connector;
using Stormshield.DataSecurity.Connector.File;
using (API api = new API())
{
  string sboxPath = @"path\to\file.sdsx";
  object[] objects = api.Execute(string.Format("Get-SDSFile '{0}'", sboxPath));
  SecureFile secureFile = objects[0] as SecureFile;
}

The SecureFile object contains the following information about the file:

  • Whether the file is encrypted
  • The list of recipients (email addresses, if file is encrypted). Information read from the header.

Multiple file paths can be passed to the Get-SDSFile API, as a PowerShell list:

object[] objects = api.Execute(string.Format("Get-SDSFile '{0}','{1}'", sboxPath1, sboxPath2));

In this case, the returned objects array contains two items, representing the information for each file passed.

No user needs to be connected to retrieve basic file information. To retrieve more details (regarding certificates), a user must be connected.

Encrypting a file

The Protect-SDSFile API can be used to encrypt a file with Stormshield Data File. A list of certificates must be retrieved from the user’s address book (see Retrieving certificates).

First of all, a Stormshield Data Security user must be connected to encrypt any file (see Handling user connection). An exception is raised if no user is connected.

The following example shows how to encrypt a file for several coworkers by providing their certificates:

using Stormshield.DataSecurity.Connector;
using Stormshield.DataSecurity.Connector.File;
using (API api = new API())
{
  // first ensure that a user is connected
  object[] certificates = api.Execute("Get-SDSCertificate -EmailAddress alicesmith@mycompany.com,jodiefisher@mycompany.com");
  KeyValuePair<string, object>[] parameters = new KeyValuePair<string, object>[]
  {
    new KeyValuePair<string, object>("-Path", @"path\to\file\to\be\encrypted"),
    new KeyValuePair<string, object>("-Coworkers", certificates)
  };
  object[] objects = api.Execute("Protect-SDSFile", parameters);
  SecureFile secureFile = objects[0] as SecureFile;
}

To protect multiple files at once:

string[] files = new string[] { @"some\path", @"some\other\path" };
KeyValuePair<string, object>[] parameters = new KeyValuePair<string, object>[]
{
  new KeyValuePair<string, object>("-Path", files),
  new KeyValuePair<string, object>("-Coworkers", objects)
};

Decrypting a file

The Unprotect-SDSFile API can be used to decrypt a file with Stormshield Data File.

A Stormshield Data Security user must be connected to decrypt any file (see Handling user connection). An exception is raised if no user is connected.

using Stormshield.DataSecurity.Connector;
using Stormshield.DataSecurity.Connector.File;
using (API api = new API())
{
  // first ensure that a user is connected
  string sboxPath = @"path\to\file.sdsx";
  object[] objects = api.Execute(string.Format("Unprotect-SDSFile '{0}'", filePath));
  SecureFile secureFile = objects[0] as SecureFile;
}

Adding coworkers for secure files

The Add-SDSFileCoworker API allows adding one or several coworkers to one or several files encrypted with Stormshield Data File.

A Stormshield Data Security user must be connected in order to add coworkers (see Handling user connection). An exception is raised if no user is connected.

using Stormshield.DataSecurity.Connector;
using Stormshield.DataSecurity.Connector.Common;
using Stormshield.DataSecurity.Connector.File;
using (API api = new API())
{
  // first ensure that a user is connected
  string sboxPath = @"path\to\file.sdsx";
  object[] certificates = api.Execute("Get-SDSCertificate -EmailAddress alicesmith@mycompany.com");
  KeyValuePair<string, object>[] parameters = new KeyValuePair<string, object>[] 
  {
    new KeyValuePair<string, object>("Path", sboxPath),
    new KeyValuePair<string, object>("Coworkers", certificates)
  };
  object[] objects = api.Execute("Add-SDSFileCoworker", parameters);
  SecureFile secureFile = objects[0] as SecureFile;
}			

Modifying the list of coworkers associated with secure files

The Set-SDSFileCoworker API allows replacing all coworkers associated with one or several files encrypted with Stormshield Data File by one or several other coworkers.

A Stormshield Data Security user must be connected in order to add coworkers (see Handling user connection). An exception is raised if no user is connected.

using Stormshield.DataSecurity.Connector;
using Stormshield.DataSecurity.Connector.Common;
using Stormshield.DataSecurity.Connector.File;  
using (API api = new API())
{
  // first ensure that a user is connected
  string sboxPath = @"path\to\file.sdsx";
  object[] certificates = api.Execute("Get-SDSCertificate -EmailAddress alicesmith@mycompany.com");
  KeyValuePair<string, object>[] parameters = new KeyValuePair<string, object>[] 
  {
    new KeyValuePair<string, object>("Path", sboxPath),
    new KeyValuePair<string, object>("Coworkers", certificates)
  };
  object[] objects = api.Execute("Set-SDSFileCoworker", parameters);
  SecureFile secureFile = objects[0] as SecureFile;
}

Deleting coworkers associated with secure files

The Remove-SDSFileCoworker API allows deleting a set of coworkers associated with one or several files encrypted with Stormshield Data File.

A Stormshield Data Security user must be connected in order to add coworkers (see Handling user connection). An exception is raised if no user is connected.

using Stormshield.DataSecurity.Connector;
using Stormshield.DataSecurity.Connector.Common;
using Stormshield.DataSecurity.Connector.File;
using (API api = new API())
{
  // first ensure that a user is connected
  string sboxPath = @"path\to\file.sdsx";
  object[] objects = api.Execute(string.Format("Remove-SDSFileCoworker '{0}' -EmailAddress alicesmith@mycompany.com", sboxPath));
  SecureFile secureFile = objects[0] as SecureFile;
}

Coworkers that are identified either by their e-mail addresses or their certificates can be deleted. If they are being deleted based on their e-mail addresses, an exception will be raised if the address of a coworker is associated with a missing certificate.

Interacting with Stormshield Virtual Disk

A Stormshield Data Security user must be connected in order to perform the operations described below (see Handling user connection). An exception is raised if no user is connected.

Creating a volume

The New-SDSDisk API allows creating an encrypted virtual disk volume.

The following example shows how to create a 42 MB volume:

using Stormshield.DataSecurity.Connector;
using Stormshield.DataSecurity.Connector.VirtualDisk;
using (API api = new API())
{
  // first ensure that a user is connected
  string vboxPath = @"path\to\file.vbox";
  object[] objects = api.Execute(string.Format("New-SDSDisk '{0}' -Size {1}", vboxPath, 50));
  Volume volume = objects[0] as Volume;
}

In this example, the volume created is neither formatted nor mounted.

Getting information about a volume

The Get-SDSDisk API allows retrieving information about a virtual disk volume.

using Stormshield.DataSecurity.Connector;
using Stormshield.DataSecurity.Connector.VirtualDisk;
using (API api = new API())
{
  // first ensure that a user is connected
  string vboxPath = @"path\to\file.vbox";
  object[] objects = api.Execute(string.Format("Get-SDSDisk '{0}'", vboxPath));
  Volume volume = obj as Volume;
}

Mounting a volume

The Mount-SDSDisk API allows mounting a virtual disk volume.

using Stormshield.DataSecurity.Connector;
using Stormshield.DataSecurity.Connector.VirtualDisk;
using (API api = new API())
{
  // first ensure that a user is connected
  string vboxPath = @"path\to\file.vbox";
  object[] objects = api.Execute(string.Format("Mount-SDSDisk '{0}'", vboxPath));
  Volume volume = obj as Volume;
}

Dismounting a volume

The Dismount-SDSDisk API allows dismounting a virtual disk volume.

using Stormshield.DataSecurity.Connector;
using Stormshield.DataSecurity.Connector.VirtualDisk;
using (API api = new API())
{
  // first ensure that a user is connected
  string vboxPath = @"path\to\file.vbox";
  object[] objects = api.Execute(string.Format("Dismount-SDSDisk '{0}'", vboxPath));
  Volume volume = obj as Volume;
}

Enabling the automatic mounting of a volume

The Enable-SDSDiskAutomaticMount API allows enabling the automatic mounting of a virtual disk volume.

using Stormshield.DataSecurity.Connector;
using Stormshield.DataSecurity.Connector.VirtualDisk;
using (API api = new API())
{
  // first ensure that a user is connected
  string vboxPath = @"path\to\file.vbox";
  object[] objects = api.Execute(string.Format("Enable-SDSDiskAutomaticMount '{0}'", vboxPath));
  Volume volume = obj as Volume;
}

Disabling the automatic mounting of a volume

The Disable-SDSDiskAutomaticMount API allows disabling the automatic mounting of a virtual disk volume.

using Stormshield.DataSecurity.Connector; 
using Stormshield.DataSecurity.Connector.VirtualDisk;
using (API api = new API())
{
  // first ensure that a user is connected
  string vboxPath = @"path\to\file.vbox";
  object[] objects = api.Execute(string.Format("Disable-SDSDiskAutomaticMount '{0}'", vboxPath));
  Volume volume = obj as Volume;
}

Interacting with Stormshield Data Team

Creating a rule on a folder

A Stormshield Data Security user must be connected in order to create a rule (see Handling user connection). An exception is raised if no user is connected.

The New-SDSTeamRule cmdlet allows creating a rule on one or several folders with Stormshield Data Team.

The following example shows how to create a rule for several coworkers:

using Stormshield.DataSecurity.Connector;
using Stormshield.DataSecurity.Connector.Team;
using (API api = new API())
{
  // first ensure that a user is connected
  string folderPath = @"path\to\folder";
  object[] certificates = api.Execute("Get-SDSCertificate -EmailAddress alicesmith@mycompany.com,jodiefisher@mycompany.com");
  KeyValuePair<string, object>[] parameters = new KeyValuePair<string, object>[] 
  {
    new KeyValuePair<string, object>("Path", folderPath),
    new KeyValuePair<string, object>("Coworkers", certificates)
  }; 
  object[] objects = api.Execute("New-SDSTeamRule", parameters);
  RuleInfoData ruleInfoData = objects[0] as RuleInfoData;
}

The connected user who creates the rule will automatically be entered as the owner (Owners parameter). If no users are connected, then the creation of the rule will fail.

Reading the rule associated with a folder

A Stormshield Data Security user must be connected in order to read a rule (see Handling user connection). An exception is raised if no user is connected.

The Get-SDSTeamRule cmdlet allows reading the rule associated with one or several folders with Stormshield Data Team.

using Stormshield.DataSecurity.Connector;
using Stormshield.DataSecurity.Connector.Team;
using (API api = new API())
{
  // first ensure that a user is connected
  string folderPath = @"path\to\folder";
  object[] objects = api.Execute(string.Format("Get-SDSTeamRule '{0}'", folderPath));
  RuleInfoData ruleInfoData = objects[0] as RuleInfoData;
}

Reading information from a file

The Get-SDSTeamFile cmdlet allows reading the Team information of one or several files with Stormshield Data Team.

using Stormshield.DataSecurity.Connector;
using Stormshield.DataSecurity.Connector.Team;
using (API api = new API())
{
  // first ensure that a user is connected
  string filePath = @"path\to\file";
  object[] objects = api.Execute(string.Format("Get-SDSTeamFile '{0}'", filePath));
  FileInfoData fileInfoData = objects[0] as FileInfoData;
}

Applying a rule on a folder

A Stormshield Data Security user must be connected in order to apply a rule (see Handling user connection). An exception is raised if no user is connected.

The Protect-SDSTeam cmdlet allows applying a rule to one or several folders with Stormshield Data Team.

This rule must be created beforehand.

using Stormshield.DataSecurity.Connector;
using Stormshield.DataSecurity.Connector.Team;
using (API api = new API())
{
  // first ensure that a user is connected
  string folderPath = @"path\to\folder";
  object[] objects = api.Execute(string.Format("Protect-SDSTeam '{0}', folderPath));
  foreach (object o in objects)
  {
    OperationStatus status = o as OperationStatus;
  }
}

Deleting a rule associated with a folder

A Stormshield Data Security user must be connected in order to delete a rule (see Handling user connection). An exception is raised if no user is connected.

The Remove-SDSTeamRule cmdlet allows deleting a rule associated with one or several folders with Stormshield Data Team.

This rule must be created beforehand.

using Stormshield.DataSecurity.Connector;
using (API api = new API())
{
  // first ensure that a user is connected
  string folderPath = @"path\to\folder";
  api.Execute(string.Format("Remove-SDSTeamRule '{0}'", folderPath));
}

Unsecuring a folder or file protected with a rule.

A Stormshield Data Security user must be connected to unsecure a folder or file (see Handling user connection). An exception is raised if no user is connected.

The Unprotect-SDSTeam cmdlet allows unsecuring one or several files or folders with Stormshield Data Team.

This rule must be deleted beforehand.

using Stormshield.DataSecurity.Connector;
using Stormshield.DataSecurity.Connector.Team;
using (API api = new API())
{
  // first ensure that a user is connected
  string folderPath = @"path\to\folder";
  object[] objects = api.Execute(string.Format("Unprotect-SDSTeam '{0}'", folderPath));
  foreach (object o in objects)
  {
    OperationStatus status = o as OperationStatus;
  }
}

Using .NET APIs from a C++ program

To run Stormshield Data Security using a .NET API from a program written in C or C++, you will need to set up a bridge between both technologies by writing code in managed C++ ("C++/CLI wrapper") that will allow calling the .NET code from C or C++ code.