General Components Encryption Service Getting Started

Getting Started

This documents explains the usage of Xafari Encryption Service. An assembly of Xafari.Framework.16.1.40XX is used as an example. The Tools folder of the framework contains the EncryptionServer folder (see the image below).

encryption_service_1

First, the web application is deployed. In this example, it is done through IIS, as follows:

launch the IIS manager (for example, by pressing Win+R on the keyboard and entering the inetmgr value into the only available field of the dialog box),

add a new application to the default list via its context menu,

name the application xafari.encryption.service (or use any other meaningful name) and specify the physical path to its files; it is also possible to customize the applications' pool or other parameters during this step.

This service always requires some way of authentication to be added. Currently, only Windows authentication is available; the implementation of a standard one is coming in the future versions.

Now we have a web service available at "http://localhost/xafari.encryption.service/" (see the image below).

encryption_service_2

Before using Xafari Encryption Service, some more things should be done as described in the following sections of this document:

setting the data access permissions,
specifying the connection string,
making the target application use the service.

Setting the data access permissions

To set the data access permissions, the executing application should be signed with a public key needed to process the encrypted data. In this sample, we suppose that the application has a digital signature and its publicKeyToken equals c9ae4f092cc930e6. The application is used by SomeUser1.

First, the UserKeys.ini file should be created. Then, the path to this file should be specified in the Web.config file of the service. See the usage of the UserPermissionsFilePath parameter below:

<add key="UserPermissionsFilePath" value="Place path here" />

Finally, add a json string below into the UserKeys.ini file (using Notepad, for instance).

{"UserName":"SomeUser1","Key":"c9ae4f092cc930e6"}

Now, SomeUser1 is allowed to get data from the service if accessing from the application which publicKeyToken is c9ae4f092cc930e6.

The keys should be separated with commas, as follows:

{"UserName":"SomeUser1","Key":"c9ae4f092cc930e6"}
{"UserName":"SomeUser2","Key":"c9ae4f092cc930e6"}
{"UserName":"SomeUser3","Key":"c9ae4f092cc930e6"}

In case there is a domain in the user name, use the double backslash, e.g. DOMAIN\\SomeUser1.

Specifying the connection string

Create the ConnectionString.ini file and add set the desired connection string there, as in the script below.

Integrated Security=SSPI;Pooling=false;Data Source=(localdb)\v11.0;Initial Catalog=webServiceDb;

The path to the file should also be set in the Web.config file. Specify the value of the ConnectionStringFilePath parameter, as follows:

<add key="ConnectionStringFilePath" value="Place path here" />

Making the target application use the service

The next step is to make the target application use the service. A new XAF application is created here for demonstration purposes.

To use the connection string received from the web service, one of the following options can be chosen (both variants are described in details later in the text):

Via Xafari AppModule by means of the UseEncryptedConnectionString checkbox.
By customizing the CreateCustomObjectSpaceProvider event in the app.

Moreover, the XafariEncryptionServiceUrl key should be added to the configuration file where the address of the service is stored, as follows:

This key should always be added in case Xafari AppModule is utilized for the setup. Otherwise, customizing through the CreateCustomObjectSpaceProvider event, it is possible to specify the URL directly when initializing the connection.

Then, a link to the Xafari.dll library should be added either to the platform-agnostic module or to AppModule, depending on the chosen scenario (the figure below shows adding to the platform-agnostic in case of using the CreateCustomObjectSpaceProvider event).

encryption_service_3

Using Xafari AppModule and its UseEncryptedConnectionString ckeckbox

In this case, the setup is done via the application's module. To find the info on how to add and configure the AppModule, refer to this document.

After adding the AppModule, modify its constructor by setting the value of the UseEncryptedConnectionString property to true (see the code sample below):

public sealed partial class SomeApplicationAppModuleAppModule : AppModuleBase
{
  //...
  public SomeApplicationAppModuleAppModule()
  {
    InitializeComponent();
    this.UseEncryptedConnectionString = true;
  }
  //...
}

Public Partial NotInheritable Class SomeApplicationAppModuleAppModule
  Inherits AppModuleBase
  '...
  Public Sub New()
    InitializeComponent()
    Me.UseEncryptedConnectionString = True
  End Sub
  '...
