Show Table of Contents

The following example explains how to integrate CipherSafe.NET into a typical Windows® application. It assumes that CipherSafe.NET is installed on developer's computer and deployment server.

Overview

Consider a web application that connects to a database server. This is how you would use CipherSafe.NET to protect the database connection string used by the application.

Back to top

Development

[Estimated time to complete: 2 minutes]

With the web application project open, do the following:

  1. Add a reference to the CipherSafe.NET library (CipherSafe.dll) to your ASP.NET project (by default, a copy of the DLL is installed in the C:\Program Files\Obviex\CipherSafe folder).
  2. In the application code, create an instance of the ApplicationProfile class.
  3. Once the ApplicationProfile object is created, use its indexer to retrieve the profile value holding the connection string.
Assuming that the profile value is named Connection String (SQL Server), this is what a C# version of the code would look like:

...
using Obviex.CipherSafe;
...
public class MyPage: System.Web.UI.Page
{
  ...
  private void DoSomethingInDatabase()
  {
    ...
    ApplicationProfile app = null;
    
    // Create an application profile object for the running Web application.
    // Category.WebApp indicates that we are expecting to retrieve a
    // profile of the immediate virtual directory, which is define as
    // an IIS application.
    try
    {
        app = ApplicationProfile.GetProfile(Category.WebApp);
    }
    catch(Exception ex)
    {
        // For troubleshooting purposes, you may want to print what
        // CipherSafe.NET considers the running application path by calling
        // the static ApplicationProfile.GetCurrentPath method
        // with the same application type attribute.

        string path = ApplicationProfile.GetCurrentPath(Category.WebApp);
         
        // Process exception and exit.
    }

    // Variable to hold connection string.
    string connString = null;

    // Use indexer to retrieve profile value.
    try
    {
        connString = app["Connection String (SQL Server)"];
    }
    catch(Exception ex)
    {
        // Process exception and exit.
    }
    ...
  }
}

Notice that the code retrieves a profile of the currently running WebApp without specifying the application path. At run time, CipherSafe.NET will dynamically determine the application path by querying the PhysicalApplicationPath property of the Request object belonging to the current HTTP context or the static HttpRuntime.AppDomainAppPath property (for other application types, CipherSafe.NET uses different methods of determining the path).

Back to top

Deployment

[Estimated time to complete: 5 minutes]

After deployment, use the CipherSafe.NET GUI tool to create a new application profile for your web application. CipherSafe.NET allows you to import and export profiles via a couple of clicks, or perform this task via an API, but here is how you would do this manually:

  1. In the CipherSafe.NET GUI tool, right-click the Web Applications node under Local System, and select the Add - Application Profile option from the context menu:

    Add application profile dialog

    Note: In this example, CpherSafe.NET stores encrypted application settings in the Windows® registry. To use configuration file instead, choose the Configuration File for the application type and set the application path to the .config file in the next step. You would also need to change the application code to retrieve the profile of a Category.ConfigFile application instead of Category.WebApp. The CipherSafe.NET User's Guide offers the step-by-step instructions explaining how to handle .config files and can help you avoid a couple of problems that may break the application functionality.

  2. In the New Application Profile dialog, specify the properties of your web application. This example assumes that the web application is defined directly under the root of the default web site, but it could exist at any location.

    When defining a new application profile, it's most important to correctly identify the application path. In this case, the application profile will be available to any page that is part of the default web site, but not to any pages belonging to other web applications, including the ones running under the same web site (you do understand the difference between IIS applications and virtual directories, right?):

    Add application profile

    You can give the application any name (name is only used for display purposes). Optionally, you can use the Administration tab to define users who will be allowed to administer this application profile in CipherSafe.NET (we'll use the global defaults here).

    If you want to restrict access to the application profile to a strong-named assembly, define the public-key token of this assembly in the corresponding field (in this example, it would be the assembly implementing your web site's code-behind logic).

    Click OK to create the application profile.

  3. Right-click the newly created application profile, and select the Add - Profile Value menu option from the context menu:

    Add profile value

  4. In the New Profile Value dialog, define the connection string, giving it the same name you used in the application code (Connection String (SQL Server) in out example).

    New profile value

    You can use the SQL arrow button on the right side of the edit field to test SQL connection.

    Click OK to save the value.
At this point, CipherSafe.NET will encrypt the value and store it in Windows® registry (or the application configuration file, if you chose the appropriate application type).

Back to top

Test

Test the application to make sure it can retrieve the decrypted value. Keep in mind that in this example, you must be testing the root of the default web site.

Back to top

Bonus

If an application profile value holds a connection string, you can test it directly from the main application window:

Test profile value

If you are using the Enterprise Edition of the product, you can export all or selected application profiles to a file and import them on another system:

Export application profiles

To use the export/import feature for multiple profiles, make sure that the application paths on both systems are identical.

Back to top