Dovetail Carrier 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 DovetailCRMSettings.DatabaseConnectionString 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 Carrier.

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

Encrypt POP3 and IMAP Email Account Password

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

password="account_password"

would be replaced with something similar to this:

password="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 clientId, clientSecret, and tenantId settings. So, the configuration of:

<account 
  username="support@company.com" 
  clientId="xxxx665e-xxxx-432e-xxxx-4e09681xxxx" 
  clientSecret="xxxxF7~5r6Rxxxx.xxxx4_~wqAX743xxxx" 
  tenantId="xxxx9085-xxxx-47d1-xxxx-e558e03axxxx" 
/>

would be replaced with something similar to this:

<account 
  username="support@company.com" 
  clientId="FCENC:AQAAANCMnd8BFVoOtj1ZD6AQAAAACAAAAAAAQZgAAAAEAACSucqST6fgHr=" 
  clientSecret="FCENC:AAADO+8vBtWqp5pkJVrjzvSsqVc/ifnAQAAAQZgAAAAEAACSucqSTc8Tra=" 
  tenantId="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:	CarrierEmailCredentialsEntropy
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 CarrierEmailCredentialsEntropy 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 CarrierEmailCredentialsEntropy configuration item by utilizing the following script:

OBJECT TYPE="config_itm", NAME="CarrierEmailCredentialsEntropy"
  UNIQUE_FIELD = name
  FIELDS
    name = "CarrierEmailCredentialsEntropy";
    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="CarrierEmailCredentialsEntropy"

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="CarrierEmailCredentialsEntropy" REL="user_prefs2config_itm";
  END_RELATIONS
END_OBJECT NAME="user"