How To Topic

Authenticating to HotDocs Cloud Services

All calls to the Direct and Embedded Cloud Services APIs must be authenticated. This is to verify your application is authorized to use Cloud Services.

Hash-based Authentication Code (HMAC)

One of the security measures to guard against unauthorized or fraudulent access to the web service is an HMAC. This is essentially a way to digitally sign a request. HotDocs Cloud Services uses the HMAC to verify that the data received matches the data sent in the original request.

When accessing HotDocs Cloud Services using a supplied client library, the HMAC is calculated and supplied to Cloud Services automatically (based on your subscriber ID, your signing key and the parameter values you provide to each web service call). If a client library is not available to calculate the HMAC automatically, it must be calculated manually.

Calculating the HMAC Manually

To calculate the HMAC

1. Get a UTF-8 encoded string representation for each of the parameters that is to be included in the HMAC. Only certain parameters are included in the HMAC calculation, and the order of the parameters is different than the order in which they are found in the web methods. See the following for the parameters used for HMAC calculation in each Cloud Services method:
   • Upload Package
   • GetInterview
   • AssembleDocument
   • GetComponentInfo
   • GetInterviewFile

2. Concatenate each parameter into a single string, separated by a line break (\n).
3. Use a signing key to compute a hash for the combined string.
4. Base-64 encode the hash.

Examples for Cloud Services Requests (C#)

For each call to Cloud Services, there is a full Visual Studio project to demonstrate how to create a request, calculate the HMAC, send the request, and handle the response from Cloud Services.

Example Code

For example methods, see the C# example code below.

For full working examples, see the HotDocs Integration Examples folder in hotdocs-samples. The following projects for examples of using Cloud Services, including HMAC calculation:

• CloudServicesAPIExample1Upload – upload a HotDocs Template Package file to Cloud Services.
• CloudServicesAPIExample2DocumentAssembly – use Cloud Services to assemble a document.

Walkthrough

For a walkthrough the example code above, see the HotDocs Integrations documentation:

• Cloud Services Example 1: Upload a Template
• Cloud Services Example 2: Assemble a Document

Calculate the HMAC Example Code (C#)

public static string CalculateHMAC(string signingKey, params object[] paramList)

{

byte[] key = Encoding.UTF8.GetBytes(signingKey);

string stringToSign = CanonicalizeParameters(paramList);

byte[] bytesToSign = Encoding.UTF8.GetBytes(stringToSign);

byte[] signature;

using (var hmac = new System.Security.Cryptography.HMACSHA1(key))

{

signature = hmac.ComputeHash(bytesToSign);

}

return Convert.ToBase64String(signature);

}

 

public static string CanonicalizeParameters(params object[] paramList)

{

if (paramList == null)

{

throw new ArgumentNullException();

}

var strings = paramList.Select(param =>

{

if (param is string || param is int || param is Enum || param is bool)

{

return param.ToString();

}

if (param is DateTime)

{

DateTime utcTime = ((DateTime)param).ToUniversalTime();

return utcTime.ToString("yyyy-MM-ddTHH:mm:ssZ");

}

if (param is Dictionary<string, string>)

{

var sorted = ((Dictionary<string, string>)param).OrderBy(kv => kv.Key);

var stringified = sorted.Select(kv => kv.Key + "=" + kv.Value).ToArray();

return string.Join("\n", stringified);

}

return "";

            });

return string.Join("\n", strings.ToArray());

}