Skip to navigation
Platform 101WebhooksMutual TLS

Troubleshooting mutual TLS

View as Markdown

The most common problem encountered when configuring Mutual TLS is caused by a missing or incomplete CertificateRequest message from your web server. To troubleshoot the problem, you will need a trace recording of the CertificateRequest message your server sent. The trace must be done by your IT department. Traces of the TLS handshake protocol are not available from Docusign. See Mutual TLS for more information.

Your web server can provide a trace, or an independent tool can be used. Wireshark is a popular free trace tool.

Issues to check while troubleshooting:

  • Mutual TLS will only be attempted if your web server sends a CertificateRequest message during the TLS handshake.
  • The CertificateRequest message must include the correct Distinguished Name (DN) of the root certificate for the Docusign certificate. The correct DN for the beginning of 2018 is VeriSign Class 3 Public Primary Certification Authority - G5.
  • A new root DN may be used in the Spring of 2018. Read the Docusign Release Notesfor more information on the certificate rollover process.
  • The CertificateRequest message also includes the certificate types and pairs of Hash Algorithm/Signature Algorithm names that the server will accept from the client. The Docusign client certificates use the SHA256 hash algorithm, so it must be included in the list of acceptable hash algorithms sent by the server.

Note: Enabling Docusign Connect for Mutual TLS does not turn on Mutual TLS. The setting only enables Mutual TLS. If your web server does not request Mutual TLS or does so incorrectly, Mutual TLS will fail, but the HTTPS connection and the notification message POST from Docusign can still proceed (depending on the server’s settings). Also, Docusign Connect cannot require Mutual TLS for a connection. Your web server can reject connection requests that don’t include Mutual TLS. Requiring Mutual TLS is a server setting