End Class

From now, the connection string is set to be received from the web-service.

To specify any additional parameters of the connection, override the CreateObjectSpaceProviders method:

public sealed partial class SomeApplicationAppModuleAppModule : AppModuleBase
{
  public SomeApplicationAppModuleAppModule()
  {
    InitializeComponent();
    this.UseEncryptedConnectionString = true;
  }
  protected override void CreateObjectSpaceProviders(CreateCustomObjectSpaceProviderEventArgs args)
  {
    //...
    base.CreateObjectSpaceProviders(args);
  }
}

Public Partial NotInheritable Class SomeApplicationAppModuleAppModule
  Inherits AppModuleBase
  Public Sub New()
    InitializeComponent()
    Me.UseEncryptedConnectionString = True
  End Sub
  Protected Overrides Sub CreateObjectSpaceProviders(ByVal args As CreateCustomObjectSpaceProviderEventArgs)
    '...
    MyBase.CreateObjectSpaceProviders(args)
  End Sub
End Class

Customizing the application via the CreateCustomObjectSpaceProvider event

namespace SomeApplication.Module
{
  public sealed partial class SomeApplicationModule : ModuleBase
  {
    //...
    public override void Setup(XafApplication application)
    {
      base.Setup(application);
      application.CreateCustomObjectSpaceProvider += ApplicationOnCreateCustomObjectSpaceProvider;
    }
    private void ApplicationOnCreateCustomObjectSpaceProvider(object sender, CreateCustomObjectSpaceProviderEventArgs e)
    {//here ObjectSpaceProvider is initialized and gets м строки подключения из веб-сервиса xafari.encryption.service
    }
  }
}

Namespace SomeApplication.Module
  Public Partial NotInheritable Class SomeApplicationModule
    Inherits ModuleBase
    '...
    Public Overrides Sub Setup(ByVal application As XafApplication)
      MyBase.Setup(application)
      application.CreateCustomObjectSpaceProvider += ApplicationOnCreateCustomObjectSpaceProvider
    End Sub
    Private Sub ApplicationOnCreateCustomObjectSpaceProvider(ByVal sender As Object, ByVal e As CreateCustomObjectSpaceProviderEventArgs)
      'here ObjectSpaceProvider is initialized and gets м строки подключения из веб-сервиса xafari.encryption.service
    End Sub
  End Class
End Namespace

To get the connection string from the web service, the XafariEncrypter class provides the GetConnectionString() method:

private void ApplicationOnCreateCustomObjectSpaceProvider(object sender, CreateCustomObjectSpaceProviderEventArgs e)
{
  //initializing XPObjectSpaceProvider:
  //url can be sent directly:
  e.ObjectSpaceProvider = new XPObjectSpaceProvider(XafariEncrypter.GetConnectionString("http://localhost/xafari.encryption.service/"));
  //or, for example, as follows (initializing SecuredObjectSpaceProvider),
  //url is read from the configuration file:
  e.ObjectSpaceProvider = new SecuredObjectSpaceProvider((SecurityStrategy)Application.Security, XafariEncrypter.GetConnectionString(System.Configuration.ConfigurationManager.AppSettings["XafariEncryptionServiceUrl"]), e.Connection);
}

Private Sub ApplicationOnCreateCustomObjectSpaceProvider(ByVal sender As Object, ByVal e As CreateCustomObjectSpaceProviderEventArgs)
  'initializing XPObjectSpaceProvider:
  'url can be sent directly:
  e.ObjectSpaceProvider = New XPObjectSpaceProvider(XafariEncrypter.GetConnectionString("http://localhost/xafari.encryption.service/"))
  'or, for example, as follows (initializing SecuredObjectSpaceProvider),
  'url is read from the configuration file:
  e.ObjectSpaceProvider = New SecuredObjectSpaceProvider(CType(Application.Security, SecurityStrategy), XafariEncrypter.GetConnectionString(System.Configuration.ConfigurationManager.AppSettings("XafariEncryptionServiceUrl")), e.Connection)
End Sub