New Connect feature: HMAC signatures for added security

By Larry Kluger and Joey Peng

We’re pleased to announce a new feature for the Docusign Connect webhook system: HMAC signatures. The new feature is available May 22, 2019 for all developer sandbox (demo) accounts. It is scheduled to be enabled for all production accounts by May 31. The new feature will be available at no additional cost. HMAC provides an easier setup of Connect security compared to Mutual TLS and is much more secure than basic authentication.

What is an HMAC signature?

An HMAC (Hash-based Message Authentication Code) signature is a form of a digital signature. HMAC signatures start with a secret key that is shared between the sender (Docusign Connect) and the recipient (your application’s listener server).

The Connect HMAC signatures provide two cryptographically strong information security guarantees:

• Authentication of the sender. Assuming that you carefully secure the HMAC secret key(s), a verified HMAC signature guarantees that the message was sent by Docusign.

• Message integrity. Verification of the HMAC signature also guarantees the message’s integrity, confirming that the message was not changed by an unauthorized third party. The included hash can also be used to double-check content correctness.

Securing your application

To maintain the security of the HMAC signatures, you should change your secret keys periodically. The usual practice is once every 1-2 years.

Docusign strongly recommends that you consult with your organization’s Information Security department or a consultant before setting up a server on the Internet.

Documentation

Documentation of the HMAC feature is available on the Docusign Developer Center under Connect HMAC. Code examples are also being developed.

The cryptography of HMAC signatures

The Wikipedia article on HMAC Signatures is a good starting point for exploring the technology of HMAC signatures.

Let’s talk in person at Momentum!

Both Larry and Joey will be at the Docusign Momentum conference from June 11-13, 2019 in San Francisco. Come discuss Docusign Connect with us, and more. And as a developer, your registration fee is zero dollars. See you there!