Using self-signed certificates with QZ Tray

QZ Tray is an amazing printing tool for your browser. It allows your websites to print receipts including bar-codes using thermal printers.

The only problem is that getting it all set up correctly can be a bit tricky especially if you want to suppress the untrusted dialogs/prompts that pop up when using the free version.

Lucky for us, their solution is open source and from version 2.02 they allow developers to recompile the source with a self signed certificate that would suppress these popups. This is great if you cannot afford the $400 annual price tag, but getting it set up could be a painful process because they don't offer step by step instructions, and other articles on the subject are incomplete.

I successfully managed to recompile the binaries using a self signed certificate and thought it might be useful if I provide step by step instructions on how to get it done.

This guide will explain how to recompile the windows binaries only. But this should give you enough insight to be able to compile for Linux and Apple as well. The biggest part is to get the certificates all correct which is what I will be focusing on.

Note: Additional QZ Tray compiling information can be found on their Compiling Wiki page

Section 1: Recompiling and Signing Instructions

Step 1 - Installing QZ Dependencies

Before you continue, you should install the required dependencies and configure them correctly to allow you to recompile the application successfully.
To install the dependencies simply follow the instructions from the QA Tray website (HERE)

Step 2 - Clone the source code

Instructions on cloning the source code is available HERE
Note: Once the source code has been cloned, you need to pull the latest code using:

cd tray
git pull

Step 3 - Install OpenSSL

OpenSSL is used to create our self signed certificate and private key. OpenSSL is not officially supported for windows but you can install the third-party OpenSSL binaries from https://slproweb.com/products/Win32OpenSSL.html

Step 4 - Generating Certificates

Note: When using self signed certificates you do not need to worry about the trusted intermediate certificate, all you need is a certificate and a private key.

a) Run OpenSSL as administrator and use the following command to generate your key and certificate:

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 11499 -nodes

You are required to input various information for the certificate to be correctly generated.
Here are some examples:

Country Name (2 letter code) [XX] : Your 2 letter country code, e.g. US
State or Province Name (full name) [Some-State] : Your state e.g. California
Locality Name (eg, city) [] : Your city e.g. San Fransisco
Organization Name (eg, company) [Internet Widgits Pty Ltd]: Your company name, e.g. Some Company Ltd.
Organizational Unit Name (eg, section) []: Department Name e.g. IT
Common Name (e.g. server FQDN or YOUR name) []: THIS ENTRY IS IMPORTANT, this should be your domain name in wildcard format an example of this would be "*.mywebsitedomain.com"
Email Address []: Your email address

This command generates a certificate that is valid for 30 years, but you can adjust the days parameter to fit your needs. Note that the days parameter cannot be larger than 11499

b) Once we have our certificate and key generated we should convert the key to the correct format. This is done by running the following command in OpenSSL.

openssl pkcs12 -inkey key.pem -in cert.pem -export -out privateKey.pfx

You will be prompted to enter (and confirm) a password for your private key, remember to use a secure password.

NOTE: Your certificates will be generated in the same folder where the OPENSSL exe file is located. This is most likely "c:\OpenSSL-Win64\bin" but could be different on version installed and also if you changed the installation path.

Step 5 - Recompile the binaries using our new certificate
Because this tutorial is for the Windows binaries we will be using ant to compile our code...

1) Run CMD prompt as Administrator.
2) Navigate to your QZ Tray source code
For example, if your cloned repository is located in "c:\src\tray"

cd C:\src\tray\

3) Run ant and include the new certificate parameter:
Assuming ant is located in "c:\ant" and certificates are located in "c:\OpenSSL-Win64\bin"...

c:\ant\bin\ant nsis -Dauthcert.use="c:\OpenSSL-Win64\bin\cert.pem"

Re-compiling finished

Your new installation will be located in the "out" folder of your cloned repository: "c:\src\tray\out\"

Section 2: QZ Tray Integration into ASP.Net

Step 1 - Getting Started

Follow the getting started instructions on the QZ Website

Step 2a - Signing the Messages (Client Side)

REMEMBER: Because we are using a self signed certificate we do not need to worry about the intermediate certificate.

For basic setup instructions please read this page first: https://qz.io/wiki/2.0-signing-messages

QZ Tray offers multiple ways to sign messages, in this example I will demonstrate the Direct method because its the easiest way to get it working.

1) Edit qz.security.setCertificatePromise() to use your self signed Certificate.

