Share via

How to: Store Passwords and Other Sensitive Data

  • Article

 

Applies To: Windows Server 2012 Essentials

This topic describes how to implement the protected data store for an integrated hosted email adapter solution.

The protected data store is a database the hosted email framework uses to store sensitive data, such as administrator user names and passwords. All data in the data store is encrypted using the GUID of the add-in, and by an optional key known as the “optional entropy”.

  1. Add-in GUID– the GUID associated with an add-in. This uniquely identifies a given set of data with an adapter.

  2. Optional Entropy – a password or GUID used by the custom add-in.

The main purpose of the data store is to store the administrator username and password data across multiple sessions. For example, when implementing Activate, the general pattern is to retrieve the passed-in administrator user name and password, and then store that data in the protected data store. Then, the adapter uses the stored information during that session for subsequent calls by the administrator into the adapter.

The following table describes the members of the HostedEmailProtectedDataStore interface.

Member Description
HostedEmailProtectedDataStore The standard constructor.
Item Gets or sets the protected data associated with the specified key.
Destroy Destroys the protected data store.

To store sensitive data in the protected data store

  1. Create a new instance of the HostedEmailProtectedDataStore, using the ID of your adapter, and an optional entropy key.

    You can usually retrieve the GUID from the .add-in XML configuration file associated with the adapter. It is strongly recommended that you provide an optional entropy key, rather than pass in a null byte array.

    private const string addinId = "3983E9AC-B6D1-4A2A-881C-4B1CEFCA5266";  
static byte[] optionalEntropy = new byte[] { 80, 0, 64, 0, 115, 0, 115, 0, 119, 0, 48, 0, 114, 0, 100, 0 };  
static HostedEmailProtectedDataStore store = new HostedEmailProtectedDataStore(Guid.Parse(addinId), optionalEntropy);

  2. Use your instance to retrieves and set data from the store, as in the following code:

    private const string adminUserNameKey = "adminUserName";  
public static string AdminUserName  
        {  
            get  
            {  
                return store[adminUserNameKey];  
            }  
            set  
            {  
                store[adminUserNameKey] = value;  
            }  
        }

  3. Once you are finished with the data in the store, it is recommended that you clear the store using Destroy, as shown in the following code.

    public static void ClearAll()  
        {  
            if (store != null) store.Destroy();  
        }

Example

The following code shows how to use the protected data store to store the admin user name and password. This code is used as part of the extended SDK sample to save the admin user name and password in the adapter implementation. For more information, see Quickstart: Creating a Hosted Email Adapter.

namespace Contoso.HostedEmail  
{  
    internal static class CredentialManager  
    {  
        private const string adminUserNameKey = "adminUserName";  
        private const string adminPasswordKey = "adminPassword";  
        // This is copied from ContosoHostedEmail.addin  
        private const string addinId = "3983E9AC-B6D1-4A2A-881C-4B1CEFCA5266";  
        // The following line is the result of executing the code 'Encoding.Unicode.GetBytes("P@ssw0rd");'  
        static byte[] optionalEntropy = new byte[] { 80, 0, 64, 0, 115, 0, 115, 0, 119, 0, 48, 0, 114, 0, 100, 0 };  
        static HostedEmailProtectedDataStore store = new HostedEmailProtectedDataStore(Guid.Parse(addinId), optionalEntropy);  
  
        public static string AdminUserName  
        {  
            get  
            {  
                return store[adminUserNameKey];  
            }  
            set  
            {  
                store[adminUserNameKey] = value;  
            }  
        }  
  
        public static string AdminPassword  
        {  
            get  
            {  
                return store[adminPasswordKey];  
            }  
            set  
            {  
                store[adminPasswordKey] = value;  
            }  
        }  
  
        public static void ClearAll()  
        {  
            if (store != null) store.Destroy();  
        }  
    }  
}