EXM and encryption keys

If you had the chance to work with Sitecore Email Experience Manager (aka EXM), you probably had to configured the connection string keys EXM.CryptographicKey and EXM.AuthenticationKey. But do you know how important are they?

EXM.CryptographicKey and EXM.AuthenticationKey are used to encrypt and decrypt the query string in the e-mail campaigns sent to your customers. They are configured in the ConnectionString.config file. Here’s one example.

<add name="EXM.CryptographicKey" connectionString=
"E040C938FC9E4EBC3E93330B0F7837F284207B8180DB64CB5B6ABEB1AFBF6F5B" />
<add name="EXM.AuthenticationKey" connectionString=
"9D80B4E56AEE694058567BD89C936FB88F2DB1272A4E88F419B6501919E0BB25" />

When EXM dipatches the emails campaigns, it encrypts every link in the message body. Below you find an example of an encrypted link in a call to action button:

https:// example.com/sitecore%20modules/Web/EXM/Redi...

Important: test e-mails don’t encrypt the links.

Notice that the query string parameter ec_eq contains a large encrypted text. That encrypted text contains a query string with the following key-pair values:

  • ex_id_s: contact identifier source. Default is “Alias”.
  • ex_id_i: contact identifier. e.g. “4353a6e5-347e-4529-af00-bcf29fc019cd”.
  • ec_message_id: campaign message item ID in Sitecore.
  • ec_lang: language. e.g. “en-GB”
  • ec_tvi: test value index.
  • ec_emailid: email history entry id.
  • ec_url: target URL in a redirect request.

All these query string parameters are mapped in the \App_Config\Sitecore\EmailExperience\Sitecore.EmailExperience.Core.config file.

These parameters are what EXM uses to track back Open rates, Clicks, Bounces and so on at a customer level.

Recently, we had a client that during a migration inadvertently decided to change these keys when configuring a DDS role. Guess what happened after a week or two? Customers started complaining that all links in the e-mails sent prior to the migration stopped working. They were getting a 404 error page whenever they clicked a link. Also, the Open rates, Clicks, Bounces from those e-mails were not being updated.

At first, we had two options.

  • Option 1: to give up on collecting data from campaigns that were sent prior to the migration.
  • Option 2: revert back the encryption and authentication keys in the ConnectionStrings.config file and give up on collection data from the new campaigns created during the weeks following the migration.

None of these options were the best since we are talking about the loss of important data for the client.

After some digging in the code, I could figure at which moment the query string is decrypted and was able to provide a solution that would make it work both the previous and the new encryption and authentication keys.

You can find the complete code here, but I give a brief explanation further.

Basically, I replaced the processor Sitecore.Modules.EmailCampaign.Core.Pipelines.TransformQueryString.DecryptQueryString, Sitecore.EmailCampaign with a new one that tries decryption with the new authentication and encryption keys and (if it fails) it proceeds with decryption using the old keys.

In the ConnectionStrings.config file I have both the new and the old encryption and authentication keys.

That’s all.

comments powered by Disqus