<script>
    /// Authentication setup ///
    qz.security.setCertificatePromise(function(resolve, reject) {
        //Preferred method - from server
//        $.ajax("assets/signing/digital-certificate.txt").then(resolve, reject);

        //Alternate method 1 - anonymous
//        resolve();

        //Alternate method 2 - direct
        resolve("-----BEGIN CERTIFICATE-----\n" +
                "MIIFAzCCAuugAwIBAgICEAIwDQYJKoZIhvcNAQEFBQAwgZgxCzAJBgNVBAYTAlVT\n" +
                "MQswCQYDVQQIDAJOWTEbMBkGA1UECgwSUVogSW5kdXN0cmllcywgTExDMRswGQYD\n" +
                "VQQLDBJRWiBJbmR1c3RyaWVzLCBMTEMxGTAXBgNVBAMMEHF6aW5kdXN0cmllcy5j\n" +
                "b20xJzAlBgkqhkiG9w0BCQEWGHN1cHBvcnRAcXppbmR1c3RyaWVzLmNvbTAeFw0x\n" +
                "NTAzMTkwMjM4NDVaFw0yNTAzMTkwMjM4NDVaMHMxCzAJBgNVBAYTAkFBMRMwEQYD\n" +
                "VQQIDApTb21lIFN0YXRlMQ0wCwYDVQQKDAREZW1vMQ0wCwYDVQQLDAREZW1vMRIw\n" +
                "EAYDVQQDDAlsb2NhbGhvc3QxHTAbBgkqhkiG9w0BCQEWDnJvb3RAbG9jYWxob3N0\n" +
                "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtFzbBDRTDHHmlSVQLqjY\n" +
                "aoGax7ql3XgRGdhZlNEJPZDs5482ty34J4sI2ZK2yC8YkZ/x+WCSveUgDQIVJ8oK\n" +
                "D4jtAPxqHnfSr9RAbvB1GQoiYLxhfxEp/+zfB9dBKDTRZR2nJm/mMsavY2DnSzLp\n" +
                "t7PJOjt3BdtISRtGMRsWmRHRfy882msBxsYug22odnT1OdaJQ54bWJT5iJnceBV2\n" +
                "1oOqWSg5hU1MupZRxxHbzI61EpTLlxXJQ7YNSwwiDzjaxGrufxc4eZnzGQ1A8h1u\n" +
                "jTaG84S1MWvG7BfcPLW+sya+PkrQWMOCIgXrQnAsUgqQrgxQ8Ocq3G4X9UvBy5VR\n" +
                "CwIDAQABo3sweTAJBgNVHRMEAjAAMCwGCWCGSAGG+EIBDQQfFh1PcGVuU1NMIEdl\n" +
                "bmVyYXRlZCBDZXJ0aWZpY2F0ZTAdBgNVHQ4EFgQUpG420UhvfwAFMr+8vf3pJunQ\n" +
                "gH4wHwYDVR0jBBgwFoAUkKZQt4TUuepf8gWEE3hF6Kl1VFwwDQYJKoZIhvcNAQEF\n" +
                "BQADggIBAFXr6G1g7yYVHg6uGfh1nK2jhpKBAOA+OtZQLNHYlBgoAuRRNWdE9/v4\n" +
                "J/3Jeid2DAyihm2j92qsQJXkyxBgdTLG+ncILlRElXvG7IrOh3tq/TttdzLcMjaR\n" +
                "8w/AkVDLNL0z35shNXih2F9JlbNRGqbVhC7qZl+V1BITfx6mGc4ayke7C9Hm57X0\n" +
                "ak/NerAC/QXNs/bF17b+zsUt2ja5NVS8dDSC4JAkM1dD64Y26leYbPybB+FgOxFu\n" +
                "wou9gFxzwbdGLCGboi0lNLjEysHJBi90KjPUETbzMmoilHNJXw7egIo8yS5eq8RH\n" +
                "i2lS0GsQjYFMvplNVMATDXUPm9MKpCbZ7IlJ5eekhWqvErddcHbzCuUBkDZ7wX/j\n" +
                "unk/3DyXdTsSGuZk3/fLEsc4/YTujpAjVXiA1LCooQJ7SmNOpUa66TPz9O7Ufkng\n" +
                "+CoTSACmnlHdP7U9WLr5TYnmL9eoHwtb0hwENe1oFC5zClJoSX/7DRexSJfB7YBf\n" +
                "vn6JA2xy4C6PqximyCPisErNp85GUcZfo33Np1aywFv9H+a83rSUcV6kpE/jAZio\n" +
                "5qLpgIOisArj1HTM6goDWzKhLiR/AeG3IJvgbpr9Gr7uZmfFyQzUjvkJ9cybZRd+\n" +
                "G8azmpBBotmKsbtbAU/I/LVk8saeXznshOVVpDRYtVnjZeAneso7\n" +
                "-----END CERTIFICATE-----\n");
    });

2) Edit qz.security.setSignaturePromise() to use your server-side signing method.

        /// Returns signed message ///
        qz.security.setSignaturePromise(function (toSign) {
            return function (resolve, reject) {
                PageMethods.SignMessage(toSign, resolve, reject);
            };
        });

Step 2b - Signing the Messages (Server Side)

Note: Make sure that your webpage that you want to print from inherits from the following CustomPage class instead of just the normal System.Web.UI.Page

using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Security.Cryptography.X509Certificates;
using System.Text;
using System.Web;
using System.Web.Services;

namespace YourNameSpace
{
    public class CustomPage : System.Web.UI.Page
    {
        [WebMethod]
        public static object SignMessage(string message)
        {
            // How to associate a private key with the X509Certificate2 class in .net
            // openssl pkcs12 -export -inkey private-key.pem -in digital-certificate.txt -out private-key.pfx

            string KEY = "PATH-TO-YOUR-PRIVATE-KEY-LOCATION (privateKey.pfx)";
            string PASS = "YOUR-PRIVATE-KEY-PASSWORD-HERE";

            var cert = new X509Certificate2(KEY, PASS, X509KeyStorageFlags.MachineKeySet | X509KeyStorageFlags.PersistKeySet | X509KeyStorageFlags.Exportable);
            RSACryptoServiceProvider csp = (RSACryptoServiceProvider)cert.PrivateKey;

            byte[] data = new ASCIIEncoding().GetBytes(message);
            byte[] hash = new SHA1Managed().ComputeHash(data);

            string response = Convert.ToBase64String(csp.SignHash(hash, CryptoConfig.MapNameToOID("SHA1")));
            return response;
        }
    }
}

And that folks, is all you need!