Dovetail RuleManager Documentation

How To Use Encrypted Credentials

Dovetail Software SDK comes with First Choice Configuration Protector Utility which can be used to encrypt database and email account access credentials. To use this tool, search for FCConfigurationProtector.exe application in the SDK installation folder, usually C:\Program Files\Dovetail Software\fcSDK. Please read the documentation before use.

Encrypted credential strings are to be stored in configuration files in lieu of the plain-text ones. The encrypted strings contain "FCENC:" prefix. Only such strings will be subject of decryption attempts when the relevant credential is to be used by the application.

The advantage of encrypting the credentials is that the encrypted keys can only be decrypted on the same machine from which they were encrypted on. For example, if you want to use an encrypted key on your application server, then you should run the Configuration Protector Utility on your application server. In effect, even if the encrypted key is stolen it is useless on any other machine.

Encrypt Database Connection String

First Choice Configuration Protector Utility can be used to encrypt database connection string which goes to fchoice.connectionstring setting. So, the value of:

Data Source=server_name; Initial Catalog=database_name; User Id=user_id; Password=the_password;

would be replaced with something similar to this:

FCENC:AQAAANCMnd8BFVoOtj1ZD6AQAAAACAAAAAAAQZgAAAAEAACSucqSTAvMgmxHcKcX4giU2dAAAAAAOgAAAAAIAACAAAADO+8vBtWqp5pkJVrjzvSsqVc/ifnGdhCYoTXobTy9pwSY/UEC5uyYXm3DsW8N+YUTtGEfAbpf/xIFpZtfZh0oMknRAW8+QxNo=

Note that you cannot use entropy string to encrypt the database connection string for use with Dovetail Rulemanager.

This is not a new functionality added to this release of Dovetail Rulemanager but we remind you of it being available.

Encrypt SMTP Email Account Password

First Choice Configuration Protector Utility can be used to encrypt email account password string which goes to EmailServiceConfig.Password setting. So, the value of:

<add key="EmailServiceConfig.Password" value="account_password" />

would be replaced with something similar to this:

<add key="EmailServiceConfig.Password" value="FCENC:AQAAANCMnd8BFVoOtj1ZD6AQAAAACAAAAAAAQZgAAAAEAACSucqSTAACAAAAD3DZh0oMknRAW8+QxNo=" />

Encrypt MsGraph Email Account Credentials

First Choice Configuration Protector Utility can be used to encrypt MsGraph email account credential strings which go to MsGraphClientId, MsGraphClientSecret, and MsGraphTenantId settings. So, the configuration of:

<add key="EmailServiceConfig.MsGraphUserName" value="support@company.com" />
<add key="EmailServiceConfig.MsGraphClientId" value="xxxx665e-xxxx-432e-xxxx-4e09681xxxx" />
<add key="EmailServiceConfig.MsGraphClientSecret" value="xxxxF7~5r6Rxxxx.xxxx4_~wqAX743xxxx" />
<add key="EmailServiceConfig.MsGraphTenantId" value="xxxx9085-xxxx-47d1-xxxx-e558e03axxxx" />

would be replaced with something similar to this:

<add key="EmailServiceConfig.MsGraphUserName" value="support@company.com" />
<add key="EmailServiceConfig.MsGraphClientId" value="FCENC:AQAAANCMnd8BFVoOtj1ZD6AQAAAACAAAAAAAQZgAAAAEAACSucqST6fgHr=" />
<add key="EmailServiceConfig.MsGraphClientSecret" value="FCENC:AAADO+8vBtWqp5pkJVrjzvSsqVc/ifnAQAAAQZgAAAAEAACSucqSTc8Tra=" />
<add key="EmailServiceConfig.MsGraphTenantId" value="FCENC:AADO+8vBtWqp5pkJVrvMgmxHcAAAAAAQZgAAAAEAACSucY7sd0kT=" />

Important: You can use entropy string to encrypt email account credential strings. This entropy string must then be saved in a dedicated Configuration Item having the following properties, when created in Agent:

Name:	RuleMngrEmailCredentialsEntropy
Scope:	User (if Integrated Security is not to be used) or any (if Integrated Security is to be used)
Value Type:	String
String Value:	Entropy_String_Of_Your_Choice_Goes_Here
Integer Value:	0
Float Value:	0
User:	User_Login_Name_From_Connection_String_Goes_Here (if scope is 'user', not applicable otherwise)

Note that all credential strings must be encrypted with the same entropy string or without entropy string, consistently. You cannot encrypt one with entropy string and another one without entropy string. If RuleMngrEmailCredentialsEntropy configuration item is found and its string value is not empty it will be used for all decryption attempts. Also note that you don't have to encrypt all credentials - if "FCENC:" prefix is not present, the string will be used as provided.

You could use Dovetail Archive Manager to import the RuleMngrEmailCredentialsEntropy configuration item by utilizing the following script:

OBJECT TYPE="config_itm", NAME="RuleMngrEmailCredentialsEntropy"
  UNIQUE_FIELD = name
  FIELDS
    name = "RuleMngrEmailCredentialsEntropy";
    description = "Entropy string. Used to decrypt encrypted email credentials.";
    value_type = 0;
    i_value = 0;
    str_value = "Entropy_String_Of_Your_Choice_Goes_Here";
    scope = 4;
  END_FIELDS
  RELATIONS
    TO_NAME="user" REL="config_itm2user";
  END_RELATIONS
END_OBJECT NAME="RuleMngrEmailCredentialsEntropy"

OBJECT TYPE="user", NAME="user"
  UNIQUE_FIELD = login_name
  FIELDS
    login_name = "User_Login_Name_From_Connection_String_Goes_Here";
  END_FIELDS
  RELATIONS
    TO_NAME="RuleMngrEmailCredentialsEntropy" REL="user_prefs2config_itm";
  END_RELATIONS
END_OBJECT NAME="user"