Learn the pitfalls of updating from SHA1 to SHA2 before it’s too late!

By Ryan Lee
Posted in Infrastructure
On January 22, 2015

What the SHA is going on with my Citrix Access?!?

The news is that SHA1, a very popular hashing function, is on the way out. Strictly speaking, this development is not new. The first signs of weaknesses in SHA1 appeared (almost) ten years ago. In 2012, some calculations showed how breaking SHA1 is becoming feasible for those who can afford it. In November 2013, Microsoft announced that they wouldn't be accepting SHA1 certificates after 2016. So what does this mean to you and your Citrix Environment? To understand how this might affect your environment, let us first discuss what a certificate and its chain are at a high level and how that chain works to provide secure access into your environment.

An SSL Certificate is a small data file that digitally binds a cryptographic key to an organization’s details. When installed on a web server, it activates the padlock and the https protocol (over port 443), and allows secure connections from a web server to a browser. SSL Certificates need to be issued from a trusted Certificate Authority's Root Certificate, which must be present on the end user's machine in order for the Certificate to be trusted. If it is not trusted, the browser will present untrusted error messages to the end user. In the case of Citrix, users may receive the following error message(s) when attempting to launch a published resource:

Error: "Connection Error. Citrix Receiver could not establish connection with remote host"


Cannot connect to the Citrix XenApp server. SSL Error 61: You have not chosen to trust "", the issuer of the server's security certificate.

Intermediate certificates are used as a stand-in for your CA’s root certificate. The intermediate certificate is used as a proxy between your organization's publicly issued SSL certificate and the public CA’s root certificate to increase security. This, in effect establishes a certificate chain, ensuring the public CA’s keys are absolutely inaccessible. If you don't install the intermediate certificate(s) with your issued SSL certificate, the trusted chain might not be established, thereby throwing the dreaded SSL error message mentioned above.


Everything in my environment was working fine until yesterday - what happened?!? All issued SSL certificates come with an expiration date requiring renewal...and, of course, payment. Whether you are purchasing a new certificate or renewing an existing certificate, your certificate will be issued with the new SHA256 security hash algorithm. At first glance this may not seem like an issue to you, but there are some caveats that you should be aware of that will help you plan and transition to the new certificate format.

Certificates using SHA256 will require the installation of a new SHA256 Intermediate certificate. The intermediates are issued under a SHA1 root. This does not affect browser performance or security, as the end entity certificate is signed using a SHA256 intermediate. The problem you may run into is that many older clients do not support SHA256.

Windows XP / Server 2003

Microsoft did not start supporting SHA256 until Windows XP service pack 3. Windows Server 2003 does not support it natively; however, you may apply the following Microsoft patch to address this. If you are running Web Interface on Server 2003 in conjunction with Citrix Secure Gateway, Citrix Access Gateway, or Citrix NetScaler Gateway, then you will most likely need this patch applied before moving to the new certificate format.


Windows Vista and Above

Okay, you made it to a platform that has the new certificate format baked in – hurray! Well, hold the phone. Even though your operating system may officially support the new format, there are a number of things that may still cause SSL errors. Even though you have done your due diligence as an admin and completed the certificate chain from your web server (or NetScaler for that matter), the intermediate certificate must still be updated on the client’s workstation. This is needed because the current intermediate certificates are all SHA1 which of course will not complete your new SHA256 chain. This typically happens seamlessly to the end user provided they have the appropriate permissions. If the workstation is locked down (centrally managed via GPO), there is a good chance the intermediate certificate will not be installed causing a kink in your certificate chain. To get around this, you are now on the hook to deliver the intermediate certificate to all of your workstations. Update your certificate before that, and you have now introduced a production outage! Its crunch time to get your workstations back in order, here are some of your options:

  • Leverage Group Policy to deploy your intermediate certificate(s)
  • Leverage a third-party desktop management tool to deploy your intermediate certificate(s)
  • Leverage custom scripting and certutil.exe to deploy your intermediate certificate(s)
  • And the tried and true method – old fashioned manual install via sneaker-net!


Unfortunately, Mac users are in the same boat, but with no captain to guide your ship. That means your only real option to stay afloat is to manually install the new intermediate certificate AND trust it via Macintosh’s keychain utility.


Okay, you have the intermediate certificate installed, but you are still getting that stupid SSL error message. Now what? Well, just as web browsers and operating systems must be coded to support the new SHA256 format, so does the Citrix Receiver client. The following versions are currently supported:

You may also check the Receiver Feature Matrix for additional clients that I have not listed such as Linux, Mobile, and HTML5 devices.

As with any Receiver installation, it is best to perform a clean uninstall of the pre-existing Citrix client before installing a SHA256 compatible version. It is also important to note that updating to newer versions may have adverse effects on your environment, so testing must be done to ensure a smooth migration. Now that you know the pitfalls, you can see that what appears to be a straightforward process, most likely requires research and planning to ensure your systems continue to function properly and seamlessly to your end users during this migration.

Ryan Lee

Ryan Lee

Ryan is a Technical Architect working out of our Connecticut site responsible for architecture and design of application, desktop, and server solutions. Ryan holds multiple technical certifications and has worked as an IT analyst, engineer, and consultant for companies in a variety of industries.