Equisys technical notes

Technical guidance, explanations and fixes for our products

HOWTO: Enable TLS1.2 with Zetadocs for NAV

Print

ZTN4513

This Zetadocs technical note applies to:

  • Zetadocs for NAV 10.0
  • Systems without SSL2.0 in favour to a more recent protocol, like TLS1.0, TLS1.1, TLS1.2

Summary

This technote describes how to enable Zetadocs to use the machine encryption protocol, typically TLS1.2, by adding a windows registry key.

It can also be applied when observing the following error in the ZetadocsArchiveApi logs:
 

The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel. ---> System.Security.Authentication.AuthenticationException: The remote certificate is invalid according to the validation procedure.

More information

WARNING: Using Registry Editor incorrectly can cause serious problems that may require you to reinstall your operating system. Equisys cannot guarantee that problems resulting from the incorrect use of Registry Editor can be solved.

To enable Zetadocs to use the machine encryption protocol, a registry key must be added to the server running the NAV service. The steps to follow are:

  • Open the Registry key editor (regedit in the windows search)
  • Ensure the protocol to be used is enabled for both Client and Server
    • Example
      • [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client]
      • [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server]
    • In case the security protocol TLS 1.2 is not present on the NAV server, please follow the manual steps below to enable it:
      • 1) In the Windows start menu, type regedit and open it.

      • 2) Back up your current registry before making any changes. This can be done by clicking File, then Export, and then save the backup at a safe location.

      • 3) Browse to the following path: Computer\HKEY_LOCAL_MACHINE\SYSTEM\ CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols.

      • 4) Right-click on the ‘Protocols’ key and choose New > Key.

      • 5) Name the new key TLS 1.2.

      • 6) Right-click on the ‘TLS 1.2’ key and add two new keys named Client and Server.

      • 7) Select the Client key, right-click on the right side, and select New -> DWORD (32-bit) Value.

      • 8) Name the DWORD DisabledByDefault, right-click on it, and select Modify. The base should be set to Hexadecimal and the value set to 0.

      • 9) Create a new DWORD with the name Enabled. The base should be set to Hexadecimal and the value set to 1.

      • 10) Repeat the process for the Server key, creating the same DWORDS with the same values.

    • Once TLS 1.2 is enabled, please add both registry keys below and restart the operating system.

·         The key to add is [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319\SystemDefaultTlsVersions].

    • This key is a DWORD of value 1.
  • On x64 versions of windows: add the key [HKEY_LOCAL_MACHINE\SOFTWARE\ Wow6432Node\Microsoft\.NETFramework\v4.0.30319\SystemDefaultTlsVersions]
    • This key is a DWORD of value 1.
  • Restart the operating system.

Adding this registry key to 1 allows the operating system to choose the protocol version for applications targeting the .NET framework 4.6.1 such as Zetadocs for NAV 10.0 and later.

How to Test

To ensure this technote has been applied correctly and the system is working, please disable (both Client and server) the protocols SSL2.0 enable TLS1.2 (or, if required, another version of TLS or SSL1.0).

Restart the NAV service to test the protocols working.

The steps to follow are:

  • Open RegEdit 
  • Go to this path – HKEY_LOCAL_MACHINE \SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols
  • If you see that you have SSL 2.0 or SSL 1.0 Hybrid mode – i.e. enabled for client but not for the server. You will need to have it consistent by enabling for both client and server. Once that is done, check to see if the issue persists.
  • Alternatively, you can disable for both which will validate the Solution 1 explained above that it has been applied correctly.

Note: If this test fails then you will need to migrate the NAV Service Tier to a newer version of Windows, please see this technote for details:
HOWTO: Move NAV Service Tier to a TLS1.2 compliant Windows Server with Zetadocs and SharePoint Online (equisys.com)

References

For further information, please refer to the Transport Layer Security (TLS) best practices with the .NET Framework by Microsoft.

Last updated: 13th May 2021 (CR/JC/NU/LM) 

Keywords: TLS, encryption, Zetadocs, Zetadocs for NAV

Equisys Logo, Document Management and Expense Management for Business Central
 

Replaced by script