SSL Certificate Pinning with NetScaler

11 August 2016 | By David Baird

The Public Key Pinning Extension for HTTP (HPKP) is a web security feature that tells a web client to associate a specific cryptographic public key with a certain web server to prevent Man-in-the-middle (MITM) attacks with forged certificates. Defined by RFC7469, HPKP is currently supported by FireFox (versions 35 and above), Chrome (versions 38 and above), and to a limited degree by Opera (version 38 and above), with Microsoft noting that the inclusion of the standard in Internet Explorer and Edge is under consideration.

The underlying mechanism of HPKP is the insertion of an HTTP header in the website response that includes the SHA-256 based hash of a minimum of a Primary pin and a Backup pin, along with a time-out interval for which the response should be cached, an option for whether or not sub domains should also be treated similarly, and an option for where violations should be reported.

An example would be as follows:

Public-Key-Pins:

pin-sha256="hgscoxTS2wkWNHh9QXdEz8c+4Enl7HZxj+lXHVLiYn4=";

pin-sha256="bef6IF2UF6jNEwA2pNmP7kpgT6NFSdt7Tqf5HzaIGWI=";

max-age=100800; includeSubDomains;

report-uri="https://website.xyz/hpkp/violation.php"

HTTP headers of this type are readily configured within Citrix NetScaler using a Rewrite Action and then binding the corresponding Rewrite Policy to the required virtual server, using a Rewrite Response policy mapping.

In order to generate the SHA-256 hashes, the OpenSSL component within NetScaler can used, with the simplest method involving connecting to the NetScaler using your preferred SSH client and then accessing the shell, before running the OpenSSL commands:

openssl x509 -in /nsconfig/ssl/.pem -pubkey -noout | openssl rsa -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64

In this example using a PEM encoded certificate, the output of the initial OpenSSL command is piped from one OpenSSL instance to another, with the end result being the Base 64 encoded SHA-256 hash. This hash should then be copied for use in the Rewrite Actions, and any additional hashes calculated for the remaining pins to be used.

Note: It is also possible to construct the SHA-256 hash using the public key file or the original Certificate Signing Request (CSR), although for many, using the standard PEM encoded certificate is generally a simpler option.

Whilst the standard allows you to have as many hashed pins as you want within the HTTP header, only one of these must be from your Trust Chain. One of these must also be from outside the Trust Chain, thereby forcing the inclusion of a Backup pin – the use of a pin that represents the Intermediate or Root CA for the public certificate is not a suitable Backup pin and will be flagged as such by the browser.

Note: When a valid backup pin is not found, browsers will ignore the HPKP information entirely. This is noted as being one of the more common mistakes made when implementing HPKP.

So, the question is, what should be used as the backup pin if this needs to be something outside the Trust Chain? Typical backup pins include the use of an alternate CA, or something that is controlled internally, such as a CSR or a secondary certificate that is held securely, solely for use as a backup pin.

Whilst using a backup pin based on another Public CA may be simpler, this does open a possible MITM attack should this CA be compromised – this has happened before and is likely to happen again.

The use of an internally controlled source for the backup pin, may therefore be a better option in the long term, although caution is advised as loss of the source used for the backup pin could result in lengthy outages of the website protected by HPKP (the duration as defined by the max-age variable).

If considering HPKP, this is something that you will need to work through internally to determine which is better for your particular environment. We recommend that you refer to additional material from Scott Helme and Tim Taubert who go into some detail about the use of primary and backup pins.

As far as integrating with Citrix NetScaler, Rewrite Action and Policies can be used to implement certificate pinning, and the configuration can be created from either the GUI or command line. In this example based on NetScaler 11.0, the Rewrite Action is created to use the INSERT_HTTP_HEADER type, as shown.

If creating the Rewrite Actions and Policies from the command line, the following commands can be used:

add rewrite action INSERT_HTTP_HEADER Public-Key-Pins q/"pin-sha256=\"\"; pin-sha256=\"\"; max-age=

add rewrite policy true

The RFC also allows for HPKP to be implemented in a Reporting Only mode, which is accomplished by amending the name of the HTTP header from “Public-Key-Pins” to “Public-Key-Pins-Report-Only”. When configured in this manner, the max-age timer is ignored and the browser will not actively block website content. We recommend that the reporting only function initially be used when implementing HPKP in your environment.

Note: Common mistakes when configuring the HTTP header is the omission of the ‘pin-sha256’ variable name, the omission of the “” around the actual hash values, and the omission of the entire header within “” marks.

The policy can then be bound to either an SSL virtual server (which may be a load balancing virtual server), or a NetScaler Gateway virtual server. In each case, the policy is bound as a Rewrite (Response) policy.

bind vserver -policyName -priority 100 -type RESPONSE

Once applied in this manner, the HPKP HTTP header will be inserted into all traffic associated with the SSL virtual server.

Note: Support within web browsers is not fully operational yet in terms of alerting the user to the issue – you need to go into the Developer options (F12) within the browser to see the alerts relating to HPKP failures currently.

You can validate that HPKP is functioning correctly by reviewing the Developer Network Tab in FireFox and Chrome’s internals.

For FireFox, hit Ctrl-Shift-Q (or F12) to open the developer Network Tab. Access the SSL based website, and after clicking on one of the objects, such as an HTML file, click on the ‘Security’ Tab and look for “Public Key Pinning: Enabled”

For Chrome, access the SSL based website, and then in another window, browse to chrome://net-internals/#hsts, and then in the Query Domain section, enter the domain name for the website being accessed. The “dynamic_spki_hashes:” entry should match the pin-sha256 values defined within the Rewrite Policy.

You can also test the HPKP implementation through a number of public SSL test sites, including The HPKP Toolset and SSL Labs (Developmental site).

Sample reporting can be obtained through Scott Helme's Reporting site. This site has been created and is run by Scott to promote awareness of certificate pinning and content security policy configuration.

If you would like to know more about certificate pinning with NetScaler and the associated use of HTTP Strict Transport Security (HSTS), please drop us a line.

Free Download

Desktop as a Service & Workspaces Whitepaper

Download Here